Provided by: exim4-base_4.60-3ubuntu3_i386 bug

NAME

       exipick - display messages from Exim queue based on a variety of
       criteria

USAGE

       exipick [--help│--version] │ [-spool <spool>] [-and│-or]
       [-bp│-bpa│-bpc│-bpr│-bpra│-bpru│-bpu] [<criterion> [<criterion> ...]]

DESCRIPTION

       exipick is designed to display the contents of a Exim mail spool based
       on user-specified criteria.  It is designed to mimic the output of
       ’exim -bp’ (or any of the other -bp* options) and Exim’s spec.txt
       should be used to learn more about the exact format of the output.  The
       criteria are formed by creating comparisons against characteristics of
       the messages, for instance $message_size, $sender_helo_name, or
       $message_headers.

OPTIONS

       --spool
           The path to Exim’s spool directory.  In general usage you should
           set the $spool variable in the script to your site’s main spool
           directory (and if exipick was installed from the Exim distribution,
           this is done by default), but this option is useful for alternate
           installs, or installs on NFS servers, etc.

       --and
           A message will be displayed only if it matches all of the specified
           criteria.  This is the default.

       --or
           A message will be displayed if it matches any of the specified
           criteria.

       --caseful
           By default criteria using the ’=’ operator are caseless.
           Specifying this option make them respect case.

       --show-vars <variable>[,<variable>...]
           Cause the value of each specified variable to be displayed for
           every message dispayed.  For instance, the command "exipick
           --show-vars ’$sender_ident’ ’sender_host_address eq 127.0.01’" will
           show the ident string for every message submitted via localhost.
           How exactly the variable value is diplayed changes according to
           what output format you specify.

       --show-rules
           If specified the internal representation of each message criteria
           is shown.  This is primarily used for debugging purposes.

       --show-tests
           If specified, for every message (regardless of matching criteria)
           the criteria’s actual value is shown and the compiled internal eval
           is shown.  This is used primarily for debugging purposes.

       --flatq
           Change format of output so that every message is on a single line.
           Useful for parsing with tools such as sed, awk, cut, etc.

       The -bp* options all control how much information is displayed and in
       what manner.  They all match the functionality of the options of the
       same name in Exim.  Briefly:
       -bp   display the matching messages in ’mailq’ format.
       -bpa    ... with generated addresses as well.
       -bpc    ... just show a count of messages.
       -bpr    ... do not sort.
       -bpra   ... with generated addresses, unsorted.
       -bpru   ... only undelivered addresses, unsorted.
       -bpu    ... only undelivered addresses.
           Please see Exim’s spec.txt for details on the format and
           information displayed with each option.

       The following options are included for compatibility with the
       ’exiqgrep’ utility:
       -f <regexp>  Same as ’$sender_address = <regexp>’
       -r <regexp>  Same as ’$recipients = <regexp>’
       -s <string>  Same as ’$shown_message_size eq <string>’
       -y <seconds> Same as ’$message_age < <seconds>’
       -o <seconds> Same as ’$message_age > <seconds>’
       -z           Same as ’$deliver_freeze’
       -x           Same as ’!$deliver_freeze’
       -c           Display count of matches only
       -l           Display in long format (default)
       -i           Display message IDs only
       -b           Display brief format only
           Please see the ’exiqgrep’ documentation for more details on the
           behaviour and output format produced by these options

       <criterion>
           The criteria are used to determine whether or not a given message
           should be displayed.  The criteria are built using variables
           containing information about the individual messages (see VARIABLES
           section for list and descriptions of available variables).  Each
           criterion is evaluated for each message in the spool and if all (by
           default) criteria match or (if --or option is specified) any
           criterion matches, the message is displayed.  See VARIABLE TYPES
           for explanation of types of variables and the evaluations that can
           be performed on them and EXAMPLES section for complete examples.

           The format of a criterion is explained in detail below, but a key
           point to make is that the variable being compared must always be on
           the left side of the comparison.

           If no criteria are provided all messages in the queue are displayed
           (in this case the output of exipick should be identical to the
           output of ’exim -bp’)

       --help
           This screen.

       --version
           Version info.

