Chapter 7. Automatically provisioning and onboarding RHEL for Edge devices with FDO

1. The Device contacts the Manufacturing server
2. The Manufacturing server generates an Ownership Voucher and the Device Credentials for the Device.
3. The Ownership Voucher is transferred to the Owner onboarding server.

4. The Owner onboarding server transfers the Ownership Voucher to the Rendezvous server, which makes a mapping of the Ownership Voucher to the Owner.
5. The device client reads device credentials.
6. The device client connects to the network.
7. After connecting to the network, the Device client contacts the Rendezvous server.
8. The Rendezvous server sends the owner endpoint URL to the Device Client, and registers the device.
9. The Device client connects to the Owner onboarding server shared by the Rendezvous server.
10. The Device proves that it is the correct device by signing a statement with a device key.
11. The Owner onboarding server proves itself correct by signing a statement with the last key of the Owner Voucher.
12. The Owner onboarding server transfers the information of the Device to the Service Info API server.
13. The Service info API server sends the configuration for the Device.
14. The Device is onboarded.

1. Install and register a RHEL system
2. Install RHEL image builder

3. By using RHEL image builder, create a blueprint with customizations for RHEL for a rhel-edge-container image type.

   name = "rhel-edge-container"
   description = "Minimal RHEL for Edge Container blueprint"
   version = "0.0.1"

4. Import the RHEL for Edge Container blueprint in RHEL image builder
5. Create a RHEL for Edge Container image
6. Use the RHEL for Edge Container image to serve the OSTree commit, which will be later used when building the RHEL for Edge Simplified Installer image type

7. Create a blueprint for and edge-simplified-installer image type with customizations for storage device path and FDO customizations

   name = "rhel-edge-simplified-installer-with-fdo"
   description = "Minimal RHEL for Edge Simplified Installer with FDO blueprint"
   version = "0.0.1"
   packages = []
   modules = []
   groups = []
   distro = ""
   
   [customizations]
   installation_device = "/dev/vda"
   
   [customizations.fdo]
   manufacturing_server_url = "http://10.0.0.2:8080"
   diun_pub_key_insecure = "true"

8. Build a simplified installer RHEL for Edge image
9. Download the RHEL for Edge simplified installer image
10. At this point, the FDO server infrastructure should be up and running, and the specific onboarding details handled by the service-info API server, that is part of the owner’s infrastructure, are configured
11. Install the simplified installer ISO image to a device. The FDO client runs on the Simplified Installer ISO and the UEFI directory structure makes the image bootable.
12. The network configuration enables the device to reach out to the manufacturing server to perform the initial device credential exchange.
13. After the system reaches the endpoint, the device credentials are created for the device.
14. The device uses the device credentials to reach the Rendezvous server, where it checks the cryptographic credentials based on the vouchers that the Rendezvous server has, and then the Rendezvous server redirects the device to the Owner server.
15. The device contacts the Owner server. They establish a mutual trust and the final steps of onboarding happen based on the configuration of the Service-info API server. For example, it installs the SSH keys in the device, transfer the files, create the users, run the commands, encrypt the filesystem, and so on.

Procedure

1. Generate the keys and certificates in the /etc/fdo directory:

   $ for i in "diun" "manufacturer" "device-ca" "owner"; do fdo-admin-tool generate-key-and-cert $i; done
   $ ls keys
   device_ca_cert.pem device_ca_key.der diun_cert.pem diun_key.der manufacturer_cert.pem manufacturer_key.der owner_cert.pem owner_key.der

2. Check the key and certificates that were created in the /etc/fdo/keys directory:

   $ tree keys

   You can see the following output:

   – device_ca_cert.pem
   – device_ca_key.der
   – diun_cert.pem
   – diun_key.dre
   – manufacturer_cert.pem
   – manufacturer_key.der
   – owner_cert.pem
   – owner_key.pem

Procedure

1. Install the fdo-admin-cli package:

   # yum install -y fdo-admin-cli

2. Check if the fdo-manufacturing-server RPM package is installed:

   $ rpm -qa | grep fdo-manufacturing-server --refresh

