Adding nodes

A node needs only two things: the central service’s address and the enrollment key, both shown under Configuration › Node enrollment. Everything else (ports, routes, destinations, settings) comes from the central service and reaches every node within seconds.

Enrollment and the node’s own key

1. When a node first starts, it presents the enrollment key.
2. The central service gives it a key of its own. The node keeps it encrypted on its disk (node-key.bin); the central service keeps only a hash of it.
3. From then on the node uses only its own key. The enrollment key no longer lets anyone act as that node, or enroll under its name.

The enrollment key does nothing but enroll, so it is safe to give to whoever installs nodes. Treat it as a password all the same: anyone holding it can add a node.

Each node’s name must be unique; by default it is the computer name.

Approving new nodes

Every newly enrolled node waits: it reports in and appears on the Nodes tab as Awaiting approval, but receives no configuration, secrets or patient ID maps until an administrator approves it. So the enrollment key alone gets nothing. Configuration › Node enrollment › New nodes need approval (on by default) turns this off, for instance while setting up many nodes at once.

Managing node keys

On the Nodes tab each node shows its key: Own key, Awaiting approval, Key reset or Revoked.

Action	When	What happens
Reset key	A node was reinstalled, or lost its data folder	Its key stops working; it enrolls again with the enrollment key. It keeps its approval.
Revoke	A node is retired or compromised	Its key stops working, and it may not enroll again until Allow again.
Remove (offline nodes)	A node is gone for good	It leaves the list, and its key with it (a revocation stays).
Generate new key (Node enrollment)	The enrollment key may have leaked	A new enrollment key at once. Enrolled nodes are not affected; nodes not yet enrolled need the new one.

Every one of these is written to the audit log. Other central servers notice within 30 seconds.

Several nodes and a load balancer

Nodes are interchangeable: every node has the same configuration, and any node can take any sender. To share the load and survive a node going down:

1. Install two or more nodes with the same central address and enrollment key.
2. Put their DICOM ports behind a load balancer’s virtual address (VIP), with a TCP health check on the same port.
3. Point senders’ DNS name for the router at the VIP.

Senders never need reconfiguring when nodes are added or removed. A node that is drained, or short of disk space, stops listening, so the health check fails and the balancer sends new associations elsewhere.

A study a sender sends on one association goes through one node. A node keeps what it has received on its own disk until it is delivered, so a node that goes down delivers its queue when it comes back.

Draining a node for maintenance

Drain (on the Nodes tab) tells a node to stop accepting associations. Open associations get the drain grace period to finish, and the node keeps sending everything it has queued. It shows Draining until both are done, then Drained: safe to stop, patch or upgrade. It stays drained across restarts until Resume.

Several nodes on one machine

For testing only, several nodes can run on one machine: give each its own NodeName, DataDirectory and PortOffset (added to every port it opens). Routing rules still see the configured port numbers.

What a node keeps

The data folder holds instances in transit, its queues, dead letters, the resend cache, history not yet sent to the central service, its own key and the secrets it was given (encrypted). It needs no backup: a replacement node is installed and enrolled (after Reset key, if it keeps the old name). Use redundant storage if instances must survive a disk failure before they are delivered. The full list is in the reference.