Our new developer documentation is now available. Please check it out!

ODIN Server

The ODIN server is a Selective Forwarding Unit (SFU), which connects users in mutual rooms by acting as a relay for media and data.

graph BT
  subgraph ODIN Server
    OR2[Odin Room 1]
    OR[Odin Room 2]        
  end
  subgraph Mobile
    ClientA[Client D] <--> OR
    ClientB[Client C] <--> OR
  end
  subgraph Desktop 
    ClientB[Client C] <--> OR2   
    ClientC[Client B] <--> OR2
  end
  subgraph Consoles*
    ClientD[Client A] <--> OR2
  end

Configuration

The server is configured using a configuration file and optional command-line arguments.

Note: For local testing, using mkcert is recommended to generate certificates.

Command-Line arguments

Option	Description	Default Value
`--config`	Path to the config file	`config.toml`
`--license`	Path to the license file	`license.toml`

Here’s an example on how to start the server using a custom config path.

./grid --config /etc/grid/config.toml

The `config.toml` file

You can change the behavior of your ODIN server by modifying its configuration file called config.toml, which uses the TOML format.

`verbosity`

The verbosity level [0-3] to define how much information should be written to logs.

verbosity = 1

`public_address` _^Required

The FQDN and port number where the server can be reached from the Internet.

public_address = "localhost:4433"

The `[supervisor]` section

The [supervisor] section allows you to attach your server instance to an external gateway, which can be used for scalability in your hosting infrastructure. It is expected to be specified on the root level.

`url` _^Required

The full web address of the supervisor to contact and send reports to.

url = "http://localhost:7000/internal"

`report_interval`

The time in milliseconds between consecutive reports to the supervisor.

report_interval = 5_000

`no_warmup`

When true, the server wait for one report cycle before starting to send reports to the supervisor.

no_warmup = false

`version`

A freely pickable number to send with reports. This is currently unused, but reserved for future usage.

version = 123456

The `[authorization]` section

The ODIN server uses JSON Web Tokens (JWT) with EdDSA/Ed25519 signature for client authorization. The [authorization] section can be used to change the behavior of this process.

`allow_unsigned`

Then true, the server will accept logins using unsigned tokens. It is strongly recommended, that you do NOT enable this in a production environment.

allow_unsigned = false

`leeway`

The number of milliseconds a login token can be before or beyond its valid time period and still pass.

leeway = 5_000

The `[[authorization.keys]]` section

The [[authorization.keys]] section is used to define a list of keys allowed to sign login tokens. When using a [supervisor], this section can be omitted as it will be automatically generated by the gateway.

[[authorization.keys]]
kid = "Afkwfu4BVHDh"
kty = "OKP"
crv = "Ed25519"
x = "a5J2bhmU7vsY0LrW1zt56iUdmhRUNz7Pl9eBoCy29d8"
d = "5FYw1qdABjE0qEKEe821L7UPl_DZfO-PavpaiLsGDR0"

Note: You can use the @4players/odin-cli package to generate this section for you.

The `[quic]` section

The [quic] section is used to enable and configure the HTTP/3 socket listener for native ODIN core SDK clients.

`binding` _^Required

The socket where incoming connections are accepted from.

binding = "0.0.0.0:4433"

`certificate_file` _^Required

The path to a PEM-encoded leaf certificate followed by optional intermediate certificates.

certificate_file = "fullchain.pem"

`privatekey_file` _^Required

The path to a PEM-encoded private key.

privatekey_file = "privkey.pem"

`migration`

When enabled, the server accept IP address changes from clients.

migration = true

`keep_alive_interval`

Time in milliseconds between keep-alive packets sent by the server.

keep_alive_interval = 5_000 # ms

`idle_timeout`

Drop a connection if no packets have been received in this time span in milliseconds.

idle_timeout = 30_000 # ms

`pre_send_timeout`

The maximum time the sender waits for a packet to be inserted into the send buffer.

pre_send_timeout = 500 # ms

`connect_timeout`

