Building From Source¶
In addition to meeting the system requirements, there are three things you need to build Routinator: rsync, a C toolchain and Rust. You can run Routinator on any operating system and CPU architecture where you can fulfil these requirements.
Dependencies¶
To get started you need rsync because some RPKI repositories still use it as its main means of distribution. Some of the cryptographic primitives used by Routinator require a C toolchain. Lastly, you need Rust because that’s the programming language that Routinator has been written in.
rsync¶
Currently, Routinator requires the rsync executable to be in your path. Due to the nature of rsync, it is unclear which particular version you need at the very least, but whatever is being shipped with current Linux and *BSD distributions, as well as macOS should be fine. Alternatively, you can download rsync from the Samba website.
On Windows, Routinator requires the rsync version that comes with Cygwin – make sure to select rsync during the installation phase.
C Toolchain¶
Some of the libraries Routinator depends on require a C toolchain to be present. Your system probably has some easy way to install the minimum set of packages to build from C sources. For example, this command will install everything you need on Debian/Ubuntu:
apt install build-essential
If you are unsure, try to run cc on a command line. If there is a complaint about missing input files, you are probably good to go.
Rust¶
The Rust compiler runs on, and compiles to, a great number of platforms, though not all of them are equally supported. The official Rust Platform Support page provides an overview of the various support levels.
While some system distributions include Rust as system packages, Routinator relies on a relatively new version of Rust, currently 1.52 or newer. We therefore suggest to use the canonical Rust installation via a tool called rustup.
Assuming you already have curl installed, you can install rustup and Rust by simply entering:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Alternatively, visit the Rust website for other installation methods.
Building and Updating¶
In Rust, a library or executable program such as Routinator is called a crate. Crates are published on crates.io, the Rust package registry. Cargo is the Rust package manager. It is a tool that allows Rust packages to declare their various dependencies and ensure that you’ll always get a repeatable build.
Cargo fetches and builds Routinator’s dependencies into an executable binary for your platform. By default you install from crates.io, but you can for example also install from a specific Git URL, as explained below.
Installing the latest Routinator release from crates.io is as simple as running:
cargo install --locked routinator
The command will build Routinator and install it in the same directory that
Cargo itself lives in, likely $HOME/.cargo/bin
. This means Routinator
will be in your path, too.
Note
Before you can use Routinator, you must first initialise the application.
Updating¶
If you want to update to the latest version of Routinator, it’s recommended to update Rust itself as well, using:
rustup update
Use the --force
option to overwrite an existing version with the latest
Routinator release:
cargo install --locked --force routinator
Installing Specific Versions¶
If you want to install a specific version of
Routinator using Cargo, explicitly use the --version
option. If needed,
use the --force
option to overwrite an existing version:
cargo install --locked --force routinator --version 0.9.0-rc2
All new features of Routinator are built on a branch and merged via a pull
request, allowing you to
easily try them out using Cargo. If you want to try a specific branch from
the repository you can use the --git
and --branch
options:
cargo install --git https://github.com/NLnetLabs/routinator.git --branch main
See also
For more installation options refer to the Cargo book.
Enabling or Disabling Features¶
When you build Routinator, “features” provide a
mechanism to express conditional compilation and optional dependencies. The
Routinator package defines a set of named features in the [features]
table of Cargo.toml. The table
also defines if a feature is enabled or disabled by default.
Routinator currently has the following features:
socks
— Enabled by defaultAllow the configuration of a SOCKS proxy.
ui
— Enabled by defaultDownload and build the the routinator-ui crate to run the user interface.
native-tls
— Disabled by defaultUse the native TLS implementation of your system instead of rustls.
rta
— Disabled by defaultLet Routinator validate Resource Tagged Attestations.
To disable the features that are enabled by default, use the
--no-default-features
option. You can then choose which features you want
using the --features
option, listing each feature separated by commas.
For example, if you want to build Routinator without the user interface, make sure SOCKS support is retained and use the native TLS implementation, enter the following command:
cargo install --locked --no-default-features --features socks,native-tls routinator
Statically Linked Routinator¶
While Rust binaries are mostly statically linked, they depend on libc which, as least as glibc that is standard on Linux systems, is somewhat difficult to link statically. This is why Routinator binaries are actually dynamically linked on glibc systems and can only be transferred between systems with the same glibc versions.
However, Rust can build binaries based on the alternative implementation
named musl that can easily be statically linked. Building such
binaries is easy with rustup. You need to install musl
and the correct musl target such as x86_64-unknown-linux-musl
for x86_64 Linux systems. Then you can just build Routinator for that
target.
On a Debian (and presumably Ubuntu) system, enter the following:
sudo apt-get install musl-tools
rustup target add x86_64-unknown-linux-musl
cargo build --target=x86_64-unknown-linux-musl --release
Platform Specific Instructions¶
Tip
GÉANT has created an Ansible playbook defining a role to deploy Routinator on Ubuntu.
For some platforms, rustup cannot provide binary releases to install directly. The Rust Platform Support page lists several platforms where official binary releases are not available, but Rust is still guaranteed to build. For these platforms, automated tests are not run so it’s not guaranteed to produce a working build, but they often work to quite a good degree.
OpenBSD¶
On OpenBSD, patches are required to get Rust running correctly, but these are well maintained and offer the latest version of Rust quite quickly.
Rust can be installed on OpenBSD by running:
pkg_add rust
CentOS 6¶
The standard installation method does not work when using CentOS 6. Here, you will end up with a long list of error messages about missing assembler instructions. This is because the assembler shipped with CentOS 6 is too old.
You can get the necessary version by installing the Developer Toolset 6 from the Software Collections repository. On a virgin system, you can install Rust using these steps:
sudo yum install centos-release-scl
sudo yum install devtoolset-6
scl enable devtoolset-6 bash
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
SELinux using CentOS 7¶
This guide, contributed by Rich Compton, describes how to run Routinator on Security Enhanced Linux (SELinux) using CentOS 7.
Start by setting the hostname:
sudo nmtui-hostname
Set the interface and connect it:
Note
Ensure that “Automatically connect” and “Available to all users” are checked.
sudo nmtui-edit
Install the required packages:
sudo yum check-update
sudo yum upgrade -y
sudo yum install -y epel-release
sudo yum install -y vim wget curl net-tools lsof bash-completion yum-utils \
htop nginx httpd-tools tcpdump rust cargo rsync policycoreutils-python
Set the timezone to UTC:
sudo timedatectl set-timezone UTC
Remove postfix as it is unneeded:
sudo systemctl stop postfix
sudo systemctl disable postfix
Create a self-signed certificate for NGINX:
sudo mkdir /etc/ssl/private
sudo chmod 700 /etc/ssl/private
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/nginx-selfsigned.key \
-out /etc/ssl/certs/nginx-selfsigned.crt
# Populate the relevant information to generate a self signed certificate
sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048
Add in the
ssl.conf
file to/etc/nginx/conf.d/ssl.conf
and edit thessl.conf
file to provide the IP of the host in theserver_name
field.Replace
/etc/nginx/nginx.conf
with thenginx.conf
file.Set the username and password for the web interface authentication:
sudo htpasswd -c /etc/nginx/.htpasswd <username>
Start Nginx and set it up so it starts at boot:
sudo systemctl start nginx
sudo systemctl enable nginx
Add the user routinator, create the
/opt/routinator
directory and assign it to the routinator user and group:
sudo useradd routinator
sudo mkdir /opt/routinator
sudo chown routinator:routinator /opt/routinator
Sudo into the routinator user:
sudo su - routinator
Install Routinator and add it to the
$PATH
for user routinator:
cargo install --locked routinator
vi /home/routinator/.bash_profile
Edit the PATH line to include "/home/routinator/.cargo/bin"
PATH=$PATH:$HOME/.local/bin:$HOME/bin:/home/routinator/.cargo/bin
Initialise Routinator, accept the ARIN TAL and exit back to the user with sudo:
/home/routinator/.cargo/bin/routinator -b /opt/routinator init -f --accept-arin-rpa
exit
Create a routinator systemd script using the template below:
sudo vi /etc/systemd/system/routinator.service
[Unit]
Description=Routinator RPKI Validator and RTR Server
After=network.target
[Service]
Type=simple
User=routinator
Group=routinator
Restart=on-failure
RestartSec=90
ExecStart=/home/routinator/.cargo/bin/routinator -v -b /opt/routinator server \
--http 127.0.0.1:8080 --rtr <IPv4 IP>:8323 --rtr [<IPv6 IP>]:8323
TimeoutStartSec=0
[Install]
WantedBy=default.target
Note
You must populate the IPv4 and IPv6 addresses. In addition, the IPv6 address needs to have brackets ‘[ ]’ around it. For example:
/home/routinator/.cargo/bin/routinator -v -b /opt/routinator server \
--http 127.0.0.1:8080 --rtr 172.16.47.235:8323 --rtr [2001:db8::43]:8323
Configure SELinux to allow connections to localhost and to allow rsync to write to the
/opt/routinator
directory:
sudo setsebool -P httpd_can_network_connect 1
sudo semanage permissive -a rsync_t
Reload the systemd daemon and set the routinator service to start at boot:
sudo systemctl daemon-reload
sudo systemctl enable routinator.service
sudo systemctl start routinator.service
Set up the firewall to permit ssh, HTTPS and port 8323 for the RTR protocol:
sudo firewall-cmd --permanent --remove-service=ssh --zone=public
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv4" \
source address="<IPv4 management subnet>" service name=ssh accept'
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv6" \
source address="<IPv6 management subnet>" service name=ssh accept'
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv4" \
source address="<IPv4 management subnet>" service name=https accept'
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv6" \
source address="<IPv6 management subnet>" service name=https accept'
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv4" \
source address="<peering router IPv4 loopback subnet>" port port=8323 protocol=tcp accept'
sudo firewall-cmd --permanent --zone public --add-rich-rule='rule family="ipv6" \
source address="<peering router IPv6 loopback subnet>" port port=8323 protocol=tcp accept'
sudo firewall-cmd --reload
Navigate to
https://<IP-address>/metrics
to see if it’s working. You should authenticate with the username and password that you provided in step 10 of setting up the RPKI Validation Server.