FastX API

Contents

Introduction

FastX API is a web based REST api.  You can send your request either by GET or POST.

Authorization Token

Unless otherwise specified, you must send a X-FASTX-TOKEN authorization token with each request.  This is the JSONWEBTOKEN that you receive when logging in.  There are several ways to add the authorization token.  The preferred method is to add it in the HTTP HEADER as X-FASTX-TOKEN as it is most secure

HTTP HEADER

X-FASTX-TOKEN

GET/POST

token

Error Object

Unless noted, the API error object has the following format

{
    error: {
      "name": "ErrorName",
      "message": "The display error message",
      "stack": "Optional stack trace"
   }
}

General

/v3/api

Get configuration information.  This information does not require a X-FASTX-TOKEN

Parameters

None

Result

{
   "result": { 
       "build": "3.0.XXX",                    /* the version string */ 
   }
}

/v3/api/config

Auth

SSH

The SSH api call is a state machine that allows you to log in using various authentication methods.  The required parameters and results change depending on the state you are in.  All intermediate stages (not the initial “login” stage, or the final “success” stage ) return an authtoken . This authtoken is required to be sent with every request.  If you want to disable the SSH state machine, add the “basic” parameter to the login request.  Basic authentication will attempt to authenticate username and password only and will fail otherwise.

/v3/api/auth/ssh

Basic Authentication

FastX will attempt to authenticate with username and password only.  This disables the SSH state machine.  If the username/password fails, the api will return an error.

