1. Composing a RHEL rpm-ostree image using the image builder tool. You can access image builder through a command-line interface in the composer-cli tool, or use a graphical user interface in the RHEL web console.
2. Deploying the image using RHEL installer.

1. Install and register a RHEL system
2. Install image builder
3. Using image builder, create a blueprint with customizations for RHEL for Edge Container image
4. Import the RHEL for Edge blueprint in image builder
5. Create a RHEL for Edge image embed in an OCI container with a webserver ready to deploy the commit as an OSTree repository
6. Download the RHEL for Edge Container image file
7. Deploy the container serving a repository with the RHEL for Edge Container commit
8. Using image builder, create another blueprint for RHEL for Edge Installer image
9. Create a RHEL for Edge Installer image configured to pull the commit from the running container embedded with RHEL for Edge Container image
10. Download the RHEL for Edge Installer image
11. Run the installation

1. Install and register a RHEL system
2. Install image builder
3. Using image builder, create a blueprint for RHEL for Edge image
4. Import the RHEL for Edge blueprint in image builder
5. Create a RHEL for Edge Commit (.tar) image
6. Download the RHEL for Edge image file
7. Set up a web server
8. Create a new blueprint for a RHEL for Edge Installer (.iso)
9. Create the RHEL for Edge Installer (.iso) image, pointing at the OSTree content from the RHEL for Edge Commit (.tar) artifact
10. Download the RHEL for Edge installer ISO image you created
11. Boot the edge device using the RHEL for Edge Installer ISO image

Procedure

1. Install the following packages on the virtual machine.

   • osbuild-composer
   • composer-cli
   • cockpit-composer
   • bash-completion
   • firewalld

   # yum install osbuild-composer composer-cli cockpit-composer bash-completion firewalld

   Image builder is installed as an application in RHEL web console.

2. Reboot the virtual machine

3. Configure the system firewall to allow access to the web console:

   # firewall-cmd --add-service=cockpit && firewall-cmd --add-service=cockpit --permanent

4. Enable image builder.

   # systemctl enable osbuild-composer.socket cockpit.socket --now

   The osbuild-composer and cockpit services start automatically on first access.

5. Load the shell configuration script so that the autocomplete feature for the composer-cli command starts working immediately without reboot:

   $ source /etc/bash_completion.d/composer-cli

Procedure

1. Create a repository source file:

   id = "repository_id"
   name = "repository_name"
   type = "repository_type"
   url = "repository-url"
   check_gpg = false
   check_ssl = false

   For example:

   id = "k8s"
   name = "Kubernetes"
   type = "yum-baseurl"
   url = "https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64"
   check_gpg = false
   check_ssl = false
   system = false

2. Save the file in the TOML format.

3. Add the new third-party source with the following command:

   $ composer-cli sources add <file-name>.toml

Procedure

1. Create a repository source file:

   check_gpg = true
   check_ssl = true
   distros = ["list_of_distributions"]
   id = "repository_id"
   name = "repository-name"
   system = false
   type = ""repository_type"
   url = "repository-url"

   For example, to specify the distribution:

   check_gpg = true
   check_ssl = true
   distros = ["rhel-8"]
   id = "rh9-local"
   name = "packages for RHEL"
   system = false
   type = "yum-baseurl"
   url = "http://local/repos/rhel8/projectrepo/"

2. Save the file in the TOML format.

Procedure

1. Access the folder where you want to create a repository:

   $ cd repo/

2. Run the createrepo_c to create a repository from RPM packages:

   $ createrepo_c .

3. Access the directory where the repodata is:

   $ cd repodata/

4. Set up a repository by signing your repomd.xml file:

   $ gpg -u YOUR-GPG-KEY-EMAIL --yes --detach-sign --armor repomd.xml

5. Check the GPG signature.

   1. Set check_repogpg = true in the repository source.

   2. If your key is available over https, set the gpgkeys field with the key URL for the key. You can add as many URL keys as you need The following is an example:

      check_gpg = true
      check_ssl = true
      id = "repository_id"
      name = "repository_name"
      system = false
      type = "repository_type"
      url = "repository_URL"
      check_repogpg = true
      gpgkeys=["_GPG_key_URL"]

   3. Optional: You can embed the whole key into the gpgkeys field. You can add as many keys as you need. For example, add the GPG key directly in the gpgkeys field:

      check_gpg = true
      check_ssl = true
      check_repogpg
      id = "repository_id"
      name = "repository_name"
      system = false
      type = "repository_type"
      url = "repository_URL"
      gpgkeys=["GPG_key"]

Procedure

1. Create a directory where you want to store your repository overrides:

   $ sudo mkdir -p /etc/osbuild-composer/repositories

2. You can create your own JSON file structure.

