# Launching the client from a web page

This feature allows a web server, such as an intranet or a web portal, to initiate a ThinLinc client connection with a given configuration on behalf of a user.

## Requirements

Web Integration requires an Apache HTTP Server, configured for TLS, with the ability to run CGI scripts.

Note

Some Linux distributions distributes their Apache HTTP Server with the mod_cgi module disabled. This module is required for Web Integration to work. On Ubuntu systems, it can be enabled by running the a2enmod cgi command and restarting the httpd service.

Note

If Web Integration is used over HTTP, an attacker with access to the network may be able to intercept user passwords. To protect from this happening, Web Integration automatically redirects to a HTTPS connection when HTTP is used.

## Installation

The Web Integration feature is not enabled by default in a ThinLinc installation. An installation script, `/opt/thinlinc/share/web_integration/install-web-integration`, is provided for ease of installation.

    $ sudo /opt/thinlinc/share/web_integration/install-web-integration

Note

After installing the Apache HTTP configuration file, make sure to restart the httpd service to load the new configuration.

While the installation script works as-is on most supported platforms, two environment variables grants you more control over where the configuration file is installed. This can be useful if you have httpd installed at a custom location.

APACHE_CONF_DIR

  If your Apache HTTP Server has been installed to a non-standard location, set this environment variable to tell the installation script where the configuration directory is located.

  If this parameter is unset, the installation script will attempt to find the configuration directory from a list of known locations.

      $ sudo env APACHE_CONF_DIR=/usr/local/etc/httpd/conf.d \
          /opt/thinlinc/share/web_integration/install-web-integration

APACHE_CONF_NAME

  The default behavior of the installation script is to install the configuration file in the configuration directory with the name `thinlinc.conf`. If you already have a file with that name in the configuration directory that you wish to keep, set this environment variable to a different name.

      $ sudo env APACHE_CONF_NAME=web-integration.conf \
          /opt/thinlinc/share/web_integration/install-web-integration

## Usage

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 receives 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 username, 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.

## 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 username. 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 a 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.