Introduction

FastX is highly configurable out of the box.  Administrators who wish to fine tune their installations to add extra functionality should read this document.  Integration is a general term for features related to customizing FastX in such a manner that it can be combined with other functionality in your infrastructure.  This can be simple features like changing the look and feel with themes, to complex customizations using the API to build custom clients that extend the use of your current website.

Themes

Theme support allows users to customize the look and feel of the FastX website.  The user interface makes it easy to change the basic colors and add logos to the new theme.  More savvy administrators can fine tune the theme to their liking.  FastX is built using Bootstrap 4 and Sass to create themes.  Users can change colors, tag lines, images and just about any other component of the website to make a more consistent look and feel across your infrastructure.

Click on Customize > Themes

Setting the Theme

Highlight the theme you want to use. Click the Use Theme button

Website Settings

Administrators may wish to customize the website to better integrate into their current websites.  There are several website settings that can be changed to help this.

Click on System > Web  > Website Settings

Website

Administrators may wish to customize where users land when they connect to the FastX website.  

Homepage

Sets the default home page of the website when you first log in and when you click on the home page button in the top left corner of the page.

Autoconnect to Bookmark

Administrators may want their users to go directly to a Shortcut Session after logging in.  Set the bookmark that the user should connect to.  Note, users can disable this in their own profiles.

Default Login Page

Administrators who have enabled OpenID Connect functionality should have their users route to the OpenID Connect Login Page when initially connecting.  This way they can have single sign on functionality.  This does not stop a user from going to the other url if the user knows where the other login page is.

Setting the Welcome Page

If the Welcome Page text is not blank, it will display this page when the user first connects to the FastX web server.  This is a custom HTML page that the administrator can use to give, users information (or warnings to leave if unauthorized).  After the user has seen this page, a session cookie will be set meaning it only appears once until the web page is closed from the browser.

Custom Error Pages

Administrators can add custom 403, 404, and 500, HTML error pages that will be shown to the user if that HTTP error is thrown, further integrating FastX into a current website.

Notifications

Users can set notThe notification feed is in XML/ATOM feed format.  You can access it in the following locations

Formatted Feed

https://server.example:3300/notifications.html
This feed has basic XSL formatting

XML Feed

https://server.example:3300/notifications

This feed is the pure XML version that integrators can use

Public Feeds

Notifications that were marked as public do not need a login to view.

https://server.example:3300/notifications?public=true

Query Parameters
public: boolean —  Filter out private messages.  Admins can use this for the public feed
limit: int — limit the number of entries
offset: int — number of entries to offset (used for pagination)

Running FastX through an nginx proxy

If you plan to run FastX through an nginx proxy you should set the following

setsebool -P httpd_can_network_connect 1 proxy_buffering: off

Single Sign On

FastX supports single sign on for systems that support OpenID Connect.  Administrators set up the OpenID Connect relays in 

Users > OpenID Connect

This allows users to gain access without adding their ssh login credentials.  However, when a user intends to start a session, the SSH login credentials will then be needed unless administrators have set up Sudo Link Authentication

Proxy Authentication

For administrators who wish to use their own authentication schemes, proxy authentication is available.  Proxy authentication allows admins to create their own JSON web tokens based off of a shared secret that will be honored like a JWT created by the web server.  This simplifies accessing the API as a user no longer needs to log in to create a JWT. Administrators set up the Proxy by going to the System Configuration.

Users > Proxy

For more information see Logins

Job Scheduling

FastX can be configured to use a third party job scheduler (LSF, MOAB, SLURM etc) to execute commands and then launch a FastX session when the job has been completed sending the DISPLAY back to FastX.

Instead of returning immediately, FastX will return output that can be shown to the user.  Then when the job has completed, the FastX session will show up in the session browser window.

A deeper explanation of job scheduling can be found here

Custom Forms

Custom Forms allow administrators to get extra data from a user when starting a session.  This allows users to better integrate with Load Balancing and Job Scheduling.  Administrators can setup Forms by going to the System Configuration.

Sessions > Forms

For more information see Starting Sessions.

Session Events

A session event is a general term for when an action happens on a session.  Session events can be divided into several categories.  Each category has its own way of handling the event but the result is the same.  Administrators can set up Session Events to execute custom code to better integrate other products into FastX.

API Events

API events are scripts that are executed before FastX makes the API call to the session.  This enables administrators to restrict commands, deny methods to users, or do any other informative task that they wish.  These events are executed as the FastX web server user.

API events are found in Sessions > Events 

API events can be set on any event that the administrator chooses.  

Event Function

