X Forwarding

Published

August 1, 2024

Modified

August 8, 2024

Abstract

The following section describes how to use graphical programs with containers. Graphical X11 programs require forwarding of the user-interface via the SSH connection established to the cluster. The nessecary SSH configuration is called “X-forwarding” and is configured by the user with command-line options.

Overview

The Virgo cluster (including its submit nodes) is prepared to forward display information¹ from the X Window System² to the local screen of a user. Since X forwarding is considered insecure the communication is send over a secure SSH connection. This process is known as “X forwarding”³. In order to execute X11 graphical applications inside a container on the cluster following requirement has to be met. In the container the xauth program must be installed which is the case for our Virtual Application Environments (VAEs). Users building a custom container image need to make sure that the xauth program is available. In most cases if there are any X11 programs installed in the container, it’s probable that Xauth has been included as dependency.

# Test if `xauth` is installed in the container
>>> apptainer exec $APPTAINER_CONTAINER which xauth                
/usr/bin/xauth

When xauth is installed, login to the container to test the functionality of X forwarding. Since there are no X applications installed in the VAEs we use an application loaded from CVMFS called Root⁴ for the following example:

# Login to the VAE'23 container...
1>>> ssh -X -J lxlogin.gsi.de vae23.hpc.gsi.de

# ...load ROOT into the shell environment
2>>> source /cvmfs/fairsoft.gsi.de/debian10/fairsoft/nov22p1/bin/thisroot.sh

# Start the ROOT interpreter...
3>>> root
   ------------------------------------------------------------------
  | Welcome to ROOT 6.26/10                        https://root.cern |
  | (c) 1995-2021, The ROOT Team; conception: R. Brun, F. Rademakers |
  | Built for linuxx8664gcc on Dec 16 2022, 14:50:00                 |
  | From tags/v6-26-10@v6-26-10                                      |
  | With c++ (Debian 8.3.0-6) 8.3.0                                  |
  | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q'       |
   ------------------------------------------------------------------

# ...launch an X11 application
root [0] new TBrowser();

1: Login with ssh to a VAE using the option -X to enable X forwarding (more details in the following sub-section).
2: After login load the ROOT application into the shell environment. Note that ROOT is one example for an X11 application, you could start any X11 program to verify if X forwarding is properly enabled.
3: When Root is started execute the command new TBrowser(); to start the ROOT object browser which should forwarded to your local screen. If the browser starts you can close it by selecting Browser » Quit Root from the menu.

If you want to start your own container the sequence is similar. Instead of direct login into a VAE, login in to a (bare-metal) submit node and start your container:

# Login to a submit-node (a non VAE environment)
>>> ssh -X -J lxlogin.gsi.de virgo.hpc.gsi.de

# We use a pre-build VAE container for this example
>>> export APPTAINER_CONTAINER=/cvmfs/vae.gsi.de/vae23/containers/user_container-production.sif

# Start a shell within a container...
1>>> apptainer shell -B /cvmfs $APPTAINER_CONTAINER

# ...test if X forwarding is working
Singularity> source /cvmfs/fairsoft.gsi.de/debian10/fairsoft/nov22p1/bin/thisroot.sh
2singularity> root
   ------------------------------------------------------------------
  | Welcome to ROOT 6.26/10                        https://root.cern |
  | (c) 1995-2021, The ROOT Team; conception: R. Brun, F. Rademakers |
  | Built for linuxx8664gcc on Dec 16 2022, 14:50:00                 |
  | From tags/v6-26-10@v6-26-10                                      |
  | With c++ (Debian 8.3.0-6) 8.3.0                                  |
  | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q'       |
   ------------------------------------------------------------------

root [0] new TBrowser();

1: Since CVMFS is not mounted by default, make sure to bind mount the directory /cvmfs explicitly with the Apptainer option -B.
2: Like in the previous example start an X11 graphical application to verify proper functionality of X forwarding.

X-forwarding Options

X forwarding is supported in two different modes: trusted ssh -Y and untrusted ssh -X X-forwarding (cf. footnotes). In summary untrusted X-forwarding restricts permissions which normally is preferable. Unfortunately trusted X-forwarding is actually the default behavior on Linux even if untrusted X-Forwarding is requested, so the user does not need to care about the differences.

X-Forwarding on Apple Mac OS X

When using ssh -X on Mac OS the system defaults to untrusted X-forwarding which has implications. The most obvious difference is a timeout of only 20 minutes (default setting) after which no new connections can be opened. If you experience problems with X-forwarding after some time you probably used untrusted X-forwarding and ran into the time limit. Resolve this by passing a different timeout as parameter during SSH login:

