==================================================================== STUN Server and Client Reference Implementation README ==================================================================== STUN Server Release 0.7.0 March, 2002 ==================================================================== LICENSE AND COPYRIGHT ==================================================================== 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. ==================================================================== INTRODUCTION ==================================================================== 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. ==================================================================== NEW FEATURES AND FUNCTIONS IN THIS RELEASE ==================================================================== none ==================================================================== BUG FIXES ==================================================================== ==================================================================== KNOWN LIMITATIONS ==================================================================== TO DO: -------------------------------------------------------------------- + Add debug log info to all returns + Add support to ethereal for decoding STUN protocol + Command line parsing and usage message + Support SRV stuff ==================================================================== GETTING STARTED ==================================================================== 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 HARDWARE OR SOFTWARE REQUIREMENTS -------------------------------------------------------------------- At present, this software has been tested on the following platforms: Windows 98/ME/2000/XP Linux 2.4 Kernel Solaris COMPILE INSTRUCTIONS -------------------------------------------------------------------- The following brief descriptions deal with compilation of the server and client on various platforms. Windows MSVC Use the included MSVC project files: stund.dsp stunc.dsp stun.dsw OR To compile in windows make an MSVC project. Goto: Settings... In Compiler Pane Preprocessor Options... Turn off pre-compiled headers. In Linker Section: Add library ws2_32.lib. For the server (stund) add : stund.cxx stun.cxx udp.cxx stun.h For the test client (stun) add: stunq.cxx stun.cxx udp.cxx stun.h 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. USING THE SOFTWARE -------------------------------------------------------------------- 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. ==================================================================== SOURCE CODE INFORMATION ==================================================================== The documentation from doc++ is located at: http://www.polyphase.ca/software/stun/docs/ Generating Documentation using Doc++ ------------------------------------ You can use Doc++ to generate API documentation. Doc++ generates an alphabetical and hierarchical index of classes, functions, and variables. To use Doc++: 1. Download Doc++ from http://www.zib.de/Visual/software/doc++/ 2. Untar the file. 3. Locate the doc++ and docify files. These files should be in the /bin directory. 4. Copy the doc++ and docify files to directory where the source code is located. 5. Type: make doc 6. Doc++ generated documentation will be saved in the html directory. 7. Select index.html from the html directory. Running Together ---------------- The together subdirectory contains Together files generated by running the program on the source code. To view, start Together, and open the 'together/baseproxy.tpr' project file. The directory also contains a gif diagram showing all of the base classes. ==================================================================== DIRECTORY STRUCTURE ==================================================================== ==================================================================== CONTRIBUTORS ==================================================================== ==================================================================== CONTACT INFORMATION AND WEBSITE ==================================================================== 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 ====================================================================