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-key CLI 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:8080

  • https://localhost:8443

  • http://127.0.0.1:8080

  • https://127.0.0.1:8443

  • http://*: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
  }
}
  • 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

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

    • Default: “/var/log/idstower/idstower.log”

  • 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
  },

  // Logging configuration
  "Logging": {
    "LogFile": "/var/log/idstower/idstower.log",
    "LogLevel": "Information",
    "LogTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level}] {Message}{NewLine}{Exception}"
  }
}