Revision as of 16:23, 24 August 2016

HiPerGator 2.0 documentation

Full Xpra Documentation

Xpra Homepage: https://xpra.org/
Xpra Basic Usage: https://xpra.org/trac/wiki/Usage
Xpra Advanced Usage: http://xpra.org/manual.html

Step 1: Client Installation

Xpra client installation depends on the operating system running on your local machine and may require assistance of a system administrator if you do not have the authority to install new software. Once Xpra is installed on your client computer feel free to skip this step. Click on the link specific to the operating system running on your local computer.

Step 2: Start a GUI session on HiPerGator

There are multiple approaches from the simplest to the most versatile, but complex to launch an application within a SLURM gui session and wrap it in Xpra for easy connection from the client side.

Single command, no job script

There are two classes of applications that can be started with just one command from the gui environment module and do not require you to provide a job script.

Preset applications

To list applications presets load the gui module and run launch_gui_session -l

module load gui
launch_gui_session -l

To launch a pre-approved application:

Load the gui module if not already loaded

module load gui

Launch the application

launch_<application>_gui

For example:

launch_mzmine_gui

or

launch_rstudio_gui

See a full example on the RSTudio Help Page.

Simple applications

If you want to run a simple application in which the environment module name matches the name of the program you want to run it's just as simple as launching a preset application

module load gui
launch_gui_session -e <application>

For example

launch_gui_session -e molden

Provided Job Script

If you need to pass custom arguments to the application, load pre-requisite environment modules and so on you can provide a simple script (linux format text file) with the required commands as an argument to launch_gui_session. Make sure to prepend the command that starts the program with xpra_start. For example, a following job script named my_molden.sh will use the molden/5.0 environment module and start molden with a particular model file:

module load molden/5.0
xpra_start 'molden /ufrc/data/tests/molden/boc-iso-1t.gjf'

Now, to launch molden with the above script run

launch_gui_session -e molden -f my_molden.sh

Manual launch

Of course, if you prefer to talk directly to SLURM you can write a full job script complete with resource requirements, job name, output file, etc in the #SBATCH section you can simply submit that script to SLURM. Make sure you use the gui partition

#SBATCH --partition=gui

and wrap your command with xpra_start as shown above.

You can use a job script for one of the application presets found in the '$HPC_GUI_JOB' directory once the 'gui' environment module is loaded as the base of your own job script.

List Xpra Sessions

If you performed a manual launch or used the '-w' argument to the automated launcher command you'll have to manually check on your gui job. Check the job status with 'squeue -u $USER'. When the job starts you have to list the available xpra sessions using xpra_list_sessions command in the gui module. This command will refresh the Xpra session list and provide a convenient list of live Xpra sessions as well as client commands that can be copied and pasted into a terminal on the client machine.

Example

$ module load gui
$ xpra_list_sessions

Output:

Refreshing the session list for jdoe to remove stale sessions

List of active Xpra sessions for jdoe:

Session: i111a-s222.rc.ufl.edu:3713
    Job ID: 123456, Name: RStudio
    Client command:
         xpra attach ssh:jdoe@i111a-s222.rc.ufl.edu:3713
        or (downloaded script):
         ./xpra attach ssh:jdoe@i111a-s222.rc.ufl.edu:3713

See the respective application pages for details and sample job scripts.

Step 3: Connect to a GUI Session from client computer

Connecting from outside of UF campus via VPN

The nodes in SLURM gui partition are accessible only within the UF campus network. If you are working off campus, you will need to use the VPN to connect to the UF campus network using AnyConnect VPN or similar software. Please see: https://vpn.ufl.edu for additional information.

Linux

Xpra is typically automatically added to your path during installation, so you can connect to your running xpra instance using the following syntax where $USERNAME is your UF GatorLink user-name, $SERVERNAME is the server where your application is running inside xpra, and $PORT is the X11 port you assigned when you started your application.

xpra attach ssh:$USERNAME@$SERVERNAME:$PORT

As an example:

testuser@jr-physics:~$ xpra attach ssh:testuser@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96

The xpra_list_sessions command presents a ready-to-use connection command, but you'll have to add the desktop scaling or dpi arguments manually.

Please note that if you close the application window using the close button in the top right (or left) corner, this will exit your application and terminate your SLURM gui session. If you want to simply detach the session and come back later, please follow the detaching xpra session instructions below

MAC OS

Navigate to the folder that contains the Xpra executable:

cd /Applications/Xpra.app/Contents/MacOS

Alternatively, call the xpra shell script you downloaded during client software installation.

Use the client command provided by 'xpra_list_sessions' to connect while adding any local options you need to improve the viewing experience like

Desktop scaling: --desktop-scaling=on
Resolution, dpi (dots per inch): --dpi=96

Example:

./Xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96

or with the wrapper script in place

xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96

Once the GUI application windows is displayed on your local computer if you close the window using the close button both the application and SLURM gui session will close. If you want to simply detach the session and come back later click on the terminal window where you ran the client command and use the 'Ctrl+c' key combination to detach the session.

Microsoft Windows

Navigate to the install location of xpra (normally C:\Program Files (x86)\Xpra\).

In MobaXterm

cd "/drives/c/Program\ Files\ \(x86\)/Xpra/"