Modernize Debian and RPM packaging (systemd, dedicated user, CI tests)

.github/workflows/build.yml

@@ -23,6 +23,11 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# The build only checks out sources and publishes artifacts through the actions
+# API; no job needs to write back to the repository.
+permissions:
+  contents: read
+
 jobs:
   build-maven:
     runs-on: ${{ matrix.os }}
@@ -586,6 +591,219 @@ jobs:
           if-no-files-found: warn
           retention-days: 90
 
+  test-deb:
+    needs: build-maven
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: ubuntu-latest-11
+      - name: Clean-room install + SysV start/stop (debian:12 container)
+        shell: bash
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work debian:12 bash -c '
+            set -e
+            export DEBIAN_FRONTEND=noninteractive
+            DEB=$(ls opendj-packages/opendj-deb/opendj-deb-standard/target/*.deb | head -1)
+            echo "Found $DEB"
+            apt-get update
+            apt-get install -y lintian
+            lintian --info --no-tag-display-limit "$DEB" || true
+            dpkg-deb -I "$DEB"
+            dpkg-deb -c "$DEB" | grep -E "lib/systemd/system/opendj.service|etc/init.d/opendj"
+            apt-get install -y "./$DEB"
+            id opendj
+            test "$(stat -c %U /opt/opendj)" = opendj
+            # No JAVA_HOME and no "which" in this clean container: Java must resolve
+            # from config/java.properties (default.java-home set by postinst).
+            runuser -u opendj -- /opt/opendj/setup --cli --no-prompt --acceptLicense --doNotStart \
+              --rootUserDN "cn=Directory Manager" --rootUserPassword password \
+              --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \
+              --baseDN dc=example,dc=com --addBaseEntry
+            /etc/init.d/opendj start
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            /etc/init.d/opendj status
+            test "$OK" = 1
+            /etc/init.d/opendj stop
+            apt-get purge -y opendj
+          '
+      - name: Live systemd install + start/stop (runner)
+        shell: bash
+        run: |
+          DEB=$(ls opendj-packages/opendj-deb/opendj-deb-standard/target/*.deb | head -1)
+          sudo apt-get update
+          sudo apt-get install -y "$PWD/$DEB"
+          test "$(stat -c '%U' /opt/opendj)" = opendj
+          # sudo/runuser/systemd strip JAVA_HOME -> also relies on config/java.properties
+          sudo runuser -u opendj -- /opt/opendj/setup --cli --no-prompt --acceptLicense --doNotStart \
+            --rootUserDN "cn=Directory Manager" --rootUserPassword password \
+            --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \
+            --baseDN dc=example,dc=com --addBaseEntry
+          sudo systemctl enable --now opendj
+          OK=0
+          for i in $(seq 1 20); do
+            if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+            sleep 3
+          done
+          sudo systemctl is-active --quiet opendj
+          test "$OK" = 1
+          echo "OpenDJ is active under systemd"
+          sudo systemctl stop opendj
+          sleep 3
+          if sudo systemctl is-active --quiet opendj; then echo "still active"; exit 1; fi
+          sudo apt-get purge -y opendj
+
+  test-rpm:
+    needs: build-maven
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: ubuntu-latest-11
+      - name: Install and start/stop in Rocky Linux 9
+        shell: bash
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work rockylinux:9 bash -c '
+            set -e
+            RPM=$(ls opendj-packages/opendj-rpm/opendj-rpm-standard/target/rpm/opendj/RPMS/noarch/*.rpm | head -1)
+            echo "Found $RPM"
+            # No manual dependencies: the package must pull everything itself (Requires).
+            dnf install -y "$RPM"
+            id opendj
+            test "$(stat -c %U /opt/opendj)" = opendj
+            # Java must come from config/java.properties (no JAVA_HOME and no "which" here)
+            runuser -u opendj -- /opt/opendj/setup --cli --no-prompt --acceptLicense --doNotStart \
+              --rootUserDN "cn=Directory Manager" --rootUserPassword password \
+              --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \
+              --baseDN dc=example,dc=com --addBaseEntry
+            /etc/init.d/opendj start
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            /etc/init.d/opendj status
+            test "$OK" = 1
+            /etc/init.d/opendj stop
+            rpm -e opendj
+          '
+
+  # Upgrade path: released 5.1.1 deb (root-owned, SysV) -> this build's deb. The new package
+  # must stop the running server, create the opendj user, migrate ownership, run the upgrade
+  # tool and restart the server with the old data (docs: chap-upgrade).
+  test-deb-upgrade:
+    needs: build-maven
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: ubuntu-latest-11
+      - name: Download released 5.1.1 deb
+        shell: bash
+        run: curl -fsSL -o opendj-5.1.1.deb https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/5.1.1/opendj_5.1.1-1_all.deb
+      - name: Upgrade 5.1.1 -> new deb (debian:12 container)
+        shell: bash
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work debian:12 bash -c '
+            set -e
+            export DEBIAN_FRONTEND=noninteractive
+            NEW=$(ls opendj-packages/opendj-deb/opendj-deb-standard/target/*.deb | head -1)
+            echo "New deb: $NEW"
+            apt-get update
+            # No manual dependencies: even the released 5.1.1 deb declares a JRE dependency.
+            apt-get install -y ./opendj-5.1.1.deb
+            # 5.1.1 model: no dedicated user, root-owned tree, SysV only
+            /opt/opendj/setup --cli --no-prompt --acceptLicense --doNotStart \
+              --rootUserDN "cn=Directory Manager" --rootUserPassword password \
+              --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \
+              --baseDN dc=example,dc=com --addBaseEntry
+            /etc/init.d/opendj start
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            test "$OK" = 1
+            # Leave the server RUNNING: the new package must stop it, upgrade and restart it.
+            apt-get install -y "./$NEW"
+            id opendj
+            test "$(stat -c %U /opt/opendj)" = opendj
+            test -f /opt/opendj/config/config.ldif
+            # The package restarted the server; the pre-upgrade data must be served again,
+            # now by the dedicated user.
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            test "$OK" = 1
+            test "$(stat -c %U /proc/$(cat /opt/opendj/logs/server.pid))" = opendj
+            /etc/init.d/opendj stop
+            apt-get purge -y opendj
+          '
+
+  test-rpm-upgrade:
+    needs: build-maven
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: ubuntu-latest-11
+      - name: Download released 5.1.1 rpm
+        shell: bash
+        run: curl -fsSL -o opendj-5.1.1.rpm https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/5.1.1/opendj-5.1.1-1.noarch.rpm
+      - name: Upgrade 5.1.1 -> new rpm (Rocky Linux 9 container)
+        shell: bash
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work rockylinux:9 bash -c '
+            set -e
+            NEW=$(ls opendj-packages/opendj-rpm/opendj-rpm-standard/target/rpm/opendj/RPMS/noarch/*.rpm | head -1)
+            echo "New rpm: $NEW"
+            # java, "which" and initscripts are needed only by the RELEASED 5.1.1 rpm, which
+            # declared no dependencies at all (declarations added by #677; java discovery and
+            # init-functions sourcing fixed by this PR). Drop them when the upgrade-source
+            # artifact link points to a release with #677.
+            # Everything the NEW package needs must come from its own Requires.
+            dnf install -y java-21-openjdk-headless which initscripts >/dev/null
+            dnf install -y ./opendj-5.1.1.rpm
+            # 5.1.1 model: no dedicated user, root-owned tree, SysV only
+            /opt/opendj/setup --cli --no-prompt --acceptLicense --doNotStart \
+              --rootUserDN "cn=Directory Manager" --rootUserPassword password \
+              --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \
+              --baseDN dc=example,dc=com --addBaseEntry
+            /etc/init.d/opendj start
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            test "$OK" = 1
+            # Leave the server RUNNING: the new package must stop it, upgrade and restart it.
+            dnf install -y "./$NEW"
+            id opendj
+            test "$(stat -c %U /opt/opendj)" = opendj
+            test -f /opt/opendj/config/config.ldif
+            # The package restarted the server; the pre-upgrade data must be served again,
+            # now by the dedicated user.
+            OK=0
+            for i in $(seq 1 20); do
+              if /opt/opendj/bin/ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password -b "dc=example,dc=com" -s base "(objectClass=*)" 1.1 >/dev/null 2>&1; then OK=1; break; fi
+              sleep 3
+            done
+            test "$OK" = 1
+            test "$(stat -c %U /proc/$(cat /opt/opendj/logs/server.pid))" = opendj
+            /etc/init.d/opendj stop
+            rpm -e opendj
+          '
+
   test-msi:
     needs: build-maven
     runs-on: 'windows-latest'

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc

@@ -434,48 +434,26 @@ You can install OpenDJ in unattended and silent fashion, too. See the procedure,
 ====
 On Debian and related Linux distributions such as Ubuntu, you can install OpenDJ directory server from the Debian package:
 
-. (Optional)  Before you install OpenDJ, install a Java runtime environment if none is installed yet:
-+
-
-[source, console]
-----
-$ sudo apt-get install default-jre
-----
-
-. Install the OpenDJ directory server package:
+. Install the OpenDJ directory server package. Use `apt-get install ./<file>.deb` (rather than `dpkg -i`) so the required Java runtime dependency (`default-jre-headless`) is resolved and installed automatically:
 +
 
 [source, console, subs="attributes"]
 ----
-$ sudo dpkg -i opendj_{opendj-version}-1_all.deb
-Selecting previously unselected package opendj.
-(Reading database ... 185569 files and directories currently installed.)
-Unpacking opendj (from opendj_{opendj-version}-1_all.deb) ...
-
-Setting up opendj ({opendj-version}) ...
- Adding system startup for /etc/init.d/opendj ...
-   /etc/rc0.d/K20opendj -> ../init.d/opendj
-   /etc/rc1.d/K20opendj -> ../init.d/opendj
-   /etc/rc6.d/K20opendj -> ../init.d/opendj
-   /etc/rc2.d/S20opendj -> ../init.d/opendj
-   /etc/rc3.d/S20opendj -> ../init.d/opendj
-   /etc/rc4.d/S20opendj -> ../init.d/opendj
-   /etc/rc5.d/S20opendj -> ../init.d/opendj
-
-Processing triggers for ureadahead ...
-ureadahead will be reprofiled on next reboot
+$ sudo apt-get install ./opendj_{opendj-version}-1_all.deb
 ----
 +
-The Debian package installs OpenDJ directory server in the `/opt/opendj` directory, generates service management scripts, adds documentation files under `/usr/share/doc/opendj`, and adds man pages under `/opt/opendj/share/man`.
+The Debian package installs OpenDJ directory server in the `/opt/opendj` directory, registers the service with systemd (`opendj.service`, with a SysV init script kept as a fallback on non-systemd hosts), adds documentation files under `/usr/share/doc/opendj`, and adds man pages under `/opt/opendj/share/man`.
++
+The package creates a dedicated `opendj` system user; the files under `/opt/opendj` are owned by it and the service runs as that user. The systemd service is granted `CAP_NET_BIND_SERVICE`, so it can bind privileged ports such as LDAP 389 and LDAPS 636 even though it runs as a non-root user. On non-systemd hosts that use the SysV init script, grant the capability another way (for example `authbind` or an `iptables` redirect) or use ports above 1024.
 +
-The files are owned by root by default, making it easier to have OpenDJ listen on ports 389 and 636.
+To pin or override the Java runtime used by the service, set `OPENDJ_JAVA_HOME` (or `OPENDJ_JAVA_ARGS`) in `/etc/default/opendj`.
 
-. Configure OpenDJ directory server by using the command `sudo /opt/opendj/setup`:
+. Configure OpenDJ directory server by running `setup` as the `opendj` user (the account that owns the files and runs the service):
 +
 
 [source, console]
 ----
-$ sudo /opt/opendj/setup --cli
+$ sudo -u opendj /opt/opendj/setup --cli
 ...
 To see basic server configuration status and configuration you can launch
  /opt/opendj/bin/status
@@ -486,9 +464,9 @@ To see basic server configuration status and configuration you can launch
 
 [source, console, subs="attributes"]
 ----
-$ service opendj status
-opendj status: > Running.
-$ sudo /opt/opendj/bin/status
+$ systemctl is-active opendj
+active
+$ sudo -u opendj /opt/opendj/bin/status
 
 
 >>>> Specify OpenDJ LDAP connection parameters
@@ -543,38 +521,28 @@ Password:
 #
 ----
 
-. Before you install OpenDJ, install a Java runtime environment if none is installed yet.
-+
-You might need to download an RPM to install the Java runtime environment, and then install the RPM by using the `rpm` command:
-+
-
-[source, console]
-----
-# rpm -ivh jre-*.rpm
-----
-
-. Install the OpenDJ directory server package:
+. Install the OpenDJ directory server package. Use `dnf install ./<file>.rpm` (rather than `rpm -i`) so the required Java runtime dependency (`java-headless >= 11`) is resolved and installed automatically:
 +
 
 [source, console, subs="attributes"]
 ----
-# rpm -i opendj-{opendj-version}-1.noarch.rpm
+# dnf install ./opendj-{opendj-version}-1.noarch.rpm
 Pre Install - initial install
 Post Install - initial install
-
-#
 ----
 +
-The RPM package installs OpenDJ directory server in the `/opt/opendj` directory, generates service management scripts, and adds man pages under `/opt/opendj/share/man`.
+The RPM package installs OpenDJ directory server in the `/opt/opendj` directory, registers the service with systemd (`opendj.service`, with a SysV init script kept as a fallback on non-systemd hosts), and adds man pages under `/opt/opendj/share/man`.
 +
-The files are owned by root by default, making it easier to have OpenDJ listen on ports 389 and 636.
+The package creates a dedicated `opendj` system user; the files under `/opt/opendj` are owned by it and the service runs as that user. The systemd service is granted `CAP_NET_BIND_SERVICE`, so it can bind privileged ports such as LDAP 389 and LDAPS 636 even though it runs as a non-root user. On non-systemd hosts that use the SysV init script, grant the capability another way (for example `authbind` or an `iptables` redirect) or use ports above 1024.
++
+To pin or override the Java runtime used by the service, set `OPENDJ_JAVA_HOME` (or `OPENDJ_JAVA_ARGS`) in `/etc/sysconfig/opendj`.
 
-. Configure OpenDJ directory server by using the command `/opt/opendj/setup`:
+. Configure OpenDJ directory server by running `setup` as the `opendj` user (the account that owns the files and runs the service):
 +
 
 [source, console]
 ----
-# /opt/opendj/setup --cli
+# runuser -u opendj -- /opt/opendj/setup --cli
 ...
 To see basic server configuration status and configuration you can launch
  /opt/opendj/bin/status
@@ -585,9 +553,9 @@ To see basic server configuration status and configuration you can launch
 
 [source, console, subs="attributes"]
 ----
-# service opendj status
-opendj status: > Running.
-# /opt/opendj/bin/status
+# systemctl is-active opendj
+active
+# runuser -u opendj -- /opt/opendj/bin/status
 
 
 >>>> Specify OpenDJ LDAP connection parameters
@@ -625,14 +593,13 @@ Entries:     2002
 Replication:
 ----
 +
-By default OpenDJ starts in run levels 2, 3, 4, and 5:
+The service is enabled to start at boot:
 +
 
 [source, console]
 ----
-# chkconfig --list | grep opendj
-...
-opendj         0:off    1:off    2:on    3:on    4:on    5:on    6:off
+# systemctl is-enabled opendj
+enabled
 ----
 
 ====

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc

@@ -129,7 +129,7 @@ Stopping Server...
 $
 ----
 +
-Removing the package does not remove your data or configuration. You must remove `/opt/opendj` manually to get rid of all files.
+Removing the package stops the server but does not remove your data or configuration, nor the dedicated `opendj` system user it created. Remove `/opt/opendj` manually to delete all files, and remove the `opendj` user if you no longer need it.
 
 ====
 
@@ -155,7 +155,7 @@ OpenDJ successfully removed.
 #
 ----
 +
-Removing the package does not remove your data or configuration. You must remove `/opt/opendj` manually to get rid of all files.
+Removing the package stops the server but does not remove your data or configuration, nor the dedicated `opendj` system user it created. Remove `/opt/opendj` manually to delete all files, and remove the `opendj` user if you no longer need it.
 
 ====