Table of Contents Setting Up Your Login for Improved Graphics Performance...... 1 X11 Forwarding...... 1 VNC: A Faster Alternative to X11...... 3 X2Go: An Alternative to X11 and VNC...... 8 Setting Up Your Login for Improved Graphics Performance

X11 Forwarding

To run X applications (such as xclock, emacs, totalview, etc) on the X client host (for example, a NAS system such as pfe21, etc.) and display them back to an X server (such as your local system), the simplest way is to use SSH X11 Forwarding.

If you are using a NAS-supported workstation or compute server, X11 Forwarding is already set up for you. The following command activates SSH X11 Forwarding automatically: your_local_system% ssh hostname.nas.nasa.gov

Most modern SSH client support this option (for example, Cygwin, TeraTerm, PuTTY, Unix, and ). To use SSH X11 Forwarding, the SSH server-side daemon (sshd) configuration file must contain the entry:

X11Forwarding yes to support the forwarding capability. All NAS-supported hosts (including all workstations and compute servers) honor this setting in the default sshd_config file (for High End Computing systems and Linux systems, it is /etc/ssh/sshd_config; for Mac systems, it is /etc/sshd_config) For other non-NAS machines, ask your system administration to set this in the sshd_config file.

In addition to setting X11Forwarding yes on the SSH server side (for example, a NAS machine), it is recommended that ForwardX11 yes is also set in the ssh_config file on the SSH client host (for example, your local system). By default, NAS and HEC system configurations will enable these settings for both client and server. If ForwardX11 yes is not set in the ssh_config file by the system administrator of your local system, you can set it in your ~/.ssh/config file or use the -X option of SSH.

Other parameters related to the performance of X11 Forwarding are handled by the NAS-recommended ssh_config file. If you are on a NAS-supported system, no action is needed in setting these parameters yourself. If your local system is not supported by NAS and you would like to get configuration ideas, you can look at /etc/ssh/ssh_config on any NAS high-end computing system, such as pfe[20-27].

Example

To run an X11-based application, for example, xclock, on pfe21.nas.nasa.gov and have it displayed on your local system, do the following: your_local_system% ssh pfe21.nas.nasa.gov ------

* * * W A R N I N G W A R N I N G * * *

U.S. GOVERNMENT COMPUTER If not authorized to access this system, disconnect NOW. .... ------** PFE21 ** .... pfe21% xclock

To run an X11-based application on a NAS-supported desktop, follow the example below:

Setting Up Your Login for Improved Graphics Performance 1 your_local_system% ssh sfe1.nas.nasa.gov sfe1% ssh a_nas_desktop a_nas_desktop% xclock

If ForwardX11 yes is not set in either the ssh_config file or the ~/.ssh/config file of your local system, use: your_local_system% ssh -X hostname.nas.nasa.gov

WARNING: The SSH daemon sets the DISPLAY environment variable by itself. DO NOT RESET it to point to display zero (for example, setenv DISPLAY your_local_system:0), otherwise SSH X11 Forwarding will not work. WARNING: For each new login, the .Xauthority file gets updated. If you are over your quota, this file cannot be updated and you get the error:

/usr/X11R6/bin/xauth: error in locking authority file /u/username/.Xauthority

X11 Forwarding will not work if you receive this error.

X11 Forwarding 2 VNC: A Faster Alternative to X11

Virtual Network Computing (VNC) software provides a way to reduce X11 overhead on high-latency networks such as the Internet. In practical terms, once a VNC session is underway, latencies are on the order of seconds rather than minutes. VNC can make remote X11 applications useful instead of being tedious and non-productive.

The principle of operation involves a host server process (for example, Xvnc) that communicates with X11 applications running on Pleiades. The host server process transmits images and image updates using a low-overhead protocol to the remote system's viewer client.

Security and Firewalls

In the NAS environment VNC traffic is carried by a SSH tunnel, similar to the way SSH is used to tunnel X11 traffic. Using an SSH tunnel provides security because SSH encrypts tunnel traffic in both directions. If you are already using SSH, then VNC traffic will travel to/from NAS systems over current connections and through current firewalls. There is no need for any additional communication updates or authorizations.

