Debug level
Introduction
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
- Display 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[1] in the Mailutils source tree. Most useful categories and levels implemented for them are discussed later in this article.
Syntax
Debug levels can be set either from the command line, by using the --debug-level option, or from the configuration file, via the /debug/level statement. In both cases, it 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 this 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 for this category.
- category.levelA-levelB
Enable all levels in the range from levelA to levelB, inclusive.
- category.!levelA-levelB
Disable 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.
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"
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. So, to force debugging of the configuration parser, one may 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:
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 asteriscs to reduce the possibility of the security compromise.
- trace7
- When used together with prot, displays the payload information as it is being sent. 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.
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 option is set. Valid levels are:
- trace6
- Show security-sensitive information (user passwords, etc.)
- trace7
- Show payload information