3. Create a JSON file, using a name corresponding to your RHEL version. Alternatively, you can copy the file for your distribution from /usr/share/osbuild-composer/ and modify its content.

   For RHEL 8, use /etc/osbuild-composer/repositories/rhel-88.json.

4. Add the following structure to your JSON file, for example:

   {
       "<ARCH>": [
           {
               "name": "baseos",
               "baseurl": "http://mirror.example.com/composes/released/RHEL-8/8.0/BaseOS/x86_64/os/",
               "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (…​)",
               "check_gpg": true,
               "metadata_expire": ""
           }
       ]
   }

   Specify only one of the following attributes:

   • baseurl - string: a base URL of the repository.
   • metalink - string: a URL of a metalink file that contains a list of valid mirror repositories.

   • mirrorlist - string: a URL of a mirrorlist file that contains a list of valid mirror repositories

     The remaining fields are optional.

     1. Alternatively, you can copy the JSON file for your distribution.

        1. Copy the repository file to the directory you created. In the following command, replace rhel-version.json with your RHEL version, for example: rhel-8.json.

           $  cp /usr/share/osbuild-composer/repositories/rhel-version.json /etc/osbuild-composer/repositories/

5. Using a text editor, edit the baseurl paths in the rhel-8.json file and save it. For example:

   $ vi /etc/osbuild-composer/repositories/rhel-version.json

6. Restart the osbuild-composer.service:

   $ sudo systemctl restart osbuild-composer.service

Procedure

1. Obtain the baseurl from the /etc/yum.repos.d/redhat.repo file:

   # cat /etc/yum.repos.d/redhat.repo
   [AppStream]
   name = AppStream mirror example
   baseurl = https://mirror.example.com/RHEL-8/8.0/AppStream/x86_64/os/
   enabled = 1
   gpgcheck = 0
   sslverify = 1
   sslcacert = /etc/pki/ca1/ca.crt
   sslclientkey = /etc/pki/ca1/client.key
   sslclientcert = /etc/pki/ca1/client.crt
   metadata_expire = 86400
   enabled_metadata = 0

2. Configure the repository override to use the same baseurl and set rhsm to true:

   {
       "x86_64": [
           {
               "name": "AppStream mirror example",
               "baseurl": "https://mirror.example.com/RHEL-8/8.0/AppStream/x86_64/os/",
               "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (…​)",
               "check_gpg": true,
               "rhsm": true
           }
       ]
   }

   Note

   osbuild-composer does not automatically use repositories defined in /etc/yum.repos.d/. You need to manually specify them either as a system repository override or as an additional source using composer-cli. System repository overrides are usually used for “BaseOS” and “AppStream” repositories, whereas composer-cli sources are used for all the other repositories.

Procedure

1. On your RHEL system, access https://localhost:9090/ in a web browser.
2. For more information about how to remotely access image builder, see Managing systems using the RHEL 8 web console document.
3. Log in to the web console using an administrative user account.
4. On the web console, in the left hand menu, click Apps.

5. Click Image Builder.

   The image builder dashboard opens in the right pane. You can now proceed to create a blueprint for the RHEL for Edge images.

Procedure

1. On the image builder dashboard, click Create Blueprint.

   The Create Blueprint dialogue box opens.

2. On the Details page:

   1. Enter the name of the blueprint and, optionally, its description. Click Next.

3. Optional: In the Packages page:

   1. On the Available packages search, enter the package name and click the > button to move it to the Chosen packages field. Search and include as many packages as you want. Click Next.

      Note

      These customizations are all optional unless otherwise specified.

4. On the Kernel page, enter a kernel name and the command-line arguments.
5. On the File system page, select Use automatic partitioning. The filesystem customization is not supported for OSTree systems, because OSTree images have their own mount rule, such as read-only. Click Next.

6. On the Services page, you can enable or disable services:

   1. Enter the service names you want to enable or disable, separating them by a comma, by space, or by pressing the Enter key. Click Next.

7. On the Firewall page, set up your firewall setting:

   1. Enter the Ports, and the firewall services you want to enable or disable.
   2. Click the Add zone button to manage your firewall rules for each zone independently. Click Next.

8. On the Users page, add a users by following the steps:

   1. Click Add user.
   2. Enter a Username, a password, and a SSH key. You can also mark the user as a privileged user, by clicking the Server administrator checkbox. Click Next.

9. On the Groups page, add groups by completing the following steps:

   1. Click the Add groups button:

      1. Enter a Group name and a Group ID. You can add more groups. Click Next.

10. On the SSH keys page, add a key:

    1. Click the Add key button.

       1. Enter the SSH key.
       2. Enter a User. Click Next.

