Configuration

MailLogSentinel is configured using a central configuration file. The interactive setup process (--setup) is the easiest and recommended way to create this file for the first time.

Main Configuration File

• Default Path: /etc/maillogsentinel.conf

• Creation Methods:

  1. Interactive Setup (Highly Recommended): Run sudo maillogsentinel --setup. This command initiates a wizard that will guide you through all necessary settings and create the configuration file at the default path.
  2. Manual Creation: If you prefer, you can manually copy the template provided in the repository (config/maillogsentinel.conf) to /etc/maillogsentinel.conf and then edit it according to your environment.

     sudo cp config/maillogsentinel.conf /etc/maillogsentinel.conf
     # Ensure appropriate ownership and restrictive permissions, for example:
     # sudo chown your_chosen_operational_user:your_chosen_operational_user_group /etc/maillogsentinel.conf
     # sudo chmod 640 /etc/maillogsentinel.conf 

• File Structure and Options: The configuration file uses a standard INI-style format.

  • [paths]

    • working_dir: Specifies the directory where the CSV output file (maillogsentinel.csv) and the script's own operational log file (maillogsentinel.log) will be stored.
      • Example: /var/log/maillogsentinel
    • state_dir: Defines the directory where the state file (state.offset) is stored. This file tracks the last processed position in the mail log, enabling incremental parsing. It can be the same as working_dir or a separate directory (e.g., for systems where /var/lib is preferred for state files).
      • Example: /var/lib/maillogsentinel (or /var/log/maillogsentinel/state)
    • mail_log: The full path to your mail server's primary log file where SASL authentication messages are recorded (e.g., Postfix/Dovecot combined log).
      • Example: /var/log/mail.log

  • [report]

    • email: The email address to which daily summary reports will be sent.
      • Example: security-alerts@example.com

  • [general]

    • log_level: Controls the verbosity of MailLogSentinel's own operational messages, which are written to maillogsentinel.log.
      • Valid Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
      • Default: INFO

  • [dns_cache]

    • enabled: Set to true to enable caching of DNS reverse lookup results, or false to disable caching (perform fresh lookups every time).
      • Default: true
    • size: The maximum number of DNS entries to store in the LRU (Least Recently Used) cache.
      • Default: 128
    • ttl_seconds: The Time-To-Live (in seconds) for entries in the DNS cache. After this duration, a cached entry will be considered stale and will be re-fetched upon the next request for that IP.
      • Default: 3600 (which corresponds to 1 hour)

Interactive Setup (--setup)

• Purpose: The --setup option provides a guided, interactive command-line process for configuring MailLogSentinel for the first time. This is the recommended method for initial configuration as it simplifies setting up paths, email details, and also helps in generating Systemd unit files for automation.
• Invocation:

  sudo maillogsentinel --setup

  If maillogsentinel is not in your system's PATH (e.g., if you haven't run sudo cp bin/maillogsentinel.py /usr/local/bin/maillogsentinel), you'll need to use the full path to the script:

  sudo python3 /path/to/your/MailLogSentinel/bin/maillogsentinel.py --setup

• Process Details:
  • The script will prompt you for essential configuration parameters, including the paths for working_dir, state_dir, and mail_log, the recipient email address for reports, and the desired operational log level. Default values are suggested where applicable.
  • It will then offer to generate example Systemd service (.service) and timer (.timer) unit files. These are customized with the paths and user you specify and are crucial for automating regular log processing and report generation.
  • If run with sufficient privileges (i.e., sudo), the setup process can attempt to create the specified working_dir and state_dir if they don't exist, and set appropriate ownership and permissions for the operational user you define.
  • It may also suggest adding the chosen operational user to a system group like adm (common on Debian/Ubuntu systems) to ensure the script has read access to system mail logs.
• Automatic Setup Logging: Throughout the interactive setup, all information displayed on your console (including prompts, the values you select, and the generated Systemd examples) is automatically logged to a file named maillogsentinel_setup.log. This log file is created in the current working directory from which you executed the --setup command. This feature is invaluable for reviewing your setup choices and for troubleshooting.