diff --git a/README.md b/README.md index e37db6840..599fb5f45 100644 --- a/README.md +++ b/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-.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 /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,7 +350,7 @@ 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 @@ -349,7 +358,7 @@ NGINX Agent can be deployed in the following environments: - 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 diff --git a/scripts/.local-nfpm.yaml b/scripts/.local-nfpm.yaml index 3d6fec373..b7df26c33 100644 --- a/scripts/.local-nfpm.yaml +++ b/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" diff --git a/scripts/packages/nginx-agent.openrc b/scripts/packages/nginx-agent.openrc new file mode 100755 index 000000000..b7c92963d --- /dev/null +++ b/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 +} diff --git a/scripts/packages/postinstall.sh b/scripts/packages/postinstall.sh index 36cadc71e..c44686b32 100755 --- a/scripts/packages/postinstall.sh +++ b/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 } diff --git a/scripts/packages/postremove.sh b/scripts/packages/postremove.sh index 6a8bb8e7d..6b2c739f2 100755 --- a/scripts/packages/postremove.sh +++ b/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 diff --git a/scripts/packages/postupgrade.sh b/scripts/packages/postupgrade.sh new file mode 100644 index 000000000..6b95c3b52 --- /dev/null +++ b/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 diff --git a/scripts/packages/preinstall.sh b/scripts/packages/preinstall.sh index 7464c1ef2..972a2507a 100644 --- a/scripts/packages/preinstall.sh +++ b/scripts/packages/preinstall.sh @@ -164,4 +164,4 @@ update_config_file() { ensure_sudo load_config_values update_config_file -} \ No newline at end of file +} diff --git a/scripts/packages/preremove.sh b/scripts/packages/preremove.sh index 67bb50f42..6ee1c2611 100644 --- a/scripts/packages/preremove.sh +++ b/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