====== Introduction ======

X2Go's HTML client makes use of HTML5, JavaScript, and WebSockets to provide graphical access to a remote host with no client-side requirements other than a modern browser. The x2gohtmlclient package, served by a web server, provides the JavaScript front-end. X2gohtmlclient works with the x2gowebrpc and x2gowswrapper packages, which run on the server. Aside from the aforementioned X2Go packages, the server-side requirements include
  * a web server,
  * minify,
  * Qt 5 and Qt 5 X11 Extras,
  * the CGI, JSON, Encode, Expect, and File::Touch Perl modules, and
  * python-websockify.
X2Go provides instructions for configuring the NGINX web server, but you can substitute another server if you prefer. Your operating system distribution likely provides packages containing the dependencies not provided by X2Go.

{{:wiki:advanced:kdr.png?400|}}

====== Components ======

===== x2gohtmlclient =====

Contains the JavaScript and other assets that are served to a browser. The main page is ''index.html'', and it provides two modes: a native client and an embedded client. The native client requires that a recent version of the X2Go client exists on the same computer as the browser. The embedded client provides the HTML5-based functionality. In any case, ''index.html'' prompts the user for:
  * the X2Go server address,
  * a username,
  * a password,
  * the desktop environment to start,
  * whether to use an SSH proxy,
  * an optional proxy username, and
  * an optional proxy password.

{{:wiki:advanced:client.png?400|}}

''index.html'' can be edited to set a default server and so on.
The file ''x2gokdriveclient.html'' allows for running the X2Go client in a separate window.

The x2gohtmlclient package also provides CSS, images, and three JavaScript classes:
  -   ''x2godomcontroller.js'', which handles communication between the HTML page and the X2Go HTML client;
  -   ''x2gohtmlclient.js'', which handles communication between the X2Go RPC script and the X2Go HTML client; and
  -   ''x2gokdrivehtmlclient.js'', which implements the X2Go KDrive client.

===== x2gowebrpc =====

The x2gorpc.cgi CGI script connects to the X2Go server using SSH and starts sessions, resumes sessions, starts SSH tunnels and so on in response to requests from the browser. This involves using SSH to run ''x2golistsessions'', run ''x2gostartagent'', start a tunnel using SSH's ''-N'' and ''-L'' arguments, run ''x2goruncommand'', and run ''x2gowswrapper''.

===== x2gowswrapper =====

The x2gowswrapper program connects the TCP sockets of the X2Go KDrive agent with WebSockets created by the browser.

====== Configuring the Web Server ======

We describe how to configure NGINX and fcgiwrap, but you can substitute any web server that provides the needed features.
Here is an example NGINX configuration:
<file>
server {
  listen 443 ssl;
  server_name your_host;
  ssl_certificate "/etc/pki/nginx/server.crt";
  ssl_certificate_key "/etc/pki/nginx/private/server.key";
  ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
  ssl_protocols TLSv1.2;
  ssl_prefer_server_ciphers off;
  ssl_session_timeout 5m;
  ssl_session_cache builtin:1000  shared:SSL:10m;
  ssl_session_tickets off;
  root /var/www/html;
  proxy_read_timeout 300;

  location /assets/ {
    add_header Strict-Transport-Security "max-age=31536000";
    add_header Content-Security-Policy "default-src 'self' 'unsafe-inline' data: blob: ws: wss:; script-src 'self' 'unsafe-inline'";
    add_header Feature-Policy "vibrate 'none' ; microphone 'none' ; camera 'none' ; gyroscope 'none' ; magnetometer 'none' ; geolocation 'none' ; midi 'self' ; notifications 'self' ; push 'self' ; sync-xhr 'self'";
    add_header Referrer-Policy "same-origin";
    add_header X-Content-Type-Options "nosniff";
    add_header X-Frame-Options "SAMEORIGIN";
  }

  location ~* \.(pl|cgi)$ {
    gzip off;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass  unix:/var/run/fcgiwrap.socket;
  }

  location ~ ^/x2gows/(.*)$ {
    proxy_pass       https://127.0.0.1:$1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_http_version 1.1;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_intercept_errors on;
    proxy_redirect off;
    proxy_cache_bypass $http_upgrade;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-NginX-Proxy true;
    proxy_ssl_session_reuse off;
  }
}
</file>
Note that the location ''/x2gows/PORT'' gets proxied to a process on localhost listening to PORT. The is the x2gowswrapper process.

====== Building and Installing ======

===== x2gohtmlclient =====

Run ''./minify.sh'' to combine x2gohtmlclient's JavaScript classes and remove the whitespace from the result.
The output will be ''dist/x2gokdriveclient.min.js'', and you should copy this file to ''$WEBROOT/assets/js/''.

The other assets should be installed as follows. Create the parent directories as required.
  * Place ''index.html'' in ''$WEBROOT/''.
  * Place ''css/*'' in ''$WEBROOT/assets/css/''.
  * Place ''img/*/*/*'' in ''$WEBROOT/assets/img/''.

===== x2gowebrpc =====

Copy ''x2gorpc.cgi'' to ''$WEBROOT/assets/rpc/''.

===== x2gowswrapper =====

Build x2gowswrapper using qmake:
<code>
$ qmake-qt5 && make
</code>
Install the resulting program named x2gowswrapper to ''/usr/sbin/''.

Create the directory ''/var/log/x2gows'', and ensure the web server's user can create and modify files therein.

Create the file named ''/etc/x2go/x2gows/x2gows.options'' that contains the following:
<code>
ws_proto=wss
ssl_cert=/etc/pki/nginx/server.crt
ssl_key=/etc/pki/nginx/private/server.key
ssl_only=true
log_dir=/var/log/x2gows
</code>
Ensure the values of ''ssl_cert'' and ''ssl_key'' match the corresponding values in NGINX's configuration,
and ensure the user running NGINX can read the files at both paths as well as the configuration file itself.

===== proof of concept installation on Debian GNU/Linux =====

<code>
sudo apt install extrepo
sudo extrepo enable x2go
sudo apt update
sudo apt install x2gohtmlclient
</code>

===== proof of concept installation on Ubuntu GNU/Linux from Launchpad PPA =====

<code>
sudo add-apt-repository ppa:x2go/nightly
sudo add-apt-repository ppa:x2go/ppa
sudo apt update
sudo apt install x2gohtmlclient
</code>