Man Linux: Main Page and Category List

NAME

       exipick - selectively display messages from an Exim queue

SYNOPSIS

       exipick [<options>] [<criterion> [<criterion> ...]]

DESCRIPTION

       exipick is a tool to display messages in an Exim queue.  It is very
       similar to exiqgrep and is, in fact, a drop in replacement for
       exiqgrep.  exipick allows you to select messages to be displayed using
       any piece of data stored in an Exim spool file.  Matching messages can
       be displayed in a variety of formats.

QUICK START

       Delete every frozen message from queue:
           exipick -zi | xargs exim -Mrm

       Show only messages which have not yet been virus scanned:
           exipick '$received_protocol ne virus-scanned'

       Run the queue in a semi-random order:
           exipick -i --random | xargs exim -M

       Show the count and total size of all messages which either originated
       from localhost or have a received protocol of 'local':
           exipick --or --size --bpc \
                   '$sender_host_address eq 127.0.0.1' \
                   '$received_protocol eq local'

       Display all messages received on the MSA port, ordered first by the
       sender's email domain and then by the size of the emails:
           exipick --sort sender_address_domain,message_size \
                   '$received_port == 587'

       Display only messages whose every recipient is in the example.com
       domain, also listing the IP address of the sending host:
           exipick --show-vars sender_host_address \
                   '$each_recipients = example.com'

       Same as above, but show values for all defined variables starting with
       sender_ and the number of recipients:
           exipick --show-vars ^sender_,recipients_count \
                   '$each_recipients = example.com'

OPTIONS

       --and
           Display messages matching all criteria (default)

       -b  Display messages in brief format (exiqgrep)

       -bp Display messages in standard mailq format (default)

       -bpa
           Same as -bp, show generated addresses also (exim)

       -bpc
           Show a count of matching messages (exim)

       -bpr
           Same as '-bp --unsorted' (exim)

       -bpra
           Same as '-bpa --unsorted' (exim)

       -bpru
           Same as '-bpu --unsorted' (exim)

       -bpu
           Same as -bp, but only show undelivered messages (exim)

       -c  Show a count of matching messages (exiqgrep)

       --caseful
           Make operators involving '=' honor case

       --charset
           Override the default local character set for $header_ decoding

       -f <regexp>
           Same as '$sender_address =~ /<regexp>/' (exiqgrep).  Note that this
           preserves the default case sensitivity of exiqgrep's interface.

       --finput
           Same as '--input-dir Finput'.  'Finput' is where exim copies frozen
           messages when compiled with SUPPORT_MOVE_FROZEN_MESSAGES.

       --flatq
           Use a single-line output format

       --freeze <cache file>
           Save queue information in an quickly retrievable format

       --help
           Display this output

       -i  Display only the message IDs (exiqgrep)

       --input-dir <inputname>
           Set the name of the directory under the spool directory.  By defaut
           this is "input".  If this starts with '/', the value of --spool is
           ignored.  See also --finput.

       -l  Same as -bp (exiqgrep)

       --not
           Negate all tests.

       -o <seconds>
           Same as '$message_age > <seconds>' (exiqgrep)

       --or
           Display messages matching any criteria

       -R  Same as --reverse (exiqgrep)

       -r <regexp>
           Same as '$recipients =~ /<regexp>/' (exiqgrep).  Note that this
           preserves the default case sensitivity of exiqgrep's interface.

       --random
           Display messages in random order

       --reverse
           Display messages in reverse order

       -s <string>
           Same as '$shown_message_size eq <string>' (exiqgrep)

       --spool <path>
           Set the path to the exim spool to use.  This value will have the
           argument to --input or 'input' appended, or be ignored if --input
           is a full path.

       --show-rules
           Show the internal representation of each criterion specified

       --show-tests
           Show the result of each criterion on each message

       --show-vars <variable>[,<variable>...]
           Show the value for <variable> for each displayed message.
           <variable> will be a regular expression if it begins with a
           circumflex.

       --size
           Show the total bytes used by each displayed message

       --thaw <cache file>
           Read queue information cached from a previous --freeze run

       --sort <variable>[,<variable>...]
           Display matching messages sorted according to <variable>

       --unsorted
           Do not apply any sorting to output

       --version
           Display the version of this command

       -x  Same as '!$deliver_freeze' (exiqgrep)

       -y  Same as '$message_age < <seconds>' (exiqgrep)

       -z  Same as '$deliver_freeze' (exiqgrep)

CRITERIA

       Exipick decides which messages to display by applying a test against
       each message.  The rules take the general form of 'VARIABLE OPERATOR
       VALUE'.  For example, '$message_age > 60'.  When exipick is deciding
       which messages to display, it checks the $message_age variable for each
       message.  If a message's age is greater than 60, the message will be
       displayed.  If the message's age is 60 or less seconds, it will not be
       displayed.

       Multiple criteria can be used.  The order they are specified does not
       matter.  By default all criteria must evaluate to true for a message to
       be displayed.  If the --or option is used, a message is displayed as
       long as any of the criteria evaluate to true.

       See the VARIABLES and OPERATORS sections below for more details

