How to enable X11 Forwarding with SSH on Mac OS X Leopard

Apple Remote Desktop (ARD) or VNC is a wonderful invention if you want full control over a remote desktop, but what if you only want to access the user display of one single X11 program on a remote machine?

This is possible on Mac OS X with X11 Forwarding.

THIS ARTICLE HAS BEEN REWRITTEN (Manual set of the $DISPLAY variable is insecure!)


X11 environments on both the local and remote machine (see man X). Ensure network access for X11. In Mac OS X  on X11 Quartz check the authorization and client access options under Preferences in the Security pane.

Enable X11 Forwarding with the “X11Forwarding yes” option set in “/private/etc/sshd_config” for your SSH Daemon own local X11 host in order to recieve X11 client request back from  the remote machine through ‘ssh‘ with the -X option set.

Start or restart the Remote Login (SSH) Service  under System Preference / Sharing pane on Mac OS X. The SSH daemon should run on the remote machine as well!

See “man ssh”,  “man ssh_config” and “man sshd_config” for the complete explanation.

3 Simple Steps to X11 Forward on Mac OS X

1. Open  “Terminal” in Mac OS X Leopard.

2. ssh -X X11 Forward to your remote host (See “man ssh” for the use of the -X or -Y flag X11 forward):

ssh -X johndoe@123.456.789

3. Start your remote X11 program and view the user display on your local machine:

xeyes &

Voila it works! The X application will start up your X11 environment. Its quite easy to do X11 forwarding when you first get the hang of it.

Do elegant X11 stuff with ssh -X -f  like:

ssh -X -f user@remotehost xcalc -bg black -fg green

Caveat Notes:

Have the latest and updated versions of Mac OS X, Developer and X11.

3 Clues to successful X11 forwarding:

A. When you make changes to /etc/sshd_config remember to restart the Remote Login Service (SSH).

B. Remember to allow incoming access to X11 in the X11 preferences and through your firewall(s) and router!

C. And you have will of curse have to be accurate about your local and remote machine naming convention i.e. John-Does-iMac.local or Check with “echo $HOSTNAME”. On the remote machine you could also do a check with $REMOTEHOST (if set) to check your own machine name on the remote host.

NOT! Sometimes it is necessary to use xhost +remotehost and set the $DISPLAY environment variable manually on Mac OS X (something -X or -Y flag in ssh should normally do for you). Try “echo $DISPLAY” on the local machine and remote to get hints of the $DISPLAY status. You can always check your environment with “env” and “$”. On Mac OS X Leopard you use EXPORT with bash shell to set environment variables as opposed to tcsh that uses setenv. You should only set the $DISPLAY variable manually in a secure environment i.e. local network.

NEW! Do not set the DISPLAY variable on the client. You will most likely disable encryption. (X connections forwarded through Secure Shell use a special local display setting.)

If you have further problems try to use -v, -vv or even -vvv verbose flag with ssh to debug.

X11 Forwarding:
X11 Forwarding
Configurering and running X11 Applications on Mac OS X
X11 FAQ  - Technical Q&A QA1232
Technical Q&A QA1383 Enabling X11 Forwarding
Forwarding X11 from a Remote Computer to the Mac
ssh X forwarding debugging
Display Names

X Window System
The X Window System (Introduktion from FreeBSD Handbook)
XQuartz project (X11)

Command-Line Administration Version 10.5 Leopard (PDF) (Connecting to Remote Computers p. 31 – 37)
Introduction to Command-Line Administration Version 10.6 Snow Leopard (PDF) (Connecting to Remote Computers p. 27 – 33)

Connecting to Remote Computers p. 27 – 33
Introduction to Command-Line Administration Version 10.6 Snow Leopard (PDF)

Open Source X11
UNIX & Open Source downloads