NoMachine Support

Your questions answered

Knowledge Base

Searching in: Documents
Filter the search results
Version:
Last update:
Searching in: Documents
ID: DT10O00160
Version: NoMachine 6
Added on: 2017-11-14
Last update: 2018-10-15
How to pre-configure web sessions
Table of Contents
Introduction
1. How to Pre-Configure Web Sessions
Configuration
2. Login
2.1. Storing Username and Password
3. Session Types
3.1. Defining the Virtual Desktop to be Run
3.2. Preconfiguring a Custom Session
3.3. Defining the Application to be run in the Custom Session
3.4. Running a Custom Session in Virtual Desktop Mode
3.5. Setting the Remote Node to be Connected (Manual Node Selection Enabled)
4. Resizing Options and Multimonitors
4.1. Resizing the Remote Desktop to the Browser Window at Session Startup
4.2. Adapting the Remote Desktop to the Browser Windows when it's Resized
4.3. Preconfiguring Size of the Browser Window
4.4. Preconfiguring Size for Custom Sessions
4.5. Preconfiguring How the Remote Session will be Shown in the Browser
4.6. Defining the Display to View when Connected to a Multi-monitors Host
5. Session Tuning and Optimization
5.1. Adjusting Display Quality Settings
5.2. Disabling Network Adaptive Display Quality
5.3. Disabling Client Side Image Post-Processing
6. Audio
6.1. Adjusting Audio Quality
6.2. Muting Audio on the Remote Host (for Physical Desktop Sessions)
7. Other keys
7.1. Tracking the Remote Cursor
7.2. Showing the Quick Access Menu Bar on Mobile Devices
7.3. Showing the Extended Keyboard on Mobile Devices


Introduction
1. How to Pre-Configure Web Sessions

Since version 6, the Web Player application in charge to deploy NoMachine sessions on the web is able to use connection files (.nxs files) in order to pre-configure aspects and behavior of sessions. It's possible to define session type, screen resolution, display quality settings.

The .nxs connection files can be deployed in two ways:

I by storing the .nxs file(s) on the user's device
II by storing the .nxs file(s) on the NoMachine Web Player's host


Read and write permissions should be granted to the owner of the .nxs files (700 on Linux and Mac).

How to use connection files on the user's device

A default template to be used for creating custom connection files is available on the Web Player host at:
NoMachineInstallationPath/share/config/default.nxs.sample

This file is owned by the nxhtd user (which is the default user for the NoMachine nxhtd web server) and has read, write, execute permissions set for this user.

On Linux and Mac permissions are set to 700:

-rwx------ 1 nxhtd nxhtd 2743 Sep 22 12:22 default.nxs.sample

- Copy and rename this file to create a personalized connection file.
- Edit option keys' value in the new connection file according to your needs.
- Save it on the user's device.
- Ensure that the connection file is owned by the user who will run the NoMachine web session and that the file owner can read and write it.

For example, let's say that the connection file is mytestdrive.nxs and it's placed in the home of user nomachine1 on a Linux computer.

The connection file must be owned by user nomachine1 and have read and write permissions set for the owner:

chown nomachine1 mytestdrive.nxs
chmod 0600 mytestdrive.nxs


To use the connection file: point the browser to the Web Player's URL, namely: http://SERVER:PORT

where SERVER is either the name or IP address of the host you want to reach and PORT is the listening port (by default 4080).

Then drag and drop the connection file into the browser: the session will be started with the configurations set in the .nxs file.



How to use connection files stored on the Web Player host

- Copy and rename the default template available at:
NoMachineInstallationPath/share/config/default.nxs.sample

- and store it in the following directory:
NoMachineInstallationPath/share/config/TestdriveConnection.nxs

For example: NoMachineInstallationPath/share/config/TestdriveConnection.nxs

- Ensure that ownership (nxhtd:nxhtd) and permissions (700, on Linux and Mac) are preserved for the new connection file.
To set them on Linux or Mac:

chown nxhtd:nxhtd TestdriveConnection.nxs
chmod 0700 TestdriveConnection.nxs

You can have as many customized connection files as you want.

To use any of the customized connections files, users have to point the browser to the given URI for creating the session with such pre-configured settings, namely:

http://SERVER:PORT/nxwebplayer?config=connectionFileName

For example: http://testdrive.nomachine.com:4080/nxwebplayer?config=TestdriveConnection.nxs



