How-to: Enable Detailed Sieve Logging and Tracing in UCS

Knowledge Base Community
, , , , ,
1

How-to Enable Detailed Sieve Logging and Tracing in UCS

When troubleshooting mail delivery issues in Univention Corporate Server (UCS), determining exactly why an email was filtered, redirected, or dropped can be challenging. By default, Dovecot’s Sieve filtering processes rules silently or writes minimal information to per-user logs. If an email is unexpectedly dropped via a discard action, standard logging often lacks the granularity needed to identify the responsible script—especially when global scripts (sieve_before or sieve_after) are involved.

Environment

  • Platform: UCS
  • Services: Dovecot, Sieve Mail Filtering

How-to

Step 1: Check Per-User Sieve Logs

By default, Sieve writes individual log files directly into the user’s home or mail directory. This is usually the quickest way to determine which script or rule triggered a specific action (such as discard).

  1. Navigate to the user’s private mail directory. Typically, the log is located at:
    /var/spool/dovecot/private/<domain>/<user>/.dovecot.sieve.log
  2. Inspect this file for the affected user before proceeding with system-wide debugging.

Note: If the per-user log file does not exist, or if the triggering script is executed globally via sieve_before or sieve_after, system-wide detailed tracing must be enabled as described in the next steps.

Step 2: Configure the Global Sieve Debug Snippet

UCS does not provide ready-made UCR variables for detailed Sieve logging. Therefore, these options must be defined directly within the Dovecot plugin block using a custom configuration snippet. This file resides in a directory that is compliant with UCS standards and will not be overwritten by ucr commit.

  1. Create a new configuration file:
    /etc/dovecot/conf.d/99-sieve-debug.conf
  2. Populate the file with the following configuration:
plugin {
  sieve_user_log = /var/log/dovecot-sieve.log

  sieve_trace_dir       = /var/log/sieve-trace
  sieve_trace_level     = matching
  sieve_trace_debug     = yes
  sieve_trace_addresses = yes
}

Step 3: Prepare the Trace Directory and Permissions

For the configuration to take effect, the designated trace directory must exist with the correct ownership and permissions.

Run the following commands to create the directory and assign the correct ownership (dovecot:dovecot):

  • mkdir -p /var/log/sieve-trace
  • chown dovecot:dovecot /var/log/sieve-trace
  • chmod 770 /var/log/sieve-trace

Step 4: Enable General Mail Debugging and Restart Services

To complement the Sieve trace, you can optionally enable general Dovecot mail debugging via UCR and then restart the service to apply all changes.

  1. Enable mail debugging:
  • ucr set mail/dovecot/logging/mail_debug=yes
  1. Restart the Dovecot service:
  • systemctl restart dovecot

Troubleshooting & Architecture Notes

How the Trace Works

With sieve_trace_level = matching, the system logs exactly which rule applies to each delivery and what action is executed. Individual trace files are generated per email and stored in /var/log/sieve-trace/.

Directory Ownership Clarification

Setting the owner and group strictly to dovecot:dovecot ensures the Sieve plugin has the required write permissions.

UCS Configuration Compliance

  • Best Practice: The path /etc/dovecot/conf.d/ is safe from being overwritten by UCR updates.
  • Alternative (Not Recommended): Directly modifying UCR-generated configuration files is highly discouraged. If you explicitly need to alter the core template structure, you must modify the UCR templates located under /etc/univention/templates/files/etc/dovecot/.
1 Like