The maximum time in milliseconds a connection can take to finish the HTTP/3 setup, until a client is created.

connect_timeout = 1_000 # ms

`no_peers_timeout`

The maximum time in milliseconds a client can stay connected, after leaving all rooms.

no_peers_timeout = 1_000 # ms

The `[http]` section

The [http] section is used to enable and configure the socket listener for ODIN web SDK clients.

`binding` _^Required

The socket where incoming connections are accepted from.

binding = "0.0.0.0:4433"

`certificate_file` _^Required

The path to a PEM-encoded leaf certificate followed by optional intermediate certificates.

certificate_file = "fullchain.pem"

`privatekey_file` _^Required

The path to a PEM-encoded private key.

privatekey_file = "privkey.pem"

`webrtc_candidates`

The list of IP addresses to be offered as candidates.

webrtc_candidates = ["127.0.0.1", "::1"]

`webrtc_binding`

The socket where WebRTC connections are accepted from.

webrtc_binding = "0.0.0.0:5000"

`timeout`

Drop connections after this much inactivity in milliseconds.

timeout = 10_000 # ms

`ping_interval`

Send a ping to the client using this interval in milliseconds.

ping_interval = 5_000 # ms

The `[metrics]` section

The [metrics] section is used to enable and configure a Prometheus metrics listener.

`binding` _^Required

The socket where incoming connections are accepted from.

binding = "0.0.0.0:9000"

`idle_timeout`

How long after the last change a metric value is reported.

idle_timeout = 3_600_000 # ms

`global_labels`

Labels that are added to all reported metrics.

global_labels = {deployment = "foo"}

`allowed`

List of IP subnets that are allowed to query metrics from the server.

allowed = ["0.0.0.0/0"]

The `[limit]` section

The [limit] section is used to configure concurrency limits.

`max_clients`

The maximum number of concurrent clients accepted by the server.

max_clients = 25

`max_rooms`

The maximum number of concurrent rooms accepted by the server.

max_rooms = 25

`max_peers`

The maximum number of concurrent peers accepted by the server.

max_peers = 25

The `[limit.network]` section

The [limit.network] section is used to configure network rate limits.

`incoming_media_packets`

The number of packets a media can send to the server every second.

incoming_media_packets = {rate = 50, capacity = 100}

The `[limit.peer]` section

The [limit.peer] section is used to configure limits per individual peer.

`incoming_messages`

The number of command packets of a peer that are processed by the server every second.

incoming_messages = {rate = 10, capacity = 50, overflow = 20}

`medias`

The number of medias a peer can create.

medias = 5

The `[telemetry]` section

The [telemetry] section is used to enable a telemetry client used for licensing.

`address` _^Required

The web address of the telemetry server to contact and send reports to.

address = "http://localhost/"

`interval`

The interval in milliseconds how often the telemetry data is being sent.

interval = 5_000 # ms

`max_consecutive_failures`

When set, this defines the maximum number of times sending telemetry data can fail before the server shuts down.

max_consecutive_failures = 4

`data`

Data from the [license] section to send to the telemetry server.

data = ["LicenseValidUntil", "LicenseLicensee", "LicenseSerialNumber", "LicenseIssuer"]

The `[license]` section

The optional [license] section is used to identify the licensee of the ODIN server. This section is used in a separate license.toml file.

`signature` _^Required

The signature of the license used to verify its validity.

signature = ""

`issuer`

An optional field to identify the issuer of the license.

issuer = "4Players"

`licensee`

An optional field to identify the licensee. Usually, this is your 4Players customer number (CID).

licensee = "622012345"

`serial_number`

An optional serial number of the license. Usually, this is the ID of your on-premise hosting subscription project.

serial_number = "b0FBTWZ2Rj3OY25uZWtYRlpoekVBUT09"

`valid_until`

An optional expiration date for the license. When set, the server can’t be used after his date.

valid_until = 1987-07-05T17:45:00Z

The `[internal]` section

The [internal] section is used to configure internal settings for debugging.

`log_hanging_api_calls`

