Configuration Guide¶
This document provides a comprehensive guide to all configuration options available in IDSTower.
Configuration can be specified either through the appsettings.json file or through environment variables when using Docker.
Core Configuration¶
License Configuration¶
Note
As of v3.1.0, the license key is stored in the database and managed via the IDSTower web UI (Settings → License tab) or via the --set-license-key CLI option.
The LicenseKey setting in appsettings.json is deprecated. Existing keys are auto-migrated on first startup.
{
"EncryptionKey": "your-64-character-hex-string"
}
LicenseKey (Deprecated since v3.1.0): License key is now stored in the database. Use the Settings → License tab in the web UI or
--set-license-keyCLI option instead.EncryptionKey (Required, since v2.9.0): A 64-character hexadecimal string used for encrypting sensitive data. Generate using
openssl rand -hex 32
Database Configuration¶
{
"Database": {
"Host": "localhost",
"Port": 3306,
"Name": "idstower",
"Username": "root",
"Password": "your-password",
"CommandTimeout": 120
}
}
Host (Required): Database server hostname or IP address
Port (Optional): Database server port, defaults to 3306
Name (Required): Database name
Username (Required): Database username
Password (Optional): Database password, defaults to empty string
CommandTimeout (Optional, since v2.9.1): Database command timeout in seconds, defaults to 120
Hosting Configuration¶
{
"Hosting": {
"URL": "http://*:8080",
"PathPrefix": "/idstower",
"ExternalUrl": "https://idstower.company.com",
"Certificate": {
"Path": "/path/to/certificate.pfx",
"Password": "cert-password"
}
}
}
URL Configuration¶
URL (Required): The URL where IDSTower will listen for connections.
Important: IDSTower must be accessible from your IDS Hosts, so localhost and 127.0.0.1 are not allowed.
Use an IP address or FQDN that your IDS Hosts can reach.
If using wildcard binding (*), you MUST configure ExternalUrl to specify how Suricata hosts will reach IDSTower.
Without ExternalUrl, Suricata hosts won’t be able to communicate with IDSTower.
Valid examples:
{
"Hosting": {
"URL": "http://*:8080",
"ExternalUrl": "http://192.168.1.10:8080" // Required when using *
}
}
Or with a specific IP (ExternalUrl optional):
{
"Hosting": {
"URL": "http://192.168.1.10:8080" // ExternalUrl not required
}
}
Invalid examples (will be rejected):
http://localhost:8080https://localhost:8443http://127.0.0.1:8080https://127.0.0.1:8443http://*:8080(without ExternalUrl configured)
Other Hosting Options¶
- PathPrefix (Optional): Base path when running behind a reverse proxy (e.g., “/idstower”)
Must start with ‘/’ and not end with ‘/’
Leave empty if not using a path prefix
- ExternalUrl (Optional): The complete URL where users will access IDSTower
Use when IDSTower is accessed through a reverse proxy or load balancer
Should include protocol, host, and any path prefix
- Certificate: HTTPS certificate configuration
Path: Path to the .pfx certificate file
Password: Certificate password
Advanced Settings¶
{
"AdvancedSettings": {
"AnsiblePlaybookBinaryPath": "/usr/bin/ansible-playbook",
"AnsiblePlaybooksPath": "/opt/idstower/playbooks/cluster_setup.yml",
"SSHKeyType": "RSA",
"SSHKeySize": 2048,
"AwsExportsNamePrefix": "IDSTower",
"DisableAuthentication": false,
"EnableAnsibleTaskProfiling": false,
"GeneratedFileCachePath": "/var/cache/idstower",
"GeneratedPayloadWaitSeconds": 30,
"GeneratedPayloadRetryAfterSeconds": 30,
"GeneratedPayloadCacheLifetimeMinutes": 360,
"RulesFetchChunkRows": 1500,
"IndicatorsFetchChunkRows": 50000
}
}
- AnsiblePlaybookBinaryPath: Path to ansible-playbook binary
Default: “/usr/bin/ansible-playbook”
- AnsiblePlaybooksPath: Path to IDSTower Ansible playbooks
Default: “<current_directory>/resources/playbooks/cluster_setup.yml”
- SSHKeyType: Type of SSH key to generate
Allowed values: “RSA”, “ECDSA”
Default: “RSA”
- SSHKeySize: SSH key size in bits
Default: 2048
- AwsExportsNamePrefix: Prefix for AWS exports
Default: “IDSTower”
- DisableAuthentication: Disable built-in authentication
Default: false
- EnableAnsibleTaskProfiling (since v3.1.0): When enabled, Ansible task durations are parsed after each playbook execution and tasks exceeding the slow-task threshold are logged as warnings. Useful for diagnosing performance bottlenecks in Ansible operations. This is always active in Development environment regardless of this setting.
Default: false
- GeneratedFileCachePath (since v3.2.0): Directory where generated payloads (exports, the per-host rules files) are cached on disk. Holds only regenerable content and is wiped on every service start. At the default path you do not need to do anything: the installer, the packages and the Docker images create it, and the systemd unit re-creates it (owned by the service user, mode
0700) before every start, so it is restored automatically if it is ever cleared. If you point this setting at a different directory, you must create that directory yourself and make it writable by the service user — IDSTower reports the problem and refuses to start when the cache directory is unusable. Default: “/var/cache/idstower”
- GeneratedFileCachePath (since v3.2.0): Directory where generated payloads (exports, the per-host rules files) are cached on disk. Holds only regenerable content and is wiped on every service start. At the default path you do not need to do anything: the installer, the packages and the Docker images create it, and the systemd unit re-creates it (owned by the service user, mode
- GeneratedPayloadWaitSeconds (since v3.2.0): How long a host rules-pull request waits for a rules compilation another request already started, before answering
202 Accepted(“compilation still in progress”). Nearly all concurrent pulls are resolved within this window and receive the freshly compiled rules directly. Keep it below your reverse proxy’s read timeout. Exports are unaffected: they always wait for generation to finish. Allowed values: 5–300
Default: 30
- GeneratedPayloadWaitSeconds (since v3.2.0): How long a host rules-pull request waits for a rules compilation another request already started, before answering
- GeneratedPayloadRetryAfterSeconds (since v3.2.0): The
Retry-Afterheader value (in seconds) sent with a202 Acceptedcompilation-in-progress response. The update scripts on the managed hosts honor it before retrying, so this paces the whole fleet centrally. Allowed values: 5–3600
Default: 30
- GeneratedPayloadRetryAfterSeconds (since v3.2.0): The
- GeneratedPayloadCacheLifetimeMinutes (since v3.2.0): How long a generated payload stays servable from the cache before it must be regenerated. Content changes (rule updates, feed imports, export edits) invalidate cached payloads immediately regardless of this setting; this is only the upper bound on reuse.
Allowed values: 5–10080
Default: 360
- RulesFetchChunkRows (since v3.2.0): How many IDS rules each database query fetches while a rules file or rules export is being generated. This bounds IDSTower’s peak memory during generation: lower values use less memory but cost more database round-trips per regeneration. The default is the measured sweet spot on a 20,000-rule corpus; rule rows are heavy (each carries its attributes), hence the small value.
Allowed values: 100–20000
Default: 1500
- IndicatorsFetchChunkRows (since v3.2.0): How many indicators each database query fetches while an indicator file (IP-reputation or dataset lists) is being generated. Same memory/round-trips trade-off as
RulesFetchChunkRows; indicator rows are flat, hence the much larger default, measured on a 1,000,000-indicator corpus. Allowed values: 1000–500000
Default: 50000
- IndicatorsFetchChunkRows (since v3.2.0): How many indicators each database query fetches while an indicator file (IP-reputation or dataset lists) is being generated. Same memory/round-trips trade-off as
Logging Configuration¶
{
"Logging": {
"LogFile": "/var/log/idstower/idstower.log",
"LogLevel": "Information",
"LogTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}"
}
}
- LogFile: Path to log file. One file is written per day. IDSTower takes ownership of the default log directory at every start, so an installation whose log directory was left owned by the wrong user repairs itself. To keep logs on another disk, point this setting at a path there rather than replacing
/var/log/idstowerwith a symbolic link — the service will not start if that directory is a symlink. A directory you choose yourself must exist and be writable by the service user. Default: “/var/log/idstower/idstower.log”
- LogFile: Path to log file. One file is written per day. IDSTower takes ownership of the default log directory at every start, so an installation whose log directory was left owned by the wrong user repairs itself. To keep logs on another disk, point this setting at a path there rather than replacing
- LogLevel: Logging verbosity level
Allowed values: “Fatal”, “Error”, “Warning”, “Information”, “Debug”, “Verbose”
Default: “Information”
- LogTemplate: Log message template format
Default: “{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}”
Docker Configuration¶
When using Docker, all configuration options can be set using environment variables. Use double underscores (__) to represent nesting in the configuration.
Complete Configuration Example¶
Here’s a fully configured appsettings.json file with comments:
{
// DEPRECATED since v3.1.0: License key is now managed via the web UI (Settings → License tab)
// "LicenseKey": "your-license-key-here",
// Required for encrypting sensitive data (generate with: openssl rand -hex 32)
"EncryptionKey": "64-character-hex-string-for-encrypting-sensitive-data",
// Database connection settings
"Database": {
"Host": "database.company.local",
"Port": 3306,
"Name": "idstower",
"Username": "idstower_user",
"Password": "secure-database-password",
"CommandTimeout": 120
},
// Web hosting configuration
"Hosting": {
// Internal listening URL - use * to listen on all interfaces
"URL": "https://*:443",
// URL prefix when running behind a reverse proxy (e.g., /idstower)
"PathPrefix": "/idstower",
// External URL that Suricata hosts will use to reach IDSTower
// Required when using * in URL
"ExternalUrl": "https://idstower.company.com/idstower",
// HTTPS certificate configuration
"Certificate": {
"Path": "/etc/idstower/certs/idstower.pfx",
"Password": "certificate-password"
}
},
// Advanced configuration options
"AdvancedSettings": {
// Path to ansible-playbook binary
"AnsiblePlaybookBinaryPath": "/usr/bin/ansible-playbook",
// Path to IDSTower playbooks
"AnsiblePlaybooksPath": "/opt/idstower/playbooks/cluster_setup.yml",
// SSH key configuration
"SSHKeyType": "RSA",
"SSHKeySize": 2048,
// AWS exports prefix
"AwsExportsNamePrefix": "IDSTower",
// Authentication settings
"DisableAuthentication": false,
// Ansible task profiling (logs slow tasks as warnings)
"EnableAnsibleTaskProfiling": false,
// On-disk cache for generated payloads (exports, per-host rules files);
// wiped on service start, must be writable by the service user
"GeneratedFileCachePath": "/var/cache/idstower",
// How long a host rules pull waits for an in-progress compilation
// before answering 202 Accepted
"GeneratedPayloadWaitSeconds": 30,
// Retry-After header value sent with the 202 response
"GeneratedPayloadRetryAfterSeconds": 30,
// Upper bound on how long a cached payload may be reused
"GeneratedPayloadCacheLifetimeMinutes": 360,
// Rows per database query while generating rules / indicator files;
// lower = less peak memory, more round-trips per regeneration
"RulesFetchChunkRows": 1500,
"IndicatorsFetchChunkRows": 50000
},
// Logging configuration
"Logging": {
"LogFile": "/var/log/idstower/idstower.log",
"LogLevel": "Information",
"LogTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}"
}
}