Become a Patron!

My Amazon wishlist can be found here.

Life Line

Debugging with multiple users

As author of Xdebug, people ask me often the question how to handle the case in teams when there is one development server and multiple developers working on the same project on that server. Xdebug only allows you to specify one IP address to connect to (through xdebug.remote_host ) while doing remote debugging. It does not automatically connect back to the IP address that runs the browser the request the PHP scripts because of security reasons. You don't want everybody on the Internet to be able to run a debugging session against your code for example. There is no problem if all developers are working on a different project, because the xdebug.remote_host setting can be made for each directory (through Apache's .htaccess functionality). However, for the case where multiple developers work on the same code, the .htaccess trick won't work as the directory in which the code lives is the same.

Now, in order to solve the above mentioned issue, you will need to run a DBGp proxy. DBGp is the protocol, designed by ActiveState and myself to facilitate communication between an IDE (such as Komodo, or any of the other listed clients ) and PHP+Xdebug. A DBGp proxy is a bit of software that acts as a redirector for DBGp streams. In order to make things work for multiple developers and one source base, you set Xdebug's xdebug.remote_host setting to the machine on which the DBGp proxy runs. This is most likely going to be on the same machine that acts as development server, so that the xdebug.remote_host setting should be set to "" (i.e. localhost). The proxy server the listens for IDE connections. An IDE needs to register itself with the DBGp proxy by using the proxyinit command. This command requires an "idekey" that is a unique identifier for each client (IDE). Every developer should have its own unique idekey (I usually just pick my name), and this idekey should be configurable in the IDE. For Komodo, it's at Edit->Preferences->Debugger->Connection->"I am running a debugger proxy and Komodo should use it"->"Proxy Key". In Komodo you also need to select "a system-provided free port" in the same configuration panel. When initiating the debugging session from the browser with either XDEBUG_SESSION_START=session_name as GET/POST/COOKIE parameter, or export XDEBUG_CONFIG="idekey=session_name" from the command line, make sure to change "session_name" to the idekey as configured in your IDE. (See the documentation on how to set this up). The Xdebug Firefox extension also has a setting for this. You have to configure Xdebug's xdebug.remote_host setting to the IP address of the machine that the proxy runs at. Xdebug itself does not see a difference between either the proxy and a normal IDE. But the proxy itself now knows because of the configured idekey on how to forward the requests and responses to the correct client.

You can find the DBGp proxy code as part of the python remote debugging package that ActiveState provides. By default it listens for IDE registrations at port 9001, and for Xdebug connections at port 9000. To run the proxy, do:

tar -xvzf Komodo-PythonRemoteDebugging-5.1.3-28369-linux-x86_64.tar.gz
cd Komodo-PythonRemoteDebugging-5.1.3-28369-linux-x86_64
cd bin

This outputs:

INFO: dbgp.proxy: starting proxy listeners.  appid: 30430
INFO: dbgp.proxy:     dbgp listener on
INFO: dbgp.proxy:     IDE listener on

Running a DBGp proxy also allows you to avoid NAT issues where (as seen from PHP+Xdebug on the server) all connections seem to come from the same IP (because your internal network is NATted). In this case, you can simple run the dbgp proxy on your NAT machine, configure xdebug.remote_host setting to the IP address of your NAT machine, and configure the IDEs to connect to the proxy running at <NAT-machine>:9001.

As a last note; there is a patch to allow the connect-back-to-requesting-IP-address functionality that is not available directly in Xdebug. This patch, written by Brian Shire and Lucas Nealan of Facebook made its way into Xdebug 2.1. However, great care should be taken by using this functionality. It does not make the NAT situation as outlined above work however.


This article has a short URL available:


Hi Derick,

thanks for the nice article, this works pretty well. Just one question: If security is really the only reason for having this overhead, why not add some IP whitelist to the configuration setup? I would find this much easier especially when developing in internal networks, where everyone is trusted.

Anyway, thanks a lot for the great work you've been doing.

Regards, Michael

I´m agree with Michael, in Zend Debugger you can put a list of IP (whitelist, instead of unique IP). It´s so simple... You can put: zend_debugger.allow_hosts=,,

Or you can put: zend_debugger.allow_hosts=

Or a combination: zend_debugger.allow_hosts=,

Could that be that your info about the debug proxy is outdated? I downloaded this: and I got no bin directory, just a for different (?) PHP versions.

+1 on the whitelist approach, if it's possible. My company is in exactly this situation, and we're looking into migrating from Zend Debugger to XDebug. Being able to just whitelist our internal subnet rather than adding extra configuration to everyone's IDE (we don't all use the same IDE) would greatly simplify the process.

@Roland: No, you need to download the python package (that's the reason why I made it bold in the article ;-) )


You need to download the Python Remote Debugging package to get the dbgp proxy:

The file you need from the above tgz is: bin/dbgpproxy

Regard, Jeroen Vermeulen - WHITE new media architects (Dutch)

So I started the proxy, and it's listening as shown in the article. Now, I do:

export XDEBUG_CONFIG="idekey=1"

And start VIM with the gdbp plugin and having:

let g:debuggerPort = 9001

in my .vimrc.

Vim complains that it can't have the port.

Can I set this up with vim? What am I doing wrong?



Just to clarify, do IDEs maintain the connection to the proxy on 9001 and the proxy passes the data over that connection, or do the IDEs still have to accept connections on port 9000 from the proxy?

Here are a couple of ideas for a server that is off site but you still want to debug.

SSH tunnel: create a tunnel with putty, the only problem is that there can be only one port 9000 setup, so only one developer at a time.

VPN: create a site to site VPN and make sure to hit the server with the VPN based IP address. this will allow multiple developers when using multiple session keys. You will need to use the new feature introduced in 2.1 xdebug.remote_connect_back. It will attempt to connect back to the your machines IP address if your VPN is setup properly.

Otherwise the proxy will be the only way to get from the off site server to connect to multiple developers back on your network.

Since "xdebug.remote_connect_back" exists proxy Komodo-PythonRemoteDebugging is useless when Apache Web Server can ping IDE developer desktop. With is the case, when both are on the same network or can ping each other in both direction through a VPN.

Nevertheless when running a multi-users environement with a NAT firewall, then not only you need Komodo-PythonRemoteDebugging but your also have to hack it.

In line 333 replace line add=xxx with addr = ['',long(idekey)] this will force proxy to send debug packets attached to a given IDE key to localhost/IdeKey [note your IdeKey should be unique to targeted server an usable as port number ie:user1=9001 user2=9002.... user999=9999]

Then start an SSH tunel on each user desktop to transfer packets from web server to developer desktops. If your IDE wait for Xdebug packet on port 9000 use: ssh -R IDEKEY:localhost:9000 MyWebServerPublicIpAddr

With this model you may have multiple developpers debugging a single webserver running behing a NATed firewall

Add Comment


Will not be posted. Please leave empty instead of filling in garbage though!

Please follow the reStructured Text format. Do not use the comment form to report issues in software, use the relevant issue tracker. I will not answer them here.

All comments are moderated