Advanced Configuration: Weblinks

Background

Weblinks are special connections where the FastX Session is not running on that same server as a FastX Server. This is typically achieved when an admin creates a custom launcher script and launches a session on a system with FastX installed, but it is not part of a FastX cluster.

Why do this?

A typical FastX cluster can handle 300-500 instances of FastX before the load gets too large and synchronization slows down the transporter.

Administrators who have load balancers (lsf, slurm etc) may find it more efficient to simply add a small proxy to the Compute Node and isolate the FastX Servers on the Head Nodes. This saves resources and speeds up the load balancing since FastX Servers only need to be clustered on the Head Nodes.

Sessions that use the weblink proxy get the nodeID of the FastX server it connects to, and the configuration is transparent to the user. This allows for greater flexibility and scaling of FastX clusters.

All connections are initiated from the weblink proxy meaning the Compute Node can be on a system behind a firewall and the FastX Server can be on the other side adding to security

Enabling Weblinks

FastX Server

To enable the FastX Server to listen for weblinks add the WEBLINK_PORT variable to fastx.env (or the environment) and restart FastX

Setup

# add to fastx.env or as an environment variable
# By convention, port 3320 is the weblink port, but it can be anything
WEBLINK_PORT=3320

Add the security configuration in $FX_CONFIG_DIR/weblink-auth.ini

Weblink Proxy

The weblink proxy sits on the same Compute Nodes as your FastX Sessions. The weblink proxy is included with the FastX installation.

Setup

  1. Install FastX on the Compute Node
  2. Disable the FastX service(s)
    • sudo systemctl disable fastx4
    • sudo systemctl disable rlm
    • sudo systemctl disable fastx-ssh
  3. Add the proxy configuration in $FX_CONFIG_DIR/weblink.ini
  4. Add the security configuration in $FX_CONFIG_DIR/weblink-secret.ini
  5. start the weblink proxy as the fastx user
    • sudo -u fastx npm start --prefix /usr/lib/fastx/4/www/scripts/weblink-proxy-server

Launching Sessions on a Proxy

Sessions are launched on the command line using the /usr/lib/fastx/4/scripts/start command. In practice this is done by a launcher script that the admin has set up on the FastX Server.

Both the proxy and the session must have the same $FX_LOCAL_DIR. Otherwise the session will never connect to the proxy

$FX_CONFIG_DIR/weblink-secret.ini

The weblink-secret.ini file contains the secret information for authenticating weblink clients to the FastX Server. You can set the location using the environment variable WEBLINK_SECRET_FILE

If weblink-secret.ini is missing, then the weblink server will disable all security

For the FastX Server, the only setting needed is the key to create a secret shared key the weblink proxy and FastX Server can use to create json webtokens for authentication

## IMPORTANT!!!: This file contains sensitive information.  Make sure it is 
## only readable by the fastx user (chmod 600 fastx.fastx weblink-auth.ini)
# authentication type "none" | "jwt" (default jwt)
type=jwt

# client issuer id. 
# environment variable WEBLINK_CLIENT_ISSUER will override this
clientIssuer=

# shared secret for jwt shared secret authentication
secret=

# inline public key the server will use for jwt public key authentication 
publicKey=

# public key file location the server will use for jwt public key authentication 
publicKeyFile=

# private key file for weblink client 
privateKeyFile=

# algorithm used to sign the jwt 
# see: https://github.com/auth0/node-jsonwebtoken
algorithm=

# In order to individually authenticate different clients, 
#you can set up specific issuers with matching clientIds
## [issuers.clientIssuerId]
## secret=
## publicKey=
## publicKeyFile=

$FX_CONFIG_DIR/weblink.ini

This file only needs to be configured on the Weblink Proxy. The FastX Server will ignore this file

The weblink.ini file contains the information the weblink proxy needs to connect to the FastX Server. Set the URL to the FastX Server. Change the URL port to the WEBLINK_PORT that was configured on the server

# url to connect to 
url = "ws://localhost:3320" 

# uri to append to the url 
# uri ="/weblink"

# require valid TLS certificates on the FastX Web Server
rejectUnauthorized = false