mono-nat

h1. Debugging the reason why your router cannot be found

The uPnP specification is (generally speaking) badly implemented by a lot of router vendors. There are so many different quirks that I've come across that it's very hard to say whether or not a specific router will work with Mono.Nat. For the cases where your router does not work, here's how to debug the issue.

h2. Step 0: Enabling debug output

If you're running in a console application you can print debug information straight to the screen:

<pre>NatUtility.Logger = Console.Out;</pre>

If you want to log to a file, it's just as easy:

<pre>NatUtility.Logger = new StreamWriter (File.OpenWrite ("logfile.txt"));</pre>

If you fail to get past step 1 below, or just want all the debug output, you should enable verbose mode:

<pre>NatUtility.Verbose = true</pre>

h2. Step 1: Detecting available services

In order to detect what services are available on the local network, a udp broadcast message is sent. There are two kinds of message:

# The 'tell me everything you support' message

# The 'respond if you support service X' message

Mono.Nat uses the 'tell me everything you support' style message. I haven't come across a router which has failed to respond to this, though there are some which fail to respond to the second type of message. If your router fails at this step, then this is probably why. Typical output from this step is a dozen or so copies of the following:

<pre>

UPnP Response: HTTP/1.1 200 OK

SERVER: Ambit OS/1.0 UPnP/1.0 AMBIT-UPNP/1.0

EXT:

LOCATION: http://192.168.0.10:80/Public_UPNP_gatedesc.xml

CACHE-CONTROL: max-age=3600

ST: upnp:rootdevice

USN: uuid:e346a71d-99ef-86a6-3222-e9ba2bb3dfa0::upnp:rootdevice

UPnP Response: HTTP/1.1 200 OK

SERVER: Ambit OS/1.0 UPnP/1.0 AMBIT-UPNP/1.0

EXT:

LOCATION: http://192.168.0.10:80/Public_UPNP_gatedesc.xml

CACHE-CONTROL: max-age=3600

ST: urn:schemas-upnp-org:device:InternetGatewayDevice:1

USN: uuid:e346a71d-99ef-86a6-3222-e9ba2bb3dfa0::urn:schemas-upnp-org:device:InternetGatewayDevice:1

</pre>

h2. Step 2: Getting the service listing

If your router advertises one of the three services that Mono.Nat assumes will allow port forwarding, you will see output similar to this:

<pre>

UPnP Response: Router advertised a 'urn:schemas-upnp-org:service:WANIPConnection:' service

Found device at: http://192.168.0.10:80/Public_UPNP_gatedesc.xml

Parsed device as: 192.168.0.10:80

Fetching service list: 192.168.0.10:80

</pre>

h3. Step 3: Parsing a service listing

The service listing contains the details required to connect to the upnp service on the router. If the listing can be retrieved and parsed, you'll see output similar to this:

<pre>

192.168.0.10:80: Parsed services list

192.168.0.10:80: Found service: urn:schemas-upnp-org:service:Layer3Forwarding:1

192.168.0.10:80: Found service: urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1

192.168.0.10:80: Found service: urn:schemas-upnp-org:service:WANIPConnection:1

192.168.0.10:80: Found upnp service at: /Public_UPNP_C3

192.168.0.10:80: Assuming control Uri is relative: /Public_UPNP_C3

192.168.0.10:80: Handshake Complete

</pre>

h4: Step 4: Using the device

Once the control Uri has been discovered, the DeviceFound event will be raised and you will be passed the INatDevice to use. From here you just need to make calls to the various methods like INatDevice.MapPort or INatDevice.GetExternalIP. It's worth noting that some devices will accept port maps which have a different internal IP address and external IP address, for example mapping external port 10000 to internal port 5000, while others will throw an exception. A few devices will silently ignore the internal port value and just map the external port 5000 to the internal port 5000.

h5. Submitting patches so your router works without modifications

If your router requires a fix to be detected with Mono.Nat, please let me know and supply a patch with the required changes. I'll gladly incorporate any changes which increase compatibility with different router models.