Instructions for upgrading a production environment v. 5 or 4 to NoMachine v. 6

Due to differences between version 6 and previous versions 5, the automatic updates via GUI from the NoMachine repositories have been disabled. Automatic updates are available only for NoMachine free and NoMachine Enterprise Client.

To upgrade from v. 4 (or v. 3.5.0) to v. 6 it's necessary to have previously upgraded to v.5.

To upgrade from v. 5 to v. 6, it is necessary to use the appropriate package downloaded from the Customer Area or provided by our Sales or Support Team. In some cases it's also necessary to replace license v. 5 with a v. 6 license.

1.1. Compatibility with previous software versions

To connect to NoMachine Cloud Server v. 6 it's necessary to use a NoMachine client v. 6.

The other NoMachine servers of version 6 accept connections from clients v. 5 and 4, but it's recommended to upgrade your client installations to benefit from all the new features sported by v. 6.

V. 6 clients can connect to NoMachine servers v. 5 or 4. (*)

Compatibility between client/server versions 5 or 4 and v. 6 is preserved. (*)

NoMachine v. 6 is not compatible with the legacy version NX 3.5.0. (*)

(*) The 'NoMachine login' authentication method in version 6 is no longer available.

1.2. Customer Packages for Upgrade

To upgrade NoMachine installations, customers should use packages downloaded from their Customer Area at: https://www.nomachine.com/support#login or provided by the Sales Team.

There is no longer any distinction between packages 'for production' and 'for update' starting with v. 6. The same package can be used now for:

I	upgrading an existing installation or
II	making a new installation.

To be compliant with MPEGLA royalty fees, downloads are limited to two for each license. The counter is reset every new release.

Please read carefully all the steps below before proceeding with the upgrade and do not hesitate to contact our Sales or Support Teams for any advice.

1.3. What are the NoMachine v.6 Products

The most prominent features introduced with NoMachine v. 6 are:

Extended Web support
Support for web sessions is extended to all server types (except NoMachine free).

Centralized access to servers in a hierarchical federation
Starting from v. 6, Cloud Server assumes a different role with the purpose of federating multiple NoMachine servers or foreign servers (Unix-like hosts running unsupported OS) and providing a single point of access to these hosts.

The new Cloud Server is not intended to be used for creating user sessions on its host but to work as a 'gateway'.

This is the list of NoMachine products v. 6 and their primary function:

Product	Acronym	Platform	Role
Cloud Server	CS	Linux, Windows, Mac	Single point of access to NoMachine multi-server subsystems and foreign hosts. Can be federated under a CS.	N/A (*)
Enterprise Desktop	ED	Linux, Windows, Mac	Access the physical desktop on this host. Can be federated under a CS.	Unlimited connections to physical desktop
Enterprise Terminal Server	ETS	Linux	Single point of access to NoMachine Terminal Server Node hosts and load-balancing of virtual desktops on these hosts. Can be federated under a CS.	()(*)
Terminal Server Node	TSN	Linux	Run virtual desktops on this host.	Unlimited connections to virtual desktops () (*)
Terminal Server	TS	Linux	Access to virtual desktops on this host. Can be federated under a CS.	Unlimited connections to virtual desktops (*)
Small Business Server (only on demand)	SBS	Linux	Access to virtual desktops on this host	Up to ten connections to virtual desktops (*)
Workstation	WS	Linux	Access to virtual desktops on this host. Can be federated under a CS.	Up to four connections to virtual desktops (*)

(*) Connections to physical desktop of this host are permitted to system administrators, NoMachine administrators and 'trusted' users and are mainly intended for administrative or remote assistance purposes.
(**) The Terminal Server Node doesn't accept direct connections to its host and must be used in conjunction with Enterprise Terminal Server. Enterprise Terminal Server does not accept connection requests to other NoMachine servers, only Terminal Server Nodes.

1.4. How Server Products v.6 are Mapped to Previous Versions

This table shows how server types and functionalities present in v. 5 are mapped to v. 6.

