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

{
  "LicenseKey": "your-license-key-here",
  "EncryptionKey": "your-64-character-hex-string"
}

• LicenseKey (Required): Your IDSTower license key in JWT format

• EncryptionKey (Required): 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"
  }
}

• 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

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

• 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

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:

{
  // Your IDSTower license key
  "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"
  },

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

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