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) |
mqtt://host:port/topic |
MQTT broker (plain text; topic in URL path) |
mqtt+wo://host:port/topic |
MQTT write-only (publish; no subscribe) |
mqtt+ro://host:port/topic |
MQTT read-only (subscribe; no publish) |
mqtts://host:port/topic |
MQTT broker over TLS |
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, udp, mqtt, or mqtts 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, udp, mqtt, and mqtts. marti://, wss://, and other schemes are unaffected.
MQTT URLs¶
MQTT transport requires pytak[with-mqtt] (aiomqtt). The MQTT topic is the URL path after the host (for example, mqtt://broker.example.com:1883/cot publishes and subscribes on topic cot).
Default ports: 1883 for mqtt://, 8883 for mqtts://. Username and password may appear in the URL (mqtt://user:pass@broker:1883/cot) or via the config keys below.
| Key | Default | Description |
|---|---|---|
MQTT_QOS |
0 |
MQTT publish/subscribe QoS level |
MQTT_KEEPALIVE |
60 |
MQTT keepalive interval (seconds) |
MQTT_CLIENT_ID |
pytak@<hostname> |
MQTT client identifier |
MQTT_USERNAME |
(from URL) | Broker username if not in URL |
MQTT_PASSWORD |
(from URL) | Broker password if not in URL |
For mqtts://, TLS uses the same PYTAK_TLS_* parameters as tls:// and wss://.
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.
TAK outage recovery¶
Clients built on pytak.cli() retry transient transport failures in-process by
default. This includes DNS failures, refused connections, timeouts, TLS
transport failures, and a TAK Server closing a WebSocket. Invalid local
configuration remains fatal so a typo does not disappear into a retry loop.
The delay starts at five seconds, doubles after each failed attempt, and is capped at two minutes. Twenty percent jitter keeps a fleet from reconnecting all at once when a shared server returns. A connection that remains healthy for five minutes resets the next delay to five seconds. Queues and network workers are recreated between attempts, so a long outage cannot build an unbounded backlog. PKCS#12 temporary PEM files are removed immediately after each TLS context is loaded.
| Key | Default | Description |
|---|---|---|
PYTAK_RECONNECT |
1 |
Retry transient TAK transport failures in-process |
PYTAK_RECONNECT_INITIAL |
5 |
Initial retry delay, seconds |
PYTAK_RECONNECT_MAX |
120 |
Maximum retry delay, seconds |
PYTAK_RECONNECT_FACTOR |
2 |
Delay multiplier after each failed attempt |
PYTAK_RECONNECT_JITTER |
0.2 |
Random delay variation as a fraction; 0 disables it |
PYTAK_RECONNECT_RESET |
300 |
Healthy-session duration that resets the delay, seconds |
For example, a deliberately slower field deployment can use:
PYTAK_RECONNECT_INITIAL = 15
PYTAK_RECONNECT_MAX = 600
PYTAK_RECONNECT_FACTOR = 2
PYTAK_RECONNECT_RESET = 300
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_LOCAL_ADDRS¶
Default: unset
Comma- or whitespace-separated interface IPv4 addresses for multicast fanout.
PyTAK sends each multicast datagram once through every usable address and joins
the multicast group on each address for receive transports. This setting takes
precedence over PYTAK_MULTICAST_LOCAL_ADDR.
If one listed output disappears, PyTAK keeps the remaining outputs active. The setting only affects multicast; ordinary UDP destinations continue to use the kernel-selected local address.
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.