FastX 3.0 API
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 */
"schedule": false, /* Enable scheduling */
"banner": false, /* Enable Banners */
}
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": "banner" | "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 */
"banner": "STRING_VALUE", /* (stage banner only) text of the banner to display */
}
Stage: banner
Next Step: Display the banner. Acknowledge that the banner has been displayed
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: “banner”
Parameters
{
"authtoken": "STRING_VALUE", /* The authorization token */
}
Result
JSON object of the authentication stage. See /api/v3/auth/ssh
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: Stage “sign”
If you send a public key that the server will accept, you will move to the sign stage
{
"result": {
"stage": "sign"
"authtoken":"STRING_VALUE", /* The authorization token */
"signData": "STRING_VALUE", /* Base64 encoded data of that you should sign with the public key you just sent */
}
}
Result: Stage “public-key”
If the public key is not accepted by the server, you will be sent back to the public key stage. At this point send a different public key in your key store. If you have no more public keys to send, send an empty string “” as the publicKey parameter to move on to a new stage.
Result: Others
JSON
object of the authentication stage. See /api/v3/auth/ssh
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 */
"icon": "STRING_VALUE", /* dataurl of icon file */
"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 */
"serverId": "STRING_VALUE", /* Server Id that the client wants to start the session on (request does not have to be honored) */
"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
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 === ‘scheduled’ the following result object is returned
{
"stage": "scheduled", /* 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 */
"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 */
}
Result
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
Result
/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
Result
/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
/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
/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
/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
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
}
Events
Configuration for session events
Database _id
config/events/api/__event_name
/v3/api/system/events/load
Returns the configured events
Parameters
{}
Result
{
"result": {
"total_rows": 5, /* number of rows */
"offset": 0, /* offset */
"rows": [ EVENT1, EVENT2 ... EVENTN], /* Session Events */
}
EVENT Object
{
"id": "EventID",
"data" {
"id": "EventID",
"script": "function(o) {}", /* Javascript function */
}
}
/v3/api/system/events/save
Saves an event
Parameters
{
"id": "Event ID",
"data": {
"script": "javascript function"
}
}
Result
{
"result": true
}
Events Web
Configuration for session update events
Database _id
config/events/update-web
/v3/api/system/events-web/load
Returns the configured events
Parameters
{}
Result
{
"result": {
"script": "javascript function"
}
}
/v3/api/system/events-web/save
Saves an event
Parameters
{
"script": "javascript function"
}
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 */
"saveXauthDefault": false, /* Save the Xauthority file to the default location */
"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
}
/v3/api/system/load-balance/set-login
Set the login load balancing script
Parameters
{
"id": "STRING_VALUE", /* 3.0 Deprecated -- id of the script to use as the log in */
"ids": ["STRING1", "STRING2", ..., "STRINGN"] /* 3.1 -- array of load balancing scripts */
}
Result
{
"result": true
}
/v3/api/system/load-balance/set-start
Set the start load balancing script
Parameters
{ "id": "STRING_VALUE", /* 3.0 Deprecated -- id of the script to use as the log in */
"ids": ["STRING1", "STRING2", ..., "STRINGN"] /* 3.1 -- array of load balancing scripts */ }
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