Skip to content

Configuring Nodes

Node Configuration

The Fed-BioMed framework consists of two main components: node and researcher. The node stores private datasets and performs training in response to the researcher's training requests. Communication between the node and the researcher component is facilitated through the RPC (Remote Procedure Call) protocol.

Basic node Configuration

A basic configuration for the node component includes the following settings:

  • A Python environment
  • A unique node ID
  • Security parameters, such as training plan approval mode and hashing algorithms
  • Connection credentials for communicating with the researcher component

Note

These basic configurations are generated automatically with default values. While it is possible to manually edit the configuration files, doing so may render certain parameters incompatible. For example, [server]/host and [server]/pem must remain consistent, as the latter depends on the former. To avoid such issues, it is strongly recommended to use the dedicated script for creating configurations: fedbiomed component create, with options described above.

Environment for Nodes

Fed-BioMed can be installed using pip. It can be installed into native host machine or on virtual environment using tools such as pyenv, conda or virtualenv. You can find more details in installation tutorial.

Node Component Installation

Fed-BioMed uses the default fbm-node directory to store all component-related files, including temporary files, variables, configuration files, certificates, and other essential documents.

When a basic command is executed, Fed-BioMed will automatically create a default fbm-node directory if it does not already exist. If the directory is already present, the system will use the existing one. The component directory is created relative to the directory where the Fed-BioMed commands are executed. For more details, please refer to the generic Component Creation Guide.

For example, the following sequence of commands will create a directory named my-workdir in the home directory, navigate to it, and then start the Fed-BioMed node. This operation will automatically instantiate the node component within the my-workdir directory, creating a folder named fbm-node, which serves as the default directory for the Fed-BioMed node component. Since fbm-node does not yet exist, the CLI will prompt you for permission to initialize the component.

mkdir $HOME/my-workdir
cd $HOME/my-workdir
fedbiomed node start

In another terminal, you can inspect the folder structure using the following command:

tree $HOME/my-workdir/fbm-node

The structure will resemble the tree below:

fbm-node
├── etc
│   ├── certs
│   │   ├── FBM_certificate.key
│   │   └── FBM_certificate.pem
│   └── config.ini
└── var
    ├── cache
    ├── db_NODE_992aab29-c485-463f-a84b-6ce055c17c2e.json
    ├── tmp
    └── training_plans

Please see section Using non-default Fed-BioMed node to select different node installations.

Managing the Node after Startup

After running the command fedbiomed node start in the previous section to start the node, you can follow the status of the node from another terminal.

To see the node status, run:

fedbiomed node status

The command reports whether the node process is running and, as described in the next section, the state of its connection to the researcher.

Checking the connection to the researcher

fedbiomed node status also prints the last connection state the node recorded with the researcher, so you can tell whether a node is actually reachable and connected without searching its logs:

fedbiomed node status
Node process:
 Field   | Value
---------+---------
 State   | running

Connection to researcher:
 Field                        | Value
------------------------------+----------------------
 State                        | connected
 Host                         | localhost
 Port                         | 50051
 Identity verified            | Yes
 Mutual authentication (mTLS) | Off
 Reason                       | -
 Connected since              | 2026-10-28T09:12:41Z
 Last update                  | 2026-10-28T09:12:41Z

The connection table contains the following fields:

Field Description
State connected, disconnected or failed (see below).
Host, Port Researcher address the node connects to (FBM_RESEARCHER_IP, FBM_RESEARCHER_PORT).
Identity verified Whether the node verified the researcher identity: Yes, No, or Unknown when it was not recorded.
Mutual authentication (mTLS) Whether the node authenticates itself to the researcher with its certificate: On, Off or Unknown. See mutual authentication.
Reason Readable detail of the current state, typically the error message.
Connected since When the node entered the current state.
Last update When the node last observed this state.

The connection states are:

  • connected: the channel to the researcher is established.
  • disconnected: the node is not connected. This is the state recorded while the node starts (Node starting, connecting to the researcher.), while the researcher does not answer and the node keeps retrying (Researcher server at ... is not available; retrying.), and when the node is stopped.
  • failed: the connection was refused, for example because the researcher certificate does not match the researcher name, the researcher requires mutual authentication, or gRPC returned an error. The Reason field gives the cause; see verifying and troubleshooting to diagnose it.

