🎉 Ebbflow has launched! 🎊
Use coupon code LaunchParty to save 25% off of the base price!

Documentation

Use Case Specific Guides & Additional Information

Quickstart Guide

This is the guide providing all you need to know on using Ebbflow.

Raspberry Pi

Put that tiny boi to use! Host a website or SSH to it from anywhere.

Kubernetes

Kubernetes iS tHe FuTuRe

More Coming Soon!

We are working to provide guides for other use cases, stay tuned..

Sections

Client

    What is the client? What does it do? How does it work?

    The Ebbflow Client allows you to easily host a service already running. It is a sidecar process that you start and run alongside your existing webserver. It works by installing a daemon to your system that can be configured easily. The daemon will proxy traffic to your local webserver based on this configuration.

    Installation

    Follow the directions below to install the client onto your system. Note that a Docker image is provided for Docker users, and a Kubernetes specific guide can be found here.

    The quickstart guide has more info on getting everything up and running!

    Besides the per-OS instructions, you will execute ebbflow init to configure and start the client. After that, you can add endpoints using ebbflow config add-endpoint, see more instructions below.

    PS: You can find the client's code on Github if you'd like to learn how it works, contribute, etc.

    Debian Buster (10)
    curl https://pkg.ebbflow.io/live/debian/buster.gpg | sudo apt-key add -
    curl https://pkg.ebbflow.io/live/debian/buster.list | sudo tee /etc/apt/sources.list.d/ebbflow.list
    sudo apt update && sudo apt install ebbflow
    sudo ebbflow init
    Debian Stretch (9)
    curl https://pkg.ebbflow.io/live/debian/stretch.gpg | sudo apt-key add -
    curl https://pkg.ebbflow.io/live/debian/stretch.list | sudo tee /etc/apt/sources.list.d/ebbflow.list
    sudo apt update && sudo apt install ebbflow
    sudo ebbflow init
    Ubuntu Focal (20.04)
    curl https://pkg.ebbflow.io/live/ubuntu/focal.gpg | sudo apt-key add -
    curl https://pkg.ebbflow.io/live/ubuntu/focal.list | sudo tee /etc/apt/sources.list.d/ebbflow.list
    sudo apt update && sudo apt install ebbflow
    sudo ebbflow init
    Ubuntu Bionic (18.04)
    curl https://pkg.ebbflow.io/live/ubuntu/bionic.gpg | sudo apt-key add -
    curl https://pkg.ebbflow.io/live/ubuntu/bionic.list | sudo tee /etc/apt/sources.list.d/ebbflow.list
    sudo apt update && sudo apt install ebbflow
    sudo ebbflow init
    Other Debian Based

    As of now, you can just follow Debian Buster directions, as we are not aware of any compatabiltiy isses between this version and other OSs.

    Raspbian Buster (10) for Raspberry Pi models 2 and newer

    Check out the Raspberry Pi specific guide here!

    curl https://pkg.ebbflow.io/live/raspbian/buster.gpg | sudo apt-key add -
    curl https://pkg.ebbflow.io/live/raspbian/buster.list | sudo tee /etc/apt/sources.list.d/ebbflow.list
    sudo apt update && sudo apt install ebbflow
    sudo ebbflow init
    Fedora
    sudo dnf config-manager --add-repo https://pkg.ebbflow.io/live/fedora/ebbflow.repo
    sudo dnf install ebbflow
    sudo systemctl enable --now ebbflowd
    sudo ebbflow init
    Opensuse
    sudo zypper ar -g -r https://pkg.ebbflow.io/live/opensuse/ebbflow.repo
    sudo zypper ref && sudo zypper in ebbflow
    sudo systemctl enable --now ebbflowd
    sudo ebbflow init

    The quickstart guide has more info on getting everything up and running!

    Ebbflow use homebrew to distribute to macOS

    NOTE: You may see an error stating /usr/local/sbin is not writeable. To solve this, follow this solution, and then run brew link ebbflow

    brew tap ebbflow-io/ebbflow
    brew install ebbflow
    ebbflow init
    brew services start ebbflow
    
    # Important: On update, you must restart the daemon yourself:
    brew services restart ebbflow
    Also, by default the above commands will only run the daemon while your user is logged in. To have the daemon run in the background always, regardless of the current logged in user, execute the brew services commands with sudo

    The quickstart guide has more info on getting everything up and running!

    Ebbflow provides three ways to run with Windows

    • Chocolatey - You can see the chocolately package here. To install: choco install ebbflow
    • winget - Microsoft's in-development package manager can also be used like so: winget install ebbflow
    • .msi Installers are also available to download directly from Github Releases
      • This is the least-recommended solution, as you will manually need to acquire this installer and future installers yourself.
      • NOTE: The installer are not signed, and there will be a warning

    Advanced Installations (Non-Interactive, EC2 UserData, Docker)

    The Ebbflow Client can be installed non-interactively to suit server provisioning or running in docker containers. These instructions are necessary for automated installations. If you have any questions, always feel free to email support@ebbflow.io.

    Non-Interactive

    Install - You can automate the installation and configuration of the Ebbflow client onto your services easily. To do this, take the per-OS instructions from above and put them into your existing initilization script (for example, your EC2 UserData). Hint: Remember to remove "sudo" if using EC2 User Data, as the user is root and sudo doesn't work.

    Configure - After the package is installed, it needs to be configured. The client uses host keys to authenticate with Ebbflow. In the IAM console page, you can provision new host keys easily. Please see the IAM Documentation for more info about these keys. Once you have a key, you must provide that key to the client on installation via the EBB_KEY environment variable. The configuration with regards to endpoints and SSH proxy can be copied from host to host, or configured via the command line.

    Example - Let's say you are running ubuntu, have an endpoint created for example.com, and your server runs on port 8000. Your configuration script may look like:

    # Install Ebbflow
    curl https://pkg.ebbflow.io/live/ubuntu/focal.gpg | apt-key add -
    curl https://pkg.ebbflow.io/live/ubuntu/focal.list | tee /etc/apt/sources.list.d/ebbflow.list
    apt update && apt install ebbflow
    
    # Configure ebbflow
    # .. set the EBB_KEY environment variable with a key ..
    ebbflow init -n
    
    # Enable immediately
    ebbflow config add-endpoint --maxconns 5000 --dns example.com --port 8000
    
    # .. or start disabled so you can start your server first
    ebbflow config add-endpoint --maxconns 5000 --dns example.com --port 8000 --disabled 
    

    Alternatively you can copy the config.yaml file from host to host. Each host will still need to be initialized. Here are the directories:

    Platform Location
    Linux /etc/ebbflow/config.yaml
    macOS /usr/local/etc/ebbflow/config.yaml
    Windows \Program Files\ebbflow\config.yaml

    EC2 UserData

    First off, check out the Non-Interactive section above so you understand what is going on. The following code is taken from an EC2 UserData script that Ebbflow itself uses internally!

    echo "installing ebbflow"
    curl https://pkg.ebbflow.io/live/ubuntu/focal.gpg | apt-key add -
    curl https://pkg.ebbflow.io/live/ubuntu/focal.list | tee /etc/apt/sources.list.d/ebbflow.list
    apt -y update && apt install ebbflow
    
    # You need to get your Ebbflow Host Key from a secret provider, such as aws secretsmanager like this:
    ebbkey=$(aws secretsmanager get-secret-value ...)
    
    # Initialize the client w/ the key
    EBB_KEY=$ebbkey ebbflow init -n
    
    # Set up the daemon to host the endpoint (initially disabled so you can start your server first)
    ebbflow config add-endpoint --disabled --dns yourendpoint.com --port 8080
    
    # Now start up your server that runs on port 8080
    
    ebbflow config enable endpoint yourendpoint.com
    

    Then, when you are deploying or updating your software, execute the following:

    echo "Disabling ebbflow"
    ebbflow config disable -i endpoint $endpoint
    
    # stop your server, download new version, start it up and health check it..
    
    echo "Enabling ebbflow"
    ebbflow config enable endpoint $endpoint
    
    Docker

    You can run the client inside of your docker container easily, but we have a specific guide for Kubernetes users here!

    Also, we have a Docker image prepared for amd64 Linux users. You can look Kubernetes guide for an example of the arguments and configuration needed to run this image.

    Otherwise, continue reading for instructions on getting the client running in a custom image.

    Install -To run ebbflow in a docker container, you must first install the Ebbflow Client to your container. To do this, use the install instructions provided above for the OS your container uses, and add commands instructions to your Dockerfile. Remember to remove "sudo" if the USER is root.

    Configure & Run - Now your image has the client installed, and your container needs to start the Ebbflow Client when it runs. In the non-Docker world, the Ebbflow Client installs as a daemon which is run in the background. In the majority case, Docker containers do not have daemons and will not execute backgoround processes, which is why the normal installation will not work for Docker containers. To get around this, we use the ebbflow tool's run-blocking command.

    run-blocking runs the ebbflow proxy without the daemon. An important note is that this command requires the EBB_KEY environment variable to be present, with the value of an ebbflow Host Key. Host keys can be created at-will in the IAM Console. You will need to set this environment variable yourself securely, typically using whatever secret-providing mechanism you already employ.

    Using the Client

    HINT: You are encouraged to run ebbflow --help to explore the options!

    The client works based on configuration. This configuration can be changed via the ebbflow config command. Here are some examples:
    1. Initializing the Client

      Note: To provision a host key for non-interactive installations, click 'Create New Host Key' in the IAM Console

      # Interactively
      ebbflow init
      
      # Non-interactively
      # EBB_KEY must be set with a provisioned host key
      ebbflow init -n
    2. Adding / Removing and Endpoint to be hosted

      Note: The Ebbflow proxy can host multiple endpoints at once!

      # Adding
      sudo ebbflow config add-endpoint --dns mysite.com --port 8000
      
      # Removing 
      sudo ebbflow config remove-endpoint mysite.com
    3. Enabling or Disabling the proxy

      Typically you will disable your endpoint(s) on a server while you are performing maintence/deploying/updating your web service, and you will enable it after.

      # Disabling A Specific Endpoint
      sudo ebbflow config disable endpoint mysite.com
      
      # Disabling all endpoints
      sudo ebbflow config disable all-endpoints
      
      # Disabling the SSH proxy
      sudo ebbflow config disable ssh
      
      # To enable, just use specify enable instead of disable like so:
      sudo ebbflow config enable ...

    The definitive source of information on the client is Github so looking at that is highly recommended.

    Other Client Information

    Starting and Stopping the Background Daemon
    Platform Instructions
    Linux Ebbflow's background service is named ebbflowd, and runs as a systemd service with that name.
    # Stop
    sudo systemctl stop ebbflowd
    
    # Start
    sudo systemctl start ebbflowd
    
    # Restart
    sudo systemctl restart ebbflowd
    macOS Ebbflow's background service is controlled through homebrew services which uses launchctl under the hood.
    # Stop
    brew services stop ebbflow
    
    # Start
    brew services start ebbflow
    
    # Restart
    brew services restart ebbflow
    Windows The daemon runs as a windows service and can be controlled through the 'Services' application (guide).

    Log File Locations

    The ebbflow client emits logs, typically at a high level, but this can be changed. If you change the log level, you must restart the daemon!

    Platform Location
    Linux Logs are captured by the systemd runner, so logs will be located in the ebbflowd service's expected location of
    sudo journalctl -u ebbflowd
    To tail the logs, try
    sudo journalctl -u ebbflowd -f -n 20
    macOS All logs are redirected to
    /usr/local/var/log/ebbflowd.log
    Windows Logs are sent to the windows event system and can be viewed through the windows Event Viewer app. (wiki, guide).

    Specifically, after opening the Event Viewer, click Applications > Services and look for Ebbflow related logs there.

