User Tools

Site Tools


wiki:advanced:x2gohtmlclient

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.

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.

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:

  1. x2godomcontroller.js, which handles communication between the HTML page and the X2Go HTML client;
  2. x2gohtmlclient.js, which handles communication between the X2Go RPC script and the X2Go HTML client; and
  3. 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:

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;
  }
}

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:

$ qmake-qt5 && make

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:

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

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.

wiki/advanced/x2gohtmlclient.txt · Last modified: 2022/01/02 18:56 by mikep