NXLogin Manual

For information regarding the installation of NXLogin, see the installation manual.

Usage

The command-line tool, NXLogin.exe, is used either as:
```
nxlogin <options> -f <connection-definition-file>
```
or as:
```
nxlogin <options> <host>:<NX-display-#>
```
To get an idea about what options are supported (most of which directly correspond to properties in connection definition files), invoke NXLogin.exe without parameters.
The GUI tool, NXLoginW.exe, is either called without arguments:
```
NXLoginW
```
or with a single filename argument:
```
NXLoginW <connection-definition-file>
```
The first form launches the chooser dialog, which allows selecting a connection from a number of user-defined stored connection definitions, and creating such definitions by invoking the connection settings dialog. The user-defined connection definitions are stored in the application's data directory (see below), which can be opened from the GUI tool by clicking the Folder button. Selecting a connection in the list and clicking Connect initiates the NX session.
The second form does not launch the chooser dialog but immediately attempts to connect to the host specified in the provided definition file. This mode of operation does not allow specifying a connection mode; the mode is always AutoResume. (For more information on connection modes see below.)

In order to be able to start .nxlogin files from Windows Explorer, associate the NXLoginW.exe executable with the file type. You can also drop a connection definition file onto the executable or a link that points to it.

Creating Connection Definitions

To create new connection definition files, the best way is to start up the GUI tool, NXLoginW.exe, without command-line arguments. You can then click the New… button to enter the settings dialog. Note that if you or your site adiministrator didn't provide site-default settings, this will initially present compiled-in defaults which will undoubtedly need to be changed in a number of places.

The options in the settings dialog are explained in more detail through context-sensitive help. In most cases, remote host, local and remote display numbers, and the path to the remote nxagent program will at least need to be set.

The settings dialog also provides a way to ease setup of SSH authentication. NXLogin uses Cygwin OpenSSH, which may not already be set up in your environment and you may thus need to initialize remote host keys and public keys. See below for a more detailed explanation.

Once a connection definition has been saved by clicking OK, it will appear in the tool's list of connections. When clicking on the Folder button, a Windows Explorer window will open that reveals the location of the associated .nxlogin file. Your can perform the normal file operations in this folder, such as renaming, deleting or copying files; its contents will be read back in the tool when you click the Refresh button. Note that if the name of an .nxlogin file and its associated connection name differ, a duplicate will be created when next saving the connection, because the settings dialog always uses file names that correspond to the connection name. This also means that in order to copy an existing definition in the tool, open it by clicking Properties… after selecting it in the list, and then simply provide a new name for it before clicking OK.

It is perfectly feasible to edit .nxlogin files by hand. In order to learn what XML tags are supported you can look up their specification in the NXLoginCore.xml file which contains the doc-comments for NXLoginCore.dll.

Files used by NXLogin

On the thin client

`*.nxlogin`	These are NXLogin connection definitions. They are the XML-serialized form of objects of the ClientConnectionSettings class. Documentation on the various properties of the configuration can be found in the doc-comment file, `NXLoginCore.xml` (in the NXLogin program directory), or by using context-sensitive help in the GUI's settings screen, which reads the property descriptions from the doc-comment file.
`%APPDATA%\NXLoginW`	This is the directory where NXLogin maintains all user-defined connection definitions that were created using the GUI (`NXLoginW.exe`). Note that it is not necessary for such files to reside in this directory in order to be used with NXLogin, but this directory is the only place that will be scanned by the GUI program to present the list of available connections in the initial chooser dialog. Files in other locations have to be directly passed to the executable as first command-line argument.
`%USERPROFILE%\.nx\S-<NX-display-#>`	This is the directory where nxproxy's log and options files are stored. The file `options` contains NX authentication data (if authentication was used). The file `XWin.log` contains log messages from the Cygwin X server, in case it was used. The file `errors` contains log messages from nxproxy. The file `NXLogin-<NX-display-#>.trace` contains verbose debug output from `NXLoginW.exe`.
`%USERPROFILE%\.ssh`	This is the directory where the OpenSSH client reads its configuration data from, such as public keys, connection options, and the known-hosts database. Note that NXLogin does support password authentication in addition to public-key authentication, but it contains no support for maintaining the known-hosts database. This means it is necessary to ensure that the known-hosts file is already set up. An easy way to do this is by using the Test SSH Login button in the connection settings dialog of the GUI tool.
`%USERPROFILE%\.Xauthority`	This is the default location of the X authentication file that is used for `XWin.exe`. Note however that it is user-configurable and it will also be in a completely different location, or might not even exist, if other X servers are used on the thin client instead of `XWin.exe`.

On the remote host

`$HOME/.xinitrc`	The default X session script (it is user-configurable though)
`$HOME/.nx/<NX-display-#>`	This is the directory where nxagent's log and options files are stored. The file `nxagent-session-options` contains NX authentication data (if authentication was used). The file `nxagent.pid` contains the PID of the a running nxagent process on the display. The file `xsession-errors` contains X session errors, i. e. StdOut and StdErr of the X session script. The file `errors` contains NX link errors.
`$HOME/.Xauthority`	The default location of the remote Xauthentication file. Note however that this location is user-configurable.
`/tmp/nxagent-session-<PPID>-*`	The temporary session script (unlinked after login) used to run the remote nxagent process(`PPID` refers to the process ID of the parent shell of the nxagent session)

Local vs. remote Xauthority files