Where is the VNC Software?

The Pleiades system runs on Linux. All of the necessary VNC software is installed in /usr/bin.

You do not need to run an X11 server on the remote system (your local system) because in the VNC environment, all of the X11 work is done on the Pleiades front-end systems (pfe[20-27]). However, you do need a VNC client viewer. The client might already be installed in many Linux distributions and on recent versions of Mac OS X; if it is not installed on your system, you will need to download the client.

If you have a NAS-supported system, please note that:

• For NAS-supported Linux workstations, a VNC client viewer (RealVNC version 4.1.2) should be installed in /usr/bin/vncviewer. • For NAS-supported Mac workstations, you can download a VNC client called TigerVNC from the TigerVNC website.

If you have a Windows desktop system, you can download free VNC clients from the following websites:

• Real VNC • Tight VNC • UVNC • TigerVNC

Ask your local system administrator for help to install the VNC client software.

Steps to Establish a VNC Session

In the following steps, pfe24 is used as an example; you can substitute another PFE.

Note: Although there are other ways to establish a VNC session, this method is convenient as it does not require you to manually find an available display number to use.

VNC: A Faster Alternative to X11 3 Before You Begin

VNC is much easier to use if you set up SSH Passthrough on your local system. In your .ssh/config file on your local system, you do not need to enable SSH X11 forwarding, but you must include the line ForwardAgent yes.

Known Issue: Make sure you do not have a MATLAB, Tecplot, or FieldView module loaded when you invoke vncserver. Once the VNC session is established, you can load the module.

Step 1: Connect to the PFE

Once SSH Passthrough is set up properly, you can establish a SSH connection from your local system to pfe24: your_local_system% ssh pfe24 pfe24%

Step 2: Run the vncserver Command on pfe24 vncserver is a script that starts/stops/kills the actual VNC server, Xvnc.

The first time you invoke vncserver on a server, you will be prompted to create a password for VNC that is up to 8 characters in length. (If you create a longer password, it will be truncated to 8 characters.) This password is encrypted and saved in the $HOME/.vnc/passwd file on the server. Once this is done, you will not be prompted for a password on the server when you invoke vncserver for subsequent VNC connections.

Run vncserver as follows: pfe24% vncserver -localhost

You will require a password to access your desktops.

Password: <--- type in a password of your choice

Warning: password truncated to the length of 8. Verify: <-- retype your password

New 'X' desktop is pfe24:25

Creating default startup script /u/username/.vnc/xstartup Starting applications specified in /u/username/.vnc/xstartup Log file is /u/username/.vnc/pfe24:25.log

There are a few options to the vncserver command, such as :display (for setting the display number), -geometry (for setting the desktop width and height in pixel), etc. The -localhost option shown in the above example is a local security option that you should use all the time. It must appear as the last option or it won't get processed.

Similar to an X11 session, a VNC session uses a display number. If not supplied, the vncserver searches over the valid range from 0 to 99 and assigns the next free display number for your session. In the above example, a display number of 25 is assigned.

Step 3: Create a SSH Tunnel from Your Local System to the Server

VNC: A Faster Alternative to X11 4 The next step is to create a SSH tunnel from your local system to the server. This is done by first escaping into an SSH sub- and specifying a local client's port number and a server's port number to use. The default SSH escape characters are ~ (upper case 'C'). If you do not get the SSH prompt, repeat the ~C. pfe24% ~C ssh> -L 59xx:localhost:59xx Forwarding port.

At the SSH prompt, provide a local client port and a remote server port. VNC by default uses TCP port 5900+xx. Thus, it is common to provide the value 59xx for both the local client port (the number before localhost) and server port (the number after localhost). The value for xx is obtained from the final output from the vncserver startup command. In the example shown in Step 2, a vncserver was started on pfe24:25, so in this scenario xx would have a value of 25. The port number would therefore be 5925.

Note that the client port number and the server port number do not need to be the same. Some may suggest using a very high client port number such as 22222 or 33333 since high port numbers are less likely to be reserved for other purposes. For example: pfe24% ~C ssh> -L 22222:localhost:5925 Forwarding port.

