STUNTMAN STUN Server

The --mode option determines the type of STUN tests performed. Use these modes to target specific diagnostic needs:

• basic (Default): Performs a simple STUN binding test only.
• behavior: Attempts to diagnose NAT behavior and port mapping methodologies (requires server support).
• filtering: Attempts to diagnose NAT filtering methodologies (requires server support; only supported for UDP).
• full (Deprecated): Performs both filtering and behavior tests. It is recommended to run these separately using different local ports instead.

stunclient --mode filtering --localport 9999 12.34.56.78

If running stunserver in full mode behind a NAT (such as in Amazon EC2), you must manually specify the public IP addresses to ensure the ORIGIN, OTHER-ADDRESS, and CHANGED-ADDRESS attributes are correct. Without these, clients performing NAT behavior tests will receive incorrect results.

• --primaryadvertised PRIMARY-IP: The public IP address of the --primaryinterface.
• --altadvertised ALT-IP: The public IP address of the --altinterface.

Use --mode full to facilitate advanced NAT behavior and NAT filtering discovery. Full mode requires the host to have two unique IP addresses. The service will listen on two different interfaces and two different ports on each interface (four listeners total).

Note: When running over TCP in full mode, the service cannot support the CHANGE-REQUEST attribute.

stunserver --mode full --primaryinterface 128.34.56.78 --altinterface 128.34.56.79

Instead of command-line arguments, you can use a JSON configuration file via the --configfile FILENAME flag.

When using a config file:

• Most command-line parameters are ignored (except --verbosity).
• Configuration fields are named identically to the command-line parameters (without the leading dashes).
• This allows running multiple protocols and IP families within the same process using separate threads.

The stunclient command-line application is used to discover a host's external IP address, obtain port mappings, and diagnose Network Address Translator (NAT) behavior or filtering methodologies.

Basic Syntax: stunclient [OPTIONS] server [port]

• server: The IP address or FQDN of the remote STUN server (Required).
• port: The remote server port (Optional, defaults to 3478 for UDP and TCP).

stunclient stunserver.org 3478

STUNTMAN operates in two primary modes:

• Basic mode: The server listens on a single port and responds to STUN binding requests.
• Full mode: The server listens on two different IP address interfaces (if available) and provides NAT behavior and filtering detection support for clients. This mode can be configured for Amazon EC2 instances by checking stunserver --help.

By default, the server operates in an open mode without authentication. While HMAC/SHA1/MD5 hashing for message integrity is implemented, the logic for validating usernames and passwords is not included in the base release.

To implement custom authentication (validating a username, fetching a password, and allowing/denying requests), you must implement a provider using the hooks provided. Reference server/sampleauthprovider.h for details on how to write your own authentication provider code.

STUNTMAN operates in two primary modes:

• Basic Mode: Configures the server to listen on one port and respond to STUN binding requests.
• Full Mode: Configures the service to listen on two different IP address interfaces (if available) and provides NAT behavior and filtering detection support for clients. This mode can be configured for Amazon EC2 instances by checking ./stunserver --help.

Important Note for Local Testing: When running in full mode locally, the server may not listen on the loopback adapter. If stunclient localhost fails, use ifconfig to find your actual IP address and connect to that instead (e.g., ./stunclient 10.11.12.13).

The server operates in two primary modes which dictate how network interfaces and IP addresses are handled:

Basic Mode

In basic mode, the server typically binds to a single interface. If no --primaryinterface is specified, it attempts to bind to all available interfaces (using 0.0.0.0 for IPv4 or :: for IPv6).

Full Mode

full mode is designed for scenarios requiring multiple IP addresses. It requires two unique IP addresses to function. The server will set up a mapping between the primary and alternate interfaces and ports (e.g., Primary Interface/Primary Port, Primary Interface/Alt Port, Alt Interface/Primary Port, and Alt Interface/Alt Port).

Note: full mode will fail if the primary and alternate interfaces resolve to the same IP address.

Use yum to install the development tools, Boost, and OpenSSL development files.

sudo yum groupinstall "Development Tools"  # For g++, make, et. al.
sudo yum install boost-devel           # For Boost
sudo yum install openssl-devel         # For OpenSSL

To quickly run a STUN server using Docker, build the image and run a container mapping both TCP and UDP port 3478.

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