koan stands for ``kickstart-over-a-network'' and allows for both network provisioning of new virtualized guests (Xen, QEMU/KVM) and re-installation of an existing system. koan is a client side application used with a Cobbler boot server.
koan --server=<host> [--list-profiles|--list-systems]
koan --server=<host> [--virt|--replace-self|--display] [--profile=<name>|--system=<name>] [--virt-name=<name>] [--virt-path=<path>] [--virt-type=<type>] [--virt-graphics]
When invoked, koan requests install information from a remote cobbler boot server. What koan does with the profile data depends on whether it was invoked with --virt or --replace-self.
Indicates the hostname of the Cobbler boot server to be contacted. Successful communication requires that no firewalls are blocking the cobbler XMLRPC port, which is usually 25151, and that ``cobblerd'' is running on the cobbler server.
This argument must be specified for all koan commands.
Specifying ``DISCOVER'' for the server in all caps will request automatic discovery of a nearby cobbler server using Avahi. The avahi-tools package must be installed to use this functionality.
Lists of the resources that can be installed from a remote server can be obtained by using the following commands:
Shows a list of profiles that can be remotely installed from the cobbler server.
Shows a list of systems that can be remotely installed from the cobbler server. Systems contain the same information as profiles but may be further customized in terms of parameters or kickstart information. The level of customization varies depending on what has been specified on the cobbler server.
Example: koan --server=cobbler.example.org --list-systems
The commands --virt, --replace-self, and --display all take the following arguments:
Names a profile, known to cobbler, that is to be installed.
Names a system, known to cobbler, that is to be installed. --system cannot be used at the same time as --profile; pick one or the other.
In depth data about what is being installed can be viewed prior to kicking off an installation. Use --display instead of --virt or --replace-self. When using this argument, specify the data to display with --profile or --system.
Example: koan --server=cobbler.example.org --display --profile=fedora7-xen-i386
When using --virt, koan will create new virtualized guests on a machine in accordance to the orders from cobbler. These can be Xen or QEMU/KVM guests depending on --virt-type. Once created, use ``virsh'' to control the guests. Virsh may need a connection string like ``virsh --connect qemu:///system''.
Example: koan --server=cobbler.example.org --virt --profile=fedora7-xen-i386
If --profile is specified, cobbler will default to naming domains based on their mac addresses; using --system will use the exact name given to the cobbler system object. To install using an alternate descriptive name, specify one with --virtname.
The additional parameters --virt-path, and --virt-type allow overriding certain defaults that are ordinarily defined by the remote cobbler server.
Optional advanced-configuration parameters for --virt:
(optional) Overrides the name of the virtual machine. This name must not conflict with other virtual machines running on the same system. If not specified, cobbler will provide reasonable defaults.
(optional) Specifies the storage for the virtual image, as a forced override over a storage location that might be set on the cobbler server. This path must be an absolute path of an existing directory in which to store the image, with an optional filename component.
Advanced usage: There is also support for specifying partitions such as ``/dev/sda4''. Volume Groups with available free space can also be used by specifying a group name such as ``VolGroup00''. Partitions should always start with /dev and Volume Groups should be represented by their names.
If you want to specify the location for more than one disk image, seperate the values with commas, such as ``/opt/foo/a,/opt/foo/b''.
(optional) Koan can install virtual guests for Xen (paravirtualized), or QEMU/KVM (paravirtualized or fully virtualized based on hardware support). Use --virt-type=``qemu'' or --virt-type=``xenpv'' to override the values already defined in cobbler. Since this parameter can be set in the cobbler profile, it's best to just set it there. See the cobbler manpage for more documentation.
qemu installs will select kvm, kqemu, or qemu, based on available hardware support.
When using '--replace-self', cobbler will reprovision the system, blowing away any current data and replacing it with the results of a network install. Specify a specific item from cobbler with --system or --profile, otherwise cobbler will try to see if there is a cobbler system record that matches a MAC address on the system.
This is useful to reinstall systems in conditions where ordinary PXE is not possible.
After using this feature, run ``/sbin/reboot'' to initiate the fully automatic reinstallation.
Example: koan --server=cobbler.example.org --profile=fedora7-xen-i386 --replace-self
Example: koan --server=cobbler.example.org --replace-self
Cobbler contains a templating feature that allows a single kickstart file to be customized on a per-system basis. See the cobbler manpage for more details.
If you have system specific customizations in your kickstarts and have cobbler system definitions defined server side for those systems, use --system and not --profile, to request the more specific per-system information from Cobbler.
Koan's source checkout (see http://cobbler.et.redhat.com) can be used to build a live CD for use with koan. This live CD serves the purpose of running --replace-self with no OS present -- bare metal installation. This tool may prove useful to emulate a PXE environment with a cobbler server, when no local DHCPconfiguration is not feasible or otherwise undesired.
To build a CD (on Fedora 7):
yum install livecd-tools
git clone git://et.redhat.com/koan
cd /checkout/koan
make
cd /checkout/koan/live
python build.py --server=cobbler.example.org --koan=``--profile=foo''
# OR (for auto-detection)
python build.py --server=cobbler.example.org --koan=``''
# burn the CD, and insert it in a bare metal machine
The koan live CD is in the early stages of development and may not support all direct attached storage. NOTE: Usage of the Live CD will erase all data on the first DASD disk during the course of provisioning.
The live CD should be very useful when used with the --server=DISCOVER switch.
The best tools to use after automatically installing a virt guest with koan are SSH (once installed and running), virsh, or virt-manager. If VNC graphics are available, virt-manager will allow access to the guest as if logged in directly to it. For Xen guests, ``virsh console <name>'' will also allow access to the guests. There is no QEMU console support at this time (use virt-manager with VNC or SSH).
Various additional commands are available through virsh. See the virsh manpage for details. Depending on virt type, start virsh with either just ``virsh'' (for Xen) or ``virsh --connect=qemu:///system'' (for QEMU).
Also see the cobbler manpage. It is both entertaining and educational.
Michael DeHaan <mdehaan@redhat.com>