1POSTSUPER(1)                General Commands Manual               POSTSUPER(1)
2
3
4

NAME

6       postsuper - Postfix superintendent
7

SYNOPSIS

9       postsuper [-psSv]
10               [-c config_dir] [-d queue_id]
11               [-e queue_id] [-f queue_id]
12               [-h queue_id] [-H queue_id]
13               [-r queue_id] [directory ...]
14

DESCRIPTION

16       The  postsuper(1)  command  does maintenance jobs on the Postfix queue.
17       Use  of  the  command  is  restricted  to  the  superuser.    See   the
18       postqueue(1)  command for unprivileged queue operations such as listing
19       or flushing the mail queue.
20
21       By default, postsuper(1) performs the operations requested with the  -s
22       and  -p  command-line  options  on all Postfix queue directories - this
23       includes the incoming, active, deferred, and hold directories with mes‐
24       sage  files and the bounce, defer, trace and flush directories with log
25       files.
26
27       Options:
28
29       -c config_dir
30              The main.cf configuration file is in the named directory instead
31              of the default configuration directory. See also the MAIL_CONFIG
32              environment setting below.
33
34       -d queue_id
35              Delete one message with the named queue ID from the  named  mail
36              queue(s) (default: hold, incoming, active and deferred).
37
38              To  delete multiple files, specify the -d option multiple times,
39              or specify a queue_id of -  to  read  queue  IDs  from  standard
40              input.  For example, to delete all mail with exactly one recipi‐
41              ent user@example.com:
42
43              mailq | tail -n +2 | grep -v '^ *(' | awk  'BEGIN { RS = "" }
44                  # $7=sender, $8=recipient1, $9=recipient2
45                  { if ($8 == "user@example.com" && $9 == "")
46                        print $1 }
47               ' | tr -d '*!' | postsuper -d -
48
49              Specify "-d ALL" to remove all messages;  for  example,  specify
50              "-d  ALL deferred" to delete all mail in the deferred queue.  As
51              a safety measure, the word ALL must be specified in upper case.
52
53              Warning: Postfix queue IDs are reused (always  with  Postfix  <=
54              2.8;  and  with  Postfix  >= 2.9 when enable_long_queue_ids=no).
55              There is a very small possibility  that  postsuper  deletes  the
56              wrong  message  file  when it is executed while the Postfix mail
57              system is delivering mail.
58
59              The scenario is as follows:
60
61              1)     The Postfix queue manager deletes the message that  post‐
62                     super(1)  is asked to delete, because Postfix is finished
63                     with the message (it is delivered, or it is  returned  to
64                     the sender).
65
66              2)     New  mail  arrives, and the new message is given the same
67                     queue ID as the message that postsuper(1) is supposed  to
68                     delete.   The  probability for reusing a deleted queue ID
69                     is about 1 in 2**15 (the number of different  microsecond
70                     values  that  the  system  clock can distinguish within a
71                     second).
72
73              3)     postsuper(1) deletes the new message, instead of the  old
74                     message that it should have deleted.
75
76       -e queue_id
77
78       -f queue_id
79              Request  forced  expiration for one message with the named queue
80              ID in the named mail queue(s) (default: hold,  incoming,  active
81              and deferred).
82
83              ·      The message will be returned to the sender when the queue
84                     manager attempts to deliver that message (note that Post‐
85                     fix will never deliver messages in the hold queue).
86
87              ·      The -e and -f options both request forced expiration. The
88                     difference is that -f will also release a message  if  it
89                     is  in  the hold queue. With -e, such a message would not
90                     be returned to the sender until it is released with -f or
91                     -H.
92
93              ·      When a deferred message is force-expired, the return mes‐
94                     sage will state the reason for the delay. Otherwise,  the
95                     reason will be "message is administratively expired".
96
97              To  expire  multiple files, specify the -e or -f option multiple
98              times, or specify a queue_id of - to read queue IDs  from  stan‐
99              dard  input (see the -d option above for an example, but be sure
100              to replace -d in the example).
101
102              Specify "-e ALL" or "-f ALL" to expire all messages;  for  exam‐
103              ple,  specify  "-e  ALL  deferred"  to  expire  all  mail in the
104              deferred queue.  As a safety measure, the word ALL must be spec‐
105              ified in upper case.
106
107              These features are available in Postfix 3.5 and later.
108
109       -h queue_id
110              Put  mail  "on  hold"  so that no attempt is made to deliver it.
111              Move one message with the named queue ID  from  the  named  mail
112              queue(s)  (default:  incoming,  active and deferred) to the hold
113              queue.
114
115              To hold multiple files, specify the -h option multiple times, or
116              specify a queue_id of - to read queue IDs from standard input.
117
118              Specify  "-h ALL" to hold all messages; for example, specify "-h
119              ALL deferred" to hold all mail in  the  deferred  queue.   As  a
120              safety measure, the word ALL must be specified in upper case.
121
122              Note:  while  mail is "on hold" it will not expire when its time
123              in   the   queue   exceeds   the    maximal_queue_lifetime    or
124              bounce_queue_lifetime  setting. It becomes subject to expiration
125              after it is released from "hold".
126
127              This feature is available in Postfix 2.0 and later.
128
129       -H queue_id
130              Release mail that was put "on hold".  Move one message with  the
131              named  queue  ID from the named mail queue(s) (default: hold) to
132              the deferred queue.
133
134              To release multiple files, specify the -H option multiple times,
135              or  specify  a  queue_id  of  -  to read queue IDs from standard
136              input.
137
138              Note: specify "postsuper -r" to release mail that  was  kept  on
139              hold  for  a  significant fraction of $maximal_queue_lifetime or
140              $bounce_queue_lifetime, or longer.
141
142              Specify "-H ALL" to release all mail that is "on  hold".   As  a
143              safety measure, the word ALL must be specified in upper case.
144
145              This feature is available in Postfix 2.0 and later.
146
147       -p     Purge  old  temporary  files  that are left over after system or
148              software crashes.  The -p, -s, and -S operations are done before
149              other operations.
150
151       -r queue_id
152              Requeue  the message with the named queue ID from the named mail
153              queue(s) (default: hold, incoming, active and deferred).
154
155              To requeue multiple files, specify the -r option multiple times,
156              or  specify  a  queue_id  of  -  to read queue IDs from standard
157              input.
158
159              Specify "-r ALL" to requeue all messages. As a  safety  measure,
160              the word ALL must be specified in upper case.
161
162              A requeued message is moved to the maildrop queue, from where it
163              is copied by the pickup(8) and cleanup(8) daemons to a new queue
164              file.  In  many respects its handling differs from that of a new
165              local submission.
166
167              ·      The message is not  subjected  to  the  smtpd_milters  or
168                     non_smtpd_milters settings.  When mail has passed through
169                     an external content filter, this would produce  incorrect
170                     results  with Milter applications that depend on original
171                     SMTP connection state information.
172
173              ·      The message is subjected again to mail address  rewriting
174                     and substitution.  This is useful when rewriting rules or
175                     virtual mappings have changed.
176
177                     The address rewriting context (local or  remote)  is  the
178                     same as when the message was received.
179
180              ·      The  message is subjected to the same content_filter set‐
181                     tings (if any) as used for new  local  mail  submissions.
182                     This is useful when content_filter settings have changed.
183
184              Warning:  Postfix  queue  IDs are reused (always with Postfix <=
185              2.8; and with Postfix  >=  2.9  when  enable_long_queue_ids=no).
186              There is a very small possibility that postsuper(1) requeues the
187              wrong message file when it is executed while  the  Postfix  mail
188              system is running, but no harm should be done.
189
190              This feature is available in Postfix 1.1 and later.
191
192       -s     Structure  check and structure repair.  This should be done once
193              before Postfix startup.  The -p, -s, and -S operations are  done
194              before other operations.
195
196              ·      Rename  files  whose name does not match the message file
197                     inode number. This operation is necessary after restoring
198                     a  mail  queue  from  a different machine or from backup,
199                     when queue files were created with Postfix <= 2.8 or with
200                     "enable_long_queue_ids = no".
201
202              ·      Move  queue files that are in the wrong place in the file
203                     system hierarchy and remove subdirectories  that  are  no
204                     longer  needed.   File position rearrangements are neces‐
205                     sary  after  a  change  in  the  hash_queue_names  and/or
206                     hash_queue_depth configuration parameters.
207
208              ·      Rename  queue files created with "enable_long_queue_ids =
209                     yes" to short names, for migration  to  Postfix  <=  2.8.
210                     The procedure is as follows:
211
212                     # postfix stop
213                     # postconf enable_long_queue_ids=no
214                     # postsuper
215
216                     Run postsuper(1) repeatedly until it stops reporting file
217                     name changes.
218
219       -S     A redundant version of -s that requires  that  long  file  names
220              also match the message file inode number. This option exists for
221              testing purposes, and is available with Postfix 2.9  and  later.
222              The -p, -s, and -S operations are done before other operations.
223
224       -v     Enable  verbose  logging  for  debugging  purposes.  Multiple -v
225              options make the software increasingly verbose.
226

