Skip to content

X11/The X Window System

What is it?

The X Window System (aka X11, aka X) is the primary GUI system for UNIX computers. X allows a program (an X "client") running on a UNIX computer in the cluster to be displayed on a remote computer (running an X "server"1) over the network. To use it, your local computer needs to have X server software installed on it.

SSH provides support for tunnelling X11 over an encrypted connection. You may need to tell SSH that you want that service, by, for example, adding the -X flag to an ssh command in a macOS Terminal.

X11 has been (slowly) being replaced by Wayland. Wayland has been the future for many years, but is now (2024) becoming common. However what is implementing X11 is usually invisible to users. It is mentioned here in case you see references to Wayland where you expect to see X11.

How do you get it?

  • macOS users need to install XQuartz from xquartz.org.
  • Windows users need to use a program like MobaXterm. We have a page describing installing and using MobaXterm.
  • Linux laptop or desktop users are already using X as their windowing system.

Example X11 Programs

xterm, SAS, RStudio, xclock, thunar.

Configuring SSH To Support X11

Authoringnote

The SSH document points to this one for ALL of the information needed to use X11. So this section needs to be complete. Pointing to the MobaXterm document of course, for Windows users.

Copying and Pasting in X

Copying and pasting into and out of X11 environments is often more challenging than doing that using native Windows or macOS programs. You may need to use different key combinations and/or modify the settings of your X11 program (XQuartz or MobaXterm).

The historical default meta key used for copying and pasting is the Ctrl key. Windows copied that usage, but macOS users are used to using the Cmd key. Depending on the settings of your X software, you may need to use Ctrl or a different key combination. (And you can often change those settings to something else that you prefer for any reason.)

An additional complication is that X11 was developed in a world where you were expected to have a three-button mouse. You could select, copy and paste using different button combinations. That knowledge will help you understand any references you may come across in documentation or program settings about things like "MIDDLE BUTTON"

X11 Forwarding and Authentication

See this excellent article from Teleport (pdf) for quite a lot of good information and diagrams!!! (Saved as a PDF from https://goteleport.com/blog/x11-forwarding/)

Troubleshooting X Connections

Authoring Note

This section should include pointers to FAQ items or vice versa. We shouldn't rewrite the same information twice!!!

  • When -X ?

  • When -Y ? Probably only on old macOS systems such as 10.13

  • printenv DISPLAY or echo $DISPLAY

  • [user@login31 ~]$ srun --pty --x11 bash srun: error: No DISPLAY variable set, cannot setup x11 forwarding.

  • How do Windows users configure ForwardX11Timeout? - No - this has only ever been an issue for Mac users ? https://jhpce.jhu.edu/help/faq/#x11

help/faq/#x11 slurm/slurm-faq/#x11-related-errors

Algorithm

If X11 isn’t working for you, consider taking the following steps, and if you cannot figure out how to resolve the problem, let us know what happened when you followed these steps, so we know what worked and where in the process you reached an error, and exactly what it was.

  1. Log out of the cluster.

  2. If you are on a Mac, test that XQuartz works on that Mac at the very most basic level. No network connections, no SSH, no remote authentication, just local X11 functionality.

    1. start XQuartz if not already running
    2. start a new xterm window from the Applications menu
    3. start a second test program from that xterm like xcalc
    4. run xauth list to (slowly) list previously-added entries to your ~/.Xauthority file. (You can Ctrl+C to cancel the xauth.)
    5. If you have any problems doing these things then STOP and find a solution. NOTHING WILL WORK IN TERMS OF X11 ON THE CLUSTER if it won't work at this level on your Mac. If you've just installed XQuartz, did you forget to reboot?

  3. Log back into the cluster: ssh -X USER@jhpce01.jhsph.edu

  4. On the login node, run printenv DISPLAY You should see a string like localhost53:0 The first number (here "53") will vary, as it needs to be unique for all currently-logged in users.

  5. If you do not have a DISPLAY variable defined, then you won't be able to run any X11 commands. You need to figure out why this variable is not being set.
  6. If do you have a DISPLAY variable defined, then:
    1. try to run a simple X11 program to see if it works: xclock should bring up a new clock window on your screen. Close the xlock window by clicking in the right button in the upper left corner of its window or by typing Ctrl+C in the original terminal.
    2. run xauth list to (slowly) list previously-added entries to your ~/.Xauthority file. (You can Ctrl+C to cancel the xauth but you should probably let it finish to ensure that your ~/.Xauthority file is not corrupt.)
    3. If you are told "xauth: Command not found" then your PATH environment variable is incorrect in an important way. xauth is found in JHPCE at /usr/bin/xauth Your ~/.bashrc file is nonstandard or your module usage has messed things up. The commands which xauth and/or whereis xauth should show you where in the list of directories contained in the PATH environment variable xauth is found. What is the output of echo $PATH?
    4. If you have any problems doing these things then STOP and find a solution. NOTHING WILL WORK IN TERMS OF X11 ON A COMPUTE NODE IN THE CLUSTER if it won't work at this level on the login node.
  7. So now we've established that you have a working X11 environment on the login node.
  8. Connect to a compute node asking for X11 forwarding support: srun --pty --x11 bash
  9. If you receive an error then see the X11-related entries in the SLURM FAQ.
  10. On the compute node, run printenv DISPLAY
  11. If you do not have a DISPLAY variable defined on the compute node, then you won't be able to run any X11 commands on the compute node. You need to figure out why this variable is not being set.
  12. If you have a DISPLAY variable defined on the compute node, then run a simple X11 program to see if it works: xclock should bring up a new clock window on your screen.
  13. Now close the xclock and try to run your application again.

  1. Note that X reverses the normal conception of client/server operation, which is that the remote computer is the "server". In X11, the "server" is the program receiving the keyboard and mouse inputs and displaying the output of remote "client" programs. ↩