LaunchPartyto save 25% off of the base price!
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.
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.
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
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
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
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
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.
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
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
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
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 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
brew servicescommands with
The quickstart guide has more info on getting everything up and running!
Ebbflow provides three ways to run with Windows
choco install ebbflow
winget install ebbflow
.msiInstallers are also available to download directly from Github Releases
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
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:
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
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
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.
HINT: You are encouraged to run
ebbflow --help to explore the options!
ebbflow configcommand. Here are some examples:
Initializing the Client
# Interactively ebbflow init # Non-interactively # EBB_KEY must be set with a provisioned host key ebbflow init -n
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
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.
|Linux||Ebbflow's background service is named
|macOS||Ebbflow's background service is controlled through homebrew services which uses launchctl under the hood.|
|Windows||The daemon runs as a windows service and can be controlled through the 'Services' application (guide).|
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!
|Linux||Logs are captured by the systemd runner, so logs will be located in the
To tail the logs, try
|macOS||All logs are redirected to
|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.
It works by routing your endpoint to ebbflow through DNS using an A record, Clients will request your website,
example.com, and DNS will direct them to ebbflow. Then ebbflow sees the customer is
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.
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).
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.
There are two types of endpoints, Managed and Passthrough
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
You may be wondering "When should I use the
A record or
CNAME record?" See the following info, and also check out this guide.
||(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.
||(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.
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.
ebbflow init(or have your non-interactive setup call
ebbflow config setup-ssh).
ssh -J ebbflow.io USER@HOSTNAME
USERis a username for the host, and
HOSTNAMEis the name of the SSH target that was configured on a host running the ebbflow client.
scpCommand 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
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.
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.
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.
Ebbflow reserves the ability to add additional limits. Please see usage terms.
ebbflow statuscan 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
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?
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?
HostAnythingthat grants a key the ability to host any endpoint. You may want to use this!
Permission denied (publickey)
open failed: administratively prohibited: Requested channel type is prohibited
ssh 0.0.0.0. If not, you will need to start the SSH daemon. Some instructions:
ssh-keygen -lf ~/.ssh/id_rsa.pub(or the path to your pubkey..) to get the
SHA256fingerprint of your key
SshToAnythingthat grants a key the ability to SSH to any target. You may want to use this!
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.
1000000000 bytes / 1 billion bytes / 1x10^9 bytes. Not a gibibyte.
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.
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.
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!
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