Customers are invited to check before downloading and installing that the package available in the customer area corresponds to their scenario. In some specific cases it will be necessary to contact the Sales Team to get the appropriate package v.6 and license.

Current installation with license v. 5	Platform	Upgrade to	Action
CS used with ED	Linux	CS	Download package from your Customer Area. Upgrading the license is not necessary
CS used with virtual desktops on its host or with Linux terminal server nodes	Linux	ETS	CONTACT THE SALES TEAM to receive the ETS package and the new license for this product
CS	Windows Mac	CS	Download the package from your Customer Area. Upgrading the license is not necessary
ES used with ED	Linux	CS	CONTACT THE SALES TEAM to receive the CS package and the new license for this product
ES used with virtual desktops on its host or with Linux terminal server nodes	Linux	ETS	Download the package from your Customer Area. Upgrading the license is not necessary
ES	Windows Mac	CS	Download the package from your Customer Area. Upgrading the license is not necessary
WS or TS used as standalone servers	Linux	WS or TS	Download WS or TS package from your Customer Area. Upgrading the license is not necessary
WS or TS used as nodes of CS or ES	Linux	TSN	CONTACT THE SALES TEAM to receive the TSN package and the new license for this product
SBS	Linux	SBS	Download SBS package from your Customer Area Upgrading the license is not necessary
ED	Linux Windows Mac	ED	Download ED package from your Customer Area. Upgrading the license is not necessary
EC (Enterprise Client)	Linux Windows Mac	EC	Download EC package from your Customer Area or use the automatic updates

2. What to Consider Before Upgrading

2.1. Planning Server Downtime Period Before Upgrading

Upgrading the installed software requires the termination of all running sessions. In case of virtual desktops and custom sessions (available on Linux only), these sessions cannot be recovered later.

This is necessary for installing the new libraries and binaries. Processes already loaded in the system memory lock down the corresponding binaries, libraries that cannot be otherwise replaced.

The upgrade procedure implies a shutdown of the server and all services. They are automatically restarted once the upgrade procedure is completed.

All operations must be executed with administrative privileges: root or 'sudo' user on Linux and Mac, and as administrator on Windows.

As a precaution, we suggest to do the following before proceeding with the upgrade:

I	Send a broadcast message to all connected users to inform them about ongoing operations.
II	If there are two servers in failover cluster mode: shutdown NoMachine server on the primary server and on the secondary server.

Note that in case of a multi-node environment, stopping the remote nodes before proceeding with the upgrade is not required.

2.2. Preserving Configurations and DBs

Large environments often adopt specific configurations that are different from the default ones. The upgrade procedure automatically preserves the original configuration: it creates a backup of the original configuration files (server.cfg.backup and node.cfg.backup in 'etc' under the NoMachine installation directory) and carries their settings over to the new configuration files.

In general the upgrade procedure takes care of the following operations when necessary:
- Removing obsolete keys no longer used in the new version.
- Adding new configuration keys.
- Renaming existing configuration keys to fit new specifications.

In the case of upgrade from Cloud Server installations to v. 6, it's important to notice that the cloud.cfg and cloud.inc files will be no longer used. A backup of these files will be created and their settings moved respectively into server.cfg and htd.cfg.

All these DBs, in the 'etc' directory under the NoMachine installation directory are automatically preserved during the upgrade procedure:

administrators.db
groups.db
guests.db
hosts.db
nodes.db
passwords.db
profiles.db
users.db

This means, for example, that the upgrade will preserve all profile rules set and all nodes of the multinode environment, if any.

3. Upgrade Instructions

The following procedures apply to NoMachine installations v. 5.

Administrative rights are required for upgrading server-side installations.

3.1. How to Upgrade a Standalone Server on Linux

Instructions for Linux are based on the command line, but it's also possible to execute them using the system's graphical package manager, as explained for Mac and Windows.

Step 1- Send a broadcast message to all connected users to inform about ongoing operations:

sudo /etc/NX/nxserver --broadcast "Your message here"

Step 2- Shutdown NoMachine server:

sudo /etc/NX/nxserver --shutdown

