Chapter 3. Automatically provisioning and onboarding RHEL for Edge devices with FDO client and server

1. Device initialization: The device manufacturer performs the first phase. During this phase, the manufacturer configure the device to perform onboarding after purchase. On completion of this phase:

   • The device stores a set of credentials to prove its identity.
   • The manufacturer creates an ownership voucher, which is a digital document that proves the ownership chain of the device.
   • The device receives a globally unique identifier (GUID).
2. Transfer of ownership: The second phase occurs after the device is purchased. During this phase, the device is onboarded to the new owner’s infrastructure.

1. Device initialization (FDO DI protocol)

   1. The device client contacts the manufacturer server.
   2. The client and server generate credentials, which are stored on the device by the client.
   3. The manufacturer server produces the ownership voucher containing the network address of the rendezvous server, or Owner server in the case of rendezvous (RV) bypass.
   4. The manufacturer server assigns a globally unique identifier (GUID) to the device.
   5. Device initialization completes, and the device is ready for onboarding at the owner’s facility.

2. On-site onboarding (FDO protocols TO0, TO1, TO2)

   1. Before the first boot of the device, the server administrator uploads the ownership voucher to the Owner server.
   2. The upload causes the Owner server to extract the rendezvous server’s network address from the ownership voucher.
   3. The Owner server contacts the rendezvous server and, by using the ownership voucher, proves it is the legitimate owner of the corresponding device.
   4. The Owner server provides the rendezvous server with its network addresses so that the device client can contact the Owner server.
   5. The rendezvous server stores the Owner server information for eventual use by the device client.
   6. On first boot, the device client retrieves the rendezvous server network address from its on-board device credentials and contacts the rendezvous server.
   7. The rendezvous server looks up the device’s ownership voucher and associated owner network addresses and returns them to the device client.
   8. The device client disconnects from the rendezvous server and attempts to connect to the Owner server by using the supplied network addresses.
   9. The device client and Owner server establish mutual trust by authenticating each other by using information from the ownership voucher and device credentials.
   10. The device client and Owner server establish a securely encrypted communications channel.
   11. The Owner server provisions the device over the secure channel by exchanging ServiceInfo key-value data.
   12. The device client uses the ServiceInfo data to implement the desired device configuration.
   13. On completion of the configuration process, the device is operational, and the FDO workflow ends.

Procedure

1. Install the Manufacturing server package:

   $ sudo dnf install go-fdo-server-manufacturer

2. Verify that the Manufacturing server’s systemd unit file and the default configuration directories were created:

   $ sudo systemctl list-unit-files | grep go-fdo-server-manufacturer

   go-fdo-server-manufacturer.service disabled disabled

3. Configure certificates by moving the test certificates generated in the previous section to the manufacturer’s configuration path.

4. After configuration, enable and start the service:

   $ systemctl enable --now go-fdo-server-manufacturer

Procedure

1. Install the required credentials by moving all certificates and keys provided by your organization into the /etc/pki/go-fdo-server/ directory.

2. Secure the certificate and key files. Restricted permissions are required to protect the integrity of the credentials. Set the ownership and permissions for the private keys so they are accessible only by the go-fdo-server-manufacturer user:

   $ sudo chown go-fdo-server-manufacturer:go-fdo-server /etc/pki/go-fdo-server/device-ca.key /etc/pki/go-fdo-server/manufacturer.key

   $ sudo chmod 600 /etc/pki/go-fdo-server/device-ca.key /etc/pki/go-fdo-server/manufacturer.key

3. Modify the /etc/go-fdo-server/manufacturing.yaml configuration file to define your operational parameters.

   Note

   Access to this file is restricted to the go-fdo-server group by default.

4. Define the server parameters. Ensure the following items are correctly mapped in your YAML file:

   Database (db)

   The path to the server’s database.

   Networking (http)

   The server’s HTTP endpoint IP and port.

   Manufacturer Key

   The path to the manufacturer’s private key.

   Device CA

   The paths to the Device CA certificate and private key.

   Owner Certificate

   The path to the Owner server’s public certificate.

   Example manufacturing.yaml configuration

   log:
     level: info
   db:
     type: sqlite
     dsn: file:/var/lib/go-fdo-server-manufacturer/db.sqlite
   http:
     ip: 0.0.0.0
     port: "8038"
   manufacturing:
     key: /etc/pki/go-fdo-server/manufacturer.key
     device_ca:
       cert: /etc/pki/go-fdo-server/device-ca.crt
       key: /etc/pki/go-fdo-server/device-ca.key
   owner:
     cert: /etc/pki/go-fdo-server/owner.crt

Procedure

