STUNTMAN 1.2: STUN server setup, limits, and deployment

STUNTMAN's binding-discovery scope

STUNTMAN addresses a narrow part of NAT traversal: discovering the public-facing transport address associated with a STUN binding request. The README lists RFC 5389, RFC 5769, and RFC 5780 compliance, with backward compatibility for RFC 3489. It provides a server executable and a client test application rather than a general-purpose relay service.

The intended users are C++ developers, network application developers, and operators who need a STUN endpoint for address discovery. A software client can send a binding request, and `stunserver` can return the source address and port observed by the server. That result can help client code reason about its public transport mapping before attempting peer-to-peer communication.

The project does not present itself as a TURN relay implementation. The documented output and feature set concern STUN binding requests, NAT behavior detection, and filtering detection in full mode. A team looking for relayed media, guaranteed connectivity through arbitrary firewalls, or a complete interactive communications server should not treat this repository as that kind of system.

STUNTMAN also defaults to an open service. The README explicitly says that authentication is not performed by default. Although hashing and message-integrity code exists, credential lookup and username validation are outside this release. That makes the project a developer-oriented STUN component rather than an administration-ready service with a documented policy and account system.

Basic and full-mode packet handling

The repository layout separates shared STUN processing, networking utilities, server code, client code, and test code under `stuncore/`, `networkutils/`, `server/`, `client/`, and `testcode/`. The root `Makefile` builds those components in sequence and then copies `stunserver`, `stunclient`, and `stuntestcode` into the source root.

In basic mode, according to the README, the server listens on one port and answers STUN binding requests. Running `stunserver` without command-line arguments places it on port 3478 across all adapters. This is the shortest path between a compiled server and a client request, but it gives up full-mode behavior detection.

Full mode is structurally different. The server listens on two different IP address interfaces when available. The README associates this arrangement with NAT behavior and filtering detection support. It also contains a note for Amazon EC2 deployments and directs readers to `stunserver --help` for that configuration.

Full mode has an operational consequence that can look like a client failure. The server may not listen on the loopback adapter, so `stunclient localhost` can fail even when the service is configured correctly. The README says to discover the relevant address with `ifconfig` and query that address instead. This behavior should be considered during local development because it makes interface selection part of the first functional check.

Compiling STUNTMAN from source

Compilation requires a C++ compiler, GNU make, Boost headers, and OpenSSL development files. On Debian, Ubuntu, or Mint, the README lists these package installation commands. Run them in the order shown:

sudo apt-get install g++
sudo apt-get install make
sudo apt-get install libboost-dev # For Boost
sudo apt-get install libssl-dev # For OpenSSL

After installing the dependencies, enter the source root and build all three executables. The README says to use `gmake` on some systems.

make

The build should produce `stuntestcode`, `stunserver`, and `stunclient` in the repository root. The Makefile also has a `clean` target, but the README warns that dependency checking is absent and recommends `make clean` before a subsequent build. That warning matters when headers or library dependencies change because stale object files can remain in component directories even after the root binaries are removed.

For RedHat, Fedora, or EC2 Amazon Linux AMI, the documented package route differs:

sudo yum groupinstall "Development Tools"
sudo yum install boost-devel
sudo yum install openssl-devel

On Mac and Solaris, the README says OpenSSL is already present and not needed on Mac. Both platforms require local Boost installation, followed by editing the top line of `common.inc` when Boost headers are not in the standard include path. This is a manual platform-specific step rather than a portable package-manager installation.

Running the first server and client request

Begin with the unit-test executable, as the README specifically recommends that step after compilation. Its output contains lines corresponding to different code paths.

./stuntestcode

A line ending in `FAIL` indicates a likely problem according to the README. If the build tree is later rebuilt after dependency or header changes, clean it first:

make clean
make

Start the default server on port 3478 by omitting command-line arguments. This configuration listens on all adapters and responds in the basic service mode described by the README.

./stunserver

In another shell, query a reachable hostname with the bundled client:

./stunclient stun.selbie.com

For a server running locally, the first request should normally target its actual interface rather than assume loopback availability. The README gives this example shape after using `ifconfig` to discover the address:

stunclient 10.11.12.13

The numeric address must be replaced with the address assigned to the interface on which that server is listening. If the server is in full mode, this is not merely a documentation nicety. A failure against `localhost` can reflect loopback exclusion rather than a broken binding request.

