From 5e61585d76ae77fd5e9e96ebabb57afa4d74880d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 14:06:34 +0200 Subject: Adding upstream version 3.5.24. Signed-off-by: Daniel Baumann --- html/postmulti.1.html | 408 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 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..0115b9f --- /dev/null +++ b/html/postmulti.1.html @@ -0,0 +1,408 @@ + + + + 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 groups.
+
+                     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 pathname by  taking  the  corre-
+                     sponding  primary instance pathname, and by replacing 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 parameters  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