Endpoint Configuration

  1. How it works for Clients/Customers of your endpoint

    It works by routing your endpoint to ebbflow through DNS using an A record, Clients will request your website, e.g. example.com, and DNS will direct them to ebbflow. Then ebbflow sees the customer is requesting example.com, and routes the client connection to one of your server connections.

    Under the hood, Ebbflow uses Server Name Indication (SNI) to determine where the client connection should be routed. This is because Ebbflow has one set of IP addresses that all customers are routed to, so Ebbflow must have a way to know where to route the traffic.

  2. How it works for Servers Hosting your endpoint

    Servers must run the provided Ebbflow client locally which handles proxying connections to your server application. For example, if you have Apache Server running on port 80, you will start the Ebbflow client and direct it to that port, supplying your credentials. See more information above in the client documentation.

    In more detail, the client hosts endpoints by establishing a TLS connection to ebbflow, using SNI to indicate which endpoint to host, and using TLS Client Authentication to prove to ebbflow that you are allowed to serve the given endpoint. This is all handled by the client (see instructions there).

Creating an Endpoint

To create an endpoint, you must be logged in. Head to the create endpoint page and make the first choice - what type of Client certificate management you want.

  1. Choosing an Endpoint Type

    There are two types of endpoints, Managed and Passthrough

    1. Managed
      Ebbflow will provision a Let's Encrypt signed certificate for your endpoint. This certificate will be presented to clients, as the TLS connection is terminated at Ebbflow. The client request will be passed to your server inside of the Ebbflow-Client (or manually created) TLS connection.
    2. Passthrough
      Ebbflow will NOT terminate the TLS connection, it will simply forward the client's TLS handshake through to your server. It just peeks at the SNI in the ClientHello to know where to route to, then starts forwarding all traffic back and forth. This means that the data as encrypted all the way from client to your server and ebbflow CANNOT see the data in its servers.
  2. Configuring DNS

    DNS is used in two ways for Ebbflow: Pointing traffic of your endpoint to Ebbflow, and verifying that you own your domain name and intend to use it with Ebbflow.

    Directing Traffic to Ebbflow

    You must change the DNS records of the endpoint you want to host to point to ebbflow. To do this, you must set either your A Record values to the values shown on the Endpoint page for the endpoint you are configuring, OR point your CNAME record to point to cname.ebbflow.io.

    You may be wondering "When should I use the A record or CNAME record?" See the following info, and also check out this guide.

    A (more info) A records will always work for all domain names. If you are hosting a "root" domain name, e.g. ebbflow.io, example.com, then you will use the A Record, as typically CNAME records are not allowed nor recommended for root records.

    Also, if your domain has other DNS records like other TXT or MX records, A records will work great, in contrast to working with CNAME records which disallow the existence of other records for the same domain.

    CNAME (more info) CNAME records work for non-root domains, e.g. pkg.ebbflow.io or this.is.an.example.com, but NOT root domains like ebbflow.io or example.com.

    However, CNAME records have benefits. If Ebbflow adds new IPs, or ever (not planned!!) needs to change IPs, then there will be no actions needed on your part.

    Ebbflow recommends using CNAME records when applicable, for maximum flexibility.

    Verifying your Endpoint

    Instructions are located in the Endpoint Detail page for one of your endpoints. Ebbflow uses TXT records that you must set to show ownership of your domain. Verification is needed so you cannot squat a domain in case the owner of that domain later adopts Ebbflow. Also, it allows you to verify that your traffic is set up to hit Ebbflow properly.