The maximum number allowed for the client port is 65535. Avoid using the local port numbers 0-1024 (root privilege required), 5900 (for Mac systems, reserved for some products), and 6000-6063 (reserved for local X window server). Use the netstat -an command to check what local port numbers have been used: your_local_system% netstat -an | less tcp46 0 0 *.5900 *.* LISTEN tcp4 0 0 *.22 *.* LISTEN

The above example shows local ports 5900 and 22 are in use and should be avoided.

Step 4: Start the VNC Viewer Application on Your Local System

• If your local system is a Mac and you have "Chicken of the VNC" installed, launch it. Open the Preferences panel from the "Chicken of the VNC" menu and select the Performance tab. Make sure the "Frontmost Connection" slider is not at its highest setting. If it is, move it down one notch. Close the Preferences panel. Now, open a new connection using the "New Connection" item from the "Connection" menu.

In the popup window "Connect", enter localhost:22222 in the Host field (if your local port number is 22222 from Step 3), and your VNC password in the Password field. Then click on the "Connect" button. • If your local system is a Linux system, run:

your_local_system% vncviewer localhost:localportnumber

You should get a password prompt. Enter your VNC password that you created on the server.

The localportnumber is the one you use in step 3. For example, if you choose 22222 as your local port, run:

your_local_system% vncviewer localhost:22222

VNC: A Faster Alternative to X11 5 If everything goes well, the Xvnc server will send a X11 display to your local system that will appear as an in the viewer's window.

The default window manager is , and there are a couple other window managers to choose from in the /usr/bin directory, including FVWM, MWM, IceWM, and GNOME. The GNOME window manager provides a GUI view of a user's files and includes a few useful tools.

To use a non-default manager, modify your $HOME/.vnc/xstartup file on the host where your start vncserver. For example:

#twm & /usr/bin/-session

You can also change the size and position of the xterm in your viewer's desktop by changing the values in the following line of the $HOME/.vnc/xstartup file on the host where you start vncserver. For example: xterm -geometry 80x24+10+10 -ls -title "$VNCDESKTOP Desktop" &

This specifies an xterm that is 80 characters wide, 24 characters high, at a position (10 pixels, 10 pixels) from the upper left corner of the VNC viewer's desktop.

TIP: The modifications to the xstartup file only take effect for a new VNC connection. You will need to stop the existing VNC server and start a new one. The window manager's xterm is running on pfe24 itself. From this xterm, you can do tasks that you normally do on pfe24—for example, start an X application or ssh to other NAS systems. PBS jobs can also connect to a VNC session. Specifically, in the xterm in the viewer's window, submit an interactive PBS job with the -X option (upper case 'X') and do not reset the DISPLAY variable before starting an X application: pfe24% qsub - - -lselect=1:ncpus=28:model=bro,walltime=1:00:00 qsub: job 1030046.pbspl1.nas.nasa.gov ready PBS> xclock

TIP: Your VNC session and the interactive PBS job will continue to be active even if you disconnect from the Pleiades front end where you started vncserver. Assuming the PFE where you started vncserver is not down, you can reconnect to the same VNC session: simply ssh into the PFE (pfe24 in this example) and repeat steps 3 and 4 with the same port number that you used before (5925 in this example). If the interactive PBS session has not reached its wall time limit, the PBS job will be there waiting.

Step 5: Shut Down the Server When You are Done with the VNC Session

On each VNC server, there are a limited number of VNC sockets available. At the end of a session, be sure to exit the VNC application on your local system so that others can use the sockets. In the terminal window where you started up VNC, use the following command to clean up a few temporary socket files vncserver had created. pfe24% vncserver -kill :xx (supply the original display number)

For example: pfe24% vncserver -kill :25 Killing Xvnc process ID 3435054

WARNING: Don't manually kill vncserver. Doing so will leave lock and socket files (for example, /tmp/.X11-unix/X25, $HOME/.vnc/pfe24:25.pid, etc.) on the server.

VNC: A Faster Alternative to X11 6 TIP: If you get a black screen on your VNC viewer, try the following methods to resolve the issue:

