8.6.  Web Integration and Web Access

This section includes information about the ThinLinc client types that can be used in conjunction with a Web Browser. ThinLinc Web Access (HTML5 client), and how to launch the Native ThinLinc client from the browser using the CGI script, are described below.

8.6.1.  Launching the Native Client From a Web Page

It is possible to launch the native ThinLinc client from a web page. The process works like this:

  1. The CGI script is called with the desired parameters.

  2. The CGI script generates a "launch file", which is a normal client configuration file. When the browser recieves this file, it launches the locally installed ThinLinc client.

The launch file delivered to the client is generated from the template /opt/thinlinc/etc/tlclient.conf.webtemplate. The CGI script performs some substitutions on this file, before sending it to the client. Currently, the following variables are substituted:

$server_name$

The server name where the CGI script resides.

$login_name$

The user name, specified by the username CGI parameter.

$password$

The password in hexadecimal ASCII notation, specified by the password or hexpassword CGI parameters.

$autologin$

The value of the autologin CGI parameter.

8.6.2.  The CGI Script tlclient.cgi

The CGI script tlclient.cgi is used to start the native client, when launched from a web page. It accepts many parameters which affects its operation. These are described below:

server_name

The desired server name.

username

The desired user name. No default.

password

The desired password, in plain text. No default.

hexpassword

The desired password, in hexadecimal ASCII notation. This parameter overrides the password parameter. No default.

redirto

After launching the native client, the browser will redirect to the web page specified by this parameter. Default value: the empty string.

loginsubmit

This boolean parameter specifies if a login should be directly executed, instead of showing a login form. Default value: 0

autologin

This boolean parameter specifies if the native client should automatically connect to the specified server at startup. Default value: 1

start_program_enabled

This boolean parameter specifies if the native client should request that the server starts the session with the command supplied by the client, as indicated by the start_program_command parameter. Default value: 0.

start_program_command

This parameter specifies the command to use when starting the session. Default value: "tl-single-app firefox".

displayurl

This boolean parameter can be used for debugging and development purposes. It will display and URL with all submitted parameters, and do nothing else. Default value: 0

shadowing_enabled

This boolean parameter specifies if the native client should activate shadowing. Default value: 0

shadow_name

This parameter specifies the user to shadow. Default value is the empty string.

To make it easier to test various parameters, the HTML file cgitest.html is included, in the same location as tlclient.cgi. It also demonstrates how to create icons on web pages, which launches ThinLinc sessions.

8.6.3.  ThinLinc Web Access (HTML5 Client)

ThinLinc Web Access is a ThinLinc client that runs in modern browsers. This web application is based on the Open Source project noVNC. It uses HTML5 features such as WebSockets and Canvas. We have tested the latest versions of following browsers:

  • Internet Explorer

  • Firefox

  • Google Chrome

  • Safari

8.6.3.1.  Server Side

ThinLinc Web Access is served by the service tlwebaccess. This server side component is included in the package thinlinc-webaccess. It is automatically installed when the ThinLinc software is installed. The default TCP port number for this HTTP service is 300. It can be changed to some other port such as 443 (see below), assuming this port is free. The configured port must be allowed in any firewalls. In a cluster setup, the tlwebaccess service must run on all machines. The same service port should be used, and all machines must be accessible from the clients. You will likely want to set the parameter /webaccess/login_page as well, see Section 8.6.3.1.2, “ Configuration ”.

8.6.3.1.1.  Certificates

For best security and user experience, we strongly recommend that you use valid TLS certificates. The certificates should match the server host names. For correct behavior, you should set the parameter /vsmagent/agent_hostname on each of the agents in the ThinLinc cluster.

If you can't obtain a valid TLS certificate but still want to test ThinLinc Web Access you can use a self-signed certificate. Such a certificate, created for "localhost", is bundled with Web Access. Any use of self-signed certificates is insecure and most browsers will display warnings when they are used. Self signed certificates must be manually approved.

Note

In Safari, the certificates MUST match the server hostname, while other browsers might be content with a warning. Firstly, this means that you cannot connect through an IP address. Secondly, you can not use the bundled self-signed certificate. You can create a new self-signed certificate using our shipped helper script make-dummy-cert. OpenSSL is required to be installed for this script. Use it like this:

		$ sudo /opt/thinlinc/etc/tlwebaccess/make-dummy-cert `hostname --fqdn`

Manually approving the self-signed certificate requires some additional steps in Safari compared to other browsers. On macOS the user must expand the browser dialog that complains about the certificate and choose to always accept that certificate. If the user already dismissed that dialog, then Safari has to be restarted. A self signed certificate must be manually approved for all machines in a cluster.

If you must test a browser on iOS with a self-signed certificate you have to use Safari to manually type the hostname and port of your server and add /server.crt to the URL in order to download the server certificate (e.g. https://thinlinc-master.example.com:300/server.crt). After downloading the certificate, you have to install it using the iOS prompt that appears. On iOS version 10.3 and later you also have to enable the full trust of that root certificate in the "Certificate Trust Settings" which can be found at the bottom of the "Settings/General/About" page. See Apple's instructions here. After using Safari to install the certificate, you can use Web Access in any browser on iOS.

Warning

The above steps for iOS are very insecure and are not recommended for production systems. iOS does not have a mechanism for ignoring bad certificates for a single site. This means that following the method above will result in that your device considers the certificate as a generally trusted authority. This can in turn allow whoever has access to that certificate's private key to generate a certificate that falsely appears valid for any site. For example, an evil website could appear to have a valid certificate for your bank.

8.6.3.1.2.  Configuration

tlwebaccess offers a number of configuration options, which are stored in the configuration file /opt/thinlinc/etc/conf.d/webaccess.hconf. The various configuration options are described below.

/webaccess/cert

The path to the certificate file to be used for TLS encryption.

Note

This certificate may be downloaded by connecting clients to be installed in their browsers. Make absolutely sure that this file does not contain a private key.

/webaccess/certkey

The path to the certificate private key file used for TLS encryption.

/webaccess/login_page

The URL which is used to redirect back to the Web Access login page on the master server. The client first authenticates with the master. Once the master server has chosen an agent server for the session, the client will authenticate with that agent server. The browser will thus present pages from two different servers. First a page from the master, and then from the agent, unless the agent is on the same server of course. This parameter is a means for the agent to know the public hostname of the master server. Thus when it's properly set, the user can, when the session has ended, click a button to return from the agent to the master to login again. The default value, which is /, will not redirect to another server and is only usable if you are running a stand alone ThinLinc server, i.e. not a cluster. If you have more than one server or are using Network Address Translation (NAT), you must set this parameter to an address that all clients can connect to. Example:

login_page = https://thinlinc-master.example.com:300/

/webaccess/listen_port

The local port for this service to listen on. The default port used is 300.

/webaccess/gnutls_priority

The GnuTLS priority string is used to select the order and availability of TLS versions, ciphers, key exchange, MAC, compression, signature and elliptic curve algorithms for TLS sessions. See Appendix E, GnuTLS priority strings for possible values.

/webaccess/logging/logfile

The file to use for logging tlwebaccess messages. By default, this is /var/log/tlwebaccess.log.

8.6.3.2.  Browser Side

ThinLinc Web Access is accessed with your web browser by browsing to the master machine, for example https://thinlinc-master.example.com:300. If you have configured the service to run on port 443, ":300" can be omitted.

Note

On iOS and Android devices, you can add an icon to the home screen. When the ThinLinc Web Access is launched from the home screen, it will run in full screen mode.