Troubleshooting Guide

This guide explains how to determine, diagnose, and fix issues you might encounter when using Instance Manager.


Known Issues

View the known issues and possible workarounds in the NGINX Management Suite modules:


NGINX Management Suite Platform

NGINX proxy gateway warns "1024 worker_connections are not enough"

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


Instance Manager

New NGINX instances don't show up in Instance Manager

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
    
(RHEL 8) NGINX doesn't start after upgrading NGINX OSS

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
    
Scan reports NGINX versions as `undefined` when NGINX App Protect is enabled

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.

The NGINX Agent does not reconnect after a containerized Instance Manager with no persistent volumes is restarted

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.

"Public Key Not Available" error when upgrading Instance Manager on a Debian-based system

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
    

API Connectivity Manager

System returns `403 Forbidden` errors when users try accessing authorized resources

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.

After installing ACM, the module doesn't show up in the NMS web interface

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
    
Can't delete ACM objects after upgrading NGINX instances

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
    

Check Installed Module Version

To see which version of an NGINX Management Suite module is installed, run the following commands:

  • Instance Manager:

    yum info nms-instance-manager
    
  • API Connectivity Manager:

    yum info nms-api-connectivity-manager
    
  • Security Monitoring module:

    yum info nms-sm
    

  • Instance Manager:

    dpkg -s nms-instance-manager
    
  • API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager
    
  • Security Monitoring module:

    dpkg -s nms-sm