Common Error Messages

Missing conf

If the agent's log or test command prints Missing conf for Agent ID and Host ID, then either:

The agent configuration file is missing required settings (or missing altogether); try re-downloading the configuration file as directed by the [Set Up Host] instructions.
The agent configuration file or directory does not have the correct permissions.
If using SELinux, the agent configuration file or directory has the wrong SELinux context label.
You did not run the test command as root; try re-running the test as root.

Check the cruxvpn.conf file in the agent's configuration directory (see the platform-specific troubleshooting page for the directory location). If you examine this file, it should look similar to the following:

$ sudo cat /etc/cruxvpn/cruxvpn.conf
# cruxvpn.conf generated 1/1/2020, 12:34:56 PM PDT
[Cruxvpn]
# Alice's Laptop Agent
Agent = ABC123def45
# Alice's Laptop
Host = DEF456ghi78

On Linux (and similar operating systems), if you examine the agent's configuration directory, the owner's permission bits should look like the following:

$ sudo ls -ld /etc/cruxvpn
drwx------ 2 root root 4096 May 25 21:39 /etc/cruxvpn
$ sudo ls -l /etc/cruxvpn
total 12
-rw-r--r-- 1 root root 181 May 27 22:52 cruxvpn.conf
-rw-r----- 1 root root 275 May 27 22:52 cruxvpn-credentials.conf
-rw-r----- 1 root root 554 May 25 21:43 wg0.conf

Missing code

If the agent's log or test command prints Missing code in setup file, then the agent setup file is missing required settings; try re-downloading the setup file as directed by the [Set Up Host] instructions.

If you examine the agent setup file, it should look similar to the following:

$ sudo cat /etc/cruxvpn/cruxvpn-setup.conf
# cruxvpn-setup.conf generated 1/1/2020, 12:34:56 PM PDT
[Cruxvpn.Setup]
# Alice's Laptop Agent
Agent = ABC123def45
Code = GHI789JKL01
Expires = 2020-01-03T20:34:56Z

Setup code has expired

If the agent's log or test command prints Setup code has expired, then the code in the agent setup file has expired; download a new setup file as directed by the [Set Up Host] instructions.

Could not read credentials

If the agent's log or test command prints Could not read credentials file, then the agent credentials file is missing; download a new setup file as directed by the [Set Up Host] instructions (a new setup file will allow the agent to generate a new credentials file).

Missing private key

If the agent's log or test command prints Missing private key in credentials file, then the agent credentials file is missing required settings; try downloading a new setup file as directed by the xref:hosts:setup.adoc[Set Up Host] instructions (a new setup file will allow the agent to generate a new credentials file).

If you examine the agent credentials file, it should look similar to the following:

$ sudo cat /etc/cruxvpn/cruxvpn-credentials.conf
# cruxvpn-credentials.conf generated 2020-01-01T20:34:56Z
# for agent ABC123def45 on a123.corp.example.com
[Cruxvpn.Credentials]
PublicKey = O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik=
PrivateKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

No wg executable

If the agent's log or test command prints no wg executable found, then you may not have installed WireGuard on the host yet. Try installing WireGuard.

No wireguard interfaces

If the agent's log or test command prints no wireguard interfaces found, then you may not have configured any WireGuard interfaces on the host yet. Try adding one.

DNS error

If the agent's log or test command prints dns error resolving ui.crux.sirius.computer (or the DNS name of your private Crux VPN API instance, if different), then the agent is not able to resolve the Crux VPN API server's DNS entry. Access to the DNS servers on which the agent relies by default may be blocked. See the DNS page to troubleshoot.

Server unavailable

If the agent's log or test command prints server unavailable, check whether or not the output also includes dns error. If it does, see the DNS error issue above.

If the output does not include dns error, the output will include the IP address of your active Crux VPN API endpoint in a phrase like 192.0.2.3 is crux vpn ip address (the IP address will be something other than 192.0.2.3, however). Try running the following command in a terminal on the host (replacing 192.0.2.3 with the actual IP address from the output):

