Troubleshooting Guide

Description

If the NGINX proxy gateway for NGINX Management Suite alerts you that there are not enough worker connections, you may need to modify the NGINX configuration (/etc/nginx/nginx.conf on the NGINX Management Suite host) to allow more worker connections and increase the number of file descriptors for worker processes.

Resolution

• For guidance on increasing the number of worker connections and file descriptors for the NGINX proxy gateway for NGINX Management Suite, refer to the guide Optimize NGINX Proxy Gateway for Large Data Planes.

Description

After installing NGINX and the NGINX Agent on an instance, the instance is not returned when calling GET https://hostname/api/platform/v1/systems.

Resolution

The NGINX service must be running before you start the NGINX Agent.

• To resolve the issue, try restarting the NGINX Agent:

  sudo systemctl restart nginx-agent
  

Description

In some cases, after upgrading NGINX OSS on RHEL 8, the NGINX service may not start and returns an error similar to the following:

Job for nginx.service failed because the control process exited with error code.

The error log may include entries similar to the following example:

022/05/12 16:11:23 [emerg] 69688#69688: still could not bind()
22022/05/12 16:18:34 [emerg] 70092#70092: bind() to 0.0.0.0:80 failed (98: Address already in use)

Resolution

Ensure there isn’t a process bound to port 80 or 443.

1. To stop processes bound to ports 80 and 443, run the following commands:

   sudo fuser -k 80/tcp
   sudo fuser -k 443/tcp
   

2. Restart the NGINX service:

   sudo service nginx restart
   

Description

When scanning for NGINX instances, the NGINX version is reported as undefined when NGINX App protect is installed.

Resolution

This behavior is by design. As a security precaution when NGINX App Protect is installed, the NGINX server does not report its version in any HTTP headers. The NGINX Plus and Instances pages in the web interface will continue to report the NGINX and NGINX App Protect versions.

Description

If Instance Manager is restarted without any persistent volumes configured, the NGINX Agent won’t reconnect automatically.

Resolution

When Instance Manager is restarted, its internal API gateway may be assigned a new IP address.

To update the NGINX Agent’s configuration with the new Instance Manager IP address, run the NGINX Agent with the --server-host CLI parameter or edit the nginx-agent.conf file. Using the --server-host CLI parameter will ensure that the setting persists across restarts.

To learn more, refer to the NGINX Agent documentation.

Description

When attempting to upgrade Instance Manager on a Debian-based system, the command sudo apt-get update may return the error “public key is not available,” preventing the NGINX Agent from being updated. To resolve this issue, you need to update the public key first.

Workaround

To manually update the public key, take the following steps:

1. Download a new key from the NGINX Management Suite host:

   • Secure:

     curl https://<NMS_FQDN>/packages-repository/nginx-signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-signing.gpg >/dev/null
     

   • Insecure:

     curl -k https://<NMS_FQDN>/packages-repository/nginx-signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-signing.gpg >/dev/null
     

2. Update the nginx-agent.list file to reference the new key:

   printf "deb [signed-by=/usr/share/keyrings/nginx-signing.gpg] https://<NMS_FQDN>/packages-repository/deb/ubuntu `lsb_release -cs` agent\n" | sudo tee /etc/apt/sources.list.d/nginx-agent.list
   

Description

Users are unable to access ACM features that they’ve been granted permission for.

The system returns errors similar to the following examples:

• Web interface error: “ACM license not found.”

• API error: “Error accessing resource: forbidden. Please contact the system administrator. User has not been granted READ permission.”

Resolution

New roles require a minimum of READ access for the Licensing feature. Without READ access for Licensing, users will be unable to access pages for which they have been granted permission; instead, the system will return 403 Forbidden errors as licensing errors.

Description

After installing the API Connectivity Manager module, the module doesn’t appear in the NGINX Management Suite web interface.

Resolution

• Force refresh the web page.

• Restart the ACM service:

  sudo systemctl restart nms-acm
  

Description

After upgrading NGINX Plus instances to R27, you may not be able to delete Environments, Proxies, or Dev Portals in the API Connectivity Manager module.

Resolution

Try restarting the NGINX Agent after upgrading NGINX.

• To restart the NGINX Agent, run the following command:

  sudo systemctl restart nginx-agent