Release Notes

The release notes for F5 NGINX Instance Manager highlight the latest features, improvements, and bug fixes in each release. This document helps you stay up to date with the changes and enhancements introduced to improve stability, performance, and usability. For each version, you’ll find details about new features, known issues, and resolved problems, ensuring you get the most out of your NGINX instance management experience.

2.18.0

November 8, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.15.x - 2.17.x

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Adds support for NGINX App Protect WAF v5

  NGINX Instance Manager 2.18.0 adds support for NGINX App Protect WAF v5.3 and v4.11.

  NGINX App Protect WAF v5, designed for both NGINX Open Source and NGINX Plus environments, includes a dynamic NGINX module and containerized WAF services. It provides robust security and scalability.

• Ridiculously easy NGINX Instance Manager installation script (Bash)

  Reduce the number of steps to deploy all NGINX Instance Manager components, including prerequisites, using a single installation script. The script supports every OS that NGINX Instance Manager supports in the technical specifications.

  The script installs NGINX (Plus or Open Source), ClickHouse, and NGINX Instance Manager. Customers only need their NGINX Plus certificate, key, and, for NGINX Plus R33 or later, a JWT downloaded from MyF5. Support for offline installations will be added in a future update.

  Support for offline installations is also available for air-gapped environments.

• Entitlement and visibility for NGINX Plus R33 – Telemetry reporting for network-restricted environments

  If NGINX Instance Manager has internet access, customers can automatically or manually send the usage data to F5 as part of the new NGINX Plus R33 changes.

  For customers who have NGINX Instance Manager deployed in network-restricted environments, this release also includes support for manual usage reporting. Customers can now manually license NGINX Instance Manager and export usage telemetry for fully disconnected environments. For usage reporting, customers can:

  • Export the usage report: Manually export the usage report from NGINX Instance Manager.
  • Send the report to F5: Submit the report to F5 for verification from a location with internet access.
  • Upload the acknowledgment: After verification, upload the acknowledgment from F5 to NGINX Instance Manager.

• Resilient Docker Compose NGINX Instance Manager deployment

  In 2.17, we released a bundled container image with all NGINX Instance Manager components. While this is a great option for demos and lab environments, it is not the most fault-tolerant for production.

  This Docker Compose option unlocks another easy, production-ready installation method for customers using Docker. It will also make upgrades easier when new Docker images are released by F5 NGINX. This option includes health checking, NGINX App Protect compilation support, and security monitoring.

Changes in Default Behavior

This release has the following changes in default behavior:

• The NGINX Usage page now only shows instances configured with the NGINX Plus R33 mgmt block.

  The “NGINX Usage” page previously displayed instances connected to NGINX Instance Manager through multiple methods, including the NGINX Agent, health checks, and the mgmt block in NGINX Plus R31-R32. With the introduction of native reporting in NGINX Plus R33, only instances using this feature appear on the page, preventing duplicates. For more information on R33 usage reporting, see About subscription licenses.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Mismatch in date formats in custom date selection on NGINX usage graph (45512)
• Failure to notify user when template configuration publish fails (44975)

Known Issues

You can find information about known issues in the Known Issues topic.

2.17.4

November 06, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.14.0 - 2.17.3

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Stability and performance improvements

  This release includes stability and performance improvements.

Known Issues

You can find information about known issues in the Known Issues topic.

2.17.3

September 13, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.14.0 - 2.17.2

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• GPG key update for NGINX Agent packages

  Previous releases of NGINX Instance Manager included NGINX Agent packages signed with an expired GPG key. This release of NGINX Instance Manager includes updated keys, allowing users to successfully download the NGINX Agent from NGINX Instance Manager.

Known Issues

You can find information about known issues in the Known Issues topic.

2.17.2

August 21, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.14.0 - 2.17.1

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Stability and performance improvements

  This release includes stability and performance improvements for a more reliable experience.

Known Issues

You can find information about known issues in the Known Issues topic.

2.17.1

July 24, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.14.0 - 2.17.0

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Stability and performance improvements

  This release includes stability and performance improvements for a more reliable experience.

Known Issues

You can find information about known issues in the Known Issues topic.

2.17.0

July 10, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.14.0 - 2.16.0

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Adds support for NGINX App Protect WAF v5

  NGINX Instance Manager 2.17.0 adds support for NGINX App Protect WAF v5..

  NGINX App Protect WAF v5 (designed for both NGINX Open Source and NGINX Plus environments) consists of a dynamic NGINX module and containerized WAF services, providing robust security and scalability.

• Hosted Docker images for Kubernetes Helm charts

  Prior to this release, users had to download NGINX Instance Manager docker images and push them to their local container registry for use in the Kubernetes Helm charts. This was not very turnkey and required multiple steps before being able to use the Helm charts. Now all Instance Manager container images are available from F5’s public docker repository, simplifying the installation in Kubernetes.

  See the Deploy Instance Manager on Kubernetes documentation for more information.

• Ansible role to deploy NGINX Instance Manager

  This release comes with an Ansible role to help you Install NGINX Instance Manager quickly, while also encouraging the best practices for your chosen environment.

• NGINX Instance Manager IaC using Packer and Terraform

  This release improves the Infrastructure as Code (IaC) project to help you quickly get started with NGINX Instance Manager using Packer and Terraform.

  The project uses Packer to create images and Terraform to deploy these images to your preferred cloud provider, including GCP, Azure, or vSphere.

