SDB:KIWI Cookbook Start Cooking
All of KIWI edit
General Preparation for all recipes
Before we start cooking, we need to make sure that we have all required ingredients ready and set up correctly.
Install the KIWI toolset
It is strongly recommended that you use the released version of the KIWI tool chain. Adding the Virtualization:Appliances repository to your system will allow you to install all KIWI related packages.
The commands below illustrate how to add the repository and install the KIWI tools from the command line using zypper. Alternatively you may use the YaST2 GUI to add the repository and accomplish the installation.
- Add the Tools repository if needed (using openSUSE 11.3 as an example, to see a list of other repositories point you browser at http://download.opensuse.org/repositories/Virtualization:/Appliances )
- Install kiwi and other needed packages
If you previously configured the Tools repository and did not install KIWI just use the above command.
The following commands will allow you to update all packages from the Tools repository, including KIWI if it was installed previously.
- Refresh the repository
- Update all installed packages with newer versions
Note: For detailed information about the zypper command line options see the zypper man page ( man zypper ) or the usage documentation SDB:Zypper_usage
The directories where we cook
Creating images with KIWI requires space in your file system (your hard drive or mounted external storage). The amount of space required depends on the size of the packages being used and any additional software to be placed into the image.
The general guideline for storage space is 8 GB + the size of any additional software. Within the 8 GB storage space one can install the entire distribution, thus this provides sufficient space for all the packages you require from the distribution repository.
For the examples provided here we will use directories in /tmp. However, you may choose to locate these working directories anywhere in your file system.
The directories created in this step will be used later as command line arguments.
Temporary build space directory:
Final image directory:
Please note that the directory used for the temporary build space may only be used once, i.e. the directory will have to be emptied prior to preparing another image in the same directory. The kiwi tool chain will produce an error such as: Couldn't create root directory: File exists failed.
The next section provides a quick overview of the basic commands and a short high level description about how Kiwi works.
Get ready to start cooking!
Creating an image with KIWI is a two step process. The first step is the preparation step followed by the creation step.
In the preparation step, the so called unpacked image is created in the temporary build space directory (/tmp/myiso in our examples, as mentioned above). The unpacked image in the temporary build space contains your new file system based on one or more software package(s) from the specified repositories (more on the repositories later).
The creation step uses the file system created in the preparation step as the image root tree to create the output image. This image is placed in the final image directory (e.g. /tmp/myiso-result in our examples, as mentioned above). If the image type ISO was requested, the output image is a file with the suffix .iso representing a live system on CD or DVD. It is also possible to create ISO images that can be used as installation source.
In addition to creating the LiveCD ISO image, kiwi is able to create images for full virtual (VMWare/qemu) and para-virtual (Xen) environments as well as for USB sticks, PXE network clients and OEM customized Linux systems.
The basic commands
Executing the two step prepare and create process is accomplished with the following commands.
kiwi --prepare <ImageDescriptionPath> --root <RootPath>
kiwi --create <RootPath> --destdir <DestinationPath>
- The ImageDescriptionPath is a directory containing a basic description of the ingredients of the image. (How this directory is used and the structure of this directory will become more evident once we complete the recipes below).
- The RootPath is the destination directory for the unpacked image, e.g /tmp/myiso
- The DestinationPath is the path to the final image directory, e.g. /tmp/myiso-result
The kiwi tool chain supports the combination of the previous two command line invocations into one. This is accomplished by passing the --build command line option. With the --build opting kiwi will still execute 2 distinct steps. However, from a users perspective only one command needs to be executed, as shown below.
kiwi --build <ImageDescriptionPath> --destdir <DestinationPath>
In this case the unpacked image will be created in a sub-directory of the DestinationPath called image-root, following our example kiwi would create /tmp/myiso-result/image-root for the unpacked image.
The source repository
As mentioned previously KIWI creates an unpacked image prior to creating the final image by installing packages. These packages are extracted from an installation source or so called repository. A repository is a collection of packages.
Specifying the installation source on the command line is accomplished using the --set-repo command line option as follows:
kiwi --build <ImageDescriptionPath> --destdir <DestinationPath> --set-repo <RepositoryPath>
Repository Options
Kiwi supports local and Internet based repositories.
With help of the --set-repo option we can set what is used as repository or overwrite the repo URL for the first listed repo from the XML file. The change is temporary and will not be written to the XML file.
The following examples show how to specify these various repositories on the command line.
- Using and Internet based repository, such as the openSUSE 11.3 repository.
kiwi --build <ImageDescriptionPath> --destdir <DestinationPath> --set-repo http://download.opensuse.org/distribution/11.3/repo/oss/
The openSUSE examples provided by KIWI use the openSUSE online repository and it is not necessary to use the --set-repo command line option. How this is configured will be explained in later chapter. See Change/Add Repositories section in our LiveSystem recipe.
- If you have the openSUSE 11.3 installation DVD you may use it as repository.
Insert the DVD into your drive and if you are using openSUSE 11.3 it will be mounted as /media/SU1110.001. If the media is not mounted automatically you may use a regular mount command to mount the DVD.
Assuming the DVD got auto mounted the following command demonstrates how we can use the mounted DVD as the installation source repository.
kiwi --build <ImageDescriptionPath> --destdir <DestinationPath> --set-repo /media/SU1110.001
- If you have the install DVD ISO image available, you may use it instead of burning it to a DVD.
In order to use the image you first must loop mount it such that it becomes available as a block device. Then use the mount point as the repository path.
mount -o loop /path-to-the-iso-file/filename.iso /mnt
kiwi --build <ImageDescriptionPath> --destdir <DestinationPath> --set-repo /mnt
A few words about the speed
Before we move on to our first example, a few words about the speed at which the image can be created.
Kiwi will access the specified repository to obtain the packages required for the image to be created. Thus if you are using an online repository the speed of creation will be dominated by the bandwidth of your Internet connection. Using a mounted DVD the speed will be dependent on the speed of your DVD drive, and using the mounted ISO image your hard drive access performance will have a strong influence on the image creation speed.
Generally the image creation will be fastest if you access a local repository, i.e. the installation DVD, a loop mounted ISO image or even a local mirror of the online repository on you LAN.
Caveats
- If you are building a 64 bit image you will need to use qemu-kvm (from the kvm package) instead of qemu
- The image name for example suse-11.3-live-iso.i686-2.5.1.iso contains the system architecture, i686 in this case. In all our recipes you will need to substitute the proper names if you build on a different architecture.
- It is possible to build a 32 bit image (x86) on a 64 bit (x86_64) system by prefixing the kiwi command with linux32 as follows: