NoMachine Web Companion v. 4 - Installation and Configuration Guide

Added on: 2013-09-24 Last Modified: 2015-07-07

 

Table of Contents

1. NoMachine Web Companion Installation and Configuration Guide

1.1. Resources on the Web

1.2. Prerequisites
2. What is NoMachine Web Companion

2.1. What the Web Companion Allows You to Do

2.2. What the Web Companion Package Includes

2.3. The Client.zip Archive

2.4. Install and Update the Plugin on the End-user's Machine

2.5. Intitiating the Connection to NoMachine
3. Installation of NoMachine Web Companion

3.1. Managing the RPM Package

3.2. Managing the DEB Package

3.3. Managing the TAR.GZ Package
4. Making the Web Companion Operative

4.1. Editing the Applet HTML File

4.2. The Session File

4.3. Generating the Session File

4.4. Multiple Session Files and Univocity

4.5. Providing Multiple Session Types via the Web Companion
5. Configuring and Personalizing the Web Companion

5.1. The Applet HTML File

5.2. How to Personalize the Messages
6. Securing the Web Companion
7. Increasing Debug Log Level

 

 

1. NoMachine Web Companion Installation and Configuration Guide

Welcome to the NoMachine Web Companion Installation Guide version 4. 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.

1.1. Resources on the Web

The NoMachine Web site, www.nomachine.com, provides you with a variety of online resources in conjunction with the software and its usage:

The NoMachine Packages
The latest version of NoMachine is available at: www.nomachine.com/download.


Latest News
To stay updated with the most recent releases of the NoMachine software, as well as the latest news please subscribe to the ML here:
https://www.nomachine.com/mailing-lists


The Knowledge Base
The 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 Guide
Our 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.

1.2. Prerequisites

The Web Companion package can be installed on any of the following Linux Operating System (32-bit and 64-bit):

Red Hat Enterprise 4/5/6/7
SLES 10/11
SLED 10.x/11.x
Open SUSE 10.x /11.x/12.x/13.x
Mandriva 2009/2010/2011
Fedora 10/11/12/13/14/15/16/17/18/19/21
Debian GNU Linux 4.0 Etch/5.0 Lenny/ 6.0 Squeeze/ 7.0 Wheezy/ 8.0 Jessie
Ubuntu 8.04 Hardy Heron/8.10 Intrepid Ibex/Ubuntu 9.04 Jaunty Jackalope/
9.10 Karmic Koala/10.4 Lucid Lynx/10.10 Maverick/11.04 Natty/11.10 Oneiric/12.04 Precise Pangolin/
13.04 Raring Ringtail/13.10 Saucy Salamander/14.04 Trusty Tahr/14.10 Utopic Unicorn/15.04 Vivid Vervet



The tar.gz version can be installed also on Windows and Mac OS X. Supported platforms are:

Windows 32-bit/64-bit XP/Vista/7/8/8.1
Mac OS X Intel 64-bit 10.5/10.6/10.7/10.8/10.9/10.10

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.

 

2. What is NoMachine Web Companion

NoMachine Web Companion is a small Java applet that can be easily integrated into a web portal to give your users one click access to remote desktops via NoMachine.

 

2.1. What the Web Companion Allows You to Do

Web Companion allows you to set-up a Web interface to:

  • - 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.

 

2.2. What the Web Companion Package Include

The NoMachine Web Companion package, named nomachine-plugin, includes:

  • - The applet (the nxapplet.jar and nxapplet.html files).
  • - All the images (buttons, messages etc...) needed by the applet.
  • - A session directory to store the session file(s), i.e. the pre-configured .nxs files.
  • - A client.zip archive for each of the supported platforms.


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.

 

2.3. The Client.zip Archive

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.

 

2.4. Install and Update the Plugin on the End-user's Machine

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.

 

2.5. Intitiating the Connection to NoMachine

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).

 

3. Installation of NoMachine Web Companion

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 OS X 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.

 

3.1 Managing the RPM Package

Installing

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

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.

 

3.2 Managing the DEB Package

