GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.3 Debugging

Mailutils debugging output is controlled by a set of levels, each of which can be set independently of others. Each debug level consists of a category name, which identifies the part of Mailutils for which additional debugging is desired, and a level number, which tells Mailutils how verbose should its output be.

Valid debug levels are:

error

Displays error conditions which are normally not reported, but passed to the caller layers for handling.

trace0 through trace9

Ten levels of verbosity, ‘trace0’ producing less output, ‘trace9’ producing the maximum amount of output.

prot

Displays network protocol interaction, where applicable.

Implementation and applicability of each level differs between various categories. The full list of categories is available in file libmailutils/diag/debcat in the Mailutils source tree. Most useful categories and levels implemented for them are discussed later in this article.

3.3.1 Level Syntax

Debug levels can be set either from the command line, by using the --debug-level command line option, or from the configuration file, using the ‘.debug.level’ statement. In both cases, the level is specified as a list of individual levels, delimited with semicolons. Each individual level can be specified as:

!category

Disables all levels for the specified category.

category

Enables all levels for the specified category.

category.level

For the given category, enables all levels from ‘error’ to level, inclusive.

category.=level

Enables only the given level for this category.

category.!level

Disables all levels from ‘error’ to level, inclusive, for this category.

category.!=level

Disables only the given level in this category.

category.levelA-levelB

Enables all levels in the range from levelA to levelB, inclusive.

category.!levelA-levelB

Disables all levels in the range from levelA to levelB, inclusive.

Additionally, a comma-separated list of level specifications is allowed after the dot. For example, the following specification:

acl.prot,!=trace9,!trace2

enables in category ‘acl’ all levels, except ‘trace9’, ‘trace0’, ‘trace1’, and ‘trace2’.

3.3.2 BNF

The following specification in Backus-Naur form describes formally the Mailutils debug level:

<debug-spec> ::= <level-spec> | <debug-level-list>
<debug-level-list> ::= <debug-level> |
                       <debug-level-list> ";" <debug-level>
<debug-level> ::= <category> | "!" <category> |
                  <category> "." <level-list>
<level-list> ::= <level-spec> | <level-list> "," <level-spec>
<level-spec> ::=  <level> | <negate-level>
<negate-level> ::= "!" <level>
<level> ::= <level-number> | "=" <level-number> |
            <level-number> "-" <level-number>
<level-number> ::= "error" | "trace0" | "trace1" | "trace2" | "trace3" |
                   "trace4" | "trace5" | "trace6" | "trace7" |
                   "trace8" | "trace9" | "prot"

3.3.3 Debugging Categories

acl

This category enables debugging of Access Control Lists. Available levels are:

error

As usual, displays errors, not directly reported otherwise.

trace0

Basic tracing of ACL processing.

trace9

Traces the process of matching the ACL conditions.

config

This category affects configuration parser and/or lexical analyzer. The following levels are supported:

trace0

Minimal information about configuration statements.

trace2

Trace lexical structure of the configuration files.

trace7

Trace execution of the configuration parser.

Due to its specific nature, this category cannot be enabled from the configuration file. A special hook is provided to facilitate debugging the configuration parser, namely, a pragmatic comment in form:

#debug=debug-level-list

causes debug-level-list to be parsed as described above. Thus, to force debugging of the configuration parser, one would add the following line at the very beginning of the configuration file:

#debug=config.trace7
mailbox

Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘prot’. The latter is used by remote mailbox support libraries.

auth

Enables debugging information about authentication and authorization. This category supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘trace2’.

In level ‘trace0’, user data are reported along with the data source they were obtained from. The output may look like this:

pop3d: source=system, name=gray, passwd=x, uid=120, gid=100,
gecos=Sergey Poznyakoff, dir=/home/gray, shell=/bin/bash,
mailbox=/var/mail/gray, quota=0, change_uid=1

In the ‘trace1’ level, additional flow traces are displayed.

In the level ‘trace2’, a detailed flow trace is displayed, which looks like the following:

pop3d: Trying generic...
pop3d: generic yields 38=Function not implemented
pop3d: Trying system...
pop3d: system yields 0=Success
pop3d: Trying generic...
pop3d: generic yields 4135=Authentication failed
pop3d: Trying system...
pop3d: system yields 0=Success
mailer

Debugs mailer operations. The following levels are supported:

error

Displays mild error conditions.

trace0

Traces mailer operations in general: displays what part of the message is being sent, etc.

trace6

When used together with ‘prot’, displays security-sensitive information (such as passwords, user keys, etc). in plaintext. By default, such information is replaced with asterisks to reduce the possibility of security compromise.

trace7

When used together with ‘prot’, displays the payload information as it is being sent. The payload is the actual message contents, i.e. the part of SMTP transaction that goes after the ‘DATA’ command and which ends with a terminating dot line. Setting this level can generate huge amounts of information.

prot

For SMTP mailer: outputs transcripts of SMTP sessions.

Note: Unless in a very secure environment, it is advised to avoid using level settings such as mailer.prot or mailer (without explicit level part), because the resulting output tends to be extremely copious and reveals sender private and security-sensitive data. If you wish to trace SMTP session flow, use ‘mailer.=prot’ or at least ‘mailer.prot,!trace6’.

server

This category provides debugging information for Mailutils IP server objects. It supports the ‘error’ and ‘trace0’ levels.

folder

This category controls debugging information shown for operations related to Mailutils folders.

remote

The remote category is used by imap4d and pop3d servers to request showing additional information in the session transcripts. This category takes effect only when the transcript configuration variable is set. Valid levels are:

trace6

Show security-sensitive information (user passwords, etc.)

trace7

Show payload information

GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Programs   Up: debugging   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index