[FDS-130] FusionDebug: Feature Focus – Non-Intrusive Debugging

Non-Intrusive Debugging

Non-Intrusive debugging has been introduced in FusionDebug 3.5, which allows breakpoints to only fire when requests are coming from a specified IP address. This makes it possible for a developer to debug and set breakpoints against a central server, leaving the system untouched and unaffected for everyone else.

This article will cover how to configure and use Non-Intrusive Debugging, the underlying implementation and a few tips on what to do if your breakpoints don’t fire when they are supposed to. The last section will also talk about the limitations of the Non-Intrusive Debugging feature in FusionDebug.

Configuration

Non-Intrusive Debugging can be enabled on any new or existent Debug Configurations in FusionDebug 3.5. This is done by entering the IP addresses to break on in the IP Restriction section available in the Connect Tab of the Debug Configuration to edit.

The IP Restriction feature in FusionDebug supports both IPv4 and IPv6 addresses, but there is no input validation so make sure these are entered correctly using standard IPv4 and IPv6 formats.

So for example say you only want breakpoints to fire when connecting locally, then you can enter 127.0.0.1 if connecting using IPv4 and 0:0:0:0:0:0:0:1 if using IPv6.

Multiple IP addresses can be specified by using a comma (,) to separate them, so in the previous example we can make sure that the breakpoints fire when connecting locally using either IPv4 or IPv6 by specifying them both like this: 127.0.0.1, 0:0:0:0:0:0:0:1

An example of this can be seen in the image below.

After the Non-Intrusive Debugging settings have been entered, click Apply to save the setting to the configuration. Please note that the debug session will have to be re-launched for the new IP Restriction properties to take effect.

Under the hood

When a request is made to the server being debugged in FusionDebug the connected IP address is compared to the ones entered in the Debug Configuration of the launched session.

FusionDebug does this by evaluating the CGI.REMOTE_ADDR variable for the request with the ones specified in the Debug Configuration screen. If the cgi.remote_addr variable matches any of the ones entered the breakpoints will fire as usual, otherwise they will not.

It is important to understand that FusionDebug can only evaluate the value that the ColdFusion server has stored. For example if the connection to the server is going through a proxy, FusionDebug will compare the IP address of the proxy and not the end user’s.

Also the entered IP addresses must exactly match the value of the cgi.remote_addr variable, no wildcards are allowed. For example you cannot enter 192.168.1.*, you will have to specify all the exact IP addresses to break on.

Adobe ColdFusion and Railo servers might also deal with different connection types differently and the value of cgi.remote_addr might differ slightly from server to server.

It is important to know that if the cgi.remote_addr variable cannot be evaluated, i.e. it has not been set properly, Non-intrusive Debugging will not function.

My breakpoints don’t fire

If you have enabled Non-Intrusive Debugging but the breakpoints do not fire or behave in the way you are expecting them to do, here are a few trouble-shooting tips.

IP addresses correctly entered

Make sure that the IP addresses to break on are specified correctly in the Debug Configuration using standard IP address notation and that no extra commas or dots have been introduced. Also make sure that the debug configuration settings have been saved.

IPv4 and IPv6

Make sure that you have not entered an IPv4 address when in fact the IP address reaching the server is an IPv6. Please note that different computers and operating systems will send different addresses depending on the network configuration. For example Microsoft Windows 7 has IPv6 enabled by default.
Also be aware that various servers will support different IP versions.

For example localhost can be specified as both an IPv4 and IPv6 address:
IPv4: 127.0.0.1
IPv6: 0:0:0:0:0:0:0:1

To be sure that the breakpoints fire on either the IPv4 or the IPv6 address both can be specified in the IP Restriction configuration, as in the image above.

Re-launch the debug session

It is not enough to just apply the new Non-Intrusive Debugging settings for the active Debug Configuration, but the actual debug session in FusionDebug has to be re-launched. This is because the IP Restriction properties are applied to the debug session at launch and cannot later be edited.

Inspect CGI.REMOTE_ADDR

If Non-Intrusive Debugging has been set up correctly but breakpoints still do not fire when they are expected to, a good thing is to actually check what value the cgi.remote_addr variable has been given.

One way to this is to have a CFML page containing this example code:

<cfoutput>remote_addr: #cgi.remote_addr#</cfoutput>

This will output the value of the cgi.remote_addr variable so that you can compare it to the ones entered in the Debug Configuration.

Another way is to inspect the value of cgi.remote_addr using FusionDebug. To do this you will have to disable Non-Intrusive Debugging by removing all the IP addresses in the Addresses field in the IP Restriction section of the Debug Configuration screen.

Once this has been done, apply the settings and re-launch the debug session and set a breakpoint on a page. Request this page from the machine you wish to enable Non-Intrusive Debugging for and the breakpoint should fire as normal.

You can now inspect the value of CGI.REMOTE_ADDR by selecting the Variables view tab in FusionDebug.

For Adobe ColdFusion:
Select the APPLICATION, REQUEST, SESSION, SERVER, CGI… Variable scope.
In this scope select CGI and scroll down the list of variables and locate the variable called REMOTE_ADDR.

For Railo:
Select the cgi Variable scope and scroll down the list of variables and locate the variable called remote_addr.

You can now copy the value of this variable and paste it in the Addresses field in the IP Restriction section of the Debug Configuration screen.

Proxy servers

If there is a proxy server between the user making the request and the server running ColdFusion, the value of the cgi.remote_addr variable will be set with the IP address of the proxy server and not the actual end user’s. This can create problems if there are multiple machines behind a proxy server and you only wish to break on a specified local IP.

Clear existent breakpoints

If breakpoints still do not fire when they are supposed to or behave in an unexpected way, it is a good idea to go to the Breakpoints view tab and delete all of the existent breakpoints and re-add them.

Sometimes breakpoints from an older version of FusionDebug will not work properly in a newer version, also if there is one bad breakpoint it might cause issues for other enabled breakpoints.

Limitations

There are many ways a request can be made to a ColdFusion server, for example http, flash remoting, web services, messaging gateway and more. We have tested FusionDebug using several different requests types and there is a DevNet article available covering this in more detail, “Debugging Flash Remoting and Gateway Messaging”.

As the Non-Intrusive Debugging feature in FusionDebug uses the value of the cgi.remote_addr variable for the request there will be cases when this variable is not being set and can therefore not be evaluated.

If you have specified IP addresses to filter breakpoints on and cgi.remote_addr doesn’t actually contain a value the breakpoints will not fire as FusionDebug would not know where the request came from.