Skip to content

Commit

Permalink
fix: avoid stopping nginx-agent service on package upgrade (#352)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
defanator authored Nov 17, 2023
1 parent 0854fe6 commit 89fc334
Show file tree
Hide file tree
Showing 8 changed files with 160 additions and 34 deletions.
57 changes: 33 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
```
Expand Down Expand Up @@ -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
Expand All @@ -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
```

Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions scripts/.local-nfpm.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
15 changes: 15 additions & 0 deletions scripts/packages/nginx-agent.openrc
Original file line number Diff line number Diff line change
@@ -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
}
13 changes: 13 additions & 0 deletions scripts/packages/postinstall.sh
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
#!/bin/sh

# Determine OS platform
# shellcheck source=/dev/null
. /etc/os-release
Expand Down Expand Up @@ -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."
Expand Down Expand Up @@ -301,5 +313,6 @@ summary() {
update_unit_file
add_default_config_file
upgrade_config_file
restart_agent_if_required
summary
}
65 changes: 56 additions & 9 deletions scripts/packages/postremove.sh
Original file line number Diff line number Diff line change
@@ -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
21 changes: 21 additions & 0 deletions scripts/packages/postupgrade.sh
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion scripts/packages/preinstall.sh
Original file line number Diff line number Diff line change
Expand Up @@ -164,4 +164,4 @@ update_config_file() {
ensure_sudo
load_config_values
update_config_file
}
}
15 changes: 15 additions & 0 deletions scripts/packages/preremove.sh
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 89fc334

Please sign in to comment.