The following URI format is also valid:

http://SERVER:PORT/nxwebplayer?connectionFileName

For example: http://testdrive.nomachine.com:4080/nxwebplayer?TestdriveConnection.nxs

Note that http connections will switch to https, which uses by default port 4443.

TIPS
I Connections by http will switch to https, which uses by default port 4443.
II The .nxs file is written in an XML-like format, you may find below accepted values for the most relevant keys.


How to lock down web connections by nxs files

It's possible to define if users should launch web sessions only by using connection files (.nxs) stored on server side or not. This option is available since v. 6.3.

To do that, disable or enable the EnableWebPreconfiguration key in the server configuration (server.cfg).

When disabled:
EnableWebPreconfiguration 0
Users can configure their web sessions at runtime or can use pre-configured connection files stored on the server or on their device.

When enabled:
EnableWebPreconfiguration 1
Users can run sessions on the web only through a a connection file pre-configured on the server.



2. Login


2.1. Storing Username and Password

When the following keys are set, user doesn't need to provide access credentials and logs-in to the server automatically:
<option key="User" value="" />
<option key="Auth" value="" />

If value is not set, the user will be requested to provide his/her password. Otherwise provide the password in the same scrambled format used by the NoMachine client, see: https://www.nomachine.com/AR01C00125 for instructions.

Note that, for security reasons, sensitive data is never transmitted from the server side to the client side. This means that even if the password is set in the connection file stored on the Web Player host, it will never be used for automatic log-in. To use a pre-configured password is therefore necessary to provide the connection file to the user and save it on his/her computer.



3. Session Types


3.1. Defining the Virtual Desktop to be Run

The following key defines the virtual desktop type to be run:
<option key="Session" value="" />

Accepted values are: 'unix', 'windows' or 'vnc'. 'windows' indicates RDP sessions.
For example, launch a RDP virtual desktop:
<option key="Session" value="rdp" />

Such key can be used in conjunction with:
<option key="Desktop" value="" />

to define the X11 desktop environment to be launched in case of session types 'unix'. Accepted values are: 'xsession-default', 'kde', 'gnome', 'xdm' or 'console'. Value 'xsession-default' will start the default desktop environment set on the system and specified in the DefaultDesktopCommand node configuration key. Value 'console' specifies instead a custom session.

For example, to run a Linux virtual desktop with the default desktop environment, set:
<option key="Session" value="unix" />
<option key="Desktop" value="xsession-default" />



3.2. Preconfiguring a Custom Session

A custom session is a single Linux application and it can be defined through these keys:
<option key="Session" value="unix" />
<option key="Desktop" value="console" />

Specify the program to be launched by means of:
<option key="Custom Unix Desktop" value="" />

This key accepts: 'application', 'default' or 'console' as value. 'application' specifies the program to be launched in the custom session, 'default' will run the default X script defined on the server and 'console' will run the system terminal program.



3.3. Defining the Application to be run in the Custom Session

Set the following keys:
<option key="Session" value="unix" />
<option key="Desktop" value="console" />
<option key="Custom Unix Desktop" value="application" />

and provide path and command for launching the application in this key:
<option key="Command line" value="" />

For example, to launch the OpenOffice Writer on the remote host:
<option key="Session" value="unix" />
<option key="Desktop" value="console" />
<option key="Custom Unix Desktop" value="application" />
<option key="Command line" value="soffice -writer" />

Note that if the application is not in the path on the remote host, it's necessary to provide the full path in the "Command line" value field.



3.4. Running a Custom Session in Virtual Desktop Mode

Running a custom session in virtual desktop mode means that the single program is launched but it's contained in a full virtual desktop. This can, for example, launch an alternative desktop environment. For example, to run Xfce as custom session in virtual desktop mode:
<option key="Session" value="unix" />
<option key="Desktop" value="console" />
<option key="Custom Unix Desktop" value="application" />
<option key="Command line" value="/etc/X11/Xsession startxfce4 />
<option key="Virtual desktop" value="true" />



3.5. Setting the Remote Node to be Connected (Manual Node Selection Enabled)

This applies only to a NoMachine Enterprise Terminal Server with a multi-node environment set (Terminal Server Nodes). When the server is configured to permit users to choose the remote node where to start the session (i.e. the manual node selection is enabled), use this key to specify the node:
<option key="Connect to this node when manual selection is enabled" value="NODE:PORT" />
Where NODE:PORT is the name of the remote node, as listed in the output of the 'nxserver --nodelist' command.

