Using image mode for RHEL to build, deploy, and manage operating systems

Procedure

1. Create a Containerfile:

   $ cat Containerfile
   FROM registry.redhat.io/rhel9/rhel-bootc:latest
   RUN dnf -y install cloud-init && \
       ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
       dnf clean all

   Copy to Clipboard Toggle word wrap

   This Containerfile example adds the cloud-init tool, so it automatically fetches SSH keys and can run scripts from the infrastructure and also gather configuration and secrets from the instance metadata. For example, you can use this container image for pre-generated AWS or KVM guest systems.

2. Build the <image> image by using Containerfile in the current directory:

   $ podman build -t quay.io/<namespace>/<image>:<tag> .

   Copy to Clipboard Toggle word wrap

Procedure

1. Select the image that you want to logically bound.

2. Create a Containerfile:

   $ cat Containerfile
   FROM quay.io/<namespace>/<image>:latest
   COPY ./<app_1>.image /usr/share/containers/systemd/<app_1>.image
   COPY ./<app_2>.container /usr/share/containers/systemd/<app_2>.container
   
   RUN ln -s /usr/share/containers/systemd/<app_1>.image \
   	/usr/lib/bootc/bound-images.d/<app_1>.image && \
       ln -s /usr/share/containers/systemd/<app_2>.container \
       	/usr/lib/bootc/bound-images.d/<app_2>.container

   Copy to Clipboard Toggle word wrap

3. In the .container definition, use:

   GlobalArgs=--storage-opt=additionalimagestore=/usr/lib/bootc/storage

   Copy to Clipboard Toggle word wrap

   In the Containerfile example, the image is selected to be logically bound by creating a symlink in the /usr/lib/bootc/bound-images.d directory pointing to either an .image or a .container file.

4. Run the bootc upgrade command.

   $ bootc upgrade

   Copy to Clipboard Toggle word wrap

   The bootc upgrade performs the following overall steps:

   1. Fetches the new base image from the image repository. See linkhttps://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/using_image_mode_for_rhel_to_build_deploy_and_manage_operating_systems/managing-users-groups-ssh-key-and-secrets-in-image-mode-for-rhel#configuring-container-pull-secrets_managing-users-groups-ssh-key-and-secrets-in-image-mode-for-rhel[Configuring container pull secrets].
   2. Reads the new base image root file system to discover logically bound images.
   3. Automatically pulls any discovered logically bound images defined in the new bootc image into the bootc-owned /usr/lib/bootc/storage image storage.

5. Make the bound images become available to container runtimes such as Podman. For that, you must explicitly configure bound images to point to the bootc storage as an "additional image store". For example:

   podman --storage-opt=additionalimagestore=/usr/lib/bootc/storage run <image>

   Copy to Clipboard Toggle word wrap
   Important

   Do not attempt to globally enable the /usr/lib/bootc/storage image storage in /etc/containers/storage.conf. Only use the bootc storage for logically bound images.

Procedure

1. Login to authenticate to registry.redhat.io:

   $ sudo podman login registry.redhat.io

   Copy to Clipboard Toggle word wrap

2. Install the bootc-image-builder tool:

   $ sudo podman pull registry.redhat.io/rhel9/bootc-image-builder

   Copy to Clipboard Toggle word wrap

Procedure

1. Optional: Create a config.toml to configure user access, for example:

   [[customizations.user]]
   name = "user"
   password = "pass"
   key = "ssh-rsa AAA ... user@email.com"
   groups = ["wheel"]

   Copy to Clipboard Toggle word wrap

2. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument.

   Note

   If you do not have the container storage mount and --local image options, your image must be public.

   1. The following is an example of creating a public QCOW2 image:

   2. The following example creates a public QCOW2 image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

      $ sudo podman run \
          --rm \
          -it \
          --privileged \
          --pull=newer \
          --security-opt label=type:unconfined_t \
          -v ./config.toml:/config.toml \
          -v ./config.toml:/config.toml:ro \
          -v ./output:/output \
          -v /var/lib/containers/storage:/var/lib/containers/storage \
          registry.redhat.io/rhel10/bootc-image-builder:latest \
          --type qcow2 \
          --config /config.toml \
        quay.io/<namespace>/<image>:<tag>
        quay.io/<namespace>/<image>:<tag>

      Copy to Clipboard Toggle word wrap
   3. The following is an example of creating a private QCOW2 image:

   4. This example creates a private QCOW2 image from a local container.

      $ sudo podman run \
          --rm \
          -it \
          --privileged \
          --pull=newer \
          --security-opt label=type:unconfined_t \
          -v $(pwd)/config.toml:/config.toml:ro \
          -v $(pwd)/output:/output \
          -v ./config.toml:/config.toml:ro \
          -v ./output:/output \
          -v /var/lib/containers/storage:/var/lib/containers/storage \
          registry.redhat.io/rhel10/bootc-image-builder:latest \
          --local \
          --type qcow2 \
          quay.io/<namespace>/<image>:<tag>
          --config /config.toml \
          quay.io/<namespace>/<image>:<tag>

      Copy to Clipboard Toggle word wrap

      You can find the .qcow2 image in the output folder.

