.. _configuration: ===================== Configuring Mailman ===================== Mailman is configured via an "ini"-style configuration file, usually called ``mailman.cfg``. Most of the defaults produce a usable system, but you will almost certainly have to set up a few things before you run Mailman for the first time. You only need to include those settings which you want to change; everything else is inherited. These file system paths are searched in the following order to find your site's custom ``mailman.cfg`` file. The first file found is used. * The file system path specified by the environment variable ``$MAILMAN_CONFIG_FILE`` * ``mailman.cfg`` in the current working directory * ``var/etc/mailman.cfg`` relative to the current working directory * ``$HOME/.mailman.cfg`` * ``/etc/mailman.cfg`` * ``/etc/mailman3/mailman.cfg`` * ``../../etc/mailman.cfg`` relative to the working directory of ``argv[0]`` You can also use the ``-C`` option to specify an explicit path, and this always takes precedence. See ``mailman --help`` for more details. You **must** restart Mailman for any changes to take effect. Which configuration file is in use? =================================== Mailman itself will tell you which configuration file is being used when you run the ``mailman info`` command:: $ mailman info GNU Mailman 3.1.0b4 (Between The Wheels) Python 3.5.3 (default, Jan 19 2017, 14:11:04) [GCC 6.3.0 20170118] config file: /home/mailman/var/etc/mailman.cfg db url: sqlite:////home/mailman/var/data/mailman.db devmode: DISABLED REST root url: http://localhost:8001/3.1/ REST credentials: restadmin:restpass The first time you run this command it will create the configuration file and directory using the built-in defaults, so use ``-C`` to specify an alternative location. Of course the ``info`` subcommand shows you other interesting things about your Mailman instance. Schemas, templates, and master sections ======================================= Mailman's configuration system is built on top of `lazr.config `_ although in general the details aren't important. Basically there is a ``schema.cfg`` file included in the source tree, which defines all the available sections and variables, along with global defaults. There is a built-in base ``mailman.cfg`` file also included in the source tree, which further refines the defaults. Your custom ``mailman.cfg`` file, found using the search locations described above, provides the final override for these settings. The ``schema.cfg`` file describes every section, variable, and permissible values, so you should consult this for more details. The ``schema.cfg`` file is included verbatim below. You will notice two types of special sections in the ``schema.cfg`` files; those that end with the ``.template`` suffix, and others which end in a ``.master`` suffix. There are no other special sections. Templates provide exactly that: a template for other similarly named sections. So for example, you will see a section labeled ``logging.template`` which provides some configuration variables and some basic defaults. You will also see a section called ``logging.bounce`` which refines the ``logging.template`` section by overriding one or more settings. If you wanted to change the default logging level for the database component in Mailman, say from ``warn`` to ``info``, you would add this to your ``mailman.cfg`` file:: [logging.database] level: info Generally you won't add new template specialization sections; everything you need is already defined. You will also see sections labeled with the ``.master`` suffix. For the most part you can treat these exactly the same as ``.template`` sections; the differences are only relevant for Mailman developers [#]_. An example of a ``.master`` section is ``[runner.master]`` which is used to define the defaults for all the :ref:`runner processes `. This is specialized in the built-in ``mailman.cfg`` file, where you'll see sections like ``[runner.archive]`` and ``[runner.in]``. You won't need to specially the master section yourself, but instead you can override some settings in the individual runner sections. How do I change a setting? ========================== If you think you want to change something, it can be a little tricky to find exactly the setting you'll need. The first step is to use the ``mailman conf`` command to print all the current variables and their values. With no options, this will print all the hundreds of (sorted!) available settings to standard output. You can narrow this down in two ways. You can print just the values of a particular section:: $ mailman conf -s webservice [webservice] admin_pass: restpass [webservice] admin_user: restadmin [webservice] api_version: 3.1 [webservice] hostname: localhost [webservice] port: 8001 [webservice] show_tracebacks: yes [webservice] use_https: no Let's say you wanted to change the port the REST API listens on. Just add this to your ``mailman.cfg`` file:: [webservice] port: 8080 You can also search for a specific setting:: $ mailman conf -k prompt [shell] prompt: >>> The ``mailman conf`` command does not provide documentation about sections or variables. In order to get more information about what a particular variable controls, read the ``schema.cfg`` and built-in base ``mailman.cfg`` file. Configuration Options ===================== .. configsection:: mailman shell database webservice mta devmode bounces ARC antispam styles digests nntp dmarc schema.cfg ========== ``schema.cfg`` defines the ini-file schema and contains documentation for every section and configuration variable. .. literalinclude:: ../schema.cfg mailman.cfg =========== Configuration settings provided in the built-in base ``mailman.cfg`` file overrides those provided in ``schema.cfg``. .. literalinclude:: ../mailman.cfg .. [#] The technical differences are described in the `lazr.config `_ package, upon which Mailman's configuration system is based.