Configuration¶
PyTAK configuration can be set in two ways:
- Environment variables — set before running your script
- INI-style config file — typically
config.ini, passed via yourConfigParser
Both methods work identically. Environment variables take precedence.
Example config.ini:
[mytool]
COT_URL = tls://takserver.example.com:8089
PYTAK_TLS_CLIENT_CERT = /etc/pytak/client.pem
DEBUG = 0
Equivalent environment variables:
export COT_URL=tls://takserver.example.com:8089
export PYTAK_TLS_CLIENT_CERT=/etc/pytak/client.pem
export DEBUG=0
Core Parameters¶
COT_URL¶
Default: udp+wo://239.2.3.1:6969 (ATAK Mesh SA multicast, write-only)
The destination for CoT events. Supported URL schemes:
| Scheme | Description |
|---|---|
tcp://host:port |
TCP unicast (plain text) |
tcp+wo://host:port |
TCP write-only (send; drain inbound, do not enqueue) |
tcp+ro://host:port |
TCP read-only (receive only) |
tls://host:port |
TLS unicast (encrypted) |
tls+wo://host:port |
TLS write-only (send; drain inbound, do not enqueue) |
tls+ro://host:port |
TLS read-only (receive only) |
udp://group:port |
UDP multicast (Mesh SA) |
udp://host:port |
UDP unicast |
udp+broadcast://network:port |
UDP broadcast |
udp+wo://host:port |
UDP write-only (no port binding) |
udp+ro://host:port |
UDP read-only (bind to receive; no send socket) |
log://stdout |
Print to stdout (debug) |
log://stderr |
Print to stderr (debug) |
marti://host:port |
TAK Server Marti REST API (TLS) |
marti+http://host:port |
TAK Server Marti REST API (plain HTTP) |
tak://... |
TAK enrollment deep-link (see below) |
Port already in use?
Add the +wo modifier (udp+wo://) to run write-only without binding the port. This lets multiple PyTAK applications share a network interface.
Direction modifiers (+wo / +ro)¶
Append +wo (write-only) or +ro (read-only) to tcp, tls, ssl, or udp schemes. They cannot be combined on the same URL.
| Modifier | Behavior |
|---|---|
+wo |
Transmit CoT only. For UDP, no receive socket is opened. For TCP/TLS, inbound data is read and discarded so the connection stays healthy, but nothing is placed on rx_queue. |
+ro |
Receive CoT only. No TXWorker is started. For UDP, no send socket is opened. |
Send-only gateways (e.g. AISCOT)
Use tls+wo:// when your tool publishes CoT to a TAK Server but does not process inbound events:
+wo / +ro apply to tcp, tls, ssl, and udp only. marti://, wss://, and other schemes are unaffected.
TAK_PROTO¶
Default: 0
TAK Protocol version for CoT output:
| Value | Protocol |
|---|---|
0 |
TAK Protocol v0 — plain XML (default, recommended) |
1 |
TAK Protocol v1 — Protobuf (requires pytak[with_takproto]) |
Protobuf compatibility
TAK Protocol v1 may not work with all TAK clients (notably some versions of iTAK). Stick with TAK_PROTO=0 unless you have a specific need for Protobuf.
DEBUG¶
Default: 0
Set to 1 to enable verbose debug logging.
FTS_COMPAT¶
Default: 0
Set to 1 to enable FreeTAKServer compatibility mode. PyTAK will sleep a random number of seconds between transmissions to avoid FTS's built-in rate-limit / anti-DoS protections.
PYTAK_SLEEP¶
Default: 0 (disabled)
Sleep interval in whole seconds between CoT transmissions. Use instead of FTS_COMPAT for a fixed sleep period.
PYTAK_NO_HELLO¶
Default: False
Set to True to suppress the initial "Hello" CoT event that PyTAK sends when connecting to a TCP or UDP endpoint. Useful for deployments that require a quiet startup.
COT_STALE¶
Default: 120 (2 minutes)
CoT event stale time in seconds. Events older than this are considered expired by TAK clients.
MAX_OUT_QUEUE¶
Default: 100
Maximum number of outgoing CoT events to buffer before dropping the oldest. Increase this if your sender produces bursts faster than the network can absorb them.
MAX_IN_QUEUE¶
Default: 500
Maximum number of incoming CoT events to buffer. Increase this if your receiver is processing events slower than they arrive.
Multicast Parameters¶
PYTAK_MULTICAST_LOCAL_ADDR¶
Default: 0.0.0.0
On systems with multiple network interfaces, specifies which interface IP to use for multicast. Set this to the IP of the interface connected to your TAK network.
PYTAK_MULTICAST_TTL¶
Default: 1
Time-to-live for multicast packets. Increase this if your TAK client is more than one network hop away (e.g. inside a VM or container with an overlay network).
TAK Data Package Support¶
PREF_PACKAGE¶
Requires pytak[with_crypto]
Install with pip install pytak[with_crypto] or apt install python3-cryptography.
Path to a TAK Data Package .zip file containing TAK Server connection settings, TLS certificates, etc. PyTAK will import these settings automatically on startup.
Or pass via command line argument: -p MyServer.zip
tak:// Onboarding URL¶
Requires pytak[with_aiohttp] and pytak[with_crypto]
PyTAK supports TAK enrollment deep-link URLs in the format used by ATAK's QR-code onboarding flow:
Set this as COT_URL (or the TAK_URL environment variable):
CLI usage:
To force a specific WebSocket/Marti port, include it in host=:
What PyTAK does with a tak:// URL:
- Parses the host, username, and token from the URL
- Checks
~/.pytak/certs/for a valid cached certificate - If no valid cert is cached, performs a full CSR → PKCS#12 enrollment against the TAK Server
- Caches the certificate and passphrase to disk
- Automatically sets
COT_URLtowss://<host>:8443/takproto/1by default and configures TLS using the enrolled cert
If the onboarding URL explicitly includes a port in host=, PyTAK uses that port instead. When the explicit port is the TAK streaming port (8089), PyTAK keeps tls://<host>:8089.
Certificates are re-enrolled automatically when they are within 7 days of expiry.
Export onboarding packages (pytak dp)¶
To enroll and write PKCS#12/PEM files plus ATAK and iTAK connection data packages without connecting to the server, use the dp subcommand. See Onboarding packages.
marti:// REST API Transport¶
Requires pytak[with_aiohttp]
Send and receive CoT via the TAK Server Marti REST API instead of a raw TCP/TLS socket:
# TLS (default port 8443)
COT_URL = marti://takserver.example.com:8443
# Plain HTTP
COT_URL = marti+http://takserver.example.com:8080
Additional Marti parameters:
| Parameter | Default | Description |
|---|---|---|
MARTI_COT_UID |
host ID | Client UID used to filter received CoT |
MARTI_POLL_INTERVAL |
5 |
Seconds between polling for new CoT events |
MARTI_POLL_SECONDS_AGO |
30 |
How far back (seconds) to fetch events per poll |
TLS Support¶
PyTAK supports full mutual-TLS (mTLS) connections to TAK Servers. Use tls:// in COT_URL.
Minimum TLS configuration:
The matching CoreConfig.xml stanza on the TAK Server:
Certificate format
All cert and key files must be in unencrypted PEM format, or use a PKCS#12 .p12 file combined with PYTAK_TLS_CLIENT_PASSWORD.
TLS Parameters¶
PYTAK_TLS_CLIENT_CERT¶
Path to the PEM-format client certificate. This file may contain both the certificate and the private key, or the certificate alone (in which case also set PYTAK_TLS_CLIENT_KEY).
PYTAK_TLS_CLIENT_KEY (optional)¶
Path to the PEM-format client private key, if not bundled with PYTAK_TLS_CLIENT_CERT.
PYTAK_TLS_CLIENT_CAFILE (optional)¶
Path to a PEM-format CA trust chain file. Required when the TAK Server uses a private CA that is not in the system trust store.
PYTAK_TLS_CLIENT_PASSWORD (optional)¶
Password for an encrypted private key or a PKCS#12 (.p12) certificate file.
PYTAK_TLS_DONT_VERIFY¶
Default: 0 (verify)
Set to 1 to disable remote certificate verification. Use with caution — this makes the connection vulnerable to man-in-the-middle attacks. A WARNING is printed when enabled.
PYTAK_TLS_DONT_CHECK_HOSTNAME¶
Default: 0 (check)
Set to 1 to disable TLS hostname (CN) verification. A WARNING is printed when enabled.
PYTAK_TLS_SERVER_EXPECTED_HOSTNAME (optional)¶
Expected hostname or Common Name (CN) of the TAK Server certificate. Only used when hostname verification is active.
PYTAK_TLS_CLIENT_CIPHERS (optional)¶
Default: ALL
Colon-separated list of TLS cipher suites. Example for FIPS-only ciphers:
Certificate Enrollment Parameters¶
Requires pytak[with_aiohttp] and pytak[with_crypto]
These parameters trigger automatic certificate enrollment from a TAK Server. Alternatively, use a tak:// URL which handles all of this automatically.
PYTAK_TLS_CERT_ENROLLMENT_USERNAME¶
TAK Server username for certificate enrollment.
PYTAK_TLS_CERT_ENROLLMENT_PASSWORD¶
TAK Server password for certificate enrollment.
PYTAK_TLS_CERT_ENROLLMENT_PASSPHRASE¶
Passphrase to protect the enrolled certificate. If not set, a random passphrase is generated and cached to disk alongside the certificate.