Service: uTURN - EyevinnOSC/community GitHub Wiki
uTURN (serviceId srperens-uturn) is an open source single-port TURN (Traversal Using Relays around NAT) relay for WebRTC, designed for Kubernetes and other restrictive network environments. Unlike traditional TURN servers that open a wide range of UDP ports, uTURN routes all traffic, both client-to-client and client-to-external-peer, through one UDP port, which makes it easy to deploy behind firewalls and standard load balancers. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.
- Enable WebRTC connectivity between clients that cannot establish direct connections.
- Authenticate clients with static long-term credentials (
Users) or with time-limited credentials minted by your backend (AuthSecret, TURN REST API scheme). - Run with a single UDP port to expose per instance.
uTURN has no dependencies on other OSC services. Create the instance with create-service-instance using serviceId: "srperens-uturn". The instance name must be alphanumeric and at most 20 characters. All options besides name are optional.
Static credentials:
{ "name": "myrelay", "Realm": "myrealm", "Users": "{{secrets.turnusers}}" }Time-limited credentials (the secret must be at least 16 bytes, for example from openssl rand -hex 32):
{ "name": "myrelay", "AuthSecret": "{{secrets.turnsecret}}" }Wait with wait-for-service-ready or get-instance-status, then read the TURN server URL with describe-service-instance.
OSC CLI example:
osc create srperens-uturn myrelay \
-o Realm="myrealm" \
-o Users="alice:secretpass"| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters. |
| Realm | No | string | TURN realm: the authentication domain for credential validation, included in the 401 challenge sent to clients. Default uturn (upstream --realm). Should match what your WebRTC application expects. |
| Users | No | string | User credentials for long-term authentication in username:password format, for example alice:secretpass. Upstream --user is repeatable, so multiple users can be given. The catalog does not mark this sensitive but it contains passwords, so store it as a service secret and pass {{secrets.NAME}}. |
| AuthSecret | No | string | Shared secret validating time-limited credentials generated by your backend, per the TURN REST API scheme (draft-uberti-behave-turn-rest-00), compatible with coturn's static-auth-secret (upstream UTURN_AUTH_SECRET). Must be at least 16 bytes; shorter secrets are refused. No default. Username is <expiry-unix-seconds>:<id> (or <id>:<expiry-unix-seconds>) and password is base64(HMAC-SHA1(secret, username)). Credentials are checked on every request including Refresh, so expired credentials stop allocations within about 60 seconds. Several secrets separated by whitespace can be given to rotate secrets ("<new> <old>"). Store as a service secret. |
| AllowedPeers | No | string |
ip:port targets on the relay's own external IP that clients may relay to, comma-separated, exact match (upstream UTURN_ALLOWED_PEERS). By default uTURN refuses to relay to its own external IP on any port other than the relay port; list another service on the same public IP here, for example an SFU on another port (203.0.113.1:30029). The NAT must support hairpinning. Loopback, link-local and multicast stay forbidden regardless. |
A {{secrets.NAME}} reference must be the whole field value. Overwriting a secret does not restart a running instance.
Pass the TURN server URL and credentials to your WebRTC ICE configuration:
const peerConnection = new RTCPeerConnection({
iceServers: [
{
urls: 'turn:<your-uturn-instance-url>',
username: 'alice',
credential: 'secretpass'
}
]
});Replace <your-uturn-instance-url> with the URL from describe-service-instance and alice/secretpass with credentials you configured in Users, or with credentials minted from AuthSecret.
- uTURN is a relay for WebRTC, not a general-purpose TURN server: client-to-client relaying relies on ICE ufrag matching, so both sides must be ICE agents (WebRTC endpoints). Plain client-to-external-peer relaying follows RFC 5766.
- Allocation state is in-process, so all participants of a call must reach the same uTURN instance; scale out by adding instances, not replicas.