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
researchercomponent
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. TheReasonfield 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 yetmeans the node has not been started yet.- While the researcher is unreachable, the node retries every couple of seconds but refreshes
Last updateonly every 30 minutes, and logs that the researcher is unavailable only every 5 minutes. An oldLast updatewith adisconnectedstate 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 alwaysNODEfor node componentversion: 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 filename: 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 is0(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
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