Prepare a handset's files
Each handset needs two files of its own before anyone can install it: a crux-setup.conf file,
which carries its Crux identity and tunnel, and a TAK Server data package, which carries its
client certificate. This guide produces both. You need org-admin access to Crux and a shell on
the TAK Server.
Placeholders
The steps in this guide use the following placeholders:
| Placeholder | Meaning | Example |
|---|---|---|
NAME |
The handset's name. It becomes the Crux host, the TAK user, and the client certificate. | handset-01 |
PUBLIC_NAME |
Public DNS name of the TAK Server | tak.example.com |
TUNNEL_NAME |
DNS name that resolves to the server's tunnel address | tak-crux.example.com |
PW |
The certificate password chosen when the TAK Server was set up | Kept in your vault |
TOKEN |
The Cloudsmith entitlement token that Sirius issued to you | |
REALM, REALM_USER, REALM_PASSWORD |
Your SKA-Platform realm and the account that devices register with | From Admin > SKA-Platform |
Before you begin
Make sure that you have the following:
- A TAK Server set up as described in Set up a TAK Server, including the two Sirius scripts.
-
make-setup-conf.sh, which you download from Cloudsmith with the following command:curl -fsSLO https://dl.cloudsmith.io/TOKEN/sirius/crux-suave-bunny/generic/download/tools/make-setup-conf.sh -
A name for the handset.
Caution
Use the same NAME for the Crux host, the TAK user, and the client certificate, with no
spaces and identical capitalization. If the names differ, the handset connects and then has
no permissions.
1. Create the host in Crux
- In the Crux web UI, go to Hosts and select add.
- Select Simple client.
- Enter
NAMEas the host's name. - Choose the TAK Server's host and its
crux0interface. - Select Customize WireGuard addresses, and check that no existing host already has either address.
- Select Create.
Crux creates the host, its crux0 interface, and an endpoint in each direction. The server's
agent picks up the new peer the next time it polls.
2. Download the Crux setup file
Note
The setup code in this file is single-use and expires. Download the file when you're ready to send it, not days ahead.
- Empty your browser's download folder of any earlier
crux-setup.conf. The file always has the same name, and a browser that finds one there saves the new one ascrux-setup (1).conf. - Open the handset's host page and select Set Up > Advanced Options.
- Select Download crux-setup.conf.
3. Download the WireGuard configuration
Warning
This file contains the interface's private key. Don't keep copies of it after step 5.
- On the handset's host page, open the
crux0interface and select Configuration. - Select Concatenate multi-line fields.
- Select Download. The file takes the interface's name,
crux0.conf. - Open
crux0.confand check thatEndpointisPUBLIC_NAMEand not an IP address. The endpoint is also the server's identity during key negotiation, so with an address the handshake never completes. - Check that the file has no
PresharedKeyline. A stored key makes the tunnel run on that fixed key and never use the SKA-Platform.
4. Write the SKA-Platform file
You write this file by hand, once for each realm, and reuse it for every handset. Every value except the password is shown in the Crux web UI under Admin > SKA-Platform.
Save the following as ska.conf, with your realm's values. An annotated template, ska.conf.example, is in the
downloads:
[SKA]
Domain = ska.quantum.cloud
Region = ska
[SKA.Registration]
Realm = REALM
Username = REALM_USER
Password = REALM_PASSWORD
Mode = OTA_QUANTUM
5. Merge the three files
The plugin reads one file, so merge the three. The script also stops with an error if the WireGuard configuration has either problem from step 3.
-
Make a folder for the handset's files:
mkdir NAME -
Merge the files into it. Write the result to the new folder, because the output has the same name as the first input:
sh make-setup-conf.sh crux-setup.conf ska.conf crux0.conf > NAME/crux-setup.conf
6. Create the TAK user and certificate
Caution
Run the certificate commands as the tak user, with CAPASS and PASS set. The astak
helper in the first step does both. Commands run as root leave files that TAK Server can't
read.
-
On the TAK Server, go to the certificate directory and define the helper, with the same subject fields that the server's certificates use:
cd /opt/tak/certs astak() { sudo -u tak env STATE=STATE CITY=CITY \ ORGANIZATION='ORG' ORGANIZATIONAL_UNIT=OU \ CAPASS='PW' PASS='PW' "$@" } -
Create the TAK user. The handset never uses this password, so you can reuse
PW:sudo java -jar /opt/tak/utils/UserManager.jar usermod -p 'PW' NAME -
Make the client certificate:
astak ./makeCert.sh client NAME
7. Build the data package
-
Build the package. Give it the tunnel name, never an IP address, because ATAK ignores IP addresses in the server certificate. The script checks that the password opens both certificate files before it writes anything:
astak ./make-tak-package.sh \ -s TUNNEL_NAME \ -t files/truststore-intermediate-signing.p12 \ -c files/NAME.p12 \ -n 'TAK via Crux' -o /tmp/NAME-cert.zip -
Optional: List the package. Both
.p12files are undercert/:unzip -l /tmp/NAME-cert.zip -
Copy
/tmp/NAME-cert.zipinto the handset's folder, besidecrux-setup.conf.
8. Send the files
Warning
crux-setup.conf and the data package contain private keys and passwords. Send them over a
channel that you'd trust with a credential, separately from the plugin download link.
Send the person who installs the handset the following:
- The plugin download link,
https://dl.cloudsmith.io/TOKEN/sirius/crux-suave-bunny/generic/download/crux/app-civ-release.apk, with your token in place ofTOKEN. crux-setup.conffrom the handset's folder.NAME-cert.zip.- A link to Install on a handset.
Each pair of files works on one handset only. If the installer loads them on a second handset, neither handset works, and you need to prepare both again.