1. Check /tmp/.X11-unix for any existing VNC sessions, and clean them up by using the vncserver -kill :xx command, as described in Step 5 above. 2. If you normally load MATLAB, Tecplot, or other GUI application modules, unload them before you start vncserver. The LIBGL_ALWAYS_INDIRECT=y setting in these modules is known to cause the black screen. 3. If unloading the MATLAB and Tecplot modules does not solve the problem, use the twm window manager instead of or gnome-session in your .vnc/xstartup file. For unknown reasons, it is possible that after you resolve the black screen issue by using twm, you can revert back to using other window managers.

VNC: A Faster Alternative to X11 7 X2Go: An Alternative to X11 and VNC

Note: X2Go is an application that enables you to do remote visualization on Pleiades. Benchmarks performed by NAS staff show that X2Go provides much better performance than X11 forwarding. Although it is not as fast as VNC, X2Go has the benefit of letting Pleiades seem like your local system without the need for an additional window manager as in the case of VNC.

X2Go Client requires a local X11 server to display the remote sessions. The server you use depends on your local , as follows:

• Windows systems: an X11 server is provided with X2Go client. • Linux systems: the client component of X2Go uses the local Xorg server. • Mac OS X systems: you must install the XQuartz X11 server as an extra component.

The information provided in this article is mostly for use on Mac systems. Additional information for use on Windows and Linux will be added when we learn more about using X2Go on those systems.

Before You Begin

You must have SSH Passthrough set up for connection from your local desktop to Pleiades.

If XQuartz is not installed on your Mac, download it from this XQuartz site and install it. (Administrator privilege may be required for the installation.)

Enable the X2Go Server on Pleiades

The X2Go server (with some security modifications) is available as a software module on Pleiades: pfe% module avail x2go x2go/stable

In order to use X2Go, add the following to your .bash_profile on Pleiades (regardless of which shell you use): source /usr/local/lib/global.profile module load x2go/stable

Download the X2Go Client

You can download X2Go from the Getting X2Go web page.

• For Mac and Windows systems, choose the version closest to your current operating system's version number. • For Linux systems, read the information in the X2Go Package Repositories for GNU/Linux section of the web page.

Note: The steps in this article are based on the X2GoClient_latest_macosx_10_13.dmg version for Mac systems.

Install the X2Go Client

X2Go: An Alternative to X11 and VNC 8 A normal installation into the /Applications folder on a Mac system may require administrator privilege. If you do not have the administrator privilege, follow these steps:

1. On your Mac's desktop, create a subdirectory (for example, ~/Desktop/dir.x2go) and move the X2GoClient_latest_macosx_10_13.dmg file into that subdirectory. 2. Modify the extended attributes of that subdirectory with the -cr option of the xattr command, where -c clears all attributes and -r means recursive.

your_local_system% xattr -cr ~/Desktop/dir.x2go 3. Double-click the .dmg file in the dir.x2go directory to mount it. An x2goclient volume and a window containing an x2goclient.app icon will appear on your

desktop: 4. Drag the x2goclient.app icon from the window to your desktop, and eject the x2goclient volume. The x2goclient.app icon will now appear on your desktop.

Steps for Using X2Go for Remote Visualization

You can use either a Pleiades front end (PFE) or a compute node to do remote visualization using X2Go.

Note: Performance decreases substantially for both X2Go and VNC on a heavily loaded PFE. For best performance, do remote visualization on a compute node if you plan to run a graphically intense application.

Step 1: Create an SSH Tunnel

If You Are Using a PFE

If you want to use a PFE for X2Go, for example, pfe20, SSH into the PFE as follows: your_local_system% ssh -L 8222:localhost:22 pfe20 where 8222 is the local port on your local desktop and 22 is the remote port on the PFE. The remote port number must be 22. You can choose a different local port number—however, there are some restrictions on which ports can be used. In our testing, port numbers between 8000 and 9000 work properly as the local port for X2Go.

If you plan to establish two connections and switch between them from time to time, use different local port numbers for the two connections—for example, one connection uses 8222 and the other uses 8333.

