Default variable details
========================

Some of ``debops.freeradius`` default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.

.. contents::
   :local:
   :depth: 1

.. _freeradius__ref_configuration:

freeradius__configuration
-------------------------

The ``freeradius__*_configuration`` variables define the contents of the
FreeRADIUS configuration files located in the :file:`/etc/freeradius/`
directory. The variables contain a list of YAML dictionaries, each dictionary
describes one "object" (file or symlink). The dictionaries with the same
``name`` parameter are merged together; it is possible to override existing
entries by later ones. This can be used to modify the configuration
conditionally.

Examples
~~~~~~~~

Define a custom :file:`radiusd.conf` configuration file with contents specified
in a YAML text block:

.. code-block:: yaml

   freeradius__configuration:

     - name: 'radiusd.conf'
       raw: |
         # Contents of the configuration file
         # ...
         # Contents of the configuration file
       state: 'present'

Enable the LDAP support via a symlink:

.. code-block:: yaml

   freeradius__configuration:

     - name: 'mods-enabled/ldap'
       link_src: '../mods-available/ldap'

Define custom client list with passwords in the configuration file; each
section can be modified separately in other configuration entries:

.. code-block:: yaml

   freeradius__configuration:

     - name: 'clients.conf'
       no_log: True
       options:

         - name: 'client_localhost'
           comment: |
             Local client, used for testing
           raw: |
             client localhost {
                 ipaddr = 127.0.0.1
                 secret = testing123
             }
           state: 'present'

         - name: 'client_ap_mgmt'
           raw: |
             client ap_mgmt {
                 ipaddr = 192.0.2.0/24
                 secret = pa$$word
             }
           state: 'present'

Include a directory from a config file:

.. code-block:: yaml

   freeradius__configuration:

     - name: 'custom.conf'
       comment: |
         Include custom configuration from a directory
       raw: |
         $INCLUDE custom-dir/
       state: 'present'

Syntax
~~~~~~

Each YAML dictionary entry can use specific set of parameters:

``name``
  Required. Name of the configuration file or symlink to manage. This parameter
  is used as an anchor to merge multiple configuration entries together.

  The specified configuration files are relative to the path defined in the
  :envvar:`freeradius__conf_base_path` variable. You need to specify the full
  filenames with extensions, you can specify files in subdirectories as normal.

``filename``
  Optional. An alternative filename to use instead of the one in ``name``.

``owner``
  Optional. Specify UNIX account which will be other owner of the generated
  file. If not specified, :envvar:`freeradius__user` will be the owner.

``group``
  Optional. Specify UNIX group of the generated file. If not specified,
  :envvar:`freeradius__group` will be set as the group.

``mode``
  Optional. Specify the file mode/attributes of the generated file. If not
  specified, ``0640`` will be used by default.

``divert``
  Optional, boolean. If ``True``, the role will use the :command:`dpkg-divert`
  command to move the original configuration file packaged in the
  ``freeradius-config`` APT package out of the way to preserve it for reference
  and to not create issues during package upgrades. The file will be reverted
  back when the ``state`` parameter is set to ``absent``.

  The role checks what files in the FreeRADIUS configuration directory are
  marked as Debian Conffiles and automatically diverts/reverts them as
  necessary. This parameter can be used to override this behaviour.

  The diverted files have a dot (``.``) prepended to them, this will ensure
  that `the files will be ignored`__ by the FreeRADIUS ``$INCLUDE dir/``
  directive.

  .. __: https://networkradius.com/doc/3.0.10/raddb/syntax/config_include.html

``divert_filename``
  Optional. An alternative name of the diverted file. This parameter can be
  used to override the name automatically generated by the role.

``link_src``
  If specified, the file defined in the ``name`` parameter will be a symlink to
  the file defined by this parameter. You can use relative paths, for example:

  .. code-block:: yaml

     freeradius__configuration:
       - name: 'sites-enabled/default'
         link_src: '../sites-available/default'

  If the ``state`` parameter is set to ``absent``, the symlink will be removed.

``raw``
  A string or YAML text block with FreeRADIUS configuration. It will be put in
  the generated configuration file as-is.

``options``
  An alternative way to specify the contents of the configuration file. This is
  a list of YAML dictionaries, each dictionary can use parameters:

  ``name``
    The name of the configuration section. If ``value`` parameter is present,
    it will be used as the variable name on the left side of the equal
    expression. If the ``raw`` parameter is present, the value of the ``name``
    parameter is not used in the configuration file. This parameter is used as
    an anchor to merge options from multiple configuration entries.

  ``value``
    If specified, it will be used as the value on the right site of the equal
    expression.

  ``raw``
    String or YAML text block with FireeRADIUS configuration. It will be put in
    the generated configuration file as-is.

  ``comment``
    String or YAML text block with comments about a given configuration
    section.

  ``state``
    If not specified or ``present``, a given configuration section will be
    included in the generated file. If ``absent``, a given configuration
    section will not be included in the configuration file. If ``ignore``,
    a given configuration entry will not be evaluated by the role.

  The ``options`` lists from multiple configuration entries are merged
  together. You can use this to create a FreeRADIUS configuration files from
  multiple parts that can be conditionally activated.

``state``
  Optional. If not specified or ``present``, a given configuration file or
  symlink will be created. If ``absent``, a given configuration file or symlink
  will be removed (original file will be reverted, if it was diverted). If
  ``ignore``, a given configuration entry will not be evaluated by the role.

``no_log``
  Optional, boolean. If ``True``, Ansible will not log the task for a given
  file. This is useful to enable when files contain passwords, so that they
  will not be leaked in the logs.

``comment``
  Optional. String or YAML text block with comments included at the beginning
  of the generated file.
