This is the end-host client for ebbflow. This is used to proxy SSH or TCP connections between ebbflow and your local server. It typically runs as a daemon which is initiated during the install process, but can also be ran directly which suits containers.
Full documentation can be found on the Ebbflow website: Client Documentation.
ebbflow --help
Please visit Ebbflow's client documentation for up to date instructions on installing and managing the client:
- Docs: https://ebbflow.io/documentation#client
- RaspberryPi Guide: https://ebbflow.io/guides/raspberrypi
The client is built, tested, and packaged using the github action workflow configured in .github/workflows
. When a release is expected, the released artifacts are downloaded to Ebbflow package servers and hosted through https://pkg.ebbflow.io.
As of now, testing is largely manual. The client is tested on various OSs & architectures before being released and vended. In the future, much of this testing could be completed in additional github workflow actions, but that is TBD.
To build the client locally, you can simply fork/clone/download the repo and run cargo build
, then continuing to execute the binaries manually. To execute with elevated privileges on linux/macos, run sudo ./target/debug/ebbflow
or sudo ./target/debug/ebbflowd
.
To build the various packages, you need the following tools.
- Install
cargo-deb
: https://crates.io/crates/cargo-deb (Only works on debian based OSs, ubuntu, debian..)- Building:
cargo deb
- Building:
- Install
cargo-rpm
: https://crates.io/crates/cargo-rpm (Only works on rpm-based architectures, fedora, opensuse, ..)cargo rpm build
- Zip
ebbflow
andebbflowd
, just those 2 files - Homebrew is used to distribute packages, see https://github.com/ebbflow-io/homebrew-ebbflow/
- To build
cargo-wix
: https://crates.io/crates/cargo-wix (Only works on windows)cargo wix
- Chocolatey is used to distribute packages, see https://github.com/ebbflow-io/chocolatey-ebbflow
- Winget is also used to distribute packages,
winget search ebbflow
- Feel free to contact ebbflow and we can work to get packages published for you!
- The simplest method is to just grab the 'ebbflow' binary, and run with
run-blocking
. This has no file-based dependencies if you pass the host key to during the command like so:EBB_KEY=... ebbflow run-blocking --dns example.com --port 8000
. This is fully supported. - Alternatively, you can run the daemon, but it does have file/directory dependencies, and you need to configure that. Note that this is uncharted waters, and its possible that the following instructions can change;
- You will need to run the
ebbflowd
binary as a background service, as insystemd
or similar. - The client uses the
/etc/ebbflow/
dir to store 3 fileshost.key
the private host key, should be600
permissions, should (ideally) not be transferred between hosts, and should NEVER be entered into source control (i'm looking at you, nix config)config.yaml
the configuration file for the daemon. This file is read from to determine how the daemon should run, what endpoints exist, etc. This file is written to when endpoints are disabled or enabled, the log level changes, and a few other commands, viaebbflow config ..
. So it is possible to have this file static, but I wouldn't recommend it..daemonaddr
is a file the daemon writes its ipv4 socket addr to for its HTTP server. Runningebbflow status
reads this file, then makes an http request for the status. The daemon will work fine, proxy-wise, if this file cannot be written or read from, it will just slowly loop on attempts to write it.
- Now, you can change the root directory of which ebbflow looks for these three files by setting the
EBB_CFG_DIR
env var. The daemon will look at this first, and fall back to/etc/ebbflow
. So you can provide this to another directory and ebbflow will look for the three files in this directory instead.- IMPORTANT If you change the directory, all invocations of the
ebbflow
command should have this env var passed to it as well!ebbflow
andebbflowd
communicate via these files, so ifebbflowd
is looking in/your/custom/dir/
andebbflow
is looking in/etc/ebbflow/
, then there will be issues..
- IMPORTANT If you change the directory, all invocations of the
- If you package up ebbflow for another distro like nix or arch or whatever, and you want Ebbflow to take over ownership of your work, then email us at
support at ebbflow.io
.
- You will need to run the
Contributions are welcome! Submit a pull request and we can go from there.
See LICENSE