If XWin.exe is used as X11 server on the thin client and the X authentication flag is enabled, NXLogin will generate X11 authentication cookies for XWin before it is started. The authentication flag causes NXLogin to also generate NX authentication cookies (provided the connection mode allows it), which are the same format (MIT-MAGIC-COOKIE-1) but are not set to the same value as XWin's cookies. This is because the X11 server on the thin client might have a different life span than the NX session and it is thus necessary to decouple generation of thin-client X cookies from the NX ones. This also means that even if XWin.exe is used, NXLogin will not generate new authentication data for it if it finds it already running and accessible.

Setting up SSH authentication

NXLogin does not alter OpenSSH's preconfigured list of authentication methods. This means, the included SSH client will connect to the remote host using whatever authentication methods are the default in the user's environment. In a setup where there was no Cygwin OpenSSH installation before, this is likely to be password authentication. Password authentication is also the common fallback in case other methods fail.

In the NXLogin connection configuration, the user can specify whether the program should ask for a password up front. This password is then provided to OpenSSH using the SSH_ASKPASS facility; whether or not it is actually used during the authentication process is up to the SSH client.

In order to be able to operate NXLogin without having to set the Provide password flag, it is necessary to generate a public/private key pair in the default location (%USERPROFILE%\.ssh\id_rsa*), which must not have a passphrase set. If one is set, it is again necessary to provide a password, except when the user runs an SSH Agent (which is untested).

The GUI tool provides a convenience feature to set up a key pair through the Run ssh-keygen button in the connection settings dialog.

Independently of the authentication method, remote hosts that have not been accessed before must have their host keys confirmed, which NXLogin is not able to do upon connection. Instead, to confirm a remote host key, perform a test login using the appropriate button in the connection settings dialog in the GUI tool.

To set up SSH for public-key access and register the remote host from the command line (i. e. not through the connection settings dialog), ensure the HOME environment variable is set to %USERPROFILE% and execute the following in a Cygwin shell:

ssh-keygen -t rsa
cd ~/.ssh
cat id_rsa.pub|ssh remote_host "cat >> .ssh/authorized_keys"

This will ask all necessary questions in order to set up your keys and confirm the identity of the remote host.

Environment variables available to the remote X session

The X session script that defines the session on the remote host, ~/.xinitrc (by default), can assume the following environment variables are set:

DISPLAY	Obviously, this is set to the X11 display that is offered to X11 clients on the remote host by nxagent.
NXAGENTPID	The process ID of the nxagent process, which is the same ID that is stored in the `nxagent.pid` file.
NXGEOMETRY	The original NX screen geometry the nxagent process was started with. This can also be the string `-R` for rootless sessions. In case a resizable setup was used, the content of this variable will be incorrect after the first resize operation.
NXSESSIONPID	The process ID of the nxagent session script, i. e. the temporary shell script that is the parent of both nxagent and the X session script.
XAUTHORITY	Set to the X authority file that was specified in the configuration for the remote host (if X authentication is enabled)

NXLogin Connection Modes (aka Session Types)

NonPersistent – this corresponds to the -nopersistent switch to nxagent. In this mode, closing the NX connection will terminate all of nxagent's X11 clients. Reconnecting to the session is not possible.
Persistent – this corresponds to the -persistent switch to nxagent. In this mode, the nxagent process that will be started will survive connection losses and can later be reconnected to by using the Resume or AutoResume modes.
Resume – in this mode, a new instance of nxagent is never started remotely. NXLogin expects that a running nxagent as well as the file ~/.nx/C-<NX-display-#>/nxagent.pid are still present on the remote host. This running session is reconnected to.
AutoResume – this will resume a session exactly like Resume does in case the nxagent PID file is available remotely. Otherwise, it tries to start a new instance of nxagent in persistent mode.

A note on Resume and AutoResume if X authentication is used:

The Resume and AutoResume connection modes will not generate new NX authentication data but assume that existing data is available in all necessary places, i. e. in the remote Xauthority file as well as in NX options files. This should normally be fine but can be problematic in case a prior connection attempt was interrupted, that successfully generated authentication data on the thin client but failed to transfer it to the remote host. In such cases, a single connection in the NonPersistent or Persistent modes (the latter one can then later be resumed) is necessary to refresh authentication data.

Session lock-file

For the duration of a connection, NXLoginW.exe maintains a trace file in its the user's ~/.nx directory that also acts as lock-file, so that only ever one open connection per NX port and (roaming) thin client is supported. The user is notified in case they try to open another session on top of an existing one on that port. The lock-file is named NXLogin-<NX-display-#>.trace and contains verbose output of the form that the -v argument to NXLogin generates.

NXLogin.exe does not maintain a lock-file.

Troubleshooting connection errors

The program in its current state takes a few shortcuts in that it does not check the return code and standard error output of every tool involved. This means that some error conditions won't be noticed until the remote side hits a timeout, and some conditions involving nxproxy errors (for example, trying to connect to a UNIX socket when only TCP would be possible) will not be noticed by the tool at all. In such cases, the session processes might just silently exit after some time.

In general, the tool is fairly robust in that it does not leave any rogue processes behind. The various log files should provide enough information to deal with errors.

I. e., to analyze error situations it is necessary to check all log files involved, which are:

File	Node	Description
`%USERPROFILE%\.nx\S-<NX-display-#>\NXLogin-<NX-display-#>.trace`	thin client	NXLogin trace output (only available if the GUI was used; corresponds to the output of running `NXLogin.exe` with the `-v` argument)
`%USERPROFILE%\.nx\S-<NX-display-#>\errors`	thin client	NX link errors
`%USERPROFILE%\.nx\S-<NX-display-#>\XWin.log`	thin client	`XWin.exe` errors (in case `XWin.exe` was used)
`$HOME/.nx/C-<NX-display-#>/errors`	remote host	NX link errors
`$HOME/.nx/C-<NX-display-#>/xsession-errors`	remote host	X session setup errors