Service: uTURN - EyevinnOSC/community GitHub Wiki

uTURN

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.

What it can do

  • 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.

Creating an 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"

Options

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.

Using the 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.

Limitations

  • 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.

Resources

⚠️ **GitHub.com Fallback** ⚠️