$ ping -c1 192.0.2.3
PING 192.0.2.3 (192.0.2.3): 56 data bytes
64 bytes from 192.0.2.3: icmp_seq=0 ttl=37 time=10.138 ms
--- 192.0.2.3 ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max/stddev = 10.138/10.138/10.138/0.000 ms

If the ping command hangs or the output of the ping command ends with 100% packet loss, network access from the host to the Crux VPN API server may be blocked. You may need to update your firewall or other networking settings to allow the host to access the Crux VPN API server.

If the output of the ping command includes 0% packet loss, your connection to the Crux VPN API server is good. The Crux VPN API may be down; email the support team to check.

Unhealthy crux vpn api

If the agent's log or test command prints unhealthy crux vpn api, then there is a problem with the Crux VPN servers; email the support team for details.

Cannot access host record

If the agent's log or test command prints cannot access host record, then the agent does not have permission to access the host's record on the Crux VPN API. Either:

The host record on the Crux VPN API has been deleted
The agent record on the Crux VPN API has been deleted
The agent's credentials for the Crux VPN API have been revoked
The agent's access to the host on the Crux VPN API has been revoked

Try re-downloading the cruxvpn.conf and cruxvpn-setup.conf files as directed by the [Set Up Host] instructions, and then restart the agent as directed by the platform-specific troubleshooting page.

Unauthorized for url

If the agent's log prints the following error message:

401 Client Error: Unauthorized for url: https://ui.crux.example.com/users/ABC123def45/credentials/signature

Try re-downloading the cruxvpn.conf and cruxvpn-setup.conf files from the host's set-up page in the web UI, and then restart the agent (see the platform-specific troubleshooting page).

No module named cruxvpn_agent

If after upgrading the OS on a host you see the following error message in the agent logs:

ModuleNotFoundError: No module named 'cruxvpn_agent'

This probably means the OS is now using a newer version of Python than the agent was originally installed under.

To fix, download the latest version of the agent, and reinstall it with the --install flag:

$ cd cruxvpn-agent-*/
$ sudo ./install.sh --install
running as root
install 1.8.0
agent configuration found at /etc/cruxvpn/cruxvpn.conf
agent credentials found at /etc/cruxvpn/cruxvpn-credentials.conf
/etc/cruxvpn/cruxvpn.conf mode ok (-rw-rw-r--)
/etc/cruxvpn/cruxvpn.conf owner is root
/etc/cruxvpn/cruxvpn.conf group is root
/etc/cruxvpn/cruxvpn-credentials.conf mode ok (-rw-r-----)
/etc/cruxvpn/cruxvpn-credentials.conf owner is root
/etc/cruxvpn/cruxvpn-credentials.conf group is root
libsodium found at /lib/aarch64-linux-gnu/libsodium.so.23
python 3.10.0 found at /usr/bin/python3
python includes all packages needed for venv
WARNING python virtualenv broken at /opt/venvs/cruxvpn-agent
recreate virtualenv? ([y]es, [q]uit): y
OK will delete virtualenv
deleted virtualenv
OK will create virtualenv
created virtualenv
WARNING agent package not installed
install agent from /root/cruxvpn-agent-1.8.0? ([y]es, [q]uit): y
OK will install agent
...
installed agent
systemd daemon found at /etc/systemd/system/cruxvpn-agent.service
WARNING daemon failed
start daemon? ([y]es, [q]uit): y
OK will start daemon
started daemon
install SUCCESS

Missing conf for realm

If the agent's log or test command prints !!! device cannot register with SKA-Platform™ (Missing conf for realm and username and password) !!!, the agent cannot find any SKA-Platform™ registration credentials. Check the cruxvpn-registration.conf file in the agent's configuration directory (see the platform-specific troubleshooting page for the directory location). If you examine this file, it should include at least the following settings:

$ sudo cat /etc/cruxvpn/cruxvpn-registration.conf
[PQC.Registration]
Realm = myorganization
Username = [email protected]
Password = password123

If you do not see this file in the agent's configuration directory, create it, and populate it as above with your SKA-Platform™ registration credentials.

Registration failure

If the agent's log prints Max retries exceeded with url: /realms/[the realm name]/protocol/openid-connect/token during the registration process, the agent cannot connect to the SKA-Platform™ user-authentication endpoint. Check the UserAuth setting in the [PQC.API] section of the cruxvpn.conf file.

If the agent's log prints Max retries exceeded with url: /api/v2/preregister/mpq during the registration process, the agent cannot connect to the SKA-Platform™ provisioning endpoint. Check the Provisioning setting in the [PQC.API] section of the cruxvpn.conf file.

Not authorized exception

If the agent's log prints a NotAuthorizedException during the registration process, the SKA-Platform™ registration credentials have been rejected. Check the cruxvpn-registration.conf file in the agent's configuration directory (see the platform-specific troubleshooting page for the directory location).

Already exists device with ID

If the agent's log prints There already exists a device with ID during the registration process, a device with the same ID is already registered. Either deregister the existing device, or set the Device setting in the cruxvpn-registration.conf file to a unique device ID.

Device cannot authenticate

If the agent's log or test command prints !!! device cannot authenticate with SKA-Platform™ () !!! and Max retries exceeded with url: /api/v3/device/authenticate/challenge, the agent cannot connect to the SKA-Platform™ authentication endpoint. Check the Authentication setting in the [PQC.API] section of the cruxvpn.conf file.

Terminal authentication failure

If the agent's log prints terminal authentication failure, the agent's local "root of trust" key has gotten out of sync with the SKA-Platform™. The device must be re-registered. If the SKA-Platform™ registration credentials are still available in the cruxvpn-registration.conf file, the agent will automatically attempt to re-register the device.

Failed to start pqc initiator

If the agent's log prints failed to start pqc initiator with a further reason of Max retries exceeded with url: /api/v1/bilocation/intermediate, the agent cannot connect to the SKA-Platform™ DSCC endpoint. Check the Dscc setting in the [PQC.API] section of the cruxvpn.conf file.

If the agent's log prints failed to start pqc initiator with a further reason of PeerFailedToReceiveMessageException, the agent cannot connect to an SKA peer (the specific peer address should be included in the error message). The peer may be offline, or its SKA peering port (usually TCP port 8887) has been blocked by a firewall.

Address in use

If the agent's log prints Address in use or port: 8887 is already in use, the agent cannot start its SKA peering receiver because some other process is using the same TCP port. Try running a command like lsof -i :8887 or ss -pl sport 8887 to identify the other process.

Note

Occasionally this error occurs as a side effect of the address-in-use check itself; if this is the case, the agent will correct the error automatically, and you'll see a successful starting pqc receiver on port 8887 log entry in 30 seconds or a minute later.

Heartbeat error

If the agent's log prints pqc heartbeat error or Max retries exceeded with url: /v1/heartbeat, the agent cannot connect to the SKA-Platform™ heartbeat endpoint. Check the MonitorHeartbeat setting in the [PQC.API] section of the cruxvpn.conf file.

Send device properties error

If the agent's log prints pqc send device properties error or Max retries exceeded with url: /v1/properties, the agent cannot connect to the SKA-Platform™ properties endpoint. Check the MonitorProperties setting in the [PQC.API] section of the cruxvpn.conf file.

Update device policies error

If the agent's log prints pqc update device policies error or Max retries exceeded with url: /api/v1/policy/delta, the agent cannot connect to the SKA-Platform™ policy endpoint. Check the Policy setting in the [PQC.API] section of the cruxvpn.conf file.

No peer found for duid

If the agent's log prints no peer found for duid, the agent received a peering message from a device whose WireGuard identity it does not know. Check the DUID (Device Unique ID) included in the log entry, and in the Crux VPN web UI, update the host that represents the device with this DUID.