To also list the recent changes of the connection state, newest first, use the --history option. Each line gives the time, the state, the name of the event (the same as in the security audit) and the reason:

fedbiomed node status --history

To check a node that does not use the default component directory, pass its path as for any other node command:

fedbiomed node -p <path-to-node-dir> status --history

Reading the connection state

  • The state is written by the running node, so it is only current while the node runs. When the node is stopped, the command reports the state the node was in when it stopped.
  • Connection to researcher: none recorded yet means the node has not been started yet.
  • While the researcher is unreachable, the node retries every couple of seconds but refreshes Last update only every 30 minutes, and logs that the researcher is unavailable only every 5 minutes. An old Last update with a disconnected state therefore does not mean the node is stuck.

Stopping and restarting the node

You can stop or restart the node from another terminal as well:

fedbiomed node stop
fedbiomed node restart

If you don't want to use another terminal, running the node in the background is also possible using the --background option. This way, you can run the start/stop/restart commands from the same terminal.

fedbiomed node start --background

# Later, if we decided to restart the node on debug mode for example.
fedbiomed node restart --background --debug 

Note

When the background option is used, logs are going to be logged in "NODE_DIR/log/node_process.log" file, instead of the terminal.

Configuration file: config.ini

A configuration file is an ini file that is located in the component directory. Each configuration file is unique to one node.

The node reads this file when it starts, so a running node keeps the settings it started with. After editing the file, restart the node to apply the changes. The researcher certificate registered on the node is read the same way: the node pins the one it read at startup and uses it for the whole run, so registering or deleting it applies only on the next start.

The configuration file is structured following the sections below:

  • Default Parameters:

    • id: This is the unique ID that identifies the node.
    • component: Specifies the component type. It is always NODE for node component
    • version: Version of the configuration format to avoid using older configuration files with recent Fed-BioMed versions.
    • db: Relative path to the node's database, from this configuration file
    • name: A custom name given by the node user, to make the node easier to identify
  • Syslog:

    • enable: Boolean parameter (True/False) to activate system level logging. When enabled, it re-routes all the security logs into the default system level logging of the Operating System, so that System Admins can directly use the OS log files to debug if needed.
  • Authentication:

    • mutual_authentication: Boolean parameter (True/False) to activate mTLS between node and researcher. By default it's False for testing, should be set to True for deployment.

    Each node's certificate should be registered in the researcher (and vice-versa). If you haven't registered the node's certificate, you can find the detailed guide in mutual authentication.

  • Certificate:

    • private_key: Path to private key to use identify the component.
    • public_key: Path to public key to share with other parties (nodes and researcher) to verify its identify.

    Node certificates are generated automatically on creation. In case of a bug, or if you wish to use your own certificates, you can follow the detailed guide in mutual authentication for regenerating and re-registering certificates.

  • Researcher:

    • ip: The IP address of the researcher component that the node will connect to.
    • port: The port of the researcher component.
  • Security Parameters:

    • hashing_algorithm: The algorithm will be used for hashing training plan scripts to verify if the requested training plan matches the one approved on the node side.
    • training_plan_approval: Boolean value to switch training plan approval to verify training plan scripts before the training.
    • allow_default_training_plans: Boolean value to enable automatic approval of example training plans provided by Fed-BioMed.
    • secure_aggregation: Boolean parameter (True/False) to activate secure aggregation.
    • force_secure_aggregation: Boolean parameter (True/False) to force secure aggregation for every action that uses local dataset.
    • secagg_insecure_validation: A boolean parameter to activate insecure validation for secure aggregation rounds to verify the correctness of the aggregation on the researcher side. This option is intended for testing and debugging purposes and must be deactivated in production deployments.
    • allow_preproc: Boolean value to enable applying pre-processing to the datasets before using them. Original dataset is not modified.
    • allow_federated_analytics: Boolean value to enable computing statistics and analytics on the datasets. See Federated Analytics — Nodes for details.
    • minimum_samples: Integer value specifying the minimum number of samples required for a dataset to be registered on the node. Default is 0 (no minimum enforced).

An example for a config file is shown below;

