Gentoo Wiki



SSH Basics

Tips & Tricks

Other Gentoo-wiki SSH


Basic X11 Forwarding Over SSH

Let's assume that you have an X application on a remote machine that you need to run, and you want it to display on the X-server installed on your local machine. One way to run this remote application is to use X11-Forwarding. This guide explains how to setup X11-Forwarding on your machine. From the perspective of SSH, the remote machine is the server and your local machine is the client. From the perspective of X, the program on the remote machine is the X client, and X server runs on your local machine.

Emerging OpenSSH Server

Your server most probably doesn't have X11 server installed. Make sure X flag for openssh is set then compile.

File: /etc/portage/package.use
 net-misc/openssh X

So emerge -pv openssh will display:

 net-misc/openssh  USE="X...

It will pull x11-apps/xauth and the rest of necessary packages.

Server Setup

X11Forwarding needs to be enabled on the sshd server. Do this by making the following edit: (Please be sure to edit the file sshd_config not ssh_config !)

File: /etc/ssh/sshd_config


X11Forwarding yes


After you make these changes, you will need to let sshd reload its configuration so the changes will be accepted:

/etc/init.d/sshd reload

Don't forget to log out and log in to the server for this change to take effect.

Note: one reason for receiving the error messages
xterm Xt error: Can't open display: your_client_name:0.0
may be that X11Forwarding is not enabled on the server.

Running single apps

$ ssh -X <remote_server> /usr/kde/3.5/bin/kcontrol

Client Setup

The client does not need any extra configuration. In order to connect to the server and use port forwarding, issue the following command:

ssh user@remotebox -X

The above will work from Apple's X11 running under 10.3 - Panther.

Under 10.4 - Tiger - use:

ssh user@remotebox -Y
Note: see also 'BadAtom? BadWindow?' below for other cases where -Y may be needed instead of -X.

Also verify that X is running without the -nolisten tcp option.

-X vs -Y

ssh -X is also known as secure X11-forwarding: it's secure, i.e., the server(running sshd) won't be able to spy on the client (key-logging etc...) ssh -Y is also known as insecure X11-forwarding: it's not secure but it can run more applications

Also, you may wish to use compression to speed things up.

ssh user@remotebox -YC


ssh user@remotebox -XC

Verify the DISPLAY

Now verify that the DISPLAY variable points to the display created by sshd (normally localhost:10.0):

Code: echo $DISPLAY

If it points to the display of the connecting client machine, you need to manually set it:

Code: echo $DISPLAY
export DISPLAY=localhost:10.0

Start Working

You should then be able to start any X application on the remote machine and have it display on your local machine. For example,

xterm &

should display a new xterm window on the screen of the local machine.

No xauth data

If you get this warning:

 Warning: No xauth data; using fake authentication data for X11 forwarding.

Add this to the end of /etc/ssh/ssh_config

 Host *
   XAuthLocation /usr/bin/xauth

This is needed as ssh defaults XAuthLocation to /usr/openwin/bin/xauth while on Gentoo it is supposed to be /usr/bin/xauth

Using after su or sudo

After doing su or sudo to root (or other user) Xforwarding should stop working, it's necessary to define $DISPLAY and $XAUTHORITY variables (for example):

 export DISPLAY=localhost:10.0
 export XAUTHORITY=/home/user_with_xauthority/.Xauthority

BadAtom? BadWindow?

If you get the BadAtom error like this:

 X Error of failed request:  BadAtom (invalid Atom parameter)
 Major opcode of failed request:  20 (X_GetProperty)
 Atom id in failed request:  0x6e
 Serial number of failed request:  20
 Current serial number in output stream:  20

or a BadWindow error like this:

 The program 'gtk-demo' received an X Window System error.
 This probably reflects a bug in the program.
 The error was 'BadWindow (invalid Window parameter)'.
   (Details: serial 3555 error_code 3 request_code 38 minor_code 0)
   (Note to programmers: normally, X errors are reported asynchronously;
    that is, you will receive the error a while after causing it.
    To debug your program, run it with the --sync command line
    option to change this behavior. You can then get a meaningful
    backtrace from your debugger if you break on the gdk_x_error() function.)

Try adding:

       ForwardX11Trusted yes

to the /etc/ssh/ssh_config or ~/.ssh/config on the machine that you ssh from, under the hostname or IP of the machine where the program runs.

Like this:

       ForwardX11 yes
       ForwardX11Trusted yes

Please note that recent openssh implementations (>=4.4 at the very least) have changed their behaviour regarding the -X and -Y options. As most X applications know nothing about the XSECURITY extension it is required to use the -Y option to run them. Ssh won't tell you anything different from the above cases but if you get badwindow errors try with -Y. In these same versions the ForwardX11Trusted option seems to be gone as sshd complains about it and refuses to start.

Forwarding Automatically

If you wish to use X-forwarding without the -X argument, edit your /etc/ssh/ssh_config or ~/.ssh/config and add an entry

File: /etc/ssh/ssh_config or ~/.ssh/config
Host remotebox
ForwardX11 yes

Or alternatively if you want to enable it system-wide

Host *
ForwardX11 yes

See also

Retrieved from ""

Last modified: Thu, 03 Jul 2008 05:39:00 +0000 Hits: 66,887