# ...login to a cluster submit-node (non VAE environment)
ssh -o ForwardX11Timeout=8h -X -J lxlogin.gsi.de virgo.hpc.gsi.de

Custom Home-Directory

Environment Variable	Description
`XAUTHORITY`	Defines the path to the Xauthority file (defaults to `$HOME/.Xauthority`)

During start of a container Apptainer mounts the $HOME directory defined on the host as home directory inside the container. This can result in problems when using different operating systems inside the containers which may manipulate files in a users home directory. Avoid this problem by using a home directory different then $HOME when starting a container.

Unfortunately a custom path to your home directory conflicts with the default behaviour of X-forwarding. Inside the container the .Xauthority file needs to be available in the home directory. Without additional configuration during SSH connection the .Xauthority file is expected in the $HOME directory on the target node by default. Configure a custom path to Xauthority by setting the environment variable XAUTHORITY:

# Login to a cluster submit-node (non VAE environment)
XAUTHORITY=~/custom_home/.Xauthority
1ssh -o SendEnv=XAUTHORITY -X -J lxlogin.gsi.de virgo.hpc.gsi.de

# Optionally check the path to the `.Xauthority` file after login
ls -l $XAUTHORITY

# ...Start a shell in the container
2apptainer shell -H ~/custom_home -B /cvmfs $APPTAINER_CONTAINER

1: Use the option -o SendEnv= to propagate the XAUTHORITY environment variable during SSH login to the target node.
2: Set the Apptainer option -H to specify the path to a custom home-directory. Note that the container environment binds the specified path to the expected default path of $HOME.

Footnotes

SSH Manual Page, Section X11 Forwarding
https://man.openbsd.org/ssh#X11_FORWARDING ↩︎
X Window System
https://en.wikipedia.org/wiki/X_Window_System ↩︎
What You Need to Know About X11 Forwarding
https://goteleport.com/blog/x11-forwarding/↩︎
ROOT Data Analyses Framework
https://root.cern.ch ↩︎