• Single docker image with all the NGINX Instance Manager services and dependencies

  This release includes access to a single Docker image for running NGINX Instance Manager as a container. This allows customers to deploy Instance Manager locally with a single “docker run” command. For more details, see Deploy NGINX Instance Manager in a Single Docker Container.

Changes in Default Behavior

This release has the following changes in default behavior:

• Web Analytics

  NGINX Instance Manager now collects and sends anonymized telemetry and interaction information for analysis by F5 NGINX. This information is used to improve our products and services.

  Customers have the option to opt out of data collection by disabling the feature in the Instance Manager web interface, using the Account menu in the top-right corner of the screen. For more details, see Configure Telemetry and Web Analytics.

• Augment Template order now matches NGINX configuration structure

  When you generate a configuration using augment templates, the order shown in the UI now matches the structure of an NGINX configuration. This makes filling out a template more intuitive.

• End of support for CentOS 7 and Red Hat Enterprise Linux 7

  CentOS 7 and Red Hat Enterprise Linux 7 reached end of maintenance support on June 30, 2024.

  Since these operating systems won’t get any more updates or security patches, NGINX Instance Manager no longer supports them.

  Please upgrade your environment to one of the supported distributions to continue using NGINX Instance Manager.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Users receive login error when NGINX Management Suite is deployed in Kubernetes (44686)
• REST API does not work until you log into the web interface first (44877)
• Editing template submissions uses the latest versions, may cause “malformed” errors (44961)
• Editing template submissions now allows for using most recent template version (44971)

Known Issues

You can find information about known issues in the Known Issues topic.

2.16.0

April 18, 2024

Upgrade Paths

NGINX Instance Manager supports upgrades from these previous versions:

• 2.13.0 - 2.15.1

If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Introducing configuration templates for simplifying NGINX configurations and self-service workflows

  This release of NGINX Instance Manager introduces Config Templates. These templates use Go templating to make it easier to set up and standardize NGINX configurations. Now, you don’t need to know all the details of NGINX syntax to create a working configuration. Just provide the required inputs for a template, and the system will do the rest. This makes setting up NGINX simpler and helps you follow best practices.

  To provide more control over your configurations, augment templates let you modify only specific segments of your NGINX configuration. This, when combined with RBAC for template submissions, enables self-service workflows. Look for pre-built templates for common scenarios in our GitHub repositories soon.

• Stability and performance improvements

  This release enhances system stability and performance.

Changes in Default Behavior

This release has the following changes in default behavior:

• Change in NGINX Agent upgrade behavior

  Starting from version v2.31.0, the NGINX Agent will automatically restart itself during an upgrade.

Known Issues

You can find information about known issues in the Known Issues topic.

2.15.1

February 14, 2024

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.12.0 - 2.15.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Stability and performance improvements

  This release includes stability and performance improvements.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Helm chart backup and restore is broken in NIM 2.15.0 (44758)
• Unable to use NMS Predefined Log Profiles for NAP 4.7 (44759)

Known Issues

You can find information about known issues in the Known Issues topic.

2.15.0

December 12, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.12.0 - 2.14.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Support for CA Certificates added

  Instance Manager now allows for managing CA Certificates to fully support NGINX directives such as proxy_ssl_trusted and proxy_ssl_verify. The main difference after this change is that you no longer need a corresponding key to upload a certificate to Instance Manager.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Instances reporting incorrect memory utilization (44351)
• Data on the dashboard is updating unexpectedly (44504)
• Missing Data when ClickHouse services are not running (44586)
• NGINX App Protect Attack Signature, Threat Campaign and Compiler fail to download (44603)

Known Issues

You can find information about known issues in the Known Issues topic.

2.14.1

October 19, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.11.0 - 2.14.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Stability and performance improvements

  This release includes stability and performance improvements.

Known Issues

You can find information about known issues in the Known Issues topic.

2.14.0

October 16, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.11.0 - 2.13.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Instance Manager Dashboard

  Monitor the health and performance of your NGINX instance fleet from a single page. Get insights and trends on CPU, memory, disk, and network traffic utilization. Quickly spot and mitigate common HTTP errors and TLS certificate issues. See the Instance Manager Dashboard documentation to learn more.

• Work with NGINX App Protect Bundles from Instance Manager

  Starting with Instance Manager 2.14, you can now use the “/security/policies/bundles” endpoint to create, read, update, and delete NGINX App Protect bundles, which allow faster deployment through pre-compilation of security policies, attack signatures, and threat-campaign. For additional information on how to use the API endpoint, refer to your product API documentation. To learn more about this feature, see the Manage WAF Security Policies documentation.

• Clickhouse LTS 23.8 support

  This release of Instance Manager has been tested and is compatible with Clickhouse LTS versions 22.3.15.33 to 23.8.

Changes in Default Behavior

This release has the following changes in default behavior:

• Inactive NGINX instances are automatically removed over time

  If an NGINX instance has been inactive (NGINX Agent not reporting to NGINX Management Suite) for a fixed amount of time, it is now automatically removed from the instances list. Instances deployed in a virtual machine or hardware are removed after 72 hours of inactivity, and those deployed in a container are removed after 12 hours.

Known Issues

