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

DIAGNOSTICS

237       Problems are reported to the standard error stream and to syslogd(8) or
238       postlogd(8).
239
240       postsuper(1) reports the number of messages deleted with -d, the number
241       of messages expired with -e, the number of messages expired or released
242       with  -f,  the  number  of messages held or released with -h or -H, the
243       number of messages requeued with -r, and the number of  messages  whose
244       queue  file  name was fixed with -s. The report is written to the stan‐
245       dard error stream and to syslogd(8) or postlogd(8).
246

ENVIRONMENT

248       MAIL_CONFIG
249              Directory with the main.cf file.
250

BUGS

252       Mail that is not sanitized by Postfix (i.e. mail in the maildrop queue)
253       cannot be placed "on hold".
254

CONFIGURATION PARAMETERS

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

SEE ALSO

293       sendmail(1), Sendmail-compatible user interface
294       postqueue(1), unprivileged queue operations
295       postlogd(8), Postfix logging
296       syslogd(8), system logging
297

LICENSE

299       The Secure Mailer license must be distributed with this software.
300

AUTHOR(S)

302       Wietse Venema
303       IBM T.J. Watson Research
304       P.O. Box 704
305       Yorktown Heights, NY 10598, USA
306
307       Wietse Venema
308       Google, Inc.
309       111 8th Avenue
310       New York, NY 10011, USA
311
312
313
314                                                                  POSTSUPER(1)
Impressum