Migration Guide

Follow the instructions in this guide to migrate from Instance Manager v1 to v2.

See Also:
To perform a clean installation of NGINX Management Suite and Instance Manager, refer to the NGINX Management Suite installation guide.


To complete this tutorial, you need the following:

  • A host with Instance Manager v1 installed that’s managing NGINX instances.


    You’ll need to install Instance Manager v2 on this same host in coexistence with Instance Manager v1. This allows you to migrate the managed NGINX instances to the newer version Verify that the host meets the technical requirements for Instance Manager v2.

    The package name for Instance Manager changed from nginx-manager to nms-instance-manager. You can run these packages in parallel.

Migrate Instance Manager

Begin the migration process by installing Instance Manager v2.

  1. Follow the instructions for Installing Instance Manager. License Instance Manager according to the installation guide.

  2. Enable the NGINX Management Suite services:

    sudo systemctl enable nms
    sudo systemctl enable nms-core
    sudo systemctl enable nms-dpm
    sudo systemctl enable nms-ingestion
    sudo systemctl enable nms-integrations
  3. Start the NGINX Management Suite services:

    sudo systemctl start nms
    sudo systemctl start nms-core
    sudo systemctl start nms-dpm
    sudo systemctl start nms-ingestion
    sudo systemctl start nms-integrations

    NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.

  4. To verify the NGINX Management Suite services are running, run the following command:

    ps aufx | grep nms
  5. (Optional) After the installation finishes, you need to migrate any customized configurations.

    Refer to the following table for mapping Instance Manager v1 properties to their v2 equivalents. For Instance Manager v2, the properties are split between Instance Manager’s configuration file (nms.conf) and the NGINX proxy instance’s configuration (nms-http.conf).

Instance Manager v1 property Instance Manager v2 equivalent Configuration file
beacon.address DEPRECATED N/A
beacon.batch_size DEPRECATED N/A
beacon.flush_interval DEPRECATED N/A
beacon.token DEPRECATED N/A
bind_address server.listen /etc/nginx/conf.d/nms-http.conf
cert server.ssl_certificate /etc/nginx/conf.d/nms-http.conf
gateway_port server.listen /etc/nginx/conf.d/nms-http.conf
grpc_port dpm.grpc_addr /etc/nms/nms.conf
influxdb.address DEPRECATED N/A
influxdb.batch_size DEPRECATED N/A
influxdb.bucket DEPRECATED N/A
influxdb.flush_interval DEPRECATED N/A
influxdb.gzip DEPRECATED N/A
influxdb.org DEPRECATED N/A
influxdb.tls.ca DEPRECATED N/A
influxdb.tls.cert DEPRECATED N/A
influxdb.tls.enable DEPRECATED N/A
influxdb.tls.key DEPRECATED N/A
influxdb.token DEPRECATED N/A
installer.dir DEPRECATED N/A
installer.filename DEPRECATED N/A
installer.port DEPRECATED N/A
installer.username DEPRECATED N/A
key server.ssl_certificate_key /etc/nginx/conf.d/nms-http.conf
log.level log.level /etc/nms/nms.conf
metrics.storage-path DEPRECATED N/A
scanner.host_discovery DEPRECATED N/A
scanner.icmp_timeout DEPRECATED N/A
scanner.tcp_timeout DEPRECATED N/A
server_name server.server_name /etc/nginx/conf.d/nms-http.conf
skip_validation DEPRECATED N/A

The default dpm_grpc_addr value uses Unix domain sockets. We advise against replacing the default value.

Also, the license must be passed using the Instance Manager REST API or web interface and is no longer configurable.

After you’ve updated the configuration, you can migrate the managed NGINX instances. To do this, upgrade the NGINX Agents from v1 to v2. See the instructions in the following section for how to migrate the NGINX Agents.

Upgrade the NGINX Agent

To upgrade the NGINX Agent from v1 to v2, take the following steps:

  1. Follow the instructions to Install NGINX Agent v2.

  2. After the installation finishes, restart the NGINX Agent:

    sudo systemctl restart nginx-agent
  3. Continue to the next section to migrate the managed NGINX instances to Instance Manager v2.

Transfer Managed NGINX Instances

After each NGINX Agent has been upgraded to v2, the managed instance should appear in the “Inventory” view for Instance Manager v2. The managed NGINX instance no longer appears as Connected in the Instance Manager v1 “Inventory” view.

After you finish migrating all of the managed NGINX instances, you can uninstall the Instance Manager v1.

To uninstall Instance Manager v1, take the following steps:

  1. Stop the Instance Manager v1 service:

    sudo systemctl stop nginx-manager
  2. Uninstall Instance Manager v1:

    sudo yum remove nginx-manager 

    sudo apt-get remove nginx-manager