Welcome to the NoMachine Web Companion Installation Guide version 5 or later. This document is intended to be an overview on how the Web Companion can be installed, personalized and configured to be integrated into whatever Web site or Portal.

The Knowledge BaseThe Knowledge Base, https://www.nomachine.com/knowledge-base, makes available both technical documents especially for administrators and end-user oriented guides, as well as articles on specific topics and How-Tos.

Leave Feedback About This GuideOur goal is provide comprehensive and clear documentation for all the NoMachine products. If you would like to send us your comments and suggestions, you can use the Web contact tool available at https://www.nomachine.com/contact-request, by selecting the Web Quality Feedback as your option.

Please note that NoMachine Web Companion is a Java applet, i.e. a platform-independent application which runs in a web browser using a Java Virtual Machine (JVM). Although the applet can be downloaded by any computer and executed by any Java-compatible browser, the end-user machine must be running one of the NoMachine Enterprise Client supported platforms in order for the plugin to be installed and used correctly.

- Install and update a portable version of NoMachine Enterprise Client, named client plugin, on the end-user's machine. No administrator intervention is needed.

- Run a pre-configured connection to the server by means of a simple click on the Web interface. The client on the end-user's machine will be started by the applet and will connect automatically to the pre-configured desktop.

Note for Linux end-users: the client.zip archive for Linux provides a version for 32-bit suitable also for Linux 64-bit as long as the Operating System offers support for 32bit applications.

For example, in case of Ubuntu 11.10 X86_64, it is necessary to previously install the libc6-i386 and libstdc++6:i386 packages to be able to install NoMachine DEB packages for i386.

The Web Companion RPM and DEB packages installs in the /usr/NX/share/plugin directory. The TAR.GZ packages creates there the NX directory and installs to NX/ share/plugin.

To make it accessible via Web, you need to copy the plugin directory to the proper public directory, i.e. the document root of your web server.

If you have NoMachine Portal server already installed, you can deploy the Web Companion by using the NoMachine HTTP server, nxhtd. However nxhtd is configured to server by default the Web Player. You will need to adapt its configuration file for the Web Companion.

The client.zip archive is a LZMA compressed Jar archive of content of the NoMachine Entperise Client installation directory.

A client.zip archive is available for each of the Enterprise Client supported Operating Systems and should not be modified. Further to every release of the Enterprise Client, NoMachine makes available a new Web Companion package providing the latest available version of the client.

Once the applet has downloaded the proper client.zip archive on the end-user's machine, it extracts the archive to provide a fully operative installation of NoMachine Enterprise Client. We will refer to that installation as the plugin.

Note that since the plugin is a portable version, i.e. not installed on the system, some functionalities are not available because they would require drivers installed on the system. The unavailable functionalities are: connecting disks and printers from the remote server to the user's pc, USB forwarding and network ports forwarding. Supported functionalities are: audio, connecting disks and printers from the user's pc to the remote sessions.

NoMachine Web Companion first checks whether there is a plugin already available on the end-user's machine. If there is, the applet verifies if it is an up-to-date version. When the plugin is not installed, the Web Companion invites the user to download it. Once the end-user accepts, the applet downloads and extracts the client.zip archive in the the user's home/.nx/plugin/OS directory, where OS indicates the local Operating System, i.e. Linux, Windows and MacOSX.

The plugin directory on the end-user's machine contains the Enterprise Client executable and all libraries and binaries needed to have a fully operative client installation. It also contains a file named VERSION which reports the version of the client.

The VERSION file is needed by the applet to verify if the plugin is out-of-date. In this case, the Web Companion advises the user to update his/her plugin and allows the download of the most recent version of Enterprise Client.

Once the plugin is made available on the end-user's machine and the user tries to run any of the available connections deployed via the Web Companion, the correspondent session file (a .nxs file resident on the server side) is downloaded by the browser and opened with the application associated with it, i.e. the Enterprise Client. The Client initiates the procedure to establish communication with the NoMachine server. After the Client has started, the Web Companion is no longer involved in the process.