1. Open the Manufacturer server’s default port in the firewalld service:

   $ sudo firewall-cmd --add-port=8038/tcp --permanent

   Note

   If you customized the http.port parameter in your configuration file, use that port number instead of the default.

   If you change the default port, you must relabel the new port in SELinux to enable the go-fdo-server service to bind to it. Failure to do so might cause the service to fail to start or be blocked by security policies.

   To enable traffic on a custom port, such as port 8040, run the following command to install the policycoreutils-python-utils package to use the semanage command.

   $ sudo semanage port -a -t fdo_port_t -p tcp 8040

2. Reload the firewall to apply the changes:

   $ sudo firewall-cmd --reload

3. Enable and start the manufacturer server by using the systemd system and service manager:

   $ sudo systemctl enable --now go-fdo-server-manufacturer.service

   This ensures the server starts automatically upon system reboot.

4. Verify the manufacturer server status:

   $ systemctl status go-fdo-server-manufacturer.service

   ● go-fdo-server-manufacturer.service - Go FDO manufacturer server
        Loaded: loaded (/usr/lib/systemd/system/go-fdo-server-manufacturer.service; enabled; preset: disabled)
        Active: active (running) since Fri 2026-03-20 16:15:47 EDT; 38s ago
   ...

5. Optional: Verify that the server’s network endpoint is functioning and accessible by probing the serve’s /health API endpoint:

   $ curl http://<ip-address>:8038/health

   {"message":"the service is up and running","status":"OK","version":"1.0.0"}

   To validate that your firewalld configuration is correct, perform this check from a different computer on the network. Local requests typically bypass firewall filtering rules.

Procedure

1. Install the Rendezvous server package:

   $ sudo dnf install go-fdo-server-rendezvous

   The package installs several files, creates the go-fdo-server group and go-fdo-server-rendezvous user, and installs a systemd service for running the Rendezvous server.

Procedure

1. Open the server’s HTTP port in the firewalld service:

   $ sudo firewall-cmd --add-port=8041/tcp --permanent

   $ sudo firewall-cmd --reload

2. Enable and start the Rendezvous server by using the systemd service:

   $ sudo systemctl enable --now go-fdo-server-rendezvous.service

3. Verify the server status:

   $ sudo systemctl status go-fdo-server-rendezvous.service

   ● go-fdo-server-rendezvous.service - Go FDO Rendezvous server
        Loaded: loaded (/usr/lib/systemd/system/go-fdo-server-rendezvous.service; enabled; preset: disabled)
        Active: active (running) since Fri 2026-03-20 17:21:34 EDT; 16h ago

4. Optional: Verify that the server’s network endpoint is functioning and accessible:

   $ curl http://192.168.124.132:8041/health

   Example output

   {"message":"the service is up and running","status":"OK","version":"1.0.0"}

   To validate that your firewalld configuration is correct, perform this check from a different computer on the network. Local requests typically bypass firewall filtering rules.

   Expand

   Parameter	Description
   log.level	The logging level. Allowed values: debug, info (default), warn, and error.
   db.type	The database type. Allowed values: sqlite and postgres.
   db.dsn	The database connection string (for example, file:database.db for SQLite, or host=localhost port=5432 user=postgres password=secret dbname=mydb for PostgreSQL).
   http.ip	The HTTP server IP address or hostname.
   http.port	The HTTP server port (string).
   http.cert	Optional: The path to the certificate file to use for server authentication.
   http.key	Optional: The path to the private key file of the cert certificate.

   Show more

Procedure

1. Install the go-fdo-server-owner package:

   $ sudo dnf install go-fdo-server-owner

   The package installs several files, creates the go-fdo-server group and go-fdo-server-owner user, and installs a systemd service for running the Owner server.

2. Verify that the Owner server’s systemd unit file is available:

   $ sudo systemctl list-unit-files | grep go-fdo-server-owner

   go-fdo-server-owner.service disabled

Procedure

1. Open the /etc/go-fdo-server/owner.yaml configuration file in a text editor.

2. Provide values for the following mandatory configuration items:

   • Database configuration: The connection details for the server’s database.
   • HTTP endpoint address: The address where the server listens for requests.
   • Device CA certificate path: The path to the Device CA certificate file.
   • Owner server public certificate path: The path to the Owner server’s public certificate file.
   • Owner server private key path: The path to the Owner server’s private key file.
3. Optional: Add a list of FDO ServiceInfo Modules (FSIM) to the configuration if you require specific device provisioning during onboarding.
4. Save the changes and close the file.

5. Set the ownership on the owner.key file to the go-fdo-server-owner user and the go-fdo-server group:

   $ sudo chown go-fdo-server-owner:go-fdo-server /etc/pki/go-fdo-server/owner.key

6. Set the permissions on the owner.key file to restrict access:

   $ sudo chmod 600 /etc/pki/go-fdo-server/owner.key

Procedure

1. Open your Owner server configuration file (for example, /etc/go-fdo-server/owner.yaml) in a text editor.

