llng-build-manager-files.1p - Man Page

Regenerate LemonLDAP::NG Manager with plugin extensions

Synopsis

  llng-build-manager-files [--plugins-dir=<path> ...] [options]

Description

This script allows LemonLDAP::NG plugins to extend the Manager interface by adding new configuration attributes, tree nodes (for the configuration tree), and portal constants.

Extensions can be provided in either Perl (.pm) or JSON (.json) format and are loaded from the specified plugins directory.

Options

--plugins-dir=path: Directory containing plugin extension files (.pm or .json). Can be specified multiple times to scan several directories. If not specified or a directory doesn't exist, it is skipped with a warning.
--struct-file=path: Output path for struct.json file.
--conftree-file=path: Output path for conftree.js file.
--manager-constants-file=path: Output path for ReConstants.pm file.
--manager-attributes-file=path: Output path for Attributes.pm file.
--default-values-file=path: Output path for DefaultValues.pm file.
--conf-constants-file=path: Output path for Constants.pm file.
--reverse-tree-file=path: Output path for reverseTree.json file.
--portal-constants-file=path: Output path for portal Constants.pm file.
--handler-status-constants-file=path: Output path for StatusConstants.pm file.
--lang-dir=path: Directory containing language JSON files (e.g., en.json, fr.json). Translations from extensions will be merged into these files.
--verbose, -v: Show detailed progress information.
--help, -h: Show help message.

Extension File Format

Perl Format (.pm)

  package MyPlugin::Extension;

  sub attributes {
      return {
          myPluginEnabled => {
              type          => 'bool',
              default       => 0,
              documentation => 'Enable my plugin',
              help          => 'myplugin.html',
          },
          myPluginOption => {
              type    => 'text',
              default => 'default_value',
          },
      };
  }

  sub tree {
      return {
          insert_into => 'generalParameters/plugins',
          nodes => [
              {
                  title => 'myPluginNode',
                  help  => 'myplugin.html',
                  form  => 'simpleInputContainer',
                  nodes => ['myPluginEnabled', 'myPluginOption'],
              }
          ],
      };
  }

  sub ctrees {
      return {
          # Extend oidcRPMetaDataNode with additional options
          oidcRPMetaDataNode => {
              insert_after => 'oidcRPMetaDataMacros',
              nodes => [
                  {
                      title => 'myPluginOidcOptions',
                      form  => 'simpleInputContainer',
                      nodes => ['myPluginOidcAttr'],
                  }
              ],
          },
      };
  }

  sub constants {
      return {
          PE_MYPLUGIN_ERROR => 200,
      };
  }

  sub lang {
      return {
          myPluginEnabled => {
              en => 'Enable my plugin',
              fr => 'Activer mon plugin',
          },
          myPluginOption => {
              en => 'My plugin option',
              fr => 'Option de mon plugin',
          },
      };
  }

  1;

JSON Format (.json)

  {
    "attributes": {
      "myPluginEnabled": {
        "type": "bool",
        "default": 0,
        "documentation": "Enable my plugin"
      }
    },
    "tree": {
      "insert_into": "generalParameters/plugins",
      "nodes": [
        {
          "title": "myPluginNode",
          "form": "simpleInputContainer",
          "nodes": ["myPluginEnabled"]
        }
      ]
    },
    "ctrees": {},
    "constants": {
      "PE_MYPLUGIN_ERROR": 200
    },
    "lang": {
      "myPluginEnabled": {
        "en": "Enable my plugin",
        "fr": "Activer mon plugin"
      }
    }
  }

Auth Plugin Declaration

Authentication plugins can declare themselves via the authPlugin key (top level of an extension file, alongside attributes, tree, etc.) instead of manually appending to every select list:

  "authPlugin": {
    "k": "JsonFile",
    "v": "JSON File (dev/test)",
    "roles": ["authentication", "userDB"]
  }

Multiple plugins may be declared as an array. Allowed roles are authentication, userDB, and passwordDB. The option is appended to the following core selects based on the declared roles:

authentication role: authentication, authChoiceModules (auth slot), combModules
userDB role: userDB, authChoiceModules (userDB slot), combModules
passwordDB role: passwordDB, authChoiceModules (password slot)

Appends are deduplicated on the k key, so re-running the rebuilder or declaring the same plugin in multiple files is safe.

Tree Insertion

The tree and ctrees extensions support the following insertion options:

insert_into: Path to the target node, using "/" as separator (e.g., "generalParameters/plugins").
insert_after: Insert new nodes after the node with this title.
insert_before: Insert new nodes before the node with this title.

If neither insert_after nor insert_before is specified, nodes are appended at the end.

If insert_after or insert_before refers to a sibling that does not exist in the target tree, nodes are also appended at the end and a warning is printed on stderr pointing to the offending extension file.

Translations

Extensions can provide translations for their configuration keys using the lang function (Perl) or lang key (JSON). Translations are specified as a hash where keys are the translation identifiers and values are hashes mapping language codes to translated text.

If a translation is not provided for a specific language, the script will:

1. Use the English (en) translation if available

2. Fall back to the first available translation

This ensures all language files get an entry even if translations are only provided for a subset of languages.

Portal Constants

Plugin constants should use values >= 200 to avoid conflicts with core constants. A warning is issued if a value below 200 is used.

Examples

  # Regenerate with plugins (uses default paths from installation)
  llng-build-manager-files --plugins-dir=/etc/lemonldap-ng/manager-overrides.d

  # Multiple plugin directories
  llng-build-manager-files \
    --plugins-dir=/etc/lemonldap-ng/manager-overrides.d \
    --plugins-dir=/usr/share/lemonldap-ng/plugins.d

  # Verbose mode
  llng-build-manager-files --plugins-dir=/etc/lemonldap-ng/manager-overrides.d -v

  # Override specific output paths (useful for testing)
  llng-build-manager-files \
    --plugins-dir=/etc/lemonldap-ng/manager-overrides.d \
    --struct-file=/custom/path/struct.json