28.2. Automatic Disk Image Installation
Creation of disk images and the installation into them can be automated using livemedia-creator. To perform an automatic installation, you will need an installed Red Hat Enterprise Linux system and a Kickstart file. The disk images themselves do not need to be created manually. For information about creating and using Kickstart files, see Chapter 27, Kickstart Installations.
28.2.1. Overview of livemedia-creator
Creating custom images using livemedia-creator is usually a two stage process. In the first stage, a temporary disk image file is created and Anaconda, the Red Hat Enterprise Linux installation program, installs a system on this image based on the parameters provided in a Kickstart file. Then, in the second stage, livemedia-creator uses this temporary system to create the final, bootable image.
This behavior can be changed by specifying additional options. For example, it is possible to go through the first stage only, with the result being a disk image file, or to skip the first stage and use an existing disk or file system image to create the final bootable ISO image.
Sample usage of livemedia-creator is described in Section 28.2.4, “Creating Custom Images”. On a system where the lorax package is installed, a list of all available options can be displayed using the
livemedia-creator --help command. Additional documentation is also installed along with the lorax package: the livemedia-creator(1) man page and the README.livemedia-creator file located in the /usr/share/doc/lorax-version/ directory, where version is the version of the lorax package you have installed.
28.2.2. Installing livemedia-creator
The livemedia-creator tool is a part of the lorax package. To install the package, execute the following command as
root:
#yum install lorax
You will also need to install several other packages in addition to lorax itself. These packages are not dependencies of lorax and therefore they are not installed automatically, but you might need them depending on what exactly are you using livemedia-creator for. Among these packages are:
- virt-install: a package providing tools to build new virtual machines, used in the first stage of live media creation unless the
--no-virtoption is specified. - libvirt, qemu-kvm, libvirt-client and other virtualization tools: when using virt-install, your system must be prepared to create, run and manage a virtual machine. See the Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide for information on virtualization in Red Hat Enterprise Linux and for documentation about installing and working with virtualization tools.
- anaconda: the Red Hat Enterprise Linux installation program, used in the first stage instead of virt-install if the
--no-virtoption is used.
Other applications, which are beyond the scope of this chapter, might be necessary. If you attempt to execute livemedia-creator and a package required with the options you specified is missing, the program will stop and an error message will be displayed informing you of packages you need to install before proceeding.
28.2.3. Sample Kickstart Files
To successfully create a custom live image, you will need a valid Kickstart configuration file. Two samples are automatically installed along with lorax. You can use these samples as a reference when creating your own custom images, or you can copy them and modify them to suit your intended usage. Both provided samples are located in the
/usr/share/doc/lorax-version/ directory, where version is the version number of the lorax package installed on your system.
The available samples are:
rhel7-minimal.ks: a configuration file which provides only a minimal installation (the@coregroup) and other essentials such as the kernel and the GRUB2 boot loader. No users apart fromrootare created, and no graphical interface or additional packages are installed.rhel7-livemedia.ks: a more advanced configuration file which creates a live system with a graphical interface. A user namedliveuseris created along withroot.
Both sample configurations need to be modified to use a valid location as the installation source. To do this edit the file and update the url command to refer to a valid installation source. See Chapter 27, Kickstart Installations for more information about Kickstart. No other changes are necessary for these samples to work.
Important
Do not modify the samples in their original location. Copy them to another directory and modify the copies instead.
Note
Red Hat only supports the repositories provided by Red Hat as installation source.
Note
When modifying the provided samples or making a Kickstart file from scratch, do not use the
%include statement as they are not supported by livemedia-creator. All Kickstart files must be flattened either manually or using the ksflatten tool before they can be used.
28.2.4. Creating Custom Images
This section describes several common usage patterns for tools in the lorax package. It is not intended to be a complete list of available options. To view every available option for livemedia-creator, execute
livemedia-creator --help or see the livemedia-creator(1) man page. For more information about lorax, see https://weldr.io/lorax/.
28.2.4.1. Using lorax to create a boot.iso file
The installation system of Red Hat Enterprise Linux is created by a tool named lorax. The lorax tool can also be used to create your own installation media, for example containing an updated kernel or additional packages.
Note
It is recommended to use lorax on a system that is the same release of Red Hat Enterprise Linux as the image being created.
After running the following as root, an installation image named
boot.iso will exist in the results/images directory. The --repo= command loads a Yum repository configuration file, in this case the default one, and use it to download package from Red Hat's content delivery network the same way they would be downloaded during a system update.
#yum install lorax#setenforce 0#lorax -p RHEL -v 7.4 -r 7.4 --repo=/etc/yum.repos.d/redhat.repo ./results/#setenforce 1
Note
The above commands require that the system they are executed on has been registered and subscribed with Red Hat Subscription Manager. For more information, see Red Hat Subscription Management.
28.2.4.2. Creating a Live Image Using virt-install
Perhaps the most common use of livemedia-creator involves using virt-install to create a temporary virtual machine to be used for the live image creation process. To create a live ISO using virt-install, you will need a valid Kickstart file and a bootable ISO image which contains the Anaconda installation program. Such images are provided by Red Hat as "minimal boot media"; see Section 3.2, “Making Installation USB Media” for details.
The following command is the bare minimum you need to create a live image using virt-install:
#livemedia-creator --make-iso --iso=/path/to/boot.iso --ks=/path/to/valid/kickstart.ks
Replace /path/to/boot.iso with a path to a minimal boot image and /path/to/valid/kickstart.ks with a path to a valid Kickstart file to be used in the image creation process.
Other frequently used options in this particular use case are:
--vnc vnc: this option allows you to watch the installation process using a VNC client such as TigerVNC. The option is passed to virt-install's--graphicsoption. See Chapter 25, Using VNC for more information.--ram x: allows you to specify the amount of RAM for the temporary virtual machine in MiB.--vcpus x: the amount of the virtual machine's processors.
28.2.4.3. Creating a Live Image Using Anaconda's Image Install
The livemedia-creator application can create a live image using the Anaconda package if virt-install is not available. In this case, no image containing the installation program is needed, but the Anaconda package must be installed on the system. Again, the process has two stages: first, a temporary disk image is created and a system is installed into it, and then this image is used to create the final bootable ISO.
Warning
Live image creation using Anaconda is potentially dangerous, because it uses the installation program on the system itself instead of inside a virtual machine. While no bugs are known at this moment that would cause any problems, it is possible that this process could render the entire system unusable. Running livemedia-creator with the
--no-virt option is therefore only recommended on virtual machines (guests) specifically reserved for this purpose.
Important
Set Security Enhanced Linux (
SELinux) to permissive (or disabled) mode before creating custom images with Anaconda. See Red Hat Enterprise Linux 7 SELinux User's and Administrator's Guide for information on setting SELinux modes.
To create a live image using Anaconda, use the
--no-virt option. For example:
#livemedia-creator --make-iso --ks=/path/to/valid/kickstart.ks --no-virt
28.2.4.4. Creating a Disk or File System Image
You can also use livemedia-creator to create a disk or file system image. This means running only the first stage of the image creation process. The final ISO will not be created, the program will stop after finishing the installation process on the temporary disk or file system image file. You can then mount and inspect this image for errors, which can be useful when troubleshooting a modified Kickstart file, and you can also keep it for future use to save time when creating images in the future.
Note
It is also possible to use the
--no-virt option in all examples in this section.
There are several ways to stop the creation process after the first stage. You can use the
--image-only option as illustrated in the following example:
#livemedia-creator --make-iso --ks=/path/to/valid/kickstart.ks --iso=/path/to/boot.iso --image-only
Alternatively, you can use the
--make-disk option instead of --make-iso:
#livemedia-creator --make-disk --ks=/path/to/valid/kickstart.ks --iso=/path/to/boot.iso
You can also create a file system image instead of partitioned disk image using the
--make-fsimage option:
#livemedia-creator --make-fsimage --ks=/path/to/valid/kickstart.ks --iso=/path/to/boot.iso
In all cases, the result will be a partitioned disk image or a file system image, located in the
/var/tmp/ directory by default. To change the location of the result, use the --tmp /path/to/temporary/directory/ option, where /path/to/temporary/directory/ is the path to the target directory.
28.2.4.5. Using a Previously Created Disk or File System Image
If you already have a disk or file system image (see Section 28.2.4.4, “Creating a Disk or File System Image”), you can supply it to livemedia-creator to produce the final bootable ISO image. In this case no Kickstart File or Anaconda installation image is necessary; these are only needed in the first stage of the image creation process, which is skipped in this case.
To create a final image from an existing partitioned disk image file, use the
--disk-image option. For example:
#livemedia-creator --make-iso --disk-image=/path/to/disk/image.img
If you want to use a file system image instead of a disk image, use the
--fs-image option instead:
#livemedia-creator --make-iso --fs-image=/path/to/filesystem/image.img
28.2.4.6. Creating an Appliance
The livemedia-creator utility can be used to create appliance images (a partitioned disk image), including an XML file containing its description, generated using a template. Virtual machine installations as well as image installations are supported in this case. To create an appliance image and description, use the
--make-appliance option instead of --make-iso. For example:
#livemedia-creator --make-appliance --ks=/path/to/valid/kickstart.ks --iso=/path/to/boot.iso
Both the image and the description XML file will be stored in the
/var/tmp/ directory unless a different one is specified using the --resultdir option.
Additional options specific to appliance creation are:
--app-name name: specifies the name of the appliance, which will appear in the XML description file marked by the<name>tag. The default value isNone.--app-template /path/to/template.tmpl: specifies the template to be used. The default is/usr/share/lorax/appliance/libvirt.tmpl.--app-file /path/to/app/file.xml: specifies name of the generated description XML file. The default value isappliance.xml.
28.2.4.7. Creating an Amazon Machine Image (AMI)
To create an Amazon Machine Image (AMI) for use within the Amazon Elastic Compute Cloud (EC2), use the
--make-ami option. Virtualized and image installations are both supported.
#livemedia-creator --make-ami --ks=/path/to/valid/kickstart.ks --iso=/path/to/boot.iso
The result will be an image file named
ami-root.img, located in the /var/tmp/ directory, unless you used the --resultdir option to specify a different one.
28.2.4.8. Additional Arguments
The following options can be used with all use cases listed above (virtual installations, Anaconda image installations and others).
--keep-image: when you specify this option, the temporary disk image file used in the first stage of the installation will not be deleted. It will be located in the/var/tmp/directory and it will have a randomly generated name such asdiskgU42Cq.img.--image-only: using this option means that only the first stage of the image creation process will be executed. Instead of producing the final bootable ISO image, livemedia-creator will only create the temporary disk image file and perform an installation on it. This option allows you to save time when testing modifications to your Kickstart file, because you can skip the time-consuming second stage and inspect the temporary disk image file.--image-name name: allows you to specify a custom name for the temporary disk image file. The default name is randomly generated (for example,disk1Fac8G.img).--tmp /path/to/temporary/directory/: specifies the top level temporary directory. The default value is/var/tmp/. When using this option, you must specify a directory which already exists.--resultdir /path/to/results/directory/: specifies the directory where the results (the bootable ISO image) will appear after livemedia-creator finishes. An already existing directory cannot be specified. The default is/var/tmp/. This option only applies to the final ISO image; if you are creating a disk or file system image and want it to be saved at a specific location, use the--tmpoption.--logfile /path/to/log/file/: specifies the location of the program's log file.
28.2.5. Troubleshooting livemedia-creator Problems
This section offers suggestions on solving various issues commonly encountered when using livemedia-creator. If you encounter a problem not described here, you can look into the program's log files, which are automatically generated during every run and saved into the directory from which you executed the tool, unless you specify a different directory using the
--logfile option. The log files will be different based on the options you used - for example, virt-install.log will not be generated when you use the --no-virt option (instead, you will get log files from Anaconda, located in the anaconda/ directory). Other files, namely livemedia.log and program.log, are generated every time.
Another way to find and solve problems is using the
--image-only option when running the utility. This option will stop the program after the first stage, so only a disk image file will be generated instead of the final bootable ISO. You can then mount the disk image file and examine its contents without having to wait for the second stage to finish. Alternatively, you can use the --keep-image option, which will execute both stages, but keep the temporary disk image for later analysis.
Using the
--vnc option is recommended when testing changes to the Kickstart file. This option will allow you to use a VNC client to connect to the virtual machine and watch the installation progress. See Chapter 25, Using VNC for details.
28.2.5.1. Stuck Virtual Machine Installation
If the installation program stops for any reason during the first stage of a virtual installation, livemedia-creator will stop as well, waiting for the installation to finish. You can either interrupt the program directly, or you can solve this problem by stopping the temporary virtual machine. Livemedia-creator will detect that the guest operating system has been stopped, delete all temporary files and exit.
To stop the temporary virtual machine, follow this procedure:
Procedure 28.1. Stopping the Temporary Virtual Machine
- Use virsh to list all virtual machines (guests) currently available on the system. The output will be similar to the following:
#virsh list --allId Name State ---------------------------------------------------- 93 LiveOS-2a198971-ba97-454e-a056-799f453e1bd7 running - RHEL7 shut offIdentify the temporary virtual machine. Its name will always start withLiveOS, followed by a string of random numbers and characters. - Once you have identified the temporary virtual machine, stop it using the
virsh destroy namecommand, where name is the virtual machine's name:#virsh destroy LiveOS-2a198971-ba97-454e-a056-799f453e1bd7Domain LiveOS-2a198971-ba97-454e-a056-799f453e1bd7 destroyed
28.2.5.2. Failed installation using a Virtual Machine
If you were performing a virtual installation and the process was interrupted for any reason (such as hardware failure, power outage or a keyboard interrupt) during the first stage, virt-install will not be able to start again until the previously created temporary disk image and virtual machine have been removed. The following procedure explains how to do this.
Not all steps might be necessary every time. For example, if you are recovering after a system crash, you will not have to stop the temporary virtual machine, instead you can just use the
virsh undefine name command. You can also use steps 4 and 5 if you only want to clean up temporary files created by livemedia-creator and nothing else.
Procedure 28.2. Removing Temporary Guests And Disk Image Files
- Use virsh to list all virtual machines (guests) currently available on the system. The output will be similar to the following:
#virsh list --allId Name State ---------------------------------------------------- 93 LiveOS-2a198971-ba97-454e-a056-799f453e1bd7 running - RHEL7 shut offIdentify the temporary virtual machine. Its name will always start withLiveOS, followed by a string of random numbers and characters. - Once you have identified the temporary virtual machine, stop it using the
virsh destroy namecommand, where name is the virtual machine's name:#virsh destroy LiveOS-2a198971-ba97-454e-a056-799f453e1bd7Domain LiveOS-2a198971-ba97-454e-a056-799f453e1bd7 destroyed - Delete the temporary virtual machine using
virsh undefine name, using the same name as in the previous step.#virsh undefine LiveOS-2a198971-ba97-454e-a056-799f453e1bd7Domain LiveOS-2a198971-ba97-454e-a056-799f453e1bd7 has been undefined - Find the temporary file system's mount. It will be targeted to the
/var/tmp/directory and its name will belorax.imgutilsfollowed by six random numbers or characters.#findmnt -T /var/tmp/lorax.imgutils*TARGET SOURCE FSTYPE OPTIONS /var/tmp/lorax.imgutils.bg6iPJ /dev/loop1 iso9660 ro,relatimeThen, unmount it using theumountcommand:#umount /var/tmp/lorax.imgutils.bg6iPJ - Find the temporary disk image created by virt-install in the
/var/tmp/directory. The name of this file is printed to command line at the beginning of the installation process and is randomly generated, unless you specify a name using the--image-nameoption. For example:2013-10-30 09:53:03,161: disk_size = 5GB 2013-10-30 09:53:03,161: disk_img = /var/tmp/diskQBkzRz.img 2013-10-30 09:53:03,161: install_log = /home/pbokoc/lorax/virt-install.log mount: /dev/loop1 is write-protected, mounting read-only
In the above example, the temporary disk image is/var/tmp/diskQBkzRz.img.If you cannot find the initial messages, you can identify the temporary files manually. List all contents of the/var/tmp/directory using thelscommand and filter the output for files containingdiskin their names:#ls /var/tmp/ | grep diskdiskQBkzRz.imgThen, delete the temporary disk image:#rm -f /var/tmp/diskQBkzRz.img
If you followed all steps in this procedure, you are now able to start a new installation with virt-install.
28.2.5.3. Failed Installation Using Anaconda
Recovery from an interrupted installation using Anaconda image install feature (the
--no-virt option) can be achieved by executing the anaconda-cleanup script, which is installed along with the anaconda package. This script is located in the /usr/bin/ directory.
Use the following command to execute the cleanup script. You will need root privileges to do this.
#anaconda-cleanup
