Skip to content

Set up a TAK Server

This guide takes a fresh Ubuntu 24.04 machine to a working TAK Server that handsets reach through a Crux tunnel. You need root on the machine. Allow about half a day the first time.

The guide assumes that your own Crux deployment is already running and has an organization for this work. Installing Crux itself is outside the scope of this guide.

What you build

You build one server that runs three components:

  • TAK Server 5.8, which ATAK on each handset connects to.
  • The Crux agent, which registers the server with Crux, runs its WireGuard interface crux0, and answers key negotiation from handsets on TCP 8887.
  • PostgreSQL 18, which is TAK Server's database.

Handsets reach TAK Server only through the tunnel.

Placeholders

The commands in this guide use the following placeholders. Decide the values before you begin:

Placeholder Meaning Example
CRUX_URL Address of your Crux web UI https://crux.example.com
PUBLIC_NAME Public DNS name of the server tak.example.com
TUNNEL_NAME DNS name that resolves to the tunnel address tak-crux.example.com
TUNNEL_IP The server's address on crux0, which Crux assigns 10.10.0.1
CA_NAME Name for your certificate authority example-tak-ca
PW One password for the CA, the keystores, and TAK users. It needs at least 15 characters, with an uppercase letter, a lowercase letter, a digit, and a symbol. Generate one and keep it in your vault
STATE, CITY, ORG, OU Certificate subject fields. The country is always US, because TAK Server's scripts fix it. London, London, Example Ltd, Ops
REALM, REALM_USER, REALM_PASSWORD Your SKA-Platform realm and the account that devices register with From Admin > SKA-Platform
TOKEN The Cloudsmith entitlement token that Sirius issued to you
ADMIN_NAME, ADMIN_PASSWORD A TAK Server admin user for the web console takadmin

Before you begin

Make sure that you have the following:

  • An Ubuntu 24.04 server with a public IPv4 address, at least 2 vCPU, and at least 8 GiB of RAM. At 8 GiB, TAK Server warns about memory at startup. It runs, but add memory before you connect many clients. The 2 vCPU minimum is strict: on a single-core server, every handset connection on port 8089 fails. For the symptoms, see Troubleshooting.
  • A tak.gov account, to download takserver_5.8-RELEASE84_all.deb.
  • Org-admin access to your organization in the Crux web UI at CRUX_URL, with the SKA-Platform configured under Admin > SKA-Platform.
  • A network path from the server, and from every handset, to CRUX_URL. The Crux agent and the plugin both register with Crux and poll it.
  • Your SKA-Platform realm name, and the username and password that devices register with.
  • Your Cloudsmith entitlement token, to download the two Sirius scripts in step 4.
  • Control of DNS for PUBLIC_NAME and TUNNEL_NAME.

Open the following inbound ports on the server's firewall or security group:

Port Purpose Allow from
UDP 51820 The WireGuard tunnel Anywhere, because handsets roam
TCP 8887 Key negotiation with the Crux agent Anywhere, because handsets roam
TCP 22 SSH Your admin addresses
TCP 8443 TAK Server web console Your admin addresses

Caution

Don't open ports 8089 or 8446 to the internet. Handsets use those ports through the tunnel.

If the server also runs a host-based firewall, see Firewall Rules for example rulesets.

1. Set up DNS

Caution

Don't create an AAAA record for PUBLIC_NAME. The Crux agent listens for key negotiation on IPv4 only, and Android prefers IPv6 whenever it's offered. With an AAAA record, handsets on some networks dial an address that nothing answers on, and Connect fails.

  1. Create an A record for PUBLIC_NAME that points at the server's public IPv4 address.
  2. Confirm that there's no AAAA record. The following command prints nothing:

    dig +short AAAA PUBLIC_NAME
    

You create the record for TUNNEL_NAME in step 3, after Crux assigns the tunnel address.

2. Install PostgreSQL 18 and TAK Server

Ubuntu 24.04 ships PostgreSQL 16, but TAK Server 5.8 needs 18, which comes from the PostgreSQL project's own repository.

Caution