11. On the Timezone page, set your timezone settings:

    1. On the Timezone field, enter the timezone you want to add to your system image. For example, add the following timezone format: "US/Eastern".

       If you do not set a timezone, the system uses Universal Time, Coordinated (UTC) as default.

    2. Enter the NTP servers. Click Next.

12. On the Locale page, complete the following steps:

    1. On the Keyboard search field, enter the package name you want to add to your system image. For example: ["en_US.UTF-8"].
    2. On the Languages search field, enter the package name you want to add to your system image. For example: "us". Click Next.

13. On the Others page, complete the following steps:

    1. On the Hostname field, enter the hostname you want to add to your system image. If you do not add a hostname, the operating system determines the hostname.
    2. Mandatory only for the Simplifier Installer image: On the Installation Devices field, enter a valid node for your system image. For example: dev/sda. Click Next.

14. Mandatory only when building FIDO images: On the FIDO device onboarding page, complete the following steps:

    1. On the Manufacturing server URL field, enter the following information:

       1. On the DIUN public key insecure field, enter the insecure public key.
       2. On the DIUN public key hash field, enter the public key hash.
       3. On the DIUN public key root certs field, enter the public key root certs. Click Next.

15. On the OpenSCAP page, complete the following steps:

    1. On the Datastream field, enter the datastream remediation instructions you want to add to your system image.
    2. On the Profile ID field, enter the profile_id security profile you want to add to your system image. Click Next.

16. Mandatory only when building Ignition images: On the Ignition page, complete the following steps:

    1. On the Firstboot URL field, enter the package name you want to add to your system image.
    2. On the Embedded Data field, drag or upload your file. Click Next.
17. . On the Review page, review the details about the blueprint. Click Create.

Procedure

1. On the image builder dashboard click Create Image.

2. On the Image output page, perform the following steps:

   1. From the Select a blueprint dropdown menu, select the blueprint you want to use.
   2. From the Image output type dropdown list, select “RHEL for Edge Commit (.tar)” for network-based deployment.
   3. Click Next.

   4. On the OSTree settings page, enter:

      1. Repository URL: specify the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/.
      2. Parent commit: specify a previous commit, or leave it empty if you do not have a commit at this time.
      3. In the Ref textbox, specify a reference path for where your commit is going to be created. By default, the web console specifies rhel/8/$ARCH/edge. The "$ARCH" value is determined by the host machine. Click Next.

   5. On the Review page, check the customizations and click Create.

      Image builder starts to create a RHEL for Edge Commit image for the blueprint that you created.

      Note

      The image creation process takes up to 20 minutes to complete.

Verification

1. To check the RHEL for Edge Commit image creation progress:

   1. Click the Images tab.

Procedure

1. On the image builder dashboard click Create Image.
2. On the Image output page, perform the following steps:

3. From the Select a blueprint dropdown menu, select the blueprint you want to use.

   1. From the Image output type dropdown list, select “RHEL for Edge Container (.tar)” for network-based deployment.
   2. Click Next.

   3. On the OSTree page, enter:

      1. Repository URL: specify the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/. By default, the repository folder for a RHEL for Edge Container image is "/repo".

         To find the correct URL to use, access the running container and check the nginx.conf file. To find which URL to use, access the running container and check the nginx.conf file. Inside the nginx.conf file, find the root directory entry to search for the /repo/ folder information. Note that, if you do not specify a repository URL when creating a RHEL for Edge Container image (.tar) using image builder, the default /repo/ entry is created in the nginx.conf file.

      2. Parent commit: specify a previous commit, or leave it empty if you do not have a commit at this time.
      3. In the Ref textbox, specify a reference path for where your commit is going to be created. By default, the web console specifies rhel/8/$ARCH/edge. The "$ARCH" value is determined by the host machine. Click Next.
   4. On the Review page, check the customizations. Click Save blueprint.

4. Click Create.

   Image builder starts to create a RHEL for Edge Container image for the blueprint that you created.

   Note

   The image creation process takes up to 20 minutes to complete.

Verification

1. To check the RHEL for Edge Container image creation progress:

   1. Click the Images tab.

Procedure

1. On the image builder dashboard click Create Image.

2. On the Image output page, perform the following steps:

   1. From the Select a blueprint dropdown menu, select the blueprint you want to use.
   2. From the Image output type dropdown list, select RHEL for Edge Installer (.iso) image.
   3. Click Next.

   4. On the OSTree settings page, enter:

      1. Repository URL: specify the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/.
      2. In the Ref textbox, specify a reference path for where your commit is going to be created. By default, the web console specifies rhel/8/$ARCH/edge. The "$ARCH" value is determined by the host machine. Click Next.
   5. On the Review page, check the customizations. Click Save blueprint.