X2Go: An Alternative to X11 and VNC 9 TIP: To keep your X2Go sessions easier to manage and troubleshoot, we recommend that you select and keep the same PFE as your X2Go remote server, unless that PFE is very busy or unavailable. Once you establish the SSH connection, continue with Step 2: Start the X2Go Client Application.

If You Are Using a Compute Node

If you want to use a compute node for X2Go, complete these steps.

a. Log into a PFE and submit a PBS job in order to access a compute node:

pfe% qsub -I -q devel -lselect=1:ncpus=28:model=bro PBS r601i0n7>

Alternatively, you can reserve a dedicated compute node and SSH into your reserved node (for example, r601i0n7):

pfe% pbs_rfe --duration 10+ --model bro pfe% ssh r601i0n7 b. Create an SSH tunnel from your local system to the compute node:

your_local_system% ssh -o "StrictHostKeyChecking=ask" -L \ 8222:localhost:22 -o ProxyJump=sfe,pfe20 r601i0n7

Note: This command line is too long to be formatted as one line, so it is broken with a backslash (\).

Once you establish the SSH connection, continue with Step 2.

Step 2: Start the X2Go Client Application

Double-click the x2goclient.app icon on your desktop. A directory called ~/.x2go will be created on your local system the first time you do this.

As shown below, two windows will appear: an X2Go Client window, and a window in gray called Session preferences - New Session, where you can configure settings. This window opens on the Session tab and shows default settings.

X2Go: An Alternative to X11 and VNC 10 Notes:

• If you don't see the Session preferences - New Session window, find the x2goclient toolbar at the upper left of your desktop and select New session from the Session pulldown menu. • You might see a pop-up dialog window that asks you to deny or allow PulseAudio to accept incoming network connections. Unless you need audio from the remote server, we suggest you deny it. To prevent the message from appearing during future connections, disable PulseAudio in the PulseAudio settings pane of the Preferences panel, as shown below:

Step 3: Configure Your Session

In the Session preferences - New session window, configure your session as follows:

a. In the Session name field, enter a name of your choice. In these steps, we use the names PFE_XTERM (for a single xterm session, without a desktop), and PFE_ICEWM (for an IceWM window manager session, with a desktop—as in the case of VNC). The way to specify the Session type is described in substep 5, below.

X2Go: An Alternative to X11 and VNC 11 Note: Our benchmark results show that the performance of a single xterm session is better than an IceWM window manager session. b. In the Host field, enter: 127.0.0.1 This local host address cannot be changed. c. In the SSH port field, enter a local port number; for example, 8222 or 8333. We use the port number 8222 in the PFE_XTERM example, and 8333 in the PFE_ICEWM example. You can choose a different port number, as long as it is consistent with what you used in Step 1: Create an SSH Tunnel. d. Activate Try auto login (via SSH Agent or default SSH key) by checking the box. e. Under Session type, do one of the following: ♦ To run a single xterm application without a desktop: In place of KDE (the default setting), select Single application from the pulldown menu and enter /usr/bin/xterm in the Command field. ♦ To confine your Pleiades graphics activity into a single window on your local system: In place of KDE, select ICEWM from the pulldown menu. Note: PFE_ICEWM is the only selection that currently works. f. Optional: You can also configure the image quality on the Connection tab, and the width and height on the Input/Output tab. Nothing else needs to be modified. g. Click OK.

Note: A session configuration is kept even after a reboot of your local system. This makes it simpler to reuse the same session configuration for a newly established SSH tunneling connection in a future session.

If you want to permanently remove a session configuration, use one of these two methods:

• Click on the icon located at the lower-right corner of the small window similar to the one below, for each session configuration, then select Delete session.

• From the Session pulldown menu at the upper left of the x2goclient toolbar, select Session management and select a session configuration, then click Delete session.

Step 4: Connect Your Session

In the large X2Go Client window, type the name of the session to make a connection. The following events will occur:

• You may be prompted for your passphrase to unlock the key pair, or for your NAS username and password. Provide the answers as prompted. • A small window will pop up showing the status as connecting. The first time you try to connect, you may see a message similar to one of the following two:

The server is unknown. Do you trust the host key? Public key hash: 127.0.0.1:8222 - bc:dd:90.....

X2Go: An Alternative to X11 and VNC 12 or

The host key for this server was not found but another type of key exists. An attacker might have changed the default server key to trick your client into thinking the key does not exist yet. For security reasons, it is recommended to stop the connection attempt. Do you want to terminate the connection?

If you get such a message, the likely reason is that you have never connected to 127.0.0.1:8222 before. Therefore, it is OK to proceed with the connection and trust/accept the host key. • If the connection succeeds, records for the session will be created in the ~/.x2go and /tmp/.x2go-username directories of the X2Go remote server (i.e., the PFE used in your SSH tunnel). ♦ If you use PFE_XTERM, a single xterm window similar to the following will pop up:

♦ If you use PFE_ICEWM, a large green ICEWM desktop window (with the SUSE logo) will appear. The window is named using its Session ID — for example, X2Go-username-169-1600128286_stDICEWM_dp32. At the bottom of this window, click on fourth icon from the left to start an xterm window for the PFE. You can have multiple xterm windows on the ICEWM desktop. You can adjust the size and shape of the windows by dragging the corners.

In principle, you can repeat the instructions described in Steps 1 - 4 to establish more than one X2Go connection, as long as the local port numbers for the connections are different. For example, you can have one connection via port 8222 to pfe20 with session name PFE_XTERM, and another one via port 8333 to pfe20 with session name PFE_ICEWM. However, only one session at a time can be actively running. If you are running PFE_ICEWM, for example, and you want to run PFE_XTERM, you must first suspend or terminate PFE_ICEWM. See Step 6: Terminate, Suspend or Resume an X2Go Session for instructions.

TIP: If your connection appears to hang (a likely symptom is that the x2go process on your Mac consumes close to 100% CPU and there is audible noise from the fan), quit and restart the X2Go client and try again. If that does not help, you can try removing the .x2go directory on your local

X2Go: An Alternative to X11 and VNC 13 system and ~/.x2go_sessions file, ~/.x2go directory, and /tmp/.x2go-username directory on the PFE where the X2Go server is running.

Step 5: Run Your Graphics Application

In the xterm window for the PFE, you can run X applications such as xclock or xeyes. To run the X applications that are available through modules on Pleiades—for example, Tecplot, MATLAB, or Intel Vtune—with their GUIs, load the module before starting the application. For example: pfe% module load tecplot pfe% tec360

Note: The version of emacs in the current operating system has a known bug when used with x2go. Use emacs-x11 instead.

Step 6: Terminate, Suspend or Resume an X2Go Session

If you have an actively running session, you will see a panel similar to the following in the large blue X2Go Client window:

In the lower right corner of this panel, look for three small icons. From left to right, they represent: (1) Share Folder; (2) Suspend; and (3) Terminate.

Terminating the Session

If you do not plan to continue or resume a session, be sure to terminate it.

When you terminate a session, its records in the ~/.x2go directory on the PFE will be removed. A terminated session cannot be resumed.

To terminate a session:

• For PFE_XTERM, click the Terminate icon or simply exit from the xterm. • For PFE_ICEWM, click the Terminate icon, or click the far-left icon at the bottom of the green ICEWM desktop to log out and shut down.

X2Go: An Alternative to X11 and VNC 14 Suspending a Session

If your session gets disconnected, or if you suspend a session, you can resume at a later time and pick up where you left off, provided you reconnect to the same PFE as before.

To suspend a session:

• For PFE_XTERM, click the Suspend icon. • For PFE_ICEWM, click the Suspend icon, or simply close the green ICEWM desktop.

Resuming a Session

To resume a session:

1. If you have lost the SSH tunnel, re-establish the tunnel with the same local port and the same remote host. 2. From the X2Go Client window, select the session configuration to start, for example, PFE_ICEWM. The possible outcomes are:

♦ The session is automatically resumed. ♦ The reconnection appears to hang. If this happens, quit and restart the X2Go client. A window similar to the following should appear; click Resume.

References

• X2Go Documentation

X2Go: An Alternative to X11 and VNC 15