Chapter 13.  Commands on the ThinLinc Server

In this chapter, we will describe the commands shipped as part of the ThinLinc server that are meant for the common user.

Commands in /opt/thinlinc/bin

tl-best-winserver server [server ...]

The tl-best-winserver command asks the Windows Remote Desktop Servers listed on its commandline for their respective load status. It then prints the name of the least loaded server on standard out, and exits. If the file .thinlinc/last-winserver exists in the user's home directory, the server listed there will be checked for sessions owned by the user. If such a session exists, tl-best-winserver will print the name of that server regardless of its load, since the user should get his/her old session when logging in again. The information that this script prints out is used by tl-run-rdesktop when it chooses which server to connect to.

tl-session-param [options ] parameter

The tl-session-param command is used to access the session information managed by the VSM server. This includes information sent by the client, such as if the client has exported any local drives, or what language is set on the client side. This command is used by for example, documented later in this chapter.

tl-config options

The tl-config command is used to access configuration parameters used by the ThinLinc system. It is also used to set parameters from scripts, and can be used instead of an editor when some parameter needs to be changed. tl-config uses hivetool, part of the Hiveconf system. See Chapter 16, Hiveconf for more information about Hiveconf.


When a user's Gnome or KDE desktop needs to be reset to default, the command tl-desktop-restore can be run. This will move the settings directories for KDE and Gnome to a backup directory named .old-thinlinc-desktop in the user's home directory, which will make both Gnome and KDE revert to the default settings.


This command is run by VSM Server at session startup and reconnect if the Printer Access Control feature of ThinLinc is activated. See Section 5.5, “ Printer Access Control ” for details.


This command is used to mount CIFS/SMB network file systems at login-time. See Section 10.1, “ Accessing Windows File Servers ” for documentation on this subject.

tl-memberof-group groupname...

This command can be used to determine if the current user is a member of the specified groups. It returns true (0) if the user is a member of any of the groups, false (1) if the user is not a member and false (2) if any of the specified groups do not exists.


This command is used to let the user change their password, both in the underlying authentication mechanism and in the ThinLinc Single Sign-On mechanism.