3. Click Create.

   Image builder starts to create a RHEL for Edge Installer image for the blueprint that you created.

   Note

   The image creation process takes up to 20 minutes to complete.

1. To check the RHEL for Edge Installer image creation progress:

   1. Click the Images tab.

1. From the More Options menu, click Download.

   The image builder tool downloads the file at your default download location.

1. Install and register a RHEL system
2. Install image builder
3. Using image builder, create a blueprint with customizations for RHEL for Edge Container image
4. Import the RHEL for Edge blueprint in image builder
5. Create a RHEL for Edge image embed in an OCI container with a web server ready to deploy the commit as an OSTree repository
6. Create a blueprint for the edge-simplified-installer image
7. Build a simplified RHEL for Edge image
8. Download the RHEL for Edge simplified image
9. Install the raw image with the edge-simplified-installer virt-install

Procedure

1. Create a plain text file in the Tom’s Obvious, Minimal Language (TOML) format, with the following content:

   name = "simplified-installer-blueprint"
   description = "blueprint for the simplified installer image"
   version = "0.0.1"
   packages = []
   modules = []
   groups = []
   distro = ""
   
   [customizations]
   installation_device = "/dev/vda"
   
   [[customizations.user]]
   name = "admin"
   password = "admin"
   groups = ["users", "wheel"]
   
   [customizations.fdo]
   manufacturing_server_url = "http://10.0.0.2:8080"
   diun_pub_key_insecure = "true"

   Note

   The FDO customization in the blueprints is optional, and you can build your RHEL for Edge Simplified Installer image with no errors.

   • name is the name and description is the description for your blueprint.
   • 0.0.1 is the version number according to the Semantic Versioning scheme.
   • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a". Notice that currently there are no differences between packages and modules.
   • Groups are packages groups to be installed into the image, for example the anaconda-tools group package. If you do not know the modules and groups, leave them empty.
   • installation-device is the customization to enable an unattended installation to your device.
   • manufacturing_server_url is the URL to perform the initial device credential exchange.
   • name is the user name to login to the image.
   • password is a password of your choice.
   • groups are any user groups, such as "widget".

2. Push (import) the blueprint to the image builder server:

   # composer-cli blueprints push blueprint-name.toml

3. List the existing blueprints to check whether the created blueprint is successfully pushed and exists.

   # composer-cli blueprints show blueprint-name

4. Check whether the components and versions listed in the blueprint and their dependencies are valid:

   # composer-cli blueprints depsolve blueprint-name

Procedure

1. Create the bootable ISO image.

   # composer-cli compose start-ostree \
   blueprint-name \
   edge-simplified-installer \
   --ref rhel/8/x86_64/edge \
   --url URL-OSTree-repository \

   Where,

   • blueprint-name is the RHEL for Edge blueprint name.
   • edge-simplified-installer is the image type .
   • --ref is the reference for where your commit is going to be created.

   • --url is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/. You can either start a RHEL for Edge Container or set up a web server. See Creating a RHEL for Edge Container image for non-network-based deployments and Setting up a web server to install RHEL for Edge image.

     A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

2. Check the image compose status.

   # composer-cli compose status

   The output displays the status in the following format:

   <UUID> RUNNING date blueprint-name blueprint-version image-type

   Note

   The image creation processes can take up to ten minutes to complete.

   To interrupt the image creation process, run:

   # composer-cli compose cancel <UUID>

   To delete an existing image, run:

   # composer-cli compose delete <UUID>

Procedure

1. Review the RHEL for Edge image status.

   # composer-cli compose status

   The output must display the following:

   $ <UUID> FINISHED date blueprint-name blueprint-version image-type

2. Download the image.

   # composer-cli compose image <UUID>

   Image builder downloads the image as an .iso file at the current directory path where you run the command.

   The UUID number and the image size is displayed alongside.

   $ <UUID>-simplified-installer.iso: size MB

Procedure

1. Click Create Blueprint in the upper-right corner of the image builder app.

   A dialog wizard with fields for the blueprint name and description opens.

2. On the Details page:

   1. Enter the name of the blueprint and, optionally, its description. Click Next.

3. Optional: On the Packages page, complete the following steps:

   1. In the Available packages search, enter the package name and click the > button to move it to the Chosen packages field. Search and include as many packages as you want. Click Next.

      Note

      The customizations are all optional unless otherwise specified.

4. Optional: On the Kernel page, enter a kernel name and the command-line arguments.
5. Optional: On the File system page, select Use automatic partitioning.The filesystem customization is not supported for OSTree systems, because OSTree images have their own mount rule, such as read-only. Click Next.

6. Optional: On the Services page, you can enable or disable services:

   1. Enter the service names you want to enable or disable, separating them by a comma, by space, or by pressing the Enter key. Click Next.