If value of this key is empty, the user will be able to choose the node, otherwise the session will be always started on the given node.



4. Resizing Options and Multimonitors


4.1. Resizing the Remote Desktop to the Browser Window at Session Startup

When the remote machine has a different resolution to the user's device, it's possible to preserve the remote resolution or change it while connected. To change the remote resolution to match the user's one, use:
<option key="Resize the remote screen to the local geometry" value="true" />

Accepted values are 'true' or 'false'.



4.2. Adapting the Remote Desktop to the Browser Windows when it's Resized

<option key="Enable session auto-resize" value="false" />

Accepted values are: 'true' or 'false'.



4.3. Preconfiguring Size of the Browser Window

This option makes the web player to ask the remote desktop to start with the given resolution. The remote desktop can ignore this setting if it has a different configuration stored in desktop manager settings or if the 'Resize the remote screen to the local geometry' or the 'Enable session auto-resize' option are enabled (set to 'true').
<option key="Resolution" value="" />

Value must be specified in the format of 'WxH' pixels, e.g. 1024x768.



4.4. Preconfiguring Size for Custom Sessions

To sepcify the resolution for a custom session, set this key to 'true' (accepted values are 'true' and' false'):
<option key="Use custom resolution" value="true" />

and define width and height (in pixels) of the custom session by means of:
<option key="Resolution width" value="" />
<option key="Resolution height" value="" />

4.5. Preconfiguring How the Remote Session will be shown in the Browser

When resizing the remote resolution is disabled and client/server resolutions don't match, the session can be displayed in two ways: its content can be scaled to fit the browser's window or a viewport is activated to let the user move the session's visible area. Any of these two methods can be set in this key:
<option key="Session resize mode" value="viewport" />

Accepted values are: 'viewport' or 'scaled'.



4.6. Defining the Display to View when Connected to a Multi-monitor Host

This applies when multiple monitors are connected on server side and pre-defines which monitor to view when connecting to the server. Monitors are identified by number starting from 0 (the first monitor). Set the following key to sepcify the monitor number:
<option key="View a specific monitor among available monitors" value="" />

Accepted values are: a number corresponding to the monitor or "ALL", which means 'see all monitors as a unique monitor'. An empty value corresponds to 'ALL'.



5. Session Tuning and Optimization


5.1. Adjusting Display Quality Settings

The following keys pre-define the display quality for the session:
<option key="Link quality" value="9" />

Accepted values are number from 1 to 9, where 9 is the highest quality.



5.2. Disabling Network Adaptive Display Quality

Disabling network adaptative display quality will anchor the lowest quality to a fixed value, making it independent from the current network congestion:
<option key="Disable network-adaptive quality" value="true" />

Accepted values are 'true' or 'false'.



5.3. Disabling Client Side Image Post-Processing

Images post-processing is made only on client side, this setting doesn't affect server side:
<option key="Disable image post-processing" value="true" />

Accepted values are 'true' or 'false'.



6. Audio
Audio streaming is possible only when WebRTC is enabled!


6.1. Adjusting Audio Quality

The following key allows adjustment of audio quality:
<option key="Output audio quality" value="" />

Accepted values are number from 1 to 9, where 9 is the highest quality.



6.2. Muting Audio on the Remote Host (for Physical Desktop Sessions)

When the user is connected to the remote physical desktop, it's possible to mute audio on the server by means of:
<option key="Mute audio of the remote physical desktop" value="true" />

Accepted values are 'true' or 'false'.



7. Other keys


7.1. Tracking the Remote Cursor

To enable or disabling showing the remote cursor use this key:
<option key="Enable remote cursor tracking" value="false" />

Accepted values are 'true' or 'false'.



7.2. Showing the Quick Access Menu Bar on Mobile Devices

On mobile devices, the quick access menu is a bar displayed at the bottom of the session window which provides fast access to most common options.
<option key="Show quick toolbar on mobile client" value='true' />

Accepted values are 'true' or 'false'.



7.3. Showing the Extended keyboard on Mobile Clients

To show or hide the extended keyboard on mobile device, use:
<option key="Show extended keyboard on mobile client" value='true' />

Accepted values are 'true' or 'false'.