Parameters
{
   "username": "STRING_VALUE", /* <required> SSH username */
   "password": "STRING_VALUE", /* SSH Password */
   "basic": true /* Force username/password authentication only */
   "admin": false /* Attempt admin login (always logs in locally. Fails if user is not an admin) */
}
Result
{
   "result": {
      "stage": "success",  /* authentication stage */ 
      "token": "STRING_VALUE", /* connection token which is required during authentication */
}

SSH State Machine Stage: “login”

Parameters
{
   "username": "STRING_VALUE", /* <required> SSH username */
   "password": "STRING_VALUE", /* SSH Password */
   "admin": false,/* Attempt admin login (always logs in locally. Fails if user is not an admin)  */
   "usePK": false,             /* enable public-key authentication */
}
Result

JSON object.  The object contains different members depending on the authentication stage.  Authentication has not completed until the ‘success’ stage has been reached.

{
   "result": {
      "stage": "public-key" | "keyboard-interactive" | "password" | "success",  /* authentication stage */ 
      "authtoken": "STRING_VALUE",       /* connection token which is required during authentication */
      "prompt": "STRING_VALUE",      /* (stage keyboard-interactive only) text description of the prompt */
}

Stage: public-key

Next Step: Send the public key to the server

Stage: keyboard-interactive

Next Step: The prompts parameter contains an array of prompts that the user should make responses to.

Stage: password

Next Step: Password based authentication

Stage: success

User has successfully logged in and can now issue api commands

SSH State Machine Stage: “keyboard-interactive”

Parameters
{
   "authtoken": "STRING_VALUE", /* The authorization token */
   "answer": "STRING_VALUE" /* answer to the prompt */
}

Result

JSON object of the authentication stage. See /api/v3/auth/ssh

SSH State Machine Stage: “password”

Answer the prompt of the password stag

Parameters
{
   "authtoken": "STRING_VALUE", /* The authorization token */
   "password": "STRING_VALUE" /* SSH Password */
}
Result

JSON object of the authentication stage. See /api/v3/auth/ssh

SSH State Machine Stage: “public-key”

Send the public key to the server during authentication

Parameters
{
   "authtoken": "STRING_VALUE", /* The authorization token */
   "publicKey": "STRING_VALUE" /* Base64 encoded public key of the SSH key */
}

The format of the Public Key is as follows

4 bytes – unsigned int: length X of string to come
X bytes – string: this will be ‘ssh-rsa’ (7 chars)
4 bytes – unsigned int: length Y of byte array
Y bytes – bigint of ‘e’
4 bytes – unsigned int: length Z of byte array
Z bytes – bigint of ‘n’

Result

JSON object of the authentication stage. See /api/v3/auth/ssh/login

SSH State Machine Stage: “sign”

Sign the data and send to the server during authentication

Parameters

{
   "authtoken": "STRING_VALUE", /* The authorization token */
   "signature": "STRING_VALUE" /* Base64 encoded signed data */
}

Result

JSON object of the authentication stage. See /api/v3/auth/ssh

User

/v3/api/user/profile

Get the user’s profile

Parameters

None

Result

{
    "result": {
       "token": "STRING_VALUE",                       /* User's authentication token */
       "login": "STRING_VALUE",                       /* User's username */
       "hostname": "STRING_VALUE",                    /* Hostname where the user is logged in */
       "provider": "ssh" | "okta" | "link",           /* authentication method used to log in */
       "authenticated": true,                         /* User has authenticated to the server and can send messages */
       "loggedIn": true,                              /* Server has responded back completing the authentication process */
       "groups": ["group1", "group2", ..., "groupN"], /* Array of Linux groups associated with the username */
       "email": "STRING_VALUE",                       /* Email address (if found) */
       "firstName": "STRING_VALUE",                   /* User's first name */
       "lastName": "STRING_VALUE",                    /* User's last name */
    }
}

/v3/api/user/logout

Logs user out and deletes the token

Parameters

None

Result

{
  "result": null
}

/v3/api/user/shutdown

Shuts down the link process of the user.  Users cannot start new sessions without a link process running.

Parameters

None

Result

{
  "result": "Goodbye"
}

/v3/api/user/keepalive

Sends a keepalive call to keep the user session open

Parameters

None

Result

{
   "result": {
      "status": "STRING_VALUE",  /* [OPTIONAL] Status message from the link process */
      "token": "STRING_VALUE" /* The token. This token may be different than the original and revokes the old one */
   }
}

Session

/v3/api/session/start

Start a new session

Alias: /v3/api/session/start/start

Parameters

{
   "command": "STRING_VALUE", /* <required> Command to execute */
   "geometry": "1024x768" | "rootless",    /* geometry of the session */
   "id": "STRING_VALUE",      /* specify the id of the session */
   "name": "STRING_VALUE"     /* Set the name parameter */
   "keyboardLayout": INTEGER,   /* (default 0x0000409 -- US English) default keyboard layout on startup. See Keyboard Note */
   "params: {                 /* user defined parameters */
       "key1": "value1",
       "key2": "value2",
       ...
    },
    "schedule": true, /* Upgrade start command to allow a job scheduler to run */
    "auth": SSH_OBJECT /* Upgrade start command to log in via SSH first */
}

Keyboard Note

FastX can change the keyboard layout on the fly during a running session.  However certain applications (notably GNOME Desktop) use the default keyboard when setting up their keyboard layouts, ignoring the FastX keyboard change in the protocol.  Set the layout to the default you prefer to use when starting a session.

Layouts are bases on the layouts in  Microsoft Keyboard Identifiers and Input Types.

 

 

Result

Default result

Connect Object.  See connect

If auth is set

The start command will first run through the SSH state machine.  Refer to the SSH state machine documentation.
on stage === ‘success’ the connect object is returned

If schedule is set

If schedule is set, then the client is aware of job schedule result.  It is up to the server to determine if this application will be scheduled or start immediately.
The result can be any of the previous results (connect, or SSH results).

If stage === ‘schedule’ the following result object is returned

{
   "stage": "schedule", /* the command has been scheduled */
   "code": 0, /* exit code */
   "output": [{ "line": 
          "output_line_1", "type": "stdout | stderr | system", "eof": false}, 
            ...] /* Array of output objects that can be parsed and displayed to the user */
}

Error

The start error object has a custom error

{     
   "name" : "STRING_VALUE", /* Error name */     
   "message":"STRING_VALUE", /* Error message */      
   "data" : {         
      "log" : { 
         "server" : "(complete server output)", 
         "xorg" : "(complete text from xorg.log)" 
       }     
   } 
}

/v3/api/session/start/bookmark

Start a new session using a bookmark id

Parameters

{
   "id": "STRING_VALUE", /* <required> Bookmark id */
}

Result

Connect Object.  See connect

Error

See Start Error

/v3/api/session/connect

Reconnect to an existing session

 

Parameters

{
   "id": "STRING_VALUE" /* <required> Session Id */
   "params": {  /* user parameters to set */
       "key1": "value1",
       "key2": "value2",
       ...
   }
}

Result

{
   "result": {
      "stage" : "success", /* Final stage if using authenticated starts */
      "geometry": "1024x768",     /* geometry of the session */
      "id": "STRING_VALUE",       /* session id */
      "login": "STRING_VALUE",    /* username who started the session */
      "params": {                 /* user parameters that have been set */
           "key1": "value1",
           "key2": "value2",
       },
      "password": "STRING_VALUE", /* one-time password that will be used to connect to the session */
      "port": 40000,              /* local port the session is listening on */
      "windowMode": "rootless", | "desktop" /* window mode of the session */ 
      "uri": "STRING_VALUE", /* (Optional) URI of web session to connect to */  
      "urls": ["STRING_VALUE1", "STRING_VALUE2" ...], /* Array of websocket urls that can be used to connect to the session */
   }
}

/v3/api/session/disconnect

Disconnect all users from the session

Parameters

{
    "id": "STRING_VALUE" /* <required> Session Id */
}

Result

{
   "result": null
}

/v3/api/session/exec

Execute a command on the session.

Parameters

{ 
     "id": "STRING_VALUE", /* <required> Session Id */
     "command": "STRING_VALUE", /* <required> Command you with to execute */
     "stdin": "STRING_VALUE" | [STRING_VALUE] | JSON_Object, /* Standard In.  see note */
     "env": JSON_Object /* Key value pairs of environment variables to set when execing the command */

}

Standard In

If this is a string, then the string will be passed to the command on stdin. I terminating newline will not be appended. If this is an array of strings, then each string will be sent on stdin, with a newline appended after each. If this is an object, then it will be JSON-encoded, and sent on stdin. If not set, then /dev/null will be used for stdin

Result

{
   "result": {
      "code": 0, /* Linux exit code. the low 7 bits is the signal, and the upper 8 bits is the exit value */
      "output": [OUTPUT, OUTPUT, OUTPUT, ...], /* Array of OUTPUT Objects */
}

OUTPUT Object

{ 
   "type": "stderr" | "stdout" | "system", /* Output type */
   "line": "STRING_VALUE", /* Text of the line" */
   "no_eol": false, /* Did the line string terminate with a new line (Only for the final line) */
}

/v3/api/session/exec-bg

Execute a command on the session and put it in the background .

Parameters

{ 
     "id": "STRING_VALUE", /* <required> Session Id */
     "command": "STRING_VALUE", /* <required> Command you with to execute */
     "env": JSON_Object /* Key value pairs of environment variables to set when execing the command */

}

Result


{
 "result": {
     "PID": 1000, /* PID of the command running */
}

/v3/api/session/list

List the user’s currently running sessions

Parameters

{
   "start": 0.                                            /* Starting session object */
   "sortBy": "STRING_VALUE",                              /* member to sort by (it will also check members in “params”) */
   "sortReverse": false,                                  /* return session objects in reverse sort order */
   "limit": Infinity,                                     /* maximum number of session objects to return */
   "filter": ["FILTER_STRING_1", "FILTER_STRING_2", ...]  /* filter session objects */
}

FILTER_STRING is defined as follows  "name==value1,value2,valueN"

name -- the member name to filter on
value1,value2,valueN -- comma separated list of values which acts as an OR

You can have multiple filters which act as AND

Result

{
  "result": {
     "total_rows": 10, /* number of session objects total (not filtered) */
     "offset" : 0, /* Offset from start (for pagination)
     "rows": [ /* Array of Session Objects */
       {
         "appPid": 1234, /* Pid of the process started from command */
         "clients": 0, /* number of clients currently connected */
         "command": "STRING_VALUE", /* initial command execed when the session was launched */
         "connectTime": 30, /* number of seconds that there has been a user connected to the session */
         "cpuPercentage": 25, /* CPU Percentage parameter when the session was started */
         "disconnectTimeout": 0, /* disconnectTimeout parameter when the session was started */
         "display": ":100", /* DISPLAY number of the session */
         "geometry": "1024x768", /* widthxheight of the session */
         "hostname": "STRING_VALUE", /* hostname of the machine the session is running on */
         "id": "STRING_VALUE", /* Session Id */ 
         "lastConnect": "TIMESTAMP", /* timestamp when the session was connected to */
         "lastDisconnect": "TIMESTAMP", /* timestamp when the session was disconnected from */
         "login": "STRING_VALUE", /* name of the user who started the session */ 
         "params":{ /* user parameters that have been set */
             "key1": "value1",
             "key2": "value2"
             ...
         }
         "serverId": "STRING_VALUE", /* id of the FastX server running the session */
         "serverPid": 5678,      /* Pid of the session process */
         "sharing": true, /* Sharing parameter when the session was started */
         "started": "TIMESTAMP", /* timestamp when the session was started */
         "uptime": 46351273, /* Number of ms since the session was started */
         "videoRam": 128000, /* Video RAM parameter when the session was started */
         "windowMode": "rootless" | "desktop", /* window mode of the session */ 
         "terminated": { "message": "Terminate reason" }, /* Terminated Sessions only: the session has terminated */
         "ended": "TIMESTAMP", /* Terminated Sessions only:  the time the session terminated */
       }
     ]
  }

/v3/api/session/list-all-users

List the all the currently running sessions.  User must have admin rights to use this API call

Parameters

See session/list

Result

See session/list

/v3/api/session/list-terminated

List the all the sessions that have been terminated.  User must have admin rights to use this API call

Parameters

See session/list

Result

See session/list

/v3/api/session/log

View a session’s log file.  The corresponding log files are found in $HOME/.fastx_server/hostname/sessions/FX3-sessionid/

Parameters

{
   "id": "STRING_VALUE" /* <required> Session Id */
}

Result

{
   "result": {
      "monitor": "STRING_VALUE", /* text of the monitor.log */
      "server": "STRING_VALUE", /* text of the server.log */
      "stderr": "STRING_VALUE", /* text of stderr.log */
      "stdout": "STRING_VALUE", /* text of stdout.log */ 
      "xorg": "STRING_VALUE", /* text of xorg.log */ 
   }
}

/v3/api/session/params

Add custom parameters to the session

Parameters

{
   "id": "STRING_VALUE"     /* <required> Session Id */
   "params": {              /* key/value pairs of the parameters */
        "key1": "value1",
        "key2": "value2",
         ...
    }
}

Note: Set a key to an empty string "" to delete the parameter

Result

{
   "result": {            /* the user parameters */
       "key1": "value1",
       "key2": "value2",
       ...
   }
}

/v3/api/session/params-form/list

List the params forms

Parameters

None

Result

{
     "result": {
           "total_rows": 5, /* Number of rows */
           "offset": 0, /* Start offset */
           "rows": [FORM_OBJECT1, FORM_OBJECT2, ... FORM_OBJECTN], /* Form Objects */
     }
}

FORM_OBJECT

{
   "id": "STRING_VALUE", /* Form object ID */
   "data": {
      "html": "STRING_VALUE", /* Sanitized HTML form */
    }
}

/v3/api/session/purge

Delete the session from the database.  This DOES NOT terminate the session or interact with the actual running session in any way.   The session will be put back into the database if there is an update.  This option is useful in a cluster when a system has gone down and will not return, or the serverId of a system has changed.

Parameters

{
   "id": "STRING_VALUE"     /* <required> Session Id */
}

Result

{
   "result": true
}

/v3/api/session/servers/list

List the params forms

Parameters

None

Result

{
     "result": {
           "total_rows": 5, /* Number of rows */
           "offset": 0, /* Start offset */
           "rows": [SERVER_OBJECT1, SERVER_OBJECT2, ... SERVER_OBJECTN], /* Server Objects */
     }
}

SERVER_OBJECT

{
   "id": "STRING_VALUE", /* Server ID */
   "hostname":"STRING_VALUE", /* Hostname of the server */
}

/v3/api/session/screenshot

Take a screenshot of the running session

Parameters

{
   "id": "STRING_VALUE",      /* <required> session id */
   "width": 800,              /* screenshot width in pixels */
   "height": 600,             /* screenshot height in pixels */
   "format": “png” | “jpeg”,  /* Specify image format default “png” */
   "keep_aspect": 1 | 0       /* keep aspect ratio when reducing image size */
   "geometry": "widthxheight" /* specify the geometry in pixels (same as using width and height members) */
}

Result

{
   "result": {
       "src": "STRING_VALUE"  /* dataUrl of the image data */
   }
}

/v3/api/session/shortcut

Connect to a session which has the shortcut parameter or start a new session if no session exists

Parameters

{
    "id": "STRING_VALUE"  /* <required> Bookmark id to search for */
}

Result

Connect Object.  See connect

/v3/api/session/terminate

Terminate a session

Parameters

{
   "id": "STRING_VALUE" /* <required> Session Id */
}

Result

{
   "result": {
       "status": "STRING_VALUE", /* output of terminate attempt */
   }
}

/v3/api/session/bridge

Create a clustering bridge.  This is for internal use only and should not be used by an API Implementer

Parameters

{
    "id": "STRING_VALUE",  /* <required> Session Id */
    "url": "STRING_VALUE", /* <required> URL of where to create the bridge"
}

Result

{
   "result": {
      "bridge": "STRING_VALUE",/*  Bridge Id */
    }
}

Bookmark

/v3/api/bookmark/list

List the favorites, history, and suggestions (global bookmarks)

Parameters

None

Result

{
    "result": {
        "favorites": [BOOKMARK_ID_1, BOOKMARK_ID_2, ...], /* array of favorited bookmark ids */
        "system":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...],   /* array of global bookmarks */
        "user":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...],     /* array of user defined bookmarks */
        "history":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...],       /* array history */
    }
}