7. Optional: On the Firewall page, set up your firewall setting:

   1. Enter the Ports, and the firewall services you want to enable or disable.
   2. Click the Add zone button to manage your firewall rules for each zone independently. Click Next.

8. On the Users page, add a users by following the steps:

   1. Click Add user.

   2. Enter a Username, a password, and a SSH key. You can also mark the user as a privileged user, by clicking the Server administrator checkbox.

      Note

      When you specify the user in the blueprint customization and then create an image from that blueprint, the blueprint creates the user under the /usr/lib/passwd directory and the password under the /usr/etc/shadow during installation time. You can log in to the device with the username and password you created for the blueprint. After you access the system, you must create users, for example, using the useradd command.

      Click Next.

9. Optional: On the Groups page, add groups by completing the following steps:

   1. Click the Add groups button:

      1. Enter a Group name and a Group ID. You can add more groups. Click Next.

10. Optional: On the SSH keys page, add a key:

    1. Click the Add key button.

       1. Enter the SSH key.
       2. Enter a User. Click Next.

11. Optional: On the Timezone page, set your timezone settings:

    1. On the Timezone field, enter the timezone you want to add to your system image. For example, add the following timezone format: "US/Eastern".

       If you do not set a timezone, the system uses Universal Time, Coordinated (UTC) as default.

    2. Enter the NTP servers. Click Next.

12. Optional: On the Locale page, complete the following steps:

    1. On the Keyboard search field, enter the package name you want to add to your system image. For example: ["en_US.UTF-8"].
    2. On the Languages search field, enter the package name you want to add to your system image. For example: "us". Click Next.

13. Mandatory: On the Others page, complete the following steps:

    1. In the Hostname field, enter the hostname you want to add to your system image. If you do not add a hostname, the operating system determines the hostname.
    2. Mandatory: In the Installation Devices field, enter a valid node for your system image to enable an unattended installation to your device. For example: dev/sda1. Click Next.

14. Optional: On the FIDO device onboarding page, complete the following steps:

    1. On the Manufacturing server URL field, enter the manufacturing server URL to perform the initial device credential exchange, for example: "http://10.0.0.2:8080". The FDO customization in the blueprints is optional, and you can build your RHEL for Edge Simplified Installer image with no errors.
    2. On the DIUN public key insecure field, enter the certification public key hash to perform the initial device credential exchange. This field accepts "true" as value, which means this is an insecure connection to the manufacturing server. For example: manufacturing_server_url="http://${FDO_SERVER}:8080" diun_pub_key_insecure="true". You must use only one of these three options: "key insecure", "key hash" and "key root certs".

    3. On the DIUN public key hash field, enter the hashed version of your public key. For example: 17BD05952222C421D6F1BB1256E0C925310CED4CE1C4FFD6E5CB968F4B73BF73. You can get the key hash by generating it based on the certificate of the manufacturing server. To generate the key hash, run the command:

       # openssl x509 -fingerprint -sha256 -noout -in /etc/fdo/aio/keys/diun_cert.pem | cut -d"=" -f2 | sed 's/://g'

       The /etc/fdo/aio/keys/diun_cert.pem is the certificate that is stored in the manufacturing server.

    4. On the DIUN public key root certs field, enter the public key root certs. This field accepts the content of the certification file that is stored in the manufacturing server. To get the content of certificate file, run the command:

       $ cat /etc/fdo/aio/keys/diun_cert.pem.

15. Click Next.
16. On the Review page, review the details about the blueprint. Click Create.

Procedure

1. Access mage builder dashboard.
2. On the blueprint table, find the blueprint you want to build an image for.
3. Navigate to the Images tab and click Create Image. The Create image wizard opens.

4. On the Image output page, complete the following steps:

   1. From the Select a blueprint list, select the blueprint you created for the RHEL for Edge Simplified image.
   2. From the Image output type list, select RHEL for Edge Simplified Installer (.iso).
   3. In the Image Size field, enter the image size. Minimum image size required for Simplified Installer image is:
5. Click Next.

6. In the OSTree settings page, complete the following steps:

   1. In the Repository URL field, enter the repository URL to where the parent OSTree commit will be pulled from.
   2. In the Ref field, enter the ref branch name path. If you do not enter a ref, the default ref for the distro is used.
7. On the Review page, review the image customization and click Create.

Procedure

1. Access the image builder dashboard. The blueprint list dashboard opens.
2. In the blueprint table, find the blueprint you built your RHEL for Edge Simplified Installer image for.
3. Navigate to the Images tab.

4. Choose one of the options:

   • Download the image.
   • Download the logs of the image to inspect the elements and verify if any issue is found.

Procedure