OPERATORS

       BOOLEAN
           Boolean variables are checked simply by being true or false.  There
           is no real operator except negation.  Examples of valid boolean
           tests:
             '$deliver_freeze'
             '!$deliver_freeze'

       NUMERIC
           Valid comparisons are <, <=, >, >=, ==, and !=.  Numbers can be
           integers or floats.  Any number in a test suffixed with d, h, m, s,
           M, K, or B will be mulitplied by 86400, 3600, 60, 1, 1048576, 1024,
           or 1 respectively.  Examples of valid numeric tests:
             '$message_age >= 3d'
             '$local_interface == 587'
             '$message_size < 30K'

       STRING
           The string operators are =, eq, ne, =~, and !~.  With the exception
           of '=', the operators all match the functionality of the like-named
           perl operators.  eq and ne match a string exactly.  !~, =~, and =
           apply a perl regular expression to a string.  The '=' operator
           behaves just like =~ but you are not required to place // around
           the regular expression.  Examples of valid string tests:
             '$received_protocol eq esmtp'
             '$sender_address = example.com'
             '$each_recipients =~ /^a[a-z]{2,3}@example.com$/'

       NEGATION
           There are many ways to negate tests, each having a reason for
           existing.  Many tests can be negated using native operators.  For
           instance, >1 is the opposite of <=1 and eq and ne are opposites.
           In addition, each individual test can be negated by adding a ! at
           the beginning of the test.  For instance, '!$acl_m1 =~ /^DENY$/' is
           the same as '$acl_m1 !~ /^DENY$/'.  Finally, every test can be
           specified by using the command line argument --not.  This is
           functionally equivilant to adding a ! to the beginning of every
           test.

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.

       Internally, all variables are represented as strings, meaning any
       operator will work on any variable.  This means that '$sender_host_name
       > 4' is a legal criterion, even if it does not produce meaningful
       results.  Variables in the list below are marked with a 'type' to help
       in choosing which types of operators make sense to use.

         Identifiers
           B - Boolean variables
           S - String variables
           N - Numeric variables
           . - Standard variable matching Exim's content definition
           # - Standard variable, contents differ from Exim's definition
           + - Non-standard variable

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

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

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

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

       S . $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.

       S . $bheader_*, $bh_*
           Value of the header(s) with the same name with any RFC2047 words
           decoded if present.  See section 11.5 of Exim's spec.txt for full
           details.

       S + $bmi_verdicts
           The verdict string provided by a Brightmail content scan

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

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

       S + $data_path
           The path to the body file's location in the filesystem.

       B + $deliver_freeze
           TRUE if the message is currently frozen.

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

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

       S + $each_recipients
           This is a psuedo variable which allows you to apply a test against
           each address in $recipients individually.  Whereas '$recipients =~
           /@aol.com/' will match if any recipient address contains aol.com,
           '$each_recipients =~ /@aol.com$/' will only be true 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.

       S + $each_recipients_del
           Like $each_recipients, but for $recipients_del

       S + $each_recipients_undel
           Like $each_recipients, but for $recipients_undel

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

       S . $header_*, $h_*
           This will always match the contents of the corresponding $bheader_*
           variable currently (the same behaviour Exim displays when iconv is
           not installed).

       S + $header_path
           The path to the header file's location in the filesystem.

       B . $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.

       B . $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.

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

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

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

       N . $max_received_linelength
           The number of bytes in the longest line that was received as part
           of the message, not counting line termination characters.

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

       S # $message_body
           The message's body.  Unlike Exim's variable of the same name, this
           variable contains the entire message body.  Newlines and nulls are
           replaced by spaces.

       B + $message_body_missing
           TRUE is a message's spool data file (-D file) is missing or
           unreadable.

       N . $message_body_size
           The size of the body in bytes.

       S . $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.

       S . $message_headers
           A concatenation of all the header lines except for lines added by
           routers or transports.  RFC2047 decoding is performed

       S . $message_headers_raw
           A concatenation of all the header lines except for lines added by
           routers or transports.  No decoding or translation is performed.

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

       N . $message_size
           The size of the message in bytes.

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

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

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

       S . $received_ip_address, $interface_address
           The address of the local IP interface for network-originated
           messages.  $interface_address is deprecated as of Exim 4.64

       N . $received_port, $interface_port
           The local port number if network-originated messages.
           $interface_port is deprecated as of Exim 4.64

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

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

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

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

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

       S + $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.  See also $each_recipients_del.

       N + $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.

       S + $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.  See also
           $each_recipients_undel.

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

       S . $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.

       S . $rheader_*, $rh_*
           The value of the message's header(s) with the same name.  See
           section 11.5 of Exim's spec.txt for full description.

       S . $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.

       S . $sender_address_domain
           The domain part of $sender_address.

       S . $sender_address_local_part
           The local part of $sender_address.

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

       S . $sender_host_address
           The remote host's IP address.

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

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

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

       S . $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.

       B + $sender_local
           TRUE if the message was locally generated.

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

       S + $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.

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

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

       S . $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)

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

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

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

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

CONTACT

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