BOOKMARK_OBJECT is defined as follows

{
   "id": "STRING_VALUE",                    /* <required> bookmark id */
   "command": "STRING_VALUE",               /* <required> command to execute */
   "name": "STRING_VALUE",                  /* bookmark display name */
   "geometry": "widthxheight" | "rootless", /* geometry of the bookmark */
   "profile": "STRING_VALUE",               /* profile id to use */
   "tags": ["tag1","tag2", ..., "tagN"]     /* array of tag strings */ 
   "icon": "STRING_VALUE"                   /* icon to show (typically a dataURL)
}

/v3/api/bookmark/edit

Create or edit a user defined bookmark

Parameters

{
   "id": "STRING_VALUE",                    /* <required> bookmark id */
   "command": "STRING_VALUE",               /* <required> command to execute */
   "name": "STRING_VALUE",                  /* bookmark display name */
   "geometry": "widthxheight" | "rootless", /* geometry of the bookmark */
   "profile": "STRING_VALUE", /* profile id to use */
   "tags": ["tag1","tag2", ..., "tagN"]     /* array of tag strings */ 
   "icon": "STRING_VALUE"                   /* icon to show */
}

Result

See bookmark/list

/v3/api/bookmark/delete

Delete a user’s favorite or a history object

Parameters

{
   "id": "STRING_VALUE"   /* <required> bookmark id */
}

