STUN Server and Client Reference Implementation

Copyright © 2002 Alan Hawrylyshen

(mailto:alan-s@jasomi.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.



Background

The software in this tarball implements a simple STUN server and client. The STUN protocol (Simle Traversal of UDP through NATs) is described in the IETF Internet Draft " draft-rosenberg-midcom-stun-00.txt", available from the IETF here.

From the above draft:

Abstract

Simple Traversal of UDP Through NATs (STUN) is a lightweight protocol that allows applications to discover the presence and types of Network Address Translators (NATs) and firewalls between them and the public Internet. It also provides the ability for applications to determine the public IP addresses allocated to them by the nat. STUN works with nearly all existing NATs, and does not require any special behavior from them. As a result, it allows a wide variety of applications to work through existing NAT infrastructure. The STUN protocol is very simple, being almost identical to echo.

Downloading the STUN server and client tarball.

Currently, the STUN client tarball can be downloaded from:

http://www.polyphase.ca/software/stun/stund_latest.tgz

This document is located at:

http://www.polyphase.ca/software/stun/overview.html

The documentation from doc++ is located at:

http://www.polyphase.ca/software/stun/docs/

There is a mailing list for this software and STUN in general at:

stun-list@polyphase.ca

You may subscribe by visiting:

http://www.polyphase.ca/mailman/listinfo/stun-list_polyphase.ca

 

 

Compilation of STUN server and client

The following brief descriptions deal with compilation of the server and client on various platforms. At present, this software has been tested on the following platforms:

Windows MSVC

Use the included MSVC project files:

OR

To compile in windows make an MSVC project.
Goto:

Linux

The tarball has been setup to work with using make, out of the box.

Editing the Makefile can control debug and optimization levels.

Solaris

In solaris probably need to add -lsocket -lnsl to the LDFLAGS in the Makefile.

Machine Configuration and Running stund

 

stund can be run from the command line, or, it can be run as a service. The sample tarball contains scripts for RedHat Linux that will start stund in runlevels 2,3,4 and 5. To activate this, run make install.

File in tarball

Installation location.
stund.svc
/etc/init.d/stund
stund.sysconfig
/etc/sysconfig/stund

none

/etc/rc?.d/stund (symlinks)

Ideally, two machines will be configured to run the stund server and each will be started with knowledge of the other. Here are sample command lines for running two stund processes on two hosts (or a single multi-homed host). The machines are known as A and B, both in the domain foo.com. Note that A and B can be different names for the same physical host if A and B resolve to different IP addresses (multi-homed).

A# /usr/sbin/stund -h a.foo.com -p 10000 -a b.foo.com -o 10001

B# /usr/sbin/stund -h b.foo.com -p 10000 -a a.foo.com -o 10001

This will run the appropriate stund server processes to permit clients to resolve their NAT status by contacting either a.foo.com or b.foo.com from the stunq query program. (Sample code).

If the machine was dual homed, the above can be run solely on host A. You can use IP addresses for the hostname components as well.

Running the sample query client (stunq)

/usr/sbin/stunq serverHostName:port

The above command will attempt to contact serverHostName on port using STUN protocol and will print out the results of the test described in Rosenburg et al.

 

Todo

Questions?

Contact alan-s@jasomi.com