Communication between client and server happens through NX protocol (which uses by default port 4000) or SSH protocol (which uses by default port 22 or 4022 if server is on Windows).

Instructions mainly refer to the installation of NoMachine Web Companion on Linux . However, the installation instructions related to the compressed TAR package can be easily extended to apply to the Windows and Mac platforms.

Once the Web Companion has been installed, it has to be published to the correct directory of your web server, i.e. the document root. The document root is a directory from which the web server reads files in order to serve contents for a Web site. Depending on the web server, and its version and configuration, the document root may be found in different places. In order to verify where this directory is on your system, you need to refer to the web server configuration file.

The Web Companion will be installed in the /usr/NX/share/plugin directory. Make the Web Companion accessible via Web, by copying the plugin directory to the proper public directory of your web server:

# sudo cp -a /usr/NX/share/plugin DocRoot

Edit the DocRoot/plugin/nxapplet.html file to fit your environment.

Updating

# rpm -Uvh nomachine-plugin_<pkgVersion>_<arch>.rpm

This will update the /usr/NX/share/plugin default installation. To make the update effective, copy the usr/NX/share/plugin directory to the public directory of your web server. Ensure you have created a backup copy of your nxapplet.html file beforehand.

Uninstalling

# rpm -e nomachine-plugin

This will remove the Web Companion default installation in the /usr/NX/share/plugin directory, but not the plugin directory in the DocRoot of your web server.

The Web Companion will be installed in the /usr/NX/share/plugin directory.

Make the Web Companion accessible via Web, by copying the plugin directory to the proper public directory of your web server:

# sudo cp -a /usr/NX/share/plugin DocRoot

Edit the DocRoot/plugin/nxapplet.html file to fit your environment.

Updating

$ sudo dpkg -i nomachine-plugin _<pkgVersion>_<arch>.deb

This will update the /usr/NX/share/plugin default installation. To make the update effective, copy the usr/NX/share/plugin directory to the public directory of your web server. Ensure you have created a backup copy of your nxapplet.html file beforehand.

Uninstalling

$ sudo dpkg -r nomachine-plugin

This will remove the Web Companion default installation in the /usr/NX/share/plugin directory, but not the plugin directory in the DocRoot of your web server.

The Web Companion will be installed in the /usr/NX/share/plugin directory.

Make the Web Companion accessible via Web, by copying the plugin directory to the proper public directory of your web server:

# sudo cp -a /usr/NX/share/plugin DocRoot

Edit the DocRoot/plugin/nxapplet.html file to fit your environment.

Updating

$ cd /usr $ sudo tar xvzf nomachine-plugin_<pkgVersion>_<arch>.tar.gz

This will update the /usr/NX/share/plugin default installation. To make the update effective, copy the usr/NX/share/plugin directory to the public directory of your web server. Ensure you have created a backup copy of your nxapplet.html file beforehand.

Uninstalling

$ sudo rm -rf /usr/NX/share/plugin

This will remove the Web Companion default installation in the /usr/NX/share/plugin directory, but not the plugin directory in the DocRoot of your web server.

A session file, by default a file with the .nxs extension, needs to be created and be resident on the web server in a public directory accessible by the Web Companion. In its default configuration, the Web Companion looks for the session.nxs file in the DocRoot/plugin/session directory. Name of the file and path to the file can be modified by editing the DocRoot/plugin/nxapplet.html file and a proper value set for the following parameter:

<PARAM NAME="SessionUrl" VALUE="/plugin/session/session.nxs">

Even if the Client is able to identify any valid session file, the .nxs extension should still be specified to ensure that the session file downloaded by the Browser is correctly associated to the NoMachine Client application by the system.

Upon the user's request, the Browser downloads the session file which is run by the Client application on the user's machine.

The behaviour of NX Client is to prompt the user with a login dialog when username and/or password are not stored in the session file. In this case, access to the remote desktop is prevented until the user provides their credentials to be able to connect to the remote desktop.

