MainConfig Configuration

Overview

The MainConfig class is the central configuration system for FreeTAKServer. It provides a singleton instance that manages all server configuration through multiple sources:

Default values
YAML configuration file
Environment variables

Configuration values are loaded in the following priority order (lowest to highest):

Built-in defaults
YAML configuration file (FTSConfig.yaml)
Environment variables (highest priority)

Configuration Methods

FreeTAKServer supports three methods for configuration:

YAML Configuration File

The default configuration file location is /opt/fts/FTSConfig.yaml. You can override this with the FTS_CONFIG_PATH environment variable.

System:
  FTS_NODE_ID: "my-custom-node-id"
  FTS_MAINLOOP_DELAY: 100
  FTS_CONNECTION_MESSAGE: "Welcome to my FreeTAKServer"
  FTS_DATABASE_TYPE: "SQLite"
  FTS_OPTIMIZE_API: true

Addresses:
  FTS_COT_PORT: 8087
  FTS_SSLCOT_PORT: 8089
  FTS_API_PORT: 19023
  FTS_FED_PORT: 9000
  FTS_API_ADDRESS: "0.0.0.0"

Filesystem:
  FTS_PERSISTENCE_PATH: "/opt/fts"
  FTS_COT_TO_DB: true
  FTS_DB_PATH: "/opt/fts/FTSDataBase.db"
  FTS_LOG_LEVEL: "info"

Certs:
  FTS_SERVER_KEYDIR: "/opt/fts/certs/server.key"
  FTS_SERVER_PEMDIR: "/opt/fts/certs/server.pem"
  FTS_CADIR: "/opt/fts/certs/ca.pem"

Environment Variables

All configuration options can be set via environment variables. Environment variables override YAML settings.

export FTS_COT_PORT=8087
export FTS_API_PORT=19023
export FTS_LOG_LEVEL="debug"

Programmatic Access

from FreeTAKServer.core.configuration.MainConfig import MainConfig

config = MainConfig.instance()

# Read configuration
port = config.CoTServicePort
api_port = config['APIPort']  # Dictionary syntax also supported

# Write configuration (if not readonly)
config.LogLevel = "debug"
config['SaveCoTToDB'] = False

System Configuration

Core system settings that control server behavior.

version

string

default:"FreeTAKServer-2.2.1"

Server version information (read-only)

APIVersion

string

default:"3"

TAK API version supported (read-only)

nodeID

string

default:"auto-generated"

Unique identifier for this FreeTAKServer node. Auto-generated as 32-character alphanumeric string if not specified.Environment variable: FTS_NODE_ID

SecretKey

string

default:"vnkdjnfjknfl1232#"

Secret key used for cryptographic operations and session management. Change this in production!Environment variable: FTS_SECRET_KEY

OptimizeAPI

boolean

default:"true"

Enable API optimizations for better performanceEnvironment variable: FTS_OPTIMIZE_API

MainLoopDelay

integer

default:"100"

Number of milliseconds to wait between each iteration of the main event loop.

Decreasing this value increases CPU usage and server performance
Increasing this value decreases CPU usage and server performance

Environment variable: FTS_MAINLOOP_DELAY

DataReceptionBuffer

integer

default:"1024"

Buffer size in bytes for receiving data from clientsEnvironment variable: FTS_DATA_RECEPTION_BUFFER

MaxReceptionTime

integer

default:"4"

Maximum time in seconds to wait for data receptionEnvironment variable: FTS_MAX_RECEPTION_TIME

LogLevel

string

default:"info"

Logging level for the server. Valid values: debug, info, warning, error, criticalEnvironment variable: FTS_LOG_LEVEL

ConnectionMessage

string

Message sent to clients upon successful connection. Set to None to disable.Environment variable: FTS_CONNECTION_MESSAGE

EmergencyRadius

integer

default:"0"

Radius in meters within which users will receive emergency notifications. Set to 0 for unlimited range.Environment variable: FTS_EMERGENCY_RADIUS

Network Configuration

Network addresses and port settings for various services.

CoTServicePort

integer

default:"8087"

TCP port for unencrypted CoT (Cursor on Target) serviceEnvironment variable: FTS_COT_PORT

SSLCoTServicePort

integer

default:"8089"

TCP port for SSL/TLS encrypted CoT serviceEnvironment variable: FTS_SSLCOT_PORT

HTTPTakAPIPort

integer

default:"8080"

HTTP port for TAK API service (unencrypted)Environment variable: FTS_HTTP_TAK_API_PORT

HTTPSTakAPIPort

integer

default:"8443"

HTTPS port for TAK API service (encrypted)Environment variable: FTS_HTTPS_TAK_API_PORT

APIPort

integer

default:"19023"

Port for the REST API serviceEnvironment variable: FTS_API_PORT

APIIP

string

default:"0.0.0.0"

IP address for the REST API service to bind to. Use 0.0.0.0 to listen on all interfaces.Environment variable: FTS_API_ADDRESS

FederationPort

integer