Result

See bookmark/list

/v3/api/bookmark/favorite

Add an existing bookmark to the user’s favorites list

Parameters

{
   "id": "STRING_VALUE"   /* <required> bookmark id */
}

Result

See bookmark/list

/v3/api/bookmark/unfavorite

Remove an existing bookmark from the user’s favorites list

Parameters

{
   "id": "STRING_VALUE"   /* <required> bookmark id */
}

Result

See bookmark/list

Shortcut

/v3/api/shortcut/list

List the user’s shortcuts.  Shortcuts extend the functionality of bookmarks by associating sessions with the bookmarks.  If a session is already running, the shortcut will reconnect to the running session.  If a session is not running it will launch a new session.

Parameters

{}

Result

{ "result": { 
    "total_rows": 10, /* number of shortcut objects total (not filtered) */ 
    "offset" : 0, /* Offset from start (for pagination) */
    "rows": [ /* Array of Shortcut Objects */
    }
}

A SHORTCUT OBJECT is defined as

{ 
  "id": "STRING_VALUE", /* <required> bookmark id */ 
  "command": "STRING_VALUE", /* <required> command to execute */ 
  "name": "STRING_VALUE", /* bookmark display name */ 
  "geometry": "widthxheight" | "rootless", /* geometry of the bookmark */ 
  "profile": "STRING_VALUE", /* profile id to use */ 
  "tags": ["tag1","tag2", ..., "tagN"] /* array of tag strings */ 
  "icon": "STRING_VALUE", /* icon to show (typically a dataURL) */
  "sessions: [sessionId1, sessionId2 ...] /* sessions launched from the bookmark */
}

<NOT YET IMPLEMENTED>Share

/v3/api/share/list

Get the sharing keys of the session

Parameters

{
    "id": "STRING_VALUE" /* <required> session id */
}

Result

{
    "result": [
       {
        "id": "STRING_VALUE",          /* session id */
        "key": "STRING_VALUE",         /* sharing key */
        "perms": ["viewer", "granter"],  /* array of permissions for the key */ 
        "timeout": 60,                 /* number of seconds a user has to connect with the share password */
      },
      ...
    ]
       
}

/v3/api/share/connect

Parameters

{
    "id": "STRING_VALUE", /* <required> session id */
    "key": "STRING_VALUE" /* <required> share key */ 
}

Result

connect object

/v3/api/share/edit

Edit a share key

Parameters

{ 
   "id": "STRING_VALUE",          /* <required> session id */
   "key": "STRING_VALUE"          /* <required> share key to edit */ 
   "perms": ["viewer","granter"],   /* <required> array of share permissions for the key */
}

Result

share/list object

/v3/api/share/email

/v3/api/share/delete

Delete a sharing key

Parameters

{
    "id": "STRING_VALUE", /* <required> session id */
    "key": "STRING_VALUE" /* <required> share key to delete */ 
}

Result

share/list object

/v3/api/share/reset

Delete the sharing keys of the session and disconnect all users

Parameters

{
    "id": "STRING_VALUE",          /* <required> session id */
    "perms": ["viewer", "granter"] /* Array of permissions.  Delete a sharing key that contains a permission in the array. 
                                      An empty array deletes all permissions. */ 
}

Result

share/list object

System

The system section is for API methods pertaining to the configuration.  You must be an admin to use these api calls.  Unless otherwise noted, configuration is stored in the web server database.

Admin

This section is for configuring the admins.

Changes to this section affect all members in a FastX Cluster

Database _id

config/user/admin

/v3/api/system/admin/load

Return the admin configuration

Parameters

{}

Result

{
   "result": {
       "users": ["admin1", "admin2", ...], /* Array of admin usernames */
    }
}

/v3/api/system/admin/save

Edit the admin configuration

Parameters

{
   "users": ["admin1", "admin2", ...], /* Array of admin usernames */
}

Result

{
   "result": true 
}

Assets

This section is for editing assets that can be uploaded to the FastX Cluster.

Changes to this section affect all members in a FastX Cluster

Uploading Assets

Assets are uploaded by sending a HTTP POST request to /assets/upload

/assets/upload

multipart-formdata

type : “public” | “private” | “system”

files[]: files to upload

/v3/api/system/assets/load

Return the assets

Parameters

{}

Result

{
    "result": {
        "public": {
            "total_rows": 5, /* Total number of public assets */
            "offset": 0, /* Starting row */
            "rows": [ ASSET_1, ASSET_2, ...], /* Array of ASSET OBJECTS */
         },
         "private": {
             "total_rows": 5, /* Total number of private assets */
              "offset": 0, /* Starting row */
              "rows": [ ASSET_1, ASSET_2, ...], /* Array of ASSET OBJECTS */
         },
        "system": {
              "total_rows": 5, /* Total number of system assets */
              "offset": 0, /* Starting row */
              "rows": [ ASSET_1, ASSET_2, ...], /* Array of ASSET OBJECTS */
         }
    }
}

Asset Object

{
    "id": "config/assets/private/myasset", /* asset ID */
    "data": {
       "name": "myasset.jpg", /* display name of the asset */
       "type": "public" | "private" | "system",     /* type of asset */
    }
}

Asset Types

The asset type determines who can access the asset

  • public — Available to everyone (logged in or not)
  • private — Only available to users who have logged in
  • system — Only available to admins

/v3/api/system/assets/remove

Delete an asset from storage

Parameters

{
  "id": "STRING_VALUE", /* Id of the asset */ 
}

Result

{
   "result": true
}

Auth-SSH

Configurations related to FastX’s SSH authorization

Changes to this section affect all members in a FastX Cluster

Database _id

config/auth/ssh

/v3/api/system/auth-ssh/load

Returns the SSH configuration

Parameters

{}

Result

{
  "result":{
     "disable": Boolean, /* Enable/disable SSH authentication */
     "disablePublicKeyAuthentication": Boolean,/* Enable/disable SSH Public Key authentication */
     "hideBackground": Boolean, /* Hide background image on web page */
     "hidePassword": Boolean, /* Hides Initial password field on web page so only username is visible */
     "passwordAuthenticationOnly": Boolean, /* Disables all SSH authentication methods except username/password */
     "theme": "light" | "dark" | "classic", /* Sets the web page theme */
  }
}

/v3/api/system/auth-ssh/save

Saves the SSH configuration

Parameters

See auth-ssh load result

Result

{
  "result": true
}

Bookmark

Configurations related to Creating and Editing System bookmarks

Changes to this section affect all members in a FastX Cluster

Database _id

Each bookmark is stored individually.  All bookmarks start with the following

config/session/bookmark/__bookmark_name__

/v3/api/system/bookmark/load

Returns the System Bookamarks

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of total System Bookmarks */
     "offset": 0, /* Starting Bookmark */
     "rows": [ BOOKMARK_1, BOOKMARK_2, ...], /* Array of BOOKMARK OBJECTS */
  }
}

