|
5 | 5 |
|
6 | 6 |  |
7 | 7 |
|
8 | | -NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables: |
9 | | -- Remote management of NGINX configurations |
10 | | -- Collection and reporting of real-time NGINX performance and operating system metrics |
| 8 | +# F5 NGINX Agent |
11 | 9 |
|
12 | | - |
13 | | -[Grafana](https://grafana.com/) dashboard showing metrics reported by NGINX Agent |
| 10 | +The F5 NGINX Agent is a companion application designed to efficiently manage NGINX instances. Key features include: |
14 | 11 |
|
15 | | -# Table of Contents |
16 | | -- [How it Works](#how-it-works) |
17 | | - - [Configuration Management](#configuration-management) |
18 | | - - [Collecting Metrics](#collecting-metrics) |
19 | | -- [Installation](#installation) |
20 | | - - [Installing NGINX](#installing-nginx) |
21 | | - - [Installing NGINX Agent from Package Files](#installing-nginx-agent-from-package-files) |
22 | | - - [Starting and Enabling Start on Boot](#starting-and-enabling-start-on-boot) |
23 | | - - [Logging](#logging) |
24 | | - - [Building Docker Image](#building-docker-image) |
25 | | -- [Getting Started with NGINX Agent](#getting-started-with-nginx-agent) |
26 | | - - [Installing NGINX](#installing-nginx) |
27 | | - - [Cloning the NGINX Agent Repository](#cloning-the-nginx-agent-repository) |
28 | | - - [Installing Go](#installing-go) |
29 | | - - [Starting the gRPC Mock Control Plane](#starting-the-grpc-mock-control-plane) |
30 | | - - [NGINX Agent Settings](#nginx-agent-settings) |
31 | | - - [Extensions](#extensions) |
32 | | - - [Starting NGINX Agent](#starting-nginx-agent) |
33 | | -- [Development Environment Setup](#development-environment-setup) |
34 | | - - [Selecting an Operating System](#selecting-an-operating-system) |
35 | | - - [Installing NGINX](#installing-nginx) |
36 | | - - [Cloning the NGINX Agent Repository](#cloning-the-nginx-agent-repository) |
37 | | - - [Installing Prerequisite Packages](#installing-prerequisite-packages) |
38 | | - - [Building NGINX Agent from Source Code](#building-nginx-agent-from-source-code) |
39 | | -- [NGINX Agent Technical Specifications](#nginx-agent-technical-specifications) |
40 | | - - [Supported Distributions](#supported-distributions) |
41 | | - - [Supported Deployment Environments](#supported-deployment-environments) |
42 | | - - [Supported NGINX Versions](#supported-nginx-versions) |
43 | | - - [Sizing Recommendations](#sizing-recommendations) |
44 | | -- [Community](#community) |
45 | | -- [Contributing](#contributing) |
46 | | -- [Change Log](#change-log) |
47 | | -- [License](#license) |
| 12 | +- Remote Management: Easily control and configure NGINX instances remotely. |
| 13 | +- Real-Time Metrics: Monitor and analyze performance data for NGINX and the underlying operating system. |
48 | 14 |
|
49 | | -# How it Works |
50 | | -NGINX Agent runs as a companion process on a system running NGINX. It provides gRPC and REST interfaces for configuration management and metrics collection from the NGINX process and operating system. NGINX Agent enables remote interaction with NGINX using common Linux tools and unlocks the ability to build sophisticated monitoring and control systems that can manage large collections of NGINX instances. |
| 15 | +Discover more advanced features and capabilities by visiting: [Try NGINX One: Free Enterprise Trial](https://www.f5.com/trials/nginx-one). |
51 | 16 |
|
52 | | - |
53 | | - |
54 | | -## Configuration Management |
55 | | -NGINX Agent provides an API interface for submission of updated configuration files. Upon receipt of a new file, it checks the output of `nginx -V` to determine the location of existing configurations. It then validates the new configuration with `nginx -t` before applying it via a signal HUP to the NGINX master process. |
56 | | - |
57 | | -## Collecting Metrics |
58 | | -NGINX Agent interfaces with NGINX process information and parses NGINX logs to calculate and report metrics. When interfacing with NGINX Plus, NGINX Agent pulls relevant information from the NGINX Plus API. Reported metrics may be aggregated by [Prometheus](https://prometheus.io/) and visualized with tools like [Grafana](https://grafana.com/). |
59 | | - |
60 | | -The NGINX Agent keeps a connection open to the NGINX Plus API and queries based on the collection interval. This connection gets reported in the metrics and depending on the phase of reporting this connection can show up as idle or active. |
61 | | - |
62 | | -### NGINX Open Source |
63 | | -When running alongside an open source instance of NGINX, NGINX Agent requires that NGINX Access and Error logs are turned on and contain all default variables. |
64 | | - |
65 | | -### NGINX Plus |
66 | | -For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. See [Instance Metrics Overview](https://docs.nginx.com/nginx-instance-manager/monitoring/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, NGINX Agent will automatically use it on startup. |
67 | 17 |
|
68 | 18 | # Installation |
69 | | -## Installing NGINX |
70 | | -NGINX Agent interfaces directly with an NGINX server process installed on the same system. If you don't have it already, follow these steps to install [NGINX Open Source](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) or [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Once installed, ensure the NGINX instance is running. |
71 | | - |
72 | | -## Installing NGINX Agent from Package Files |
73 | | -To install NGINX Agent on your system, go to [Releases](https://github.com/nginx/agent/releases) and download the latest package supported by your OS distribution and CPU architecture. |
74 | | - |
75 | | -Use your system's package manager to install the package. Some examples: |
76 | | - |
77 | | -Debian, Ubuntu, and other distributions using the `dpkg` package manager. |
78 | | - |
79 | | -``` |
80 | | -sudo dpkg -i nginx-agent-<agent-version>.deb |
81 | | -``` |
82 | | -RHEL, CentOS RHEL, Amazon Linux, Oracle Linux, and other distributions using the `yum` package manager |
83 | | -``` |
84 | | -sudo yum localinstall nginx-agent-<agent-version>.rpm |
85 | | -``` |
86 | | -RHEL and other distributions using the `rpm` package manager |
87 | | -``` |
88 | | -sudo rpm -i nginx-agent-<agent-version>.rpm |
89 | | -``` |
90 | | -Alpine Linux |
91 | | -``` |
92 | | -sudo apk add nginx-agent-<agent-version>.apk |
93 | | -``` |
94 | | -FreeBSD |
95 | | -``` |
96 | | -sudo pkg add nginx-agent-<agent-version>.pkg |
97 | | -``` |
98 | | - |
99 | | -## Starting and Enabling Start on Boot |
100 | | -To start the NGINX Agent on systemd systems, run the following command: |
101 | | -``` |
102 | | -sudo systemctl start nginx-agent |
103 | | -``` |
104 | | -To enable the NGINX Agent to start on boot, run the following command: |
105 | | -``` |
106 | | -sudo systemctl enable nginx-agent |
107 | | -``` |
108 | | - |
109 | | -On Alpine Linux, use the following command to start the agent: |
110 | | -``` |
111 | | -sudo service nginx-agent start |
112 | | -``` |
113 | | -To enable the agent to start at boot time on Alpine Linux, run this: |
114 | | -``` |
115 | | -sudo rc-update add nginx-agent default |
116 | | -``` |
117 | | - |
118 | | -## Logging |
119 | | -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. |
120 | | - |
121 | | -### Log Rotation |
122 | | -By default, NGINX Agent rotates logs daily using logrotate with the following configuration: |
123 | | - |
124 | | -```yaml |
125 | | -/var/log/nginx-agent/*.log |
126 | | -{ |
127 | | - # log files are rotated every day |
128 | | - daily |
129 | | - # log files are rotated if they grow bigger than 5M |
130 | | - size 5M |
131 | | - # truncate the original log file after creating a copy |
132 | | - copytruncate |
133 | | - # remove rotated logs older than 10 days |
134 | | - maxage 10 |
135 | | - # log files are rotated 10 times before being removed |
136 | | - rotate 10 |
137 | | - # old log files are compressed |
138 | | - compress |
139 | | - # if the log file is missing it will go on to the next one without issuing an error message |
140 | | - missingok |
141 | | - # do not rotate the log if it is empty |
142 | | - notifempty |
143 | | -} |
144 | | -``` |
145 | | - |
146 | | -If you need to make changes to the default configuration you can update the file here `/etc/logrotate.d/nginx-agent` |
147 | | - |
148 | | -For more detail on logrotate configuration see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate) |
149 | | - |
150 | | - |
151 | | -# NGINX Agent Technical Specifications |
152 | | -## Supported Distributions |
153 | | -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. |
154 | | - |
155 | | -## Supported Deployment Environments |
156 | | -NGINX Agent can be deployed in the following environments: |
157 | | - |
158 | | -- Bare Metal |
159 | | -- Container |
160 | | -- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure |
161 | | -- Virtual Machine |
162 | | - |
163 | | -## Supported NGINX Versions |
164 | | -NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. |
165 | | - |
166 | | -## Sizing Recommendations |
167 | | -Minimum system sizing recommendations for NGINX Agent: |
168 | | - |
169 | | -| CPU | Memory | Network | Storage | |
170 | | -|------------|----------|-----------|---------| |
171 | | -| 1 CPU core | 1 GB RAM | 1 GbE NIC | 20 GB | |
172 | | - |
173 | | -# Community |
174 | | -- Our [NGINX Community](https://community.nginx.org/), is the go-to place to start asking questions and sharing your thoughts. |
175 | 19 |
|
176 | | -- Our [GitHub issues page](https://github.com/nginx/agent/issues) offers space for a more technical discussion at your own pace. |
| 20 | +You can install the **F5 NGINX Agent** using one of the following methods: |
177 | 21 |
|
| 22 | +1. **Official Documentation** |
| 23 | + Follow the step-by-step guide to add and configure instances: |
| 24 | + [How to Add an Instance](https://docs.nginx.com/nginx-one/how-to/nginx-configs/add-instance/) |
178 | 25 |
|
179 | | -# Contributing |
180 | | -Get involved with the project by contributing! Please see our [contributing guide](CONTRIBUTING.md) for details. |
| 26 | +2. **GitHub Releases** |
| 27 | + Download the latest binaries or packages directly from the GitHub releases page: |
| 28 | + [NGINX Agent GitHub Releases](https://github.com/nginx/agent/releases) |
181 | 29 |
|
182 | | -# Change Log |
183 | | -See our [release page](https://github.com/nginx/agent/releases) to keep track of updates. |
| 30 | +3. **Installation and Upgrade Guide** |
| 31 | + Access detailed instructions to install or upgrade the agent from the official NGINX documentation: |
| 32 | + [NGINX Agent Installation Guide](https://docs.nginx.com/nginx-agent/installation-upgrade/) |
184 | 33 |
|
185 | | -# License |
186 | | -[Apache License, Version 2.0](LICENSE) |
| 34 | + |
0 commit comments