Connecting Zend Studio to Zend Debugger over an SSH Tunnel

This article applies to:

[ Zend Studio, Zend Server ]
[ All operating systems ]


Normally, Zend Studio initiates the remote debugging session by sending a regular HTTP request to the debug server. This HTTP request contains return address parameters (IP address and port number) that the Zend Debugger uses when starting a new connection to Zend Studio in order to relay debugging information.

Regular debug session


In many environments, it may be the case that the debugging session is prevented by some network obstacles (firewalls, routers, proxy servers, etc.). To allow safe and effective bypassing of network obstructions you can setup an SSH Tunnel for remote debugging with Zend Studio. In this case, the process of establishing the debug session consists of two major steps:

  • Creating an SSH Tunnel
  • Instructing Zend Debugger to relay its traffic through the SSH Tunnel

To setup an SSH Tunnel you need first to tell the SSH daemon to open a listening port on the server and forward the traffic from this port to the port on your workstation, where Zend Studio is listening. Once this is done you need to instruct Zend Debugger to send the debug information not to the Zend Studio workstation directly, but through the created tunnel.

Debug session trough the SSH Tunnel


Since Zend Studio opens the listening port 10137 for establishing the debug sessions by default, we use this port number in our examples. If for some reason you are using a different port, make the necessary changes to adapt our instructions to your situation.


Creating an SSH Tunnel

To create an SSH Tunnel from a Linux and Mac OS X workstation use this command template:

ssh <Zend Studio listening port>:<port to open on the debug server> <user>@<debug server address>

For example:
user@workstation:~> ssh -R 10137: user@debugserver
user@debugserver’s password: <enter user’s password on the debug server>

Welcome to the Debug Server!
[/box]To create an SSH Tunnel from a Microsoft Windows workstation, you can use PuTTY. Run the program and configure it as described below:

    1. From the Category list choose Connection | SSH | Tunnels.

This will display the Options controlling SSH port forwarding page.

    1. In the Source port field enter “10137”.
    2. In the Destination field enter “”.
    3. From the options below select Remote.
    4. Click Add.

This will add the configuration to the Forwarde ports list.

    1. From the Category list choose Session.

This will display the Basic options for your PuTTY session page.

    1. In the Host Name field enter the name or the IP address of the debug server (you may use the “user@host” notation as well).
    2. In the Saved Sessions field enter a descriptive name.
    3. Click Save.

This will add the newly configured session to the Saved Sessions list where you can easily re-use it.

  1. Click Open to create the SSH Tunnel connection to the debug server.
  2. Enter the user name and password at relevant prompts.


login as: user
Using keyboard-interactive authentication.
Password: <enter user’s password on the debug server>

Welcome to the Debug Server!


Instructing Zend Debugger to Relay Its Traffic Through the SSH Tunnel

  1. In Zend Studio go to Window | Preferences.
    This opens the Preferences page.
  2. Navigate to the page PHP | Debug | Installed Debuggers.
  3. Select Zend Debugger and click Configure.
    This opens the Zend Debugger configuration dialog.
  4. Verify that the field Client Host/IP contains the loopback address

Zend Studio Installed Debuggers



If you are planning to debug your applications only via the SSH Tunnel, it is recommended to remove all IP addresses except the loopback address in the Client Host/IP field. This may significantly improve the performance of the debug session.



You should be able to verify that the SSH Tunnel is open in the remote shell session after the connection. Issue the following command to see that the SSH deamon is listening on the local port 10137:

[box]user@debugserver:~$ netstat -tln | grep :10137
tcp        0      0*               LISTEN
tcp6       0      0 ::1:10137               :::*                    LISTEN[/box]

The ultimate proof that your setup is correct is the possibility to start and conduct a remote debugging session.