SSH Proxy

Ebbflow provides an SSH proxy to allow you to easily connect to your servers. There are a few core components needed:
  1. The client is set up for SSH. make sure you enable the SSH proxy while executing ebbflow init (or have your non-interactive setup call ebbflow config setup-ssh).
    • Make sure the host key identity has sufficient permissions to host your endpoint, see the IAM documentation.
  2. The public portion of your SSH key is uploaded as an SSH key to IAM, and has sufficient permission.
One the ebbflow client is setup, you can connect to the target host using any SSH client like so
ssh -J ebbflow.io USER@HOSTNAME
where USER is a username for the host, and HOSTNAME is the name of the SSH target that was configured on a host running the ebbflow client.

Other SSH Information

Using the scp Command with the Ebbflow Proxy

scp is easily used with the Ebbflow proxy. The only difference is that you need to specify the ProxyJump argument specifically, in contrast to just specifying -J which is a shortcut that the ssh command has, but scp does not.

# Send file to target host
scp -o 'ProxyJump ebbflow.io' file USER@HOSTNAME:/target/dir

# Retrieve file from target host
scp -o 'ProxyJump ebbflow.io' . USER@HOSTNAME:/path/to/file

Security Information

  1. TLS, when is the data encrypted?

    When using Managed or Hosted endpoints, data is encrypted from client-Ebbflow, decrypted, then re-encrypted to be passed between Ebbflow-server. This is due to there being one TLS connection between Client and Ebbflow, and another between Ebbflow and your server. There is a short time in the middle where the data is not encrypted, but the data on lives in the memory of the Ebbflow server process and is not inspected at all.

    Alternatively, you can use a Passthrough endpoint. In this case, Ebbflow just peeks at the ClientHello of the Client (never any data), and then forwards ALL bytes through the Ebbflow-Server TLS connection. This means that Ebbflow's servers are never able to view the plaintext communications. The side-effect is that the data that is passed through the Ebbflow-Server TLS connection is TLS data itself, so the data received through this connection must be treated as TLS data. This results in having to host the TLS certificate of your endpoint on each server.

  2. How do I apply authorization to my account?

    Authorization is provided by the IAM (Identity and Access Management) system, see that documentation here.

