POSTSUPER(1)                                         POSTSUPER(1)

NAME
       postsuper - Postfix superintendent

SYNOPSIS
       postsuper [-psv] [-c config_dir] [-d queue_id]
               [-h queue_id] [-H queue_id]
               [-r queue_id] [directory ...]

DESCRIPTION
       The postsuper command does maintenance jobs on the Postfix
       queue. Use of the command is restricted to the  superuser.
       See  the  postqueue  command for unprivileged queue opera-
       tions such as listing or flushing the mail queue.

       By default, postsuper performs  the  operations  requested
       with  the  -s  and  -p command-line options on all Postfix
       queue directories - this includes the incoming, active and
       deferred  directories  with  mail  files  and  the bounce,
       defer, trace and flush directories with log files.

       Options:

       -c config_dir
              The main.cf configuration  file  is  in  the  named
              directory  instead  of  the  default  configuration
              directory. See  also  the  MAIL_CONFIG  environment
              setting below.

       -d queue_id
              Delete one message with the named queue ID from the
              named  mail  queue(s)  (default:  hold,   incoming,
              active and deferred).  If a queue_id of - is speci-
              fied, the program reads  queue  IDs  from  standard
              input.  For  example, to delete all mail from or to
              user@example.com:

              mailq | tail +2 | awk  'BEGIN { RS = "" } \
                  / user@example\.com$/ { print $1 } \
              ' | tr -d '*!' | postsuper -d -

              Specify -d ALL to remove all messages; for example,
              specify  -d  ALL  deferred  to  delete  mail in the
              deferred queue.  As a safety measure, the word  ALL
              must be specified in upper case.

              Warning:  Postfix queue IDs are reused.  There is a
              very small possibility that postsuper  deletes  the
              wrong  message  file  when it is executed while the
              Postfix mail system is delivering mail.

              The scenario is as follows:

              1)     The Postfix queue manager deletes  the  mes-
                     sage  that  postsuper  is  asked  to delete,
                     because Postfix is finished with the message
                     (it  is  delivered, or it is returned to the
                     sender).

              2)     New mail arrives, and  the  new  message  is
                     given  the same queue ID as the message that
                     postsuper is supposed to delete.  The proba-
                     bility  for  reusing  a  deleted queue ID is
                     about 1 in 2**15 (the  number  of  different
                     microsecond values that the system clock can
                     distinguish within a second).

              3)     postsuper deletes the new  message,  instead
                     of  the  old  message  that  it  should have
                     deleted.

       -h queue_id
              Put mail "on hold" so that no attempt  is  made  to
              deliver  it.  Move one message with the named queue
              ID from the named mail queue(s) (default: incoming,
              active  and  deferred)  to  the  hold  queue.  If a
              queue_id of - is specified, the program reads queue
              IDs from standard input.

              Specify  -h  ALL to hold all messages; for example,
              specify  -h  ALL  deferred  to  hold  mail  in  the
              deferred  queue.  As a safety measure, the word ALL
              must be specified in upper case.

              Note: while mail is "on hold" it  will  not  expire
              when  its  time  in  the  queue  exceeds  the maxi-
              mal_queue_lifetime  or  bounce_queue_lifetime  set-
              ting.  It becomes subject to expiration after it is
              released from "hold".

       -H queue_id
              Release mail that was put "on hold".  Move one mes-
              sage  with  the  named queue ID from the named mail
              queue(s) (default: hold) to the deferred queue.  If
              a  queue_id  of  -  is specified, the program reads
              queue IDs from standard input.

              Note: use "postsuper -r" to release mail  that  was
              kept  on  hold for a significant fraction of $maxi-
              mal_queue_lifetime  or  $bounce_queue_lifetime,  or
              longer.

              Specify  -H  ALL  to  release  all mail that is "on
              hold".  As a safety measure, the word ALL  must  be
              specified in upper case.

       -p     Purge  old temporary files that are left over after
              system or software crashes.

       -r queue_id
              Requeue the message with the named  queue  ID  from
              the  named  mail queue(s) (default: hold, incoming,
              active and deferred).   To  requeue  multiple  mes-
              sages,  specify  multiple  -r command-line options.
              Alternatively, if a queue_id of - is specified, the
              program reads queue IDs from standard input.

              Specify -r ALL to requeue all messages. As a safety
              measure, the word ALL must be  specified  in  upper
              case.

              A  requeued message is moved to the maildrop queue,
              from where it is copied by the pickup daemon  to  a
              new  file whose name is guaranteed to match the new
              queue file inode number. The new queue file is sub-
              jected  again to mail address rewriting and substi-
              tution. This is useful when rewriting rules or vir-
              tual mappings have changed.

              Warning:  Postfix queue IDs are reused.  There is a
              very small possibility that postsuper requeues  the
              wrong  message  file  when it is executed while the
              Postfix mail system is running, but no harm  should
              be done.

       -s     Structure  check and structure repair.  This should
              be done once before Postfix startup.

              o      Rename files whose name does not  match  the
                     message file inode number. This operation is
                     necessary after restoring a mail queue  from
                     a different machine, or from backup media.

              o      Move queue files that are in the wrong place
                     in the file system hierarchy and remove sub-
                     directories that are no longer needed.  File
                     position rearrangements are necessary  after
                     a  change  in  the  hash_queue_names  and/or
                     hash_queue_depth configuration parameters.

       -v     Enable verbose logging for debugging purposes. Mul-
              tiple  -v  options  make  the software increasingly
              verbose.

DIAGNOSTICS
       Problems are reported to the standard error stream and  to
       syslogd(8).

       postsuper  reports the number of messages deleted with -d,
       the number of messages requeued with -r, and the number of
       messages  whose  queue  file  name  was fixed with -s. The
       report is written to the standard error stream and to sys-
       logd(8).

ENVIRONMENT
       MAIL_CONFIG
              Directory with the main.cf file.

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

CONFIGURATION PARAMETERS
       The following main.cf parameters are  especially  relevant
       to this program.  The text below provides only a parameter
       summary. See postconf(5) for more details including  exam-
       ples.

       config_directory (see 'postconf -d' output)
              The  default  location  of  the Postfix main.cf and
              master.cf configuration files.

       hash_queue_depth (1)
              The number of subdirectory levels for queue  direc-
              tories  listed with the hash_queue_names parameter.

       hash_queue_names (see 'postconf -d' output)
              The names  of  queue  directories  that  are  split
              across multiple subdirectory levels.

       queue_directory (see 'postconf -d' output)
              The  location of the Postfix top-level queue direc-
              tory.

       syslog_facility (mail)
              The syslog facility of Postfix logging.

       syslog_name (postfix)
              The mail system name that is prepended to the  pro-
              cess  name  in  syslog  records,  so  that  "smtpd"
              becomes, for example, "postfix/smtpd".

SEE ALSO
       sendmail(1), Sendmail-compatible user interface
       postqueue(1), unprivileged queue operations

LICENSE
       The Secure Mailer license must be  distributed  with  this
       software.

AUTHOR(S)
       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA

                                                     POSTSUPER(1)