Release Notes 2.0.0

These release notes contain information about new features, improvements, and known issues in NGINX Instance Manager.

We recommend installing the latest version of NGINX Instance Manager to take advantage of the newest features and updates.

December 21, 2021


NGINX Instance Manager 2.0.0 includes the following updates:

  • New architecture!

    We redesigned and improved the architecture of NGINX Instance Manager! Because of these changes, upgrading to version 2.0 is different. Make sure to read the Migration Guide for instructions.

  • Improved user access control

    NGINX Instance Manager 2.0. allows you to create user access controls with tags. Administrators can grant users read or write access to perform instance management tasks. And admins can grant or restrict access to the Settings options, such as managing licenses and creating users and roles. See the Configure Authentication guide for more details.

  • More metrics and instance dashboards

    NGINX Instance Manager now collects additional metrics from the NGINX instances. We also added pre-configured dashboards to the web interface for each NGINX instance managed by NGINX Instance Manager. See the Catalog Reference documentation for a complete list of metrics.

  • (Experimental) Share a configuration across multiple instances

    With a feature called Instance Groups, you can share the same configuration across multiple instances. So, if your website requires a number of instances to support the load, you can publish the same configuration to each instance with ease.

Known Issues

The following issues are known to be present in this release. Look for updates to these issues in future release notes.

  • gRPC errors occur when starting NGINX Instance Manager (28683)

    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"


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

  • NGINX/NGINX Plus is not a requirement when installing NGINX Instance Manager on CentOS 7, RHEL 7, and Amazon Linux 2 (28758)

    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.


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

  • Include cycles in the configuration cause the analyzer to spin (31025)

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

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


    Avoid uploading configurations that contain cycles.

  • The web interface doesn’t report an error when uploading config files larger than 50 MB (max size) (31081)

    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.


    Keep config files under 50 MB.

  • System reports “error granting scope: forbidden” if user granting permissions belongs to more than one role (31215)

    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.”


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

  • After upgrading NGINX, NGINX Instance Manager reports the old NGINX version (31225)

    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.


    Restart the Agent to have the new version reflected properly:

    systemctl restart nginx-agent
  • When using Instance Groups, tag-based access controls are not enforced (31267)

    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.

  • Bad Gateway (502) errors with Red Hat 7 (31277)

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


    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
  • Unable to access the NGINX Instance Manager web interface after loading SELinux policy (31583)

    The web interface is unavailable after installing NGINX Instance Manager 2.0.0 and loading the associated SELinux policy.


    • Switch to permissive mode.


    • Upgrade to NGINX Instance Manager 2.0.1 or later.

  • The nms-dpm service restarts when registering multiple NGINX Agents with the same identity (31612)

    When multiple NGINX Agents with the same identity register with NGINX Instance Manager at the same time, the nms-dpm service may restart. In the the nms.log file on the affected data plane host, you’ll find entries mentioning func NginxConfigUpdate.

    This issue most often affects Docker hosts with multiple containers running NGINX Agents registered with NGINX Instance Manager.

    No action should be required to recover or restart the nms-dpm service.


    • Upgrade to NGINX Instance Manager 2.0.1 or later.
  • Unable to register multiple NGINX Agents in containers on the same host (31739)

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

Supported Versions