Skip to content

Network matrix

Network communication matrix

This page describes the network communications:

  • between the Fed-BioMed components (nodes, and researcher), aka application internal / backend communications
  • for user access to the Fed-BioMed components GUI
  • for Fed-BioMed software installation and docker image build

Network communications for the setup of host machines and the installation of software requirements are out of the scope of this document. Network communications necessary for the host machines to run (access to DNS, LDAP, etc.) regardless of Fed-BioMed are also out of the scope of this document. They are specific to system configuration and installation processes.

Introduction

Fed-BioMed network communications basic principle is that all communications between components are outbound from one node to the researcher. There is no inbound communications to a node.

Secure aggregation uses logical node-to-node overlay messages, but it does not create direct network connections or additional ports between nodes. The researcher relays these messages over each node's existing gRPC connection. The initial ChannelSetupRequest and ChannelSetupReply are plaintext requests. Subsequent node-to-node payloads are signed and encrypted with keys derived through ECDH. There is no shared default node-to-node private key.

Fed-BioMed provides some optional GUI for the node (node configuration GUI) and the researcher (Jupyter notebook and Tensorboard). By default, these GUI components are not secured (no HTTPS and/or no certificate signed by well known authority). So they are configured by default to accept only communications from the same machine (localhost).

All backend communications between the components are encrypted with TLS in every scenario. Mutual authentication, mandatory for a deployment, additionally binds each channel to a registered party without changing the flows themselves — see Mutual authentication (mTLS) below.

Software installation

Network communications for software installation cover the Fed-BioMed software installation and setup until the software is ready to be used.

They cover all deployment scenarios. If multiple machines are used, each machine needs to authorize these communications.

  • direction is out (outbound communication from the component) or in (inbound communication to the component)
dir source machine destination machine destination port service
out component Internet TCP/80 HTTP
out component Internet TCP/443 HTTPS


"Component" is the node or researcher.

For destination machine, it is simpler to authorize outbound communications to all Internet addresses for the required ports during installation. Indeed, several packaging systems are used for installation, with no guarantee of stable IP address used by the packaging server:

  • For all deployment scenarios: conda, pip (all components) and yarn/npm (node GUI component) packages
  • Plus for containers scenarios: dockerhub images and apt packages

Running without containers

fedbiomed-network-matrix

This part describes the communication matrix for running Fed-BioMed without containers:

  • The direction is out (outbound communication from the component) or in (inbound communication to the component)
  • Type of communication is either backend (between the application components) or user (user access to a component GUI). Command line user access to component from localhost are not noted here. GUI access are noted though recommended default configuration is to give access only from localhost
  • The status is either mandatory (needed to run Fed-BioMed) or optional (a Fed-BioMed experiment can run without this part)

On the node component (node + gui ):

dir source machine destination machine destination port service type status comment
out node researcher TCP/50051 gRPC/TLS backend mandatory node-researcher communications
in localhost gui TCP/8484 HTTP user optional node GUI
  • node and gui also need a shared filesystem, so they are usually installed on the same machine.


On the researcher component (researcher):

dir source machine destination machine destination port service type status comment
in nodes researcher TCP/50051 gRPC/TLS backend mandatory node-researcher communications
in localhost researcher TCP/8888 HTTP user optional Jupyter
in localhost researcher TCP/6006 HTTP user optional Tensorboard

Running with Docker containers

This section describes the communication matrix for running Fed-BioMed using Docker containers.

As for every deployment, enable mutual authentication on every component.

In this setup all containers are attached to a shared user-defined Docker bridge network (e.g. fedbiomed-net). Container-to-container communication uses Docker's internal DNS — containers address each other by container name. Ports are published from the container to the host machine to allow user access from localhost (or, in a cross-host setup, from the public internet).

  • The direction is out (outbound communication from the component) or in (inbound communication to the component)
  • Type of communication is either backend (between the application components) or user (user access to a component GUI). Command line user access to a component from localhost is not noted here. GUI access is noted, though the recommended default is to restrict it to localhost
  • The status is either mandatory (needed to run Fed-BioMed) or optional (a Fed-BioMed experiment can run without this part)

On the node component (node + gui):

dir source destination destination port service type status comment
out node container researcher container TCP/50051 gRPC/TLS backend mandatory via Docker bridge network, using researcher container name
in localhost (host) node container TCP/8484 HTTP user optional Node GUI (published to host)
  • node and gui containers share a Docker volume and are typically co-located on the same host.
  • When running multiple node containers on the same host, each must publish its GUI on a distinct host port (e.g. 8484, 8485, …).


On the researcher component (researcher):

dir source destination destination port service type status comment
in node containers researcher container TCP/50051 gRPC/TLS backend mandatory inbound from any node on the Docker network (or from a remote host in cross-network setups)
in localhost (host) researcher container TCP/8888 HTTP user optional Jupyter notebook (published to host)
in localhost (host) researcher container TCP/6007 HTTP user optional TensorBoard (published to host via socat proxy; TensorBoard listens internally on TCP/6006)
  • The TensorBoard port published to the host is 6007, not the native 6006. Inside the researcher container a socat process forwards container:6007 → localhost:6006. TensorBoard must be started manually on port 6006 before the proxy can serve traffic.
  • In a cross-network / public IP setup, the researcher's host port 50051 is reachable from the internet and nodes on remote machines connect to it directly using the researcher's public IP. No additional port needs to be published on the node side as nodes always initiate the connection. See the Docker deployment guide for configuration details.

Mutual authentication (mTLS)

Mutual authentication changes how the two ends of an existing channel verify each other, not which channels exist. The researcher binds the same port and nodes still dial out to it, so enabling it requires no change to the filters described above — no port to open, no flow to add, no direction to reverse.

What it changes is the service carried on the backend channel of each scenario:

deployment scenario backend channel without mutual authentication with mutual authentication
Without containers node → researcher, TCP/50051 gRPC/TLS: the node trusts the certificate the endpoint presents, the researcher accepts any node gRPC/mTLS: the node pins a registered researcher certificate, the researcher requires a registered node certificate
With Docker containers node container → researcher container, TCP/50051 gRPC/TLS gRPC/mTLS


  • Where the surrounding infrastructure already authenticates the machines that reach each other, mutual authentication is a second, independent layer: it authenticates the Fed-BioMed parties talking over the channel, not the hosts carrying it. Neither replaces the other.
  • Certificates are exchanged out of band — e-mail, secure messaging, any trusted channel. Fed-BioMed opens no network flow to distribute them, so certificate exchange adds no entry to the matrix.
  • Mutual authentication imposes no naming or DNS requirement. A node verifies the researcher certificate it has pinned; when the address it dials is not among the names that certificate carries, it verifies against a name that is. Issuing the researcher certificate for the names nodes reach it at is recommended, not a condition for the channel to establish.
  • A node rejected for mutual authentication is refused inside the TLS handshake, so the connection is dropped at the researcher rather than filtered by the network. It is not visible as a blocked packet, and the researcher logs nothing per rejected node — see verifying and troubleshooting.