Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
9 changes: 9 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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 \
Expand Down
45 changes: 45 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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/`.
Expand Down
18 changes: 15 additions & 3 deletions rootfs/etc/s6-overlay/scripts/config
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
1 change: 0 additions & 1 deletion rootfs/etc/s6-overlay/scripts/fix-perms
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
6 changes: 6 additions & 0 deletions rootfs/usr/bin/lnms
Original file line number Diff line number Diff line change
@@ -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
Expand Down
6 changes: 6 additions & 0 deletions rootfs/usr/local/bin/artisan
Original file line number Diff line number Diff line change
@@ -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 "$@"
195 changes: 195 additions & 0 deletions rootfs/usr/local/bin/librenms-composer
Original file line number Diff line number Diff line change
@@ -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 <<EOL
Usage: lnms plugin:add <package> [<version>]
lnms plugin:remove <package>
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
Loading