Custom configuration placeholder
================================


LemonLDAP::NG optionally supports the ``%SERVERENV:VariableName%`` syntax to read configuration values from the environment.

You may also define additional placeholder syntaxes by creating your own Perl module.

Ready-to-use implementations are provided:

* :doc:`filesystemplaceholder`: secrets stored in local files

Enable and configure your module
--------------------------------

Edit the ``[configuration]`` section in ``lemonldap-ng.ini``

.. code:: ini

   [configuration]

   configPlaceHolderModules=SECRET=Lemonldap::NG::Common::Conf::SecretPlaceholder
   ; optionally configure the module here
   ; secretPlaceholderConfig=my_config


This configuration will call ``Lemonldap::NG::Common::Conf::SecretPlaceholder`` everytime
``%SECRET:MyVariable%`` is encountered in the configuration.

You can define multiple modules by separating them with a comma:

.. code:: ini

   [configuration]

   ; this will dispatch %SECRET:xx%, %DNS:yy% and %VAULT:zz% to each
   ; declared module
   configPlaceHolderModules=SECRET=My::Secret, DNS=My::DNS, VAULT=My::Vault

Write your custom module
------------------------

Here is an example of a Perl module that implements a configuration placeholder:

.. code:: perl

    # Must be stored in Lemonldap/NG/Common/Conf/SecretPlaceholder.pm
    package Lemonldap::NG::Common::Conf::SecretPlaceholder;

    use strict;

    # You must define a replace function
    sub replace {
        # The function takes:
        # * current module name
        # * current configuration hash
        # * variable name to look up
        my ( $class, $conf, $variable ) = @_;

        # You can read configuration options (vault server IP, etc)
        # from the ini-file configuration here
        my $placeholder_config = $conf->{secretPlaceholderConfig};

        # Obtain and return the value to be used in actual configuration
        my $value = implement_this($variable);

        return $value;
    }
    1;

Error handling
--------------

The resolution of a module placeholder is *fail-closed*: if ``replace()`` dies
or does not return a string (``undef``, a reference), the placeholder is left
as is, an error is logged and the whole configuration is rejected. Portals and
handlers then keep the configuration they had already loaded, rather than
running with an empty secret.

``%SERVERENV:VariableName%`` is not concerned: an undefined environment
variable is still replaced by an empty string.