Installing by hand

The setup wizard installs vulnboxd for you. This page is for installing just the daemon, without the GitHub setup, and for upgrading.

From a release

Releases are built for x86_64 against glibc, on an old enough distribution to run on most boxes. libgit2 and OpenSSL are built in, so the binaries only need libc and zlib.

curl -fsSL https://github.com/aarondewes/vulnboxd/releases/latest/download/vulnboxd-x86_64-unknown-linux-gnu.tar.gz | tar -xz
sudo ./vulnboxd-x86_64-unknown-linux-gnu/vulnboxctl install --tick 60s --window 5s /srv

vulnboxctl install does the whole installation:

1. checks that Docker and its compose plugin are there;
2. copies vulnboxd and vulnboxctl to /usr/local/bin;
3. writes /etc/vulnboxd/config.yml for the services directory, unless one is there already;
4. installs the systemd unit and the compose guard;
5. starts vulnboxd and checks that it stays up.

option
SERVICES_DIR	one directory per service, each with a compose file; defaults to the config's, or /srv
--tick <duration>	tick length of the game
--window <duration>	the end of each tick vulnboxd restarts services in
--poll <duration>	how often git is checked for new commits
--no-start	install everything, but do not start vulnboxd yet
--force	replace an existing config

For a game with a game mode, set game in the config instead of --tick: the mode knows the timing.

Taking over is not free

Starting vulnboxd for the first time moves every public port behind the proxy and recreates the containers at the end of the next tick. That is a few seconds of downtime, once. Use --no-start if you want to pick the moment yourself, then systemctl start vulnboxd.

Upgrading

sudo vulnboxctl upgrade                    # the latest release
sudo vulnboxctl upgrade --version v0.5.0   # a particular one
sudo vulnboxctl upgrade ./release.tar.gz   # one you already have

The running daemon takes the new build up at the end of a tick, without closing a port or dropping a connection. Upgrading covers the whole of it, including private repositories, going back a version, and what the unit has to allow.

The systemd unit

[Unit]
Description=vulnboxd
After=docker.service
Requires=docker.service

[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/vulnboxd -c /etc/vulnboxd/config.yml
Restart=always
RestartSec=1
LimitNOFILE=524288
# If a service container eats the memory, let the kernel kill it rather than the proxy for all services.
OOMScoreAdjust=-900

[Install]
WantedBy=multi-user.target

Type=notify is what lets an upgrade hand over without a restart: the old daemon tells systemd which process to watch from now on, and stays behind to finish the connections it had open. On a unit without it the daemon replaces itself instead and those connections are closed.

Restart=always matters: while vulnboxd is down, intercepted services are unreachable. Restarting it takes over the running containers without downtime, though a restart does close the public ports for a moment, which upgrading avoids entirely.

The capture broker has a unit of its own, vulnboxd-pcap, written when pcap.enabled is set. So does the status world, vulnboxd-mc, written when minecraft.enabled is — and removed, with the service stopped, when it is not.

Each proxied connection needs two file descriptors, so the unit raises the limit a long way. vulnboxd takes the hard limit at startup and warns if it is below 65536; LimitNOFILE is what sets it under systemd. OOMScoreAdjust=-900 means that if a service container eats the box's memory the kernel kills that container rather than the proxy in front of every service.

Building from source

Building needs a Rust toolchain and a C compiler (libgit2 and OpenSSL are compiled in), plus perl and make for OpenSSL's build.

cargo build --release
sudo ./target/release/vulnboxctl install /srv

The status world is a feature of its own, so it is a second build. The release archive has both; from source it is:

cargo build --release --features minecraft --bin vulnboxd-mc
sudo ./target/release/vulnboxctl install --minecraft /srv