You can find information about known issues in the Known Issues topic.

2.13.1

September 05, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.10.0 - 2.13.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Validation errors in Resource Groups for certificates uploaded before 2.13 upgrade (44254)
• Access levels cannot be assigned to certain RBAC features (44277)

Known Issues

You can find information about known issues in the Known Issues topic.

2.13.0

August 28, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.10.0 - 2.12.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Easily manage access to specific objects with Resource Groups

  With NGINX Instance Manager, you can now combine Instances, Instance Groups, and Certificates into a Resource Group. This grouping can be used when defining roles to grant access to those specific objects. When objects are added to or removed from the Resource Group, the changes are automatically reflected in any roles that use the Resource Group. For more details, refer to Working with Resource Groups.

• Get version controlled NGINX configurations with an external commit hash

  The Instance Manager REST API supports setting and retrieving instances, instance groups, and staged NGINX configurations using a version control commit hash.

  To learn how to use a commit hash with NGINX configurations, refer to these topics:

  • Add Hash Versioning to Staged Configs
  • Publish Configs with Hash Versioning to Instances
  • Publish Configs with Hash Versioning to Instance Groups

• Configure analytics data retention with the nms.conf file

  You can set the data retention policy for analytics data, which includes metrics, events, and security events, in the nms.conf file. By default, metrics and security events are stored for 32 days, while events are stored for 120 days. To keep data for a longer period, update the retention durations in the nms.conf file.

• RBAC for security policies

  You can now use Role-Based Access Control (RBAC) to allow or restrict the level of access to security policies according to your security governance model.

• RBAC for log profiles

  You can now use Role-Based Access Control (RBAC) to allow or restrict access to log profiles according to your security governance model.

• Use NGINX Plus Health Checks to easily track NGINX Plus Usage with NGINX Instance Manager

  The NGINX Plus Health Check feature now allows you to monitor the count of both NGINX Plus and NGINX App Protect instances that you’ve deployed. You can view this information in the “NGINX Plus” area of the “Instance Manager” web interface, or through the /inventory API. For guidance on how to set this up, refer to the following documentation: View Count of NGINX Plus Instances.

• Improved log output for better JSON parsing

  In the log output, extra whitespace has been removed, and brackets have been removed from the log level field. This results in clean, parsable log output, particularly when using JSON log encoding.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• An “unregistered clickhouse-adapter” failure is logged every few seconds if logging is set to debug. (43438)

Known Issues

You can find information about known issues in the Known Issues topic.

2.12.0

July 20, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.9.0 - 2.11.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• New support for license tokens for automatic entitlement updates, renewals, and Flexible Consumption Reporting

  NGINX Management Suite now supports license tokens formatted as a JSON Web Token (JWT). With JWT licensing, you can automatically update entitlements during subscription renewals or amendments, and you can automate reporting for the Flexible Consumption Program (FCP). For more information, see the Add a License topic.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Filtering Analytics data with values that have double backslashes (\\) causes failures (42105)
• Unable to publish configurations referencing the log bundle for Security Monitor (42932)
• Disk Usage in Metrics Summary shows incorrect data when multiple partitions exist on a system (42999)

Known Issues

You can find information about known issues in the Known Issues topic.

2.11.0

June 12, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.8.0 - 2.10.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• The config editor now lets you see auxiliary files

  Auxiliary files, such as certificate files and other non-config files on managed instances or instance groups, are now visible in the file tree of the config editor view. This improvement makes it easier to reference these files within a configuration.

• Introducing new predefined log profiles for NGINX App Protect WAF

  Now, managing your NGINX App Protect WAF configuration is even easier with new predefined log profiles. In addition to the existing log_all, log_blocked, log_illegal, and log_secops log profiles, the following new predefined log profiles are now available:

  • log_f5_arcsight
  • log_f5_splunk
  • log_grpc_all
  • log_grpc_blocked
  • log_grpc_illegal

  These new log profiles make it even easier to integrate NGINX App Protect WAF with other logging systems, such as Splunk, ArcSight, and gRPC.

• You can now install Advanced Metrics automatically when you install NGINX Agent

  When installing the NGINX Agent with NGINX Management Suite, you can include the -a or --advanced-metrics flag. Including this option installs the Advanced Metrics module along with the NGINX Agent. With this module, you gain access to extra metrics and insights that enrich the monitoring and analysis capabilities of the NGINX Management Suite, empowering you to make more informed decisions.

• NGINX Management Suite can send telemetry data to F5 NGINX

  In order to enhance product development and support the success of our users with NGINX Management Suite, we offer the option to send limited telemetry data to F5 NGINX. This data provides valuable insights into software usage and adoption. By default, telemetry is enabled, but you have the flexibility to disable it through the web interface or API. For detailed information about the transmitted data, please refer to our documentation.

Changes in Default Behavior

This release has the following changes in default behavior:

• The location of agent-dynamic.conf has changed

  In this release, the agent-dynamic.conf file has been moved from /etc/nginx-agent/ to /var/lib/nginx-agent/. To assign an instance group and tags to an instance, you will now need to edit the file located in /var/lib/nginx-agent/.

• Action required:Update OIDC configurations for management plane after upgrading to Instance Manager 2.11.0

  In Instance Manager 2.11.0, we added support for telemetry to the OIDC configuration files. Existing OIDC configurations will continue to work, but certain telemetry events, such as login, may not be captured.

