This document provides a comprehensive introduction to the Coturn TURN server project. It covers the server's purpose, key features, protocol support, RFC compliance, and high-level architecture. For detailed information about specific subsystems, see:
Coturn is a free, open-source implementation of a TURN (Traversal Using Relays around NAT) and STUN (Session Traversal Utilities for NAT) server. It provides NAT traversal capabilities for VoIP, WebRTC, and other real-time communication applications by relaying media traffic between peers that cannot establish direct connections due to firewall or NAT restrictions.
Current Version: 4.11.0 "Gorst" (src/ns_turn_defs.h38-39)
Software Identifier: Coturn-4.11.0 'Gorst' (src/ns_turn_defs.h43)
Sources: src/ns_turn_defs.h38-43 ChangeLog1-3 README.md9-13
| Feature Category | Description | Key Benefits |
|---|---|---|
| TURN Relay | Full RFC 5766/6062/6156 TURN server with UDP and TCP relay support | Enables peer-to-peer connectivity through restrictive NATs |
| STUN Binding | RFC 5389/3489 STUN server for NAT behavior discovery | Helps clients determine their public IP/port mappings |
| Multi-Protocol | Supports UDP, TCP, TLS, DTLS, SCTP transports | Flexible deployment for various network environments |
| Authentication | Long-term credentials, REST API, OAuth support | Secure access control with multiple integration options |
| Scalability | Multi-threaded architecture with optimized I/O engine | Handles thousands of concurrent sessions per CPU |
| Database Support | SQLite, PostgreSQL, MySQL, MongoDB, Redis backends | Flexible user management and statistics storage |
ALTERNATE-SERVER mechanism (300 response) and DNS-based balancing (README.turnserver234-241)Sources: README.turnserver1-73 rpm/turnserver.spec26-73 README.md53-136 STATUS.md1-110
Protocol Details
Sources: README.md86-98 rpm/turnserver.spec44-53 STATUS.md14-20
Coturn implements a wide range of IETF specifications for NAT traversal:
| RFC | Title | Implementation Status |
|---|---|---|
| RFC 5766 | Traversal Using Relays around NAT (TURN) | ✓ Complete (Base) |
| RFC 6062 | TURN Extensions for TCP Allocations | ✓ Complete |
| RFC 6156 | TURN Extension for IPv6 | ✓ Complete |
| RFC 8016 | Mobility with TURN (MICE) | ✓ Complete |
| RFC 8656 | TURNbis (Dual Allocation/SSODA) | ✓ Supported (Draft-based) |
| RFC | Title | Implementation Status |
|---|---|---|
| RFC 3489 | STUN (Classic) | ✓ Backward compatibility (ChangeLog53) |
| RFC 5389 | Session Traversal Utilities for NAT | ✓ Complete (Base) |
| RFC 5769 | Test Vectors for STUN | ✓ Complete (Verified via turnutils_rfc5769check) |
| RFC 5780 | NAT Behavior Discovery Using STUN | ✓ Complete |
| RFC 7443 | ALPN support for STUN & TURN | ✓ Complete |
| RFC | Title | Implementation Status |
|---|---|---|
| RFC 7635 | OAuth 2.0 Third-Party Authorization | ✓ Complete |
| Draft-uberti | TURN REST API | ✓ Complete |
Sources: README.md55-85 rpm/turnserver.spec30-48 STATUS.md1-55
Architecture Characteristics
libevent2 for high-performance asynchronous I/O (README.md152)NEV_UDP_SOCKET_PER_THREAD for modern kernels (STATUS.md76)Sources: README.md148-158 STATUS.md58-95 man/man1/turnserver.115-36
| Component | Code Entity | Responsibility |
|---|---|---|
| Relay Server | turnserver | The main relay daemon handling all STUN/TURN traffic (man/man1/turnserver.115) |
| Admin Tool | turnadmin | User account management, realm configuration, and key generation (README.turnadmin3-9) |
| I/O Engine | ioa_engine | Abstraction for socket I/O, timers, and buffer management (STATUS.md61) |
| Protocol Logic | ns_turn_msg.c | Parsing and construction of STUN/TURN messages and attributes (ChangeLog81) |
| Database Abstraction | turn_dbdriver_t | Unified interface for SQLite, MySQL, PostgreSQL, Redis, and MongoDB (rpm/turnserver.spec54-60) |
Coturn uses a multi-threaded design where threads communicate via bufferevent_pair:
-m (README.turnutils172).Sources: README.md150-155 STATUS.md58-62 README.turnutils138-149
Coturn includes a suite of tools for verification and performance testing:
| Tool | Purpose | Key Features |
|---|---|---|
turnutils_uclient | Client Emulation | Simulates multiple clients; supports load-generation and DOS attack modes (man/man1/turnutils.16-13 ChangeLog5) |
turnutils_peer | Echo Server | Simple UDP echo server used as a "peer" in relay testing (man/man1/turnutils.117-23) |
turnutils_stunclient | STUN Test | Simple client to test STUN binding requests (man/man1/turnutils.129-32) |
turnutils_natdiscovery | NAT Analysis | Discovers NAT mapping and filtering behavior per RFC 5780 (man/man1/turnutils.147-50) |
turnutils_oauth | OAuth Utility | Generates and validates OAuth access tokens (RFC 7635) (man/man1/turnutils.154-59) |
turnutils_rfc5769check | Compliance | Validates protocol implementation against RFC 5769 test vectors (man/man1/turnutils.134-36) |
Sources: README.turnutils1-48 man/man1/turnutils.11-63
The server can be configured via command-line flags or a configuration file (default turnserver.conf). If a config file is modified, the server must be restarted (README.turnserver40 man/man1/turnserver.1102-128).
turnadmin provides commands for:
-a)-A, -D)-s)-O)-g)Refresh this wiki