FastX Installation Guide


Purpose

The purpose of this document is to give an in-depth understanding of how to install and configure FastX for use on your Linux system.  This guide will cover basic installation as well as more advanced topics such as installation in non standard locations.

System Requirements

FastX Server 

Hardware Requirements

  • Intel or AMD x86-64 processor
  • A FastX session’s memory requirements are highly dependent on the applications running in the session.  As such provisioning requires some calculations based on your actual use case.  We provide the following examples to give you a better understanding of the system requirements when provisioning your systems.
    • FastX Xterm single window mode session 4K:  360 MB RAM
    • FastX Gnome single window mode session 4K:  1.1 Gig RAM
    • We also recommend a system with at least 8 logical CPU cores in order to maximize the CPU compression speed,

Please see FastX Memory Usage for more information

Operating Systems

  • Red Hat Enterprise (including CentOS) 7, 8,  or later, 64-bit only. FastX version 3.0 is the latest version available for Red Hat 6.
  • Any Linux operating system equivalent to Red Hat 7 or later including Debian/Ubuntu style systems

Miscellaneous Requirements

These requirements can be modified by changing the default startup options.

  • Mounted $HOME directory (when using clustering)
  • /tmp directory with read/write access for all users

Default Ports

  • Port 3300 for http and https (https://hostname:3300)
  • Port 22 for SSH

Migrating from Earlier Versions of FastX

FastX 3.2 uses a generic database architecture that is not compatible with 3.1 and below.  You should export your 3.1 configuration before upgrading to 3.2.  If you are updating from 2.X, please first migrate to 3.1, then follow these instructions.

Migrate the configuration (bookmarks, profiles, admins, load balancing, etc.) from the FastX 3.1 database with these steps:

  1. Shutdown the fastx3.1 service: systemctl stop fastx3
  2. Download https://www.starnet.com/files/private/FastX3/export-3.1.tgz
  3. Extract it: tar xf export-3.1.tgz
  4. Export the 3.1 configuration: export-3.1/export.sh

This will convert the 3.1 data into the 3.2 “standalone” format in the directory /var/fastx/local/store.  If you will be running a standalone (not clustered) version of FastX, you are done.  If you want to migrate the standalone information to the cluster, see the clustering guide.

Root Installations

Follow these instructions for administrators who have root privileges.  Systems can be RPM or Deb based. The following instructions assume an installation in the default /usr directory. 

Download the setup script (setup-fastx-server.sh) and run it with bash as follows:
bash setup-fastx-server.sh

Install the FastX server package

rpm install -y fastx-server

On a Debian/Ubuntu system, use apt-get:

Apt-get install -y fastx-server

Run the post install script (as root)
/usr/lib/fastx/3/install.sh

Installing in an Alternate Location

The FastX server rpm supports installs in alternate locations. This is helpful when admins want to install the server in a shared directory, or a specific location for 3rd party applications. In the following example, the FastX server will be installed in /your/base/dir

Install the server (as root)

rpm -i --prefix=/your/base/dir fastx-server-*.rpm


Run the post install script (as root)

/your/base/dir/lib/fastx/3/install.sh

Upgrading FastX

To upgrade FastX simply follow the installation instructions again with the new RPM Package.

** If you have a prerelease version of FastX you will need to uninstall FastX before upgrading to the newer version.

Uninstalling FastX

To uninstall, run the command

yum erase -y fastx-server

Debian/Ubuntu

Debian packages won’t install to an alternate location. To install the FastX server in an alternate location, use the non-root instructions below.

Non Root Installations

Users who do not have root access can still install FastX using the following commands to extract the file from rpm. First, download the RPM file to your home directory.

Run the following commands to extract the files

cd $HOME
mkdir FastX
cd FastX
rpm2cpio ~/fastx-server-version.build.rhel7.x86_64.rpm | cpio -id
mv usr/* .
rmdir usr$HOME/FastX/lib/fastx/3/install.sh

This will create a $HOME/FastX directory where all the files are extracted.  

Licensing

Activating a License

To install a license (necessary to launch a session), run:

$HOME/FastX/lib/fastx/3/install/activate


Closed Network Registering (No internet)

Please follow the instructions from the following webpage.

https://www.starnet.com/xwin32kb/floating-license-registration/

Running the License Server

After the license is installed, run the license server

$HOME/FastX/lib/fastx/3/rlm/rlm -c $HOME/FastX/lib/fastx/var/license

Suggestions

FastX can scan your system and preconfigure basic suggestions (GNOME, KDE, xterm etc) to simplify the connection process.  If you want FastX to check for default suggestions ru

$HOME/FastX/lib/fastx/3/install/suggestions

Web Server

Running the Web Server

To run the web service with default settings, run:

nohup $HOME/FastX/lib/fastx/3/tools/run-web &

Silent and Automated Installs

The install.sh program is designed to help the installation by being user-interactive. Administrators wishing to automate their installs should run one or all of the install commands in their scripts.  Below is a listing of the operations needed for installing FastX using an automated install. 

Administrators can also call use the -q command to silently install with the default options:  /usr/lib/fastx/3/install.sh -q

Create a Fastx User

The install.sh script creates a user called fastx that will be used to run the fastx3 service file.  When rolling a custom install, make sure to have a fastx user account who owns the FX_VAR_DIR.  The FastX web server will switch to the uid of the owner of the FX_VAR_DIR directory. 

Add Licensing

Administrators typically use a centralized license server in a distributed system. Your installation should point to the central server.

  1. Create the directory /var/fastx/license
  2. Make sure the directory (from step 1) is world-readable (e.g. mode 755).
  3. Put the name of your license server into a variable: $LICENSE_SERVER
  4. Run this command: echo “HOST $LICENSE_SERVER 00000000 5053” > /var/fastx/license/$LICENSE_SERVER.lic
  5. Make sure that file is world-readable (e.g. chmod 644 /var/fastx/license/$LICENSE_SERVER.lic)
  6. If you have multiple (e.g. failover) license servers, repeat steps 3-5 for each license server on your network.

Install the Web Server

Run /usr/lib/fastx/3/install/web -q to install the web server.

Add the Initial Admin Group

Run /usr/lib/fastx/3/tools/reset-admin group1 group2 group3 … to set your initial admin groups.

Create Global Applications

Run /usr/lib/fastx/3/install/suggestions -q to create the initial set of bookmarks.  This is an optional command. In a cluster, the bookmarks are synced with the cluster members.  Run this command if you are making a standalone server.

Add Screenshot Support

The script /usr/lib/fastx/3/install/screenshot attempts to install the packages to support FastX screenshots (thumbnails). This may not be necessary if the packages are already installed or if you are on a closed network.

Create Clustering

Adding a server to a cluster is not done by the install script.   See our Clustering Guide for more information.

Customizing Configuration

Configuration can be customized via automated install by configuring and installing files. See Configuration Management for details

Resetting the Admin Account

Admins are defined by Linux User Groups.  If somehow you need to reset the admin account run the following command  /usr/lib/fastx/tools/reset-admin

Note: The user who is running the FastX web service always has superadmin access.

Installing Third-Party Certificates

FastX ships with self-signed certificates to get the web server up and running with as little trouble as possible.  Once the system has been configured and is ready to go into production, it is time to add your own certificates from a trusted third party (VeriSign, Thawte, Comodo etc).  Acquiring the certificate is beyond the scope of this guide and typically the trusted third parties have instructions on how to do those.

  1. Log in to the web interface as an administrator
  2. Click on the gear icon to bring up the System Section
  3. Choose Local System > WWW
  4. Add the paths to your cert, key and CA file
  5. Save
  6. Restart the FastX service

Granting Sudo Access to the FastX User

In order to avoid cases where double authentication is required in a cluster, or when using OpenID Connect administrators can set the fastx user account to try to sudo to the other user.  This is an optional option.  The method for allowing sudo access is documented in Security Considerations

Startup Options

FastX can be configured to set files and directories in locations other than the default location.  This is useful for administrators who want to install FastX in a central location for multiple systems, and for users who wish to install FastX on a Docker image.  Administrators should keep the following rules in mind

  • Each system needs its own var, config, and local dir
  • A TEMP directory must have read/write permissions for all users
  • Users are defined by their username (not uid)
  • In a cluster, users should have a mounted $HOME directory

FastX.conf

The FastX.conf file is a special file that is located in $FX_CONFIG_DIR. This file sets special variables for launching sessions.  These are the default paths where the session will store session information.

# HOST is set to $(hostname) by default.
FastXPath=@HOME@/.fastx_server   #base directory for FastX user storage
SessionPath=@HOME@/.fastx_server/@HOST@/sessions # location of session directories

Variable expansion is done by enclosing the variable name in “@” (@VAR@). To put a literal “@” in a variable, use “@@”. A “#” makes the rest of the line a comment. To put a literal “#” in a variable, use “@#@”. A variable can be either a FastX.conf variable or an environment variable. Available variables are HOST, which is set to the hostname of this server; USER, which is the username. HOME is a useful environment variable.

SessionPath is where session directories are stored. A session directory is named “FX3-” followed by the session id. The session directory contains log files, the X11 authorization file, session parameters, process ids, and other session-specific files.

FastXPath is where the history, bookmarks, and favorites file are kept, although the FastX database may have a more updated version of the information in these files. If this directory cannot be created, then the history is not saved.

HOST can be set if the system hostname command does not return a valid DNS hostname. It is used in the history file, to make an X11 authorization entry, and to set the DISPLAY name.

Environment Variables

FX_VAR_DIR

Default: /var/fastx

Directory for Configuration, database, licenses, and local files.  The var directory contains files that are specific to this installation of FastX. This includes configuration files (see FastX config Directory below), the local directory (see below), web (SSL) certificates, license files, and local web files (if used).

FX_CONFIG_DIR

Default: /etc/fastx

This is the directory of all configuration that is local to the system.  You can mount this directory to be used by multiple systems, but that means changes that should be local to one system would propagate to others.  A better idea is to clone a base configuration to the other systems’ config dirs.  

The config directory is read by the fastx-protocol and session start scripts, and the FastX web server.

FX_LOCAL_DIR

Default: $FX_VAR_DIR/local

The local directory contains the FastX database, the server ID, and the public-private key for this FastX server. This directory must be unique (not shared) for each FastX server (including FastX cluster members)

Setting Environment Variables

When FastX is installed as a service, you can set environment variables in /etc/sysconfig/fastx3

Variables are set using the syntax “NAME=value”.

Hostname Substitution

Users may wish to create unique directory names by including the system host name. This can be done in the /etc/sysconfig/fastx3 file with a substitution that depends on the type of system.

Systemd Systems

Systemd is installed on most modern linux systems (Red Hat 7 or later)

Use “%H” to substitute the host name. 

Init.d Systems

Older systems use init.d

Use $HOST. To determine if your system is using systemd, run the command systemctl. If it shows many units loaded, then your system is a systemd system. If the systemctl command is not found, or shows nothing, then your system is the older init.d type.

Example

On a RedHat 7 system with systemd support suppose FastX is installed in /opt/sw/fx
You wish to configure your FX_LOCAL_DIR as  /opt/sw/fx/var/local/`hostname`/

Edit /etc/sysconfig/fastx3 

FX_LOCAL_DIR=/opt/sw/fx/var/local/%H

Configuring FastX for Multiple Systems

FastX uses a distributed database and local files to save configuration.  The database allows for automatic synchronization for configuration across a cluster of servers.  If you are configuring standalone servers you may want to automatically distribute configuration when setting up the server.  The following steps will guide you through this process.

Set up a License Server

  1. On a system central to all servers, Instal the License Server 
  2. On each session server, run /usr/lib/fastx/3/install.sh
    • When asked if there is a license server on the network select yes
    • Add the hostname to point to the license server

Configure the First Server

  1. Install FastX
  2. Run the post installation script /usr/lib/fastx/3/install.sh
  3. Log in to the Browser Client as a FastX Administrator
  4. Configure the FastX Server According to your needs

Export the FastX Configuration

Local configuration is located in the /etc/fastx directory.  Any configuration that is local to this system only (not to the entire cluster) is located in this directory.  It is Best Practice to make a backup copy of your default config directory.  Copy the default configuration into each server so that the individual servers can change them later.

Clusters

Configuration global to your cluster is located in the database.  If you are using clustering, this information is automatically synced across the cluster.

Standalone Servers

If you are not using clustering, or want to make a backup the database is stored in files located at /var/fastx/local/store.  Copy these files to the same location in other systems to set them up.

Configuring Other Servers

  1. Install FastX
  2. Run the post installation script in quiet mode: /usr/lib/fastx/3/install.sh -q
  3. Copy the default local configuration from the first server into /etc/fastx
  4. Copy the /var/fastx/local/store directory the new system
  5. Copy the license.lic file into /var/fastx/license
  6. Restart the FastX service