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