1. Mount the ISO image to the directory of your choice:

   # mkdir /mnt/rhel8-install/
   # mount -o loop,ro -t iso9660 /path_directory/installer.iso /mnt/rhel8-install/

   Replace /path_directory/installer.iso with the path to the RHEL for Edge bootable ISO image.

2. Copy the files from the mounted image to the HTTP server root. This command creates the /var/www/html/rhel8-install/ directory with the contents of the image.

   # mkdir /var/www/html/httpboot/
   # cp -R /mnt/rhel8-install/* /var/www/html/httpboot/
   # chmod -R +r /var/www/html/httpboot/*

   Note

   Some copying methods can skip the .treeinfo file which is required for a valid installation source. Running the cp command for whole directories as shown in this procedure will copy .treeinfo correctly.

3. Update the /var/www/html/EFI/BOOT/grub.cfg file, by replacing:

   1. coreos.inst.install_dev=/dev/sda with coreos.inst.install_dev=/dev/vda
   2. linux /images/pxeboot/vmlinuz with linuxefi /images/pxeboot/vmlinuz
   3. initrd /images/pxeboot/initrd.img with initrdefi /images/pxeboot/initrd.img

   4. coreos.inst.image_file=/run/media/iso/disk.img.xz with coreos.inst.image_url=http://{IP-ADDRESS}/disk.img.xz

      The IP-ADDRESS is the ip address of this machine, which will serve as a http boot server.

4. Start the httpd service:

   # systemctl start httpd.service

   As a result, after you set up an UEFI HTTP Boot server, you can install your RHEL for Edge devices by using UEFI HTTP boot.

Procedure

1. Set up a network configuration to support UEFI HTTP boot. See Setting up UEFI HTTP boot with libvirt.

2. Use the virt-install command to create a RHEL for Edge Virtual Machine from the UEFI HTTP Boot.

   # virt-install \
       --name edge-install-image \
       --disk path=”  “, ,format=qcow2
       --ram 3072 \
       --memory 4096 \
       --vcpus 2 \
       --network network=integration,mac=mac_address \
       --os-type linux
       --os-variant rhel8 \
       --cdrom "/var/lib/libvirt/images/”ISO_FILENAME"
       --boot uefi,loader_ro=yes,loader_type=pflash,nvram_template=/usr/share/edk2/ovmf/OVMF_VARS.fd,loader_secure=no
       --virt-type kvm \
       --graphics none \
        --wait=-1
        --noreboot

Procedure

1. Copy the ISO image file to a USB flash drive.
2. Connect the USB flash drive to the port of the computer you want to boot.

3. Boot the ISO image from the USB flash drive.The boot menu shows you the following options:

   Install Red Hat Enterprise Linux 8
   Test this media & install Red Hat Enterprise Linux 8

4. Choose Install Red Hat Enterprise Linux 8. This starts the system installation.

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 image builder

3. Using 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 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. Create a directory for the keys and certificates:

   $ mkdir /etc/fdo/keys

2. 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

3. 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. Create a directory for each of the components: owner vouchers, manufacturer keys, and manufacturing sessions.

   # mkdir -p /etc/fdo/stores/manufacturer_keys
   # mkdir -p /etc/fdo/stores/manufacturing_sessions
   # mkdir -p /etc/fdo/stores/owner_vouchers

6. 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

7. 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

8. 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 directories to store the following directories: the registered directory, where the registered device owner vouchers will be hosted and the sessions directory:

   # mkdir -p /etc/fdo/stores/rendezvous_registered
   # mkdir -p /etc/fdo/stores/rendezvous_sessions

3. 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"

4. 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

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

   # ss -ltn

6. 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. Create the additional directories that the Owner server service needs:

   # mkdir -p /etc/fdo/stores/owner_vouchers
   # mkdir -p /etc/fdo/stores/owner_onboarding_sessions

3. 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

4. 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=

5. 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.

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

   # ss -ltn

7. 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.

1. Log in to the device by providing the username and password you created in the Service Info API.

Procedure

1. Extract the downloaded image .tar file:

   # tar xvf <UUID>-commit.tar

2. Go to the directory where you have extracted the .tar file.

   It has a compose.json file and an OSTree directory. The compose.json file has the commit number and the OSTree directory has the RPM packages.

3. Open the compose.json file and note the commit ID number. You need this number handy when you proceed to set up a web server.

   If you have the jq JSON processor installed, you can also retrieve the commit ID by using the jq tool:

   # jq '.["ostree-commit"]' < compose.json

4. List the RPM packages in the commit.

   # rpm-ostree db list rhel/8/x86_64/edge --repo=repo

