Skip to main content

Configuration File

Nauthilus uses a YAML configuration file to define its behavior. This document explains the general structure and format of this file.

File Format​

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.

File Location​

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

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

The first file found in these locations will be used.

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.

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:

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=%u))"
      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.