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:


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.


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
    
NGINX Agent doesn't reconnect after a containerized Instance Manager without persistent volumes restarts

Description

If Instance Manager restarts, and there are no persistent volumes configured, then the NGINX Agent won’t automatically reconnect after Instance Manager starts up again.

Resolution

If a restart of Instance Manager occurs, then a different IP address may be assigned to Instance Manager’s internal API gateway.

To fix the configuration following a restart, you need to update the Instance Manager IP address. To do so, you can either run NGINX Agent with the --server-host CLI parameter or edit the nginx-agent.conf file. Using the --server-host CLI parameter will persist the Agent host setting for the Instance Manager IP address across restarts.

To learn more, check out the NGINX Agent documentation


Security Monitoring

Total requests count is zero on the Security Monitoring dashboard, but there's been a valid attack

Description

For the Security Monitoring module to gather the total request count processed by NGINX, the following requirements must be enabled:

  • The NGINX Plus API must be enabled
  • Each server block that has NGINX App Protect enabled must have status_zone enabled

Resolution

You can find steps for enabling these requirements in the installation guide for the Security Monitoring module.

Total attack count is greater than total requests processed by NGINX

Description

In some cases, multiple attacks may be logged for a single request sent to NGINX.

This happens if NGINX App Protect WAF is enabled at the server block for content proxied content using proxy_pass.

Resolution

When configuring NGINX App Protect WAF, make sure to enable app_protect_enable in a proxy_pass location. If the configuration returns static content, add a location that enables NGINX App Protect and proxies the request using proxy_pass to the internal static content location.


Example config

load_module modules/ngx_http_app_protect_module.so;

http {
    server {
        listen       127.0.0.1:8080;
        server_name  localhost;
        status_name  default_server

        location / {
            app_protect_enable on;
            proxy_pass    http://127.0.0.1:8080/proxy/$request_uri;
        }

        location /proxy {
            default_type text/html;
            return 200 "Hello! I got your URI request - $request_uri\n";
        }
    }
}

How To Look Up the Installed Version

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

  • Look up the installed version of Instance Manager:

    yum info nms-instance-manager
    
  • Look up the installed version of API Connectivity Manager:

    yum info nms-api-connectivity-manager
    
  • Look up the installed version of the Security Monitoring module:

    yum info nms-sm
    

  • Look up the installed version of Instance Manager:

    dpkg -s nms-instance-manager
    
  • Look up the installed version of API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager
    
  • Look up the installed version of the Security Monitoring module:

    dpkg -s nms-sm