guestfish.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 guestfish - the libguestfs filesystem interactive shell
   6
   7 =head1 SYNOPSIS
   8
   9  guestfish [--options] [commands]
  10
  11  guestfish -i libvirt-domain
  12
  13  guestfish -i disk-image(s)
  14
  15 =head1 EXAMPLES
  16
  17 =head2 From shell scripts
  18
  19 Create a new C</etc/motd> file in a guest:
  20
  21  guestfish <<_EOF_
  22  add disk.img
  23  run
  24  mount /dev/VolGroup00/LogVol00 /
  25  write_file /etc/motd "Hello users" 0
  26  _EOF_
  27
  28 List the LVs in a guest:
  29
  30  guestfish <<_EOF_
  31  add disk.img
  32  run
  33  lvs
  34  _EOF_
  35
  36 =head2 On the command line
  37
  38 List the LVM PVs in a guest image:
  39
  40  guestfish add disk.img : run : pvs
  41
  42 Remove C</boot/grub/menu.lst> (in reality not such a great idea):
  43
  44  guestfish --add disk.img \
  45    --mount /dev/VolGroup00/LogVol00 \
  46    --mount /dev/sda1:/boot \
  47    rm /boot/grub/menu.lst
  48
  49 =head2 As an interactive shell
  50
  51  $ guestfish
  52
  53  Welcome to guestfish, the libguestfs filesystem interactive shell for
  54  editing virtual machine filesystems.
  55
  56  Type: 'help' for help with commands
  57        'quit' to quit the shell
  58
  59  ><fs> help
  60
  61 =head2 As a script interpreter
  62
  63  #!/usr/bin/guestfish -f
  64  alloc /tmp/output.img 10M
  65  run
  66  sfdisk /dev/sda 0 0 0 ,
  67  mkfs ext2 /dev/sda1
  68
  69 =head1 DESCRIPTION
  70
  71 Guestfish is a shell and command-line tool for examining and modifying
  72 virtual machine filesystems.  It uses libguestfs and exposes all of
  73 the functionality of the guestfs API, see L<guestfs(3)>.
  74
  75 =head1 OPTIONS
  76
  77 =over 4
  78
  79 =item B<--help>
  80
  81 Displays general help on options.
  82
  83 =item B<-h> | B<--cmd-help>
  84
  85 Lists all available guestfish commands.
  86
  87 =item B<-h cmd> | B<--cmd-help cmd>
  88
  89 Displays detailed help on a single command C<cmd>.
  90
  91 =item B<-a image> | B<--add image>
  92
  93 Add a block device or virtual machine image to the shell.
  94
  95 =item B<-f file> | B<--file file>
  96
  97 Read commands from C<file>.  To write pure guestfish
  98 scripts, use:
  99
 100  #!/usr/bin/guestfish -f
 101
 102 =item B<-i> | B<--inspector>
 103
 104 Run virt-inspector on the named libvirt domain or list of disk
 105 images.  If virt-inspector is available and if it can identify
 106 the domain or disk images, then partitions will be mounted
 107 correctly at start-up.
 108
 109 Typical usage is either:
 110
 111  guestfish -i myguest
 112
 113 (for an inactive libvirt domain called I<myguest>), or:
 114
 115  guestfish --ro -i myguest
 116
 117 (for active domains, readonly), or specify the block device directly:
 118
 119  guestfish -i /dev/Guests/MyGuest
 120
 121 You cannot use I<-a> or I<-m> in conjunction with this option, and
 122 options other than I<--ro> might not behave correctly.
 123
 124 See also: L<virt-inspector(1)>.
 125
 126 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
 127
 128 Mount the named partition or logical volume on the given mountpoint.
 129
 130 If the mountpoint is omitted, it defaults to C</>.
 131
 132 You have to mount something on C</> before most commands will work.
 133
 134 If any C<-m> or C<--mount> options are given, the guest is
 135 automatically launched.
 136
 137 =item B<-n> | B<--no-sync>
 138
 139 Disable autosync.  This is enabled by default.  See the discussion
 140 of autosync in the L<guestfs(3)> manpage.
 141
 142 =item B<-r> | B<--ro>
 143
 144 This changes the C<-m> option so that mounts are done read-only
 145 (see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
 146
 147 =item B<-v> | B<--verbose>
 148
 149 Enable very verbose messages.  This is particularly useful if you find
 150 a bug.
 151
 152 =item B<-D> | B<--no-dest-paths>
 153
 154 Don't tab-complete paths on the guest filesystem.  It is useful to be
 155 able to hit the tab key to complete paths on the guest filesystem, but
 156 this causes extra "hidden" guestfs calls to be made, so this option is
 157 here to allow this feature to be disabled.
 158
 159 =item B<-V> | B<--version>
 160
 161 Display the guestfish / libguestfs version number and exit.
 162
 163 =back
 164
 165 =head1 COMMANDS ON COMMAND LINE
 166
 167 Any additional (non-option) arguments are treated as commands to
 168 execute.
 169
 170 Commands to execute should be separated by a colon (C<:>), where the
 171 colon is a separate parameter.  Thus:
 172
 173  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
 174
 175 If there are no additional arguments, then we enter a shell, either an
 176 interactive shell with a prompt (if the input is a terminal) or a
 177 non-interactive shell.
 178
 179 In either command line mode or non-interactive shell, the first
 180 command that gives an error causes the whole shell to exit.  In
 181 interactive mode (with a prompt) if a command fails, you can continue
 182 to enter commands.
 183
 184 =head1 USING launch (OR run)
 185
 186 As with L<guestfs(3)>, you must first configure your guest by adding
 187 disks, then launch it, then mount any disks you need, and finally
 188 issue actions/commands.  So the general order of the day is:
 189
 190 =over 4
 191
 192 =item *
 193
 194 add or -a/--add
 195
 196 =item *
 197
 198 launch (aka run)
 199
 200 =item *
 201
 202 mount or -m/--mount
 203
 204 =item *
 205
 206 any other commands
 207
 208 =back
 209
 210 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 211 your guest before mounting or performing any other commands.
 212
 213 The only exception is that if the C<-m> or C<--mount> option was
 214 given, the guest is automatically run for you (simply because
 215 guestfish can't mount the disks you asked for without doing this).
 216
 217 =head1 QUOTING
 218
 219 You can quote ordinary parameters using either single or double
 220 quotes.  For example:
 221
 222  add "file with a space.img"
 223
 224  rm '/file name'
 225
 226  rm '/"'
 227
 228 A few commands require a list of strings to be passed.  For these, use
 229 a space-separated list, enclosed in quotes.  For example:
 230
 231  vgcreate VG "/dev/sda1 /dev/sdb1"
 232
 233 =head1 WILDCARDS AND GLOBBING
 234
 235 Neither guestfish nor the underlying guestfs API performs
 236 wildcard expansion (globbing) by default.  So for example the
 237 following will not do what you expect:
 238
 239  rm-rf /home/*
 240
 241 Assuming you don't have a directory literally called C</home/*>
 242 then the above command will return an error.
 243
 244 To perform wildcard expansion, use the C<glob> command.
 245
 246  glob rm-rf /home/*
 247
 248 runs C<rm-rf> on each path that matches (ie. potentially running
 249 the command many times), equivalent to:
 250
 251  rm-rf /home/jim
 252  rm-rf /home/joe
 253  rm-rf /home/mary
 254
 255 C<glob> only works on simple guest paths and not on device names.
 256
 257 If you have several parameters, each containing a wildcard, then glob
 258 will perform a cartesian product.
 259
 260 =head1 COMMENTS
 261
 262 Any line which starts with a I<#> character is treated as a comment
 263 and ignored.  The I<#> can optionally be preceeded by whitespace,
 264 but B<not> by a command.  For example:
 265
 266  # this is a comment
 267          # this is a comment
 268  foo # NOT a comment
 269
 270 Blank lines are also ignored.
 271
 272 =head1 RUNNING COMMANDS LOCALLY
 273
 274 Any line which starts with a I<!> character is treated as a command
 275 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
 276 For example:
 277
 278  !mkdir local
 279  tgz-out /remote local/remote-data.tar.gz
 280
 281 will create a directory C<local> on the host, and then export
 282 the contents of C</remote> on the mounted filesystem to
 283 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 284
 285 =head1 PIPES
 286
 287 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
 288 first command (a guestfish command) to the second command (any host
 289 command).  For example:
 290
 291  cat /etc/passwd | awk -F: '$3 == 0 { print }'
 292
 293 (where C<cat> is the guestfish cat command, but C<awk> is the host awk
 294 program).  The above command would list all accounts in the guest
 295 filesystem which have UID 0, ie. root accounts including backdoors.
 296 Other examples:
 297
 298  hexdump /bin/ls | head
 299  list-devices | tail -1
 300
 301 The space before the pipe symbol is required, any space after the pipe
 302 symbol is optional.  Everything after the pipe symbol is just passed
 303 straight to the host shell, so it can contain redirections, globs and
 304 anything else that makes sense on the host side.
 305
 306 To use a literal argument which begins with a pipe symbol, you have
 307 to quote it, eg:
 308
 309  echo "|"
 310
 311 =head1 EXIT ON ERROR BEHAVIOUR
 312
 313 By default, guestfish will ignore any errors when in interactive mode
 314 (ie. taking commands from a human over a tty), and will exit on the
 315 first error in non-interactive mode (scripts, commands given on the
 316 command line).
 317
 318 If you prefix a command with a I<-> character, then that command will
 319 not cause guestfish to exit, even if that (one) command returns an
 320 error.
 321
 322 =head1 COMMANDS
 323
 324 =head2 help
 325
 326  help
 327  help cmd
 328
 329 Without any parameter, this lists all commands.  With a C<cmd>
 330 parameter, this displays detailed help for a command.
 331
 332 =head2 quit | exit
 333
 334 This exits guestfish.  You can also use C<^D> key.
 335
 336 =head2 alloc | allocate
 337
 338  alloc filename size
 339
 340 This creates an empty (zeroed) file of the given size, and then adds
 341 so it can be further examined.
 342
 343 For more advanced image creation, see L<qemu-img(1)> utility.
 344
 345 Size can be specified (where C<nn> means a number):
 346
 347 =over 4
 348
 349 =item C<nn> or C<nn>K or C<nn>KB
 350
 351 number of kilobytes, eg: C<1440> = standard 3.5in floppy
 352
 353 =item C<nn>M or C<nn>MB
 354
 355 number of megabytes
 356
 357 =item C<nn>G or C<nn>GB
 358
 359 number of gigabytes
 360
 361 =item C<nn>sects
 362
 363 number of 512 byte sectors
 364
 365 =back
 366
 367 =head2 echo
 368
 369  echo [params ...]
 370
 371 This echos the parameters to the terminal.
 372
 373 =head2 edit | vi | emacs
 374
 375  edit filename
 376
 377 This is used to edit a file.  It downloads the file, edits it
 378 locally using your editor, then uploads the result.
 379
 380 The editor is C<$EDITOR>.  However if you use the alternate
 381 commands C<vi> or C<emacs> you will get those corresponding
 382 editors.
 383
 384 NOTE: This will not work reliably for large files
 385 (> 2 MB) or binary files containing \0 bytes.
 386
 387 =head2 lcd
 388
 389  lcd directory
 390
 391 Change the local directory, ie. the current directory of guestfish
 392 itself.
 393
 394 Note that C<!cd> won't do what you might expect.
 395
 396 =head2 glob
 397
 398  glob command args...
 399
 400 Expand wildcards in any paths in the args list, and run C<command>
 401 repeatedly on each matching path.
 402
 403 See section WILDCARDS AND GLOBBING.
 404
 405 @ACTIONS@
 406
 407 =head1 ENVIRONMENT VARIABLES
 408
 409 =over 4
 410
 411 =item LIBGUESTFS_DEBUG
 412
 413 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
 414 same effect as using the B<-v> option.
 415
 416 =item LIBGUESTFS_PATH
 417
 418 Set the path that guestfish uses to search for kernel and initrd.img.
 419 See the discussion of paths in L<guestfs(3)>.
 420
 421 =item LIBGUESTFS_QEMU
 422
 423 Set the default qemu binary that libguestfs uses.  If not set, then
 424 the qemu which was found at compile time by the configure script is
 425 used.
 426
 427 =item LIBGUESTFS_APPEND
 428
 429 Pass additional options to the guest kernel.
 430
 431 =item HOME
 432
 433 If compiled with GNU readline support, then the command history
 434 is saved in C<$HOME/.guestfish>
 435
 436 =item EDITOR
 437
 438 The C<edit> command uses C<$EDITOR> as the editor.  If not
 439 set, it uses C<vi>.
 440
 441 =back
 442
 443 =head1 EXIT CODE
 444
 445 guestfish returns I<0> if the commands completed without error, or
 446 I<1> if there was an error.
 447
 448 =head1 SEE ALSO
 449
 450 L<guestfs(3)>,
 451 L<http://libguestfs.org/>.
 452
 453 =head1 AUTHORS
 454
 455 Richard W.M. Jones (C<rjones at redhat dot com>)
 456
 457 =head1 COPYRIGHT
 458
 459 Copyright (C) 2009 Red Hat Inc.
 460 L<http://libguestfs.org/>
 461
 462 This program is free software; you can redistribute it and/or modify
 463 it under the terms of the GNU General Public License as published by
 464 the Free Software Foundation; either version 2 of the License, or
 465 (at your option) any later version.
 466
 467 This program is distributed in the hope that it will be useful,
 468 but WITHOUT ANY WARRANTY; without even the implied warranty of
 469 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 470 GNU General Public License for more details.
 471
 472 You should have received a copy of the GNU General Public License
 473 along with this program; if not, write to the Free Software
 474 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.