• Configuration file permissions have been lowered to strengthen security

  To strengthen the security of configuration details, certain file permissions have been modified. Specifically, the following configuration files now have lowered permissions, granting Owner Read/Write access and Group Read access (also referred to as 0640 or rw-r-----):

  • /etc/nms/nginx.conf
  • /etc/nginx/conf.d/nms-http.conf
  • /etc/nms/nginx/oidc/openid_configuration.conf
  • /etc/nms/nginx/oidc/openid_connect.conf

  Additionally, the following file permissions have been lowered to Owner Read/Write and Group Read/Write access (also known as 0660 or rw-rw-----):

  • /logrotate.d/nms.conf
  • /var/log/nms/nms.log

  These changes aim to improve the overall security of the system by restricting access to sensitive configuration files while maintaining necessary privileges for authorized users.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Count of NGINX Plus graph has a delay in being populated (37705)
• Duplicate Certificate and Key published for managed certificates (42182)
• The Metrics module is interrupted during installation on Red Hat 9 (42219)
• Certificate file is not updated automatically under certain conditions (42425)
• Certificate updates allow for multiples certs to share the same serial number (42429)

Known Issues

You can find information about known issues in the Known Issues topic.

2.10.1

May 22, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.7.0 - 2.10.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Valid licenses incorrectly identified as invalid (42598)

Known Issues

You can find information about known issues in the Known Issues topic.

2.10.0

April 26, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.7.0 - 2.9.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• New "Category" Filter in the Events web interface

  You can now filter entries in the Events web interface using a new “Category” filter. Categories for event entries include “Certs”, “Instance Groups”, and “Templates”.

• New NGINX Agent install flag for NGINX App Protect WAF

  The NGINX Agent installation script now has a flag to enable the default configuration required for NGINX App Protect WAF. It is used to retrieve the deployment status and precompiled_publication mode, with an option for the NGINX App Protect WAF instance to use the mode for policies.

• NGINX Management Suite version now visible in the web interface and API

  You can now look up the NGINX Management Suite and NGINX Instance Manager versions in the web interface and API. Other module versions are also visible, though older versions of API Connectivity Manager and Security Monitoring may appear as undefined.

• NGINX Management Suite can now use NGINX Ingress Controller to manage routing

  The NGINX Management Suite Helm Chart can now generate an NGINX Ingress Controller VirtualServer definition, which can be used to expose NGINX Management Suite when running in your Kubernetes cluster. More about the VirtualServer custom resource can be found in the VirtualServer and VirtualServerRoute documentation.

• Configuration Publication Status now visible in App Security pages.

  The most recent publication date and status for an instance’s configuration is now visible on App Security Pages. This reflects configuration for NGINX, NGINX App Protect policies, Attack Signatures and Threat Campaigns.

• Instance Manager can now automatically retrieve WAF compilers associated with NGINX App Protect instances

  Using a user-provided NGINX repository certificate & key after the first set-up of the WAF compiler, Instance Manager can automatically retrieve WAF compilers associated with NGINX App Protect instances. These can be used to publish App Protect WAF configurations in precompiled_publication mode.

• Add option to toggle ICMP scanning in the web interface

  You can now explicitly enable or disable ICMP scanning at the top of the “Scan” interface.

• New NGINX Agent install flag for Security Monitoring

  The NGINX Agent installation script now has a flag to enable the default configuration required for the Security Monitoring module.

Changes in Default Behavior

This release has the following changes in default behavior:

• Improvements to Role Based Access Control for SSL Certificate and Key management

  Role Based Access Control for SSL Certificate and Key management can now use three different objects for precise controls: certificates, systems, and instance groups. Using certificates as an object controls the viewing and assigning of specific certificate and key pairs. Using systems or instance groups allows a user to see all certificates but restricts access for publishing.

• By default, NGINX Management Suite is not exposed to the internet when installed with a Helm Chart

  When NGINX Management Suite is installed using a Helm Chart, it now defaults to a ClusterIP without an external IP address.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Installing NGINX Agent on FreeBSD fails with “error 2051: not implemented” (41157)
• SELinux errors encountered when starting NGINX Management Suite on RHEL9 with the SELinux policy installed (41327)

Known Issues

You can find information about known issues in the Known Issues topic.

2.9.1

April 06, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.6.0 - 2.9.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• NGINX configurations with special characters may not be editable from the web interface after upgrading Instance Manager (41557)

Known Issues

You can find information about known issues in the Known Issues topic.

2.9.0

March 21, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.6.0 - 2.8.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• New webpages for viewing Attack Signature and Threat Campaigns

  The Instance Manager web interface now allows you to view Attack Signatures and Threat Campaign packages published to instances and instance groups. You can also publish these packages using the precompiled publication mode.

• NGINX Agent supports Rocky Linux 8 and 9

  The NGINX Agent now supports Rocky Linux 8 (x86_64, aarch64) and 9 (x86_64, aarch64). The NGINX Agent supports the same distributions as NGINX Plus. For a list of the supported distributions, refer to the NGINX Plus Technical Specs guide.

• New Events for CUD actions

  Events will be triggered for CREATE, UPDATE, and DELETE actions on Templates, Instances, Certificates, Instance Groups, and Licenses.

