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
  14
  15
  16
  17
  18 =head1 GLOBAL OPTIONS
  19
  20 =over 4
  21
  22 =item B<--help>
  23
  24 Display brief help message and exit.
  25
  26 =item B<-f mclu.conf>
  27
  28 =item B<--config-file mclu.conf>
  29
  30 Specify the path to the configuration file.  If this command option is
  31 I<not> given, then the environment variable C<MCLU_CONFIG> is used,
  32 and if that environment variable is not set then C</etc/mclu.conf> is
  33 used.
  34
  35 See also: L</CONFIGURATION FILE> below.
  36
  37 =item B<-v>
  38
  39 =item B<--verbose>
  40
  41 Enable verbose / debugging messages.
  42
  43 =item B<-V>
  44
  45 =item B<--version>
  46
  47 Display version number and exit.
  48
  49 =back
  50
  51 =head1 SUBCOMMANDS
  52
  53 =over 4
  54
  55 =item B<mclu boot template [host:]name [--memory ..] [--vcpus ..]>
  56
  57 Boot (create) a new instance from B<template>.  It will be started on
  58 B<host> and named B<name>.  If the C<host:> prefix is not given then
  59 it is started on the first host that has sufficient free memory.
  60
  61 The instance is created by running the template script.  You can
  62 control resources using the following options:
  63
  64 =over 4
  65
  66 =item B<--console>
  67
  68 Open the serial console immediately after booting the guest.  This is
  69 the same as using the C<mclu console> subcommand, but quicker.
  70
  71 =item B<--memory nnG>
  72
  73 Specify the amount of memory (RAM) to give this guest.  You can use
  74 a number followed by a unit, eg. C<--memory 4G>
  75
  76 =item B<--size nnG>
  77
  78 Specify the amount of disk space to give this guest.  You can use
  79 a number followed by a unit, eg. C<--size 20G>
  80
  81 =item B<--timezone TZ>
  82
  83 Specify the timezone, eg. C<--timezone Europe/London>
  84
  85 =item B<--vcpus N>
  86
  87 Specify the number of virtual CPUs to give to the guest.  The default
  88 is the number of physical CPUs, but not more than 4.
  89
  90 =item B<--viewer>
  91
  92 Open the graphical console immediately after booting the guest.  This is
  93 the same as using the C<mclu viewer> subcommand, but quicker.
  94
  95 =back
  96
  97 =item B<mclu console [host:]guest>
  98
  99 Connect to the serial console console of the named guest.
 100
 101 =item B<mclu destroy [host:]guest>
 102
 103 Destroy the named guest.
 104
 105 Note this permanently deletes the guest and its data.
 106
 107 =item B<mclu list [--active] [--all] [--templates]>
 108
 109 List all active (running) guests and/or templates.  You can use
 110 the following options:
 111
 112 =over 4
 113
 114 =item B<--active>
 115
 116 List only active (running) guests.
 117
 118 =item B<--all>
 119
 120 List active (running) guests, and templates.  This is the default.
 121
 122 =item B<--templates>
 123
 124 List only templates.
 125
 126 =back
 127
 128 =item B<mclu off node|wildcard ...>
 129
 130 Switch the node(s) off.  Wildcards can be used in place of hostnames.
 131
 132 mclu checks that no guests are running on the nodes.  Migrate or shut
 133 down the guests first.
 134
 135 =item B<mclu on node|wildcard ...>
 136
 137 Switch the node(s) on.  Wildcards can be used in place of hostnames.
 138
 139 This requires Wake-on-LAN support, both on the target host and in the
 140 mclu configuration.  mclu must have been compiled with the L<wol(1)>
 141 client installed, and the C<mclu.conf> file must list a MAC address
 142 for each host:
 143
 144  [nodes]
 145  host0 mac=11:22:33:44:55:66
 146  host1 mac=11:22:33:44:55:67
 147
 148 =item B<mclu reboot [host:]guest>
 149
 150 Reboot the guest.
 151
 152 =item B<mclu status>
 153
 154 Display the status of the cloud.  This shows you which nodes are on
 155 and off, and the amount of resources used and free on each node.
 156
 157 =item B<mclu viewer [host:]guest>
 158
 159 Open the graphical console of the guest (using L<virt-viewer(1)>).
 160
 161 =back
 162
 163
 164 =head1 CONFIGURATION FILE
 165
 166
 167
 168
 169
 170 =head1 TEMPLATE FILES
 171
 172 Template files are shell scripts which the C<mclu> program calls to
 173 perform various operations.
 174
 175 Template files must have the extension C<.template>, must be
 176 executable (C<chmod +x *.template>), and they must live in the
 177 template directory (usually found through the C<$MCLU_PATH>
 178 environment variable).
 179
 180 Several template files are supplied with mclu sources, and it's a good
 181 idea to consult those for examples and when creating your own
 182 templates.
 183
 184 C<mclu> runs the template with a single parameter in order to "query"
 185 the template.  All templates must support the C<probe> parameter,
 186 which is used to test that the file is a template:
 187
 188  $ ./templates/rawhide.template probe
 189  hello
 190
 191 Templates should exit with code 2 if they don't know about a parameter:
 192
 193  $ ./templates/rawhide.template unknown
 194  $ echo $?
 195  2
 196
 197 The current parameters are:
 198
 199 =over 4
 200
 201 =item base-image
 202
 203 The template MUST print the name of the image that it builds.  The
 204 meaning of this generally follows the conventions of
 205 L<virt-builder(1)>, if virt-builder is used by the template.
 206
 207 =item build
 208
 209 The template MUST build a disk image.  Because the C<template build>
 210 command could run on any node in the cluster, it won't necessarily
 211 have access to other local files on the same node that C<mclu> is
 212 running on.
 213
 214 The following environment variables are passed to the template:
 215
 216 =over 4
 217
 218 =item C<$base_image>
 219
 220 The name of the base image.  This is the output of the C<base-image>
 221 probe.
 222
 223 =item C<$format>
 224
 225 The output format (eg. C<qcow2>).
 226
 227 =item C<$name>
 228
 229 The hostname.
 230
 231 =item C<$output>
 232
 233 The output file.
 234
 235 =item C<$size>
 236
 237 (Optionally) The output size (in bytes).  If not specified, then the
 238 template can choose a default size.
 239
 240 =item C<$timezone>
 241
 242 (Optionally) The timezone.
 243
 244 =back
 245
 246 =item disk-bus
 247
 248 The template MAY print the disk type supported by this guest.  Possible
 249 values include C<ide>, C<virtio>, C<virtio-scsi>.
 250
 251 =item minimum-memory
 252
 253 The template MAY print the minimum memory (RAM) required by this
 254 guest.  Abbreviations like C<1G> are supported.
 255
 256 =item minimum-size
 257
 258 The template MAY print the minimum disk space required by this guest.
 259 Abbreviations like C<10G> are supported.
 260
 261 =item network-model
 262
 263 The template MAY print the network type supported by this guest.
 264 Possible values include C<e1000>, C<virtio>.
 265
 266 =item probe
 267
 268 The template MUST print C<hello> followed by a newline, and then exit
 269 with code 0.
 270
 271 =item recommended-memory
 272
 273 The template MAY print the recommended amount of memory (RAM), used if
 274 the user does not select any other value.  Abbreviations like C<2G>
 275 are supported.
 276
 277 =back
 278
 279 =head1 ENVIRONMENT VARIABLES
 280
 281 =over 4
 282
 283 =item C<MCLU_CONFIG>
 284
 285 May be used to override the default configuration file location
 286 (C</etc/mclu.conf>).  See L</CONFIGURATION FILE> above.
 287
 288 =item C<MCLU_PATH>
 289
 290 The path to the directory that contains template files.  See
 291 L</TEMPLATE FILES> above.
 292
 293 =back
 294
 295 =head1 FILES
 296
 297
 298
 299
 300 =head1 SEE ALSO
 301
 302 L<virt-builder(1)>,
 303 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
 304
 305 =head1 AUTHORS
 306
 307 Richard W.M. Jones <rjones @ redhat . com>
 308
 309 =head1 COPYRIGHT
 310
 311 (C) Copyright 2014-2015 Red Hat Inc.
 312
 313 This program is free software; you can redistribute it and/or modify
 314 it under the terms of the GNU General Public License as published by
 315 the Free Software Foundation; either version 2 of the License, or
 316 (at your option) any later version.
 317
 318 This program is distributed in the hope that it will be useful,
 319 but WITHOUT ANY WARRANTY; without even the implied warranty of
 320 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 321 GNU General Public License for more details.
 322
 323 You should have received a copy of the GNU General Public License
 324 along with this program; if not, write to the Free Software
 325 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.