From b7c15c31519dc44c1f691e0466badd556ffe9423 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:18:56 +0200 Subject: Adding upstream version 3.7.10. Signed-off-by: Daniel Baumann --- html/postmulti.1.html | 409 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 html/postmulti.1.html (limited to 'html/postmulti.1.html') diff --git a/html/postmulti.1.html b/html/postmulti.1.html new file mode 100644 index 0000000..6456b92 --- /dev/null +++ b/html/postmulti.1.html @@ -0,0 +1,409 @@ + + + + Postfix manual - postmulti(1) + 
+POSTMULTI(1)                                                      POSTMULTI(1)
+
+NAME
+       postmulti - Postfix multi-instance manager
+
+SYNOPSIS
+   Enabling multi-instance management:
+
+       postmulti -e init [-v]
+
+   Iterator mode:
+
+       postmulti -l [-aRv] [-g group] [-i name]
+
+       postmulti -p [-av] [-g group] [-i name] postfix-command...
+
+       postmulti -x [-aRv] [-g group] [-i name] unix-command...
+
+   Life-cycle management:
+
+       postmulti -e create [-av] [-g group] [-i name] [-G group] [-I name]
+       [param=value ...]
+
+       postmulti -e import [-av] [-g group] [-i name] [-G group] [-I name]
+       [config_directory=/path]
+
+       postmulti -e destroy [-v] -i name
+
+       postmulti -e deport [-v] -i name
+
+       postmulti -e enable [-v] -i name
+
+       postmulti -e disable [-v] -i name
+
+       postmulti -e assign [-v] -i name [-I name] [-G group]
+
+DESCRIPTION
+       The  postmulti(1) command allows a Postfix administrator to manage mul-
+       tiple Postfix instances on a single host.
+
+       postmulti(1) implements two fundamental modes of operation.  In  itera-
+       tor  mode, it executes the same command for multiple Postfix instances.
+       In life-cycle management mode, it adds  or  deletes  one  instance,  or
+       changes the multi-instance status of one instance.
+
+       Each  mode  of  operation  has its own command syntax. For this reason,
+       each mode is documented in separate sections below.
+
+BACKGROUND
+       A  multi-instance  configuration  consists  of  one   primary   Postfix
+       instance,  and  one  or  more  secondary  instances whose configuration
+       directory pathnames are recorded  in  the  primary  instance's  main.cf
+       file. Postfix instances share program files and documentation, but have
+       their own configuration, queue and data directories.
+
+       Currently, only the default Postfix instance can  be  used  as  primary
+       instance  in  a  multi-instance configuration. The postmulti(1) command
+       does not currently support a -c option to select an alternative primary
+       instance,  and  exits with a fatal error if the MAIL_CONFIG environment
+       variable is set to a non-default configuration directory.
+
+       See the MULTI_INSTANCE_README tutorial for a more  detailed  discussion
+       of multi-instance management with postmulti(1).
+
+ITERATOR MODE
+       In  iterator mode, postmulti performs the same operation on all Postfix
+       instances in turn.
+
+       If multi-instance support is not enabled, the requested command is per-
+       formed just for the primary instance.
+
+       Iterator mode implements the following command options:
+
+Instance selection
+       -a     Perform the operation on all instances. This is the default.
+
+       -g group
+              Perform the operation only for members of the named group.
+
+       -i name
+              Perform  the  operation only for the instance with the specified
+              name.  You can specify either the instance name or the  absolute
+              pathname of the instance's configuration directory.  Specify "-"
+              to select the primary Postfix instance.
+
+       -R     Reverse the iteration order. This may be appropriate when updat-
+              ing  a multi-instance system, where "sink" instances are started
+              before "source" instances.
+
+              This option cannot be used with -p.
+
+List mode
+       -l     List Postfix instances with their instance name, instance  group
+              name, enable/disable status and configuration directory.
+
+Postfix-wrapper mode
+       -p postfix-command
+              Invoke  postfix(1)  to  execute  postfix-command.   This  option
+              implements the postfix-wrapper(5) interface.
+
+              o      With "start"-like commands, "postfix check"  is  executed
+                     for instances that are not enabled. The full list of com-
+                     mands  is  specified  with  the  postmulti_start_commands
+                     parameter.
+
+              o      With   "stop"-like   commands,  the  iteration  order  is
+                     reversed, and disabled instances are  skipped.  The  full
+                     list   of   commands   is   specified   with   the  post-
+                     multi_stop_commands parameter.
+
+              o      With "reload" and other commands that require  a  started
+                     instance,  disabled  instances are skipped. The full list
+                     of commands is specified with the  postmulti_control_com-
+                     mands parameter.
+
+              o      With  "status"  and  other  commands that don't require a
+                     started  instance,  the  command  is  executed  for   all
+                     instances.
+
+              The  -p option can also be used interactively to start/stop/etc.
+              a named instance or instance group. For example, to  start  just
+              the  instances  in  the group "msa", invoke postmulti(1) as fol-
+              lows:
+
+                     # postmulti -g msa -p start
+
+Command mode
+       -x unix-command
+              Execute the specified unix-command for  all  Postfix  instances.
+              The  command  runs  with  appropriate  environment  settings for
+              MAIL_CONFIG, command_directory, daemon_directory,  config_direc-
+              tory,   queue_directory,   data_directory,  multi_instance_name,
+              multi_instance_group and multi_instance_enable.
+
+Other options
+       -v     Enable verbose  logging  for  debugging  purposes.  Multiple  -v
+              options make the software increasingly verbose.
+
+LIFE-CYCLE MANAGEMENT MODE
+       With  the -e option postmulti(1) can be used to add or delete a Postfix
+       instance, and to  manage  the  multi-instance  status  of  an  existing
+       instance.
+
+       The following options are implemented:
+
+Existing instance selection
+       -a     When  creating  or importing an instance, place the new instance
+              at the front of the secondary instance list.
+
+       -g group
+              When creating or importing an instance, place the  new  instance
+              before  the  first  secondary  instance  that is a member of the
+              specified group.
+
+       -i name
+              When creating or importing an instance, place the  new  instance
+              before the matching secondary instance.
+
+              With  other  life-cycle  operations,  apply the operation to the
+              named existing instance.  Specify  "-"  to  select  the  primary
+              Postfix instance.
+
+New or existing instance name assignment
+       -I name
+              Assign  the  specified  instance  name  to an existing instance,
+              newly-created instance, or imported  instance.   Instance  names
+              other  than "-" (which makes the instance "nameless") must start
+              with "postfix-".  This restriction  reduces  the  likelihood  of
+              name collisions with system files.
+
+       -G group
+              Assign  the specified group name to an existing instance or to a
+              newly created or imported instance.
+
+Instance creation/deletion/status change
+       -e action
+              "Edit" managed instances. The following actions are supported:
+
+              init   This command is required before postmulti(1) can be  used
+                     to  manage  Postfix  instances.   The "postmulti -e init"
+                     command updates the primary instance's  main.cf  file  by
+                     setting:
+
+                            multi_instance_wrapper =
+                                    ${command_directory}/postmulti -p --
+                            multi_instance_enable = yes
+
+                     You can set these by other means if you prefer.
+
+              create Create   a  new  Postfix  instance  and  add  it  to  the
+                     multi_instance_directories  parameter  of   the   primary
+                     instance.   The  "-I  name" option is recommended to give
+                     the instance a short  name  that  is  used  to  construct
+                     default  values  for  the  private directories of the new
+                     instance. The "-G  group"  option  may  be  specified  to
+                     assign  the  instance  to  a  group,  otherwise,  the new
+                     instance is not a member of any group.
+
+                     The new instance main.cf is the stock  main.cf  with  the
+                     parameters  that  specify  the  locations of shared files
+                     cloned  from  the  primary  instance.    For   "nameless"
+                     instances,  you  should  manually adjust "syslog_name" to
+                     yield a unique "logtag"  starting  with  "postfix-"  that
+                     will  uniquely identify the instance in the mail logs. It
+                     is simpler to assign the instance a short name  with  the
+                     "-I name" option.
+
+                     Optional "name=value" arguments specify the instance con-
+                     fig_directory, queue_directory and  data_directory.   For
+                     example:
+
+                            # postmulti -I postfix-mumble \
+                                    -G mygroup -e create \
+                                    config_directory=/my/config/dir \
+                                    queue_directory=/my/queue/dir \
+                                    data_directory=/my/data/dir
+
+                     If  any  of  these pathnames is not supplied, the program
+                     attempts to generate the missing  pathname(s)  by  taking
+                     the  corresponding primary instance pathname, and replac-
+                     ing the last pathname component by the value  of  the  -I
+                     option.
+
+                     If  the  instance configuration directory already exists,
+                     and contains both a main.cf and  master.cf  file,  create
+                     will "import" the instance as-is. For existing instances,
+                     create and import are identical.
+
+              import Import an existing instance into the  list  of  instances
+                     managed by the postmulti(1) multi-instance manager.  This
+                     adds the instance to the multi_instance_directories  list
+                     of the primary instance.  If the "-I name" option is pro-
+                     vided it specifies the new name for the instance  and  is
+                     used  to  define a default location for the instance con-
+                     figuration directory (as with  create  above).   The  "-G
+                     group"  option  may  be  used to assign the instance to a
+                     group. Add a "config_directory=/path" argument  to  over-
+                     ride a default pathname based on "-I name".
+
+              destroy
+                     Destroy  a  secondary Postfix instance. To be a candidate
+                     for destruction an instance must be disabled, stopped and
+                     its  queue  must  not  contain  any messages. Attempts to
+                     destroy the primary  Postfix  instance  trigger  a  fatal
+                     error, without destroying the instance.
+
+                     The instance is removed from the primary instance main.cf
+                     file's  alternate_config_directories  parameter  and  its
+                     data,  queue and configuration directories are cleaned of
+                     files and directories created by the Postfix system.  The
+                     main.cf and master.cf files are removed from the configu-
+                     ration directory even if they have  been  modified  since
+                     initial  creation.  Finally,  the  instance is "deported"
+                     from the list of managed instances.
+
+                     If other files are present in instance  private  directo-
+                     ries, the directories may not be fully removed, a warning
+                     is logged to alert the administrator. It is expected that
+                     an  instance built using "fresh" directories via the cre-
+                     ate action will be fully removed by  the  destroy  action
+                     (if  first  disabled).  If the instance configuration and
+                     queue directories are  populated  with  additional  files
+                     (access  and rewriting tables, chroot jail content, etc.)
+                     the instance directories will not be fully removed.
+
+                     The destroy action triggers  potentially  dangerous  file
+                     removal  operations. Make sure the instance's data, queue
+                     and configuration directories are set  correctly  and  do
+                     not contain any valuable files.
+
+              deport Deport  a  secondary  instance  from  the list of managed
+                     instances. This deletes the instance configuration direc-
+                     tory  from the primary instance's multi_instance_directo-
+                     ries list, but does not remove any files or  directories.
+
+              assign Assign  a  new  instance  name or a new group name to the
+                     selected instance.  Use "-G -" to specify "no group"  and
+                     "-I  -"  to  specify "no name".  If you choose to make an
+                     instance "nameless", set a suitable  syslog_name  in  the
+                     corresponding main.cf file.
+
+              enable Mark the selected instance as enabled. This just sets the
+                     multi_instance_enable   parameter   to   "yes"   in   the
+                     instance's main.cf file.
+
+              disable
+                     Mark  the  selected instance as disabled. This means that
+                     the instance will  not  be  started  etc.  with  "postfix
+                     start",  "postmulti -p start" and so on. The instance can
+                     still be started etc. with "postfix  -c  config-directory
+                     start".
+
+Other options
+       -v     Enable  verbose  logging  for  debugging  purposes.  Multiple -v
+              options make the software increasingly verbose.
+
+ENVIRONMENT
+       The postmulti(1) command exports the  following  environment  variables
+       before executing the requested command for a given instance:
+
+       MAIL_VERBOSE
+              This is set when the -v command-line option is present.
+
+       MAIL_CONFIG
+              The location of the configuration directory of the instance.
+
+CONFIGURATION PARAMETERS
+       config_directory (see 'postconf -d' output)
+              The  default  location of the Postfix main.cf and master.cf con-
+              figuration files.
+
+       daemon_directory (see 'postconf -d' output)
+              The directory with Postfix support programs and daemon programs.
+
+       import_environment (see 'postconf -d' output)
+              The  list  of  environment  variables  that a privileged Postfix
+              process will  import  from  a  non-Postfix  parent  process,  or
+              name=value environment overrides.
+
+       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_group (empty)
+              The optional instance group name of this Postfix instance.
+
+       multi_instance_name (empty)
+              The optional instance name of this Postfix instance.
+
+       multi_instance_enable (no)
+              Allow  this  Postfix instance to be started, stopped, etc., by a
+              multi-instance manager.
+
+       postmulti_start_commands (start)
+              The postfix(1) commands that the postmulti(1)  instance  manager
+              treats as "start" commands.
+
+       postmulti_stop_commands (see 'postconf -d' output)
+              The  postfix(1)  commands that the postmulti(1) instance manager
+              treats as "stop" commands.
+
+       postmulti_control_commands (reload flush)
+              The postfix(1) commands that the postmulti(1)  instance  manager
+              treats as "control" commands, that operate on running instances.
+
+       syslog_facility (mail)
+              The syslog facility of Postfix logging.
+
+       syslog_name (see 'postconf -d' output)
+              A prefix that  is  prepended  to  the  process  name  in  syslog
+              records, so that, for example, "smtpd" becomes "prefix/smtpd".
+
+       Available in Postfix 3.0 and later:
+
+       meta_directory (see 'postconf -d' output)
+              The  location of non-executable files that are shared among mul-
+              tiple Postfix instances, such as postfix-files,  dynamicmaps.cf,
+              and  the  multi-instance  template  files main.cf.proto and mas-
+              ter.cf.proto.
+
+       shlib_directory (see 'postconf -d' output)
+              The location of Postfix dynamically-linked  libraries  (libpost-
+              fix-*.so),  and the default location of Postfix database plugins
+              (postfix-*.so) that have  a  relative  pathname  in  the  dynam-
+              icmaps.cf file.
+
+FILES
+       $meta_directory/main.cf.proto, stock configuration file
+       $meta_directory/master.cf.proto, stock configuration file
+       $daemon_directory/postmulti-script, life-cycle helper program
+
+SEE ALSO
+       postfix(1), Postfix control program
+       postfix-wrapper(5), Postfix multi-instance API
+
+README FILES
+       MULTI_INSTANCE_README, Postfix multi-instance management
+
+HISTORY
+       The postmulti(1) command was introduced with Postfix version 2.6.
+
+LICENSE
+       The Secure Mailer license must be distributed with this software.
+
+AUTHOR(S)
+       Victor Duchovni
+       Morgan Stanley
+
+       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
+
+                                                                  POSTMULTI(1)
+
-- cgit v1.2.3