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<$name>
 278
 279 The hostname.
 280
 281 =item C<$output>
 282
 283 The output file.
 284
 285 =item C<$size>
 286
 287 (Optionally) The output size (in bytes).  If not specified, then the
 288 template can choose a default size.
 289
 290 =item C<$timezone>
 291
 292 (Optionally) The timezone.
 293
 294 =back
 295
 296 =item disk-bus
 297
 298 The template MAY print the disk type supported by this guest.  Possible
 299 values include C<ide>, C<virtio>, C<virtio-scsi>.
 300
 301 =item minimum-memory
 302
 303 The template MAY print the minimum memory (RAM) required by this
 304 guest.  Abbreviations like C<1G> are supported.
 305
 306 =item minimum-size
 307
 308 The template MAY print the minimum disk space required by this guest.
 309 Abbreviations like C<10G> are supported.
 310
 311 =item network-model
 312
 313 The template MAY print the network type supported by this guest.
 314 Possible values include C<e1000>, C<virtio>.
 315
 316 =item probe
 317
 318 The template MUST print C<hello> followed by a newline, and then exit
 319 with code 0.
 320
 321 =item recommended-memory
 322
 323 The template MAY print the recommended amount of memory (RAM), used if
 324 the user does not select any other value.  Abbreviations like C<2G>
 325 are supported.
 326
 327 =item xml
 328
 329 The template MAY specify custom libvirt XML.  Usually you should
 330 I<not> specify this.  It is only used when you need very odd guest
 331 configuration (especially when emulating other architectures).
 332
 333 The following environment variables are passed to the template:
 334
 335 =over 4
 336
 337 =item C<$name>
 338
 339 The guest name.
 340
 341 =item C<$format>
 342
 343 The disk format (eg. C<qcow2>).
 344
 345 =item C<$output>
 346
 347 The disk file name.
 348
 349 =item C<$memory_kb>
 350
 351 The size of the RAM in kilobytes.
 352
 353 =item C<$vcpus>
 354
 355 The number of virtual CPUs.
 356
 357 =item C<$mac_addr>
 358
 359 The MAC address.
 360
 361 =back
 362
 363 =back
 364
 365 =head1 ENVIRONMENT VARIABLES
 366
 367 =over 4
 368
 369 =item C<MCLU_CONFIG>
 370
 371 May be used to override the default configuration file location
 372 (C</etc/mclu.conf>).  See L</CONFIGURATION FILE> above.
 373
 374 =item C<MCLU_PATH>
 375
 376 The path to the directory that contains template files.  See
 377 L</TEMPLATE FILES> above.
 378
 379 =back
 380
 381 =head1 FILES
 382
 383
 384
 385
 386 =head1 SEE ALSO
 387
 388 L<virt-builder(1)>,
 389 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 390
 391 =head1 AUTHORS
 392
 393 Richard W.M. Jones <rjones @ redhat . com>
 394
 395 =head1 COPYRIGHT
 396
 397 (C) Copyright 2014-2015 Red Hat Inc.
 398
 399 This program is free software; you can redistribute it and/or modify
 400 it under the terms of the GNU General Public License as published by
 401 the Free Software Foundation; either version 2 of the License, or
 402 (at your option) any later version.
 403
 404 This program is distributed in the hope that it will be useful,
 405 but WITHOUT ANY WARRANTY; without even the implied warranty of
 406 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 407 GNU General Public License for more details.
 408
 409 You should have received a copy of the GNU General Public License
 410 along with this program; if not, write to the Free Software
 411 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.