Procedure

1. Create a Containerfile with the following content:

   FROM registry.redhat.io/rhel10/rhel-bootc:latest
   RUN dnf -y install cloud-init open-vm-tools && \
   ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
   rm -rf /var/{cache,log} /var/lib/{dnf,rhsm} && \
   systemctl enable vmtoolsd.service

   Copy to Clipboard Toggle word wrap

2. Build the bootc image:

   # podman build . -t localhost/rhel-bootc-vmdk

   Copy to Clipboard Toggle word wrap
3. Create a VMDK file from the previously created bootc image:

4. Create a VMDK file from the previously created bootc image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

   # podman run \
   --rm \
   -it \
   --privileged \
   -v /var/lib/containers/storage:/var/lib/containers/storage \
   -v ./output:/output \
   --security-opt label=type:unconfined_t \
   --pull newer \
   registry.redhat.io/rhel10/bootc-image-builder:latest \
   --local \
   --type vmdk \
   --config /config.toml \
   localhost/rhel-bootc-vmdk:latest

   Copy to Clipboard Toggle word wrap

   The --local option uses the local container storage to source the originating image to produce the VMDK instead of a remote repository.

Procedure

1. Optional: Create a config.toml to configure user access, for example:

   [[customizations.user]]
   name = "user"
   password = "pass"
   key = "ssh-rsa AAA ... user@email.com"
   groups = ["wheel"]

   Copy to Clipboard Toggle word wrap

2. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument.

   Note

   If you do not have the container storage mount and --local image options, your image must be public.

3. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

   1. The following is an example of creating a gce image:

      $ sudo podman run \
          --rm \
          -it \
          --privileged \
          --pull=newer \
          --security-opt label=type:unconfined_t \
          -v ./config.toml:/config.toml \
          -v ./output:/output \
          -v /var/lib/containers/storage:/var/lib/containers/storage \
          registry.redhat.io/rhel10/bootc-image-builder:latest \
          --type gce \
          --config /config.toml \
        quay.io/<namespace>/<image>:<tag>

      Copy to Clipboard Toggle word wrap

      You can find the gce image in the output folder.

Procedure

1. Create a disk image from the bootc image.

   • Configure the user details in the Containerfile. Make sure that you assign it with sudo access.
   • Build a customized operating system image with the configured user from the Containerfile. It creates a default user with passwordless sudo access.

2. Optional: Configure the machine image with cloud-init. See Users and groups configuration - Injecting users and SSH keys by using cloud-init. The following is an example:

   FROM registry.redhat.io/rhel10/rhel-bootc:latest
   
   RUN dnf -y install cloud-init && \
       ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
       rm -rf /var/{cache,log} /var/lib/{dnf,rhsm}

   Copy to Clipboard Toggle word wrap
   Note

   You can also use cloud-init to add users and additional configuration by using instance metadata.

3. Build the bootc image. For example, to deploy the image to an x86_64 AWS machine, use the following commands:

   $ podman build -t quay.io/<namespace>/<image>:<tag> .
   $ podman push quay.io/<namespace>/<image>:<tag> .

   Copy to Clipboard Toggle word wrap
4. Use the bootc-image-builder tool to create an AMI from the bootc container image.

5. Use the bootc-image-builder tool to create a public AMI image from the bootc container image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

   $ sudo podman run \
     --rm \
     -it \
     --privileged \
     --pull=newer \
     -v $HOME/.aws:/root/.aws:ro \
     -v /var/lib/containers/storage:/var/lib/containers/storage \
     --env AWS_PROFILE=default \
     registry.redhat.io/rhel10/bootc-image-builder:latest \
     --type ami \
     --config /config.toml \
     --aws-ami-name rhel-bootc-x86 \
     --aws-bucket rhel-bootc-bucket \
     --aws-region us-east-1 \
   quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap
   Note

   The following flags must be specified all together. If you do not specify any flag, the AMI is exported to your output directory.

   • --aws-ami-name - The name of the AMI image in AWS
   • --aws-bucket - The target S3 bucket name for intermediate storage when you are creating the AMI

   • --aws-region - The target region for AWS uploads

     The bootc-image-builder tool builds an AMI image and uploads it to your AWS s3 bucket by using your AWS credentials to push and register an AMI image after building it. The bootc-image-builder tool builds an AMI image and uploads it to your AWS S3 bucket by using your AWS credentials to push and register an AMI image after building it.

