fix: avoid stopping nginx-agent service on package upgrade (#352)

* fix: restart service on package upgrade on Debian/Ubuntu

Previously it was stopped during the executing of package scripts
due to incorrect behavior in prerm:

https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html#summary-of-ways-maintainer-scripts-are-called

* fix: do not stop service on upgrade (RHEL-based distros)

* Avoid restarting nginx-agent service from pkg on FreeBSD during upgrades

This will end up with a new process being killed immediately by pkg:
https://github.com/freebsd/pkg/blob/1.19.1/libpkg/scripts.c#L100-L103
https://github.com/freebsd/pkg/blob/1.19.1/libpkg/scripts.c#L244-L261

See also:
freebsd/pkg#2128

* feat: OpenRC package scripts for Alpine Linux

* chore: add Alpine Linux instructions to README

While here, removed extra trailing spaces across the doc.

* chore: adjust service description, remove modelines

* chore: remove leading underscore from shell func names

Author: defanator

README.md

@@ -89,7 +89,7 @@ To install NGINX Agent on your system, go to [Releases](https://github.com/nginx
 
 Use your system's package manager to install the package. Some examples:
 
-Debian, Ubuntu, and other distributions using the `dpkg` package manager. 
+Debian, Ubuntu, and other distributions using the `dpkg` package manager.
 
 ```
 sudo dpkg -i nginx-agent-<agent-version>.deb
@@ -121,7 +121,16 @@ To enable the NGINX Agent to start on boot, run the following command:
 sudo systemctl enable nginx-agent
 ```
 
-## Logging 
+On Alpine Linux, use the following command to start the agent:
+```
+sudo service nginx-agent start
+```
+To enable the agent to start at boot time on Alpine Linux, run this:
+```
+sudo rc-update add nginx-agent default
+```
+
+## Logging
 NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services.
 
 ### Log Rotation
@@ -171,7 +180,7 @@ Follow steps in the [Installation](#installation) section to download, install,
 Using your preferred method, clone the NGINX Agent repository into your development directory. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help.
 
 ## Installing Go
-NGINX Agent and the Mock Control Plane are written in Go. Go 1.21.0 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). 
+NGINX Agent and the Mock Control Plane are written in Go. Go 1.21.0 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/).
 
 ## Starting the gRPC Mock Control Plane
 Start the mock control plane by running the following command from the `agent` source code root directory:
@@ -185,12 +194,12 @@ INFO[0000] gRPC listening at 54789 # gRPC control plane port which NGINX Agent w
 ```
 
 ## NGINX Agent Settings
-If it doesn't already exist, create the `/etc/nginx-agent/` directory and copy the `nginx-agent.conf` file into it from the project root directory. 
+If it doesn't already exist, create the `/etc/nginx-agent/` directory and copy the `nginx-agent.conf` file into it from the project root directory.
 ```
 sudo mkdir /etc/nginx-agent
 sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
 ```
-Create the `agent-dynamic.conf` file in the `/etc/nginx-agent/` directory, which is required for NGINX Agent to run. 
+Create the `agent-dynamic.conf` file in the `/etc/nginx-agent/` directory, which is required for NGINX Agent to run.
 ```
 sudo touch /var/lib/nginx-agent/agent-dynamic.conf
 ```
@@ -242,7 +251,7 @@ Open a web browser to view the Swagger UI at http://localhost:8082/docs.
 ## Extensions
 An extension is a piece of code, not critical to the main functionality that the NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics.
 
-To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. 
+To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`.
 Here is an example of enabling the advanced metrics extension:
 
 ```yaml
@@ -258,24 +267,24 @@ Open another terminal window and start the NGINX Agent. Issue the following comm
 sudo make run
 
 # Command Output snippet
-WARN[0000] Log level is info                            
-INFO[0000] setting displayName to XXX            
+WARN[0000] Log level is info
+INFO[0000] setting displayName to XXX
 INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX
-INFO[0000] NginxBinary initializing                     
-INFO[0000] Commander initializing                       
-INFO[0000] Comms initializing                           
-INFO[0000] OneTimeRegistration initializing             
-INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX 
-INFO[0000] Metrics initializing                         
-INFO[0000] MetricsThrottle initializing                 
-INFO[0000] DataPlaneStatus initializing                 
-INFO[0000] MetricsThrottle waiting for report ready     
-INFO[0000] Metrics waiting for handshake to be completed 
-INFO[0000] ProcessWatcher initializing                  
-INFO[0000] Extensions initializing                      
-INFO[0000] FileWatcher initializing                     
+INFO[0000] NginxBinary initializing
+INFO[0000] Commander initializing
+INFO[0000] Comms initializing
+INFO[0000] OneTimeRegistration initializing
+INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
+INFO[0000] Metrics initializing
+INFO[0000] MetricsThrottle initializing
+INFO[0000] DataPlaneStatus initializing
+INFO[0000] MetricsThrottle waiting for report ready
+INFO[0000] Metrics waiting for handshake to be completed
+INFO[0000] ProcessWatcher initializing
+INFO[0000] Extensions initializing
+INFO[0000] FileWatcher initializing
 INFO[0000] FileWatchThrottle initializing
-INFO[0001] Events initializing                          
+INFO[0001] Events initializing
 INFO[0001] OneTimeRegistration completed
 ```
 
@@ -341,15 +350,15 @@ sudo make run
 ## Supported Distributions
 NGINX Agent can run in most environments. For a list of supported distributions, see the [NGINX Technical Specs](https://docs.nginx.com/nginx/technical-specs/#supported-distributions) guide.
 
-## Supported Deployment Environments 
+## Supported Deployment Environments
 NGINX Agent can be deployed in the following environments:
 
 - Bare Metal
 - Container
 - Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure
 - Virtual Machine
 
-## Supported NGINX Versions 
+## Supported NGINX Versions
 NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus.
 
 ## Sizing Recommendations

scripts/.local-nfpm.yaml

@@ -19,6 +19,9 @@ contents:
     dst: /etc/systemd/system/nginx-agent.service
   - src: ./scripts/nginx-agent.logrotate
     dst: /etc/logrotate.d/nginx-agent
+  - src: ./scripts/packages/nginx-agent.openrc
+    dst: /etc/init.d/nginx-agent
+    packager: apk
   - src: ./scripts/selinux/nginx_agent_selinux.8.gz
     dst: /usr/share/man/man8/nginx_agent_selinux.8.gz
     packager: rpm
@@ -39,3 +42,6 @@ scripts:
   postinstall: "./scripts/packages/postinstall.sh"
   preremove: "./scripts/packages/preremove.sh"
   postremove: "./scripts/packages/postremove.sh"
+apk:
+  scripts:
+    postupgrade: "./scripts/packages/postupgrade.sh"

scripts/packages/nginx-agent.openrc

@@ -0,0 +1,15 @@
+#!/sbin/openrc-run
+
+description="NGINX Agent"
+command_background=true
+
+cfgfile=${cfgfile:-/etc/nginx-agent/nginx-agent.conf}
+pidfile=/var/run/nginx-agent.pid
+command=/usr/bin/nginx-agent
+command_args=""
+required_files="$cfgfile"
+
+depend() {
+    need net
+    use dns logger netmount
+}

scripts/packages/postinstall.sh

@@ -1,4 +1,5 @@
 #!/bin/sh
+
 # Determine OS platform
 # shellcheck source=/dev/null
 . /etc/os-release
@@ -271,6 +272,17 @@ upgrade_config_file() {
     fi
 }
 
+restart_agent_if_required() {
+    if [ "${ID}" = "freebsd" ]; then
+        # https://github.com/freebsd/pkg/pull/2128
+        return
+    fi
+    if service nginx-agent status >/dev/null 2>&1; then
+        printf "PostInstall: Restarting nginx agent\n"
+        service nginx-agent restart || true
+    fi
+}
+
 summary() {
     echo "----------------------------------------------------------------------"
     echo " NGINX Agent package has been successfully installed."
@@ -301,5 +313,6 @@ summary() {
     update_unit_file
     add_default_config_file
     upgrade_config_file
+    restart_agent_if_required
     summary
 }

scripts/packages/postremove.sh

@@ -1,21 +1,68 @@
 #!/bin/sh
+
 # Determine OS platform
 # shellcheck source=/dev/null
 . /etc/os-release
 
-if [ "$ID" = "freebsd" ]; then
-    echo "Stop and remove nginx-agent service"
+stop_agent_freebsd() {
+    echo "Stopping nginx-agent service"
     service nginx-agent onestop >/dev/null 2>&1 || true
+}
+
+disable_agent_freebsd() {
+    echo "Disabling nginx-agent service"
     sysrc -x nginx_agent_enable >/dev/null 2>&1 || true
-elif command -V systemctl >/dev/null 2>&1; then
-    echo "Stop and disable nginx-agent service"
+}
+
+stop_agent_systemd() {
+    echo "Stopping nginx-agent service"
     systemctl stop nginx-agent >/dev/null 2>&1 || true
+}
+
+disable_agent_systemd() {
+    echo "Disabling nginx-agent service"
     systemctl disable nginx-agent >/dev/null 2>&1 || true
+}
+
+systemd_daemon_reload() {
     echo "Running daemon-reload"
     systemctl daemon-reload || true
-fi
+}
+
+cleanup() {
+    echo "Removing /var/run/nginx-agent directory"
+    rm -rf "/var/run/nginx-agent"
+}
 
-echo "Removing /var/run/nginx-agent directory"
-rm -rf "/var/run/nginx-agent"
-echo "Removing /var/log/nginx-agent directory"
-rm -rf "/var/log/nginx-agent"
+case "$ID" in
+    freebsd)
+        stop_agent_freebsd
+        disable_agent_freebsd
+        cleanup
+        ;;
+    debian|ubuntu)
+        if [ "$1" = "remove" ]; then
+            stop_agent_systemd
+            disable_agent_systemd
+            systemd_daemon_reload
+            cleanup
+        fi
+        ;;
+    rhel|fedora|centos|amzn|almalinux|rocky)
+        if [ "$1" = "0" ]; then
+            stop_agent_systemd
+            disable_agent_systemd
+            systemd_daemon_reload
+            cleanup
+        fi
+        ;;
+    alpine)
+        cleanup
+        ;;
+    *)
+        stop_agent_systemd
+        disable_agent_systemd
+        systemd_daemon_reload
+        cleanup
+        ;;
+esac

scripts/packages/postupgrade.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+NEWVER="$1"
+OLDVER="$2"
+
+restart_agent_if_required() {
+    if service nginx-agent status >/dev/null 2>&1; then
+        printf "PostUpgrade: Restarting nginx agent (upgraded to %s from %s)\n" "$NEWVER" "$OLDVER"
+        service nginx-agent restart || true
+    fi
+}
+
+# Determine OS platform
+# shellcheck source=/dev/null
+. /etc/os-release
+
+case "$ID" in
+    alpine)
+        restart_agent_if_required
+        ;;
+esac

scripts/packages/preinstall.sh

@@ -164,4 +164,4 @@ update_config_file() {
     ensure_sudo
     load_config_values
     update_config_file
-}
+}

scripts/packages/preremove.sh

@@ -1,2 +1,17 @@
 #!/bin/sh
 # Pre Remove Steps
+
+# Determine OS platform
+# shellcheck source=/dev/null
+. /etc/os-release
+
+stop_agent_openrc() {
+    echo "Stopping nginx-agent service"
+    service nginx-agent stop 2>&1 || true
+}
+
+case "$ID" in
+    alpine)
+        stop_agent_openrc
+        ;;
+esac