Step 3- Upgrade the installation using the appropriate NoMachine package downloaded from your Customer Area. Instructions from command line are

for DEB:

sudo dpkg -i packageName.deb

for RPM:

sudo rpm -Uvh packageName.rpm

Step 4- Verify your installation:

/etc/NX/nxserver --version

sudo /etc/NX/nxserver --status

sudo /etc/NX/nxserver --subscription

3.2. How to Upgrade a Standalone Server on Mac or Windows

Step 1- Send a broadcast message to all connected users to inform them about the maintenance operations.

On the NoMachine server host, click on the !M icon in the system tray and then on 'Show the server status'. Open the 'Connected users' panel and right click on users to 'Send message'.

As an alternative, use the command line and send the same message to all running sessions

on Mac:

sudo /etc/NX/nxserver --broadcast "Your message here"

on Windows change directory to the NoMachine bin folder and execute:

nxserver --broadcast "Your message here"

Step 2- Shutdown the NoMachine server.

On the NoMachine server host, click on the !M icon in the system tray and then on 'Show the server status'. Click on the 'Shutdown the server' button.

As an alternative, from command line

on Mac execute:

sudo /etc/NX/nxserver --shutdown

and on Windows, in the NoMachine bin directory execute:

nxserver --shutdown

Step 3- Upgrade the installation using the proper NoMachine package downloaded from your Customer Area:
double-click on the icon of the executable file and follow the wizard to proceed with the installation.

Step 4- Verify your installation:

On the NoMachine server host, click on the !M icon in the system tray and then on 'Show the server status'. In the server GUI access the Server preferences -> Updates panel. You can verify the version and license of your current installation.

As an alternative, from command line

on Mac execute:

/etc/NX/nxserver --version

sudo /etc/NX/nxserver --status

sudo /etc/NX/nxserver --subscription

on Windows execute in the NoMachine bin directory:

nxserver --version

nxserver --status

nxserver --subscription

3.3. How to Upgrade a Multi-Node Environment for Virtual Desktops

Considerations

I	The package type to be used for upgrading the main server (CS or ES v. 5) is: Enterprise Terminal Server, ETS. If the server was a CS, contact the Sales Team if you don't have yet an ETS license (server.lic and node.lic) and get it before proceeding.
II	The package type to be used for upgrading the remote nodes is: Terminal Server Node , TSN. Contact the Sales Team if you don't have yet a TSN license.

Step 1- Send a broadcast message to all connected users to inform them about the maintenance operations. (nxserver --broadcast "Your message here")

Step 2- Shutdown the main server. (nxserver --shutdown)
If you have two servers in failover cluster, shutdown also the secondary server.

Step 3- Upgrade each remote node.
Download the TSN package from your Customer Area and upgrade each node installation.

If there's not already a TSN license:
- replace the node.lic file.
- rename or remove the server.lic file (TSN requires only one license file, node.lic).

Step 4- Finally upgrade the main server installation.
Download the ETS package from your Customer Area and upgrade the server installation.

If the license v. 5 is for CS, replace the server.lic and node.lic files with ETS license files.

Step 5- If you have two servers in failover cluster, proceed to upgrade the second server and replace the licenses if necessary.
Then restart both cluster servers to make sure that the cluster interface is created on the primary server. (nxserver --restart)

Step 6- Check your installation by verifying on the main server host:
- version (nxserver --version)
- status (nxserver --status)
- license (nxserver --subscription)
- nodes' availability (nxserver --nodelist)

On each of the remote node, verify:
- version (nxnode --version)
- license (nxnode --subscription)

If you have two servers in a cluster failover, verify on the second server:
- version (nxserver --version)
- license (nxserver --subscription)

3.4. How to Upgrade a Multi-Node Environment for Connections to Physical Desktop

Considerations