default:"9000"

Port for federation serviceEnvironment variable: FTS_FED_PORT

DataPackageServiceDefaultIP

string

default:"auto-detected"

IP address used for data package service. Auto-detected by default. Must be set correctly for private data packages to work.Environment variable: FTS_DP_ADDRESS

UserConnectionIP

string

default:"auto-detected"

IP address that clients should use to connect. Auto-detected by default. Should match the IP used in TAK device connection settings.Environment variable: FTS_USER_ADDRESS

CLIIP

string

default:"127.0.0.1"

IP address for CLI access

AllowCLIIPs

list

default:"[127.0.0.1]"

List of IP addresses allowed to access the CLI interfaceEnvironment variable: FTS_CLI_WHITELIST (colon or comma separated)

Routing and Integration

Configuration for the internal message routing and integration system.

NumRoutingWorkers

integer

default:"3"

Number of routing worker processes to spawn for handling messagesEnvironment variable: FTS_NUM_ROUTING_WORKERS

RoutingProxySubscriberPort

integer

default:"19030"

Port for routing proxy to subscribe to requestsEnvironment variable: FTS_ROUTING_PROXY_SUBSCRIBE_PORT

RoutingProxySubscriberIP

string

default:"127.0.0.1"

IP address for routing proxy subscriberEnvironment variable: FTS_ROUTING_PROXY_SUBSCRIBE_IP

RoutingProxyPublisherPort

integer

default:"19032"

Port for routing proxy to publish responsesEnvironment variable: FTS_ROUTING_PROXY_PUBLISHER_PORT

RoutingProxyPublisherIP

string

default:"127.0.0.1"

IP address for routing proxy publisherEnvironment variable: FTS_ROUTING_PROXY_PUBLISHER_IP

RoutingProxyRequestServerPort

integer

default:"19031"

Port for routing proxy to send requests to workersEnvironment variable: FTS_ROUTING_PROXY_SERVER_PORT

RoutingProxyRequestServerIP

string

default:"127.0.0.1"

IP address for routing proxy request serverEnvironment variable: FTS_ROUTING_PROXY_SERVER_IP

IntegrationManagerPullerPort

integer

default:"19033"

Port for integration manager to receive worker responsesEnvironment variable: FTS_INTEGRATION_MANAGER_PULLER_PORT

IntegrationManagerPullerAddress

string

default:"127.0.0.1"

Address for integration manager pullerEnvironment variable: FTS_INTEGRATION_MANAGER_PULLER_ADDRESS

IntegrationManagerPublisherPort

integer

default:"19034"

Port for integration manager to publish messagesEnvironment variable: FTS_INTEGRATION_MANAGER_PUBLISHER_PORT

IntegrationManagerPublisherAddress

string

default:"127.0.0.1"

Address for integration manager publisherEnvironment variable: FTS_INTEGRATION_MANAGER_PUBLISHER_ADDRESS

Filesystem Paths

Paths for data persistence, logs, and certificates.

persistencePath

string

default:"/opt/fts"

Root directory for all FreeTAKServer persistent dataEnvironment variable: FTS_PERSISTENCE_PATH

DBFilePath

string

default:"/opt/fts/FTSDataBase.db"

Path to the SQLite database fileEnvironment variable: FTS_DB_PATH

SaveCoTToDB

boolean

default:"true"

Whether to save Cursor on Target (CoT) messages to the databaseEnvironment variable: FTS_COT_TO_DB

LogFilePath

string

default:"/opt/fts/Logs"

Directory for server log filesEnvironment variable: FTS_LOGFILE_PATH

DataPackageFilePath

string

default:"/opt/fts/FreeTAKServerDataPackageFolder"

Directory for storing uploaded data packagesEnvironment variable: FTS_DATAPACKAGE_PATH

certsPath

string

default:"/opt/fts/certs"

Directory containing SSL/TLS certificatesEnvironment variable: FTS_CERTS_PATH

ClientPackages

string

default:"/opt/fts/certs/clientPackages"

Directory for backing up client certificate packagesEnvironment variable: FTS_CLIENT_PACKAGES_PATH

EnterpriseSyncPath

string

default:"/opt/fts/enterprise_sync"

Directory for TAK Enterprise Sync data

ExCheckMainPath

string

default:"/opt/fts/ExCheck"

Root directory for ExCheck (checklist) dataEnvironment variable: FTS_EXCHECK_PATH

ExCheckFilePath

string

default:"/opt/fts/ExCheck/template"

Directory for ExCheck templatesEnvironment variable: FTS_EXCHECK_TEMPLATE_PATH

ExCheckChecklistFilePath

string

default:"/opt/fts/ExCheck/checklist"

Directory for ExCheck checklistsEnvironment variable: FTS_EXCHECK_CHECKLIST_PATH

MainPath

string

default:"auto-detected"

Root path of the FreeTAKServer installationEnvironment variable: FTS_MAINPATH

UserPersistencePath

string

default:"/opt/fts/user_persistence.txt"