5. Use a Kickstart file to run the RHEL installer. Optionally, you can use any existing file or can create one by using the Kickstart Generator tool.

   In the Kickstart file, ensure that you include the details about how to provision the file system, create a user, and how to fetch and deploy the RHEL for Edge image. The RHEL installer uses this information during the installation process.

   The following is a Kickstart file example:

   lang en_US.UTF-8
   keyboard us
   timezone Etc/UTC --isUtc
   text
   zerombr
   clearpart --all --initlabel
   autopart
   reboot
   user --name=core --group=wheel
   sshkey --username=core "ssh-rsa AAAA3Nza…​."
   rootpw --lock
   network --bootproto=dhcp
   
   ostreesetup --nogpg --osname=rhel --remote=edge --url=https://mirror.example.com/repo/ --ref=rhel/8/x86_64/edge

   The OStree-based installation uses the ostreesetup command to set up the configuration. It fetches the OSTree commit, by using the following flags:

   • --nogpg - Disable GNU Privacy Guard (GPG) key verification.
   • --osname - Management root for the operating system installation.
   • --remote - Management root for the operating system installation
   • --url - URL of the repository to install from.
   • --ref - Name of the branch from the repository that the installation uses.

   • --url=http://mirror.example.com/repo/ - is the address of the host system where you extracted the edge commit and served it over nginx. You can use the address to reach the host system from the guest computer.

     For example, if you extract the commit image in the /var/www/html directory and serve the commit over nginx on a computer whose hostname is www.example.com, the value of the --url parameter is http://www.example.com/repo.

     Note

     Use the http protocol to start a service to serve the commit, because https is not enabled on the Apache HTTP Server.

Procedure

1. Create the nginx configuration file with the following instructions:

   events {
   
   }
   
   http {
       server{
           listen 8080;
           root /usr/share/nginx/html;
                   }
            }
   
   pid /run/nginx.pid;
   daemon off;

2. Create a Dockerfile with the following instructions:

   FROM registry.access.redhat.com/ubi8/ubi
   RUN yum -y install nginx && yum clean all
   COPY kickstart.ks /usr/share/nginx/html/
   COPY repo /usr/share/nginx/html/
   COPY nginx /etc/nginx.conf
   EXPOSE 8080
   CMD ["/usr/sbin/nginx", "-c", "/etc/nginx.conf"]
   ARG commit
   ADD ${commit} /usr/share/nginx/html/

   Where,

   • kickstart.ks is the name of the Kickstart file from the RHEL for Edge image. The Kickstart file includes directive information. To help you manage the images later, it is advisable to include the checks and settings for Greenboot checks. For that, you can update the Kickstart file to include the following settings:

     lang en_US.UTF-8
     keyboard us
     timezone Etc/UTC --isUtc
     text
     zerombr
     clearpart --all --initlabel
     autopart
     reboot
     user --name=core --group=wheel
     sshkey --username=core "ssh-rsa AAAA3Nza…​."
     
     ostreesetup --nogpg --osname=rhel --remote=edge
     --url=https://mirror.example.com/repo/
     --ref=rhel/8/x86_64/edge
     
     %post
     cat << EOF > /etc/greenboot/check/required.d/check-dns.sh
     #!/bin/bash
     
     DNS_SERVER=$(grep nameserver /etc/resolv.conf | cut -f2 -d" ")
     COUNT=0
     
     # check DNS server is available
     ping -c1 $DNS_SERVER
     while [ $? != '0' ] && [ $COUNT -lt 10 ]; do
     
     							
     							
     							
     							COUNT++
     echo "Checking for DNS: Attempt $COUNT ."
     sleep 10
     ping -c 1 $DNS_SERVER
     done
     EOF
     %end

     Any HTTP service can host the OSTree repository, and the example, which uses a container, is just an option for how to do this. The Dockerfile performs the following tasks:

     1. Uses the latest Universal Base Image (UBI)
     2. Installs the web server (nginx)
     3. Adds the Kickstart file to the server
     4. Adds the RHEL for Edge image commit to the server

3. Build a Docker container

   # podman build -t name-of-container-image --build-arg commit=uuid-commit.tar .

4. Run the container

   # podman run --rm -d -p port:8080 localhost/name-of-container-image

   As a result, the server is set up and ready to start the RHEL Installer by using the commit.tar repository and the Kickstart file.

Procedure

1. Run the RHEL Anaconda Installer by using libvirt virt-install:

   virt-install \
   --name rhel-edge-test-1 \
   --memory 2048 \
   --vcpus 2 \
   --disk path=prepared_disk_image.qcow2,format=qcow2,size=8 \
   --os-variant rhel8 \
   --cdrom /home/username/Downloads/rhel-8-x86_64-boot.iso

