Known Issues

This document lists and describes the known issues and possible workarounds in NGINX Instance Manager. Fixed issues are removed after 45 days.

We recommend you upgrade to the latest version of Instance Manager to take advantage of new features, improvements, and bug fixes.

2.3.0

Scan misidentifies some NGINX OSS instances as NGINX Plus

Description

When NGINX Plus is installed on a datapath instance, then removed and replaced with NGINX OSS, NGINX Instance Manager may incorrectly identify the instance as an NGINX Plus instance. This is due to multiple NGINX entries for the same datapath.

Workaround

Use NGINX Instance Manager’s NGINX Instances API to remove the inactive NGINX instance. For instructions, refer to the API reference guide, which you can find at https://<NGINX-INSTANCE-MANAGER-FQDN>/ui/docs.

You may need to stop the NGINX Agent first. To stop the NGINX Agent, run the following command:

sudo systemctl stop nginx-agent

Metrics may report additional data

Description

NGINX Instance Manager reports metrics at a per-minute interval and includes dimensions for describing the metric data’s characteristics.

An issue has been identified in which metric data is aggregated across all dimensions, not just for existing metrics data. When querying the Metrics API with aggregations like SUM(metric-name), the aggregated data causes the API to over count the metric. This overcounting skews some of the metrics dashboards.

Workaround

When querying the Metrics API, you can exclude the data for an aggregated dimension by specifying the dimension name in the filterBy query parameter.

filterBy=<dimension-name>!= ''

Unable to publish config changes to a custom nginx.conf location

Description

Using Instance Manager to publish a config may fail if the NGINX Instance has the configuration file stored in a folder other than the default.

Workaround

Use the default location for the configuration file.

2.2.0

Post-install steps to load SELinux policy are in the wrong order

Description

After installing Instance Manager, the post-installation steps shown in the command-line output say to start the NGINX Management Suite services before loading the included SELinux policy. These steps are transposed. You need to load the SELinux policy first and start the NMS services after; otherwise, the NMS services will be unconfined.

Workaround

See the Enforce Security with SELinux Policy guide for the correct instructions.

Giving long names (255+ characters) to certificates causes internal error

Description

When adding certificates, an internal error (error code: 134018) is returned if the name given for the certificate exceeds 255 characters.

Workaround

Use a name that is 255 or fewer characters.

Associating instances with expired certificates causes internal error

Description

An internal error (error code: 134018) is reported when adding an expired certificate if the certificate is associated with an instance.

Workaround

If possible, use a certificate that isn’t expired.

NGINX service may fail to start after upgrading NGINX OSS on RHEL 8

Description

In some cases, after NGINX OSS is upgraded on RHEL 8, the NGINX service fails to start and returns an error similar to the following:

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

Workaround

1. Run the following commands:

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

2. Restart the NGINX service:

   sudo service nginx restart
   

2.1.0

Running Agent install script with sh returns “not found” error

Description

When running the NGINX Agent install script with sh, an error similar to the following is reported:

"171: [[: not found"

This message is only a warning and does not interrupt the installation processes.

Workaround

Run the script with bash.

Duplicate instances are shown after upgrading Agent to 2.1.0

Description

After upgrading to NGINX Instance Manager 2.1.0, and updating nginx-agent from platform packaging, duplicate instances may appear on the Instance overview page. This issue is caused by a change in how the NGINX Agent generates the system_uid.

Workaround

You can safely delete the older entries or wait for them to expire.

Helm chart deployments don’t support OIDC

Description

OIDC is not supported for helm chart deployments of NGINX Instance Manager on Kubernetes. Only basic auth is supported.

“No such process” error occurs when publishing a configuration

Description

When publishing a configuration, you might encounter an error similar to the following example:

config action failed: Config apply failed (write): no such process

This error can occur when there is a desyncronization between the NGINX Agent and NGINX PID, often after manually restarting NGINX when the Agent is running.

Workaround

Restart the NGINX Agent:

sudo systemctl restart nginx-agent

2.0.0

“Option unknown” password error when installing Instance Manager on Ubuntu with OpenSSL v1.1.0

Description