Path to user persistence file

Component Paths

Configuration for locating core and extended components.

CoreComponentsPath

string

default:"{MainPath}/core"

Path to core componentsEnvironment variable: FTS_CORE_COMPONENTS_PATH

CoreComponentsImportRoot

string

default:"FreeTAKServer.core"

Import root for core componentsEnvironment variable: FTS_CORE_COMPONENTS_IMPORT_ROOT

InternalComponentsPath

string

default:"{MainPath}/components/core"

Path to internal componentsEnvironment variable: FTS_INTERNAL_COMPONENTS_PATH

InternalComponentsImportRoot

string

default:"FreeTAKServer.components.core"

Import root for internal componentsEnvironment variable: FTS_INTERNAL_COMPONENTS_IMPORT_ROOT

ExternalComponentsPath

string

default:"{MainPath}/components/extended"

Path to external/extended componentsEnvironment variable: FTS_EXTERNAL_COMPONENTS_PATH

ExternalComponentsImportRoot

string

default:"FreeTAKServer.components.extended"

Import root for external componentsEnvironment variable: FTS_EXTERNAL_COMPONENTS_IMPORT_ROOT

Example Configurations

Development Setup

System:
  FTS_LOG_LEVEL: "debug"
  FTS_MAINLOOP_DELAY: 50
  FTS_CONNECTION_MESSAGE: "Development Server"

Addresses:
  FTS_COT_PORT: 8087
  FTS_API_PORT: 19023
  FTS_API_ADDRESS: "127.0.0.1"

Filesystem:
  FTS_PERSISTENCE_PATH: "./dev_data"
  FTS_COT_TO_DB: true

Production Setup

System:
  FTS_SECRET_KEY: "your-random-secret-key-here"
  FTS_NODE_ID: "production-fts-01"
  FTS_LOG_LEVEL: "info"
  FTS_OPTIMIZE_API: true

Addresses:
  FTS_COT_PORT: 8087
  FTS_SSLCOT_PORT: 8089
  FTS_API_PORT: 19023
  FTS_API_ADDRESS: "0.0.0.0"
  FTS_USER_ADDRESS: "your-public-ip"
  FTS_DP_ADDRESS: "your-public-ip"

Filesystem:
  FTS_PERSISTENCE_PATH: "/opt/fts"
  FTS_COT_TO_DB: true

Certs:
  FTS_SERVER_KEYDIR: "/opt/fts/certs/server.key"
  FTS_SERVER_PEMDIR: "/opt/fts/certs/server.pem"
  FTS_CADIR: "/opt/fts/certs/ca.pem"

Docker/Container Setup

docker run -d \
  -e FTS_COT_PORT=8087 \
  -e FTS_API_PORT=19023 \
  -e FTS_LOG_LEVEL=info \
  -e FTS_PERSISTENCE_PATH=/data \
  -e FTS_USER_ADDRESS=192.168.1.100 \
  -v /host/fts-data:/data \
  -p 8087:8087 \
  -p 19023:19023 \
  freetakteam/freetakserver

Configuration Validation

FreeTAKServer validates paths specified in configuration to ensure they are accessible and writable. If a path cannot be accessed, the server will exit with an error message.

Path Sanitization

All paths ending with PATH or DIR in the YAML configuration are automatically sanitized and validated:

Normalized to prevent directory traversal
Checked for existence
Checked for write permissions

Best Practices

Always change the default SecretKey in production environments. Use a cryptographically random string.

Set DataPackageServiceDefaultIP and UserConnectionIP to your server’s public IP address or domain name for proper data package functionality.

The MainLoopDelay setting directly impacts CPU usage vs. responsiveness. Test different values to find the right balance for your deployment.

Use environment variables for sensitive configuration like secret keys
Keep YAML configuration files outside the web root
Regularly back up your persistence path (/opt/fts by default)
Use appropriate log levels: debug for development, info or warning for production
Ensure all paths have proper filesystem permissions

Get Started

Core Concepts

Guides

Configuration

MainConfig Configuration

Overview

Configuration Methods

YAML Configuration File

Environment Variables

Programmatic Access

System Configuration

Network Configuration

Routing and Integration

Filesystem Paths

Component Paths

Example Configurations

Development Setup

Production Setup

Docker/Container Setup

Configuration Validation

Path Sanitization

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

​Overview

​Configuration Methods

​YAML Configuration File

​Environment Variables

​Programmatic Access

​System Configuration

​Network Configuration

​Routing and Integration

​Filesystem Paths

​Component Paths

​Example Configurations

​Development Setup

​Production Setup

​Docker/Container Setup

​Configuration Validation

​Path Sanitization

​Best Practices

Build docs developers (and LLMs) love

Overview

Configuration Methods

YAML Configuration File

Environment Variables

Programmatic Access

System Configuration

Network Configuration

Routing and Integration

Filesystem Paths

Component Paths

Example Configurations

Development Setup

Production Setup

Docker/Container Setup

Configuration Validation

Path Sanitization

Best Practices