3. Check if the files were correctly installed:

   $ ls /usr/share/doc/fdo

   You can see the following output:

   Output:
   manufacturing-server.yml
   owner-onboarding-server.yml
   rendezvous-info.yml
   rendezvous-server.yml
   serviceinfo-api-server.yml

4. Optional: Check the content of each file, for example:

   $ cat /usr/share/doc/fdo/manufacturing-server.yml

5. Configure the Manufacturing server. You must provide the following information:

   • The Manufacturing server URL
   • The IP address or DNS name for the Rendezvous server

   • The path to the keys and certificates you generated. See Generating key and certificates.

     You can find an example of a Manufacturing server configuration file in the /usr/share/doc/fdo/manufacturing-server.yml directory. The following is a manufacturing server.yml example that is created and saved in the /etc/fdo directory. It contains paths to the directories, certificates, keys that you created, the Rendezvous server IP address and the default port.

     session_store_driver:
       Directory:
         path: /etc/fdo/stores/manufacturing_sessions/
     ownership_voucher_store_driver:
       Directory:
         path: /etc/fdo/stores/owner_vouchers
     public_key_store_driver:
       Directory:
         path: /etc/fdo/stores/manufacturer_keys
     bind: "0.0.0.0:8080"
     protocols:
       plain_di: false
       diun:
         mfg_string_type: SerialNumber
         key_type: SECP384R1
         allowed_key_storage_types:
           - Tpm
           - FileSystem
         key_path: /etc/fdo/keys/diun_key.der
         cert_path: /etc/fdo/keys/diun_cert.pem
     rendezvous_info:
       - deviceport: 8082
         ip_address: 192.168.122.99
         ownerport: 8082
         protocol: http
     manufacturing:
       manufacturer_cert_path: /etc/fdo/keys/manufacturer_cert.pem
       device_cert_ca_private_key: /etc/fdo/keys/device_ca_key.der
       device_cert_ca_chain: /etc/fdo/keys/device_ca_cert.pem
       owner_cert_path: /etc/fdo/keys/owner_cert.pem
       manufacturer_private_key: /etc/fdo/keys/manufacturer_key.der

6. Start the Manufacturing server.

   1. Check if the systemd unit file are in the server:

      # systemctl list-unit-files | grep fdo | grep manufacturing
      fdo-manufacturing-server.service disabled disabled

   2. Enable and start the manufacturing server.

      # systemctl enable --now fdo-manufacturing-server.service

   3. Open the default ports in your firewall:

      # firewall-cmd --add-port=8080/tcp --permanent
      # systemctl restart firewalld

   4. Ensure that the service is listening on the port 8080:

      # ss -ltn

7. Install RHEL for Edge onto your system using the simplified installer. See Building simplified installer images to provision a RHEL for Edge image.

Procedure

1. Install the fdo-rendezvous-server RPM packages:

   # yum install -y fdo-rendezvous-server

2. Create the rendezvous-server.yml configuration file, including the path to the manufacturer certificate. You can find an example in /usr/share/doc/fdo/rendezvous-server.yml. The following example shows a configuration file that is saved in /etc/fdo/rendezvous-server.yml.

   storage_driver:
     Directory:
       path: /etc/fdo/stores/rendezvous_registered
   session_store_driver:
     Directory:
       path: /etc/fdo/stores/rendezvous_sessions
   trusted_manufacturer_keys_path: /etc/fdo/keys/manufacturer_cert.pem
   max_wait_seconds: ~
   bind: "0.0.0.0:8082"

3. Check the Rendezvous server service status:

   # systemctl list-unit-files | grep fdo | grep rende
   fdo-rendezvous-server.service disabled disabled

   1. If the service is stopped and disabled, enable and start it:

      # systemctl enable --now fdo-rendezvous-server.service

4. Check that the server is listening on the default configured port 8082:

   # ss -ltn

5. Open the port if you have a firewall configured on this server:

   # firewall-cmd --add-port=8082/tcp --permanent
   # systemctl restart firewalld