Procedure

1. Optional: Create a config.toml to configure user access, for example:

   [[customizations.user]]
   name = "user"
   password = "pass"
   key = "ssh-rsa AAA ... user@email.com"
   groups = ["wheel"]

   Copy to Clipboard Toggle word wrap
2. Run bootc-image-builder. If you want to use user access configuration, pass the config.toml as an argument:

3. Run bootc-image-builder. If you want to use user access configuration, pass the config.toml as an argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v /var/lib/containers/storage:/var/lib/containers/storage \
       -v ./config.toml:/config.toml \
       -v ./output:/output \
       registry.redhat.io/rhel10/bootc-image-builder:latest \
       --local \
       --type raw \
       --config /config.toml \
     quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

   You can find the .raw image in the output folder.

Procedure

1. Optional: Create a config.toml to which overrides the default embedded Kickstart which performs an automatic installation.

   [customizations.installer.kickstart]
   contents = """
   text --non-interactive
   zerombr
   clearpart --all --initlabel --disklabel=gpt
   autopart --noswap --type=lvm
   network --bootproto=dhcp --device=link --activate --onboot=on
   """

   Copy to Clipboard Toggle word wrap
2. Run bootc-image-builder. If you do not want to add any configuration, omit the -v $(pwd)/config.toml:/config.toml argument.

3. Run bootc-image-builder to create a public ISO image. If you do not want to add any configuration, omit the -v $(pwd)/config.toml:/config.toml argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v /var/lib/containers/storage:/var/lib/containers/storage \
       -v $(pwd)/config.toml:/config.toml \
       -v $(pwd)/output:/output \
       registry.redhat.io/rhel10/bootc-image-builder:latest \
       --type iso \
       --config /config.toml \
     quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

   You can find the .iso image in the output folder.

Procedure

1. Create your Kickstart file. The following Kickstart file is an example of a fully unattended Kickstart file configuration that contains user creation, and partition instructions.

   [customizations.installer.kickstart]
   contents = """
   lang en_GB.UTF-8
   keyboard uk
   timezone CET
   
   user --name <user> --password <password> --plaintext --groups <groups>
   sshkey --username <user> ssh-<type> <public key>
   rootpw --lock
   
   zerombr
   clearpart --all --initlabel
   autopart --type=plain
   reboot --eject
   """

   Copy to Clipboard Toggle word wrap
2. Save the Kickstart configuration in the toml format to inject the Kickstart content. For example, config.toml.

3. Run bootc-image-builder, and include the Kickstart file configuration that you want to add to the ISO build. The bootc-image-builder automatically adds the ostreecontainer command that installs the container image.

   Note

   If you do not have the container storage mount and --local image options, your image must be public.

   1. The following is an example of creating a public ISO image:

      $ sudo podman run \
          --rm \
          -it \
          --privileged \
          --pull=newer \
          --security-opt label=type:unconfined_t \
          -v /var/lib/containers/storage:/var/lib/containers/storage \
          -v $(pwd)/config.toml:/config.toml \
          -v $(pwd)/output:/output \
          registry.redhat.io/rhel9/bootc-image-builder:latest \
          --type iso \
          --config /config.toml \
        quay.io/<namespace>/<image>:<tag>

      Copy to Clipboard Toggle word wrap

   2. The following is an example of creating a private ISO image:

      $ sudo podman run \
          --rm \
          -it \
          --privileged \
          --pull=newer \
          --security-opt label=type:unconfined_t \
          -v $(pwd)/config.toml:/config.toml:ro \
          -v $(pwd)/output:/output \
          -v /var/lib/containers/storage:/var/lib/containers/storage \
          registry.redhat.io/rhel9/bootc-image-builder:latest \
          --local
          --type iso \
        quay.io/<namespace>/<image>:<tag>

      Copy to Clipboard Toggle word wrap

      You can find the .iso image in the output folder.