Install only the takserver package. The takserver-database package is for a separate database host, and installing both on one machine makes the install abort.

  1. Add the PostgreSQL repository, then install the database and TAK Server's other dependencies:

    sudo apt-get update
    sudo apt-get install -y ca-certificates curl gnupg
    sudo curl -fsSL -o /etc/apt/keyrings/pgdg.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
    echo "deb [signed-by=/etc/apt/keyrings/pgdg.asc] https://apt.postgresql.org/pub/repos/apt noble-pgdg main" |
      sudo tee /etc/apt/sources.list.d/pgdg.list
    sudo apt-get update
    sudo apt-get install -y postgresql-18 postgresql-18-postgis-3 openjdk-17-jdk bc openssl zip unzip
    
  2. Check that PostgreSQL 18 owns port 5432. TAK Server connects by port, not by cluster name, so if another version holds 5432, remove that cluster first.

    pg_lsclusters
    
  3. Install TAK Server:

    sudo apt-get install -y ./takserver_5.8-RELEASE84_all.deb
    
  4. Enable and start TAK Server. The package installs the service but doesn't start it:

    sudo systemctl daemon-reload
    sudo systemctl enable takserver
    sudo systemctl start takserver
    

Note

TAK Server writes /opt/tak/CoreConfig.xml the first time it starts. Until you finish steps 4 to 6, it has no certificates and can't open its ports.

3. Install the Crux agent

Note

The setup code in crux-setup.conf is single-use and expires, so download the file right before you use it.

  1. In the Crux web UI at CRUX_URL, go to Hosts, select add, and create a host for the server with a crux0 interface.
  2. Note the tunnel address that Crux assigns. That address is your TUNNEL_IP.
  3. On the host's page, select Set Up.
  4. Select Download crux-setup.conf.
  5. Select Download crux-agent-ska-latest.tar.gz.
  6. Copy crux-setup.conf and the tarball to the server.
  7. On the server, write the agent's SKA-Platform registration file by hand. Save the following as crux-registration.conf, with your realm's values:

    [SKA.Registration]
    Realm = REALM
    Username = REALM_USER
    Password = REALM_PASSWORD
    
  8. Move both files to the agent's configuration directory:

    sudo mkdir -p /etc/crux
    sudo mv crux-registration.conf crux-setup.conf /etc/crux/
    
  9. Install the agent, and enter y at each prompt:

    tar xf crux-agent-ska-*.tar.gz
    cd crux-agent-ska-*/
    sudo ./install.sh --install
    
  10. Stop systemd-networkd from clearing the agent's routes. In /etc/systemd/networkd.conf, set the following:

    ManageForeignRoutingPolicyRules=no
    ManageForeignRoutes=no
    
  11. Reboot the server.

  12. Check the agent:

    systemctl status crux-agent
    sudo /opt/crux-agent/bin/crux-agent --test
    sudo wg show crux0
    sudo ss -ltnup | grep -E '8887|51820'
    

    The Crux web UI shows the host as Active, crux0 has TUNNEL_IP, and the agent listens on TCP 8887.

  13. Create an A record for TUNNEL_NAME that points at TUNNEL_IP. You can use a public record, because only hosts on the tunnel can route to that address.

Note

Handsets connect to TUNNEL_NAME, never to the address. ATAK checks the name it dials against the DNS names in the server certificate and ignores IP addresses in it.

4. Install the two Sirius scripts

TAK Server's own scripts can't put two DNS names in the server certificate, and they build data packages that ATAK can't read. Two Sirius scripts do those two jobs instead. They sit beside TAK Server's scripts and change nothing that TAK Server ships, so a TAK Server upgrade doesn't affect them.

  1. Download both scripts from Cloudsmith:

    base=https://dl.cloudsmith.io/TOKEN/sirius/crux-suave-bunny/generic/download/tools
    curl -fsSLO "$base/make-tak-server-cert.sh"
    curl -fsSLO "$base/make-tak-package.sh"
    
  2. Install them in the certificate directory:

    sudo install -o tak -g tak -m 755 make-tak-server-cert.sh make-tak-package.sh /opt/tak/certs/
    
  3. Optional: Run each script's self-test. Each prints selftest OK:

    sh /opt/tak/certs/make-tak-server-cert.sh --selftest
    sh /opt/tak/certs/make-tak-package.sh --selftest
    