2. On the installation screen:

   Figure 8.1. Red Hat Enterprise Linux boot menu

   

   1. Press the e key to add an additional kernel parameter:

      inst.ks=http://edge_device_ip:port/kickstart.ks

      The kernel parameter specifies that you want to install RHEL by using the Kickstart file and not the RHEL image contained in the RHEL Installer.

   2. After adding the kernel parameters, press Ctrl+X to boot the RHEL installation by using the Kickstart file.

      The RHEL Installer starts, fetches the Kickstart file from the server (HTTP) endpoint and executes the commands, including the command to install the RHEL for Edge image commit from the HTTP endpoint. After the installation completes, the RHEL Installer prompts you for login details.

Verification

1. On the Login screen, enter your user account credentials and click Enter.

2. Verify whether the RHEL for Edge image is successfully installed.

   $ rpm-ostree status

   The command output provides the image commit ID and shows that the installation is successful.

   Following is a sample output:

   State: idle
   Deployments:
   * ostree://edge:rhel/8/x86_64/edge
   		  Timestamp: 2020-09-18T20:06:54Z
   			Commit: 836e637095554e0b634a0a48ea05c75280519dd6576a392635e6fa7d4d5e96

Procedure

1. Navigate to the directory where you have downloaded the RHEL for Edge Container OSTree commit.

2. Load the RHEL for Edge Container OSTree commit into Podman.

   $ sudo podman load -i UUID-container.tar

   The command output provides the image ID, for example: @8e0d51f061ff1a51d157804362bc875b649b27f2ae1e66566a15e7e6530cec63

3. Tag the new RHEL for Edge Container image, using the image ID generated by the previous step.

   $ sudo podman tag image-ID localhost/edge-container

   The podman tag command assigns an additional name to the local image.

4. Run the container named edge-container.

   $ sudo podman run -d --name=edge-container -p 8080:8080 localhost/edge-container

   The podman run -d --name=edge-container command assigns a name to your container-based on the localhost/edge-container image.

5. List containers:

   $ sudo podman ps -a
   CONTAINER ID  IMAGE                               	COMMAND	CREATED    	STATUS                	PORTS   NAMES
   2988198c4c4b  …./localhost/edge-container   /bin/bash  3 seconds ago  Up 2 seconds ago      	edge-container

Procedure

1. Begin to create the RHEL for Edge Installer image.

   # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

   Where,

   • ref is the same value that customer used to build ostree repository
   • URL-OSTree-repository is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repo/. See Creating a RHEL for Edge Container image for non-network-based deployments.
   • blueprint-name is the RHEL for Edge Installer blueprint name.

   • image-type is edge-installer.

     A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

2. Check the image compose status.

   # composer-cli compose status

   The command output displays the status in the following format:

   <UUID> RUNNING date blueprint-name blueprint-version image-type

   Note

   The image creation process takes a few minutes to complete.

   To interrupt the image creation process, run:

   # composer-cli compose cancel <UUID>

   To delete an existing image, run:

   # composer-cli compose delete <UUID>

   Image builder pulls the commit that is being served by the running container during the image build.

   After the image build is complete, you can download the resulting ISO image.

3. Download the image. See Downloading a RHEL for Edge image.

   After the image is ready, you can use it for non-network deployments. See Installing the RHEL for Edge image for non-network-based deployments.

Procedure

1. Create a qcow VM disk file to install the (.iso) image. That is an image of a hard disk drive for the virtual machine (VM). For example:

   $ qemu-img create -f qcow2 diskfile.qcow2 20G

2. Use the virt-install command to boot the VM using the disk as a drive and the installer ISO image as a CD-ROM. For example:

   $ virt-install \
   --boot uefi \
   --name VM_NAME
   --memory 2048 \
   --vcpus 2 \
   --disk path=diskfile.qcow2
   --cdrom /var/lib/libvirt/images/UUID-installer.iso \
   --os-variant rhel9.0

   This command instructs virt-install to:

   • Instructs the VM to use UEFI to boot, instead of the BIOS.
   • Mount the installation ISO.

   • Use the hard disk drive image created in the first step.

     It gives you an Anaconda Installer. The RHEL Installer starts, loads the Kickstart file from the ISO and executes the commands, including the command to install the RHEL for Edge image commit. Once the installation is complete, the RHEL installer prompts for login details.

     Note

     Anaconda is preconfigured to use the Container commit during the installation. However, you need to set up system configurations, such as disk partition, timezone, between others.

3. Connect to Anaconda GUI with virt-viewer to setup the system configuration:

   $ virt-viewer --connect qemu:///system --wait VM_NAME

4. Reboot the system to finish the installation.
5. On the login screen, specify your user account credentials and click Enter.

Verification steps

1. Verify whether the RHEL for Edge image is successfully installed.

   $  rpm-ostree status