1. Set the [Image size] parameter to the size that you want.
2. Add any extra mountpoints with their required minimum sizes. Ensure that the sum of the sizes is smaller than the image size by at least 3.01 GiB if there is no /usr mountpoint, or at least 1.01 GiB if there is. The extra 0.01 MiB is more than enough for the headers and metadata for which extra space might be reserved.
3. Do not specify a size for the / mountpoint.

Procedure

1. Create a config.tom file with the following content:

   1. Add a user to the image.

      [[customizations.user]]
      name = "user1"
      password = "user2"
      key = "ssh-rsa AAA ... user@email.com"
      groups = ["wheel"]
      
      # Set a size for the root partition:
      
      [[customizations.partitioning.plain.filesystems]]
      mountpoint = "/"
      type = "ext4"
      minsize = "3 GiB"
      
      # Add an extra data partition
      [[customizations.partitioning.plain.filesystems]]
      mountpoint = "/var/data"
      type = "xfs"
      minsize = "2 GiB"
      label = "data"
      
      
      # Add an app partition with a top-level mountpoint.
      # Requires derived container.
      [[customizations.partitioning.plain.filesystems]]
      mountpoint = "/app"
      type = "xfs"
      minsize = "1 GiB"
      label = "app"
      
      # Add the LVM configuration:
      # Define the LVM Volume Group name and size
      [[customizations.partitioning.lvm.volume_groups]]
      name = "centosvg"
      minsize = 10737418240  # 10 GiB
      
      
      # Add a data Logical Volume to the group
      [[customizations.partitioning.lvm.volume_groups.logical_volumes]]
      name = "datalv"
      mountpoint = "/var/data"
      label = "data"
      minsize = "1 GiB"
      type = "xfs"
      
      
      # The root Logical Volume is created automatically if not defined, but setting
      # it lets us set the name, label, and size explicitly
      [[customizations.partitioning.lvm.volume_groups.logical_volumes]]
      name = "rootlv"
      mountpoint = "/"
      label = "system"
      minsize = "2 GiB"
      type = "ext4"
      
      
      # Add an app Logical Volume with a top-level mountpoint.
      # Requires derived container.
      [[customizations.partitioning.lvm.volume_groups.logical_volumes]]
      mountpoint = "/app"
      type = "xfs"
      minsize = "1 GiB"
      label = "app"
      name = "applv"

      Copy to Clipboard Toggle word wrap

2. Run the bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument. The following is an example of creating a public QCOW2 image:

   sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v ./config.toml:/config.toml:ro \
       -v ./output:/output \
        registry.redhat.io/rhel9/bootc-image-builder:latest \
       --type qcow2 \
       --config /config.toml \
     quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

Verification

1. Run the resulting QCOW2 file on a virtual machine.

   qemu-system-x86_64 \
        -enable-kvm \
        -cpu host \
        -m 8G \
        -bios /usr/share/edk2/ovmf/OVMF_CODE.fd \
        -snapshot \
        -drive file="${path}/output/qcow2/disk.qcow2"

   Copy to Clipboard Toggle word wrap

2. Access the system in the virtual machine launched with SSH.

   # ssh -i /<path_to_private_ssh-key> <user1>@<ip-address>

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a config.toml to configure custom mount options, for example:

   name = "lvm"
   description = "A base system with custom LVM partitioning"
   
   [customizations.disk]
   
   [[customizations.disk.partitions]]
   mountpoint = "/var/data"
   minsize = "1 GiB"
   label = "data"
   fs_type = "ext4"
   
   [[customizations.disk.partitions]]
   mountpoint = "/"
   minsize = "2 GiB"
   label = "root"
   fs_type = "ext4"

   Copy to Clipboard Toggle word wrap

2. Run bootc-image-builder, passing the config.toml as an argument.

   Note

   If you do not have the container storage mount and --local image options, your image must be public.

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v ./config.toml:/config.toml \
       -v ./output:/output \
       registry.redhat.io/rhel9/bootc-image-builder:latest \
       --type <image_type>\
       --config config.toml \
     quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

   You can find your image with the customized advanced partitioning in the output folder.

Procedure

