ferrix/docs/content/docs/getting-started/installation.md

+++ 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.
• A C compiler and make, to build the jemalloc memory allocator that the daemon uses (for example build-essential on Debian and Ubuntu, base-devel on Arch Linux, or the Xcode command line tools on macOS).
• 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:

1. Clone the repository.

   git clone https://git.rayhaan.net/rayhaan/ferrix.git
   cd ferrix
   

2. Build the release binary.

   cargo build --release --locked -p bgp
   

   The --locked option builds with the dependency versions recorded in Cargo.lock, which are the versions tested in continuous integration.

3. Install the binary.

   sudo install -m 0755 target/release/bgp /usr/local/bin/bgp
   

4. Verify the installation.

   bgp --version
   

   The command displays the installed version, for example bgp 0.2.5.

Building a Static Executable

The script scripts/build-static.sh builds the daemon as a single static executable for x86_64 Linux, linked against musl. The executable runs on any x86_64 Linux distribution without other dependencies.

The script requires the Rust target and a musl C compiler for jemalloc:

rustup target add x86_64-unknown-linux-musl

On macOS, install the cross compiler with brew install FiloSottile/musl-cross/musl-cross. On x86_64 Linux, install musl-tools (Debian, Ubuntu) or musl (Arch Linux).

scripts/build-static.sh

The script displays the path of the executable, the source revision, and the SHA-256 checksum of the executable:

target/x86_64-unknown-linux-musl/release/bgp: ELF 64-bit LSB pie executable, x86-64, static-pie linked
revision 9ce81a8
2faa32d3...  target/x86_64-unknown-linux-musl/release/bgp

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=1 and net.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.