Table of Contents

Launching remote X11 processes

You can also launch processes with graphical user interface. There are two possible methods. As of version 3.0, WinGDB offers X11 forwarding feature, which is the preffered method. If your SSH server does not support X11 forwarding, you can alternatively use the legacy method.

Using X11 forwarding

In order to enable X11 forwarding, first you must ensure that your SSH server running on the target machine allows it. sshd supports this feature, however it must be enabled in the configuration files. For now, let's assume it is done already, as it is typically enabled by default. If the following steps do not work in your case, refer to the Configuration of the sshd server section below.

To enable X11 forwarding in WinGDB for debugging session, go to the Debug page in the Properties and set Enable X11 forwarding to Yes. This setting is enabled per project, solution or launch session.

To enable X11 forwarding in WinGDB for remote shell connections, open the Edit session dialog and set Enable X11 forwarding to Yes.

How does it work?

When an X11 program starts on the target Linux machine, it checks the DISPLAY environment variable. It can contain either an IP address of some other machine where the actual monitor and keyboard is located (and the X-server is running), or just something like ":0.0" string which means the X-server is running locally and you are actually operating this particular machine. In the X11 forwarding scenario, your sshd server simulates the second case. It creates "fake X-server" which can be connected to like a real one. But instead of displaying anything, it transfers all the data through SSH connection, in both directions.

On the other side of the connection (your Windows computer), real X-server must be running. The X-server on Windows machine listens for connections on port 6000. All that WinGDB must do is to connect to this port and forward all incoming and outgoing data through the SSH channel mentioned above. It acts just like a pipe. The user program on the target machine does not see any difference, as the whole tunneling process is transparent.

Configuration of the sshd server

sshd has two relevant configuration files. In /etc/ssh/sshd_config the following option must be set:

    X11Forwarding   yes

Also to avoid conflicts with remotely running real X-server (if the machine is e.g. a laptop with own display), the following option may be used:

    X11DisplayOffset   10

The second file of interest is /etc/ssh/ssh_config. It allows per-host configuration. The relevant options are:

    Host *
        ForwardAgent yes
        ForwardX11 yes
        ForwardX11Trusted yes

If your internal network has high security requirements, it is recommended to consult your network administrator to do required configuration changes.

Automatic launch of Xming X-server

As mentioned above, you need some X-server running locally on your Windows machine. We suggest using the popular Xming X-server. For this one, WinGDB has an option to start the server automatically if there is none already listening. To enable that option, first install Xming and provide the installation path in WinGDB Preferences on General page:

Next, go to the X11 page on the Preferences and set the following options:

The second one is optional and allows you to specify any command line arguments to the X-server. By default, there is "-multiwindow" argument supplied, which enables internal window management in Xming. It will display each connected remote program in separate window.


X11 forwarding can be used only when launching processes -- it does not make sense when attaching, because the program has already connected itself to some X display. Also currently the X11 forwarding can be used only in the Native Linux mode. Indirect and embedded modes are not supported. It does not seem to be very significant on embedded devices, as they have own displays. If you need X11 forwarding for these modes, please contact our support.

Using the legacy method

There is also a different (legacy) method which does not involve SSH. In this scenario, the program on the remote machine directly connects to port 6000 on the local machine. This has some serious drawbacks:

Since there are lot of additional configuration needed for this method, the X11 forwarding through SSH method is recommended. However, the legacy method must be used in WinGDB versions prior to 3.0, which do not support X11/SSH forwarding.

Table of Contents

Copyright (C) 2008-2019 SOFT-ERG. All rights reserved.