5. Make the certificates

Caution

Run every certificate command as the tak user. If you run the commands as root, they leave files that TAK Server can't read, and the server doesn't start. To recover, run sudo chown -R tak:tak /opt/tak/certs.

Caution

The scripts take the subject fields and both passwords from the environment. If CAPASS and PASS aren't set, TAK Server's own scripts use a default password without telling you.

The astak helper in the first step handles both.

  1. Go to the certificate directory and define the helper. The helper lasts only for the current shell, so define it again in a new one:

    cd /opt/tak/certs
    astak() {
      sudo -u tak env STATE=STATE CITY=CITY \
        ORGANIZATION='ORG' ORGANIZATIONAL_UNIT=OU \
        CAPASS='PW' PASS='PW' "$@"
    }
    
  2. Make the root CA:

    astak ./makeRootCa.sh --ca-name CA_NAME
    
  3. Make the intermediate CA. The script appends -signing to the name, so you get intermediate-signing-signing.jks and truststore-intermediate-signing.jks.

    astak ./makeCert.sh ca intermediate-signing
    
  4. When the script asks whether this new CA should sign future server and client certificates, answer y. The intermediate CA then signs every certificate that you make in the following steps. If you answer n, the root CA keeps signing, and the rest of this guide still works, because the truststore from this step holds both CAs.

  5. Make the server certificate. The script prints the keystore that it wrote and the names in the certificate:

    astak ./make-tak-server-cert.sh -i TUNNEL_IP PUBLIC_NAME TUNNEL_NAME
    

Note

The script doesn't overwrite an existing certificate. Before you re-issue the server certificate, delete files/PUBLIC_NAME.key, .pem, .p12, and .jks.

6. Configure CoreConfig.xml

  1. Copy the server keystore to the filename that CoreConfig expects. Repeat this whenever you re-issue the server certificate.

    sudo -u tak cp files/PUBLIC_NAME.jks files/takserver.jks
    
  2. Open /opt/tak/CoreConfig.xml. It has two <tls> elements, one inside <security> and one inside <federation-server>.

  3. In both <tls> elements, set keystorePass and truststorePass to PW. If you change only the first, the web console never starts.
  4. In the <tls> element inside <security>, point the truststore at the intermediate CA's, which holds both the root and the intermediate. The default truststore holds only the root, so if you leave it, TAK Server rejects client certificates that the intermediate CA signed.

    truststoreFile="certs/files/truststore-intermediate-signing.jks"
    
  5. Check that the file is still valid XML. The following command prints nothing:

    python3 -c 'import xml.etree.ElementTree as ET; ET.parse("/opt/tak/CoreConfig.xml")'
    
  6. Restart TAK Server and give it a few minutes. Ports 8089, 8443, and 8446 open only when startup finishes.

    sudo systemctl restart takserver
    

7. Verify the server

On the server, check the certificate that TAK Server presents on the tunnel name:

echo | openssl s_client -connect TUNNEL_NAME:8089 -servername TUNNEL_NAME 2>/dev/null |
  openssl x509 -noout -subject -ext subjectAltName

The output lists both PUBLIC_NAME and TUNNEL_NAME as DNS names.

Optional: Access the web console

The web console on port 8443 accepts only a client certificate.

  1. Create an admin user. The password needs at least 15 characters, with an uppercase letter, a lowercase letter, a digit, and a symbol.

    sudo java -jar /opt/tak/utils/UserManager.jar usermod -A -p 'ADMIN_PASSWORD' ADMIN_NAME
    
  2. Make a client certificate for that user, with the astak helper from step 5:

    astak ./makeCert.sh client ADMIN_NAME
    
  3. Import files/ADMIN_NAME.p12 into your browser. The import password is PW.

What's next

The server is ready for handsets. For each one, follow Prepare a handset's files. If something on this page didn't work, see Troubleshooting.