Bookmark Object

{
  "id": "STRING_VALUE", /* Bookmark ID */
  "data": {
     "id": "STRING_VALUE", /* Bookmark ID.  Same as above */
     "command": STRING_VALUE", /* Command to execute */
     "icon": "STRING_VALUE", /* Icon to display */
     "name": "STRING_VALUE", /* Bookmark name */
     "profile": "STRING_VALUE", /* id of Profile that will be used when launching session */
     "tags": ["tag1", "tag2", ...], /* Array of tags */
  }
}

/v3/api/system/bookmark/save

Creates/Edits a bookmark

Parameters

See Bookmark Object.  If id is omitted, creates a new Bookmark

Result

{
  "result": true
}

/v3/api/system/bookmark/remove

Deletes a bookmark

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

Client

Configuration for connected sessions.  These configuration settings are typically used when creating custom clients and you want to better integrate FastX into your existing UI.  disableTokenValidation is used when you already have a password from a connect call and you want to forward that again.

Changes to this section affect all members in a FastX Cluster

Database _id

config/client

/v3/api/system/client/load

Returns the Client configuration

Parameters

{}

Result

{
  "result":{
     "disableMenu": Boolean, /* Hide the Menu */
     "disableModal": Boolean,/* Hide any Modal popups */
     "disableTokenValidation": Boolean, /* Do not verify the token on connection */
     "keyboardLayout": 1033, /* Default Keyboard layout if none currently exists on client */
     "keyboardType": 4, /* Default Keyboard type if none currently exists on client */
  }
}

