    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.

                  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)