Troubleshooting on Linux
On Linux, the agent runs as a system daemon. Following are the directories the agent uses by default:
/etc/cruxvpn: Configuration files./opt/venvs/cruxvpn-agent: Root program directory./opt/venvs/cruxvpn-agent/bin: Executables./opt/venvs/cruxvpn-agent/lib: Python packages./usr/local/lib/cruxvpn/agent/scripts: WireGuard post-up scripts.
Status
Systemd
On a Linux distribution that uses systemd, to view the general status of the agent, run the following command in a terminal on the host:
$ systemctl status cruxvpn-agent
● cruxvpn-agent.service - Crux VPN Agent
Loaded: loaded (/etc/systemd/system/cruxvpn-agent.service; enabled; preset: enabled)
Active: active (running) since Tue 2025-01-17 06:52:55 UTC; 15h ago
Main PID: 604973 (cruxvpn-agent)
Tasks: 3 (limit: 482)
Memory: 47.9M (peak: 81.1M)
CPU: 1min 4.319s
CGroup: /system.slice/cruxvpn-agent.service
└─604973 /opt/venvs/cruxvpn-agent/bin/python3 /opt/venvs/cruxvpn-agent/bin/cruxvpn-agent --loop=30 --verbosity=INFO
Jan 17 06:52:55 localhost systemd[1]: Started Crux VPN Agent.
If the agent is running, this command output should include active (running). Otherwise, try starting the agent with this command:
$ sudo systemctl start cruxvpn-agent
Substitute restart for start to restart an already running agent.
OpenRC
On a Linux distribution that uses OpenRC, to view the general status of the agent, run the following command in a terminal on the host:
$ rc-service cruxvpn-agent status
cruxvpn-agent started
If the agent is running, this command output should end with started. Otherwise, try starting the agent with this command:
$ sudo rc-service cruxvpn-agent start
Substitute restart for start to restart an already running agent.
Logs
When the agent starts up normally, its first dozen log entries should look like the following:
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
... 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 :)
2025-01-17 06:52:59,619 INFO procustodibus_agent.pqc.app - pqc update device policies
2025-01-17 06:52:59,625 INFO uk.arqit.device.monitoring.device_properties_client - Loading device metadata & properties...
2025-01-17 06:53:00,237 INFO uk.arqit.device.monitoring.device_properties_client - About to send properties with correlationId: 820CF1BD-7A5D-4C64-B7C6-AB266361978A
2025-01-17 06:53:00,837 INFO uk.arqit.device.monitoring.heartbeat_client - Loading device metadata...
2025-01-17 06:53:00,838 INFO uk.arqit.device.monitoring.heartbeat_client - About to send heartbeat with correlationId: 3662BAD5-BFFA-42F2-8AA2-B270F86FFD2F
2025-01-17 06:53:01,120 INFO procustodibus_agent.pqc.peering - starting pqc receiver on port 8887
The very first time the agent starts up, it will include a number of additional log entries related to registering with the Arqit SKA-Platform™ and starting up its WireGuard interfaces:
2025-01-15 22:46:07,862 INFO procustodibus_agent.pqc.app - pqc device metadata missing: /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:08,876 INFO procustodibus_agent.resolve_hostname - adjusting preference from ipv6 to ipv4
2025-01-15 22:46:09,420 INFO procustodibus_agent.pqc.app - pqc device metadata missing: /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:09,421 INFO procustodibus_agent.pqc.app - pqc device metadata missing: /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:09,427 INFO procustodibus_agent.agent - Starting agent 1.8.0
!!! no 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 not registered with SKA-Platform™ !!!
... 198.51.100.103 is SKA-Platform™ DSCC ip address ...
!!! device not authenticated with SKA-Platform™ !!!
All systems go :)
2025-01-15 22:46:09,577 INFO procustodibus_agent.pqc.app - pqc device metadata missing: /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:09,578 INFO procustodibus_agent.pqc.app - pqc device metadata missing: /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:10,215 INFO uk.arqit.device.registration.registration - Registering device with ID 'host-8zhVy1sDwAe', app_name 'Crux VPN Linux Host', manufacturer ID 'Sirius' OU UID '28it83MlKjaH3viVCyqpEM+QkcFH6PsjiQTZ59UXdSI='
2025-01-15 22:46:10,215 INFO uk.arqit.device.registration.key_exchanger_state_machines.ota_quantum_key_exchanger_state_machine - About to preregister with correlationId: 5D04C716-2379-4AEF-845F-6D3515559FDF
/opt/venvs/cruxvpn-agent/lib/python3.12/site-packages/oqs/oqs.py:173: UserWarning: liboqs version 0.11.0 differs from liboqs-python version 0.12.0
warnings.warn(
2025-01-15 22:46:13,240 INFO uk.arqit.device.registration.key_exchanger_state_machines.ota_quantum_key_exchanger_state_machine - About to register with correlationId: D86E2AE6-BCFD-41C5-9631-71E6ED2B9A4C
2025-01-15 22:46:15,206 INFO uk.arqit.device.registration.registration - Successfully registered device with QuantumCloud(TM)
2025-01-15 22:46:15,207 INFO uk.arqit.device.registration.registration - Stored device metadata at /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:15,209 INFO uk.arqit.device.common.authentication.authentication - About to authenticate device ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-15 22:46:15,967 INFO uk.arqit.device.common.authentication.authentication - Finished successfully authenticating device duid ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-15 22:46:15,974 INFO uk.arqit.device.provisioning.provisioning - Loading device metadata...
2025-01-15 22:46:15,975 INFO uk.arqit.device.provisioning.provisioning - Authenticating Device...
2025-01-15 22:46:15,975 INFO uk.arqit.device.provisioning.provisioning - Provisioning device with QuantumCloud(TM)...
2025-01-15 22:46:15,976 INFO uk.arqit.device.provisioning.provisioning - About to provision with correlationId: 03548452-F942-41AB-98F9-D82CA4DF7E84
2025-01-15 22:46:16,687 INFO uk.arqit.device.provisioning.provisioning - Successfully provisioned device with QuantumCloud(TM)
2025-01-15 22:46:16,687 INFO uk.arqit.device.provisioning.provisioning - Updating device metadata...
2025-01-15 22:46:16,691 INFO uk.arqit.device.provisioning.provisioning - Successfully updated device metadata at /etc/cruxvpn/deviceMetadata.json
2025-01-15 22:46:16,698 INFO uk.arqit.device.common.authentication.authentication - About to authenticate device ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-15 22:46:17,830 INFO uk.arqit.device.common.authentication.authentication - Finished successfully authenticating device duid ge3AOPdLKp9dwn/gQezC9egtRvrJXW/3Ds6IugXDiMs=
2025-01-15 22:46:18,489 INFO procustodibus_agent.pqc.app - pqc update device policies
2025-01-15 22:46:18,502 INFO uk.arqit.device.monitoring.device_properties_client - Loading device metadata & properties...
2025-01-15 22:46:19,719 INFO uk.arqit.device.monitoring.device_properties_client - About to send properties with correlationId: 7BB634D9-AB04-4CA4-9789-465B6D5B2434
2025-01-15 22:46:20,288 INFO uk.arqit.device.monitoring.heartbeat_client - Loading device metadata...
2025-01-15 22:46:20,289 INFO uk.arqit.device.monitoring.heartbeat_client - About to send heartbeat with correlationId: 757799DD-774F-4005-93FD-0A05C32A91E7
2025-01-15 22:46:20,814 INFO procustodibus_agent.pqc.peering - starting pqc receiver on port 8887
See the Common Error Messages page for more information about specific error messages you might see.
Systemd
On a Linux distribution that uses systemd, to view the agent's log files, run the following command in a terminal on the host:
$ journalctl -u cruxvpn-agent
Tip
Append the -e option to this command to scroll to the bottom of the log file:
$ journalctl -u cruxvpn-agent -e
Append the -S option to scroll to a particular timestamp:
$ journalctl -u cruxvpn-agent -S '2021-02-03 04:05:06'
Append the -f option to "tail" the log file (display new log entries as they are written):
$ journalctl -u cruxvpn-agent -f
OpenRC
On a Linux distribution that uses OpenRC, to view the agent's log files, run the following command in a terminal on the host:
$ less /var/log/cruxvpn-agent.log
Also check the error log, if present:
$ less /var/log/cruxvpn-agent.err
WireGuard
To view the status of the WireGuard tunnels on the host, run the following command in a terminal:
$ sudo 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
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:
$ sudo wq-quick down /etc/cruxvpn/crux0.conf
$ sudo wq-quick up /etc/cruxvpn/crux0.conf
Systemd
On a Linux distro that uses systemd, the agent will start and stop the WireGuard tunnels it manages via systemd "instantiated" services named like cruxvpn-wg@crux0 (where crux0 is a network interface name).
The standard systemctl and journalctl tools can be used with these services; for example to restart a tunnel:
$ sudo systemctl restart cruxvpn-wg@crux0
Tools
Agent Test
Run the following command on the host for a connectivity test to the Crux VPN API server and SKA-Platform™:
$ sudo /opt/venvs/cruxvpn-agent/bin/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
Use the standard ping utility to check connectivity through a WireGuard tunnel. 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:
$ 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
Various iproute2 commands can be used to check the network addresses and routing on a host. Run the following command to check the IP addresses assigned to the crux0 network interface:
$ 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:
$ ip route
default via 192.168.1.1 dev eth0 proto static metric 100
10.0.0.0/24 dev crux0 proto kernel scope link src 10.0.0.1
192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.123 metric 100
And the following command to check the main IPv6 route table on the host:
$ ip -6 route
2001:db8:abc:123::/64 dev ens5 proto ra metric 100 hoplimit 255 pref medium
fd00::/64 dev crux0 proto kernel metric 256 pref medium
fe80::/64 dev ens5 proto kernel metric 256 pref medium
default via fe80::de:f5:67:89 dev ens5 proto ra metric 100 expires 1790sec hoplimit 255 pref medium
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:
$ ip route get 10.0.0.2
10.0.0.2 dev crux0 src 10.0.0.1 uid 1001
cache
Firewall
Linux firewall rules are usually defined either as iptables rules or nftables rules. On most newer Linux systems, however, the iptables utilities actually are shims that transparently convert iptables rules to nftables rules.
In that case, the following command will print out all the active firewall rules on the host, in the form of nftables rules:
$ sudo nft list ruleset
# Warning: table ip filter is managed by iptables-nft, do not touch!
table ip filter {
chain FORWARD {
type filter hook forward priority filter; policy accept;
iifname "crux0" oifname "crux0" counter packets 0 bytes 0 accept
}
}
# Warning: table ip6 filter is managed by iptables-nft, do not touch!
table ip6 filter {
chain FORWARD {
type filter hook forward priority filter; policy accept;
iifname "crux0" oifname "crux0" counter packets 11 bytes 838 accept
}
}
Alternatively, run the following command to print out just the IPv4 iptables rules:
$ sudo 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
And the following command to print out just the IPv6 iptables rules:
$ sudo ip6tables-save
# Generated by ip6tables-save v1.8.10 (nf_tables) on Wed Jun 18 02:07:03 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:07:03 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).
SELinux
If you're using SELinux, run the ls -lZ command to check the context labels for the files in the /etc/cruxvpn/ directory. If the files are labeled correctly, you should see output similar to the following:
$ sudo ls -lZ /etc/cruxvpn
total 12
-rw-r--r--. 1 root root system_u:object_r:etc_t:s0 181 May 27 22:52 cruxvpn.conf
-rw-r-----. 1 root root system_u:object_r:etc_t:s0 275 May 27 22:52 cruxvpn-credentials.conf
-rw-r-----. 1 root root system_u:object_r:etc_t:s0 554 May 25 21:43 crux0.conf
If not, try running the restorecon command to relabel them:
$ sudo restorecon -Fv /etc/cruxvpn/*
Relabeled /etc/cruxvpn/cruxvpn-credentials.conf from unconfined_u:object_r:user_home_t:s0 to system_u:object_r:etc_t:s0
Relabeled /etc/cruxvpn/cruxvpn.conf from unconfined_u:object_r:user_home_t:s0 to system_u:object_r:etc_t:s0