VARIABLE TYPES

       Although there are variable types defined, they are defined only by the
       type of data that gets put into them.  They are internally typeless.
       Because of this it is perfectly legal to perform a numeric comparison
       against a string variable, although the results will probably be
       meaningless.

       NUMERIC
           Variable of the numeric type can be of integer or float.  Valid
           comparisons are <, <=, >, >=, ==, and !=.

           The numbers specified in the criteria can have a suffix of d, h, m,
           s, M, K, or B, in which case the number will be mulitplied by
           86400, 3600, 60, 1, 1048576, 1024, or 1 respectively.  These
           suffixes are case sensitive.  While these are obviously designed to
           aid in date and size calculations, they are not restricted to
           variables of their respective types.  That is, though it’s odd it’s
           legal to create a criterion of a message being around for 3
           kiloseconds: ’$message_age >= 3K’.

       BOOLEAN
           Variables of the boolean type are very easy to use in criteria.
           The format is either the variable by itself or the variable negated
           with a ! sign.  For instance, ’$deliver_freeze’ matches if the
           message in question is frozen, ’!$deliver_freeze’ matches if
           message is not frozen.

       STRING
           String variables are basically defined as those that are neither
           numeric nor boolean and can contain any data.  The string operators
           are =, eq, ne, =~, and !~.  With the exception of ’=’, the
           operators all match the functionality of the like-named perl
           operators.

           The simplest form is a bare string regular expression, represented
           by the operator ’=’.  The value used for the comparison will be
           evaluated as a regular expression and can be as simple or as
           complex as desired.  For instance ’$sender_helo_name = example’ on
           the simple end or ’$sender_helo_name = ^aol\.com$’ on the more
           complex end.  This comparison is caseless by default, but see the
           --caseful option to change this.

           Slightly more complex is the string comparison with the operators
           ’eq’ and ’ne’ for equal and not equal, respectively.
           ’$sender_helo_name eq hotmail.com’ is true for messages with the
           exact helo string "hotmail.com", while ’$sender_helo_name ne
           hotmail.com’ is true for any message with a helo string other than
           "hotmail.com".

           The most complex and the most flexible format are straight regular
           expressions with the operators ’=~’ and ’!~’.  The value in the
           criteria is expected to be a correctly formatted perl regular
           expression including the regexp delimiters (usually //).  The
           criterion ’$sender_helo_name !~
           /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/’ matches for any message
           which does not have an IP address for its helo string.

VARIABLES

       With a few exceptions the available variables match Exim’s internal
       expansion variables in both name and exact contents.  There are a few
       notable additions and format deviations which are noted below.
       Although a brief explanation is offered below, Exim’s spec.txt should
       be consulted for full details.  It is important to remember that not
       every variable will be defined for every message.  For example,
       $sender_host_port is not defined for messages not received from a
       remote host.

       In the list below, ’.’ denotes standard messages with contents matching
       Exim’s variable, ’#’ denotes standard variables with non-standard
       contents, and ’+’ denotes a non-standard variable.

       Boolean variables

       + $allow_unqualified_recipient
           TRUE if unqualified recipient addresses are permitted in header
           lines.

       + $allow_unqualified_sender
           TRUE if unqualified sender addresses are permitted in header lines.

       + $deliver_freeze
           TRUE if the message is currently frozen.

       . $first_delivery
           TRUE if the message has never been deferred.

       . $manually_thawed
           TRUE when the message has been manually thawed.

       + $dont_deliver
           TRUE if, under normal circumstances, Exim will not try to deliver
           the message.

       . $host_lookup_deferred
           TRUE if there was an attempt to look up the host’s name from its IP
           address, but an error occurred that during the attempt.

       . $host_lookup_failed
           TRUE if there was an attempt to look up the host’s name from its IP
           address, but the attempt returned a negative result.

       + $local_error_message
           TRUE if the message is a locally-generated error message.

       + $sender_local
           TRUE if the message was locally generated.

       + $sender_set_untrusted
           TRUE if the envelope sender of this message was set by an untrusted
           local caller.

       . $tls_certificate_verified
           TRUE if a TLS certificate was verified when the message was
           received.

       Numeric variables

       . $body_linecount
           The number of lines in the message’s body.

       . $body_zerocount
           The number of binary zero bytes in the message’s body.

       + $deliver_frozen_at
           The epoch time at which message was frozen.

       . $interface_port
           The local port number if network-originated messages.

       . $message_age
           The number of seconds since the message was received.

       . $message_body_size
           The size of the body in bytes.

       . $message_linecount
           The number of lines in the entire message (body and headers).

       . $message_size
           The size of the message in bytes.

       . $originator_gid
           The group id under which the process that called Exim was running
           as when the message was received.

       . $originator_uid
           The user id under which the process that called Exim was running as
           when the message was received.

       . $received_count
           The number of Received: header lines in the message.

       . $received_time
           The epoch time at which the message was received.

       . $recipients_count
           The number of envelope recipients for the message.

       + $recipients_del_count
           The number of envelope recipients for the message which have
           already been delivered.  Note that this is the count of original
           recipients to which the message has been delivered.  It does not
           include generated addresses so it is possible that this number will
           be less than the number of addresses in the recipients_del string.

       + $recipients_undel_count
           The number of envelope recipients for the message which have not
           yet been delivered.

       . $sender_host_port
           The port number that was used on the remote host for network-
           originated messages.

       + $warning_count
           The number of delay warnings which have been sent for this message.

       String variables

       . $acl_c0-$acl_c9, $acl_m0-$acl_m9
           User definable variables.

       . $authenticated_id
           Optional saved information from authenticators, or the login name
           of the calling process for locally submitted messages.

       . $authenticated_sender
           The value of AUTH= param for smtp messages, or a generated value
           from the calling processes login and qualify domain for locally
           submitted messages.

       + $bmi_verdicts
           I honestly don’t know what the format of this variable is.  It only
           exists if you have Exim compiled with WITH_CONTENT_SCAN and
           EXPERIMENTAL_BRIGHTMAIL (and, you know, pay Symantec/Brightmail a
           bunch of money for the client libs and a server to use them with).

       + $each_recipients
           This is a psuedo variable which allows you to apply a criterion
           against each address in $recipients individually.  This allows you
           to create criteria against which every individual recipient is
           tested.  For instance, ’$recipients =~ /aol.com/’ will match if any
           of the recipient addresses contain the string "aol.com".  However,
           with the criterion ’$each_recipients =~ /@aol.com$/’, a message
           will only match if every recipient matches that pattern.  Note that
           this obeys --and or --or being set.  Using it with --or is very
           similar to just matching against $recipients, but with the added
           benefit of being able to use anchors at the beginning and end of
           each recipient address.

       + $each_recipients_del
           Like $each_recipients, but for the $recipients_del variable.

       + $each_recipients_undel
           Like $each_recipients, but for the $recipients_undel variable.

       # $header_*
           The value of the same named message header, for example header_to
           or header_reply-to.  These variables are really closer to Exim’s
           rheader_* variables, with the exception that leading and trailing
           space is removed.

       . $interface_address
           The address of the local IP interface for network-originated
           messages.

       . $local_scan_data
           The text returned by the local_scan() function when a message is
           received.

       # $message_body
           The message’s body.  Unlike Exim’s variable of the same name, this
           variable contains the entire message body.  The logic behind this
           is that the message body is not read unless it is specifically
           referenced, so under normal circumstances it is not a penalty, but
           when you need the entire body you need the entire body.  Like
           Exim’s copy, newlines and nulls are replaced by spaces.

       . $message_headers
           A concatenation of all the header lines except for lines added by
           routers or transports.

       . $message_exim_id, $message_id
           The unique message id that is used by Exim to identify the message.
           $message_id is deprecated as of Exim 4.53.

       + $originator_login
           The login of the process which called Exim.

       . $received_protocol
           The name of the protocol by which the message was received.

       # $recipients
           The list of envelope recipients for a message.  Unlike Exim’s
           version, this variable always contains every envelope recipient of
           the message.  The recipients are separated by a comma and a space.

       + $recipients_del
           The list of delivered envelope recipients for a message.  This non-
           standard variable is in the same format as recipients and contains
           the list of already-delivered recipients including any generated
           addresses.

       + $recipients_undel
           The list of undelivered envelope recipients for a message.  This
           non-standard variable is in the same format as recipients and
           contains the list of undelivered recipients.

       . $reply_address
           The contents of the Reply-To: header line if one exists and it is
           not empty, or otherwise the contents of the From: header line.

       . $sender_address
           The sender’s address that was received in the message’s envelope.
           For bounce messages, the value of this variable is the empty
           string.

       . $sender_address_domain
           The domain part of $sender_address.

       . $sender_address_local_part
           The local part of $sender_address.

       . $sender_helo_name
           The HELO or EHLO value supplied for smtp or bsmtp messages.

       . $sender_host_address
           The remote host’s IP address.

       . $sender_host_authenticated
           The name of the authenticator driver which successfully
           authenticated the client from which the message was received.

       . $sender_host_name
           The remote host’s name as obtained by looking up its IP address.

       . $sender_ident
           The identification received in response to an RFC 1413 request for
           remote messages, the login name of the user that called Exim for
           locally generated messages.

       + $shown_message_size
           This non-standard variable contains the formatted size string.
           That is, for a message whose $message_size is 66566 bytes,
           $shown_message_size is 65K.

       . $smtp_active_hostname
           The value of the active host name when the message was received, as
           specified by the "smtp_active_hostname" option.

       . $spam_score
           The spam score of the message, for example ’3.4’ or ’30.5’.
           (Requires exiscan or WITH_CONTENT_SCAN)

       . $spam_score_int
           The spam score of the message, multiplied by ten, as an integer
           value.  For instance ’34’ or ’305’.  (Requires exiscan or
           WITH_CONTENT_SCAN)

       . $tls_cipher
           The cipher suite that was negotiated for encrypted SMTP
           connections.

       . $tls_peerdn
           The value of the Distinguished Name of the certificate if Exim is
           configured to request one.

EXAMPLES

       exipick ’$deliver_freeze’
           Display only frozen messages.

       exipick ’$received_protocol eq asmtp’ ’$message_age < 20m’
           Display only messages which were delivered over an authenticated
           smtp session in the last 20 minutes.

       exipick -bpc ’$message_size > 200K’
           Display a count of messages in the queue which are over 200
           kilobytes in size.

       exipick -or ’$sender_helo_name =~
       /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/’ ’$sender_helo_name = _’
           Display message which have a HELO string which either is an IP
           address or contains an underscore.

REQUIREMENTS

       None that I know of, except an Exim installation.  Your life will also
       be a lot easier if you set $spool at the top of the script to your
       install’s spool directory (assuming this was not done automatically by
       the Exim install process).

ACKNOWLEDGEMENTS

       Although I conceived of the concept for this program independently, the
       name ’exipick’ was taken from the Exim WishList and was suggested by
       Jeffrey Goldberg.

       Thank you to Philip Hazel for writing Exim.  Of course this program
       exists because of Exim, but more specifically the message parsing code
       is based on Exim’s and some of this documentation was copy/pasted from
       Exim’s.

CONTACT

       EMAIL: proj-exipick@jetmore.net
       HOME: jetmore.org/john/code/#exipick