Configuration File

Nauthilus uses a configuration file to define its behavior. By default, the configuration is in YAML format, but other formats like JSON, TOML, etc. are also supported. This document explains the general structure and format of this file.

File Format

By default, the configuration file is written in YAML format. YAML is a human-readable data serialization standard that is commonly used for configuration files. The file should have a .yml extension.

Nauthilus also supports other configuration formats such as JSON, TOML, HCL, and INI. You can specify the format using the -config-format command-line flag.

File Location

By default, Nauthilus looks for its configuration file named nauthilus.yml in the following locations:

• Current directory
• $HOME/.nauthilus
• /etc/nauthilus/
• /usr/local/etc/nauthilus/

The first file found in these locations will be used.

Search order changed in version 1.7.9

Command-Line Options

Nauthilus supports the following command-line options:

• -config <path>: Specify a custom path to the configuration file. This overrides the default search locations.
• -config-format <format>: Specify the configuration file format (yaml, json, toml, etc.). Default is "yaml".
• -version: Print the version information and exit.
• -gen-oidc-key: Generate a new RSA private key for OIDC signing and exit.
• -gen-saml-cert <common-name>: Generate a self-signed SAML certificate/key pair and exit.
• -key-bits <bits>: RSA key size used by generation flags. Default: 4096.
• -cert-years <years>: Certificate validity for -gen-saml-cert. Default: 10.
• --test-lua <script.lua>: Run Lua test mode for a single script and exit.
• --test-callback <filter|feature|action|backend|hook>: Required in Lua test mode.
• --test-mock <mock.json>: Optional JSON mock fixture in Lua test mode.

Environment Variables

Some configuration options can be set using environment variables. These are typically used for settings that don't change frequently or that might contain sensitive information like passwords. See the Reference document for details on available environment variables.

Structure

The configuration file contains several main sections, where each is responsible for a particular category of runtime behavior.

Features

• realtime_blackhole_lists
• cleartext_networks
• relay_domains
• brute_force
• lua
• backend_server_monitoring

Experimental Features

Nauthilus includes several experimental features that are under active development:

• Machine Learning Enhanced Brute Force Detection: A neural network approach to enhance the rule-based brute force detection system. This feature is configured in the brute_force::neural_network section. Deprecated Feature: This functionality has been dropped in version 1.8.0 and is no longer available.

To enable experimental machine learning features, set the NAUTHILUS_EXPERIMENTAL_ML environment variable to true.

General configuration settings

• server
• ldap
• lua

Each section has individual subsections. See details in the specific documentation pages. If you do not require some sections, please do not include it into the configuration file.

Configuration Sections

The configuration is divided into the following main sections:

• Includes - Split configuration across multiple files (required, optional, and env-specific includes)
• Server Configuration - Core server settings including address, TLS, logging, Redis, and more
• Realtime Blackhole Lists - Configuration for RBL checks
• Cleartext Networks - Settings for allowing unencrypted connections
• Relay Domains - Domain validation for email addresses
• Backend Server Monitoring - Health checks for backend servers
• Brute Force Protection - Settings for brute force attack prevention
• Password Nonce - Password hashing configuration
• Identity Provider - Native OIDC (Authorization Code + Device Code + Client Credentials) and SAML2
• Database Backends - Configuration for authentication backends
  • Protocols - Protocol-specific settings
  • Macros - Macro definitions for queries
  • Cache Namespaces - Redis cache namespace configuration
  • Encrypted Passwords - Supported password encryption formats
  • LDAP - LDAP backend configuration
  • Lua - Lua backend configuration
• Full Example - Complete configuration example

Example

Here's a minimal example of a Nauthilus configuration file:

server:
  address: "127.0.0.1:9080"
  log:
    level: "info"
  redis:
    master:
      address: "127.0.0.1:6379"

ldap:
  config:
    server_uri:
      - "ldap://127.0.0.1:389"
    bind_dn: "cn=admin,dc=example,dc=com"
    bind_pw: "password"
    lookup_pool_size: 8
    auth_pool_size: 8
  search:
    - protocol:
        - "imap"
      cache_name: "imap"
      base_dn: "ou=people,dc=example,dc=com"
      filter:
        user: "(&(objectClass=inetOrgPerson)(uid=%L{user}))"
      mapping:
        account_field: "uid"
      attribute:
        - "uid"
        - "userPassword"

For a complete example with all available options, see the Full Example page.

Reloading Configuration

You can reload the configuration file without restarting Nauthilus by sending a HUP signal to the process:

kill -HUP $(pidof nauthilus)

This will stop LDAP connections, reload the configuration file, and restart the database connections. The main web server process will remain running.

If you change settings related to the web server itself, you must first reload the configuration file and then send a second signal to restart the server process:

kill -HUP $(pidof nauthilus)
kill -SIGUSR1 $(pidof nauthilus)

warning

Changing environment variables require a full restart of the service, as they cannot be reloaded by sending signals. ::::

Validation

Nauthilus validates the configuration file when it starts up and will report any errors it finds. Make sure to check the logs if Nauthilus fails to start after changing the configuration.