contrib/sendmail/contrib/qtool.8

   1 .\" Copyright (c) 1999, 2001-2002 Sendmail, Inc. and its suppliers.
   2 .\"      All rights reserved.
   3 .\"
   4 .\" By using this file, you agree to the terms and conditions set
   5 .\" forth in the LICENSE file which can be found at the top level of
   6 .\" the sendmail distribution.
   7 .\"
   8 .\"
   9 .\"     $Id: qtool.8,v 8.17 2002/01/29 21:55:49 ca Exp $
  10 .\"
  11 .TH QTOOL 8 "$Date: 2002/01/29 21:55:49 $"
  12 .SH NAME
  13 qtool
  14 \- manipulate sendmail queues
  15 .SH SYNOPSIS
  16 .B qtool.pl
  17 .RB [options]
  18 target_directory source [source ...]
  19 .PP
  20 .B qtool.pl [-Q][-d|-b]
  21 .RB [options]
  22 source [source ...]
  23 .SH DESCRIPTION
  24 .B Qtool
  25 moves the queue files used by sendmail between queues. It uses the same
  26 locking mechanism as sendmail so can be safely used while sendmail is
  27 running.
  28 However, it should not be used when queue groups have been configured
  29 to move queue files into directories to which they do not belong according
  30 to the queue group selections made in the sendmail.cf file.
  31 Unless you are absolutely sure you do not interfere with the queue group
  32 selection mechanism, do not move queue files around.
  33 .PP
  34 With no options,
  35 .B qtool
  36 will move any queue files as specified by \fIsource\fP into
  37 \fItarget_directory\fP. \fISource\fP can be either an individual
  38 queue control file, a queue file id, or a queue directory.
  39 .PP
  40 If the -d option is specified, qtool will delete the messages specified by
  41 source instead of moving them.
  42 .PP
  43 If the -b option is specified, the selected messages will be bounced by
  44 running sendmail with the -OTimeout.queuereturn=now option.
  45 .SS Options
  46 .TP
  47 \fB\-b\fP
  48 Bounce all of the messages specified by source. The messages will be bounced
  49 immediately. No attempt will be made to deliver the messages.
  50 .TP
  51 \fB\-C\fP configfile
  52 Specify the sendmail config file.
  53 Defaults to /etc/mail/sendmail.cf.
  54 .TP
  55 \fB\-d\fP
  56 Delete all of the messages specified by source.
  57 .TP
  58 \fB\-e\fP \fIperl_expression\fP
  59 Evalute \fIperl_expression\fP for each queue file as specified
  60 by \fIsource\fP. If \fIperl_expression\fP evaluates to true, then that
  61 queue file is moved. See below for more detail on \fIperl_expression\fP.
  62 .TP
  63 \fB\-Q\fP
  64 Operate on quarantined items
  65 (queue control file begins with hf instead of qf).
  66 .TP
  67 \fB\-s\fP \fIseconds\fP
  68 Move only the queue files specified by \fIsource\fP that have a
  69 modification time older than \fIseconds\fP.
  70 .SS Perl Expressions
  71 You can use any valid perl expression. Inside the expression you have
  72 access to a hash that contains many of the fields in the control file as
  73 well as some other data about that queued message. The hash is called
  74 \fI%msg\fP. If a field has multiple values (e.g. 'Recipient'), it will be
  75 returned as an array, otherwise it will be returned as a scalar. Through
  76 \fI%msg\fP, you can access the following variables:
  77 .TP
  78 \fBauth\fP
  79 AUTH= parameter.
  80 .TP
  81 \fBbody_type\fP
  82 Body type (\fB8BITMIME\fP, \fB7BIT\fP, or undefined).
  83 .TP
  84 \fBbody_last_mod_time\fP
  85 The last time the body was modified since the epoch in seconds.
  86 .TP
  87 \fBbody_size\fP
  88 The size of the body file in bytes.
  89 .TP
  90 \fBcontent-length\fP
  91 Content-Length: header value (Solaris sendmail only).
  92 .TP
  93 \fBcontrolling_user\fP
  94 The controlling user.
  95 .TP
  96 \fBcontrol_last_mod_time\fP
  97 The last time the control file was modified since the epoch in seconds.
  98 .TP
  99 \fBcontrol_size\fP
 100 The size of the control file in bytes.
 101 .TP
 102 \fBcreation_time\fP
 103 The time when the control file was created.
 104 .TP
 105 \fBcurrent_delay\fP
 106 Current delay for queue delay algorithm if _FFR_QUEUEDELAY is enabled.
 107 .TP
 108 \fBdata_file_name\fP
 109 The data file name (deprecated).
 110 .TP
 111 \fBdeliver_by\fP
 112 Deliver by flag and deadline for DELIVERBY ESMTP extension.
 113 .TP
 114 \fBenvid\fP
 115 Original envelope id form ESMTP.
 116 .TP
 117 \fBerror_recipient\fP
 118 The error recipient (deprecated).
 119 .TP
 120 \fBfinal_recipient\fP
 121 Final recipient (for DSNs).
 122 .TP
 123 \fBflags\fP
 124 Array of characters that can be the following values:
 125 .PD 0
 126 .RS +8
 127 .TP 8
 128 w
 129 warning message has been sent
 130 .TP 8
 131 r
 132 This is an error response or DSN
 133 .TP 8
 134 8
 135 has 8 bit data in body
 136 .TP 8
 137 b
 138 delete Bcc: headers
 139 .TP 8
 140 d
 141 envelope has DSN RET= parameter
 142 .TP 8
 143 n
 144 don't return body
 145 .PD
 146 .RE
 147 .TP
 148 \fBheaders\fP
 149 This is a Perl hash where the keys are rfc822 field names and the values
 150 are rfc822 field values. If a field has only one value it will be returned
 151 as a string. If a field has more than one value (e.g. 'Received') it will
 152 be returned as a list of strings.
 153 .TP
 154 \fBinode_number\fP
 155 The inode number for the data (body) file.
 156 .TP
 157 \fBnext_delivery_time\fP
 158 Earliest time of next delivery attempt.
 159 .TP
 160 \fBnum_delivery_attempts\fP
 161 Number of delivery attempts that have been made.
 162 .TP
 163 \fBmacro\fP
 164 Defined macro.
 165 .TP
 166 \fBmessage\fP
 167 Envelope status message.
 168 .TP
 169 \fBoriginal_recipient\fP
 170 Original recipient (ORCPT= parameter).
 171 .TP
 172 \fBpriority\fP
 173 Adjusted priority of message.
 174 .TP
 175 \fBquarantine_reason\fP
 176 Quarantine reason for quarantined (held) envelopes if _FFR_QUARANTINE is
 177 enabled.
 178 .TP
 179 \fBqueue_delay\fP
 180 Queue delay algorithm if _FFR_QUEUEDELAY is enabled.
 181 .TP
 182 \fBrecipient\fP
 183 Array of character flags followed by colon and recipient name. Flags:
 184 .PD 0
 185 .RS +8
 186 .TP 8
 187 N
 188 Has NOTIFY= parameter.
 189 .TP 8
 190 S
 191 Success DSN requested.
 192 .TP 8
 193 F
 194 Failure DSN requested.
 195 .TP 8
 196 D
 197 Delay DSN requested.
 198 .TP 8
 199 P
 200 Primary address (not the result of alias/forward expansion).
 201 .PD
 202 .RE
 203 .TP
 204 \fBsender\fP
 205 Sender
 206 .TP
 207 \fBversion\fP
 208 Version of control file.
 209 .SH EXAMPLES
 210 .TP
 211 \fBqtool.pl q2 q1\fP
 212 Moves all of the queue files in queue q1 to queue q2.
 213 .TP
 214 \fBqtool.pl q2 q1/d6CLQh100847\fP
 215 Moves the message with id d6CLQh100847 in queue q1 to queue q2.
 216 .TP
 217 \fBqtool.pl q2 q1/qfd6CLQh100847\fP
 218 Moves the message with id d6CLQh100847 in queue q1 to queue q2.
 219 .TP
 220 \fBqtool.pl -e '$msg{num_delivery_attempts} == 3' /q2 /q1\fP
 221 Moves all of the queue files that have had three attempted deliveries from
 222 queue q1 to queue q2.
 223 .SH BUGS
 224 In sendmail 8.12, it is possible for a message's queue and data files (df)
 225 to be stored in different queues.
 226 In this situation, you must give qtool the pathname of the queue file,
 227 not of the data file (df).
 228 To be safe, never feed qtool the pathname of a data file (df).
 229 .SH SEE ALSO
 230 sendmail(8)
 231 .SH HISTORY
 232 The
 233 .B qtool
 234 command appeared in
 235 sendmail 8.10.