When installing NGINX Instance Manager on Ubuntu with OpenSSL v1.1.0, you might see an error similar to the following example:

  Generating default password for ‘admin’ user account
  Using openssl version 1.1
  passwd: Option unknown option -6
  passwd: Use -help for summary.
  dpkg: error processing package nms-instance-manager

If you receive this error during the installation, your version of OpenSSL is not compatible with the password hashing algorithm used to generate an initial admin password.

Workaround

Upgrade your OpenSSL version to v1.1.1 or later:

  sudo apt-get install openssl

After updating OpenSSL this way, apt will re-try installing NGINX Instance Manager.

NGINX App Protect WAF blocks Instance Manager from publishing configurations

Description

NGINX Instance Manager does not currently support managing NGINX App Protect WAF instances. NGINX App Protect WAF may block attempts to publish configurations to NGINX App Protect WAF instances.

Web interface returns Bad Gateway (502) error on RHEL 7

Description

On RHEL 7, when authenticating with basic auth, the web interface becomes unresponsive and returns a 502 error.

Workaround

1. Verify that NGINX is added to the NMS group:

   id nginx
   

   The expected output looks similar to the following example:

   uid=994(nginx) gid=991(nginx) groups=991(nginx),992(nms)
   

2. If the NMS group is missing, run the following command to add it:

   usermod -a -G nms nginx
   

3. Restart each daemon:

   systemctl start nms-core
   systemctl start nms-dpm
   systemctl start nms-ingestion
   

Tag-based access controls are not enforced for instance groups

Description

When using the experimental Instance Groups feature, access controls based on instance tags are not enforced. We recommend only using Instance Groups at this time if you are not relying on tag-based access controls.

Instance Manager reports old NGINX version after upgrade

Description

After upgrading NGINX to a new version, the NGINX Instance Manager web interface and API report the old NGINX version until the NGINX Agent is restarted.

Workaround

Restart the Agent to have the new version reflected properly:

systemctl restart nginx-agent

“granting scope: forbidden” error if user granting permissions belongs to multiple roles

Description

If a user is assigned to multiple roles for Instance Management and Settings, and the user has WRITE access for Settings, which allows for creating new roles, the user cannot grant permissions to new roles or existing ones. The system returns an error similar to the following:

Error granting scope: forbidden. You cannot grant access for a scope you are not assigned to.

Workaround

Combine all permissions into one role for the user, allowing them to create new roles with the same set of permissions.

Web interface doesn’t report error when failing to upload large config files

Description

In the web interface, when uploading a config file that’s larger than 50 MB (max size), the system incorrectly reports the state as Analyzing (Status code 403), although the upload failed.

Workaround

Keep config files under 50 MB.

Include cycles in the configuration cause the analyzer to timeout

Description

A configuration containing a cycle will cause the analyzer to timeout before causing an nms-dpm restart.

nginx.conf:
http {
include conf.d/server-1.conf
}
conf.d/server-1.conf:
server {
listen 80;
include conf.d/server-2.conf
}

conf.d/server-2.conf
server {
listen 443;
include conf.d/server-1.conf
}

Workaround

Avoid uploading configurations that contain cycles.

Cannot register multiple Agents in containers on the same host

Description

NGINX Instance Manager 2.0.0 does not support containers at this time. Look for support in a future release.

CentOS 7, RHEL 7, and Amazon Linux 2 package managers allow unsupported NGINX/NGINX Plus versions

Description

When installing on CentOS 7, RHEL 7, and Amazon Linux 2, the package manager doesn’t prevent installing NGINX Instance Manager with unsupported versions of NGINX or NGINX Plus. As a consequence, it is possible that nms-instance-manager is installed without an NGINX gateway. Resulting in a less than optimal experience.

Workaround

Install a supported version of NGINX (v1.18 or later) or NGINX Plus (R22 or later). See the Technical Specifications guide for details.

gRPC errors when starting Instance Manager

Description

When starting NGINX Instance Manager, you may see errors similar to the following in /etc/nginx/conf.d/nms-http.conf:227:

nginx[1234]: nginx: [emerg] unknown directive "grpc_socket_keepalive"

Workaround

Make sure your version of NGINX is v1.18 or later. See the Technical Specifications guide for details.