1KOAN(1) koan KOAN(1)
2
6 koan stands for "kickstart-over-a-network" and allows for both network
7 provisioning of new virtualized guests (Xen, QEMU/KVM, VMware) and
8 re-installation of an existing system. koan is a client side applica‐
9 tion used with a Cobbler installation server.
10
12 koan --server=<host> [--list-profiles⎪--list-systems]
13 koan --server=<host> [--virt⎪--replace-self⎪--display] [--pro‐
15 file=<name>⎪--system=<name>] [--add-reinstall-entry]
16 [--virt-name=<name>] [--virt-path=<path>] [--virt-type=<type>]
17 [--nogfx]
18
20 When invoked, koan requests install information from a remote cobbler
21 boot server. What koan does with the cobbler data depends on whether
22 it was invoked with --virt or --replace-self.
23
25 --server
26 Indicates the hostname of the Cobbler boot server to be contacted.
27 Successful communication requires that no firewalls are blocking
28 the cobbler XMLRPC port, which is usually 25151, and that "cob‐
29 blerd" and Apache is running on the cobbler server.
30 This argument must be specified for all koan commands.
32 Specifying "DISCOVER" for the server in all caps will request auto‐
34 matic discovery of a nearby cobbler server using Avahi. The avahi-
35 tools package must be installed to use this functionality.
36
38 Lists of the resources that can be installed from a remote server can
39 be obtained by using the following commands:
40 --list-profiles
42 Shows a list of profiles that can be remotely installed from the
43 cobbler server.
44 --list-systems
46 Shows a list of systems that can be remotely installed from the
47 cobbler server. Systems contain the same information as profiles
48 but may be further customized in terms of parameters or kickstart
49 information. The level of customization varies depending on what
50 has been specified on the cobbler server.
51 Example: koan --server=cobbler.example.org --list-systems
53
55 The commands --virt, --replace-self, and --display all take the follow‐
56 ing arguments:
57 --profile
59 Names a profile, known to cobbler, that is to be installed.
60 --system
62 Names a system, known to cobbler, that is to be installed. --sys‐
63 tem cannot be used at the same time as --profile; pick one or the
64 other.
65
67 Koan can provide some in depth data about profile and system records in
68 Cobbler before installing them.
69 Example: koan --server=cobbler.example.org --display --pro‐
71 file=fedora9-xen-i386
72
74 When using --virt, koan will create new virtualized guests on a machine
75 in accordance to the orders from cobbler. These can be Xen, qemu/KVM,
76 or VMware guests depending on --virt-type. Once created, use "virsh"
77 to control the guests. Virsh may need a connection string like "virsh
78 --connect qemu:///system".
79 Example: koan --server=cobbler.example.org --virt --pro‐
81 file=fedora9-xen-i386
82 If --profile is specified, cobbler will default to naming domains based
84 on their mac addresses; using --system will use the exact name given to
85 the cobbler system object. To install using an alternate descriptive
86 name, specify one with --virtname.
87 The additional parameters --virt-path, and --virt-type allow overriding
89 certain defaults that are ordinarily defined by the remote cobbler
90 server.
91 Optional advanced-configuration parameters for --virt:
93 --virt-bridge
95 Specifies the virtualized bridge to use, instead of the one as
96 defined in cobbler. For profiles, this must be a single bridge.
97 For system records that define multiple interfaces, multiple bridge
98 names can be seperated with commas.
99 --virt-name
101 Specifies the name of the virtual machine/image to create.
102 --virt-path
104 Specifies the storage location for the virtual image, as a override
105 of the default storage location that might be set on the cobbler
106 server.
107 To specify a file on the filesystem, this parameter must be an
109 absolute path of an existing directory, with an optional filename
110 component. An example is "/opt/myimages".
111 To specify a partition, specify it with device file, such as
113 "/dev/sda4". You can also specify an empty LVM volume group with a
114 syntax such as "VolGroup00" and koan will carve out space based on
115 the name of the guest.
116 To specify multiple disks, seperate the values with commas, such as
118 "/opt/foo/a,/opt/foo/b".
119 --virt-type
121 Koan can install virtual guests for Xen, qemu/KVM, and VMware.
122 Usage of this parameter overrides the virt type that is specified
123 in Cobbler, which may be set to "auto" or a specific preferred vir‐
124 tualization type that can vary based on the Cobbler profile or sys‐
125 tem record.
126 Valid types are "xenpv", "xenfv", "qemu" and "vmware". "xenfv" and
128 "vmware" types require PXE infrastructure. For KVM, pick the virt
129 type "qemu". VMware support is experimental.
130 --nogfx
132 This option prevents Xen based installs from establishing a VNC
133 based display, so that the machine can accessed by xm/virsh con‐
134 soles on the command line. For qemu/KVM, VNC cannot be disabled as
135 there is no text based console.
136
138 Installing virtual machines is only one feature of Koan, it can also be
139 used to help in reinstalling running Linux systems.
140 When using '--replace-self', cobbler will install a new entry in the
142 grub or lilo configuration of the system, so that the next time it
143 reboots, it will immediately reinstall itself as defined to the speci‐
144 fications set by cobbler. Specify a specific item from cobbler with
145 --system or --profile, otherwise cobbler will try to see if there is a
146 cobbler system record that matches a MAC address on the system.
147 This is useful to reinstall systems in conditions where ordinary PXE is
149 not possible. (Another alternative to this is the cobbler "buildiso"
150 command).
151 After using this feature, reboot to initiate reinstallation.
153 Example: koan --server=cobbler.example.org --profile=fedora7-xen-i386
155 --replace-self
156 Example: koan --server=cobbler.example.org --replace-self
158 If you want to just add an entry to grub but not make it the default,
160 add the additional argument "--add-reinstall-entry" to the command
161 line. Only one reinstall entry can be added to grub; re-running this
162 command will replace the previous entry.
163
165 While it is expected that nearly all users will want to use a cobbler
166 server, the functionality of --replace-self can still be used in koan
167 without contacting a cobbler server. This may be useful if you want to
168 use koan with some existing infrastructure and can't yet upgrade that
169 infrastructure to use cobbler.
170 Example: koan --no-cobbler=http://somewebserver/ks.cfg --replace-self
172 Note that none of the other koan options work in this mode.
174
176 Also see the cobbler manpage. It is both entertaining and educational.
177
179 Michael DeHaan <mdehaan@redhat.com>
180 2008-05-14 KOAN(1)