A debug option to emit warnings if RPC calls take longer then the threshold in milliseconds.

log_hanging_api_calls = 1_000 # ms

Examples

Create a configuration file and use the grid executable to start the ODIN server.

Minimal `config.toml` for Supervised Server

When running the ODIN server in combination with a gateway, you only need to specify the web address of the supervisor. The server will register with the supervisor and automatically receive recommended settings, which will be used to extend the local config.toml file.

The recommended configuration of the gateway can be defined here.

[supervisor]
url = "http://localhost:7000/internal"

Minimal `config.toml` for Standalone Server

When running the ODIN server in standalone mode, you need to specify at least one JWK used for authorization pair as well as the binding and certificate configuration for incoming client connections.

[[authorization.keys]]
kid = "Afkwfu4BVHDh"
kty = "OKP"
crv = "Ed25519"
x = "a5J2bhmU7vsY0LrW1zt56iUdmhRUNz7Pl9eBoCy29d8"
d = "5FYw1qdABjE0qEKEe821L7UPl_DZfO-PavpaiLsGDR0"

[quic]
binding = "0.0.0.0:4433"
certificate_file = "fullchain.pem"
privatekey_file = "privkey.pem"

[http]
binding = "0.0.0.0:4433"
certificate_file = "fullchain.pem"
privatekey_file = "privkey.pem"

Developer Documentation

ODIN Server

Configuration#

Command-Line arguments#

The config.toml file#

verbosity#

public_address Required#

The [supervisor] section#

url Required#

report_interval#

no_warmup#

version#

The [authorization] section#

allow_unsigned#

leeway#

The [[authorization.keys]] section#

The [quic] section#

binding Required#

certificate_file Required#

privatekey_file Required#

migration#

keep_alive_interval#

idle_timeout#

pre_send_timeout#

connect_timeout#

no_peers_timeout#

The [http] section#

binding Required#

certificate_file Required#

privatekey_file Required#

webrtc_candidates#

webrtc_binding#

timeout#

ping_interval#

The [metrics] section#

binding Required#

idle_timeout#

global_labels#

allowed#

The [limit] section#

max_clients#

max_rooms#

max_peers#

The [limit.network] section#

incoming_media_packets#

The [limit.peer] section#

incoming_messages#

medias#

The [telemetry] section#

address Required#

interval#

max_consecutive_failures#

data#

The [license] section#

signature Required#

issuer#

licensee#

serial_number#

valid_until#

The [internal] section#

log_hanging_api_calls#

Examples#

Minimal config.toml for Supervised Server#

Minimal config.toml for Standalone Server#

Configuration

Command-Line arguments

The `config.toml` file

`verbosity`

`public_address` _^Required

The `[supervisor]` section

`url` _^Required

`report_interval`

`no_warmup`

`version`

The `[authorization]` section

`allow_unsigned`

`leeway`

The `[[authorization.keys]]` section

The `[quic]` section

`binding` _^Required

`certificate_file` _^Required

`privatekey_file` _^Required

`migration`

`keep_alive_interval`

`idle_timeout`

`pre_send_timeout`

`connect_timeout`

`no_peers_timeout`

The `[http]` section

`binding` _^Required

`certificate_file` _^Required

`privatekey_file` _^Required

`webrtc_candidates`

`webrtc_binding`

`timeout`

`ping_interval`

The `[metrics]` section

`binding` _^Required

`idle_timeout`

`global_labels`

`allowed`

The `[limit]` section

`max_clients`

`max_rooms`

`max_peers`

The `[limit.network]` section

`incoming_media_packets`

The `[limit.peer]` section

`incoming_messages`

`medias`

The `[telemetry]` section

`address` _^Required

`interval`

`max_consecutive_failures`

`data`

The `[license]` section

`signature` _^Required

`issuer`

`licensee`

`serial_number`

`valid_until`

The `[internal]` section

`log_hanging_api_calls`

Examples

Minimal `config.toml` for Supervised Server

Minimal `config.toml` for Standalone Server