• The Certificate and Keys webpage has a new look!

  Our new and improved Certificates and Keys webpage makes it easier than ever to efficiently manage your TLS certificates.

• Add commit hash details to NGINX configurations for version control

  Use the Instance Manager REST API to add a commit hash to NGINX configurations if you use version control, such as Git.

  For more information, see the following topics:

  • Add Hash Versioning to Staged Configs
  • Publish Configs with Hash Versioning to Instances
  • Publish Configs with Hash Versioning to Instance Groups

Security Updates

Important:
For the protection of our customers, NGINX doesn’t disclose security issues until an investigation has occurred and a fix is available.

This release includes the following security updates:

• Instance Manager vulnerability CVE-2023-1550

  NGINX Agent inserts sensitive information into a log file (CVE-2023-1550). An authenticated attacker with local access to read NGINX Agent log files may gain access to private keys. This issue is exposed only when the non-default trace-level logging is enabled.

  NGINX Agent is included with NGINX Instance Manager, and used in conjunction with API Connectivity Manager and the Security Monitoring module.

  This issue has been classified as CWE-532: Insertion of Sensitive Information into Log File.

  Mitigation

  • Avoid configuring trace-level logging in the NGINX Agent configuration file. For more information, refer to the Configuring the NGINX Agent section of NGINX Management Suite documentation. If trace-level logging is required, ensure only trusted users have access to the log files.

  Fixed in

  • NGINX Agent 2.23.3
  • Instance Manager 2.9.0

  For more information, refer to the MyF5 article K000133135.

Changes in Default Behavior

This release has the following changes in default behavior:

• SSL Certificates can be associated with Instance Groups

  When assigning SSL certificates for the NGINX data plane, you have the option of associating them with a single instance or with an instance group. When associated with an instance group, the certificates will be shared across all instances in the group.

• Action required: OIDC configurations for the management plane must be updated after upgrading to Instance Manager 2.9.0

  OIDC configuration files were modified to improve support for automation and integration in CI/CD pipelines. To continue using OIDC after upgrading to Instance Manager 2.9.0, you’ll need to update these configuration files.

  To take advantage of the expanded functionality for OIDC authentication with NGINX Management Suite, we recommend following these two options:

  Option 1

  1. During the upgrade, type Y when prompted to respond Y or I: install the package mainatiner's version for each of the following files:

     • /etc/nms/nginx/oidc/openid_configuration.conf
     • /etc/nms/nginx/oidc/openid_connect.conf
     • /etc/nms/nginx/oidc/openid_connect.js

  2. After the upgrade finishes, make the following changes to the /etc/nms/nginx/oidc/openid_configuration.conf file using the /etc/nms/oidc/openid_connect.conf.dpkg-old that was created as a backup:

     • Uncomment the appropriate “Enable when using OIDC with” for your IDP (for example, keycloak, azure).
     • Update $oidc_authz_endpoint value with the corresponding values from openid_connect.conf.dpkg-old.
     • Update $oidc_token_endpoint value with the corresponding values from openid_connect.conf.dpkg-old.
     • Update $oidc_jwt_keyfile value with the corresponding values from openid_connect.conf.dpkg-old.
     • Update $oidc_client and oidc_client_secret with corresponding values from openid_connect.conf.dpkg-old.
     • Review and restore any other customizations from openid_connect.conf.dpkg-old beyond those mentioned above.

  3. Save the file.

  4. Restart NGINX Management Suite:

     sudo systemctl restart nms
     

  5. Restart the NGINX web server:

     sudo systemctl restart nginx
     

  
  

  Option 2

  1. Before upgrading Instance Manager, edit the following files with your desired OIDC configuration settings:

     • /etc/nginx/conf.d/nms-http.conf
     • /etc/nms/nginx/oidc/openid_configuration.conf
     • /etc/nms/nginx/oidc/openid_connect.conf
     • /etc/nms/nginx/oidc/openid_connect.js

  2. During the upgrade, type N when prompted to respond N or O : keep your currently-installed version.

  3. After the upgrade finishes replace etc/nms/nginx/oidc/openid_connect.js with openid_connect.js.dpkg-dist.

  4. Restart NGINX Management Suite:

     sudo systemctl restart nms
     

  5. Restart the NGINX web server:

     sudo systemctl restart nginx
     

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• After upgrading to NGINX Instance Manager 2.1.0, the web interface reports timeouts when NGINX Agent configs are published (32349)
• Scan does not update an unmanaged instance to managed (37544)
• “Public Key Not Available” error when upgrading Instance Manager on a Debian-based system (39431)
• The Type text on the Instances overview page may be partially covered by the Hostname text (39760)
• App Protect: “Assign Policy and Signature Versions” webpage may not initially display newly added policies (40085)
• Upgrading NGINX Management Suite may remove the OIDC configuration for the platform (41328)

Known Issues

You can find information about known issues in the Known Issues topic.

2.8.0

January 30, 2023

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.5.0 - 2.7.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Enhanced details page for SSL Certificates

  The Instance Manager web interface now features an improved details page for SSL Certificates. This page provides important information about the certificate and any associated instances.

• Automatic retrieval of Attack Signatures and Threat Campaign updates to Instance Manager

  Instance Manager now allows you to set up automatic downloads of the most recent Attack Signature and Threat Campaign packages. By publishing these updates to your App Protect instances from Instance Manager, you can ensure your applications are shielded from all recognized attack types.