Procedure

1. Install the required RPMs in this server:

   # dnf install -y fdo-owner-cli fdo-owner-onboarding-server

2. Prepare the owner-onboarding-server.yml configuration file and save it to the /etc/fdo/ directory. Include the path to the certificates you already copied and information about where to publish the Owner server service in this file.

   The following is an example available in /usr/share/doc/fdo/owner-onboarding-server.yml. You can find references to the Service Info API, such as the URL or the authentication token.

   ---
   ownership_voucher_store_driver:
     Directory:
       path: /etc/fdo/stores/owner_vouchers
   session_store_driver:
     Directory:
       path: /etc/fdo/stores/owner_onboarding_sessions
   trusted_device_keys_path: /etc/fdo/keys/device_ca_cert.pem
   owner_private_key_path: /etc/fdo/keys/owner_key.der
   owner_public_key_path: /etc/fdo/keys/owner_cert.pem
   bind: "0.0.0.0:8081"
   service_info_api_url: "http://localhost:8083/device_info"
   service_info_api_authentication:
     BearerToken:
       token: Kpt5P/5flBkaiNSvDYS3cEdBQXJn2Zv9n1D50431/lo=
   owner_addresses:
     - transport: http
       addresses:
         - ip_address: 192.168.122.149

3. Create and configure the Service Info API.

   1. Add the automated information for onboarding, such as user creation, files to be copied or created, commands to be executed, disk to be encrypted, and so on. Use the Service Info API configuration file example in /usr/share/doc/fdo/serviceinfo-api-server.yml as a template to create the configuration file under /etc/fdo/.

      ---
      service_info:
        initial_user:
          username: admin
          sshkeys:
          - "ssh-rsa AAAA...."
        files:
        - path: /root/resolv.conf
          source_path: /etc/resolv.conf
        commands:
        - command: touch
          args:
          - /root/test
          return_stdout: true
          return_stderr: true
        diskencryption_clevis:
        - disk_label: /dev/vda4
          binding:
            pin: tpm2
            config: "{}"
          reencrypt: true
        additional_serviceinfo: ~
      bind: "0.0.0.0:8083"
      device_specific_store_driver:
        Directory:
          path: /etc/fdo/stores/serviceinfo_api_devices
      service_info_auth_token: Kpt5P/5flBkaiNSvDYS3cEdBQXJn2Zv9n1D50431/lo=
      admin_auth_token: zJNoErq7aa0RusJ1w0tkTjdITdMCWYkndzVv7F0V42Q=

4. Check the status of the systemd units:

   # systemctl list-unit-files | grep fdo
   fdo-owner-onboarding-server.service        disabled        disabled
   fdo-serviceinfo-api-server.service         disabled        disabled

   1. If the service is stopped and disabled, enable and start it:

      # systemctl enable --now fdo-owner-onboarding-server.service
      # systemctl enable --now fdo-serviceinfo-api-server.service

      Note

      You must restart the systemd services every time you change the configuration files.

5. Check that the server is listening on the default configured port 8083:

   # ss -ltn

6. Open the port if you have a firewall configured on this server:

   # firewall-cmd --add-port=8081/tcp --permanent
   # firewall-cmd --add-port=8083/tcp --permanent
   # systemctl restart firewalld

Procedure

1. Start the installation process by booting the RHEL for Edge simplified installer image on your device. You can install it from a CD-ROM or from a USB flash drive, for example.

2. Verify through the terminal that the device has reached the manufacturing service to perform the initial device credential exchange and has produced an ownership voucher.

   You can find the ownership voucher at the storage location configured by the ownership_voucher_store_driver: parameter at the manufacturing-sever.yml file.

   The directory should have an ownership_voucher file with a name in the GUID format which indicates that the correct device credentials were added to the device.

   The onboarding server uses the device credential to authenticate against the onboarding server. It then passes the configuration to the device. After the device receives the configuration from the onboarding server, it receives an SSH key and installs the operating system on the device. Finally, the system automatically reboots, encrypts it with a strong key stored at TPM.