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 te 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 disk-bus
 303
 304 The template MAY print the disk type supported by this guest.  Possible
 305 values include C<ide>, C<virtio>, C<virtio-scsi>.
 306
 307 =item guest-arch
 308
 309 The template MAY print the guest architecture.
 310
 311 If supplied, this acts as a hint when generating the XML in the C<mclu
 312 boot> subcommand.  The default is to assume the guest architecture is
 313 the same as the cluster host on which the guest runs.
 314
 315 =item minimum-memory
 316
 317 The template MAY print the minimum memory (RAM) required by this
 318 guest.  Abbreviations like C<1G> are supported.
 319
 320 =item minimum-size
 321
 322 The template MAY print the minimum disk space required by this guest.
 323 Abbreviations like C<10G> are supported.
 324
 325 =item needs-external-kernel
 326
 327 The template MAY print C<yes> or C<1>.  If it does so then after the
 328 guest has been built, L<virt-get-kernel(1)> is run to extract the
 329 kernel and initrd from the guest, and these are used to boot the guest
 330 with an external kernel and initrd (ie. using the libvirt
 331 C<E<lt>kernelE<gt>> and C<E<lt>initrdE<gt>> directives).
 332
 333 =item network-model
 334
 335 The template MAY print the network type supported by this guest.
 336 Possible values include C<e1000>, C<virtio>.
 337
 338 =item probe
 339
 340 The template MUST print C<hello> followed by a newline, and then exit
 341 with code 0.
 342
 343 =item recommended-memory
 344
 345 The template MAY print the recommended amount of memory (RAM), used if
 346 the user does not select any other value.  Abbreviations like C<2G>
 347 are supported.
 348
 349 =item xml
 350
 351 The template MAY specify custom libvirt XML.  Usually you should
 352 I<not> specify this.  It is only used when you need very odd guest
 353 configuration (especially when emulating other architectures).
 354
 355 The following environment variables are passed to the template:
 356
 357 =over 4
 358
 359 =item C<$name>
 360
 361 The guest name.
 362
 363 =item C<$format>
 364
 365 The disk format (eg. C<qcow2>).
 366
 367 =item C<$output>
 368
 369 The disk file name.
 370
 371 =item C<$memory_kb>
 372
 373 The size of the RAM in kilobytes.
 374
 375 =item C<$vcpus>
 376
 377 The number of virtual CPUs.
 378
 379 =item C<$mac_addr>
 380
 381 The MAC address.
 382
 383 =back
 384
 385 =back
 386
 387 =head1 ENVIRONMENT VARIABLES
 388
 389 =over 4
 390
 391 =item C<MCLU_CONFIG>
 392
 393 May be used to override the default configuration file location
 394 (C</etc/mclu.conf>).  See L</CONFIGURATION FILE> above.
 395
 396 =item C<MCLU_PATH>
 397
 398 The path to the directory that contains template files.  See
 399 L</TEMPLATE FILES> above.
 400
 401 =back
 402
 403 =head1 FILES
 404
 405
 406
 407
 408 =head1 SEE ALSO
 409
 410 L<virt-builder(1)>,
 411 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 412
 413 =head1 AUTHORS
 414
 415 Richard W.M. Jones <rjones @ redhat . com>
 416
 417 =head1 COPYRIGHT
 418
 419 (C) Copyright 2014-2015 Red Hat Inc.
 420
 421 This program is free software; you can redistribute it and/or modify
 422 it under the terms of the GNU General Public License as published by
 423 the Free Software Foundation; either version 2 of the License, or
 424 (at your option) any later version.
 425
 426 This program is distributed in the hope that it will be useful,
 427 but WITHOUT ANY WARRANTY; without even the implied warranty of
 428 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 429 GNU General Public License for more details.
 430
 431 You should have received a copy of the GNU General Public License
 432 along with this program; if not, write to the Free Software
 433 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.