From b5896ba9f6047e7031e2bdee0622d543e11a6734 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 03:46:30 +0200 Subject: Adding upstream version 3.4.23. Signed-off-by: Daniel Baumann --- html/postfix-wrapper.5.html | 272 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 html/postfix-wrapper.5.html (limited to 'html/postfix-wrapper.5.html') diff --git a/html/postfix-wrapper.5.html b/html/postfix-wrapper.5.html new file mode 100644 index 0000000..d9a8ba4 --- /dev/null +++ b/html/postfix-wrapper.5.html @@ -0,0 +1,272 @@ + + + + Postfix manual - postfix-wrapper(5) + 
+POSTFIX-WRAPPER(5)                                          POSTFIX-WRAPPER(5)
+
+NAME
+       postfix-wrapper - Postfix multi-instance API
+
+DESCRIPTION
+       Support for managing multiple Postfix instances is available as of ver-
+       sion 2.6. Instances share executable files and documentation, but  have
+       their own directories for configuration, queue and data files.
+
+       This  document  describes  how  the  familiar "postfix start" etc. user
+       interface can be used to manage one or multiple Postfix instances,  and
+       gives details of an API to coordinate activities between the postfix(1)
+       command and a multi-instance manager program.
+
+       With multi-instance support, the default  Postfix  instance  is  always
+       required.  This  instance is identified by the config_directory parame-
+       ter's default value.
+
+GENERAL OPERATION
+       Multi-instance support is backwards compatible: when you run  only  one
+       Postfix  instance,  commands  such  as  "postfix start" will not change
+       behavior at all.
+
+       Even with multiple Postfix instances, you can keep using the same post-
+       fix commands in boot scripts, upgrade procedures, and other places. The
+       commands do more work, but humans are not forced to learn new tricks.
+
+       For example, to start all Postfix instances, use:
+
+              # postfix start
+
+       Other postfix(1) commands also work as expected. For example,  to  find
+       out  what  Postfix  instances  exist in a multi-instance configuration,
+       use:
+
+              # postfix status
+
+       This  enumerates  the  status  of  all  Postfix  instances   within   a
+       multi-instance configuration.
+
+MANAGING AN INDIVIDUAL POSTFIX INSTANCE
+       To manage a specific Postfix instance, specify its configuration direc-
+       tory on the postfix(1) command line:
+
+              # postfix -c /path/to/config_directory command
+
+       Alternatively, the postfix(1) command accepts the instance's configura-
+       tion  directory  via  the MAIL_CONFIG environment variable (the -c com-
+       mand-line option has higher precedence).
+
+       Otherwise,  the  postfix(1)  command  will  operate  on   all   Postfix
+       instances.
+
+ENABLING POSTFIX(1) MULTI-INSTANCE MODE
+       By default, the postfix(1) command operates in single-instance mode. In
+       this mode the command invokes the postfix-script  file  directly  (cur-
+       rently installed in the daemon directory).  This file contains the com-
+       mands that start or stop one Postfix instance, that upgrade the config-
+       uration of one Postfix instance, and so on.
+
+       When  the  postfix(1)  command  operates in multi-instance mode as dis-
+       cussed below, the command needs to execute start, stop, etc.   commands
+       for  each Postfix instance.  This multiplication of commands is handled
+       by a multi-instance manager program.
+
+       Turning on postfix(1) multi-instance  mode  goes  as  follows:  in  the
+       default  Postfix  instance's main.cf file, 1) specify the pathname of a
+       multi-instance manager program with the multi_instance_wrapper  parame-
+       ter; 2) populate the multi_instance_directories parameter with the con-
+       figuration directory pathnames of additional  Postfix  instances.   For
+       example:
+
+              /etc/postfix/main.cf:
+                  multi_instance_wrapper = $daemon_directory/postfix-wrapper
+                  multi_instance_directories = /etc/postfix-test
+
+       The  $daemon_directory/postfix-wrapper file implements a simple manager
+       and contains instructions for creating Postfix instances by hand.   The
+       postmulti(1) command provides a more extensive implementation including
+       support for life-cycle management.
+
+       The multi_instance_directories and other main.cf parameters are  listed
+       below in the CONFIGURATION PARAMETERS section.
+
+       In   multi-instance   mode,   the   postfix(1)   command   invokes  the
+       $multi_instance_wrapper command instead  of  the  postfix-script  file.
+       This  multi-instance manager in turn executes the postfix(1) command in
+       single-instance mode for each Postfix instance.
+
+       To illustrate the main ideas behind multi-instance operation, below  is
+       an  example  of  a simple but useful multi-instance manager implementa-
+       tion:
+
+              #!/bin/sh
+
+              : ${command_directory?"do not invoke this command directly"}
+
+              POSTCONF=$command_directory/postconf
+              POSTFIX=$command_directory/postfix
+              instance_dirs=`$POSTCONF -h multi_instance_directories |
+                              sed 's/,/ /'` || exit 1
+
+              err=0
+              for dir in $config_directory $instance_dirs
+              do
+                  case "$1" in
+                  stop|abort|flush|reload|drain)
+                      test "`$POSTCONF -c $dir -h multi_instance_enable`" \
+                          = yes || continue;;
+                  start)
+                      test "`$POSTCONF -c $dir -h multi_instance_enable`" \
+                          = yes || {
+                          $POSTFIX -c $dir check || err=$?
+                          continue
+                      };;
+                  esac
+                  $POSTFIX -c $dir "$@" || err=$?
+              done
+
+              exit $err
+
+PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS
+       Each Postfix instance has its own main.cf  file  with  parameters  that
+       control how the multi-instance manager operates on that instance.  This
+       section discusses the most important settings.
+
+       The setting "multi_instance_enable =  yes"  allows  the  multi-instance
+       manager  to  start (stop, etc.) the corresponding Postfix instance. For
+       safety reasons, this setting is not the default.
+
+       The default setting "multi_instance_enable = no" is useful  for  manual
+       testing  with  "postfix  -c  /path/name start" etc.  The multi-instance
+       manager will not start such an instance, and it will skip commands such
+       as  "stop"  or  "flush"  that  require a running Postfix instance.  The
+       multi-instance manager will execute commands such as "check", "set-per-
+       missions"  or  "upgrade-configuration",  and it will replace "start" by
+       "check" so that problems will be reported even  when  the  instance  is
+       disabled.
+
+MAINTAINING SHARED AND NON-SHARED FILES
+       Some  files  are  shared between Postfix instances, such as executables
+       and manpages, and some files are per-instance,  such  as  configuration
+       files, mail queue files, and data files.  See the NON-SHARED FILES sec-
+       tion below for a list of per-instance files.
+
+       Before Postfix multi-instance support was implemented, the executables,
+       manpages,  etc.,  have  always  been  maintained as part of the default
+       Postfix instance.
+
+       With multi-instance support, we simply continue to do  this.   Specifi-
+       cally,  a  Postfix  instance will not check or update shared files when
+       that instance's config_directory  value  is  listed  with  the  default
+       main.cf file's multi_instance_directories parameter.
+
+       The  consequence  of this approach is that the default Postfix instance
+       should be checked and updated before any other instances.
+
+MULTI-INSTANCE API SUMMARY
+       Only  the   multi-instance   manager   implements   support   for   the
+       multi_instance_enable  configuration parameter. The multi-instance man-
+       ager  will  start  only  Postfix  instances  whose  main.cf  file   has
+       "multi_instance_enable  =  yes".  A  setting  of  "no" allows a Postfix
+       instance to be tested by hand.
+
+       The postfix(1) command operates on only one Postfix instance  when  the
+       -c  option  is specified, or when MAIL_CONFIG is present in the process
+       environment. This is necessary to terminate recursion.
+
+       Otherwise,  when  the  multi_instance_directories  parameter  value  is
+       non-empty,  the  postfix(1) command executes the command specified with
+       the multi_instance_wrapper parameter, instead of executing the commands
+       in postfix-script.
+
+       The  multi-instance  manager  skips commands such as "stop" or "reload"
+       that require a running Postfix instance, when an instance does not have
+       "multi_instance_enable = yes".  This avoids false error messages.
+
+       The multi-instance manager replaces a "start" command by "check" when a
+       Postfix instance's main.cf file does not have "multi_instance_enable  =
+       yes".  This  substitution  ensures  that problems will be reported even
+       when the instance is disabled.
+
+       No Postfix command or script will update or check shared files when its
+       config_directory   value   is   listed   in   the   default   main.cf's
+       multi_instance_directories parameter  value.   Therefore,  the  default
+       instance  should  be  checked  and updated before any Postfix instances
+       that depend on it.
+
+       Set-gid commands  such  as  postdrop(1)  and  postqueue(1)  effectively
+       append  the  multi_instance_directories  parameter  value to the legacy
+       alternate_config_directories parameter value.  The  commands  use  this
+       information to determine whether a -c option or MAIL_CONFIG environment
+       setting specifies a legitimate value.
+
+       The legacy alternate_config_directories parameter remains necessary for
+       non-default  Postfix  instances  that are running different versions of
+       Postfix, or that are not managed  together  with  the  default  Postfix
+       instance.
+
+ENVIRONMENT VARIABLES
+       MAIL_CONFIG
+              When present, this forces the postfix(1) command to operate only
+              on the specified Postfix instance. This environment variable  is
+              exported  by  the  postfix(1) -c option, so that postfix(1) com-
+              mands in descendant processes will work correctly.
+
+CONFIGURATION PARAMETERS
+       The text below provides only a parameter summary. See  postconf(5)  for
+       more details.
+
+       multi_instance_directories (empty)
+              An  optional  list of non-default Postfix configuration directo-
+              ries; these directories belong to additional  Postfix  instances
+              that  share  the Postfix executable files and documentation with
+              the default Postfix instance, and  that  are  started,  stopped,
+              etc., together with the default Postfix instance.
+
+       multi_instance_wrapper (empty)
+              The  pathname of a multi-instance manager command that the post-
+              fix(1)  command  invokes  when  the   multi_instance_directories
+              parameter value is non-empty.
+
+       multi_instance_name (empty)
+              The optional instance name of this Postfix instance.
+
+       multi_instance_group (empty)
+              The optional instance group name of this Postfix instance.
+
+       multi_instance_enable (no)
+              Allow  this  Postfix instance to be started, stopped, etc., by a
+              multi-instance manager.
+
+NON-SHARED FILES
+       config_directory (see 'postconf -d' output)
+              The default location of the Postfix main.cf and  master.cf  con-
+              figuration files.
+
+       data_directory (see 'postconf -d' output)
+              The  directory  with  Postfix-writable  data files (for example:
+              caches, pseudo-random numbers).
+
+       queue_directory (see 'postconf -d' output)
+              The location of the Postfix top-level queue directory.
+
+SEE ALSO
+       postfix(1) Postfix control program
+       postmulti(1) full-blown multi-instance manager
+       $daemon_directory/postfix-wrapper simple multi-instance manager
+
+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
+
+       Wietse Venema
+       Google, Inc.
+       111 8th Avenue
+       New York, NY 10011, USA
+
+                                                            POSTFIX-WRAPPER(5)
+
-- cgit v1.2.3