Scroll to navigation

LLNG-BUILD-MANAGER-FILES(1p) User Contributed Perl Documentation LLNG-BUILD-MANAGER-FILES(1p)

NAME

llng-build-manager-files - 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

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.
Output path for struct.json file.
Output path for conftree.js file.
Output path for ReConstants.pm file.
Output path for Attributes.pm file.
Output path for DefaultValues.pm file.
Output path for Constants.pm file.
Output path for reverseTree.json file.
Output path for portal Constants.pm file.
Output path for StatusConstants.pm file.
Directory containing language JSON files (e.g., en.json, fr.json). Translations from extensions will be merged into these files.
Show detailed progress information.
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:

Path to the target node, using "/" as separator (e.g., "generalParameters/plugins").
Insert new nodes after the node with this title.
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

SEE ALSO

Lemonldap::NG::Manager::Build, <https://lemonldap-ng.org/>

AUTHORS

LemonLDAP::NG team <http://lemonldap-ng.org/team>

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

2026-07-29 perl v5.42.2