Skip to content

Install on Docker

Docker Load

To install the agent, load the downloaded OCI image into your container runner, and tag it as latest:

$ docker load --input cruxvpn-agent-latest-linux-amd64-oci.tar.bz2
$ docker tag \
    $(docker image ls -q ghcr.io/crux-comms/cruxvpn-agent | head -n1) \
    ghcr.io/crux-comms/cruxvpn-agent:latest

Docker Run

Once the OCI image is loaded, you can run it with a docker run command like the following:

$ docker run \
    --cap-add NET_ADMIN \
    --publish 8887:8887/tcp \
    --publish 51820:51820/udp \
    --name cruxvpn \
    --rm \
    --volume /srv/containers/cruxvpn/conf:/etc/cruxvpn:Z \
    ghcr.io/crux-comms/cruxvpn-agent

 * /proc is already mounted
 * /run/lock: creating directory
 * /run/lock: correcting owner
   OpenRC 0.43.3.bf57debcde is starting up Linux 5.11.0-1020-aws (x86_64) [DOCKER]

 * Caching service dependencies ... [ ok ]
 * Starting WireGuard interface crux0 ...[#] ip link add crux0 type wireguard
[#] wg setconf crux0 /dev/fd/63
[#] ip -4 address add 10.0.0.1/32 dev crux0
[#] ip link set mtu 1420 up dev crux0
[#] ip -4 route add 10.0.0.2/32 dev crux0
 [ ok ]
 * Starting cruxvpn-agent ... [ ok ]

These are what the above command options do:

  • --cap-add NET_ADMIN: Grants the container the NET_ADMIN capability -- this is required to start a WireGuard interface inside the container.
  • --publish 51820:51820/udp: Forwards the public 51820 UDP port on the container's host to the container's 51820 UDP port -- make sure the latter matches the ListenPort setting in the WireGuard config file (the former can be whatever port you want to expose publicly). When running multiple WireGuard interfaces in the same container, publish one port mapping for each interface.
  • --publish 8887:8887/tcp: Forwards the public 8887 TCP port on the container's host to the container's 8887 TCP port, allowing the agent to receive SKA-P peering connections.
  • --name cruxvpn: Sets the container's name to cruxvpn (you can set this to whatever name you want, or omit it entirely if you don't care how it's named).
  • --rm: Deletes the container when it's shut down (you can omit this if you don't want to delete the container).
  • --volume /srv/containers/cruxvpn/conf:/etc/cruxvpn:Z: Maps the /srv/containers/cruxvpn/conf directory on the container's host to the /etc/cruxvpn directory within the container (you can change the host directory to whatever you want).
  • ghcr.io/crux-comms/cruxvpn-agent: Runs the latest version of the Crux VPN agent.

You can omit the --publish options if the container will only be used as an SKA-P initiator, and not as a receiver.

If you are going to run a WireGuard interface with an AllowedIPs setting of 0.0.0.0/0 (and using the default routing table), also add the following command option:

--sysctl net.ipv4.conf.all.src_valid_mark=1

Tip

When using Podman, if the container serves as a hub or gateway to other hosts, you may also need to add the following options: 

--sysctl net.ipv4.conf.all.forwarding=1

Place the agent setup files, as well as any existing agent, SKA-P, or WireGuard interface configuration files, in the container host's /srv/containers/cruxvpn/conf/ directory (or in whatever directory on the container's host you choose to map to the container's /etc/cruxvpn/ directory). Starting the container will start the Crux VPN agent, as well as any Crux VPN tunnels configured for the host.

Docker Compose

The basic pattern for running the agent image with the docker compose command is to create a docker-compose.yml file like the following:

# /srv/containers/cruxvpn/docker-compose.yml
services:
  cruxvpn:
    image: ghcr.io/crux-comms/cruxvpn-agent
    cap_add:
    - NET_ADMIN
    ports:
    - 8887:8887/tcp
    - 51820:51820/udp
    volumes:
    - ./conf:/etc/cruxvpn:Z

These are what the above cruxvpn service keys do:

  • image: ghcr.io/crux-comms/cruxvpn-agent: Runs the latest version of the Crux VPN agent.
  • cap_add: ['NET_ADMIN']: Grants the container the NET_ADMIN capability -- this is required to start a WireGuard interface inside the container.
  • ports: ['8887:8887/tcp', '51820:51820/udp']: Forwards the public 8887 TCP port on the container's host to the container's 8887 TCP port, allowing the agent to receive SKA-P peering connections; and forwards the public 51820 UDP port on the container's host to the container's 51820 UDP port -- make sure the latter matches the ListenPort setting in the WireGuard config file (the former can be whatever port you want to expose publicly). When running multiple WireGuard interfaces in the same container, include one UDP port mapping for each interface.
  • volumes: ['./conf:/etc/cruxvpn:Z']: Maps the conf directory on the container's host (sibling of the docker-compose.yml file) to the /etc/cruxvpn directory within the container (you can change the host directory to whatever you want).

You can omit the ports key if the container will only be used as an SKA-P initiator, and not as a receiver.

If you are going to run a WireGuard interface with an AllowedIPs setting of 0.0.0.0/0 (and using the default routing table), also add the following sysctls entry to the cruxvpn service:

    sysctls:
    - net.ipv4.conf.all.src_valid_mark=1

Tip

When using Podman, if the container serves as a hub or gateway to other hosts, you may also need to add the following sysctls entry: 

    - net.ipv4.conf.all.forwarding=1

If you create the docker-compose.yml file in the container host's /srv/containers/cruxvpn/ directory, create a conf/ subdirectory in that directory, and place the agent setup files and any existing WireGuard interface configuration files there (or wherever you choose to map to the container's /etc/cruxvpn/ directory).

Starting the container from the directory containing the docker-compose.yml file with the following command will start the Crux VPN agent, as well as any Crux VPN tunnels configured for the host:

$ docker compose up
Creating network "cruxvpn_default" with the default driver
Creating cruxvpn_cruxvpn_1 ... done
Attaching to cruxvpn_cruxvpn_1
cruxvpn_1  |
cruxvpn_1  |  * /proc is already mounted
cruxvpn_1  |  * /run/lock: creating directory
cruxvpn_1  |  * /run/lock: correcting owner
cruxvpn_1  |    OpenRC 0.43.3.bf57debcde is starting up Linux 5.11.0-1020-aws (x86_64) [DOCKER]
cruxvpn_1  |
cruxvpn_1  |  * Caching service dependencies ... [ ok ]
cruxvpn_1  |  * Starting WireGuard interface crux0 ...[#] ip link add crux0 type wireguard
cruxvpn_1  | [#] wg setconf crux0 /dev/fd/63
cruxvpn_1  | [#] ip -4 address add 10.0.0.1/24 dev crux0
cruxvpn_1  | [#] ip link set mtu 1420 up dev crux0
cruxvpn_1  |  [ ok ]
cruxvpn_1  |  * Starting cruxvpn-agent ... [ ok ]

Next Steps

  1. Check the host's main page in the app. The Agent panel should show the results of the agent's latest ping.
  2. If the Agent panel simply reads Set Up Agent, or if the Interfaces panel shows the host's interfaces as Down, check the Agent Troubleshooting page.

Upgrade

To upgrade the agent, download the latest version of the agent OCI image; then run the docker load commands described at the top of the page to load it and tag it as latest. Restart any running Crux VPN containers to update them to the newly loaded image.

Caution

Restarting a container will temporarily interrupt any Crux VPN tunnels running in the container.

To restart a container started with docker run, run the following command to stop and delete the container (if the container is named cruxvpn):

$ docker stop cruxvpn && docker rm cruxvpn

Then re-run the docker run command you used originally to start the container.

To restart a container started with docker compose, run the following command from the directory containing the docker-compose.yml file (if the Crux VPN agent service is named cruxvpn):

$ docker compose up -d cruxvpn

Deregister

To deregister a container from the Arqit SKA-Platform™ (SKA-P), make sure the container has a registration file with current credentials. Then run the following command on the container host to deregister it (if the container is named for example cruxvpn):

$ docker exec cruxvpn cruxvpn-deregister

Uninstall

You can uninstall the containerized version of the agent by stopping and deleting all running agent containers, and removing all versions of the agent OCI image.

This will not deregister any containers from the SKA-P; nor will it remove any agent configuration or credential files (to remove these files, delete the directories on the host that you used for agent configuration, such as /srv/containers/cruxvpn/conf/ in the above examples).