Migrate from NGINX Instance Manager v1

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


This documentation applies to NGINX Instance Manager 2.0.0 and later.


Prerequisites

To complete this tutorial, you need the following:

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

    Note:

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

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

Migrate NGINX Instance Manager

Begin the migration process by installing NGINX Instance Manager v2.

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

  2. For systemd systems, take the following steps to start or reload NGINX Instance Manager:

    1. Start the ClickHouse database server:

      sudo systemctl start clickhouse-server
      
    2. Start the NGINX web server:

      sudo systemctl start nginx
      

      —Or—

      If NGINX is already running, reload it:

      sudo service nginx reload
      
    3. Enable the following NGINX Instance Manager services:

      sudo systemctl enable nms-core
      sudo systemctl enable nms-dpm
      sudo systemctl enable nms-ingestion
      sudo systemctl enable nms
      
    4. Start the NGINX Instance Manager service:

      sudo systemctl start nms
      

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

    5. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible following the steps in the Configure Authentication guide.

    Note:
    After you’ve started NGINX Instance Manager, you can access the web interface by going to https://<NGINX-INSTANCE-MANAGER-FQDN>/ui/, where NGINX-INSTANCE-MANAGER-FQDN is the address of the host where you installed NGINX Instance Manager.
  3. (Optional) After the installation finishes, you need to migrate any customized configurations.

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

NIM v1 property NIM v2 equivalent Configuration file
audit_log access_log /etc/nms/nms.conf
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
license DEPRECATED N/A
log.level log_level /etc/nms/nms.conf
log.path DEPRECATED N/A
metrics.storage-path DEPRECATED N/A
rbac 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
Important:

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 NGINX 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 NGINX 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 NGINX Instance Manager v2. The managed NGINX instance no longer appears as Connected in the NGINX Instance Manager v1 “Inventory” view.

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

To uninstall NGINX Instance Manager v1, take the following steps:

  1. Stop the NGINX Instance Manager v1 service:

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

    sudo yum remove nginx-manager 
    

    sudo apt-get remove nginx-manager