Norsk Domains

Every Norsk media engine keeps its media buffers in memory owned by norskd, a small memory daemon. On its own, an engine runs a private norskd that lives and dies with it. A Norsk Domain is a set of instances that share one norskd instead. Because every member’s buffers come from the same daemon, one engine can hand a frame to another over the norsk-link without copying it: the receiving engine adopts the buffer where it already is.

Use a domain when instances on one host pass uncompressed media between them. A typical example is a capture instance that owns an ST 2110 interface, feeding several recorder instances. Instances that never talk to each other have no reason to be in one.

Joining a domain

An instance joins the domain its domain launch setting names:

Source	Set by
--domain <name> at launch (or the Launch form’s Norsk Domain field)	You, per instance
The product template’s declared default (advanced.domain.default in its manifest)	The product

The first match wins. A product whose templates are meant to talk to each other declares one domain for all of them, so its instances land together without you naming it. --domain "" (or clearing the form field) declines a declared domain, and the instance runs isolated with its own private daemon. Isolated is also what you get when nothing names a domain.

What norsk-ctl does for you

A domain’s daemon runs in its own container, norsk-ctl-norskd-<name>. Each member’s media container mounts the domain’s socket volume at /run/norsk and is given NORSKD_DAEMON_SOCKET_PATH. norsk-ctl manages the daemon’s whole life:

• The first member brings it up. Before that member’s containers start, norsk-ctl runs the daemon and waits for it to report READY. The daemon’s image tag is taken from the member’s media image, so the two always match.
• Later members join it as it is.
• The last member takes it down. When the last instance naming the domain is deleted, the daemon container and its volume are removed, so the next member starts a fresh one. A first launch that fails also takes down the daemon it brought up.

Caution

A member is given its domain’s daemon, and does not fall back to a private one. If the daemon cannot be reached, the member’s engine refuses to start. That is deliberate: a member that quietly ran alone would look healthy while nothing crossed the link.

One user per domain

Only a process running as the socket’s owner can connect to it. The daemon therefore runs as the same user as its members’ engines, which on native Linux is the daemon’s own uid:gid, or the instance’s --container-user. It uses a socket volume that only that user can open. The member that starts the domain decides its user.

A member that would run as someone else is refused at launch with NORSKD_DOMAIN_USER_MISMATCH. The message names both users. Launch the member as the domain’s user, give it another domain, or stop the domain’s members so it starts afresh. A mismatched daemon with no members left, for example one left behind by an older norsk-ctl, is replaced rather than refused. If docker cannot bring the daemon up at all, the launch fails with NORSKD_DOMAIN_UNAVAILABLE and the daemon’s own last words.

Hugepages

Hugepages are a host resource that other software on the host may depend on. In particular, an ST 2110 interface’s MTL needs pages of its own. So a domain reserves none unless you declare a pool for it:

norsk-ctl domain set chanel --hugepages 4g --numa-node 0

• The size uses docker size syntax (4g, 512m, binary units). --numa-node binds the pool to one node: use the ST 2110 NIC’s, so DMA buffers are local to it. --hugepages none declares the domain with no pool.
• The daemon reserves the whole pool up front, and it is required. If the host has not reserved enough pages (vm.nr_hugepages, on that node), the domain fails to come up and its members’ launches fail with NORSKD_DOMAIN_UNAVAILABLE. The reason is the daemon’s own. The daemon does not run quietly on ordinary memory.
• With no pool declared, the daemon runs on ordinary memory. That is fine for the norsk-link, but not for ST 2110 zero-copy DMA.
• A declared pool applies when the domain’s daemon is created. A running daemon keeps what it started with until its last member leaves, and the UI shows the declared change as pending until then.
• norsk-ctl domain clear chanel forgets the domain’s settings.

Declaring a pool needs the settings-edit permission, because it takes memory from the host.

Seeing your domains

• norsk-ctl domain list shows each domain: its daemon’s state, the user it runs as, its hugepage pool, its members and its image. A domain declared ahead of its first member is listed too, with the pool it will get. norsk-ctl domain describe <name> gives one domain in full.
• Runtime → Infrastructure in the UI shows a card per domain with the same facts.
• The API is GET /api/v1/norsk-domains and GET /api/v1/norsk-domains/{name}. Settings are PUT and DELETE /api/v1/norsk-domains/{name}.

A domain that its instances name but that has no daemon is shown too. Those instances cannot start until the next member launched brings one up.