..  GENERATED FILE, DO NOT EDIT DIRECTLY

    This file is automatically generated using https://codeberg.org/slidge/legacy-module-template/
    Its source is at:
    https://codeberg.org/slidge/legacy-module-template/src/branch/main/docs/source/admin/config.rst.jinja
    Open a pull request for this repository instead, to benefit the documentation of all slidge-based gateways.

.. _config:

Configuration
=============

Both
:ref:`matridge-specific options <config-matridge>` and
:ref:`slidge generic options <generic-config>`
can be set using
:ref:`config text file(s) <config-file>`,
:ref:`command-line arguments <config-cli>`,
or :ref:`environment variables <config-env>`.

.. _config-file:

Config files
************

Location
--------

By default, matridge uses all config files found in ``/etc/slidge/conf.d/*.conf``.
You can change this using the ``SLIDGE_CONF_DIR`` env var, eg
``SLIDGE_CONF_DIR=/path/dir1:/path/dir2:/path/dir3``.

We recommend using ``/etc/slidge/conf.d/common.conf`` file to set
the options common to several slidge-based gateways
(eg, attachment handling, logging options, etc.),
then use a matridge-specific dedicated config file, eg
``/etc/slidge/matridge.conf``.

Point to this specific file using the ``-c`` command line argument when
launching matridge.

.. code-block:: bash

    matridge -c /etc/slidge/matridge.conf


Syntax
------

Config files are simple text files with ``key=value`` entries.

.. code-block::

    some-option=some-value
    some-other-option=some-other-value

.. _config-cli:

Command-line arguments
**********************

To pass options as command-line arguments, prepend their name with ``--``.

.. code-block::

    matridge --some-option=some-value --some-other-option=some-other-value

.. _config-env:

Environment variables
*********************

To pass options as environment variables:

* uppercase their name;
* substitue dashed for underscores;
* prepend with ``SLIDGE_`` for :ref:`generic slidge options <generic-config>`,
  or ``MATRIDGE_`` for
  :ref:`matridge-specific options <config-matridge>`.

.. code-block::

    SLIDGE_SOME_GENERIC_OPTION=some-value
    MATRIDGE_SOME_SPECIFIC_OPTION=some-other-value

.. _config-matridge:

matridge-specific config
************************

matridge provides the instance-wide options displayed in the table below.

.. config-obj:: matridge.config

.. _generic-config:

Generic slidge config
*********************

.. note::

    The following options are for slidge version |slidge_version|.
    Depending on how you installed matridge, you might have a different version of slidge.
    Use ``matridge --help`` for the exact list of options you can use.

Slidge provides the generic instance-wide options displayed in the table below.
They may not all have an effect on matridge's behaviour.

.. config-obj:: slidge.core.config


Advanced logging configuration
******************************

To customize the output of the slidge, you can use the command line argument ``--log-config``
to specify a `logging configuration file
<https://docs.python.org/3/library/logging.config.html#configuration-file-format>`_.
