Troubleshooting Crux for ATAK
Find the symptom in the table for where you see it. The placeholders PUBLIC_NAME and
TUNNEL_NAME are the TAK Server's public name and tunnel name, as defined in
Set up a TAK Server.
On the handset
The following problems show up in ATAK or in the Crux pane:
| What you see | Why | What to do |
|---|---|---|
| Crux isn't in the ☰ menu. | The plugin is installed but not loaded. An update also unloads it. | Load it under Settings > Tool Preferences > Package Management, then close ATAK completely and open it again. |
Loading crux-setup.conf reports that the code has been used or has expired, or reports HTTP 401. |
The setup code in the file is single-use and expires. | Ask your administrator for a new crux-setup.conf. |
| Connect fails after about 30 seconds, and the message mentions port 8887. | The handset can't reach the Crux agent on the server for key negotiation. | Check that the handset has a working internet connection. On the server, check that TCP 8887 and UDP 51820 are open, that the agent is running, and that PUBLIC_NAME has no AAAA record. If you just removed an AAAA record, force-stop the Crux app on the handset and restart ATAK. |
| The pane stays on Requesting VPN permission… and no permission prompt appears. | Key negotiation failed after the permission step. The pane shows the last status that it set. | Follow the previous row. |
| The tunnel keeps dropping. | Another VPN app on the handset is taking the VPN connection. Android allows only one at a time. | Turn off or remove the other VPN app. |
| ATAK asks you to sign in to the TAK Server. | The tunnel isn't connected yet, so ATAK can't reach the server. If the tunnel is connected, the data package didn't import. | Dismiss the prompt and check the Crux pane. If it doesn't show Connected, connect the tunnel and wait, because ATAK retries on its own. If it shows Connected, import the data package again. |
| The dot next to the server connection stays red. | The tunnel isn't connected, or ATAK hasn't retried yet. | Check that the Crux pane shows Connected, then wait 30 seconds. |
| ATAK reports that the TAK Server's identity could not be verified. | The data package was built with TAK Server's own make-connection-package.sh, so ATAK finds no certificates in it. |
Rebuild the package with make-tak-package.sh, as described in Prepare a handset's files, and import it again. |
ATAK reports hostname in certificate didn't match. |
The data package points at an IP address, or at a name that the server certificate doesn't carry. | Rebuild the package with TUNNEL_NAME, and verify the server to confirm that the certificate lists that name. |
| The handset connects to the TAK Server but has no permissions. | No TAK user matches the name on the handset's certificate. | Create a TAK user with exactly the certificate's name, including capitalization. |
If the problem isn't listed, tap Diagnostic Logs in the Crux pane, tap Copy, and send the copied report to your administrator.
On the server
The following problems show up on the TAK Server:
| What you see | Why | What to do |
|---|---|---|
ATAK reports SSL handshake failure. /opt/tak/logs/takserver-messaging.log shows "this.nettyContext" is null and Certificate error: peer not verified for port 8089. The web console on port 8443 still works. |
The server has one vCPU. TAK Server 5.8 can't complete a TLS handshake on port 8089 with a single core. The certificates are fine. | Resize the server to at least 2 vCPU. To confirm the cause before you resize, run sudo sed -i '5s#^java #java -XX:ActiveProcessorCount=2 #' /opt/tak/takserver-messaging.sh, then sudo systemctl restart takserver-messaging, and connect again. |
The TAK Server log shows password authentication failed for user "martiuser". |
The database password and the one in CoreConfig.xml differ. |
Find the password with sudo grep -o 'password="[^"]*"' /opt/tak/CoreConfig.xml, set the database role to it with sudo -u postgres psql -c "ALTER ROLE martiuser WITH PASSWORD 'VALUE_FROM_CORECONFIG';", then restart TAK Server. |
TAK Server doesn't start, and the log shows loadKeyPair returned null. |
The certificate files are owned by root. | Run sudo chown -R tak:tak /opt/tak/certs, then restart TAK Server. |
makeCert.sh stops, or fails with invalid null input. |
The client certificate's .jks and .p12 files already exist, and the script is waiting on a prompt that you can't see. |
Delete both files, then run the script again. |
| TAK Server rejects a handset's client certificate. | CoreConfig.xml still points at the default truststore, which holds only the root CA. |
Point truststoreFile at the intermediate CA's truststore, which holds both CAs, as described in Configure CoreConfig.xml. |
Port 8089 opens but ports 8443 and 8446 never do, and takserver-api.log shows the trustAnchors parameter must be non-empty. |
The <tls> element inside <federation-server> in CoreConfig.xml still has the default passwords. |
Set keystorePass and truststorePass in both <tls> elements, as described in Configure CoreConfig.xml, then restart TAK Server. |
/opt/tak/CoreConfig.xml doesn't exist. |
TAK Server writes the file the first time it starts, and the package doesn't start the service. | Run sudo systemctl enable takserver, then sudo systemctl start takserver. |
| The TAK Server ports aren't open after a restart. | Startup takes a few minutes, and the ports open only when it finishes. | Wait a few minutes, then check again. |
Quarantine and release
The following problems show up when you use Crux Admin:
| What you see | Why | What to do |
|---|---|---|
| Crux Admin fails to sign in, and the account's password is correct. | The Api value in admin-setup.conf ends in /api/g, which refuses admin sign-ins, or the account uses multi-factor authentication. |
End the Api value in /api, and use an org-admin account without multi-factor authentication. |
| A quarantined handset still shows Connected. | The pane doesn't change during a quarantine. The tunnel is down, and the byte count no longer moves. | Nothing. Watch the device's marker go stale on another handset's map to confirm the quarantine. |
| On the server, a quarantined handset still appears in the list of open connections. | The connection was open before the quarantine, and the server takes a while to close it. No data passes. | Check the handshake time for the handset's peer in sudo wg show crux0 instead. |
| A handset is still down 5 minutes after release. | The handset's tunnel didn't recover on its own. | Check that the device is released. Then, on the handset, go to Android Settings > Apps > Crux > Force stop, restart ATAK, and tap Connect in the Crux pane. |