Overview

A number of programs with graphical user interfaces (e.g., R, MATLAB) use the X11 system which lets the program run on an O2 computer, but show the graphics on your desktop. Even to activate the graphics devices and plot to files, an X11 session must be enabled.  To do this, you need to have an X11 server running on your desktop, your SSH connection needs to have X11 forwarding enabled.

If you have SSH X11 forwarding enabled in your SSH client and are running an X11 server on your local system, you can run X11 jobs on the O2 compute nodes. As of the July 7, 2020 upgrade, batch jobs now have X11 forwarding enabled by default without any sbatch flag required (provided you submitted a job after having logged in with the corresponding ssh flag, see below). However, in order to utilize X11 forwarding in an interactive session, it is still necessary to specify the --x11 flag, like 

srun --pty -p interactive -t 0-12:00 --x11 /bin/bash

X11 Terminology

X11 client
The application being displayed (xterm, XEmacs, Mozilla, etc.) You would run this, e.g., on O2

X11 server
The program that drives the user's display and handles connections from X11 clients. This program runs on your desktop.

xterm
X11 client that provides a terminal window

What Not To Do

Do not:

• use xhost or set the DISPLAY environment variable manually to the name of the system where your X11 server is running. Using SSH X11 forwarding will automate and secure this process for you – see below for details.

• run applications that can be run directly on the system where you're running your X11 server (xterm, XEmacs, Mozilla, mail readers, etc.). In general, you will get better performance from running these applications locally.* With web browsers, you can easily make a connection to a remote service from a locally running browser.

• * X11-based editors usually have a facility for accessing remote files. For example, for XEmacs, you can use http://savannah.gnu.org/projects/tramp/.

SSH X11 Forwarding

Security notice about SSH X11 forwarding

SSH X11 forwarding is often disabled by default in SSH clients because administrative users on remote hosts to which you connect can access your X11 server, which could allow them to observe or manipulate your X11 session (including logging keystrokes).

It is recommended you enable X11 forwarding only for remote hosts where you trust the administrators. If you have a question about Research Computing-maintained hosts, please  email rchelp@hms.harvard.edu.

Microsoft Windows

You will need an X11 server for your desktop, as none are included with Windows.

The easiest solution:

• Install MobaXterm as your terminal client of choice; it has a built-in X server installed.

• Install http://sourceforge.net/projects/xming/ , and make sure to include the SSH client Putty.

• When configuring Putty for your SSH login, you must check the "Enable X11 Forwarding" box.

Alternatively, if you want X11 display along with a UNIX-like environment to run on top of Windows (e.g. to run UNIX shell scripts and commands), then we recommend using http://cygwin.com/ . The X11 server and OpenSSH client work similarly to those on UNIX-like systems.

Linux, Mac OS X, and other UNIX-like systems

You must have X11 started in order for forwarding to work properly. For most UNIX desktop installations, X11 is the default graphical interface and is already running.

For Mac OS X, X11 is not the default graphical interface and must be installed and started. Install http://xquartz.macosforge.org/landing/ on your Mac and run it whenever you want to use X11 forwarding.

This document assumes

• that X11 forwarding is not enabled by default. (This is common in modern software distributions because of the security implications mentioned above.)

• that you are using OpenSSH, which is the most common SSH client on UNIX-like systems.

X11 forwarding from the command line

X11 forwarding can be enabled by adding -XY to the command line:

Adding -C enables compression of the SSH connection along with any X11 traffic.

X11 forwarding from a configuration file

If you use the same settings for a given host every time you connect, you may find it convenient to list these in your SSH client's configuration file.

The ssh configuration file is located in ~/.ssh/config. For hosts you want to enable X11 forwarding to, add the following to your config file:

Adding Compression yes enables compression of the SSH connection along with any X11 traffic.

Troubleshooting X11 forwarding

Here is the recommended order for troubleshooting X11 forwarding if you're having trouble:

• If your desktop is a UNIX-like system, make sure you can run an X11 program locally, from the same terminal from which you plan to SSH to the remote host. A trivial program like xlogo is useful for this sort of testing. If you can't display a local X11 client, then remote clients are unlikely to work either.

• SSH to the remote host. Without doing anything further, type echo $DISPLAY. You should get something like localhost:11.0. (The host name will be that of the remove host and the display number will differ from this example.) If $DISPLAY has no value, you don't have X11 forwarding enabled.

• At this point, you should be able to run an X11 client program like xlogo on the remote host.

• If you still have trouble, feel free to email Research Computing at rchelp@hms.harvard.edu .