mclu.pod

   1 =head1 NAME
   2
   3  mclu - Mini Cloud, a tiny, sane cloud
   4
   5 =head1 SUMMARY
   6
   7 mclu [-f mclu.conf] [--options] [list|status|boot|...] [...]
   8
   9 mclu --help
  10
  11 =head1 DESCRIPTION
  12
  13 C<mclu> (Mini Cloud, previously Mini Cluster) is probably the simplest
  14 cloud management software possible.
  15
  16 Cloud management doesn't require a daemon running on each node.  We
  17 already have L<sshd(8)> for secure access, and L<libvirtd(8)> to
  18 manage the state of the guests.  On most Linux systems, those are
  19 running out of the box.  That is sufficient to manage all the state we
  20 care about.  C<mclu> just goes out and queries each node for that
  21 information when it needs it (in parallel of course).  Nodes that are
  22 switched off are handled by ignoring them.
  23
  24 For a small cloud, we can throw out features that aren't needed:
  25 multi-user/multi-tenant, failover, VLANs, a GUI.
  26
  27 C<mclu> is essentially the smallest sensible interface to parallel
  28 libvirt over ssh.  There are some extra features, such as the ability
  29 to boot VMs from templates, but those are kept as minimal as possible.
  30
  31 C<mclu> is good for small clouds from 2 - 10 Linux nodes, that are
  32 managed by a single user, where everything is located at a single
  33 location on a single network, where you are happy to hack on small
  34 shell scripts and manage everything from the command line.
  35
  36 =head2 EXAMPLES
  37
  38 Examine the state of the nodes (one node is switched on, three nodes
  39 are off):
  40
  41  $ mclu status
  42  ham0                   on
  43                           total: 8pcpus 30.9G
  44                            free: 29.9G
  45  ham1                   off
  46  ham2                   off
  47  ham3                   off
  48
  49 Bring up another node (using wake-on-LAN):
  50
  51  $ mclu on ham1
  52  Waking up 74:d4:35:51:ab:86...
  53
  54 Start a new instance on node C<ham1>, based on the C<rawhide> guest
  55 template, with up to 20G of disk space:
  56
  57  $ mclu boot rawhide ham1:test --size 20G
  58
  59 Connect to the graphical console of the new guest:
  60
  61  $ mclu viewer test
  62
  63 If your local DHCP server and DNS are connected then you can probably
  64 connect to the new instance by doing:
  65
  66  $ ssh test
  67
  68 =head1 GLOBAL OPTIONS
  69
  70 =over 4
  71
  72 =item B<--help>
  73
  74 Display brief help message and exit.
  75
  76 =item B<-f mclu.conf>
  77
  78 =item B<--config-file mclu.conf>
  79
  80 Specify the path to the configuration file.  If this command option is
  81 I<not> given, then the environment variable C<MCLU_CONFIG> is used,
  82 and if that environment variable is not set then C</etc/mclu.conf> is
  83 used.
  84
  85 See also: L</CONFIGURATION FILE> below.
  86
  87 =item B<-v>
  88
  89 =item B<--verbose>
  90
  91 Enable verbose / debugging messages.
  92
  93 =item B<-V>
  94
  95 =item B<--version>
  96
  97 Display version number and exit.
  98
  99 =back
 100
 101 =head1 SUBCOMMANDS
 102
 103 =over 4
 104
 105 =item B<mclu boot template [host:]name [--memory ..] [--vcpus ..]>
 106
 107 Boot (create) a new instance from B<template>.  It will be started on
 108 B<host> and named B<name>.  If the C<host:> prefix is not given then
 109 it is started on the first host that has sufficient free memory.
 110
 111 The instance is created by running the template script.  You can
 112 control resources using the following options:
 113
 114 =over 4
 115
 116 =item B<--console>
 117
 118 Open the serial console immediately after booting the guest.  This is
 119 the same as using the C<mclu console> subcommand, but quicker.
 120
 121 =item B<--memory nnG>
 122
 123 Specify the amount of memory (RAM) to give this guest.  You can use
 124 a number followed by a unit, eg. C<--memory 4G>
 125
 126 =item B<--size nnG>
 127
 128 Specify the amount of disk space to give this guest.  You can use
 129 a number followed by a unit, eg. C<--size 20G>
 130
 131 =item B<--timezone TZ>
 132
 133 Specify the timezone, eg. C<--timezone Europe/London>
 134
 135 =item B<--vcpus N>
 136
 137 Specify the number of virtual CPUs to give to the guest.  The default
 138 is the number of physical CPUs, but not more than 4.
 139
 140 =item B<--viewer>
 141
 142 Open the graphical console immediately after booting the guest.  This is
 143 the same as using the C<mclu viewer> subcommand, but quicker.
 144
 145 =back
 146
 147 =item B<mclu console [host:]guest>
 148
 149 Connect to the serial console console of the named guest.
 150
 151 =item B<mclu destroy [host:]guest>
 152
 153 Destroy the named guest.
 154
 155 Note this permanently deletes the guest and its data.
 156
 157 =item B<mclu list [--active] [--all] [--templates]>
 158
 159 List all active (running) guests and/or templates.  You can use
 160 the following options:
 161
 162 =over 4
 163
 164 =item B<--active>
 165
 166 List only active (running) guests.
 167
 168 =item B<--all>
 169
 170 List active (running) guests, and templates.  This is the default.
 171
 172 =item B<--templates>
 173
 174 List only templates.
 175
 176 =back
 177
 178 =item B<mclu off node|wildcard ...>
 179
 180 Switch the node(s) off.  Wildcards can be used in place of hostnames.
 181
 182 mclu checks that no guests are running on the nodes.  Migrate or shut
 183 down the guests first.
 184
 185 =item B<mclu on node|wildcard ...>
 186
 187 Switch the node(s) on.  Wildcards can be used in place of hostnames.
 188
 189 This requires Wake-on-LAN support, both on the target host and in the
 190 mclu configuration.  mclu must have been compiled with the L<wol(1)>
 191 client installed, and the C<mclu.conf> file must list a MAC address
 192 for each host:
 193
 194  [nodes]
 195  host0 mac=11:22:33:44:55:66
 196  host1 mac=11:22:33:44:55:67
 197
 198 =item B<mclu reboot [host:]guest>
 199
 200 Reboot the guest.
 201
 202 =item B<mclu status>
 203
 204 Display the status of the cloud.  This shows you which nodes are on
 205 and off, and the amount of resources used and free on each node.
 206
 207 =item B<mclu viewer [host:]guest>
 208
 209 Open the graphical console of the guest (using L<virt-viewer(1)>).
 210
 211 =back
 212
 213
 214 =head1 CONFIGURATION FILE
 215
 216
 217
 218
 219
 220 =head1 TEMPLATE FILES
 221
 222 Template files are shell scripts which the C<mclu> program calls to
 223 perform various operations.
 224
 225 Template files must have the extension C<.template>, must be
 226 executable (C<chmod +x *.template>), and they must live in the
 227 template directory (usually found through the C<$MCLU_PATH>
 228 environment variable).
 229
 230 Several template files are supplied with mclu sources, and it's a good
 231 idea to consult those for examples and when creating your own
 232 templates.
 233
 234 C<mclu> runs the template with a single parameter in order to "query"
 235 the template.  All templates must support the C<probe> parameter,
 236 which is used to test that the file is a template:
 237
 238  $ ./templates/rawhide.template probe
 239  hello
 240
 241 Templates should exit with code 2 if they don't know about a parameter:
 242
 243  $ ./templates/rawhide.template unknown
 244  $ echo $?
 245  2
 246
 247 The current parameters are:
 248
 249 =over 4
 250
 251 =item base-image
 252
 253 The template MUST print the name of the image that it builds.  The
 254 meaning of this generally follows the conventions of
 255 L<virt-builder(1)>, if virt-builder is used by the template.
 256
 257 =item build
 258
 259 The template MUST build a disk image.  Because the C<template build>
 260 command could run on any node in the cluster, it won't necessarily
 261 have access to other local files on the same node that C<mclu> is
 262 running on.
 263
 264 The following environment variables are passed to the template:
 265
 266 =over 4
 267
 268 =item C<$base_image>
 269
 270 The name of the base image.  This is the output of the C<base-image>
 271 probe.
 272
 273 =item C<$format>
 274
 275 The output format (eg. C<qcow2>).
 276
 277 =item C<$guest_arch>
 278
 279 The guest architecture (eg. "x86_64").  This is the output of the
 280 C<guest-arch> probe.  If the template doesn't provide that, it
 281 defaults to the cluster node's host architecture.
 282
 283 =item C<$name>
 284
 285 The hostname.
 286
 287 =item C<$output>
 288
 289 The output file.
 290
 291 =item C<$size>
 292
 293 (Optionally) The output size (in bytes).  If not specified, then the
 294 template can choose a default size.
 295
 296 =item C<$timezone>
 297
 298 (Optionally) The timezone.
 299
 300 =back
 301
 302 =item cmdline
 303
 304 The template MAY print a kernel command line.  This is used to boot
 305 the guest, but only when C<needs-external-kernel> is set (see below).
 306
 307 =item disk-bus
 308
 309 The template MAY print the disk type supported by this guest.  Possible
 310 values include C<ide>, C<virtio>, C<virtio-scsi>.
 311
 312 =item guest-arch
 313
 314 The template MAY print the guest architecture.
 315
 316 If supplied, this acts as a hint when generating the XML in the C<mclu
 317 boot> subcommand.  The default is to assume the guest architecture is
 318 the same as the cluster host on which the guest runs.
 319
 320 =item minimum-memory
 321
 322 The template MAY print the minimum memory (RAM) required by this
 323 guest.  Abbreviations like C<1G> are supported.
 324
 325 =item minimum-size
 326
 327 The template MAY print the minimum disk space required by this guest.
 328 Abbreviations like C<10G> are supported.
 329
 330 =item needs-external-kernel
 331
 332 The template MAY print C<yes> or C<1>.  If it does so then after the
 333 guest has been built, L<virt-get-kernel(1)> is run to extract the
 334 kernel and initrd from the guest, and these are used to boot the guest
 335 with an external kernel and initrd (ie. using the libvirt
 336 C<E<lt>kernelE<gt>> and C<E<lt>initrdE<gt>> directives).
 337
 338 =item network-model
 339
 340 The template MAY print the network type supported by this guest.
 341 Possible values include C<e1000>, C<virtio>.
 342
 343 =item probe
 344
 345 The template MUST print C<hello> followed by a newline, and then exit
 346 with code 0.
 347
 348 =item recommended-memory
 349
 350 The template MAY print the recommended amount of memory (RAM), used if
 351 the user does not select any other value.  Abbreviations like C<2G>
 352 are supported.
 353
 354 =item xml
 355
 356 The template MAY specify custom libvirt XML.  Usually you should
 357 I<not> specify this.  It is only used when you need very odd guest
 358 configuration (especially when emulating other architectures).
 359
 360 The following environment variables are passed to the template:
 361
 362 =over 4
 363
 364 =item C<$name>
 365
 366 The guest name.
 367
 368 =item C<$format>
 369
 370 The disk format (eg. C<qcow2>).
 371
 372 =item C<$output>
 373
 374 The disk file name.
 375
 376 =item C<$memory_kb>
 377
 378 The size of the RAM in kilobytes.
 379
 380 =item C<$vcpus>
 381
 382 The number of virtual CPUs.
 383
 384 =item C<$mac_addr>
 385
 386 The MAC address.
 387
 388 =back
 389
 390 =back
 391
 392 =head1 ENVIRONMENT VARIABLES
 393
 394 =over 4
 395
 396 =item C<MCLU_CONFIG>
 397
 398 May be used to override the default configuration file location
 399 (C</etc/mclu.conf>).  See L</CONFIGURATION FILE> above.
 400
 401 =item C<MCLU_PATH>
 402
 403 The path to the directory that contains template files.  See
 404 L</TEMPLATE FILES> above.
 405
 406 =back
 407
 408 =head1 FILES
 409
 410
 411
 412
 413 =head1 SEE ALSO
 414
 415 L<virt-builder(1)>,
 416 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 417
 418 =head1 AUTHORS
 419
 420 Richard W.M. Jones <rjones @ redhat . com>
 421
 422 =head1 COPYRIGHT
 423
 424 (C) Copyright 2014-2016 Red Hat Inc.
 425
 426 This program is free software; you can redistribute it and/or modify
 427 it under the terms of the GNU General Public License as published by
 428 the Free Software Foundation; either version 2 of the License, or
 429 (at your option) any later version.
 430
 431 This program is distributed in the hope that it will be useful,
 432 but WITHOUT ANY WARRANTY; without even the implied warranty of
 433 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 434 GNU General Public License for more details.
 435
 436 You should have received a copy of the GNU General Public License
 437 along with this program; if not, write to the Free Software
 438 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.