• Improved WAF Compiler error messages

  The messaging around security policy compilation errors has been improved by providing more detailed information and alerting users if the required compiler version is missing.

Changes in Default Behavior

This release has the following changes in default behavior:

• Switching between storing secrets on disk and using Vault migrates secrets

  When transitioning between storing secrets on disk or using HashiCorp Vault, any existing secrets can be easily migrated to the new storage method. For instructions, refer to the guide Configure Vault for Storing Secrets.

• Create roles using either an object name or UID

  You can now use either an object name or a unique identifier (UID) when assigning object-level permissions while creating or editing a role via the Instance Manager REST API.

• Upgrading from 2.7 or earlier, you must re-enable precompiled_publication to continue publishing security policies with Instance Manager

  To continue publishing security policies with Instance Manager if you are upgrading from Instance Manager 2.7 and earlier, you must set the precompiled_publication parameter to true in the nginx-agent.conf file.

  In Instance Manager 2.7 and earlier, the pre-compiled_publication setting was set to true by default. However, starting with Instance Manager 2.8, this setting is set to false by default. This means you will need to change this setting to true again when upgrading from earlier versions.

  To publish App Protect policies from Instance Manager, add the following to your nginx-agent.conf file:

      nginx_app_protect:
         precompiled_publication: true
  

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Web interface reports no license found when a license is present (30647)
• Associating instances with expired certificates causes internal error (34182)
• Publishing to an Instance/instance-group will fail when the configuration references a JSON policy or a JSON log profile (38357)
• Missing dimension data for Advanced Metrics with modules (38634)
• Large payloads can result in disk I/O error for database operations (38827)
• The Policy API endpoint only allows NGINX App Protect policy upsert with content length upto 3.14MB. (38839)
• Deploy NGINX App Protect policy is listed as “Not Deployed” on the Policy Version detail page (38876)
• NGINX Management Suite services may lose connection to ClickHouse in a Kubernetes deployment (39285)
• NGINX App Protect status may not be displayed after publishing a configuration with a security policy and certificate reference (39382)
• Security Policy Snippet selector adds incorrect path reference for policy directive (39492)
• The API Connectivity Manager module won’t load if the Security Monitoring module is enabled (39943)
• The API Connectivity Manager module won’t load if the Security Monitoring module is enabled (44433)

Known Issues

You can find information about known issues in the Known Issues topic.

2.7.0

December 20, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.4.0 - 2.6.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Changes in Default Behavior

This release has the following changes in default behavior:

• NGINX App Protect upgrades are supported

  You can upgrade NGINX App Protect WAF on managed instances where Instance Manager publishes NGINX App Protect policies and configurations. For example, upgrade from App Protect release 3.12.2 to release 4.0.

• NGINX Management Suite Config file is now in YAML format

  With the release of NGINX Instance Manager 2.7, the NGINX Management Suite configuration file is now in YAML format. Through the upgrade process, your existing configuration will automatically be updated. Any settings you have customized will be maintained in the new format. If you have existing automation tooling for the deployment of the NGINX Management Suite that makes changes to the configuration file, you will need to update it to account for the change.

• Existing NGINX Agent configuration kept during upgrade to the latest version

  When upgrading NGINX Agent, the existing NGINX Agent configuration is maintained during the upgrade. If the Agent configuration is not present in /etc/nginx-agent/nginx-agent.conf, a default configuration is provided after NGINX Agent installation.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Instance Manager reports old NGINX version after upgrade (31225)
• Instance Manager returns a “Download failed” error when editing an NGINX config for instances compiled and installed from source (35851)
• Null data count is not correctly represented in the NGINX Plus usage graph. (38206)
• When upgrading Instance Manager from v2.4 to later versions of Instance Manager, certificate associations are no longer visible. (38641)
• NGINX App Protect policy deployment status not reflecting removal of associated instance. (38700)
• When upgrading a multi-node NMS deployment with helm charts the ingestion pod may report a “Mismatched migration version” error (38880)
• After a version upgrade of NGINX Instance Manager, NMS Data Plane Manager crashes if you publish NGINX configuration with App Protect enablement directive (app_protect_enable) set to ON (38904)

Known Issues

You can find information about known issues in the Known Issues topic.

2.6.0

November 17, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.3.0 - 2.5.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Manage and deploy configurations to NGINX App Protect WAF Instances

  This release introduces the following features to manage and deploy configurations to NGINX App Protect instances:

  • Create, upsert, and delete NGINX App Protect WAF security policies
  • Manage NGINX App Protect WAF security configurations by using the NGINX Management Suite user interface or REST API
  • Update Signatures and Threat Campaign packages
  • Compile security configurations into a binary bundle that can be consumed by NGINX App Protect WAF instances

• Adds support for RHEL 9

  Instance Manager 2.6 supports RHEL 9. See the Technical Specifications Guide for details.

• Support for using HashiCorp Vault for storing secrets

  NGINX Management Suite now supports the use of Hashicorp Vault to store secrets such as SSL Certificates and Keys. Use of a new or existing Vault deployment is supported.

• Graph and additional data are included in NGINX Plus usage tracking interface

  On the NGINX Plus usage tracking page, the number of NGINX Plus instances used over time is available in a graph. You can also view the minimum, maximum, and average count of concurrent unique instances in a given time period.