When the server is on Linux and is configured to support the automatic generation of guest accounts, the session file can be created to instruct the Client to log in as a guest user on the server. In this case, the user doesn't need to provide their access credentials since the server will create a system account automatically.

The NoMachine GUI allows for the creation of a valid session file which is then saved in the directory specified in the 'Player environment' panel, field 'Connections'.

Once you have created that file, you can copy it to the web server public directory and make it accessible to the applet by updating the applet html file accordingly.

To create a session file which won't ask for access credentials to log in to NoMachine, connect to that server and when you are prompted for credentials, remember to check 'Save this password in the configuration file'.

To generate a session file to run connections as a guest on the server, connect to that server and when you are prompted for credentials, check 'Login as a guest user'.

This applies mainly for connections to virtual desktops on Linux. You need to make one session file available for each user in order to provide every user with their own individual virtual desktop. When guest users are connecting, however, a single session file on the web server is enough to ensure that all users can have their own virtual desktop.

If you are not deploying guest user sessions, or if you need to make available a different session file for each of your users on the web server, you will have to identify each session file with a unique name. To ensure uniqueness and security of the session files, it is advisable to name those files by using the MD5 utility, although any system implementing a one-way hashing algorithm can be used to avoid collision in the namespace of session files. The Web Companion can also be used to make more than one session type available as well as for numerous users.

In order to deploy multiple session files, you need to implement a simple Web application written for example in php or any other language for the Web such as ASP, JavaScript or Vbscript. This application has to send the variable (e.g. SessionFileName) through a Web form or an HTML link that identifies each session file in a unique way. By using PHP your code could look similar to: <ahref="http://ServerName/plugin/nxapplet.php?sessionFileName=session1">SessionFile1</a>

Define the root path to which all the relative paths will be appended. Please note that it is necessary to modify this value, otherwise the applet can't be initiated: <PARAM NAME="SiteUrl" VALUE="http://webserver">

You may change the applet background color by editing the nxapplet HTML. To use your own messages or button images you need to replace the relative images with your own. Please refer to the nxapplet HTML file to see what these parameters are.

The Web Companion contains a signed Java applet used to download the required client plugin (client.zip) and the session information. The client.zip archives are signed too.

The process of signing an applet ensures that the applet's code cannot be modified while travelling over the network, so that it can be trusted by the browser and executed under the user's control. Nonetheless, the signing process does not mean that other data downloaded by the applet might not be subject to spoofing and other common Internet threats. Therefore, unless the access to the Web Companion is offered on a trusted network, it is strongly suggested that you protect your communication by means of a HTTPS/SSL connection. By using the Web Companion the user is getting access to various information. You may consider putting the different data on different servers, these being HTTP or HTTPS servers, depending on the level of security you want to achieve. Some considerations to point out are:

The Java applet itself and the other Web Companion's components are not considered critical data. As we have seen, the applet has been signed so that it can be verified by the browser upon execution, and the download of the other binary components will offer the same security as the download of the NX binary packages from any other server on the Internet.

The Web page containing the applet parameters contains critical data because it exposes the address of the NoMachine Server and the URL where the session configuration can be downloaded. If the download of the session configuration has not been protected by additional means (host based access, HTTP password) a hacker would be able to intercept the data travelling over the network and get hold of the session configuration of the legitimate user.

The session configuration file, including the user's credentials should be carefully protected and never transferred over the network across an unencrypted connection. This data is downloaded by the applet from the URL specified among the parameters and used to run the session without further interaction with the user.

Please refer to your network administrator or operating system vendor to learn how to configure Apache to provide secure access by SSL.

Being a Java applet, the Web Companion displays information in the browser's Java console on the end-user's machine.

If needed, administrator can increase the debug log level by editing the nxapplet.html file placed in the Document Root of the web server. The following parameter in the nxapplet.html file specifies the log level, which is by default "1", i.e. "Warning":