Installing

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

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.

 

3.3. Managing the TAR.GZ Package

Installing

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

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.

 

4. Making the Web Companion Operative

In order to have NoMachine Web Companion fully operative you need to ensure that:

  • - The plugin/ directory provided by the Web Companion installation is accessible by your web server, i.e. it has been copied to the document root of the web server.
  • - You have edited the DocRoot/plugin/nxapplet.html file to fit your environment.
  • - You have created at least one session file (.nxs).


4.1. Editing the Applet HTML File

The HTML file contains all the parameters used by the Web Companion. Among them, the SiteUrl parameter must be edited to define the root path to which all the relative paths will be appended:


<PARAM NAME="SiteUrl" VALUE="http://webserver">


For example:


<PARAM NAME="SiteUrl" VALUE="http://testdrive.nomachine.com">

 

4.2. The Session File

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.

 

4.3. Generating the Session File

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'.

Sessions files 3.5.0 are compatible with NoMachine Enterprise 4.

 

4.4. Multiple Session Files and Univocity

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.

 

4.5. Providing Multiple Session Types via the Web Companion

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:
<a
href="http://ServerName/plugin/nxapplet.php?sessionFileName=session1">SessionFile1
</a>


<a
href="http://ServerName/plugin/nxapplet.php?sessionFileName=session2"><SessionFile2
</a>


Then you need to modify the DocRoot/plugin/nxapplet.html file to get the value passed for the session file name:
<PARAM NAME="SessionUrl"


VALUE="/plugin/session/<?=$_REQUEST['sessionFileName']?>.nxs">

The Web Compation is fully parametric, thus allowing for dynamic change of the other parameters specified in the applet HTML file.

 

5. Configuring and Personalizing the Web Companion

 

5.1. The Applet HTML File

The DocRoot/plugin/nxapplet.html file provides the following parameters which allow to personalize the installation and appearance of your NX Web Companion:

Parameters for configuring the applet initialization phase


Applet background color:


<PARAM NAME="boxbgcolor" VALUE="236, 235, 229">


To enable or disable the progress bar:
<PARAM NAME="progressbar" VALUE="true">


Message provided during the applet initialization:
<PARAM NAME="boxmessage" VALUE="Please wait while Java applet loads...">


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">


Parameters to configure the applet appearance


Base directory where the images used for the background are placed:


<PARAM NAME="BackgroundsUrl" VALUE="/plugin/images/backgrounds/">


Background images:


<PARAM NAME="Background1" VALUE="background-1.png">
<PARAM NAME="Background2" VALUE="background-2.png">
<PARAM NAME="Background3" VALUE="background-3.png">
<PARAM NAME="Background4" VALUE="background-2.png">
<PARAM NAME="Background5" VALUE="background-4.png">
<PARAM NAME="Background6" VALUE="background-4.png">
<PARAM NAME="Background7" VALUE="background-5.png">
<PARAM NAME="Background8" VALUE="background-6.png">
<PARAM NAME="Background9" VALUE="background-7.png">


Base directory where the message images are placed:


<PARAM NAME="StringsUrl" VALUE="/plugin/images/strings/">


Message images:


<PARAM NAME="String1" VALUE="string-1.png">
<PARAM NAME="String2" VALUE="string-2.png">
<PARAM NAME="String3" VALUE="string-3.png">
<PARAM NAME="String4" VALUE="string-4.png">
<PARAM NAME="String5" VALUE="string-5.png">
<PARAM NAME="String6" VALUE="string-6.png">
<PARAM NAME="String7" VALUE="string-7.png">


Base directory where the error message images are placed:
<PARAM NAME="ErrorsUrl" VALUE="/plugin/images/errors/">


Error message images:


<PARAM NAME="Error1" VALUE="error-1.png">
<PARAM NAME="Error2" VALUE="error-2.png">
<PARAM NAME="Error3" VALUE="error-3.png">
<PARAM NAME="Error4" VALUE="error-4.png">
<PARAM NAME="Error5" VALUE="error-5.png">
<PARAM NAME="Error6" VALUE="error-6.png">
<PARAM NAME="Error7" VALUE="error-7.png">
<PARAM NAME="Error8" VALUE="error-8.png">
<PARAM NAME="Error9" VALUE="error-9.png">
<PARAM NAME="Error10" VALUE="error-10.png">
<PARAM NAME="Error11" VALUE="error-11.png">


