{
    "mode": "info",
    "parameter": "POSTFIX-WRAPPER",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/POSTFIX-WRAPPER/json",
    "generated": "2026-07-05T23:46:00Z",
    "sections": {
        "NAME": {
            "content": "postfix-wrapper - Postfix multi-instance API\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Support for managing multiple Postfix instances is available as of ver-\nsion 2.6. Instances share executable files and documentation, but  have\ntheir own directories for configuration, queue and data files.\n\nThis  document describes how the familiar \"postfix start\" etc. user in-\nterface can be used to manage one or multiple  Postfix  instances,  and\ngives details of an API to coordinate activities between the postfix(1)\ncommand and a multi-instance manager program.\n\nWith multi-instance support, the default Postfix instance is always re-\nquired. This instance is identified by the configdirectory parameter's\ndefault value.\n",
            "subsections": []
        },
        "GENERAL OPERATION": {
            "content": "Multi-instance support is backwards compatible: when you run  only  one\nPostfix  instance, commands such as \"postfix start\" will not change be-\nhavior at all.\n\nEven with multiple Postfix instances, you can keep using the same post-\nfix commands in boot scripts, upgrade procedures, and other places. The\ncommands do more work, but humans are not forced to learn new tricks.\n\nFor example, to start all Postfix instances, use:\n\n# postfix start\n\nOther postfix(1) commands also work as expected. For example,  to  find\nout  what  Postfix  instances  exist in a multi-instance configuration,\nuse:\n\n# postfix status\n\nThis enumerates the status of all Postfix instances within a  multi-in-\nstance configuration.\n",
            "subsections": []
        },
        "MANAGING AN INDIVIDUAL POSTFIX INSTANCE": {
            "content": "To manage a specific Postfix instance, specify its configuration direc-\ntory on the postfix(1) command line:\n\n# postfix -c /path/to/configdirectory command\n\nAlternatively, the postfix(1) command accepts the instance's configura-\ntion  directory  via  the MAILCONFIG environment variable (the -c com-\nmand-line option has higher precedence).\n\nOtherwise, the postfix(1) command  will  operate  on  all  Postfix  in-\nstances.\n\nENABLING POSTFIX(1) MULTI-INSTANCE MODE\nBy default, the postfix(1) command operates in single-instance mode. In\nthis mode the command invokes the postfix-script  file  directly  (cur-\nrently installed in the daemon directory).  This file contains the com-\nmands that start or stop one Postfix instance, that upgrade the config-\nuration of one Postfix instance, and so on.\n\nWhen  the  postfix(1)  command  operates in multi-instance mode as dis-\ncussed below, the command needs to execute start, stop, etc.   commands\nfor  each Postfix instance.  This multiplication of commands is handled\nby a multi-instance manager program.\n\nTurning on postfix(1) multi-instance mode goes as follows: in  the  de-\nfault  Postfix  instance's  main.cf  file, 1) specify the pathname of a\nmulti-instance manager program with the multiinstancewrapper  parame-\nter; 2) populate the multiinstancedirectories parameter with the con-\nfiguration directory pathnames of additional  Postfix  instances.   For\nexample:\n\n/etc/postfix/main.cf:\nmultiinstancewrapper = $daemondirectory/postfix-wrapper\nmultiinstancedirectories = /etc/postfix-test\n\nThe  $daemondirectory/postfix-wrapper file implements a simple manager\nand contains instructions for creating Postfix instances by hand.   The\npostmulti(1) command provides a more extensive implementation including\nsupport for life-cycle management.\n\nThe multiinstancedirectories and other main.cf parameters are  listed\nbelow in the CONFIGURATION PARAMETERS section.\n\nIn  multi-instance  mode, the postfix(1) command invokes the $multiin-\nstancewrapper  command  instead  of  the  postfix-script  file.   This\nmulti-instance  manager in turn executes the postfix(1) command in sin-\ngle-instance mode for each Postfix instance.\n\nTo illustrate the main ideas behind multi-instance operation, below  is\nan  example  of  a simple but useful multi-instance manager implementa-\ntion:\n\n#!/bin/sh\n\n: ${commanddirectory?\"do not invoke this command directly\"}\n\nPOSTCONF=$commanddirectory/postconf\nPOSTFIX=$commanddirectory/postfix\ninstancedirs=`$POSTCONF -h multiinstancedirectories |\nsed 's/,/ /'` || exit 1\n\nerr=0\nfor dir in $configdirectory $instancedirs\ndo\ncase \"$1\" in\nstop|abort|flush|reload|drain)\ntest \"`$POSTCONF -c $dir -h multiinstanceenable`\" \\\n= yes || continue;;\nstart)\ntest \"`$POSTCONF -c $dir -h multiinstanceenable`\" \\\n= yes || {\n$POSTFIX -c $dir check || err=$?\ncontinue\n};;\nesac\n$POSTFIX -c $dir \"$@\" || err=$?\ndone\n\nexit $err\n",
            "subsections": []
        },
        "PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS": {
            "content": "Each Postfix instance has its own main.cf  file  with  parameters  that\ncontrol how the multi-instance manager operates on that instance.  This\nsection discusses the most important settings.\n\nThe setting \"multiinstanceenable =  yes\"  allows  the  multi-instance\nmanager  to  start (stop, etc.) the corresponding Postfix instance. For\nsafety reasons, this setting is not the default.\n\nThe default setting \"multiinstanceenable = no\" is useful  for  manual\ntesting  with  \"postfix  -c  /path/name start\" etc.  The multi-instance\nmanager will not start such an instance, and it will skip commands such\nas  \"stop\"  or  \"flush\"  that  require a running Postfix instance.  The\nmulti-instance manager will execute commands such as \"check\", \"set-per-\nmissions\"  or  \"upgrade-configuration\",  and it will replace \"start\" by\n\"check\" so that problems will be reported even  when  the  instance  is\ndisabled.\n",
            "subsections": []
        },
        "MAINTAINING SHARED AND NON-SHARED FILES": {
            "content": "Some  files  are  shared between Postfix instances, such as executables\nand manpages, and some files are per-instance,  such  as  configuration\nfiles, mail queue files, and data files.  See the NON-SHARED FILES sec-\ntion below for a list of per-instance files.\n\nBefore Postfix multi-instance support was implemented, the executables,\nmanpages,  etc.,  have  always  been  maintained as part of the default\nPostfix instance.\n\nWith multi-instance support, we simply continue to do  this.   Specifi-\ncally,  a  Postfix  instance will not check or update shared files when\nthat instance's configdirectory  value  is  listed  with  the  default\nmain.cf file's multiinstancedirectories parameter.\n\nThe  consequence  of this approach is that the default Postfix instance\nshould be checked and updated before any other instances.\n",
            "subsections": []
        },
        "MULTI-INSTANCE API SUMMARY": {
            "content": "Only the multi-instance manager implements support  for  the  multiin-\nstanceenable  configuration parameter. The multi-instance manager will\nstart only Postfix instances whose main.cf file has \"multiinstanceen-\nable  =  yes\". A setting of \"no\" allows a Postfix instance to be tested\nby hand.\n\nThe postfix(1) command operates on only one Postfix instance  when  the\n-c  option  is specified, or when MAILCONFIG is present in the process\nenvironment. This is necessary to terminate recursion.\n\nOtherwise,  when  the  multiinstancedirectories  parameter  value  is\nnon-empty,  the  postfix(1) command executes the command specified with\nthe multiinstancewrapper parameter, instead of executing the commands\nin postfix-script.\n\nThe  multi-instance  manager  skips commands such as \"stop\" or \"reload\"\nthat require a running Postfix instance, when an instance does not have\n\"multiinstanceenable = yes\".  This avoids false error messages.\n\nThe multi-instance manager replaces a \"start\" command by \"check\" when a\nPostfix instance's main.cf file does not have \"multiinstanceenable  =\nyes\".  This  substitution  ensures  that problems will be reported even\nwhen the instance is disabled.\n\nNo Postfix command or script will update or check shared files when its\nconfigdirectory  value  is  listed  in the default main.cf's multiin-\nstancedirectories parameter value.  Therefore,  the  default  instance\nshould  be checked and updated before any Postfix instances that depend\non it.\n\nSet-gid commands such as postdrop(1) and postqueue(1)  effectively  ap-\npend  the  multiinstancedirectories parameter value to the legacy al-\nternateconfigdirectories parameter value. The commands use  this  in-\nformation  to  determine whether a -c option or MAILCONFIG environment\nsetting specifies a legitimate value.\n\nThe legacy alternateconfigdirectories parameter remains necessary for\nnon-default  Postfix  instances  that are running different versions of\nPostfix, or that are not managed together with the default Postfix  in-\nstance.\n",
            "subsections": []
        },
        "ENVIRONMENT VARIABLES": {
            "content": "MAILCONFIG\nWhen present, this forces the postfix(1) command to operate only\non the specified Postfix instance. This environment variable  is\nexported  by  the  postfix(1) -c option, so that postfix(1) com-\nmands in descendant processes will work correctly.\n",
            "subsections": []
        },
        "CONFIGURATION PARAMETERS": {
            "content": "The text below provides only a parameter summary. See  postconf(5)  for\nmore details.\n\nmultiinstancedirectories (empty)\nAn  optional  list of non-default Postfix configuration directo-\nries; these directories belong to additional  Postfix  instances\nthat  share  the Postfix executable files and documentation with\nthe default Postfix instance, and  that  are  started,  stopped,\netc., together with the default Postfix instance.\n\nmultiinstancewrapper (empty)\nThe  pathname of a multi-instance manager command that the post-\nfix(1) command invokes when the  multiinstancedirectories  pa-\nrameter value is non-empty.\n\nmultiinstancename (empty)\nThe optional instance name of this Postfix instance.\n\nmultiinstancegroup (empty)\nThe optional instance group name of this Postfix instance.\n\nmultiinstanceenable (no)\nAllow  this  Postfix instance to be started, stopped, etc., by a\nmulti-instance manager.\n",
            "subsections": []
        },
        "NON-SHARED FILES": {
            "content": "configdirectory (see 'postconf -d' output)\nThe default location of the Postfix main.cf and  master.cf  con-\nfiguration files.\n\ndatadirectory (see 'postconf -d' output)\nThe  directory  with  Postfix-writable  data files (for example:\ncaches, pseudo-random numbers).\n\nqueuedirectory (see 'postconf -d' output)\nThe location of the Postfix top-level queue directory.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "postfix(1) Postfix control program\npostmulti(1) full-blown multi-instance manager\n$daemondirectory/postfix-wrapper simple multi-instance manager\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "The Secure Mailer license must be distributed with this software.\n\nAUTHOR(S)\nWietse Venema\nIBM T.J. Watson Research\nP.O. Box 704\nYorktown Heights, NY 10598, USA\n\nWietse Venema\nGoogle, Inc.\n111 8th Avenue\nNew York, NY 10011, USA\n\nPOSTFIX-WRAPPER(5)",
            "subsections": []
        }
    },
    "summary": "postfix-wrapper - Postfix multi-instance API",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "postfix",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/postfix/1/json"
        },
        {
            "name": "postmulti",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/postmulti/1/json"
        }
    ]
}