I	The package type to be used for upgrading the main server (CS or ES v. 5) is: Cloud Server, CS. If the server is ES, contact the Sales Team if you don't have yet a CS license v. 6 (server.lic and node.lic) and get it before proceeding.
II	CS v. 6 is not intended for running sessions on its host, it works as a gateway to its child servers.
III	Due to structural differences between the multi-host environment v. 5 and v. 6, it will be necessary to re-add all the remote host to the main server.
IV	The package type to be used for upgrading the remote nodes is the same of the previous installation v. 5.

Step 1- Send a broadcast message to all connected users to inform them about the maintenance operations. (nxserver --broadcast "Your message here")

Step 2- Shutdown the main server. (nxserver --shutdown)
If you have two servers in failover cluster, shutdown also the secondary server.

Step 3- Upgrade each remote node.
Download the proper package from your Customer Area and upgrade each node installation.

Replacing the license files (server.lic and node.lic) is not necessary.

Step 4- Upgrade the main server installation.
Download the CS package from your Customer Area and upgrade the server installation.

If the license v. 5 is for ES, replace the server.lic and node.lic files with CS license files.

On each of the remote node, verify:
- version (nxnode --version)
- license (nxnode --subscription)

If you have two servers in a cluster failover, verify on the second server:
- version (nxserver --version)
- license (nxserver --subscription)

Step 7- Add each of the remote hosts as child server to the CS server. (nxserver --serveradd HOST)

Step 8- Verify that all child servers have been added. (nxserver --serverlist)

4. Appendix - Specific Cases and the Right Products for Upgrading

This section deals with specific cases which require that you contact the Sales Team. Customers will receive the proper package suitable for their environment and the new license v. 6 necessary for the software.

CS v.5 on Linux + Linux multi-node environment
Cloud Server version 5 is set-up in a multi-node environment with WS or TS or TSN on the remote nodes. To preserve the same load-balancing functionalities of v. 5:

I	Upgrade the remote node(s) with the TSN package. Then replace the license v. 5 if the node was WS or TS: (i) rename or remove the old server.lic and (ii)replace node.lic with the new node.lic file for TSN.
II	Upgrade CS to ETS and replace license v. 5 with ETS license v. 6

CS v.5 on Linux/Windows/Mac + ED v.5 as remote nodes
Cloud Server version 5 is set-up in a multi-node environment with ED on the remote nodes. Besides upgrading nodes and server host, it will be necessary to add the ED server(s) to CS v.6. That's because Cloud Server v. 6 implements the new concept of multi-tier server architecture and works as single point of access to server subsystems. The multi-node environment v. 5 will therefore become a multi-server environment v.6.

I	Upgrade the remote node(s) with ED v.6. Replacing licenses on the nodes is not necessary.
II	Upgrade CS v. 5 to CS v.6. Replacing the license is not necessary.
III	Add each ED host to CS by means of 'nxserver --serveradd HOST' command or via client v. 6 GUI.

ES v.5 on Linux + Linux multi-node environment
Enterprise Server version 5 is set-up in a multi-node environment with WS or TS or TSN on the remote nodes. To preserve the same load-balancing functionalities of v. 5:

I	Upgrade the remote node(s) with the TSN package. Then replace the license v. 5 if the node was WS or TS: (i) rename or remove the old server.lic and (ii)replace node.lic with the new node.lic file for TSN.
II	Upgrade ES to ETS. Replacing the ES license is not necessary since it's automatically mapped to ETS.

ES v.5 + ED v.5 as remote nodes
Enterprise Server v. 5 on Windows, Linux or Mac is set-up in a multi-node environment with ED as remote nodes. Besides upgrading nodes and server host, it will be necessary to add the ED server(s) to CS v.6. That's because Cloud Server v. 6 implements the new concept of multi-tier server architecture and works as single point of access to servers' subsystems. The multi-node environment v. 5 will therefore become a multi-server environment v.6.

I	Upgrade the remote node(s) with ED v.6. Replacing license on the nodes(s) is not necessary.
II	Upgrade ES to CS and replace ES license v. 5 with CS license v. 6 (server.lic and node.lic)
III	Add each ED host to CS by means of 'nxserver --serveradd HOST' command

For any other scenario not contemplated in this document, please contact the Sales Team or the Support Team.