Before testing from another host, configure the firewall to allow traffic on the server's local listening ports. The README supplies no firewall command because port selection and firewall tooling depend on the deployment. The default path uses port 3478.

Docker deployment constraints in the repository

A `Dockerfile` is present, and the README gives a local image build and container run sequence. Its final image copies only `stunclient` and `stunserver` into `/opt/stunserver`; the unit-test executable is not included in the runtime image. The image exposes TCP and UDP port 3478 and declares `/opt/stunserver/stunclient localhost` as its health check.

The documented image build is:

docker image build -t=stun-server-image .

The documented container command publishes the same port for both transports:

docker container run -d -p 3478:3478/tcp -p 3478:3478/udp --name=stun-container stun-server-image

There are specific maintenance concerns here. The build stage uses `ubuntu:18.04`, and the runtime stage installs `libssl1.1`. Both choices are tied to an older distribution generation and a package that may not be available from current standard repositories. The Dockerfile also clones the default branch during the build rather than copying a pinned local source tree. As a result, rebuilding the same Dockerfile later can retrieve different repository content. These are visible details in the file, not runtime observations.

The health check also depends on localhost behavior. The README warns that full mode may not listen on the loopback adapter, while the `ENTRYPOINT` starts the server without recorded mode arguments. That makes the health check appropriate only if the default basic-mode server does listen locally. The Dockerfile does not document a full-mode health-check alternative.

Authentication, TLS, scaling, and release maintenance

The most important limitation is authentication. Open mode is the default, and the repository does not validate usernames or retrieve passwords in this release. Code for authentication, challenge-response, message hashing, and integrity attributes is described as present, but implementors must supply username validation, password lookup, and allow or deny decisions. `server/sampleauthprovider.h` is the documented starting point for that integration. Deploying an open endpoint is therefore different from deploying an authenticated service, even if integrity primitives are available in the codebase.

TLS mode has not been implemented. That boundary is especially relevant because the source has OpenSSL-related compilation requirements and integrity code, but those facts should not be interpreted as transport encryption for the STUN listener. The documentation does not offer a TLS deployment option.

The feature roadmap lists cross-CPU scaling as unfinished work. The README says threading code exists but needs additional completion, so a multi-core deployment should not be justified by an unstated expectation that full mode will scale across processors. The roadmap also lists Makefile cleanup, `configure` and autotools support, a finished Windows service port, and TLS support.

There are no GitHub releases. The README identifies version 1.2.17 and is dated June 30, 2024. The last push was on 2026-05-12, so the repository has recent repository activity, but activity does not erase the stated feature gaps or provide a formal release artifact stream.

The Apache-2.0 license permits source-level use and modification under its terms, but operators remain responsible for reviewing those terms and notices. STUNTMAN is also not the right tool where TLS, enforced user authentication, documented rollback, or multi-core scaling is a procurement requirement.

Where STUNTMAN differs from a custom responder

The closest practical alternative for a very narrow deployment is a custom STUN binding responder built for one platform and one fixed packet flow. Such an implementation can target only the exact response behavior needed by an application and may avoid the broader server modes, authentication hooks, client executable, and multi-platform build layout found here. The trade-off is that protocol compatibility and response correctness become the application's own responsibility.

STUNTMAN offers a more concrete codebase for developers who want existing handling for RFC 5389, RFC 5769, RFC 5780, and backward compatibility with RFC 3489. It also supplies both UDP and TCP over IPv4 and IPv6, a basic mode, a full mode, a test client, and a unit-test executable. A custom responder would need to add whichever of those elements its users require.

STUNTMAN is the better fit when source access and protocol logic matter more than packaged operations. A custom responder is the better fit when the required behavior is intentionally tiny and its platform, packet handling, and maintenance ownership are already controlled. Neither approach removes the need to decide whether binding discovery alone addresses the connectivity requirement.

Editorial conclusion

STUNTMAN fits developers who need a small STUN server, its bundled test client, and source-level control over basic or full mode. It is a poor fit for deployments requiring TLS, built-in credential validation, current multi-core scaling, or packaged releases. Before adoption, verify full-mode routing on the target interfaces, configure firewall access for the selected ports, and run `stuntestcode` after each clean rebuild.

Frequently asked questions

Official sources

1. Issues
2. jselbie/stunserver on GitHub
3. License: Apache-2.0
4. Project website
5. README