• Adds support for Oracle 8

  Oracle 8 is now a supported distribution starting with Instance Manager 2.6. You can use the RedHat/CentOS distro to install the Oracle 8 package.

Changes in Default Behavior

This release has the following changes in default behavior:

• GET Roles API responses now include user and group associations

  GET /roles and GET/roles/{roleName} API responses include any user(s) or group(s) associated with a role now.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Password error “option unknown” occurs when installing NGINX Instance Manager on Ubuntu with OpenSSL v1.1.0 (33055)
• Instance Manager reports the NGINX App Protect WAF build number as the version (37510)

Known Issues

You can find information about known issues in the Known Issues topic.

2.5.1

October 11, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.2.0 - 2.5.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Extended NGINX metrics aren’t reported for NGINX Plus R26 and earlier (37738)

Known Issues

You can find information about known issues in the Known Issues topic.

2.5.0

October 04, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.2.0 - 2.4.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Track NGINX Plus usage over time

  When viewing your NGINX Plus instances in the Instnace Manager web interface, you can set a date and time filter to review the NGINX Plus instance count for a specific period. Also, you can use the Instance Manager REST API to view the lowest, highest, and average number of NGINX Plus instances over time.

• New helm charts for each release of Instance Manager

  Each release of Instance Manager now includes a helm chart, which you can use to easily install Instance Manager on Kubernetes. You can download the helm charts from MyF5.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• OIDC is not supported for helm chart deployments (33248)
• Managed certificates may be overwritten if they have the same name on different datapath certificates (36240)
• Scan overview page doesn’t scroll to show the full list of instances (36514)

Known Issues

You can find information about known issues in the Known Issues topic.

2.4.0

August 16, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.1.0 - 2.3.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Get notified about critical events

  Instance Manager 2.4 adds a notifications panel to the web interface. After logging in to NGINX Management Suite, select the notification bell at the top of the page to view critical system events (WARNING or ERROR level events). Future releases will support additional notification options.

• See which of your NGINX Plus instances have NGINX App Protect installed

  Now, when you view your NGINX Plus inventory, you can see which instances have NGINX App Protect installed. NGINX App Protect is a modern app‑security solution that works seamlessly in DevOps environments as a robust WAF or app‑level DoS defense, helping you deliver secure apps from code to customer

Changes in Default Behavior

This release has the following changes in default behavior:

• You no longer need to associate a certificate with an instance using the web interface

  NGINX Management Suite will automatically deploy a certificate to an NGINX instance if the instance’s config references the certificate on the NMS platform.

• Adds nms-integrations service

  This release adds a new service called nms-integerations. This service is for future integrations; no user management or configuration is needed at this time.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Unable to publish config changes to a custom nginx.conf location (35276)

Known Issues

You can find information about known issues in the Known Issues topic.

2.3.1

July 21, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.0.0 - 2.3.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Security Updates

Important:
For the protection of our customers, NGINX doesn’t disclose security issues until an investigation has occurred and a fix is available.

This release includes the following security updates:

• Instance Manager vulnerability CVE-2022-35241

  In versions of 2.x before 2.3.1 and all versions of 1.x, when Instance Manager is in use, undisclosed requests can cause an increase in disk resource utilization.

  This issue has been classified as CWE-400: Uncontrolled Resource Consumption.

  For more information, refer to the AskF5 article K37080719.

Known Issues

You can find information about known issues in the Known Issues topic.

2.3.0

June 30, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.0.0 - 2.2.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Instance Manager provides information about your NGINX App Protect WAF installations

  You can configure NGINX Agent to report the following NGINX App Protect WAF installation information to NGINX Management Suite:

  • The current version of NGINX App Protect WAF
  • The current status of NGINX App Protect WAF (active or inactive)
  • The Attack Signatures package version
  • The Threat Campaigns package version

• View a summary of your instances' most important metrics for the last 24 hours

  This release adds a Metrics Summary page, from which you can view key system, network, HTTP request, and connection metrics at a glance for the last 24 hours. After logging in to Instance Manager, select an instance on the Instances Overview page, then select the Metrics Summary tab.

• Track the details for your NGINX Plus instances

  Easily track your NGINX Plus instances from the new NGINX Plus inventory list page. View the current count for all your NGINX Plus instances, as well as each instance’s hostname, UID, version, and the last time each instance was reported to Instance Manager. Select the Export button to export the list of NGINX Plus instances to a .csv file.

• Explore events in NGINX Instance Manager with the Events Catalogs API

  This release introduces a Catalogs API endpoint specifically for viewing NGINX Instance Manager events and corresponding information. You can access the endpoint at /analytics/catalogs/events.

• Support for provisioning users and user groups with SCIM

  Now, you can use SCIM to provision, update, or deprovision users and user groups for your Identity Provider to NGINX Instance Manager. SCIM, short for “System for Cross-domain Identity Management,” is an open API for managing identities.

• Adds support for Ubuntu 22.04

  The NGINX Management Suite, which includes NGINX Instance Manager, now supports Ubuntu 22.04 (Jammy).

  Refer to the Technical Specifications Guide for details.

Changes in Default Behavior

This release has the following changes in default behavior:

• New login screen

  Sometimes it’s the small things that count. Now, when logging in to NGINX Instance Manager, you’re treated to an attractive-looking login screen instead of a bland system prompt. 🤩

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Post-install steps to load SELinux policy are in the wrong order (34276)

Known Issues

You can find information about known issues in the Known Issues topic.

2.2.0

May 25, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.0.0 - 2.1.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• New events for NGINX processes and configuration rollbacks

  Now, you can use the NGINX Instance Manager Events API or web interface to view events when NGINX instances start and reload or when a configuration is rolled back.

• Filter events and metrics with custom date and time ranges

  Now you can filter events and metrics using a custom date and time range. Select Custom time range in the filter list, then specify the date and time range you want to use.

• Role-based access control added to Events and Metrics pages

  A warning message is shown when users try to view the Events and Metrics pages in the web interface if they don’t have permission to access the Analytics feature. For instructions on assigning access to features using role-based access control (RBAC), see Set Up RBAC.

• Modules field added to Metrics and Dimensions catalogs

  A modules field was added to the Metics and Dimensions catalogs. This field indicates which module or modules the metric or dimension belongs to.

• Adds reporting for NGINX worker metrics (API only)

  The NGINX Agent now gathers metrics for NGINX workers. You can access these metrics using the NGINX Instance Manager Metrics API.

  The following worker metrics are reported:

  • The count of NGINX workers
  • CPU, IO, and memory usage

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Running Agent install script with sh returns “not found” error (33385)

Known Issues

You can find information about known issues in the Known Issues topic.

2.1.0

April 05, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.0.0 - 2.0.1

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

What’s New

This release includes the following updates:

• Adds Docker support for NGINX Agent

  Now you can collect metrics about the Docker containers that the NGINX Agent is running in. The NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage.

  If you have multiple Docker containers on your data plane host, each container registers with Instance Manager as unique.

  Refer to the NGINX Agent Docker Support guide for details.

  Note:
  Containerizing the NGINX Agent is supported only with Docker at the moment. Look for additional container support in future releases of Instance Manager.

• Redesigned metrics views in the web interface

  The metrics pages in the web interface have been revised and improved.

  See the View Metrics topic to get started.

• New RBAC lets you limit access to NGINX Instance Manager features

  RBAC has been updated and improved. Add users to roles – or add users to user groups if you’re using an external identity provider – to limit access to Instance Manager features.

  For more information, see the tutorial Set Up RBAC.

• Improved certificate handling

  Stability and performance improvements for managing certificates using the web interface.

• View events for your NGINX instances

  Now you can use the Instance Manager API or web interface to view events for your NGINX instances.

  See the View Events and View Events (API) topics for instructions.

• Deploy NGINX Instance Manager on Kubernetes using a helm chart

  We recommend using the Instance Manager helm chart to install Instance Manager on Kubernetes.

  Among the benefits of deploying from a helm chart, the chart includes the required services, which you can scale independently as needed; upgrades can be done with a single helm command; and there’s no requirement for root privileges.

  For instructions, see Install from a Helm Chart.

Changes in Default Behavior

This release has the following changes in default behavior:

• Tags are no longer enforced for RBAC or set when creating or updating a role

  If you’re using tags for RBAC on an earlier version of Instance Manager, you’ll need to re-create your roles after upgrading. Tags assigned to instances for the purpose of RBAC won’t be honored after you upgrade.

• The DeploymentDetails API now requires values for failure and success

  The DeploymentDetails API spec has changed. Now, the failure and success fields are required. The values can be an empty array or an array of UUIDs of NGINX instances.

  Endpoint: /systems/instances/deployments/{deploymentUid}

  Example JSON Response

          {
            "createTime": "2022-04-18T23:09:16Z",
            "details": {
              "failure": [ ],
              "success": [
                {
                  "name": "27de7cb8-f7d6-3639-b2a5-b7f48883aee1"
                }
              ]
            },
            "id": "07c6101e-27c9-4dbb-b934-b5ed75e389e0",
            "status": "finalized",
            "updateTime": "2022-04-18T23:09:16Z"
          }
  

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Unable to register multiple NGINX Agents in containers on the same host (30780)
• Include cycles in the configuration cause analyzer to spin. (31025)
• System reports “error granting scope: forbidden” if user granting permissions belongs to more than one role (31215)
• When using Instance Groups, tag-based access controls are not enforced (31267)
• Bad Gateway (502) errors with Red Hat 7 (31277)

Known Issues

You can find information about known issues in the Known Issues topic.

2.0.1

January 27, 2022

Upgrade Paths

Instance Manager supports upgrades from these previous versions:

• 2.0.0

If your Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version.

Resolved Issues

This release fixes the following issues. Select an issue’s ID link to view its details.

• Unable to access the NGINX Instance Manager web interface after loading SELinux policy (31583)
• The nms-dpm service restarts when registering multiple NGINX Agents with the same identity (31612)

Known Issues

You can find information about known issues in the Known Issues topic.

2.0.0

December 21, 2021

What’s New

This release includes the following updates:

• (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.

• More metrics and instance dashboards

  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 Instance Manager. See the Catalog Reference documentation for a complete list of metrics.

• New architecture!

  We redesigned and improved the architecture of Instance Manager!

• Improved user access control

  Instance Manager 2.x. 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 Set up Authentication guide for more details.

Known Issues

You can find information about known issues in the Known Issues topic.