Base directory where the button images are placed:


<PARAM NAME="ButtonsUrl" VALUE="/plugin/images/buttons/">


Button images:


<PARAM NAME="Cancel" VALUE="cancel.png">
<PARAM NAME="CancelOver" VALUE="cancel-over.png">
<PARAM NAME="CancelActive" VALUE="cancel-active.png">
<PARAM NAME="Continue" VALUE="continue.png">
<PARAM NAME="ContinueOver" VALUE="continue-over.png">
<PARAM NAME="ContinueActive" VALUE="continue-active.png">
<PARAM NAME="Download" VALUE="download.png">
<PARAM NAME="DownloadOver" VALUE="download-over.png">
<PARAM NAME="DownloadActive" VALUE="download-active.png">
<PARAM NAME="Run" VALUE="run.png">
<PARAM NAME="RunOver" VALUE="run-over.png">
<PARAM NAME="RunActive" VALUE="run-active.png">
<PARAM NAME="Details" VALUE="details.png">
<PARAM NAME="DetailsOver" VALUE="details-over.png">
<PARAM NAME="DetailsActive" VALUE="details-active.png">
<PARAM NAME="Pause" VALUE="pause.png">
<PARAM NAME="PauseOver" VALUE="pause-over.png">
<PARAM NAME="PauseActive" VALUE="pause-active.png">
<PARAM NAME="Resume" VALUE="resume.png">
<PARAM NAME="ResumeOver" VALUE="resume-over.png">
<PARAM NAME="ResumeActive" VALUE="resume-active.png">


URL to which the user will be redirected when exiting the applet. If this parameter is not specified, the user will be referred back to the previous page.

<PARAM NAME="RedirectUrl" VALUE="http://www.nomachine.com">


Parameters for specifying the session file


URL from which the applet will download the session file. This name should be unique, in order to grant every user their own session file. It is strongly suggested to use the .nxs extension:


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


How the downloaded session file should be renamed when saved locally. Please note that it is strongly suggested to use the .nxs extension:


<PARAM NAME="SessionName" VALUE="testdrive.nxs">


Parameters for specifying the client.zip archives


URL from which the applet will download the NX Client for Linux archive:
<PARAM NAME="LinuxClientUrl" VALUE="/plugin/Linux/client.zip">


URL from which the applet will download the NX Client for Windows archive:
<PARAM NAME="WindowsClientUrl" VALUE="/plugin/Windows/client.zip">


URL from which the applet will download the client plugin for Mac OS/X archive:
<PARAM NAME="MacOSClientUrl" VALUE="/plugin/MacOSX/client.zip">

IMPORTANT
Do not modify the following parameters:

  • Applet parameters

<PARAM NAME="archive" VALUE="nxapplet.jar">
<PARAM NAME="code" VALUE="NXApplet.class">
<PARAM NAME="type" VALUE="application/x-java-applet;version=1.2">

  • Version of the Enterprise Client contained in the client.zip archive:

<PARAM NAME="LinuxClientVersion" VALUE = "4.6.4-2">
<PARAM NAME="WindowsClientVersion" VALUE = "4.6.4-2">
<PARAM NAME="MacOSClientVersion" VALUE = "4.6.4-2">

5.2. How to Personalize the Messages

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.

 

6. Securing the Web Companion

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.

 

7. Increasing Debug Log Level

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":


<PARAM NAME="loglevel" VALUE="1">


Accepted values are:


Log level: 0 -> PANIC, display only fatal errors.
Log level: 1 -> WARNING, display errors and warnings.
Log level: 2 -> TEST, display errors, warnings and information about main operations executed by the applet.
Log level: 3 -> DEBUG, display errors, warnings and specific information about operations executed by the applet.