Limits

  1. Number of Server and/or Client connections per Endpoint

    By default there are no limits on the number of server or client connections per endpoint. Ebbflow may enforce limits to mitigate bad actors or noisy neighbors.

  2. Throughput per Connection

    By default, there are no limits on the throughput for connections. Ebbflow may enforce limits to mitigate bad actors or noisy neighbors, but a baseline of 16mbps will be provided per-connection.

  3. TBD - Other limits possible

    Ebbflow reserves the ability to add additional limits. Please see usage terms.

Troubleshooting & Gotchas

  • Some basic debug steps:
    • ebbflow status can tell you a lot, and spits out messages such as..
      • ERROR: Received traffic but could not connect to local host - The daemon could not connect to your running webserver. Check that its up and running on the port that is specified
      • A connection for endpoint ... failed due to Forbidden - The key being used by this server cannot serve the endpoint. Maybe it doesn't exist, or this key doesn't have the correct IAM policies
    • Did you initialize the client, via ebbflow init?
    • Check out the logs, is there any information there?
    • Has your endpoint been verified? And has it finished provisioning (if its a Managed endpoint)?
    • Is your local web server running? The one that ebbflow will try to connect to?

    A good test is to run ebbflow run-blocking --loglevel Debug to quickly see if there are any issues

    Does your Host Key identity have permissions to host the endpoint?

    • For the key the host is using, created during init, go to the IAM Console. Does this Host Key identity have a policy allowing it to host the endpoint? Or is it part of a role that does?
    • Hint: Ebbflow provides a default Policy named HostAnything that grants a key the ability to host any endpoint. You may want to use this!
    • For more information about IAM permissions, check out the IAM documentation.
  • SSH not working

    SSH Errors
    • Permission denied (publickey)
    • open failed: administratively prohibited: Requested channel type is prohibited
      • Likely: Your identity is known, but you do not have permissions to SSH to the target IAM (IAM documentation.).
      • Otherwise, maybe you tried to SSH to ebbflow, e.g. ssh ebbflow.io, instead of using it as a jump host with -J ebbflow.io or ProxyJump=ebbflow.io
    • If the user you are logging in as does NOT require a password, this will likely fail, see this stackexchange answer.
    If you think the server is the problem:
    • Is your SSH daemon running? Try to SSH locally: ssh 0.0.0.0. If not, you will need to start the SSH daemon. Some instructions:
    • Does your host identity (i.e. the host running the daemon, the one you're trying to connect to) have the correct IAM policies or roles attached?
    If you think the client is the problem:
    • Has your key that you're using been added to Ebbflow as a SSH key identity?
      • Run ssh-keygen -lf ~/.ssh/id_rsa.pub (or the path to your pubkey..) to get the SHA256 fingerprint of your key
      • Go to the IAM Console, find the corresponding SSH key, and double check the fingerprints match up
    • Does your SSH Key have permissions to SSH to the target host?
      • Look at the key you're using on the IAM Console. Is it part of roles that grant permissions to SSH to the host? Does it have a policy directly attached to it that allows it to SSH to the host?
      • Hint: Ebbflow provides a default Policy named SshToAnything that grants a key the ability to SSH to any target. You may want to use this!
      • For more information about IAM permissions, check out the IAM documentation.

Frequently Asked Questions

  • Why don't I just use a load balancer provided by my cloud provider?

    Depending on your situation, that may be easier! Ebbflow's goal is to allow for non-standard use cases to be solved. If you want to throw 3 instances behind an load balancer in EC2 and call it a day, that may work. Its goal is not to replace every load balancer or other networking solution. Its goal is to allow people to serve websites from anywhere with security and privacy, and ease of use.

  • How many bytes are in an Ebbflow GB?

    1000000000 bytes / 1 billion bytes / 1x10^9 bytes. Not a gibibyte.

  • What technologies does Ebbflow use?

    First and foremost, Rust! Ebbflow is entirely written in Rust, from the website to the data plane and everything in between. Also, it uses the more recent asynchronous programming support. Ebbflow uses PostgreSQL, numerous AWS technologies, and even a hand-rolled SSH implementation.

Upcoming Features

Here are some features that Ebbflow is working on!

Private Endpoints

Presently any client can visit a domain name hosted through Ebbflow. Private endpoints will enable you to have endpoints that require some secret to communicate with. This would be helpful for users who would like to have Beta or any non-Public sites hosted through Ebbflow so that the non-Production networking stack looks just like the Production stack.

Dynamic / Wildcard Endpoints (IoT!)

You can let devices or servers host any domain under *.yourdomain.com. When a client connects to specific.yourdomain.com, it will be routed to whatever capacity (could be none, or 1, or N) is hosting that endpoint at the present time.

This has implications for IoT deployments. Instead of a single broker or message passing service e.g. MQTT, you can just connect directly to a given device and speak any protocol over TCP to that device. Connect directly to any device in the field without a VPN or other networking primetives - just connect!

Endpoint Forwarding

Ebbflow will forward your traffic to specified endpoints on location or weight. With this enabled, you can use Ebbflow to globally route traffic to your existing infrastructure

Example target endpoints may include: https://asdkflasdfa.alb.us-east-2.amazonaws.com, non-HTTP/TLS to 123.45.67.89:1234 or my-api-service.company.com:8080