--- title: X Forwarding date: 2024/08/01 date-modified: 2024/08/08 abstract: > The following section describes how to use graphical programs with containers. Graphical X11 programs require forwarding of the user-interface via the SSH connection established to the cluster. The nessecary SSH configuration is called "X-forwarding" and is configured by the user with command-line options. --- ### Overview The Virgo cluster (including its [submit nodes][aquCl]) is prepared to forward display information[^NOfA2] from the X Window System[^asgPH] to the local screen of a user. Since X forwarding is considered insecure the communication is send over a secure SSH connection. This process is known as "X forwarding"[^W0VNt]. In order to execute X11 graphical applications inside a container on the cluster following requirement has to be met. In the container the **`xauth` program must be installed** which is the case for our [Virtual Application Environments][KwaHQ] (VAEs). Users building a custom container image need to make sure that the `xauth` program is available. In most cases if there are any X11 programs installed in the container, it's probable that Xauth has been included as dependency. [aquCl]: run-time.html#submit-node [KwaHQ]: ../overview/software.html#vae [^asgPH]: X Window System <https://en.wikipedia.org/wiki/X_Window_System> [^W0VNt]: What You Need to Know About X11 Forwarding <https://goteleport.com/blog/x11-forwarding/> [^NOfA2]: SSH Manual Page, Section X11 Forwarding <https://man.openbsd.org/ssh#X11_FORWARDING> ```bash # Test if `xauth` is installed in the container >>> apptainer exec $APPTAINER_CONTAINER which xauth /usr/bin/xauth ``` When `xauth` is installed, login to the container to test the functionality of X forwarding. Since there are no X applications installed in the VAEs we use an application loaded from [CVMFS][n7fWW] called Root[^CDWyR] for the following example: [n7fWW]: ../storage/cvmfs.md [^CDWyR]: ROOT Data Analyses Framework <https://root.cern.ch> ```bash # Login to the VAE'23 container... >>> ssh -X -J lxlogin.gsi.de vae23.hpc.gsi.de #<1> # ...load ROOT into the shell environment >>> source /cvmfs/fairsoft.gsi.de/debian10/fairsoft/nov22p1/bin/thisroot.sh #<2> # Start the ROOT interpreter... >>> root #<3> ------------------------------------------------------------------ | Welcome to ROOT 6.26/10 https://root.cern | | (c) 1995-2021, The ROOT Team; conception: R. Brun, F. Rademakers | | Built for linuxx8664gcc on Dec 16 2022, 14:50:00 | | From tags/v6-26-10@v6-26-10 | | With c++ (Debian 8.3.0-6) 8.3.0 | | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q' | ------------------------------------------------------------------ # ...launch an X11 application root [0] new TBrowser(); ``` 1. Login with `ssh` to a VAE using the **option `-X` to enable X forwarding** (more details in the following sub-section). 2. After login load the ROOT application into the shell environment. Note that ROOT is one example for an X11 application, you could **start any X11 program to verify if X forwarding is properly enabled**. 3. When Root is started execute the command `new TBrowser();` to start the ROOT object browser which should forwarded to your local screen. If the browser starts you can close it by selecting _Browser » Quit Root_ from the menu. If you want to start your own container the sequence is similar. Instead of direct login into a VAE, login in to a (bare-metal) submit node and start your container: ```bash # Login to a submit-node (a non VAE environment) >>> ssh -X -J lxlogin.gsi.de virgo.hpc.gsi.de # We use a pre-build VAE container for this example >>> export APPTAINER_CONTAINER=/cvmfs/vae.gsi.de/vae23/containers/user_container-production.sif # Start a shell within a container... >>> apptainer shell -B /cvmfs $APPTAINER_CONTAINER # <1> # ...test if X forwarding is working Singularity> source /cvmfs/fairsoft.gsi.de/debian10/fairsoft/nov22p1/bin/thisroot.sh singularity> root #<2> ------------------------------------------------------------------ | Welcome to ROOT 6.26/10 https://root.cern | | (c) 1995-2021, The ROOT Team; conception: R. Brun, F. Rademakers | | Built for linuxx8664gcc on Dec 16 2022, 14:50:00 | | From tags/v6-26-10@v6-26-10 | | With c++ (Debian 8.3.0-6) 8.3.0 | | Try '.help', '.demo', '.license', '.credits', '.quit'/'.q' | ------------------------------------------------------------------ root [0] new TBrowser(); ``` 1. Since CVMFS is not mounted by default, make sure to [bind mount][fp5Bb] the directory `/cvmfs` explicitly with the Apptainer option `-B`. 2. Like in the previous example start an X11 graphical application to verify proper functionality of X forwarding. [fp5Bb]: environment.html#bind-mounts ### X-forwarding Options X forwarding is supported in two different modes: **trusted `ssh -Y`** and **untrusted `ssh -X`** X-forwarding (cf. footnotes). In summary untrusted X-forwarding restricts permissions which normally is preferable. Unfortunately trusted X-forwarding is actually the default behavior on Linux even if untrusted X-Forwarding is requested, so the user does not need to care about the differences. ::: {.callout-tip appearance="simple" title="X-Forwarding on Apple Mac OS X"} When using `ssh -X` on Mac OS the system defaults to untrusted X-forwarding which has implications. The most obvious difference is a timeout of only 20 minutes (default setting) after which no new connections can be opened. If you experience problems with X-forwarding after some time you probably used untrusted X-forwarding and ran into the time limit. Resolve this by passing a different timeout as parameter during SSH login: ```bash # ...login to a cluster submit-node (non VAE environment) ssh -o ForwardX11Timeout=8h -X -J lxlogin.gsi.de virgo.hpc.gsi.de ``` ::: ### Custom Home-Directory Environment Variable | Description --|----- `XAUTHORITY` | Defines the path to the Xauthority file (defaults to `$HOME/.Xauthority`) During start of a container Apptainer mounts the `$HOME` directory defined on the host as home directory inside the container. This can result in problems when using different operating systems inside the containers which may manipulate files in a users home directory. Avoid this problem by using a **home directory different then `$HOME`** when starting a container. Unfortunately a custom path to your home directory conflicts with the default behaviour of X-forwarding. Inside the container **the `.Xauthority` file needs to be available in the home directory**. Without additional configuration during SSH connection the `.Xauthority` file is expected in the `$HOME` directory on the target node by default. Configure a custom path to Xauthority by setting the environment variable `XAUTHORITY`: ```bash # Login to a cluster submit-node (non VAE environment) XAUTHORITY=~/custom_home/.Xauthority ssh -o SendEnv=XAUTHORITY -X -J lxlogin.gsi.de virgo.hpc.gsi.de #<1> # Optionally check the path to the `.Xauthority` file after login ls -l $XAUTHORITY # ...Start a shell in the container apptainer shell -H ~/custom_home -B /cvmfs $APPTAINER_CONTAINER #<2> ``` 1. Use the **option `-o SendEnv=` to propagate the `XAUTHORITY` environment variable** during SSH login to the target node. 2. Set the Apptainer option `-H` to specify the path to a custom home-directory. Note that the container environment binds the specified path to the expected default path of `$HOME`.