DIAGNOSTICS

228       Problems are reported to the standard error stream and to syslogd(8) or
229       postlogd(8).
230
231       postsuper(1) reports the number of messages deleted with -d, the number
232       of messages expired with -e, the number of messages expired or released
233       with  -f,  the  number  of messages held or released with -h or -H, the
234       number of messages requeued with -r, and the number of  messages  whose
235       queue  file  name was fixed with -s. The report is written to the stan‐
236       dard error stream and to syslogd(8) or postlogd(8).
237

ENVIRONMENT

239       MAIL_CONFIG
240              Directory with the main.cf file.
241

BUGS

243       Mail that is not sanitized by Postfix (i.e. mail in the maildrop queue)
244       cannot be placed "on hold".
245

CONFIGURATION PARAMETERS

247       The  following  main.cf parameters are especially relevant to this pro‐
248       gram.  The text below provides only  a  parameter  summary.  See  post‐
249       conf(5) for more details including examples.
250
251       config_directory (see 'postconf -d' output)
252              The  default  location of the Postfix main.cf and master.cf con‐
253              figuration files.
254
255       hash_queue_depth (1)
256              The number of subdirectory levels for queue  directories  listed
257              with the hash_queue_names parameter.
258
259       hash_queue_names (deferred, defer)
260              The  names  of  queue directories that are split across multiple
261              subdirectory levels.
262
263       import_environment (see 'postconf -d' output)
264              The list of environment parameters  that  a  privileged  Postfix
265              process  will  import  from  a  non-Postfix  parent  process, or
266              name=value environment overrides.
267
268       queue_directory (see 'postconf -d' output)
269              The location of the Postfix top-level queue directory.
270
271       syslog_facility (mail)
272              The syslog facility of Postfix logging.
273
274       syslog_name (see 'postconf -d' output)
275              A prefix that  is  prepended  to  the  process  name  in  syslog
276              records, so that, for example, "smtpd" becomes "prefix/smtpd".
277
278       Available in Postfix version 2.9 and later:
279
280       enable_long_queue_ids (no)
281              Enable long, non-repeating, queue IDs (queue file names).
282

SEE ALSO

284       sendmail(1), Sendmail-compatible user interface
285       postqueue(1), unprivileged queue operations
286       postlogd(8), Postfix logging
287       syslogd(8), system logging
288

LICENSE

290       The Secure Mailer license must be distributed with this software.
291

AUTHOR(S)

293       Wietse Venema
294       IBM T.J. Watson Research
295       P.O. Box 704
296       Yorktown Heights, NY 10598, USA
297
298       Wietse Venema
299       Google, Inc.
300       111 8th Avenue
301       New York, NY 10011, USA
302
303
304
305                                                                  POSTSUPER(1)
Impressum