# Add an NGINX instance


> Add NGINX Open Source and NGINX Plus instances to F5 NGINX Instance Manager by installing NGINX Agent for centralized management.


This guide shows you how to add NGINX Open Source and NGINX Plus instances to F5 NGINX Instance Manager so you can manage them from a central dashboard.

## Before you begin

Make sure you have:

- One or more instances running [NGINX Open Source](nginx/admin-guide/installing-nginx/installing-nginx-open-source.md) or [NGINX Plus](nginx/admin-guide/installing-nginx/installing-nginx-plus.md).
- Admin access to NGINX Instance Manager.

## Add instances

1. Open the NGINX Instance Manager web interface and log in.
2. In the **Manage** section on the left, select **Instances**.
3. Select **Add**.
4. Copy the `curl` command.
5. On the host where your NGINX instance is running, run the `curl` command to install NGINX Agent:

   ```shell
   curl https://<NIM_FQDN>/install/nginx-agent | sudo sh
   ```

6. On the same host, run the following command to start NGINX Agent:

   ```shell
   sudo systemctl start nginx-agent
   ```

## Set up metrics reporting

### Enable NGINX Plus API

To collect comprehensive metrics for NGINX Plus, including bytes streamed, information about upstream systems and caches, and counts of all HTTP status codes, add the following to your NGINX Plus configuration file, for example `/etc/nginx/nginx.conf` or an included file:

**Note:** 
- By default, all clients can call the API.  
- To limit who can access the API, uncomment the `allow` and `deny` lines under `api write=on` and replace the example CIDR with your trusted network.  
- To restrict write methods (`POST`, `PATCH`, `DELETE`), uncomment and configure the `limit_except GET` block and set up [HTTP basic authentication](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html).  

**Note:** 
If there are issues with NGINX Agent discovering the NGINX Plus API, NGINX Agent can be manually configured with the address of the NGINX Plus API. 

- Add the following configuration to `/etc/nginx-agent/nginx-agent.conf`:
```
data_plane_config:
  nginx:
    api:
      url: "http://127.0.0.1:9000/api"
```
- Restart NGINX Agent for the configuration changes to take affect
```
sudo systemctl restart nginx-agent
```

- Run the following command 
```
sudo journalctl -u nginx-agent | grep "Found NGINX Plus API"
``` 
- Ensure that the following log message is seen 
```
Found NGINX Plus API
```

For more details, see the [NGINX Plus API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) documentation and [Configuring the NGINX Plus API](/nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api).

### Enable NGINX Open Source Metrics

To collect basic metrics about server activity for NGINX Open Source:

1. **Enable the stub status API**

Add the following to your NGINX configuration file:

```nginx
server {
   listen 127.0.0.1:8080;
   location /api {
       stub_status;
       allow 127.0.0.1;
       deny all;
   }
}
```

**Note:** 
Make sure that the `server` and  `location` blocks are in the same configuration file, and not split across multiple files using `include` directives.

This configuration:

- Enables the stub status API endpoint.
- Allows requests only from `127.0.0.1` (localhost).
- Blocks all other requests for security.

For more details, see the [NGINX Stub Status module documentation](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html).

2. **Configure access logging** 

Enable access logging in your NGINX configuration to collect detailed traffic metrics. Ensure that the following log format is used:

```nginx
log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" '
'"$bytes_sent" "$request_length" "$request_time" '
'"$gzip_ratio" $server_protocol ';

access_log  /var/log/nginx/access.log  main;
```

This log format captures key metrics including request timing, response sizes, and client information.

## Next steps

- [Add instances to instance groups](nim/nginx-instances/manage-instance-groups.md)
- [Add managed certificates](nim/nginx-instances/manage-certificates.md)