Provided by: exim4-base_4.90.1-1ubuntu1.10_amd64 
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 | --config <config>
Use <config> to determine the proper spool directory. (See "--spool" or "--input" for alternative
ways to specify the directories to operate on.)
-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 default 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. If not specified, exipick uses the value from
"exim [-C config] -n -bP spool_directory", and if this call fails, the /opt/exim/spool from build
time (Local/Makefile) is used. See also --config.
--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 multiplied 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 equivalent 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 pseudo 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
S . $tls_sni
The value of the Server Name Indication TLS extension sent by a client, if one was sent.
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