Rayhaan JaufeerallyandClaude Opus 5.5
dc275f99d7
The documentation moves from READMEs into a site in docs/: getting started, a user guide, operations, a reference, and development pages, written in the style of network vendors' documentation (docs/STYLE.md). bin/bgp/README.md and docs/RFCs.md are folded into it. - A theme of its own in the International Typographic Style, in blues, with self-hosted Inter and JetBrains Mono, search over Zola's index, dark mode, and no resources loaded from other hosts. - Example configurations in docs/examples/, shown on the pages and checked with `bgp --check` in CI. - A test that fails when a field of config.proto is missing from the configuration reference. - A CI job that builds the site; Zola fails on broken links and anchors. - A hardened systemd unit, tried under systemd with kernel routes on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.7 KiB
+++ title = "Installing Ferrix" description = "Describes how to build Ferrix from source or as a container image, and how to grant the daemon the privileges it requires." weight = 2
[extra] nav = "Installation" +++
Ferrix is distributed as source code. You build the bgp binary with
Cargo, or build a container image with the provided Dockerfile.
Requirements
- A stable Rust toolchain from rustup.rs. The container image uses Rust 1.92.
- Linux, for kernel route installation. On other operating systems, Ferrix operates as a BGP speaker only and does not modify forwarding.
The configuration schema is compiled in pure Rust; the Protocol Buffers
compiler (protoc) is not required.
Building from Source
To build and install the daemon:
-
Clone the repository.
git clone https://git.rayhaan.net/rayhaan/ferrix.git cd ferrix -
Build the release binary.
cargo build --release --locked -p bgpThe
--lockedoption builds with the dependency versions recorded inCargo.lock, which are the versions tested in continuous integration. -
Install the binary.
sudo install -m 0755 target/release/bgp /usr/local/bin/bgp -
Verify the installation.
bgp --versionThe command displays the installed version, for example
bgp 0.1.0.
Building a Container Image
The Dockerfile in the repository builds the daemon in a Rust build stage
and copies the binary into a Debian slim image.
docker build -t ferrix .
docker run --rm --network host \
-v /etc/ferrix:/etc/ferrix:ro \
ferrix
By default, the container reads the configuration from
/etc/ferrix/server.textpb. The container requires the host network
namespace (--network host). If the configuration includes kernel, the
container also requires the NET_ADMIN capability (--cap-add NET_ADMIN).
Granting Privileges
Ferrix does not require root privileges. Table 1 lists the Linux capabilities that it requires.
| Capability | Required for |
|---|---|
CAP_NET_BIND_SERVICE |
Listening on TCP port 179 |
CAP_NET_ADMIN |
Installing routes in the kernel (kernel statement) |
To grant the capabilities to the binary:
sudo setcap cap_net_admin,cap_net_bind_service+ep /usr/local/bin/bgp
Alternatively, grant them to the systemd service. See Deploying Ferrix.
Note
Ferrix does not enable IP forwarding. To forward transit traffic, set
net.ipv4.ip_forward=1andnet.ipv6.conf.all.forwarding=1:sudo sysctl -w net.ipv4.ip_forward=1 net.ipv6.conf.all.forwarding=1
Next Steps
To establish a first BGP session, see Quick Start.