diff options
Diffstat (limited to 'src/mailman/config/docs')
| -rw-r--r-- | src/mailman/config/docs/config.rst | 140 |
1 files changed, 120 insertions, 20 deletions
diff --git a/src/mailman/config/docs/config.rst b/src/mailman/config/docs/config.rst index 16c3d40bc..796e82fa8 100644 --- a/src/mailman/config/docs/config.rst +++ b/src/mailman/config/docs/config.rst @@ -4,38 +4,139 @@ Configuring Mailman ===================== -This is Mailman's default configuration, directly included from the source -code. The format is standard "ini"-style. +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. -You can override these in your configuration to modify the behavior of Mailman -Core. To override these settings, these file system paths are search in -order: +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; + ``$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/mailman.cfg`` relative to the working directory of ``argv[0]`` -You only need to include the settings you want to override. They must be -specified inside the appropriate section. For example, to override the "no -reply address" only, put this in your ``mailman.cfg`` file:: +You can also use the ``-C`` option to specify an explicit path, and this +always takes precedence. See ``mailman --help`` for more details. - [mailman] - noreply_address: ignore@example.com +You **must** restart Mailman for any changes to take effect. -You will need to 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 +<http://pythonhosted.org/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 <runners>`. 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. schema.cfg ========== ``schema.cfg`` defines the ini-file schema and contains documentation for -every section and configuration variable. Sections that are named with a -suffix of ``.master`` or ``.template`` (e.g. ``paths.master``) are "template" -sections which must be defined in the ``mailman.cfg`` file [#]_. +every section and configuration variable. .. literalinclude:: ../schema.cfg @@ -43,9 +144,8 @@ sections which must be defined in the ``mailman.cfg`` file [#]_. mailman.cfg =========== -Configuration options provided in the source code's ``mailman.cfg`` override -those provided in ``schema.cfg``. Your own ``mailman.cfg`` file overrides -these. +Configuration settings provided in the built-in base ``mailman.cfg`` file +overrides those provided in ``schema.cfg``. .. literalinclude:: ../mailman.cfg |