diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 62c49cbd..42c50c8b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -84,6 +84,52 @@ jobs: env: LIBRENMS_IMAGE: ${{ env.BUILD_TAG }} LIBRENMS_CONTAINER: ${{ env.CONTAINER_NAME }} + - + name: Check Composer packages + run: | + set -euo pipefail + services=(librenms dispatcher syslogng snmptrapd) + package=socialiteproviders/saml2 + probe='require "/opt/librenms/vendor/autoload.php"; exit(class_exists("SocialiteProviders\\Saml2\\Provider") ? 0 : 1);' + loaded() { + for service in "${services[@]}"; do + timeout 180 bash -c 'until docker compose exec -T -u librenms "$1" php -r "$2" 2>/dev/null; do sleep 2; done' _ "$service" "$probe" + done + } + build() { + docker compose exec -T librenms stat -c %i /data/composer/build + } + + docker compose exec -T librenms lnms plugin:add "$package" + if docker compose exec -T librenms lnms plugin:add "$package" 0.0.0; then + echo "Composer accepted an unavailable version" + exit 1 + fi + # the image is left untouched + docker compose exec -T librenms sh -ec '! grep -q "$1" composer.json composer.lock && test ! -e "vendor-image/$1"' _ "$package" + + # packages survive container replacement without being installed again + before=$(build) + docker compose up -d --no-deps --force-recreate "${services[@]}" + loaded + test "$(build)" = "$before" + + # packages are installed again when the image changes + docker compose exec -T librenms sh -c "echo other-image > /data/composer/build/stamp" + docker compose restart "${services[@]}" + loaded + test "$(build)" != "$before" + + docker compose exec -T librenms lnms plugin:remove "$package" + docker compose restart "${services[@]}" + for service in "${services[@]}"; do + timeout 180 bash -c 'until [ "$(docker compose exec -T "$1" readlink /opt/librenms/vendor 2>/dev/null)" = vendor-image ]; do sleep 2; done' _ "$service" + done + docker compose exec -T librenms curl -sS -o /dev/null --fail --retry 5 --retry-connrefused http://127.0.0.1:8000/login + working-directory: test + env: + LIBRENMS_IMAGE: ${{ env.BUILD_TAG }} + LIBRENMS_CONTAINER: ${{ env.CONTAINER_NAME }} - name: Logs if: always() diff --git a/Dockerfile b/Dockerfile index 871dff5f..f2758052 100644 --- a/Dockerfile +++ b/Dockerfile @@ -108,6 +108,7 @@ ENV S6_BEHAVIOUR_IF_STAGE2_FAILS="2" \ S6_STAGE2_HOOK="/etc/s6-overlay/scripts/runtime-bundles" \ LIBRENMS_PATH="/opt/librenms" \ LIBRENMS_DOCKER="1" \ + LIBRENMS_COMPOSER_PLUGINS="/data/composer/composer.plugins.json" \ TZ="UTC" \ PUID="1000" \ PGID="1000" @@ -136,6 +137,14 @@ RUN apk --update --no-cache add -t build-dependencies \ && echo "foreach (glob(\"${LIBRENMS_PATH}/config.d/*.php\") as \$filename) include \$filename;" >> config.php \ && chown -R librenms:librenms ${LIBRENMS_PATH} \ && su librenms -s /bin/sh -c "COMPOSER_CACHE_DIR=/tmp composer install --no-dev --no-interaction --no-ansi" \ + && mv vendor vendor-image \ + && ln -s vendor-image vendor \ + && ln -s /usr/bin/composer composer.phar \ + && touch -d 2100-01-01 /usr/bin/composer \ + && chown root:root . composer.json composer.lock \ + && chown -R root:root vendor-image \ + && chmod go-w . composer.json composer.lock \ + && chmod -R go-w vendor-image \ && apk del build-dependencies \ && rm -rf .git \ html/plugins/Test \ diff --git a/README.md b/README.md index a3162ee9..819e3853 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ ___ * [Syslog-ng container](#syslog-ng-container) * [Snmptrapd container](#snmptrapd-container) * [Add a LibreNMS plugin](#add-a-librenms-plugin) + * [Add a Composer package](#add-a-composer-package) * [Additional Monitoring plugins](#additional-monitoring-plugins) * [Custom alert templates](#custom-alert-templates) * [Contributing](#contributing) @@ -404,6 +405,50 @@ will be removed and yours will be used. > [!WARNING] > Container has to be restarted to propagate changes. +### Add a Composer package + +For example, install the Socialite SAML provider and restart the LibreNMS services. + +```console +$ docker compose exec librenms lnms plugin:add socialiteproviders/saml2 +$ docker compose restart librenms dispatcher syslogng snmptrapd +``` + +Use the service names in your Compose file. Add a version constraint after the +package name if needed. To uninstall, use `plugin:remove` and restart the same +services. + +Only the list of added packages is persisted, in +`/data/composer/composer.plugins.json`. The image's `composer.json`, +`composer.lock` and `vendor` folder are never modified. The added packages are +installed next to a copy of the image's dependencies in `/data/composer/build` +with `lnms plugin:sync`, which is run again when the container starts with a +new image. +Nothing is installed at startup if the list and the image are unchanged. + +> [!NOTE] +> All LibreNMS services must share `/data` and use the same `PUID` and `PGID`. +> Access to the Composer repositories is required after an image upgrade to +> install the packages again. If that fails, LibreNMS starts without them and +> an error is logged, restart the containers to try again. + +You can also provide `/data/composer/composer.plugins.json` yourself, the +packages it requires are installed when the container starts: + +```json +{ + "require": { + "socialiteproviders/saml2": "^4.8" + } +} +``` + +If you added packages with an older image, copy the list before upgrading: + +```console +$ docker compose exec librenms sh -c 'mkdir -p /data/composer && cp /opt/librenms/composer.plugins.json /data/composer/' +``` + ### Additional Monitoring plugins You can add a custom Monitoring plugin in `/data/monitoring-plugins/`. diff --git a/rootfs/etc/s6-overlay/scripts/config b/rootfs/etc/s6-overlay/scripts/config index f1458afd..8f97eb3b 100755 --- a/rootfs/etc/s6-overlay/scripts/config +++ b/rootfs/etc/s6-overlay/scripts/config @@ -94,7 +94,7 @@ sed -i -e "s/RANDOMSTRINGGOESHERE/${LIBRENMS_SNMP_COMMUNITY}/" /etc/snmp/snmpd.c # Init files and folders echo "Initializing LibreNMS files / folders..." -mkdir -p /data/config /data/logs /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates +mkdir -p /data/config /data/logs /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates /data/composer if [ -d "${LIBRENMS_PATH}/html/plugins/Weathermap" ]; then if [ -d "${LIBRENMS_PATH}/html/plugins/Weathermap/configs" ] && [ ! -L "${LIBRENMS_PATH}/html/plugins/Weathermap/configs" ]; then @@ -217,8 +217,8 @@ done # Fix perms echo "Fixing perms..." -chown librenms:librenms /data/config /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates -find /data/logs ${LIBRENMS_PATH}/composer* ${LIBRENMS_PATH}/config.d ${LIBRENMS_PATH}/bootstrap ${LIBRENMS_PATH}/logs ${LIBRENMS_PATH}/storage ${LIBRENMS_PATH}/vendor \( ! -user librenms -o ! -group librenms \) -exec chown librenms:librenms {} + +chown librenms:librenms /data/config /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates /data/composer +find /data/logs ${LIBRENMS_PATH}/config.d ${LIBRENMS_PATH}/bootstrap ${LIBRENMS_PATH}/logs ${LIBRENMS_PATH}/storage \( ! -user librenms -o ! -group librenms \) -exec chown librenms:librenms {} + chmod ug+rw /data/logs /data/rrd ${LIBRENMS_PATH}/bootstrap/cache ${LIBRENMS_PATH}/storage ${LIBRENMS_PATH}/storage/framework/* # Check additional Monitoring plugins @@ -256,3 +256,15 @@ for template in ${templates}; do echo " Adding ${template} alert template" ln -sf /data/alert-templates/${template} ${LIBRENMS_PATH}/resources/views/alerts/templates/${template} done + +# Use the image's Composer packages, or the build in /data/composer when +# packages were added with "lnms plugin:add" +echo "Checking Composer packages..." +if [ -f /data/composer/composer.plugins.json ]; then + chown librenms:librenms /data/composer/composer.plugins.json +fi +if [ "${SIDECAR_DISPATCHER:-0}" != "1" ] && [ "${SIDECAR_SYSLOGNG:-0}" != "1" ] && [ "${SIDECAR_SNMPTRAPD:-0}" != "1" ]; then + librenms-composer activate --prune +else + librenms-composer activate +fi diff --git a/rootfs/etc/s6-overlay/scripts/fix-perms b/rootfs/etc/s6-overlay/scripts/fix-perms index f8fcae0e..941de4ee 100755 --- a/rootfs/etc/s6-overlay/scripts/fix-perms +++ b/rootfs/etc/s6-overlay/scripts/fix-perms @@ -7,7 +7,6 @@ mkdir -p /data \ /var/run/php-fpm chown librenms:librenms \ /data \ - "${LIBRENMS_PATH}" \ "${LIBRENMS_PATH}/.env" \ "${LIBRENMS_PATH}/cache" \ "${LIBRENMS_PATH}/rrd" diff --git a/rootfs/usr/bin/lnms b/rootfs/usr/bin/lnms index 125ed55b..c5d4a0a1 100755 --- a/rootfs/usr/bin/lnms +++ b/rootfs/usr/bin/lnms @@ -1,5 +1,11 @@ #!/usr/bin/env sh +# Composer packages are kept in /data, the image is never modified +case "$1" in + plugin:add) shift; exec librenms-composer add "$@" ;; + plugin:remove) shift; exec librenms-composer remove "$@" ;; +esac + if [ "$(id -u -n)" = "librenms" -a "$(id -g -n)" = "librenms" ]; then php -f /opt/librenms/lnms "$@" else diff --git a/rootfs/usr/local/bin/artisan b/rootfs/usr/local/bin/artisan index 59849ec6..2f329d9d 100755 --- a/rootfs/usr/local/bin/artisan +++ b/rootfs/usr/local/bin/artisan @@ -1,4 +1,10 @@ #!/usr/bin/env sh +# Composer packages are kept in /data, the image is never modified +case "$1" in + plugin:add) shift; exec librenms-composer add "$@" ;; + plugin:remove) shift; exec librenms-composer remove "$@" ;; +esac + cd /opt/librenms || exit 1 gosu librenms:librenms php artisan "$@" diff --git a/rootfs/usr/local/bin/librenms-composer b/rootfs/usr/local/bin/librenms-composer new file mode 100755 index 00000000..739f6631 --- /dev/null +++ b/rootfs/usr/local/bin/librenms-composer @@ -0,0 +1,195 @@ +#!/usr/bin/env bash +# Composer packages added on top of the image (lnms plugin:add / plugin:remove). +# +# Only the list of added packages is persisted as the source of truth, in +# LIBRENMS_COMPOSER_PLUGINS. LibreNMS installs them next to a copy of the +# image's dependencies in /data/composer/build, which is recreated whenever +# the list or the image changes. The image's own files are never modified. +set -euo pipefail + +LIBRENMS_PATH=${LIBRENMS_PATH:-/opt/librenms} +image_vendor=vendor-image +data=/data/composer +list=${LIBRENMS_COMPOSER_PLUGINS:-${data}/composer.plugins.json} +build=${data}/build + +usage() { + cat >&2 < [] + lnms plugin:remove + librenms-composer list +EOL + exit 64 +} + +log() { + echo "$*" >&2 +} + +lock() { + mkdir -p "$data" + exec 9>"${data}/.lock" + flock 9 +} + +# Print the requirements of a package list as "name:constraint" lines. +requirements() { + [ -f "$1" ] || return 0 + php -r ' + $json = json_decode((string) file_get_contents($argv[1]), true); + if (! is_array($json)) { + fwrite(STDERR, "ERROR: $argv[1] is not valid JSON\n"); + exit(1); + } + foreach ($json["require"] ?? [] as $name => $constraint) { + echo "$name:$constraint\n"; + } + ' "$1" +} + +# Identifies what the image contributes to a build. +stamp() { + sha256sum <"${LIBRENMS_PATH}/composer.json" + sha256sum <"${LIBRENMS_PATH}/composer.lock" + php -r 'echo PHP_MAJOR_VERSION, ".", PHP_MINOR_VERSION, "\n";' +} + +# Is the build made from this image and the current package list? +valid() { + [ -f "${build}/vendor/autoload.php" ] && [ -f "${build}/stamp" ] || return 1 + [ "$(<"${build}/stamp")" = "$(stamp)" ] || return 1 + [ "$(requirements "${build}/composer.plugins.json")" = "$(requirements "$list")" ] +} + +# Start a build from the image's packages so only additions are downloaded. +# LibreNMS creates composer.json and composer.lock from the image's. +seed() { + rm -rf "$1" || return 1 + mkdir -p "$1" || return 1 + cp -R "${LIBRENMS_PATH}/${image_vendor}" "$1/vendor" +} + +# Run a LibreNMS plugin command against a build instead of the image. +plugin() { + local dir=$1 + shift + ( + cd "${LIBRENMS_PATH}" || exit 1 + COMPOSER="${dir}/composer.json" COMPOSER_VENDOR_DIR="${dir}/vendor" php lnms "$@" --no-ansi --no-interaction >&2 + ) +} + +record() { + cp "$list" "$1/composer.plugins.json" || return 1 + stamp >"$1/stamp" +} + +# Every step is checked: errexit is off when this runs as a condition. +rebuild() { + seed "${build}.new" || return 1 + plugin "${build}.new" plugin:sync || return 1 + record "${build}.new" || return 1 + rm -rf "$build" || return 1 + mv "${build}.new" "$build" +} + +cmd_change() { + local action=$1 status=0 + shift + lock + + if ! valid; then + if [ -n "$(requirements "$list")" ]; then + rebuild + elif [ "$action" = "remove" ]; then + log "No Composer packages have been added." + return + else + seed "$build" + fi + fi + + plugin "$build" "plugin:${action}" "$@" || status=$? + if [ -n "$(requirements "$list")" ]; then + record "$build" + fi + return "$status" +} + +cmd_list() { + requirements "$list" +} + +# Print the vendor directory to use, installing the packages first if the +# list or the image changed. Falls back to the image's packages rather than +# keeping LibreNMS down when that fails. +cmd_select() { + local vendor=$image_vendor reqs + lock + + if reqs=$(requirements "$list") && [ -n "$reqs" ]; then + if valid; then + vendor="${build}/vendor" + else + log "Installing Composer packages from ${list}..." + if rebuild; then + vendor="${build}/vendor" + else + log "ERROR: Failed to install the Composer packages from ${list}, they are NOT loaded." + fi + fi + elif [ "${1:-}" = "--prune" ]; then + # Sidecars leave it, the main container may still be using it. + rm -rf "$build" + fi + + echo "$vendor" +} + +# Point this container at the selected vendor directory. +cmd_activate() { + local vendor + vendor=$(gosu librenms:librenms "$0" select "$@") || vendor="" + if [ -z "$vendor" ]; then + log "ERROR: Failed to check Composer packages, added packages are NOT loaded" + vendor=$image_vendor + fi + if [ "$(readlink "${LIBRENMS_PATH}/vendor")" != "$vendor" ]; then + if [ "$vendor" != "$image_vendor" ]; then + log "Using Composer packages from ${vendor}" + fi + # Cached package discovery and config belong to the previous packages + rm -f "${LIBRENMS_PATH}"/bootstrap/cache/{packages,services,config,events,routes-v7}.php + ln -sfn "$vendor" "${LIBRENMS_PATH}/vendor" + fi +} + +export COMPOSER_HOME=${COMPOSER_HOME:-/home/librenms/.composer} + +cmd=${1:-} +shift || true +case "$cmd" in + add | remove) + if [ "$(id -u)" != "0" ]; then + log "ERROR: plugin:${cmd} must be run as root" + exit 1 + fi + if [ "$cmd" = "add" ]; then + [ $# -ge 1 ] && [ $# -le 2 ] || usage + else + [ $# -eq 1 ] || usage + fi + status=0 + gosu librenms:librenms "$0" change "$cmd" "$@" || status=$? + cmd_activate + if [ "$status" = "0" ]; then + log "Restart all LibreNMS containers to load the change." + fi + exit "$status" + ;; + activate) cmd_activate "$@" ;; + change) cmd_change "$@" ;; + select) cmd_select "$@" ;; + list) cmd_list ;; + *) usage ;; +esac