2. Define the fsim section and add the required modules. The following example configures a script download, a command execution, and a large file download by using fdo.wget:

   log:
     level: "info"
   
   db:
     type: "sqlite"
     dsn: "file:/var/lib/go-fdo-server-owner/db.sqlite"
   
   http:
     ip: "0.0.0.0"
     port: "8043"
   
   device_ca:
     cert: "/etc/pki/go-fdo-server/device-ca.crt"
   
   owner:
     cert: "/etc/pki/go-fdo-server/owner.crt"
     key: "/etc/pki/go-fdo-server/owner.key"
   
   fsim:
     - module: "fdo.download"
       files:
         - src: "/var/lib/go-fdo-server-owner/scripts/setup-env.sh"
           dst: "/usr/local/bin/setup-env.sh"
           permissions: "0755"
   
     - module: "fdo.command"
       commands:
         - command: ["/usr/local/bin/setup-env.sh", "--init"]
           description: "Initializing environment"
   
     - module: "fdo.wget"
       files:
         - src: "http://distribution.example.com/images/worker-payload.tar.gz"
           dst: "/var/tmp/worker-payload.tar.gz"
           may_fail: true

3. Save the file and restart the Owner server service to apply the configuration:

   $ sudo systemctl restart fdo-owner-server

Procedure

1. Ensure that the system firewall does not block the server’s HTTP endpoint by opening the server’s network port:

   $ sudo firewall-cmd --add-port=8043/tcp --permanent

2. Restart the firewalld service:

   $ sudo systemctl restart firewalld

3. Enable and start the Owner server by using the systemd service:

   $ sudo systemctl enable --now go-fdo-server-owner.service

4. Verify that the server is active:

   $ sudo systemctl status go-fdo-server-owner.service

   ● go-fdo-server-owner.service - Go FDO owner server
        Loaded: loaded (/usr/lib/systemd/system/go-fdo-server-owner.service; enabled; preset: disabled)
        Active: active (running) since Sun 2026-03-22 16:35:04 EDT; 18s ago
   ...

Procedure

1. Install the packages by using a Containerfile:

   FROM registry.redhat.io/rhel10/rhel-bootc:10.2
   #Install the go-fdo-client package using your distribution's package manager:
   RUN dnf install -y go-fdo-client && dnf clean all

   Note

   If you plan to use a Trusted Platform Module (TPM) for credential storage, you must also install tpm2-tools in the Containerfile. For more information, see <Using_a_TPM>.

2. Build the container image:

   $ podman build -t quay.io/example/fdo-client-bootc:latest -f Containerfile .

3. Push the container image to the registry:

   $ podman push quay.io/example/fdo-client-bootc:latest

4. Reference the container image in your Kickstart file by using the ostreecontainer directive to deploy it on the target device.

Procedure

1. Identify the required configuration parameters. To view a comprehensive list of all available flags and options for a specific subcommand, pass the --help flag:

   $ go-fdo-client <command> --help

2. Create or edit a configuration file. You can use either the YAML (.yaml, .yml) or TOML (.toml) format. Ensure that any file paths defined within the configuration are either absolute or relative to your current working directory.

3. Run the client by using a configuration file. Use the --config flag to point the client to your specific settings:

   $ go-fdo-client <command> --config /etc/fdo/config.yaml

   Note

   The file format is automatically detected by the extension provided in the --config path.

4. Optional: Override settings by using CLI flags. The client resolves configuration values based on a specific hierarchy. If a value is defined in multiple places, the client applies them in the following order of precedence (from highest to lowest):

   • Positional arguments: Such as the server URL for device-init.
   • CLI flags: --key or --kex.
   • Configuration file values: Settings defined in your YAML or TOML file.
   • Default values: Built-in application defaults.

Procedure

1. Initialize the device by using the TPM:

   $ sudo go-fdo-client device-init http://manufacturer.example.com:8038 --key ec256 --tpm /dev/tpmrm0

2. Run the onboarding command by using the TPM:

   $ sudo go-fdo-client onboard --key ec256 --kex ECDH256 \ --tpm /dev/tpmrm0

Procedure

1. Verify the credential by using the command appropriate for your storage method:

   • For file-based storage:

     If the credential was stored in the boot directory during initialization, use the --blob flag to point to the file path.

     $ sudo go-fdo-client print --blob /boot/device_credential

   • For Trusted Platform Module (TPM)-based storage:

     If the device uses a Hardware Security Module (HSM) or TPM for enhanced security, use the --tpm flag and specify the TPM resource manager path.

     $ sudo go-fdo-client print --tpm /dev/tpmrm0

Verification

1. Verify the following command output parameters to ensure the device is prepared for deployment:

   • The device’s public key information
   • Rendezvous server information
   • Ownership header status
2. Ensure the output does not return an error, which indicates a corrupted or missing credential.