1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>NAME</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#the_cobbler_server">THE COBBLER SERVER</a></li>
<li><a href="#listing_available_resources">LISTING AVAILABLE RESOURCES</a></li>
<li><a href="#main_commands">MAIN COMMANDS</a></li>
<li><a href="#viewing_the_installation_data">VIEWING THE INSTALLATION DATA</a></li>
<li><a href="#virtualized_installs">VIRTUALIZED INSTALLS</a></li>
<li><a href="#reinstallation">REINSTALLATION</a></li>
<li><a href="#notes_for_users_of_cobbler_templating">NOTES FOR USERS OF COBBLER TEMPLATING</a></li>
<li><a href="#new_live_cd">NEW LIVE CD</a></li>
<li><a href="#post_installation_management_of_virt_guests">POST INSTALLATION MANAGEMENT OF VIRT GUESTS</a></li>
<li><a href="#additional">ADDITIONAL</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>koan --server=<host> [--list-profiles|--list-systems]</p>
<p>koan --server=<host> [--virt|--replace-self|--display] [--profile=<name>|--system=<name>] [--virt-name=<name>] [--virt-path=<path>] [--virt-type=<type>] [--virt-graphics]</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="the_cobbler_server">THE COBBLER SERVER</a></h1>
<dl>
<dt><strong><a name="item__2d_2dserver">--server</a></strong>
<dd>
<p>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.</p>
</dd>
<dd>
<p>This argument must be specified for all koan commands.</p>
</dd>
<dd>
<p>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.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="listing_available_resources">LISTING AVAILABLE RESOURCES</a></h1>
<p>Lists of the resources that can be installed from a remote server can be obtained by using the following commands:</p>
<dl>
<dt><strong><a name="item__2d_2dlist_2dprofiles">--list-profiles</a></strong>
<dd>
<p>Shows a list of profiles that can be remotely installed from the cobbler server.</p>
</dd>
</li>
<dt><strong><a name="item__2d_2dlist_2dsystems">--list-systems</a></strong>
<dd>
<p>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.</p>
</dd>
</li>
</dl>
<p>Example: koan --server=cobbler.example.org --list-systems</p>
<p>
</p>
<hr />
<h1><a name="main_commands">MAIN COMMANDS</a></h1>
<p>The commands --virt, --replace-self, and --display all take the following arguments:</p>
<dl>
<dt><strong><a name="item__2d_2dprofile">--profile</a></strong>
<dd>
<p>Names a profile, known to cobbler, that is to be installed.</p>
</dd>
</li>
<dt><strong><a name="item__2d_2dsystem">--system</a></strong>
<dd>
<p>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.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="viewing_the_installation_data">VIEWING THE INSTALLATION DATA</a></h1>
<p>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.</p>
<p>Example: koan --server=cobbler.example.org --display --profile=fedora7-xen-i386</p>
<p>
</p>
<hr />
<h1><a name="virtualized_installs">VIRTUALIZED INSTALLS</a></h1>
<p>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''.</p>
<p>Example: koan --server=cobbler.example.org --virt --profile=fedora7-xen-i386</p>
<p>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.</p>
<p>The additional parameters --virt-path, and --virt-type allow overriding certain defaults that are ordinarily defined by the remote cobbler server.</p>
<p>Optional advanced-configuration parameters for --virt:</p>
<dl>
<dt><strong><a name="item__2d_2dvirt_2dname">--virt-name</a></strong>
<dd>
<p>(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.</p>
</dd>
</li>
<dt><strong><a name="item__2d_2dvirt_2dpath">--virt-path</a></strong>
<dd>
<p>(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.</p>
</dd>
<dd>
<p>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.</p>
</dd>
<dd>
<p>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''.</p>
</dd>
</li>
<dt><strong><a name="item__2d_2dvirt_2dtype">--virt-type</a></strong>
<dd>
<p>(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.</p>
</dd>
<dd>
<p>qemu installs will select kvm, kqemu, or qemu, based on available hardware support.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="reinstallation">REINSTALLATION</a></h1>
<p>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.</p>
<p>This is useful to reinstall systems in conditions where ordinary PXE is not possible.</p>
<p>After using this feature, run ``/sbin/reboot'' to initiate the fully automatic reinstallation.</p>
<p>Example: koan --server=cobbler.example.org --profile=fedora7-xen-i386 --replace-self</p>
<p>Example: koan --server=cobbler.example.org --replace-self</p>
<p>
</p>
<hr />
<h1><a name="notes_for_users_of_cobbler_templating">NOTES FOR USERS OF COBBLER TEMPLATING</a></h1>
<p>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.</p>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="new_live_cd">NEW LIVE CD</a></h1>
<p>Koan's source checkout (see <a href="http://cobbler.et.redhat.com)">http://cobbler.et.redhat.com)</a> 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.</p>
<p>To build a CD (on Fedora 7):</p>
<p>yum install livecd-tools</p>
<p>git clone <a href="git://et.redhat.com/koan">git://et.redhat.com/koan</a></p>
<p>cd /checkout/koan</p>
<p>make</p>
<p>cd /checkout/koan/live</p>
<p>python build.py --server=cobbler.example.org --koan=``--profile=foo''</p>
<p># OR (for auto-detection)</p>
<p>python build.py --server=cobbler.example.org --koan=``''</p>
<p># burn the CD, and insert it in a bare metal machine</p>
<p>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.</p>
<p>The live CD should be very useful when used with the --server=DISCOVER
switch.</p>
<p>
</p>
<hr />
<h1><a name="post_installation_management_of_virt_guests">POST INSTALLATION MANAGEMENT OF VIRT GUESTS</a></h1>
<p>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).</p>
<p>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).</p>
<p>
</p>
<hr />
<h1><a name="additional">ADDITIONAL</a></h1>
<p>Also see the cobbler manpage. It is both entertaining and educational.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Michael DeHaan <<a href="mailto:mdehaan@redhat.com">mdehaan@redhat.com</a>></p>
</body>
</html>
|