[default]
id = node_73768d5f-6a66-47de-8533-1291c4ef59d1
component = NODE
version = 2.4.0
db = ../var/db_NODE_94572b0f-f55c-4167-b729-f16247c35a04.json
name = Default Node Alias

[syslog]
enable = False

[authentication]
mutual_authentication = True

[security]
hashing_algorithm = SHA256
allow_default_training_plans = True
training_plan_approval = False
secure_aggregation = True
force_secure_aggregation = False
secagg_insecure_validation = False
allow_preproc = True
allow_federated_analytics = True
minimum_samples = 0

[certificate]
private_key = certs/FBM_certificate.key
public_key = certs/FBM_certificate.pem


[researcher]
ip = localhost
port = 50051

Changing a setting

A node setting can be changed in three ways:

  • Manually: edit the value in config.ini, then restart the node.
  • Environment variables: set the FBM_<SECTION>_<KEY> variable when the node configuration is created (see Environment Variables).
  • GUI: edit the value in the Configuration tab of the Node Management page, then use Save & Restart (see Node GUI).

Using non-default Fed-BioMed node

The option --path that comes after specification node in Fed-BioMed command allows to use different node component in different directories than the default one. --path can be relative or absolute. As it is in default command execution, if the given directory for node is existing it will created automatically.

$ fedbiomed node --path my-node start
The command above will create a folder called my-node in the directory where the command is executed, or use the one already existing to start a node.

The --path flag can be used with any of the node subcommands as in the examples below.

$ fedbiomed node --path my-node dataset list
$ fedbiomed node --path my-node dataset add

Creating a component without doing any action

The component create action allows you to initialize a Fed-BioMed component without needing to start it or add a dataset to a node. This option is ideal for initializing a node component and configuring it later, such as making changes to the configuration file.

fedbiomed component create -c NODE --path </path/for/component>

The command will raise an error if a component has already been initialized in the specified -r root directory. To prevent this error, you can use the --exist-ok option.

Once the component is initialized, you can edit its configuration file located at path/to/component/etc/config.ini.


Environment Variables

Environment variables can be used to parameterize various options for creating the configuration file. The fields that can be controlled, along with their associated environment variables and default values, are described below.

Security

The defaults depend on how the node is run. A node installed directly on a machine uses permissive defaults, intended for local development. The fedbiomed/node Docker image uses restrictive defaults, closer to what a deployment needs.

Field Environment variable Default, no container Default, fedbiomed/node image
allow_default_training_plans FBM_SECURITY_ALLOW_DEFAULT_TRAINING_PLANS True False
training_plan_approval FBM_SECURITY_TRAINING_PLAN_APPROVAL False True
secure_aggregation FBM_SECURITY_SECURE_AGGREGATION True True
force_secure_aggregation FBM_SECURITY_FORCE_SECURE_AGGREGATION False False
secagg_insecure_validation FBM_SECURITY_SECAGG_INSECURE_VALIDATION True False
allow_preproc FBM_SECURITY_ALLOW_PREPROC True False
allow_federated_analytics FBM_SECURITY_ALLOW_FEDERATED_ANALYTICS True False
minimum_samples FBM_SECURITY_MINIMUM_SAMPLES 0 0

The local federation defined in docker/local-federation.yml runs the fedbiomed/node image for testing, and sets training_plan_approval to False so that experiments run without approving each training plan, and allow_preproc and allow_federated_analytics to True.

Security values in a deployment

These values define what the node accepts to run on its data. Do not rely on the defaults in a deployment: set each value explicitly, according to the node's data governance policy. In particular, keep training_plan_approval enabled, and allow_default_training_plans and secagg_insecure_validation disabled. Enable allow_preproc and allow_federated_analytics only when they are needed, and set minimum_samples to the smallest dataset size the node accepts to share.

Researcher

Field Environment variable Default
ip FBM_RESEARCHER_IP localhost
port FBM_RESEARCHER_PORT 50051

Examples

Create the new component with a specified IP and port for the researcher, and disabling secure aggregation. Forcefully delete and recreate the file if it was already existing.

export FBM_RESEARCHER_IP=121.203.21.147
export FBM_RESEARCHER_PORT=8909
export FBM_SECURITY_SECURE_AGGREGATION=0
fedbiomed component create -c NODE -p my-node