Versions¶
Fed-BioMed stores and checks version numbers for several of its components. The semantics of the versions are as follows:
- different major version: incompatibility that results in halting the execution immediately
- different minor or micro version: backward compatibility, provide a warning message if versions are different
This page tracks the version changes for each component, to provide further information when incompatibilities are detected.
Configuration files¶
- researcher configuration file
- node configuration file
- node state
- researcher breakpoint
- messaging protocol
Note that due to the two-sided nature of the communication, every change to the messaging protocol is equivalent to a major change.
Messaging protocol incompatible versions
In case of version mismatch, the only solution is to upgrade the software to have the same version on researcher and all nodes.
Upgrading an existing deployment¶
When upgrading from 6.4.1 to a release with mutual authentication, complete these steps before resuming experiments:
- Upgrade the researcher and every node together. The messaging protocol must match across the federation; see version 8 below.
- Review each component's
etc/config.ini. For compatibility, loading an older configuration without[authentication]section, automatically starts the component withmutual_authentication = Falseand logs a warning at startup. Upgrading does not enable authentication automatically. Add the section to the file and set the value toTrueon the researcher and every node in a deployment. - Check the existing certificates. A researcher certificate registered on a node must have a DNS or IP Subject Alternative Name (SAN). Older certificates without these names must be regenerated or replaced before enabling mTLS. Prefer names that nodes use to reach the researcher; see names on the researcher certificate. Check expiry as well: expired certificates cannot be registered.
- Exchange and register certificates through a trusted channel. The researcher registers every node's certificate; each node registers the researcher's certificate. Node-to-node registration is not needed. After regenerating or replacing a certificate, redistribute it and update existing registrations with
--upsert. Follow the registration procedure. - Restart components to apply the changes. Configuration changes and changes to a component's own certificate/key require a restart. Restart each node after changing its registered researcher certificate. The researcher picks up changes to registered node certificates on subsequent handshakes without a restart.
- Verify authentication before training. Check
fedbiomed node statuson each node: the connection should beconnected, with mutual authenticationOnand identity verificationYes. See verifying and troubleshooting.
Migrating from bundled VPN deployments¶
The bundled VPN images, envs/vpn deployment files, and scripts/fedbiomed_vpn helper have been removed. Existing deployments using them must plan a transition to the standard Docker images or a native installation; updating the source checkout does not migrate running containers or their volumes.
Back up and preserve each component's configuration, database, certificates/private keys, datasets, and experiment files before changing containers. Map the existing component directories to the standard images' persistent paths (/fbm-node and /fbm-researcher), and update dataset mounts and researcher addresses as needed. Complete the mTLS checklist above and verify the replacement deployment before retiring the old containers.
If institutional policy requires a VPN, provide it independently of Fed-BioMed. The optional Docker VPN guide illustrates a third-party setup; it does not migrate the old VPN configuration, and mTLS remains required.
Messaging protocol¶
Version 8¶
Version 8 removes the packaged default node-to-node EC private key. Channel setup now carries only public material: ChannelSetupRequest and ChannelSetupReply are in plaintext.
This setup format is incompatible with version 7, which encrypted the initial exchange with the repository-wide default key. Researchers and all nodes participating in the same federation must therefore use messaging protocol version 8 together.