mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00

Files

Thomas Eizinger 0d2ddd8497 feat(gateway): create debian package (#10537 )

With this PR we add `cargo-deb` to our CI pipeline and build a debian
package for the Gateway. The debian package comes with several
configuration files that make it easy for admins to start and maintain a
Gateway installation:

- The embedded systemd unit file is essentially the same one as what we
currently install with the install script with some minor modifications.
- The token is read from `/etc/firezone/gateway-token` and passed as a
systemd credential. This allows us to set the permissions for this file
to `0400` and have it owned by `root:root`.
	- The configuration is read from `/etc/firezone/gateway-env`.
- Both of these changes basically mean the user should never need to
touch the unit file itself.
- The `sysusers` configuration file ensures the `firezone` user and
group are present on the system.
- The `tmpfiles` configuration file ensures the necessary directories
are present.

All of the above is automatically installed and configured using the
post-installation script which is called by `apt` once the package is
installed.

In addition to the Gateway, we also package a first version of the
`firezone-cli`. Right now, `firezone-cli` (installed as `firezone`) has
three subcommands:

- `gateway authenticate`: Asks for the Gateway's token and installs it
at `/etc/firezone/gateway-token`. The user doesn't have to know how we
manage this token and can trust that we are using safe defaults.
- `gateway enable`: Enables and starts the systemd service.
- `gateway disable`: Disables the systemd service.

Right now, the `.deb` file is only uploaded to the preview APT
repository and not attached to the release. It should therefore not yet
be user-visible unless somebody pokes around a lot, meaning we can defer
documentation to a later PR and start testing it from the preview
repository for our own purposes.

Related: #10598
Resolves: #8484 
Resolves: #10681

2025-10-24 05:14:58 +00:00

debian

feat(gateway): create debian package (#10537 )

2025-10-24 05:14:58 +00:00

src

fix(gateway): trim whitespace from systemd credential (#10695 )

2025-10-24 04:03:40 +00:00

Cargo.toml

feat(gateway): create debian package (#10537 )

2025-10-24 05:14:58 +00:00

README.md

feat(gateway): support systemd credentials (#10538 )

2025-10-14 00:07:49 +00:00

README.md

gateway

This crate houses the Firezone gateway.

Building

You can build the gateway using: cargo build --release --bin firezone-gateway

You should then find a binary in target/release/firezone-gateway.

Running

The Firezone Gateway supports Linux only. To run the Gateway binary on your Linux host:

Generate a new Gateway token from the "Gateways" section of the admin portal and save it in your secrets manager.
Provide the token to the Gateway using one of these methods:
- Set the FIREZONE_TOKEN=<gateway_token> environment variable
- Set a systemd credential named FIREZONE_TOKEN.
Set FIREZONE_ID to a unique string to identify this gateway in the portal, e.g. export FIREZONE_ID=$(head -c 32 /dev/urandom | sha256sum | cut -d' ' -f1). The Gateway requires this variable at startup. We recommend this to be a 64 character hex string.
Now, you can start the Gateway with:

firezone-gateway

If you're running as a non-root user, you'll need the CAP_NET_ADMIN capability to open /dev/net/tun. You can add this to the gateway binary with:

sudo setcap 'cap_net_admin+eip' /path/to/firezone-gateway

Ports

The gateway requires no open ports. Connections automatically traverse NAT with STUN/TURN via the relay.