1. Create a Containerfile:

   FROM <internal_repository>/<image>
   RUN  mkdir -p /etc/pki/ca-trust/extracted/pem/
   COPY tls-ca-bundle.pem /etc/pki/ca-trust/extracted/pem/
   RUN  rm -rf /etc/yum.repos.d/*
   COPY echo-rhel9_4.repo /etc/yum.repos.d/

   Copy to Clipboard Toggle word wrap

2. Build the custom image:

   # podman build -t <your_image> .

   Copy to Clipboard Toggle word wrap

3. Run the <your_image>:

   # podman run -it --rm <your_image>

   Copy to Clipboard Toggle word wrap

Procedure

1. In a browser, access Service→EC2 and log in.
2. On the AWS console dashboard menu, choose the correct region. The image must have the Available status, to indicate that it was correctly uploaded.
3. On the AWS dashboard, select your image and click Launch.
4. In the new window that opens, choose an instance type according to the resources you need to start your image. Click Review and Launch.
5. Review your instance details. You can edit each section if you need to make any changes. Click Launch.
6. Before you start the instance, select a public key to access it. You can either use the key pair you already have or you can create a new key pair.

7. Click Launch Instance to start your instance. You can check the status of the instance, which displays as Initializing.

   After the instance status is Running, the Connect button becomes available.

8. Click Connect. A window appears with instructions on how to connect by using SSH.

9. Run the following command to set the permissions of your private key file so that only you can read it. See Connect to your Linux instance.

   $ chmod 400 <your-instance-name.pem>

   Copy to Clipboard Toggle word wrap

10. Connect to your instance by using its Public DNS:

    $ ssh -i <your-instance-name.pem>ec2-user@<your-instance-IP-address>

    Copy to Clipboard Toggle word wrap

Procedure

1. Create an ostreecontainer Kickstart file to fetch the image from the network. For example:

   # Basic setup
   text
   network --bootproto=dhcp --device=link --activate
   # Basic partitioning
   clearpart --all --initlabel --disklabel=gpt
   reqpart --add-boot
   part / --grow --fstype xfs
   
   # Reference the container image to install - The kickstart
   # has no %packages section. A container image is being installed.
   ostreecontainer --url quay.io/<namespace>/<image>:<tag> . bootc-image-builder:latest
   
   firewall --disabled
   services --enabled=sshd
   
   # Only inject a SSH key for root
   rootpw --iscrypted locked
   sshkey --username root "<your-key>"
   reboot

   Copy to Clipboard Toggle word wrap

2. Boot a system by using the 9.4 Boot ISO installation media.

   1. Append the Kickstart file with the following to the kernel argument:

      inst.ks=http://<path_to_your_kickstart>

      Copy to Clipboard Toggle word wrap
3. Press CTRL+X to boot the system.

Procedure

1. Copy your ISO disk image to a USB flash drive.
2. Perform a bare-metal installation by using the content in the USB stick into a disconnected environment.

Procedure

1. Export the RHEL installation ISO image to the HTTP server. The PXE boot server is now ready to serve PXE clients.
2. Boot the client and start the installation.
3. Select PXE Boot when prompted to specify a boot source. If the boot options are not displayed, press the Enter key on your keyboard or wait until the boot window opens.
4. From the Red Hat Enterprise Linux boot window, select the boot option that you want, and press Enter.
5. Start the network installation.

Procedure

1. Create a ./config.toml. The following example shows how to add a user to the disk image.

   [[customizations.user]]
   name = "user"
   password = "pass"
   key = "ssh-rsa AAA ... user@email.com"
   groups = ["wheel"]

   Copy to Clipboard Toggle word wrap
   • name - Mandatory. Name of the user.
   • password - Not mandatory. Nonencrypted password.
   • key - Not mandatory. Public SSH key contents.
   • groups - Not mandatory. An array of groups to add the user into.

2. Run bootc-image-builder and pass the following arguments, including the config.toml:

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v $(pwd)/config.toml:/config.toml \
       -v $(pwd)/output:/output \
       registry.redhat.io/rhel9/bootc-image-builder:latest \
       --type qcow2 \
       --config config.toml \
       quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

3. Launch a VM, for example, by using virt-install:

   $ sudo virt-install \
     --name bootc \
     --memory 4096 \
     --vcpus 2 \
     --disk qcow2/disk.qcow2 \
     --import \
     --os-variant rhel9

   Copy to Clipboard Toggle word wrap

Procedure

1. After the instance starts, connect to it by using SSH using the key you selected when creating the instance:

   $ ssh -i <ssh-key-file> <cloud-user@ip>

   Copy to Clipboard Toggle word wrap

2. Make sure that the system-reinstall-bootc subpackage is installed:

   # rpm -q system-reinstall-bootc

   Copy to Clipboard Toggle word wrap

   If not, install the system-reinstall-bootc subpackage:

   # dnf -y install system-reinstall-bootc

   Copy to Clipboard Toggle word wrap

3. Convert the system to use a bootc image:

   # system-reinstall-bootc <image>

   Copy to Clipboard Toggle word wrap
   • You can use the container image from the Red Hat Ecosystem Catalog or the customized bootc image built from a Containerfile.
4. Select users to import to the bootc image by pressing the "a" key.
5. Confirm your selection twice and wait until the image is downloaded.

6. Reboot the system:

   # reboot

   Copy to Clipboard Toggle word wrap

7. Remove the stored SSH host key for the given <ip> from your /.ssh/known_hosts file:

   # ssh-keygen -R <ip>

   Copy to Clipboard Toggle word wrap

   The bootc system is now using a new public SSH host key. When attempting to connect to the same IP address with a different key than what is stored locally, SSH will raise a warning or refuse the connection due to a host key mismatch. Since this change is expected, the existing host key entry can be safely removed from the ~/.ssh/known_hosts file using the following command.

8. Connect to the bootc system:

   # ssh -i <ssh-key-file> root@<ip>

   Copy to Clipboard Toggle word wrap

Verification steps

1. Save and build your image.

   $ podman build -t quay.io/<namespace>/<image>:<tag> . --cap-add=all --security-opt=label=type:container_runtime_t --device /dev/fuse

   Copy to Clipboard Toggle word wrap

2. Build <_image_> image by using the Containerfile in the current directory:

   $ podman build -t quay.io/<namespace>/<image>:<tag> .

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a 01-fips.toml to configure FIPS enablement, for example:

   # Enable FIPS
   kargs = ["fips=1"]

   Copy to Clipboard Toggle word wrap

2. Create a Containerfile with the following instructions to enable the fips=1 kernel argument:

   FROM registry.redhat.io/rhel9/rhel-bootc:latest
   # Enable fips=1 kernel argument: https://bootc-dev.github.io/bootc/building/kernel-arguments.html
   COPY 01-fips.toml /usr/lib/bootc/kargs.d/
   # Enable the FIPS crypto policy
   # crypto-policies-scripts is not installed by default in RHEL-10
   RUN dnf install -y crypto-policies-scripts && update-crypto-policies --no-reload --set FIPS

   Copy to Clipboard Toggle word wrap

3. Create your bootc <image> compatible base disk image by using Containerfile in the current directory:

   $ podman build -t quay.io/<namespace>/<image>:<tag> .

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a 01-fips.toml to configure FIPS enablement, for example:

   # Enable FIPS
   kargs = ["fips=1"]

   Copy to Clipboard Toggle word wrap

2. Create a Containerfile with the following instructions to enable the fips=1 kernel argument:

   FROM registry.redhat.io/rhel9/rhel-bootc:latest
   # Enable fips=1 kernel argument: https://bootc-dev.github.io/bootc/building/kernel-arguments.html
   COPY 01-fips.toml /usr/lib/bootc/kargs.d/
   # Install and enable the FIPS crypto policy
   RUN dnf install -y crypto-policies-scripts && update-crypto-policies --no-reload --set FIPS

   Copy to Clipboard Toggle word wrap

3. Create your bootc <image> compatible base disk image by using Containerfile in the current directory:

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v $(pwd)/config.toml:/config.toml:ro \
       -v $(pwd)/output:/output \
       -v /var/lib/containers/storage:/var/lib/containers/storage \
       registry.redhat.io/rhel9/bootc-image-builder:latest \
       --local
       --type iso \
       quay.io/<namespace>/<image>:<tag>

   Copy to Clipboard Toggle word wrap

4. Enable FIPS mode during the system installation:

   1. When booting the RHEL Anaconda installer, on the installation screen, press the TAB key and add the fips=1 kernel argument.

      After the installation, the system starts in FIPS mode automatically.

Procedure

1. Create a Containerfile:

   FROM registry.redhat.io/rhel9/rhel-bootc:latest
   
   # Install OpenSCAP scanner and security content to the image
   RUN dnf install -y openscap-utils scap-security-guide && dnf clean all
   
   # Add sudo user 'admin' with password 'admin123'.
   # The user can be used with profiles that prevent
   # ssh root logins.
   RUN useradd -G wheel -p "\$6\$Ga6Zn
   IlytrWpuCzO\$q0LqT1USHpahzUafQM9jyHCY9BiE5/ahXLNWUMiVQnFGblu0WWGZ1e6icTaCGO4GNgZNtspp1Let/qpM7FMVB0" admin
   
   # Run scan and hardening
   RUN oscap-im --profile <profileID> /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

   Copy to Clipboard Toggle word wrap

   This Containerfile performs the following tasks:

   • Installs the openscap-utils package that provides the oscap-im tool and the scap-security-guide package that provides the data streams with the Security Content Automation Protocol (SCAP) content.
   • Adds a user with sudoer privileges for profiles that prevent SSH root logins.
   • Scans and remediates the image for compliance with the selected profile.

2. Build the image by using the Containerfile in the current directory:

   $ podman build -t quay.io/<namespace>/<image>:<tag> .

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a Containerfile:

   FROM registry.redhat.io/rhel9/rhel-bootc:latest
   
   # Copy a tailoring file into the Containerfile
   COPY tailoring.xml /usr/share/
   
   # Install OpenSCAP scanner and security content to the image
   RUN dnf install -y openscap-utils scap-security-guide && dnf clean all
   
   
   # Add sudo user 'admin' with password 'admin123'.
   # The user can be used with profiles that prevent
   # ssh root logins.
   RUN useradd -G wheel -p "\$6\$Ga6Zn
   IlytrWpuCzO\$q0LqT1USHpahzUafQM9jyHCY9BiE5/ahXLNWUMiVQnFGblu0WWGZ1e6icTaCGO4GNgZNtspp1Let/qpM7FMVB0" admin
   
   # Run scan and hardening including the tailoring file
   RUN oscap-im --tailoring-file /usr/share/tailoring.xml --profile stig_customized /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml

   Copy to Clipboard Toggle word wrap

Procedure

1. Write your drop-in configuration file. For example:

   dracutmodules = "module"

   Copy to Clipboard Toggle word wrap

2. Place your drop-in configuration file in the location that dracut normally uses: /usr. For example:

   /usr/lib/dracut/dracut.conf.d/50-custom-added-modules.conf

   Copy to Clipboard Toggle word wrap

3. Regenerate the initrd as part of the container build. You must explicitly pass the kernel version to target to dracut, because it tries to pull the running kernel version, which can cause an error. The following is an example:

   FROM <baseimage>
   COPY 50-custom-added-modules.conf /usr/lib/dracut/dracut.conf.d
   RUN set -x; kver=$(cd /usr/lib/modules && echo *); dracut -vf /usr/lib/modules/$kver/initramfs.img $kver

   Copy to Clipboard Toggle word wrap

1. Pulling the registry.access.redhat.com/ubi9/toolbox:latest image to your local system
2. Starting up a container from the image
3. Running a shell inside the container from which you can access the host system

Procedure

1. Start a Toolbx container by using the toolbox create command and enter the container with the toolbox enter command.

   • As a rootless user:

     $ toolbox create <mytoolbox>

     Copy to Clipboard Toggle word wrap

   • As a root user:

     $ sudo toolbox create <mytoolbox>
     Created container: <mytoolbox>
     Enter with: toolbox enter

     Copy to Clipboard Toggle word wrap

   • Verify that you pulled the correct image:

     [user@toolbox ~]$ toolbox list
     IMAGE ID      IMAGE NAME    CREATED
     fe0ae375f149   registry.access.redhat.com/ubi{ProductVersion}/toolbox 5 weeks ago
     
     CONTAINER ID  CONTAINER NAME  CREATED         STATUS   IMAGE NAME
     5245b924c2cb  <mytoolbox>       7 minutes ago   created  registry.access.redhat.com/ubi{ProductVersion}/toolbox:8.9-6

     Copy to Clipboard Toggle word wrap

     1. Enter the Toolbx container:

        [user@toolbox ~]$ toolbox enter <mytoolbox>

        Copy to Clipboard Toggle word wrap
     2. Optional: Check if you pulled the correct image

   • Enter a command inside the <mytoolbox> container and display the name of the container and the image:

     ⬢ [user@toolbox ~]$ cat /run/.containerenv
     engine="podman-4.8.2"
     name="<mytoolbox>"
     id="5245b924c2cb..."
     image="registry.access.redhat.com/ubi{ProductVersion}/toolbox"
     imageid="fe0ae375f14919cbc0596142e3aff22a70973a36e5a165c75a86ea7ec5d8d65c"

     Copy to Clipboard Toggle word wrap

2. Use the Toolbx to install the development tools:

   1. Install the tools of your choice, for example, the Emacs text editor, GCC compiler and GNU Debugger (GDB):

      ⬢[user@toolbox ~]$ sudo dnf install emacs gcc gdb

      Copy to Clipboard Toggle word wrap

   2. Optional: Verify that the tools are installed:

      ⬢[user@toolbox ~]$  dnf repoquery --info --installed <package_name>

      Copy to Clipboard Toggle word wrap

      After installation, you can continue using those tools as a rootless user.

3. Use Toolbx to troubleshoot the host system without installing them on the host system.

   1. Install the systemd suite to be able to run the journalctl command:

      ⬢[root@toolbox ~]# dnf install systemd

      Copy to Clipboard Toggle word wrap

   2. Display log messages for all processes running on the host:

      ⬢[root@toolbox ~]# j journalctl --boot -0
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>

      Copy to Clipboard Toggle word wrap

   3. Display log messages for the kernel:

      ⬢[root@toolbox ~]# journalctl --boot -0 --dmesg
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>
      Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-e820: [mem 0x0000>

      Copy to Clipboard Toggle word wrap

   4. Install the nmap network scanning tool:

      ⬢[root@toolbox ~]# dnf install nmap

      Copy to Clipboard Toggle word wrap

   5. Scan IP addresses and ports in a network:

      ⬢[root@toolbox ~]# nmap -sS scanme.nmap.org
      Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-02 10:39 CET
      Stats: 0:01:01 elapsed; 0 hosts completed (0 up), 256 undergoing Ping Scan
      Ping Scan Timing: About 29.79% done; ETC: 10:43 (0:02:24 remaining)
      Nmap done: 256 IP addresses (0 hosts up) scanned in 206.45 seconds

      Copy to Clipboard Toggle word wrap
      • The -sS option performs a TCP SYN scan. Most of Nmap’s scan types are only available to privileged users, because they send and receive raw packets, which requires root access on UNIX systems.

4. Stop the Toolbx bootc container.

   1. Leave the container and return to the host:

      ⬢ [user@toolbox ~]$ exit

      Copy to Clipboard Toggle word wrap

   2. Stop the toolbox container:

      ⬢ [user@toolbox ~]$ podman stop <mytoolbox>

      Copy to Clipboard Toggle word wrap

   3. Optional: Remove the toolbox container:

      ⬢ [user@toolbox ~]$ toolbox rm <mytoolbox>

      Copy to Clipboard Toggle word wrap

      Alternatively, you can also use the podman rm command to remove the bootc container.

1. Create files within /usr/lib/bootc/kargs.d with kernel arguments.
2. Fetch the container image to get the OSTree commit.
3. Use the OSTree commit to return the file tree.
4. Navigate to /usr/lib/bootc/kargs.d.
5. Read each file within the directory.
6. Push the contents of each kargs file into a file containing all the needed kargs.
7. Pass the kargs to the stage() function.
8. Apply these arguments to switch, upgrade, or edit.

Procedure

1. Create a symbolic link between bootc and Podman to use a single pull secret. By creating the symbolic link, you ensure that both locations are present to a common persistent file embedded in the container image.

2. Create the /usr/lib/container-auth.json file.

   FROM quay.io/<namespace>/<image>:<tag>
   COPY containers-auth.conf /usr/lib/tmpfiles.d/link-podman-credentials.conf
   RUN --mount=type=secret,id=creds,required=true cp /run/secrets/creds /usr/lib/container-auth.json && \
       chmod 0600 /usr/lib/container-auth.json && \
       ln -sr /usr/lib/container-auth.json /etc/ostree/auth.json

   Copy to Clipboard Toggle word wrap

   When you run the Containerfile, the following actions happen:

   • The Containerfile makes /run/containers/0/auth.json a transient runtime file.
   • It creates a symbolic link to the /usr/lib/container-auth.json.
   • It also creates a persistent file, which is also symbolic linked from /etc/ostree/auth.json.

Procedure

1. Configure a pull secret:

   %pre
   mkdir -p /etc/ostree
   cat > /etc/ostree/auth.json << 'EOF'
   {
           "auths": {
                   "quay.io": {
                           "auth": "<your secret here>"
                   }
           }
   }
   EOF
   %end

   Copy to Clipboard Toggle word wrap

   With this configuration, the system pulls images from quay.io using the provided authentication credentials, which are stored in /etc/ostree/auth.json.

2. Disable TLS for an insecure registry:

   %pre
   mkdir -p /etc/containers/registries.conf.d/
   cat > /etc/containers/registries.conf.d/local-registry.conf << 'EOF'
   
   [[registry]]
   location="[IP_Address]:5000"
   insecure=true
   EOF
   %end

   Copy to Clipboard Toggle word wrap

   With this configuration, the system pulls container images from a registry that is not secured with TLS. You can use it in development or internal networks.