async function (o) {     //modify the input object before the api call is processed     //Your script should return the input object (o)     //throwing an error will cause the API call to fail     //use this if you want to prevent APIs from being executed     //throw new Error (‘API is disabled’);     return o; //successfully return input object and API can continue }

Input Object

{   “action”: ‘session/connect’, /* The API Event being called */   “login”: username, /* User’s username */   “token”: API_TOKEN, /* User’s API TOKEN */   “session”: SESSION_OBJECT, /* Session object (if not start/schedule)   “data”: API_DATA, /* Data sent to the API call */ }

Return Object

The object returned should be in the same format of the input object.  You can change the data object as needed.  This new data object will be used as the API data that will be sent to the server.

Throwing Errors

The API call will fail if an error object is thrown in the API Event.  This has the effect of disabling the call for certain users.  If you want to generally disable an API call across a cluster, you should use FastX Permissions.

Update Events

The FastX Session periodically updates the FastX web server when new data is available.  Administrators who want to execute an event on an update like this should use the update event.  This event will be executed as the FastX web server process owner.

Update Event Function

The update event function is a javascript function for executing event actions.

function(oldSession,newSession) {   if(!oldSession) {     //Session Started   } else if(newSession.terminated) {     //session has terminated   }else if(newSession.clientCount > oldSession.clientCount) {     //client connected   } else if(newSession.clientCount < oldSession.clientCount) {     //client disconnected     if(newSession.clientCount === 0) {       //all users disconnected     }   } }

Input Objects

oldSession is the session data that is currently in the database.  If this is a new session (session started) this is null

newSession is the new session data that has just been updated by the FastX session

Return Value

The return value is not used.

Profile Scripts

If a FastX session is started with a profile that has “Event Scripts” specified, those scripts will be run as the same user who is running the session. The various events are triggered when the following events happen:

• ‘start’: Triggered soon after the session starts.
• ‘connect’: Triggered when a connection is made to the session. [To be slightly modified when we implement sharing.]
• ‘disconnect’: Triggered when the connection to the session is disconnected.
• ‘params’: Triggered when the params of a session (such as the name) are changed.
• ‘terminate’: Triggered when a session is terminated.

With the exception of ‘terminate’, the scripts that are triggered run in the background. This means that if the script is long-running,  the session may terminate while the script is still running. In the case of ‘terminate’, the session monitor will not exit, and thus the session directory will not be removed, until the terminate script exits.

One Liners

If the script specified is a single line (after removing blank lines at the start and end), it will be run under the shell. This means that special characters, such as file pattern matching, environment variable expansion, and file redirection, will all work.

Script Files

If the script is multiple lines, then the entire script is put into a script file, which is executed when the trigger happens. This means that any multiple line event script should start with an interpreter, e.g. !/bin/bash.

Environment Variables

The following environment variables will be set for an event script:

$DISPLAY, $XAUTHORITY, $FASTX_SESSION_ID, $FASTX_SESSION_DIR, as well as the usual ones (HOME, USER, etc.)

This means that the event script could run an X11 application, such as xmessage or xwininfo.

Custom Channels

FastX 3.1 implements the ClientComm channel which lets custom channels to flow from client to server and vice versa.  The ClientComm channel is documented in ClientComm.

FastX API

The FastX API is a fully documented REST API that allows users to execute commands .  See FastX API for the list of commands.

Making Requests

A typical API session consists of the following:

• Getting an API Web Token (ie logging in)
• Executing API Commands
• Logging Out

CURL Example

curl --insecure -X POST -H "Content-Type: application/json"  -d "{ \"username\": \"myuser\", \"password\": \"mypassword\", \"basic\": true }" https://pc130.starnet.com:3300/v3/api/auth/ssh

Explanation

curl

--insecure : ignore SSL errors

-X POST : send as a post request

-H "Content-Type: application/json"  : post the data as JSON

-d "{ \"username\": \"myuser\", \"password\": \"mypassword\", \"basic\": true }" . :  post data in json format

https://pc130.starnet.com:3300/v3/api/auth/ssh  : the api url

FastX CLI

The FastX server comes with a command line client that allows users to execute api calls to the web server.

Basic Usage

The Command Line client will automatically log the user in locally and generate a FastX  Authorization Token.  This simplifies the setup

Command Line Parameter Format

/usr/lib/fastx/3/tools/fastx-cli [api_method] –arg1=arg1 –arg2=arg2 …

• api_method — The API method as described in FastX 3 API
• arg1 – argN — The parameters of the API method

JSON Format

/usr/lib/fastx/3/tools/fastx-cli [api_method] –json='{ JSON_OBJECT }’

• api_method — The API method as described in FastX 3 API
• json — The parameters of the API method as a JSON string

Advanced Usage

Generating a token

/usr/lib/fastx/3/tools/fastx-cli token create

This will generate a token to be used at a later time.  The basic version automatically does this for you when executing the api call

Shutting down the link daemon

/usr/lib/fastx/3/tools/fastx-cli shutdown

FastX runs a daemon called link in order to start new sessions.  Shutting this down will force a user to re-authenticate when launching a new session. Other API calls such as listing sessions and performing actions on  running sessions are not affected by this command.

Integrating FastX Into Other Websites

Integrators who want to add FastX into their own web site should do the following

• Create an iframe connecting to the client
• Use the FastX API to make a connect call.
• Take the “result” object of the Connect call and BASE 64 encode the object
• Add it to the fragment #BASE_64

The resulting iframe should look like this

<iframe src=”https://server.example.com:3300/client/custom#BASE_64_RES” style=”width:100%;height:100%” ></iframe>

/client/custom

Note that unlike a typical connection, when integrating the url is /client/custom. This url is designed specifically for integrators.

• It does not check to see if the user is logged in
• It does not issue any API calls when connecting
• It gets all API data from the fragment #BASE_64

Sending/Receiving Messages From FastX

if you wish to send or receive messages from the FastX iframe you can add the following script to your HTML page header.

<script src=’https://fastx.example.com:3300/tools/client-api.js’></script>

This script will create the FastX class to your global namespace.  Add the following line in your HTML.  You can then access the API like this.

<script>     var myIframe = document.getElementById(‘fastxIframe’);     var fx = new FastX(myIframe);     fx.onready = function(e) {          //Add your ready code here. e.g.         //fx.resize(window.innerWidth, window.innerHeight)     } </script>

Api Callbacks

onmessage(e)

Emitted when any message gets sent.

onready(e)

Emitted when the protocol has finished its initial setup.

Api Commands

send(msg: string, body: object)

Generic function that will send arbitrary messages to the iframe. Typically not used

resize(width: number, height: number)

Send a resize request

keyboard(layout: number, type: number)

Change the keyboard layout. Refer to https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-language-pack-default-values for valid keyboard layouts

networkAutodetect(enabled: boolean)

Enable network autodetection

compression(current: number, min: number, max: number)

Set compression level (lower is blurrier)

frameRate(current: number, min: number, max: number)

Set the frame rate

frameWindow(current: number, min: number, max: number)

Set the number of interim frames before the server stops sending data

scaling(current: number, autoscale: boolean min: number, max: number)

Set the client side scaling. Autoscale lets the client determine it for you

mouseDown(flags: number, pos: Array<number:number>)

Send a mouse down event. Refer to https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons for flags. pos is an array of [x,y]

mouseUp(flags, pos)

Send a mouse up event. Refer to https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons for flags. pos is an array of [x,y]

mouseMove(pos)

Send a mouse move event. pos is an array of [x,y]

mouseWheel(delta, pos)

Send a mouse wheel. Negative delta is scroll up pos is an array of [x,y]

keyDown(code)

Send a keyboard down event. Refer to the code strings at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values for a list of code values

keyUp(code)

Send a keyboard up event. Refer to the code strings at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values for a list of code values

keyPress(code)

Shortcut for

fx.keyDown(code);

fx.keyUp(code);

Additional Integrations

The FastX browser client shows its own menus and dialog boxes.  Integrators may wish to disable part or all of these features and handle them in their own code for a better look and feel

Hide Client Menu

System > Customization > Client Settings > Hide Client Menu will hide the menu bar in the middle of the running FastX session.  Integrators can post messages to the FastX iframe to enable the events in the menus (eg. change geometry)

Hide All Dialogs

System > Customization > Client Settings > Hide All Dialogs will prevent any modal dialogs (typically a disconnect error) from appearing.  These events are still propagated up to the iframe’s parent where the integrator can handle the event using his own error handling system.

Stop Message Propagation to iframe parent window

By default, all protocol events are propagated to the parent window of the iframe.  System > Customization > Client Settings > Stop Message Propagation to iframe parent window turns event propagation off so the parent window will not receive any messages

Hide Home button in menu

The client menu has a Home button that will link to the FastX Session Configuration portion of FastX.  Integrators of FastX may not want that button. System > Customization > Client Settings > Hide Home button in menu will hide this button

Home button opens in the same window

System > Customization > Client Settings > Home button opens in the same window decides when clicking the Home button, open in the same window (which would effectively disconnect the session) or open in a new window

Url of the home button

System > Customization > Client Settings > Url of the home button is the uri that the home button will link to.  Integrators may wish to keep the home button, but have it link to some other “home” page, like the base page of their product.