Config.Xml File Part I

KIWI Building OS images and Appliances

Robert Schweikert Software Engineer Consultant Novell Welcome and Introduction Who am I

•Robert Schweikert • Work in ISV Engineering team – Work closely with IBM – Work on appliances with other ISVs as time permits • Contribute to Kiwi • Contribute to the openSUSE project • Active member of the LSB work group • Nuts about soccer

•Welcome and Introduction •Preliminaries • What is Kiwi • Setting up a Kiwi build • High level Kiwi image build process overview • Kiwi documentation resources • Using the Kiwi build environment •Using Kiwi • The Kiwi configuration tree • Kiwi configuration – the config.xml file part I

• Kiwi configuration – the config.xml file part II • Exploring image types • Kiwi configuration – the config.sh file • Kiwi configuration – the images.sh file • The overlay file system • What is an appliance • Build an appliance •Summary •Final Questions, Thoughts, Comments

•It's a Fruit •It's a Bird •It's someone from New Zealand •It is a Linux image build system • Kiwi is an open source project hosted at kiwi.berlios.de licensed under GPL v2 with roots in the openSUSE build service. • Kiwi is mostly written in Perl • Kiwi is the engine behind SUSE Studio

•root access is required •Kiwi is part of the openSUSE standard repository •Kiwi is part of the SLE-SDK • Add the SDK as a repository through YaST • Detailed description at http://www.novell.com/communities/node/10464/step-step-guide-set-kiwi-build-environment-sle •Live on the bleeding edge http://download.opensuse.org/repositories/Virtualization:/Appliances/ •In YaST or via zypper search for kiwi, install the packages

•Two step process • Prepare step – Output is unpacked image directory • Create step – Output is the desired image

•Kiwi reads information from configuration tree •Kiwi initializes the configured repositories •Kiwi installs the configured packages into specified directory • Dependency resolution occurs automatically and dependent packages are installed • This is called the “unpacked image tree” •Kiwi applies overlay files •Kiwi executes config.sh script from configuration tree •Generic command line • kiwi –prepare PATH_TO_CONFIG –root PATH_TO_DEST

•Kiwi reads information from the configuration tree •Kiwi accesses the unpacked image tree •Kiwi executes images.sh from configuration tree •Kiwi creates the boot image (initrd) • Boot image created by another instance of Kiwi • Uses Kiwi configuration installed with the kiwi-desc-*boot packages •Kiwi builds the specified image in the appropriate format

•Cookbook • On the web: – http://git.berlios.de/cgi-bin/gitweb.cgi?p=kiwi;a=blob;f=doc/kiwi.pdf • From the kiwi-doc package: – /usr/share/doc/packages/kiwi/kiwi.pdf •Schema documentation • Point your browser at: – file:///usr/share/doc/packages/kiwi/schema/kiwi.html •Online Example Cookbook • http://en.opensuse.org/Build_Service/KIWI/Cookbook

•Kiwi is a command line tool • GUI front end is SUSE Studio •Most Kiwi commands require root privileges • Kiwi needs to access package management • Kiwi installs packages into the unpacked image tree • Kiwi needs to perform operations on the image being created that require root access – Setup users – Setup networking – ......

•Kiwi uses a directory structure as configuration • config.xml → required • config.sh → optional • images.sh → optional • archives → optional • root → optional

•config.xml – required • Configuration file used to specify attributes of the image to be created, packages to be included, image type, etc. •config.sh - optional • Shell script executed at the root level at the end of the prepare step. •images.sh - optional • Shell script executed at the root level at the beginning of the create step.

•archive – optional • One or more archives in a known format, tar, tar.gz, tar.bz2, etc. The archive name is specified in config.xml. The archive will be extracted at the root level prior to the execution of config.sh during the prepare step •root – optional directory • A directory that may represent the structure of the root file system of the image. Files and directories in this tree are copied to the image root tree after the extraction of any archives in the prepare step. Files in this directory are referred to as overlay files.

•XML file following XML rules • File is validated as part of the build process against schema – Schema is covered later • When schema is updated automatic upgrade functionality is provided via XSLT •Specify aspects of the image to be created •Specify packages to be installed

•All elements are children of the element •Elements may have attributes or children •Too many elements and attributes to discuss in detail cover most common elements, attributes, and use cases •Use schema documentation and Cookbook for additional details

1.0.0 zypper false true en_US us.map.gz

10 Novell Inc. 21 Kiwi configuration - config.xml

•Kiwi config.xml file is governed by a schema •Schema is implemented in RELAX NG (relaxing) compact notation • http://www.relaxng.org/ • http://www.relaxng.org/tutorial-20011203.html • http://en.wikipedia.org/wiki/RELAX_NG •The schema document is installed by the kiwi package in /usr/share/kiwi/modules/KIWISchema.rnc •Schema may change between Kiwi releases • Kiwi provides automatic upgrades of config.xml files via XSLT (XSL Transformations)

•The schema documentation is found in /usr/share/doc/packages/kiwi/schema/kiwi.html installed by the kiwi-doc package •Parser messages are not always the most useful

•Element pattern: k.ELEMENTNAME • Contains the complete definition of the given element, including attributes and content model. For example: k.image for the image element. • Attribute pattern: k.ELEMENTNAME.ATTRNAME.attribute • Contains an attribute definition for a given element, for example: k.image.name.attribute for the name attribute of the image element. •Attribute pattern for shared attributes: k.ATTRNAME.attribute • Used for attributes shared between multiple elements, for example: k.id.attribute for the id attribute. •Attribute collection: k.ELEMENTNAME.attlist • Collects all attributes for a given element, for example: k.image.attlist contains all attributes from the image element. •Content pattern: k.ELEMENTNAME.content • Contains the supported values and datatypes in this context.