/v3/api/system/client/save

Saves the Client configuration

Parameters

See client load result object

Result

{
  "result": true
}

DB

Database configuration.

Changes to this section affect THE CURRENT WEB SERVER ONLY

Changes to this section take effect when the web server is restarted

Changes are saved in /usr/lib/fastx/var/config/db.json

/v3/api/system/db/load

Returns the database configuration of the local system

Parameters

{}

Result

{
  "result":{}
}

/v3/api/system/db/save

Saves the database configuration of the local system.

Changes take effect when the web server restarts

Parameters

See client load result object

Result

{
  "result": true
}

/v3/api/system/db/info

Get Database information of local system.

Parameters

{}

Result

{
  "result": [DB_INFO_1, DB_INFO_2, ...], /* Array of Database info objects */
}

License

Configuration Options for managing licenses.

/v3/api/system/license/load

Returns the license files that are stored on Local system.  License files are located in /usr/lib/fastx/var/license

Parameters

{}

Result

{
  "result": [ LICENSE_1, LICENSE_2, ...] /* Array of License Objects */
}

License Object

{
   "filename": "STRING_VALUE", /* License file name */
}

/v3/api/system/license/save

Saves license data to a new file

Parameters

{
  "data": "STRING_VALUE", /* Contents of an RLM license file */
}

Result

{
  "result": true
}

/v3/api/system/license/remove

Deletes a license file

Parameters

{
  "id": "STRING_VALUE", /* filename located in the license directory */
}

Result

{
  "result": true
}

/v3/api/system/license/reread

Sends an rlmutil rlmreread call to the license server.  This may have the effect of sending license rereads to a different server depending on how your licenses are set up

Parameters

{
}

Result

{
  "result": {
     "success": true
  }
}

/v3/api/system/license/usage

Sends an rlmutil rlmreread call to the license server.  This may have the effect of sending license rereads to a different server depending on how your licenses are set up

Parameters

{
}

Result

{
  "result": {
     "licenses": [ USAGE_1, USAGE_2, ...] /* Array of License usage objects */
  }
}

License Usage Object

{
  "count": 10, /* Total licenses in license file */
  "inuse": 5, /* Number of licenses currently in use */
  "version": "2020.12", /* Version Maintenance string */
}

Profile

Configuration for creating an editing session profiles

Changes to this section affect all members in a FastX Cluster

Database _id

Each profile is stored as its own database entry.  The _id always begins with

config/session/profile/__profile_name__

/v3/api/system/profile/load

Returns the session profiles.

Parameters

{}

Result

{
  "result": {
     "total_rows": 10, /* Total number of profiles */
     "offset": 0, /* row offset */
     "rows": [ PROFILE_1, PROFILE_2, ...] /* Array of Profile Objects */
  }
}

Profile Object

The profile object sets the profile parameters of the FastX session.

If the FastX is not running, the FastX session will read the  /usr/lib/fastx/var/config/session.json file.

The /usr/lib/fastx/var/config/session.json file has the same format as the data section of the profile object

A special object with the id:”config/session/profile/default” is the DEFAULT profile.  Starting a session with no profile set will use the DEFAULT profile

{
  "id": "STRING_VALUE", /* Profile Id */
  "data": {
     "name": "STRING_VALUE", /* Display name */
     "description": "STRING_VALUE", /* Display description */ 
     "session": {
        "clipboard": true, /* Enable Clipboard support */
        "cpuPercentage" 50, /* Max CPU the FastX Compressor will use */
        "denyMethods: [ 'session methods' ], /* explicitly disable session methods */
        "disconnectTimeout": 0, /* Terminate session after N minutes disconnected. 0 disables timeout */
        "iglx": false, /* Enable indirect GLX for older openGL libraries */
        "licenseDiagnostics": false, /* log license diagnostics */
        "listenTCP": true, /* Enable X server to listen on a TCP port.  Also sets the $DISPLAY */
        "logLevel": 3, /* Set the logging for X server */
        "offlineSharing": false, /* Enable Offline sharing.  Master does not have to connected for users to log in */
        "sharing": false, /* Enable Session Sharing */
        "videoRam": 1280000, /* Maximum RAM for video buffer.  Higher numbers allow for larger max resolution */
      },
     "command": {
        "enableRestrictions": false, /* Enable Command restrictions.  Only valid restrictions can use this profile */
        "allowedCommands": [ "^regex1$", "^regex2$", ...], /* Array of regular expressions which are allowed"
      }
   }
}

/v3/api/system/profile/save

Create or edit a profile

Parameters

The Profile Object. Omitting the id will create a new profile

Result

{ 
  "result": true
}

/v3/api/system/license/remove

Deletes a profile.  If you delete the default profile it will reset it to the factory settings

Parameters

{
  "id": "STRING_VALUE", /* the profile id */
}

Result

{
  "result": true
}

Settings

Local Web Server settings

Changes to this section affect THE CURRENT WEB SERVER ONLY

File location

This object is not stored in the database.  It is always stored locally on the server

/usr/lib/fastx/var/config/static.json

/v3/api/system/settings/load

Returns the settings configuration of the local system

Parameters

{}

Result

{
  "result":{
     "disable": ["login", "start"], /* Array of settings to disable */
     "sshport": 22, /* SSH port to use when connecting via ssh */
     "authorizedKeysDir": "STRING_VALUE", /* directory where to store authorized keys in a CLUSTER */
     "hostname": "STRING_VALUE", /* Override hostname of this system */
  }
}

/v3/api/system/settings/save

Saves the database configuration of the local system.

Parameters

See client load result object

Result

{
  "result": true
}

System Log

Web Server’s Log files

/v3/api/system/systemlog/log

View the local web server’s output

Parameters

{}

Result

{
  "result": {
     "filename": "STRING_VALUE", /* File where the logs are being written to */
     "lines": ["line1", "line2", ...], /* Array of lines of output */
  }
}

Theme

Create and Edit Themes

Changes to this section affect all members in a FastX Cluster

Database _id

Each theme is stored as its own database entry.  The _id always begins with

config/theme/data/__theme_name__

/v3/api/system/theme/load

Returns the Themes

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of total Themes */
     "offset": 0, /* Starting Theme */
     "rows": [ THEME_1, THEME_2, ...], /* Array of THEME OBJECTS */
  }
}

Theme Object

{
  "id": "STRING_VALUE", /* Theme ID */
  "data": {
    "name": "STRING_VALUE", /* Display name of the theme */
    "description": "STRING_VALUE", /* Description of the theme */
    "background": { /* See CSS Background Property for more details */
        "image": "STRING_VALUE", /* Background Image */
        "attachment": "STRING_VALUE", /* Background Attachment */
        "clip": "STRING_VALUE", /* Background Clipping region
        "color": "STRING_VALUE", /* Background Color */
        "origin": "STRING_VALUE", /* Background Origin */
        "position": "STRING_VALUE",  /* Background Position */
        "repeat": "STRING_VALUE", /* Background repeat */ 
    },
    "brand": {
       "logo": "STRING_VALUE", /* Logo Image (usually a dataurl) */
       "tagline": "STRING_VALUE", /* Display text to be used with the theme */
    },
    "colors": { /* All colors are CSS Color Values in strings */
       "primary": "STRING_VALUE",
       "secondary": "STRING_VALUE",
       "info": "STRING_VALUE",
       "success": "STRING_VALUE",
       "warning": "STRING_VALUE",
       "danger": "STRING_VALUE",
       "light":"STRING_VALUE",
       "dark":"STRING_VALUE",
       
    },
    "sass": "STRING_VALUE", /* Custom SASS configuration to add to the theme */
  }
}

/v3/api/system/theme/save

Creates/Edits a theme

Parameters

See Theme Object.  If id is omitted, creates a new Theme

Result

{
  "result": true
}

/v3/api/system/theme/remove

Deletes a theme

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

Use

Set Default configurations for configuration options that do not have defaults

Database _id

config/use

/v3/api/system/use/load

Returns the settings configuration of the local system

Parameters

{}

Result

{
  "result":{
     "theme": "STRING_VALUE, /* Optional Theme id to use */
  }
}

/v3/api/system/use/save

Saves the database configuration of the local system.

Parameters

See use load result object

Result

{
  "result": true
}

HTTP Headers

Set Http Headers on different pages

Changes to this section affect all members in a FastX Cluster

Database _id

Each header is stored as its own database entry.  The _id always begins with

config/http/header/__header_name__

/v3/api/system/http-headers/load

Returns the Headers

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of total Http Headers */
     "offset": 0, /* Starting Header */
     "rows": [ HEADER_1, HEADER_2, ...], /* Array of HTTP HEADER OBJECTS */
  }
}

HTTP Header Object

{
  "id": "STRING_VALUE", /* Header Id */
  "data": {
    "header": "STRING_VALUE", /*  HTTP Header */
    "value": "STRING_VALUE", /* HTTP Header Value */
    "path": "^.*$", /* Regular expression defining where to set the header */ 
   }
}

/v3/api/system/http-headers/save

Creates/Edits an http header

Parameters

See Header Object.  If id is omitted, creates a new Header

Result

{
  "result": true
}

/v3/api/system/http-headers/remove

Deletes an Http header

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

HTTPS Options

Configure HTTPS Options

Changes to this section affect all members in a FastX Cluster

Changes to this section take effect when the web server is restarted

Database _id

config/https/options

/v3/api/system/https-options/load

Returns the https options configuration of the local system

JSON Object for the HTTPS Server Configuration

Parameters

{}

Result

{
  "result": HTTPS_OPTIONS_OBJECT /* JSON Object for the HTTPS Server Configuration */
}

/v3/api/system/https-options/save

Saves the database configuration of the local system.

 

Parameters

See JSON Object for the HTTPS Server Configuration

Result

{
  "result": true
}

WWW

