Content-type: text/html Manpage of maillog

maillog

Section: User Commands (1)
Updated: 27 Jun 2006
Index Return to Main Contents
 

NAME

maillog - select entries from a sendmail or postfix log.  

SYNOPSIS

maillog [-h] [-V] [-v] [-t] [-u] [-c] fieldname[,...] [-s] fieldname[,...] [-p] fieldname[,...] [-d] \

      [message-selector...] [--] file...

 

DESCRIPTION

Maillog selects sendmail or postfix log entries from one or more syslog files named on the command line. Logfiles whose names end in .gz, .z, or .Z are passed through gunzip -c -f before processing; logfiles whose names end in .bz2 are passed through bunzip2 -c -f before processing.

All lines are re-formatted into a style that is easier for browsing. In the default non-verbose mode, only the date, from, to, ctladdr, stat, and notes fields are printed. (Notes is a pseudo-key that contains the values of log fields that aren't in the usual key=value format, such as lqreturn to senderrq.

The output is formatted into blocks like: 

Message : Message-queue-id
   file.line   host   field   value
   file.line   host   field   value
   ...
where the message-queue-id is the mta queue id; file is 1 for the first file on the command line, 2 for the second, etc; line is the line number within the file; host is the host that generated the syslog entry; field is the field name within the mta line; and value gives the field's value (of course). For example: 

Message : IAA07301
   1.506  sunup   date    Jun 5 08:10:10
   1.506  sunup   from    smith
   1.512  sunup   date    Jun 5 08:10:15
   1.512  sunup   to      svasq@sci.gmt.carney.nowhere
   1.512  sunup   ctladdr smith (87/200)
   1.512  sunup   stat    Sent (IAA01006 Message accepted for delivery)

A field name can repeat several times in a message block, because sendmail or postfix often makes several logfile entries for each message.  

OPTIONS

-h
Print this message, then exit.
-p field,...
Print selected fields. This lets you specify which fields from each log message are printed. Note that not all fields are present in every message. Valid fieldnames include: 
     arg1                arg2                bodytype
     client              class               ctladdr
     daemon              date                delay
     dsn                 from                host
     id                  mailer              msgid,message-id
     nrcpt,nrcpts        pid                 pri
     proto               qid                 relay
     ruleset             size                stat,status
     to                  xdelay
The following pairs are treated as aliases:

    (stat,status), (msgid,message-id), and (nrcpt,nrcpts).
The default output is equivalent to

    -p date,from,to,ctladdr,stat,notes
If the first character of the fieldlist is `+', it stands for the default fields. That is, -p +aaa,bbb means to print the usual fields, aaa, and bbb.
-c field,...
Use case-sensitive matching for these fields' values. The default is case-insensitive matching for all fields.
-s field,...
Suppress duplicate printing: print just one copy of duplicate field/value pairs. In the default (non-terse) format, when one of these fields appears on multiple lines for a single message, successive copies are not printed unless the next value differs from the preceding value. The default is
-s date,host,from If the first character of the fieldlist is `+', it stands for the default fields. That is, -s +aaa,bbb means to suppress duplicates of the usual fields plus aaa and bbb. (Use -s  to suppress no fields.)
-V
Print version, then exit.
-v
Verbose mode -- print all log fields.
-t
Moderately terse mode -- print just one line of output for each logfile line that matched the message selectors. The fields are separated with tabs, and by default only the date, from, and to fields are printed. The output is formatted like: 

Message-queue-id  file.line  host val val...
     ...
Here, the val's are in the same order as given with the -p option, and any missing val's are replaced with -.
-tt
Very terse mode -- print just one line of output for each message id that matched the message selectors. The fields are separated with tabs. Only the first date for each message id is printed. For other fields, Within each field, multiple values are joined with commas. By default, only the date, from, and to fields are printed. The output is formatted like: 

Message-queue-id  v1,v2,... v1,v2,...
     ...
Each of the tab-separated groups v1,v2,... is in turn a comma-separated list of all the values for that field. The val's are in the same order as given with the -p option, and any missing val's are replaced with -.
-f
Follow message id threads. That is, if a matched message is passed to another mta process, and the new queue id is available in the logfile(s), then this option causes the new message id to also match. Also, any clones of matched messages count as matches. This lets you trace a message that has mail queue id XXXXX by using
maillog -f qid=XXXXX ...
-u
Keep unclassifiable mta lines. An unclassifiable line is one that doesn't have the expected syntax. Normally these lines are discarded. The -u flag says to attach the line as a 'note' to the current qid. -d Print debug info. Not interesting to most users. More d's may add more detail (up to a point).
 

MESSAGE SELECTORS

By default, all mta log entries are selected for printing. You can use boolean expressions, hereafter called message selectors, to limit the selected entries.

Selectors use the key=value fields from the log entries to choose messages. Additionally, there is some useful data that is not in key=value format, and that data is converted to key=value as follows:

Key Value
qid
mail queue id, from the message preamble;
date
Month date time, taken from the message preamble;
host
mta hostname, taken from the message preamble;
pid
mta pid, also from the message preamble;
clone-of
this message is a clone of the message with queue id clone-of.
child-is
The message was handed to another mta process, and its new message queue id is child-is.
notes
contains the messages that don't match the usual key=value format ("clone XXX", "return to sender", etc).
 

Basic Message Selectors

The basic message selectors are the following:
key=val
The key is a field in a log entry, such as from, to, etc. Any log entries whose key value equals val are selected for display. Each key=val selector must be a separate command-line argument. For instance, 

maillog 'to=smith from=wesson'               # Wrong
maillog 'to=smith' 'from=wesson'             # Better (but see key#word)
NOTE: if you want to match a from=xxx or to=xxx value, the key=val selector is not a good way to do it. If xxx is, say, "smith", then it will match smith but not <smith@somewhere.dom>. The selectors that do pattern-matching, below, are better for matching to or from fields.
key:glob-pat
Like key=val, except that the value is interpreted as a non-anchored glob pattern --- that is, to:will matches to=will or to=gillwillnot or to=<will@wherever>, etc.
key#word
Like key=val, except that the value is interpreted as a username-like word --- that is, the selector to#will matches to=will or to=<will@wherever>, but not to=willard. NOTE: This is the preferred way to select mail to or from a particular user.

The word will not match after a dot or @-sign, so it won't match in the address part of a name; it will only match the username part of a name.

As a special case for the `#' operator, to#xxx is always turned into the expression:

      ( ctladdr#xxx or to#xxx )
This helps collect all mail to user xxx, because the individual username won't show up in the to field when the address is a maillist, but will eventually appear as the ctladdr.

key~regexp-pat
Like key=val, except that the value is interpreted as a regexp pattern. It can be difficult to write complicated regexp's because the pattern has to be protected from shell expansion, and then maillog has to quote it properly for use in a search function. Thus, it is often useful to briefly use the -d (debug) flag, so that you can check that the generated regexp search patterns are what you intended to use.
key==val, key<val, key>val, key<=val, key>=val, key!=val
Similar to key=val, except these do numeric comparisons instead of string comparisons, and therefore make sense only for keywords "date" and those with a numeric value. Special case: note that the "date" keyword records time to the second. When comparing date to a value, maillog does the following: 
Value             Interpretation
Apr 19            ...truncates dates to the day.
Apr 19 10:        ...truncates dates to the hour.
Apr 19 10:12      ...truncates dates to the minute.
Apr 19 10:12:     ...same as above.
Apr 19 10:12:14   ...uses full time resolution.
See the examples.
 

Compound Message Selectors

The basic message selectors can be combined with the usual boolean operators to produce more complicated expressions. The compound selector expressions include: 
     &&, and             Boolean and.
     ||, or              Boolean and.
     !, not              Boolean not.
     ( ... ), { ... }    Grouping.
You can combine key-selection options using the boolean operators &&, ||, and !, and group expressions using (...). Since these operators all have meaning to the shell, and thus need to be quoted, you may prefer to use the alternatives and, or, and not, and group expressions with braces: {...}. (Note that braces are significant to some shells, but never when passed as simple standalone arguments to a command.)

Just as for the key=val selectors, each of these syntactic elements must be a separate command-line argument. This allows maillog to distinguish operators and grouping characters from the patterns that are being matched. For instance: 


{to#june or from#july} and not from#august     # Wrong
"{ to#june or from#july }" and not from#august # Wrong
{ to#june or from#july } and not from#august   # Right
The default operator is && --- that is, all key/pattern pairs need to match:
      to#june from#july
is equivalent to
      to#june and from#july
 

EXAMPLES

Any mail that is to jeepers and from creepers:
      maillog to#jeepers from#creepers syslog

Any mail that is to user june or user july, and is from user august:
      maillog { to#june or to#july } and from#august syslog

Any mail that is to jen, and arrived on Apr 19, between 3:17:00 and 3:17:59, inclusive:
      maillog to#jen 'date==Apr 19 3:17' syslog

Any mail that is to lil and from abner and has a date of of today, any time on April 20, or after Apr 3, 3:17am:
      maillog to#lil from#abner { 'date==today' or \\
           'date==Apr 20' or 'date>Apr 3 3:17' } syslog Here is a complete sample with a brief description of the output. The command requests messages from user smith, sent on June 5, before 8:12: 


% maillog from#smith 'date >= jun 5' \
          'date < jun 5 08:12' syslog

Message : IAA07301
   1.506  sunup   date    Jun 5 08:10:10
   1.506  sunup   from    smith
   1.512  sunup   date    Jun 5 08:10:15
   1.512  sunup   to      svasq@sci.gmt.carney.nowhere
   1.512  sunup   ctladdr smith (87/200)
   1.512  sunup   stat    Sent (IAA01006 Message accepted for delivery)

Message   : IAA01006
   1.511  helipad date    Jun 5 08:05:56
   1.511  helipad from    <smith@helipad.myplace.org>
   1.513  helipad date    Jul 5 08:06:00
   1.513  helipad to      <svasq@sci.gmt.carney.nowhere>
   1.513  helipad ctladdr <smith@helipad.myplace.org> (87/200)
   1.513  helipad stat    User unknown
   1.514  helipad date    Jul 5 08:06:01
   1.514  helipad notes   IAA01014: DSN: User unknown
Here, host sunup accepted a message from user smith (line 506 in the syslog file), and used host helipad as a relay (line 512; the relay field wasn't printed because this is not a verbose listing), and the stat field shows that helipad's message queue id for the mssage is IAA01006. At line 511, host helipad accepted the message. (Clearly, helipad's and sunup's clocks are badly skewed, since helipad says that it accepted the message about 4 minutes before sunup says that it sent the message). Four seconds after accepting the message, helipad recorded that the message was undeliverable because lqUser unknownrq (line 513).  

BUGS

Maillog internally stores messages using the mta's per-host internal message id. The internal message id will remain unique within any single host, but mta's running on different hosts will sometimes use the same id. Therefore, if you use maillog to process files containing mta logs from multiple hosts, maillog will sometimes erroneously identify several distinct messages as all being part of a single message. In practice this is not a common problem, and it should be obvious from the host column when different messages are using the same message id.

 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
MESSAGE SELECTORS
Basic Message Selectors
Compound Message Selectors
EXAMPLES
BUGS
This document was created by man2html, using the manual pages.
Time: 01:41:23 GMT, October 03, 2006