•A typical Element definition #======# common element # div { (1) k.archive.name.attribute = k.name.attribute (2) k.archive.bootinclude.attribute = k.bootinclude.attribute (2) k.archive.attlist = (3) k.archive.name.attribute & (4) k.archive.bootinclude.attribute? (5) k.archive = (6) ## Name of an image archive file (tarball) element archive { k.archive.attlist, empty } }

(1) Elements are wrapped in div {....} constructs (2) Attribute definition (3) Attribute list definition (4) Add required (&) “name” attribute to attribute list (5) Add optional (?) “bootinclude” attribute to attribute list (6) Define the element • Use attributes defined in attribute list • Element has no value (empty) •More info see • http://en.opensuse.org/Build_Service/KIWI/Cookbook_Recipe06

•Image types are determined by the value of the “image” attribute of the element. •ec2 • An Amazon Machine Image for the Amazon Elastic Compute Cloud image • Requires the use of the element for configuration purposes of the image • Requires the installation of the Amazon tools – http://docs.amazonwebservices.com/AmazonEC2/gsg/2006-06-26/ • Kiwi provides the “suse-ec2-guest” example in the kiwi- doc package • Resulting AMI can be uploaded and registered on EC2

•oem • Image within an image – Inner image is the image configured in config.xml ready for deployment onto HW – Outer image is a live system with an “auto installer” – Detects storage media and dumps inner image onto storage media » Either dump to partition or to entire drive is possible, dump to drive erases any pre-existing data – Inner image will automatically adapt to disk geometry • Use child element to influence configuration of the deployed image – Configure swap space, separate home partition, image size, etc.

• Use the “format” attribute to select the outer image format – ISO file or USB stick – Without format attribute the output is a raw disk image that can be dumped to a storage device such as a hard drive • Partitioning can be controlled via LVM, use child element

•pxe • Boot image and system image are separated – Install in specific locations on PXE server • Use requires DHCP server and atftp server • Client configuration is controlled via config. file

•usb • Build a Live system on a USB stick, i.e. a portable system with full read/write access • Supports LVM, use child element • Kiwi has –bootstick option to deploy image on USB stick – Can use “dd” utility to dump the image onto the stick, don't forget the bs=32k option or stick will not boot

•vmx • Generates a virtual disk image • Format of image determined by “format” attribute – bochs → Bochs emulator disk format – cloop → compressed loop – cow → qemu disk format – dmg → Mac OS disk format – ovf → Open Virtual Format (requires VMmare ovftool) – qcow & qcow2 → qemu disk format – vmdk → VMware disk format, also generates .vmx config file – vpc → Virtual PC disk format (read only) – vvfat → DOS 32 file system © August 7, 2010 Novell Inc. 33 Exploring image types

• For vmdk format use child element to configure VMware options • Supports LVM with the child element

•xen • Build a Xen image – Host – Set “bootprofile” attribute to “xen” – Set “bootkernel” attribute to “xenk” – Set “domain” attribute of to “dom0” • Use child element to configure Xen options • Specify installation of kernel-xen and xen packages – Potentially in section • Kiwi creates the name.xenconfig file

•Expected at top level of configuration tree •Executed at / level in unpackaged image tree at the end of the prepare step in fully functional scripting environment •Functions available to modify/customize image • Also provides access to build environment information •Non 0 exit status triggers Kiwi build failure

•Expected at top level of configuration tree •Executed at the / level of the unpacked image tree at beginning of create step •Design such that it will work even if called multiple times • Kiwi allows multiple image creation from one unpacked image tree •Most often useful for boot images as size really matters •A number of pre-defined functions are available

•All content in the directory named “root” in the Kiwi configuration tree is copied to the unpacked image tree prior to execution of config.sh • config.sh can operate on data added to image via this overlay mechanism •Full access to all files • Can overwrite any configuration file installed from any package – Firewall rules – Database setup – Web server configuration

• Not recommended to re-implement scripts from boot mechanism as these might change between OS versions. Modify files provided by packages if necessary – inittab – boot.* •Add your application if it is not packaged as rpm

•An appliance is the combination of the OS, an application and any middle ware and configuration in one package

•Another delivery mechanism for your application • Saves installation effort at the customer • Saves configuration effort at the customer •Deliver as hardware appliance • OEM image “factory installed” + hardware

•Deliver as software appliance • OEM image – Customer provides hardware – Customer boots of media and appliance proceeds with self installation • Virtual appliance – Deliver the virtual disk image – Customer simply drops image into their virtual infrastructure

•Start the provided build image or log into the system if you installed the OEM image • root / kiwiUser • Start terminal – cd ~ – kiwi –prepare ./kiwiLab –root /tmp/kiwiLab_unpacked – kiwi –create /tmp/kiwiLab_unpacked -d /tmp/kiwiLab_image

•What desktop environment is used in the appliance?

• Find the lines in the appropriate configuration files effecting the desktop environment setup.

•What is the repository type used to install the packages in the image?

•Where is the repository located?

•What type of image is being created by default?

•What user is automatically logged into the system when it boots?

• Where did you find this information?

•What applications start automatically on login

•Where in the Kiwi configuration tree is one of the autostart applications located?

•What kernel drivers are removed from the image?

•Kiwi is very flexible image build tool •Command line driven for easy integration into any build process •Supports creation of many image formats from one prepared image tree •Open source licensed under GPL v2 •Post questions to: [email protected] •Developers: [email protected] •Git repository: git.berlios.de/kiwi

General Disclaimer This document is not to be construed as a promise by any participating company to develop, deliver, or market a product. Novell, Inc., makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.

This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 2.5 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/2.5/.

For other licenses contact author.