Set the local web server’s configuration

Changes to this section affect THE CURRENT WEB SERVER ONLY

Changes to this section take effect when the web server is restarted

File location

This object is not stored in the database.  It is always stored locally on the server

/usr/lib/fastx/var/config/www.json

/v3/api/system/www/load

Returns the WWW configuration of the local system

Parameters

{}

Result

{
  "result":{
    "ca_file": "/path/to/ca/file", /* Path to the certificate's CA file */
    "cert_file": "/path/to/certificate/file", /* Path to the certificate file */
    "key_file": "/path/to/key/file", /* Path to the certificate's private key file */
    "pfx_file": "/path/to/pfx/file", /* Path to the PFX file (if ca, cert and key not used) */
    "port": 3300, /* WWW port */
  }
}

/v3/api/system/www/save

Saves the WWW configuration of the local system.

Parameters

See client load result object

Result

{
  "result": true
}

 

Clustering

If clustering is enabled, the following api options are available.  Users must be admins in order to call these API methods

Cluster Server

Database servers to connect to for clustering

Changes to this section affect THE CURRENT WEB SERVER ONLY

File location

This object is not stored in the database.  It is always stored locally on the server

/usr/lib/fastx/var/config/cluster.json

/v3/api/system/cluster-server/load

Returns the Servers

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of Cluster Servers */
     "offset": 0, /* Starting Cluster Server */
     "rows": [ SERVER_1, SERVER_2, ...], /* Array of SERVER OBJECTS */
  }
}

Cluster Server Object

{
  "id": "STRING_VALUE", /* Cluster Server ID */
  "data": {
    "url": "https://server.example.com:3300", /* URL of the database cluster to connect to  */
    "agent": JSON_OBJECT, /* JSON Object that will set the HTTP agent */
  }
}

/v3/api/system/cluster-server/save

Creates/Edits a Database Cluster Server

Parameters

See Cluster Server Object.  If id is omitted, creates a new Server

Result

{
  "result": true
}

/v3/api/system/cluster-server/remove

Deletes a Database Cluster Server

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

 

Load Balance

Configure load balancing scripts

Changes to this section affect all members in a FastX Cluster

Database _id

Each load balancing function is stored as its own database entry.  The _id always begins with

config/load-balance/script/__script_name__

/v3/api/system/load-balance/load

Returns the load balancing scripts

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of Load balancing scripts */
     "offset": 0, /* Starting Load Balancing Script */
     "rows": [ SCRIPT_1, SCRIPT_2, ...], /* Array of LOAD BALANCING OBJECTS */
  }
}

Load Balancing Object

{
  "id": "STRING_VALUE", /* Load Balancing ID */
  "data": {
    "name": "STRING_VALUE", /* Name of the load balancing script  */
    "script": "STRING_VALUE, /* Load balancing function */
  }
}

/v3/api/system/load-balance/save

Creates/Edits a Load balancing Script

Parameters

See Load Balancing Object.  If id is omitted, creates a new Load Balancing Object

Result

{
  "result": true
}

/v3/api/system/load-balance/remove

Deletes a Load Balancing Script

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

Schedule

Configure Scheduling Scripts

Changes to this section affect all members in a FastX Cluster

Database _id

Each scheduling script is stored as its own database entry.  The _id always begins with

config/job-scheduling-filter

/v3/api/system/schedule/load-filter

Returns the scheduling function

Parameters

{}

Result

{
  "result":{
     "fun": "STRING_VALUE", /* The job scheduler function */
  }
}

/v3/api/system/schedule/save-filter

Edit the scheduling function

Parameters

{
   "fun": "STRING_VALUE", /* The job scheduler function */
}

Result

{
  "result": true
}

Static

Configure static data on Local System

Changes to this section affect THE CURRENT WEB SERVER ONLY

File location

This object is not stored in the database.  It is always stored locally on the server

/usr/lib/fastx/var/config/static.json

/v3/api/system/static/load

Returns the static data object configuration of the local system

Parameters

{}

Result

{
  "result": JSON_OBJECT
}

/v3/api/system/static/save

Saves the static data configuration of the local system.

Parameters

{} JSON_OBJECT

The Static data is an object that gets sent with every update.  For more information see Load Balancing

Result

{
  "result": true
}

Metrics

Configure Metrics scripts

Changes to this section affect all members in a FastX Cluster

Database _id

Each metric script is stored as its own database entry.  The _id always begins with

config/metrics/__script_name__

 

/v3/api/system/metrics/load

Returns themetrics scripts

Parameters

{}

Result

{
  "result":{
     "total_rows": 5, /* Number of Metrics Scripts */
     "offset": 0, /* Starting Metrics Script */
     "rows": [ SCRIPT_1, SCRIPT_2, ...], /* Array of Metrics Script OBJECTS */
  }
}

Metrics Script Object

{
  "id": "STRING_VALUE", /* Metric Script ID */
  "data": {
    "metric": "STRING_VALUE", /* Metric Id  */
    "command": "STRING_VALUE", /* Metric Function */
  }
}

/v3/api/system/metrics/save

Creates/Edits a Metrics Object

Parameters

See Metrics Script Object.  If id is omitted, creates a new Metric Script Object

Result

{
  "result": true
}

/v3/api/system/metrics/remove

Deletes a Metrics Object

Parameters

{
   "id": "STRING_VALUE", /* id to delete */
}

Result

{
  "result": true
}

CURL

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

CURL Example

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