Xdebug for remote server not connecting
Debugging PHP on a remote Linux server from a local development machine using NetBeans is a classic workflow, but it hinges entirely on one misunderstood concept: the direction of the connection. When you see the status bar message "Waiting For Connection (netbeans-xdebug)" followed by a timeout, the issue is almost never that Xdebug is uninstalled or that port 9000 is blocked on the server.
The error stems from the fundamental architecture of the remote debugging protocol. Xdebug does not initiate a connection to your IDE. Instead, it waits passively for your local debugger (NetBeans) to connect back to the server. This behavior is controlled by the xdebug.remote_host and xdebug.remote_port settings in your PHP configuration.
The Critical Configuration Error
In the scenario described, the server configuration shows:
xdebug.remote_host=localhost
xdebug.remote_port=9000
This is the root cause of the failure. Setting remote_host to localhost instructs Xdebug to listen for incoming connections on the loopback interface (127.0.0.1). When your local machine attempts to connect to http://your-server-ip/debugger.php, the connection request arrives at the server's network stack. However, because Xdebug is configured to only accept connections from localhost, it silently ignores traffic coming from your external IP address.
To fix this, you must change the listening interface. The configuration should point to the actual IP address of the remote server where NetBeans resides. Since your goal is for a team with different computers to debug, you have two options:
- Specific IPs: Configure
xdebug.remote_hostto a specific IP that acts as an entry point. - Wildcard (Recommended): Change
xdebug.remote_hostto*. This tells Xdebug to accept connections from any remote source on the specified port.
Update your php.ini file on the Ubuntu server accordingly:
zend_extension="/usr/lib/php5/20090626+lfs/xdebug.so"
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=* # Changed from 'localhost' to allow remote connections
xdebug.remote_port=9000
Firewall and Network Considerations
Once the configuration is corrected, the next hurdle is often the network layer. Even with remote_host set correctly, if a firewall (such as iptables, ufw, or an AWS Security Group) blocks incoming traffic on port 9000, the connection will still time out.
You must ensure that UDP and TCP traffic on port 9000 is allowed through to the web server process. On Ubuntu, if you are using UFW, run:
sudo ufw allow 9000/tcp
If you are using iptables, ensure a rule exists for the new connection tracking state and the specific port before the packet is dropped.
Verifying the Fix
After applying these changes and restarting your web server (e.g., service apache2 restart or systemctl reload php-fpm), verify that Xdebug is listening correctly. You can inspect this by checking the process list on the remote server:
netstat -tlnp | grep 9000
You should see a line indicating that PHP/Apache is listening on 0.0.0.0 (or the server's primary IP) and port 9000, rather than just 127.0.0.1.
If your team members are connecting from various networks, you might also consider binding to a specific interface if security requirements dictate that you do not want to expose the debugger port to the public internet. In production environments, this is often handled by placing the debugger port on an internal network segment or using Docker networking to isolate the debug traffic.
For large-scale Laravel applications where debugging is critical but security is paramount, many teams opt for IDEs that support cloud-based debugging or utilize tools like PhpStorm with its own remote debugging integration, which can sometimes offer more granular control over connection timeouts and protocol versions compared to the legacy Xdebug 2.x stack. However, if sticking with NetBeans and Xdebug, ensuring remote_host is set to * and the firewall is permissive for port 9000 resolves the "Waiting For Connection" loop.