Migrate on VMs (RPM/DEB)

Before you begin

Ensure you have the following:
- NGINX_LICENSE_JWT
- NGINX Agent command auth token (data plane key)
- Repository access and package manager permissions for your distribution
Back up configuration:
- /etc/nginx-agent
- Every configuration directory specified as a config_dirs value in /etc/nginx-agent/nginx-agent.conf
Plan a maintenance window and test this procedure in a non‑production environment first.

Do not run v2 and v3 concurrently

Do not run NGINX Agent v2 and v3 concurrently on the same host.

If you are using a version older than NGINX Agent v2.31.0, stop the agent before upgrading and start it again after the upgrade.
- sudo systemctl stop nginx-agent

Upgrade the package to v3.

CentOS, RHEL (RPM‑based):

shell

sudo yum -y makecache
sudo yum update -y nginx-agent

Debian, Ubuntu (DEB‑based):

shellsudo apt-get update
sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold"

If you are using a config file, ensure required values are present. If you used Config Sync Groups in v2, add the following label in v3:
- NGINX_AGENT_LABELS: config-sync-group=

Check service status and logs for a successful connection, for example: msg="Agent connected".
Verify the instance appears Online in the NGINX One Console.

Review the nginx-agent service status and logs for authentication or configuration errors.
- View logs by running: sudo journalctl -u nginx-agent -xe
Confirm that credentials (NGINX_LICENSE_JWT, data plane key) are valid.

Reinstall the previous v2 package and restore your configuration backup if required.