Troubleshooting Docker Containers
The Crux VPN agent Docker container uses Alpine Linux for its base image. The agent runs as an OpenRC service within the container; most of the same features of the Linux version of the agent running under OpenRC apply to the Docker version of the agent.
The agent uses the host directory mounted to the container's /etc/cruxvpn directory for all of its configuration files.
Status
To view the general status of the agent in a running container, shell into the container and run the following docker exec command (where cruxvpn is the name you gave the container when you started it):
$ sudo docker exec -it cruxvpn bash
1234567890ab:/# rc-service cruxvpn-agent status
cruxvpn-agent started
Logs
The agent will send its logs to stdout. To view the logs of a running container, run the following docker logs command (where cruxvpn is the name you gave the container when you started it):
$ sudo docker logs cruxvpn
* /proc is already mounted
* /run/lock: creating directory
* /run/lock: correcting owner
fopen '/run/openrc/deptree': No such file or directory
fopen '/run/openrc/depconfig': No such file or directory
* Failed to update the dependency tree
[ !! ]
* failed to load deptree
OpenRC 0.62.2 is starting up Linux 6.8.0-60-generic (x86_64) [DOCKER]
* Caching service dependencies ... * Caching service dependencies ... [ ok ]
* Caching service dependencies ... [ ok ]
* Starting cruxvpn-agent ... [ ok ]
2025-01-17 06:52:57,154 INFO uk.arqit.device.common.authentication.authentication - About to authenticate device ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-17 06:52:58,633 INFO uk.arqit.device.common.authentication.authentication - Finished successfully authenticating device duid ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-17 06:52:58,634 INFO procustodibus_agent.agent - Starting agent 1.8.0
...
See the Common Error Messages page for more information about specific error messages you might see.
Tip
Use the -n option with this command to limit the entries to just the last N entries (like the last 50 entries):
$ sudo docker logs -n 50 cruxvpn
Use the --since option to limit the entries to those after a particular timestamp:
$ sudo docker logs --since 2021-02-03T04:05:06 cruxvpn
Use the -f option to "tail" the log file (display new log entries as they are written):
$ sudo docker logs -f cruxvpn
WireGuard
To view the status of the WireGuard tunnels in a running container, shell into the container and run the following command (where cruxvpn is the name you gave the container when you started it):
$ sudo docker exec -it cruxvpn bash
1234567890ab:/# wg
interface: crux0
public key: /TOE4TKtAqVsePRVR+5AA43HkAK5DSntkOCO7nYq5xU=
private key: (hidden)
listening port: 51820
peer: fE/wdxzl0klVp/IR8UcaoGUMjqaWi3jAd7KzHKFS6Ds=
preshared key: (hidden)
endpoint: 203.0.113.22:42527
allowed ips: 10.0.0.0/24
latest handshake: 28 seconds ago
transfer: 2.48 KiB received, 1.82 KiB sent
Within the container, the standard wg and wg-quick tools can be used to update or start and stop these WireGuard tunnels; for example to restart a tunnel:
1234567890ab:/# wq-quick down /etc/cruxvpn/crux0.conf
1234567890ab:/# wq-quick up /etc/cruxvpn/crux0.conf
Tools
Agent Test
For a connectivity test to the Crux VPN API server and SKA-Platform™, shell into the container and run the following command (where cruxvpn is the name you gave the container when you started it):
$ sudo docker exec -it cruxvpn bash
1234567890ab:/# cruxvpn-agent --test
... 1 wireguard interfaces found ...
... 203.0.113.150 is crux vpn ip address ...
... healthy crux vpn api ...
... can access host record on api for Example Host ...
... device registered with SKA-Platform™ ...
... 198.51.100.103 is SKA-Platform™ DSCC ip address ...
... device can authenticate with SKA-Platform™ ...
All systems go :)
If this command outputs an error message, see the Common Error Messages page for more information.
Ping
To check connectivity through a WireGuard tunnel, shell into the container and use the standard ping utility. For example, to verify that you can connect through the tunnel to a remote host with a private WireGuard address of 10.0.0.2, run the following command to "ping" it with its private address:
1234567890ab:/# ping -nc1 10.0.0.2
PING 10.0.0.2 (10.0.0.2) 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=52.3 ms
--- 10.0.0.2 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 52.294/52.294/52.294/0.000 ms
Routing
The iproute2 utilities are included in the container image, and can be used to check the network addresses and routing inside the container. Shell into the container and run the following command to check the IP addresses assigned to the crux0 network interface:
1234567890ab:/# ip address show dev crux0
3: crux0: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1420 qdisc noqueue state UNKNOWN group default qlen 1000
link/none
inet 10.0.0.1/24 scope global crux0
valid_lft forever preferred_lft forever
inet6 fd00::1/64 scope global
valid_lft forever preferred_lft forever
Run the following command to check the main IPv4 route table on the host:
1234567890ab:/# ip route
default via 172.16.0.1 dev eth0
172.16.0.0/16 dev eth0 proto kernel scope link src 172.16.0.2
10.0.0.0/24 dev crux0 proto kernel scope link src 10.0.0.1
Run the following command to verify which network interface traffic to a particular IP address (such as 10.0.0.2) will be routed out:
1234567890ab:/# ip route get 10.0.0.2
10.0.0.2 dev crux0 src 10.0.0.1 uid 0
cache
Firewall
Shell into the container and run the following command to check the container's active IPv4 iptables rules:
1234567890ab:/# iptables-save
# Generated by iptables-save v1.8.10 (nf_tables) on Wed Jun 18 02:05:29 2025
*filter
:INPUT ACCEPT [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
-A FORWARD -i crux0 -o crux0 -m comment --comment "crux vpn agent forward script" -j ACCEPT
COMMIT
# Completed on Wed Jun 18 02:05:29 2025
If the host is meant to be used in a server role, it will need to accept inbound connections on its WireGuard listen port (usually UDP port 51820), and on its SKA peering port (usually TCP port 8887). Make sure you've run the container with those ports exposed (like with the docker run -p option).
Namespace Enter
You can use the nsenter tool on the host to run any other command-line diagnostic tools you have installed on the host from within the container's own network namespace. This allows you to run a utility available only outside of the container as if it were actually installed inside the container.
First, identify the PID (process ID) of the container with the following command (where cruxvpn is the container's name):
$ sudo docker container inspect cruxvpn -f '{{.State.Pid}}'
12345
Then use the nsenter command with that PID to run any tool installed on the container's host, like dig:
$ sudo nsenter -t 12345 -n dig +short ui.crux.sirius.computer
192.0.2.0