In order for this to work, any user must be able to read the file /etc/pam.d/sshd (or, more correct, the file that the symbolic link /etc/pam.d/thinlinc points at.

Also, in the case where the underlying authentication mechanism is LDAP or eDirectory, make sure that the parameter pam_password in /etc/ldap.conf is set to a value that is appropriate for your environment. If you're authenticating against eDirectory servers, it must be set to nds. See the comments in ldap.conf for more information.

tl-run-rdesktop [options ]

The tl-run-rdesktop program is a wrapper around the rdesktop program. It extends the functionality of rdesktop by connecting to one of the Windows Remote Desktop Servers specified by the system administrator in /appservergroups/rdp/<group>/servers . If the user has a pre-existing session on one of the servers in the list, the session is reconnected. If not, the server with the least load is selected. The command creates the connection with the correct domain and keyboard layout. For more information, see Section 14.2.4, “ Parameters in /appservergroups/ ”. Multiple groups of Windows Remote Desktop Servers can be specified. This makes it possible to direct different groups of users to different servers in an easy way. In the parameters specified above, exchange <group> for the group you have specified in Hiveconf, and tell tl-run-rdesktop which group to use by using the -G commandline option. If no group is selected, the group named default is used.

tl-run-unixapp [arguments ]

This command uses single sign-on to login to a UNIX server defined in /appservergroups/x11/<group>/servers , executing either a shell or the commands specified. It also sets up X11 over SSH if defined in /appservergroups/x11/<group>/use_ssh_encryption . Just as with tl-run-rdesktop, tl-run-unixapp supports application server groups, which means multiple groups of Unix servers can be specified. The application server group to be used is choosen by using the -G commandline option to tl-run-unixapp. If no group is selected, the group named default is used.


This command requires that the OpenSSH client is installed on the server where it is run.

Best Practice

If the SSH host key of the server tl-run-unixapp is configured to connect to is not known, a window will be shown where the user is asked if the host key should be trusted. If this question is confusing your users, add the host keys of the servers in /etc/ssh/ssh_known_hosts. That will make SSH recognize the host, removing the question for the users. It will also increase security, since the host key is then checked by personell that have the ability to actually verify the key.

tl-run-winapp [-D] [-T title ] [arguments ] windows-app [application arguments ]

This is a wrapper around tl-run-rdesktop that executes a single command on the Windows Remote Desktop Server with most system resources left.

tl-run-winapp takes many different arguments, but the most common ones are -D , which hides the window manager decorations. -T title sets the title of the window to the string in question.


tl-run-winapp -D -T Excel excel.exe

tl-run-winapp-seamless [arguments ] windows-app [application arguments ]

This command resembles tl-run-winapp except that the application is executed in SeamlessRDP mode. This allows for full integration with the desktop. For more information, see Section 11.3.4, “ Running a Windows application in SeamlessRDP Mode ”.

tl-run-winapp-seamless takes the same arguments as rdesktop, except for the -G parameter.


tl-run-winapp-seamless c:\program\\mozilla\mozilla.exe


This is a wrapper for tl-run-rdesktop that starts a full screen session against the best Windows Remote Desktop Server available.


This command is run by the default session startup file (/opt/thinlinc/etc/xstartup.default) to execute all start scripts in the directory /opt/thinlinc/etc/xstartup.d/. Files with the suffix .sh will be sourced. All other files will be executed.


This command is run by the session setup file (/opt/thinlinc/etc/xstartup.default or ~/.thinlinc/xstartup) and provides a menu where the user can choose what kind of session to run. See Section 14.4, “ Customizing the User's Session ” for more information.

By creating a symlink from /opt/thinlinc/etc/xstartup.d to this command, the user's LANG environment will be set to the language environment reported by the client.


This command starts the tl-shadow-notify command for the lifetime of the session. This will enable notifications when the session is shadowed.

tl-single-app command [arguments ]

The tl-single-app command can be used to execute a single application in a ThinLinc session. A window manager with a suitable configuration is automatically started. All top level windows are automatically maximized. Window titles are displayed in the title bar of the ThinLinc Client, not in the ThinLinc session. The client close button will disconnect the session as usual. Inner close buttons closes application windows. The tl-single-app command can be specified as a client supplied start program (see Section 14.4.4, “ Session Startup with a Client Supplied Start Program ”), or used with the ThinLinc profile selector (see Section 14.4.5, “ Configuring available profiles ”).

Switching Between Windows

If the application opens multiple top level windows, you can switch between them by clicking on the application icon in the top left corner.


This command requests a password from the user, to be used with the Single Sign-On mechanism of ThinLinc. It is useful when the password is not already available, for example, when using One Time Passwords. See Section 9.5.3, “ Configuration for RSA SecurID ” for more information.

tl-support [-p listen-port ] [-u user ] [host ]

The tl-support command can be used to enable a support technician to login to your ThinLinc server, even though the server is behind a firewall that doesn't allow connections to the ssh port. This is accomplished by opening a ssh connection from the server to an external server on the internet, at the same time setting up a tunnel from the remote host to the local host's ssh port. The default server to connect to is with the default username "support". This command should only be used after contacting your ThinLinc support technician.


This command is used to unmount CIFS/SMB network file systems at logout-time. See Section 10.1, “ Accessing Windows File Servers ” for documentation on this subject.


This command is used to disconnect from the current session. This can be used to provide an alternative to the F8 key, such as a disconnect button on the Gnome panel.

tl-sso-password [--check] [--remove]

This command can be used to hook up the Single Sign-on mechanism of ThinLinc with new applications. It can be used to test for the presence of a valid password and to feed that password out on standard output to another application.

To check for the existance of a valid password, invoke the command as tl-sso-password --check. A return code of zero indicates a valid password.

If the --remove option is specified, the password will be removed, after the retrieval or check.

There are two basic models to connect tl-sso-password to an application. The first is to use shell pipes:

# tl-sso-password | /usr/bin/application --read-password-on-stdin

The second is to have the application invoke tl-sso-password as needed:

# /usr/bin/application --password-prog tl-sso-password

tl-sso-token-passphrase [--check] [--remove]

This command is identical to tl-sso-password, except that it uses the smart card token passphrase (PIN) instead of the user's password. For usage, see the tl-sso-password section above.

tl-env [-d ] [-n nr ] [command [arg... ] ]

tl-env [-s] [-n nr ]

This command can be used to save and restore the ThinLinc session environment variables. It operates on the file xstartup.env in the session directory. During session startup, tl-env is called with the -s option after everything in xstartup.d have been executed. Later, tl-env can be used to execute a command in this environment, even outside the ThinLinc session. During restore, the DISPLAY environment variable can be excluded by specifying -d. By default, this command operates on the "last" session number for the invoking user. An alternative session number can be specified with the -n option.

Commands in /opt/thinlinc/sbin

tl-notify [-u username ] message

This command sends a user-visible message to ThinLinc sessions on the server. The default is to send the message to all sessions, but the -u option can be used to send the message to a single recipient instead.

To send messages to all users in a ThinLinc cluster, you can use this command in combination with the tl-ssh-all command described in this section.


This command is used to synchronize files and directories in a ThinLinc cluster. It runs the rsync command over SSH against all agent servers in the cluster. When using this command, it's convenient if password-less SSH login between the servers in the clusters has been setup.

See also tl-ssh-all below for some tips regarding password-less running of ssh.


This command is used to perform shell commands on all slaves in a ThinLinc cluster. It works by running the ssh command against all agent servers in the cluster. When using this command, it's convenient if password-less SSH login between the servers in the clusters has been set up.

Best Practice

An alternative approach to using password-less login is to use the SSH agent to cache the passphrase of a SSH keypair. This increases the security, since a malicious party that gains access to the server which is configured to login to the other servers with SSH key-pair does not automatically get access to the rest of the servers - a password is needed.

First, setup the SSH key-pair as described below:

# First time / One time procedure
# Generate a private and public key-pair for SSH with SSH keygen.
# When prompted pick a secret password for the key-pair.
ssh-keygen -t dsa

# Copy the public key to SSH authorized_keys
cp /root/.ssh/ /root/.ssh/authorized_keys

# Make sure the authorized key has the right permissions
chmod 600 /root/.ssh/authorized_keys

# Copy the authorized key to all ThinLinc Agents
tl-rsync-all /root/.ssh/authorized_keys

Next, before using tl-ssh-all, do as follows

eval `ssh-agent`

# Run your commands
tl-ssh-all rpm -Uvh /root/kdelibs-3.5.1-1.fc4.i386.rpm

Commands in /opt/thinlinc/libexec


CodeWeavers CrossOver allows you to configure the mapping between Windows drive letters and paths in the Linux file system. This can be done globally by adding symbolic links to the directory /opt/cxoffice/support/BOTTLENAME/dosdevices. However, this does not work if drive letters should correspond to different paths for different users. In this case, a bottle hook script is required. tl-crossover-drives is such a script that automatically maps "personal" mounts to separate drive letters in CrossOver. This includes all mounts mounted on subdirectories in the users home directory. The first character of the directory name determines the drive letter. To activate this command for all bottles, execute:

# mkdir /opt/cxoffice/support/scripts.d
# ln -s /opt/thinlinc/libexec/tl-crossover-drives \


The tl-has-gnome-2 command is used to check if Gnome 2 is installed on the system, in a way which works for most distributions. It is used by the default profile configuration.

tl-unity-2d [--test ]

The tl-unity-2d command is used to start the Unity 2D desktop environment, in a way that works on most distributions. It is used by the default profile configuration. The --test option can be used to test if this desktop environment is installed.

The command is used to obtain a Kerberos ticket automatically during start of the session, using the single sign-on mechanism.

The command is used to destroy the Kerberos ticket cache. It calls kdestroy during logout.