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  part-disk /dev/sda mbr
  67  mkfs ext2 /dev/sda1
  68
  69 =head2 Remote control
  70
  71  eval `guestfish --listen`
  72  guestfish --remote cmd
  73
  74 =head1 DESCRIPTION
  75
  76 Guestfish is a shell and command-line tool for examining and modifying
  77 virtual machine filesystems.  It uses libguestfs and exposes all of
  78 the functionality of the guestfs API, see L<guestfs(3)>.
  79
  80 =head1 OPTIONS
  81
  82 =over 4
  83
  84 =item B<--help>
  85
  86 Displays general help on options.
  87
  88 =item B<-h> | B<--cmd-help>
  89
  90 Lists all available guestfish commands.
  91
  92 =item B<-h cmd> | B<--cmd-help cmd>
  93
  94 Displays detailed help on a single command C<cmd>.
  95
  96 =item B<-a image> | B<--add image>
  97
  98 Add a block device or virtual machine image to the shell.
  99
 100 =item B<-D> | B<--no-dest-paths>
 101
 102 Don't tab-complete paths on the guest filesystem.  It is useful to be
 103 able to hit the tab key to complete paths on the guest filesystem, but
 104 this causes extra "hidden" guestfs calls to be made, so this option is
 105 here to allow this feature to be disabled.
 106
 107 =item B<-f file> | B<--file file>
 108
 109 Read commands from C<file>.  To write pure guestfish
 110 scripts, use:
 111
 112  #!/usr/bin/guestfish -f
 113
 114 =item B<-i> | B<--inspector>
 115
 116 Run virt-inspector on the named libvirt domain or list of disk
 117 images.  If virt-inspector is available and if it can identify
 118 the domain or disk images, then partitions will be mounted
 119 correctly at start-up.
 120
 121 Typical usage is either:
 122
 123  guestfish -i myguest
 124
 125 (for an inactive libvirt domain called I<myguest>), or:
 126
 127  guestfish --ro -i myguest
 128
 129 (for active domains, readonly), or specify the block device directly:
 130
 131  guestfish -i /dev/Guests/MyGuest
 132
 133 You cannot use I<-a>, I<-m>, I<--listen>, I<--remote> or I<--selinux>
 134 in conjunction with this option, and options other than I<--ro> might
 135 not behave correctly.
 136
 137 See also: L<virt-inspector(1)>.
 138
 139 =item B<--listen>
 140
 141 Fork into the background and listen for remote commands.  See section
 142 I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 143
 144 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
 145
 146 Mount the named partition or logical volume on the given mountpoint.
 147
 148 If the mountpoint is omitted, it defaults to C</>.
 149
 150 You have to mount something on C</> before most commands will work.
 151
 152 If any C<-m> or C<--mount> options are given, the guest is
 153 automatically launched.
 154
 155 If you don't know what filesystems a disk image contains, you
 156 can either run guestfish without this option, then list the partitions
 157 and LVs available (see L</list-partitions> and L</lvs> commands),
 158 or you can use the L<virt-list-filesystems(1)> program.
 159
 160 =item B<-n> | B<--no-sync>
 161
 162 Disable autosync.  This is enabled by default.  See the discussion
 163 of autosync in the L<guestfs(3)> manpage.
 164
 165 =item B<--remote[=pid]>
 166
 167 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
 168 I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 169
 170 =item B<-r> | B<--ro>
 171
 172 This changes the C<-m> option so that mounts are done read-only
 173 (see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
 174
 175 =item B<--selinux>
 176
 177 Enable SELinux support for the guest.  See L<guestfs(3)/SELINUX>.
 178
 179 =item B<-v> | B<--verbose>
 180
 181 Enable very verbose messages.  This is particularly useful if you find
 182 a bug.
 183
 184 =item B<-V> | B<--version>
 185
 186 Display the guestfish / libguestfs version number and exit.
 187
 188 =item B<-x>
 189
 190 Echo each command before executing it.
 191
 192 =back
 193
 194 =head1 COMMANDS ON COMMAND LINE
 195
 196 Any additional (non-option) arguments are treated as commands to
 197 execute.
 198
 199 Commands to execute should be separated by a colon (C<:>), where the
 200 colon is a separate parameter.  Thus:
 201
 202  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
 203
 204 If there are no additional arguments, then we enter a shell, either an
 205 interactive shell with a prompt (if the input is a terminal) or a
 206 non-interactive shell.
 207
 208 In either command line mode or non-interactive shell, the first
 209 command that gives an error causes the whole shell to exit.  In
 210 interactive mode (with a prompt) if a command fails, you can continue
 211 to enter commands.
 212
 213 =head1 USING launch (OR run)
 214
 215 As with L<guestfs(3)>, you must first configure your guest by adding
 216 disks, then launch it, then mount any disks you need, and finally
 217 issue actions/commands.  So the general order of the day is:
 218
 219 =over 4
 220
 221 =item *
 222
 223 add or -a/--add
 224
 225 =item *
 226
 227 launch (aka run)
 228
 229 =item *
 230
 231 mount or -m/--mount
 232
 233 =item *
 234
 235 any other commands
 236
 237 =back
 238
 239 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 240 your guest before mounting or performing any other commands.
 241
 242 The only exception is that if the C<-m> or C<--mount> option was
 243 given, the guest is automatically run for you (simply because
 244 guestfish can't mount the disks you asked for without doing this).
 245
 246 =head1 QUOTING
 247
 248 You can quote ordinary parameters using either single or double
 249 quotes.  For example:
 250
 251  add "file with a space.img"
 252
 253  rm '/file name'
 254
 255  rm '/"'
 256
 257 A few commands require a list of strings to be passed.  For these, use
 258 a whitespace-separated list, enclosed in quotes.  Strings containing whitespace
 259 to be passed through must be enclosed in single quotes.  A literal single quote
 260 must be escaped with a backslash.
 261
 262  vgcreate VG "/dev/sda1 /dev/sdb1"
 263  command "/bin/echo 'foo      bar'"
 264  command "/bin/echo \'foo\'"
 265
 266 =head1 WILDCARDS AND GLOBBING
 267
 268 Neither guestfish nor the underlying guestfs API performs
 269 wildcard expansion (globbing) by default.  So for example the
 270 following will not do what you expect:
 271
 272  rm-rf /home/*
 273
 274 Assuming you don't have a directory literally called C</home/*>
 275 then the above command will return an error.
 276
 277 To perform wildcard expansion, use the C<glob> command.
 278
 279  glob rm-rf /home/*
 280
 281 runs C<rm-rf> on each path that matches (ie. potentially running
 282 the command many times), equivalent to:
 283
 284  rm-rf /home/jim
 285  rm-rf /home/joe
 286  rm-rf /home/mary
 287
 288 C<glob> only works on simple guest paths and not on device names.
 289
 290 If you have several parameters, each containing a wildcard, then glob
 291 will perform a cartesian product.
 292
 293 =head1 COMMENTS
 294
 295 Any line which starts with a I<#> character is treated as a comment
 296 and ignored.  The I<#> can optionally be preceeded by whitespace,
 297 but B<not> by a command.  For example:
 298
 299  # this is a comment
 300          # this is a comment
 301  foo # NOT a comment
 302
 303 Blank lines are also ignored.
 304
 305 =head1 RUNNING COMMANDS LOCALLY
 306
 307 Any line which starts with a I<!> character is treated as a command
 308 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
 309 For example:
 310
 311  !mkdir local
 312  tgz-out /remote local/remote-data.tar.gz
 313
 314 will create a directory C<local> on the host, and then export
 315 the contents of C</remote> on the mounted filesystem to
 316 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 317
 318 =head1 PIPES
 319
 320 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
 321 first command (a guestfish command) to the second command (any host
 322 command).  For example:
 323
 324  cat /etc/passwd | awk -F: '$3 == 0 { print }'
 325
 326 (where C<cat> is the guestfish cat command, but C<awk> is the host awk
 327 program).  The above command would list all accounts in the guest
 328 filesystem which have UID 0, ie. root accounts including backdoors.
 329 Other examples:
 330
 331  hexdump /bin/ls | head
 332  list-devices | tail -1
 333
 334 The space before the pipe symbol is required, any space after the pipe
 335 symbol is optional.  Everything after the pipe symbol is just passed
 336 straight to the host shell, so it can contain redirections, globs and
 337 anything else that makes sense on the host side.
 338
 339 To use a literal argument which begins with a pipe symbol, you have
 340 to quote it, eg:
 341
 342  echo "|"
 343
 344 =head1 HOME DIRECTORIES
 345
 346 If a parameter starts with the character C<~> then the tilde may be
 347 expanded as a home directory path (either C<~> for the current user's
 348 home directory, or C<~user> for another user).
 349
 350 Note that home directory expansion happens for users known I<on the
 351 host>, not in the guest filesystem.
 352
 353 To use a literal argument which begins with a tilde, you have to quote
 354 it, eg:
 355
 356  echo "~"
 357
 358 =head1 WINDOWS PATHS
 359
 360 If a path is prefixed with C<win:> then you can use Windows-style
 361 paths (with some limitations).  The following commands are equivalent:
 362
 363  file /WINDOWS/system32/config/system.LOG
 364
 365  file win:/windows/system32/config/system.log
 366
 367  file win:\windows\system32\config\system.log
 368
 369  file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
 370
 371 This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
 372 handles case insensitivity like Windows would.  This only works in
 373 argument positions that expect a path.
 374
 375 =head1 EXIT ON ERROR BEHAVIOUR
 376
 377 By default, guestfish will ignore any errors when in interactive mode
 378 (ie. taking commands from a human over a tty), and will exit on the
 379 first error in non-interactive mode (scripts, commands given on the
 380 command line).
 381
 382 If you prefix a command with a I<-> character, then that command will
 383 not cause guestfish to exit, even if that (one) command returns an
 384 error.
 385
 386 =head1 REMOTE CONTROL GUESTFISH OVER A SOCKET
 387
 388 Guestfish can be remote-controlled over a socket.  This is useful
 389 particularly in shell scripts where you want to make several different
 390 changes to a filesystem, but you don't want the overhead of starting
 391 up a guestfish process each time.
 392
 393 Start a guestfish server process using:
 394
 395  eval `guestfish --listen`
 396
 397 and then send it commands by doing:
 398
 399  guestfish --remote cmd [...]
 400
 401 To cause the server to exit, send it the exit command:
 402
 403  guestfish --remote exit
 404
 405 Note that the server will normally exit if there is an error in a
 406 command.  You can change this in the usual way.  See section I<EXIT ON
 407 ERROR BEHAVIOUR>.
 408
 409 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
 410
 411 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
 412 which is how the C<--remote> option knows where to send the commands.
 413 You can have several guestfish listener processes running using:
 414
 415  eval `guestfish --listen`
 416  pid1=$GUESTFISH_PID
 417  eval `guestfish --listen`
 418  pid2=$GUESTFISH_PID
 419  ...
 420  guestfish --remote=$pid1 cmd
 421  guestfish --remote=$pid2 cmd
 422
 423 =head2 REMOTE CONTROL DETAILS
 424
 425 Remote control happens over a Unix domain socket called
 426 C</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective
 427 user ID of the process, and C<$PID> is the process ID of the server.
 428
 429 Guestfish client and server versions must match exactly.
 430
 431 =head1 GUESTFISH COMMANDS
 432
 433 The commands in this section are guestfish convenience commands, in
 434 other words, they are not part of the L<guestfs(3)> API.
 435
 436 =head2 alloc | allocate
 437
 438  alloc filename size
 439
 440 This creates an empty (zeroed) file of the given size, and then adds
 441 so it can be further examined.
 442
 443 For more advanced image creation, see L<qemu-img(1)> utility.
 444
 445 Size can be specified (where C<nn> means a number):
 446
 447 =over 4
 448
 449 =item C<nn> or C<nn>K or C<nn>KB
 450
 451 number of kilobytes, eg: C<1440> = standard 3.5in floppy
 452
 453 =item C<nn>M or C<nn>MB
 454
 455 number of megabytes
 456
 457 =item C<nn>G or C<nn>GB
 458
 459 number of gigabytes
 460
 461 =item C<nn>T or C<nn>TB
 462
 463 number of terabytes
 464
 465 =item C<nn>P or C<nn>PB
 466
 467 number of petabytes
 468
 469 =item C<nn>E or C<nn>EB
 470
 471 number of exabytes
 472
 473 =item C<nn>sects
 474
 475 number of 512 byte sectors
 476
 477 =back
 478
 479 =head2 echo
 480
 481  echo [params ...]
 482
 483 This echos the parameters to the terminal.
 484
 485 =head2 edit | vi | emacs
 486
 487  edit filename
 488
 489 This is used to edit a file.  It downloads the file, edits it
 490 locally using your editor, then uploads the result.
 491
 492 The editor is C<$EDITOR>.  However if you use the alternate
 493 commands C<vi> or C<emacs> you will get those corresponding
 494 editors.
 495
 496 NOTE: This will not work reliably for large files
 497 (> 2 MB) or binary files containing \0 bytes.
 498
 499 =head2 glob
 500
 501  glob command args...
 502
 503 Expand wildcards in any paths in the args list, and run C<command>
 504 repeatedly on each matching path.
 505
 506 See section WILDCARDS AND GLOBBING.
 507
 508 =head2 help
 509
 510  help
 511  help cmd
 512
 513 Without any parameter, this lists all commands.  With a C<cmd>
 514 parameter, this displays detailed help for a command.
 515
 516 =head2 lcd
 517
 518  lcd directory
 519
 520 Change the local directory, ie. the current directory of guestfish
 521 itself.
 522
 523 Note that C<!cd> won't do what you might expect.
 524
 525 =head2 more | less
 526
 527  more filename
 528
 529  less filename
 530
 531 This is used to view a file.
 532
 533 The default viewer is C<$PAGER>.  However if you use the alternate
 534 command C<less> you will get the C<less> command specifically.
 535
 536 NOTE: This will not work reliably for large files
 537 (> 2 MB) or binary files containing \0 bytes.
 538
 539 =head2 quit | exit
 540
 541 This exits guestfish.  You can also use C<^D> key.
 542
 543 =head2 reopen
 544
 545  reopen
 546
 547 Close and reopen the libguestfs handle.  It is not necessary to use
 548 this normally, because the handle is closed properly when guestfish
 549 exits.  However this is occasionally useful for testing.
 550
 551 =head2 sparse
 552
 553  sparse filename size
 554
 555 This creates an empty sparse file of the given size, and then adds
 556 so it can be further examined.
 557
 558 In all respects it works the same as the C<alloc> command, except that
 559 the image file is allocated sparsely, which means that disk blocks are
 560 not assigned to the file until they are needed.  Sparse disk files
 561 only use space when written to, but they are slower and there is a
 562 danger you could run out of real disk space during a write operation.
 563
 564 For more advanced image creation, see L<qemu-img(1)> utility.
 565
 566 Size can be specified (where C<nn> means a number):
 567
 568 =over 4
 569
 570 =item C<nn> or C<nn>K or C<nn>KB
 571
 572 number of kilobytes, eg: C<1440> = standard 3.5in floppy
 573
 574 =item C<nn>M or C<nn>MB
 575
 576 number of megabytes
 577
 578 =item C<nn>G or C<nn>GB
 579
 580 number of gigabytes
 581
 582 =item C<nn>T or C<nn>TB
 583
 584 number of terabytes
 585
 586 =item C<nn>P or C<nn>PB
 587
 588 number of petabytes
 589
 590 =item C<nn>E or C<nn>EB
 591
 592 number of exabytes
 593
 594 =item C<nn>sects
 595
 596 number of 512 byte sectors
 597
 598 =back
 599
 600 =head2 time
 601
 602  time command args...
 603
 604 Run the command as usual, but print the elapsed time afterwards.  This
 605 can be useful for benchmarking operations.
 606
 607 =head1 COMMANDS
 608
 609 @ACTIONS@
 610
 611 =head1 ENVIRONMENT VARIABLES
 612
 613 =over 4
 614
 615 =item EDITOR
 616
 617 The C<edit> command uses C<$EDITOR> as the editor.  If not
 618 set, it uses C<vi>.
 619
 620 =item GUESTFISH_PID
 621
 622 Used with the I<--remote> option to specify the remote guestfish
 623 process to control.  See section I<REMOTE CONTROL GUESTFISH OVER A
 624 SOCKET>.
 625
 626 =item HOME
 627
 628 If compiled with GNU readline support, then the command history
 629 is saved in C<$HOME/.guestfish>
 630
 631 =item LIBGUESTFS_APPEND
 632
 633 Pass additional options to the guest kernel.
 634
 635 =item LIBGUESTFS_DEBUG
 636
 637 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
 638 same effect as using the B<-v> option.
 639
 640 =item LIBGUESTFS_MEMSIZE
 641
 642 Set the memory allocated to the qemu process, in megabytes.  For
 643 example:
 644
 645  LIBGUESTFS_MEMSIZE=700
 646
 647 =item LIBGUESTFS_PATH
 648
 649 Set the path that guestfish uses to search for kernel and initrd.img.
 650 See the discussion of paths in L<guestfs(3)>.
 651
 652 =item LIBGUESTFS_QEMU
 653
 654 Set the default qemu binary that libguestfs uses.  If not set, then
 655 the qemu which was found at compile time by the configure script is
 656 used.
 657
 658 =item LIBGUESTFS_TRACE
 659
 660 Set C<LIBGUESTFS_TRACE=1> to enable command traces.
 661
 662 =item PAGER
 663
 664 The C<more> command uses C<$PAGER> as the pager.  If not
 665 set, it uses C<more>.
 666
 667 =item TMPDIR
 668
 669 Location of temporary directory, defaults to C</tmp>.
 670
 671 If libguestfs was compiled to use the supermin appliance then each
 672 handle will require rather a large amount of space in this directory
 673 for short periods of time (~ 80 MB).  You can use C<$TMPDIR> to
 674 configure another directory to use in case C</tmp> is not large
 675 enough.
 676
 677 =back
 678
 679 =head1 EXIT CODE
 680
 681 guestfish returns I<0> if the commands completed without error, or
 682 I<1> if there was an error.
 683
 684 =head1 SEE ALSO
 685
 686 L<guestfs(3)>,
 687 L<http://libguestfs.org/>,
 688 L<virt-cat(1)>,
 689 L<virt-edit(1)>,
 690 L<virt-list-filesystems(1)>,
 691 L<virt-ls(1)>,
 692 L<virt-rescue(1)>,
 693 L<virt-tar(1)>.
 694
 695 =head1 AUTHORS
 696
 697 Richard W.M. Jones (C<rjones at redhat dot com>)
 698
 699 =head1 COPYRIGHT
 700
 701 Copyright (C) 2009 Red Hat Inc.
 702 L<http://libguestfs.org/>
 703
 704 This program is free software; you can redistribute it and/or modify
 705 it under the terms of the GNU General Public License as published by
 706 the Free Software Foundation; either version 2 of the License, or
 707 (at your option) any later version.
 708
 709 This program is distributed in the hope that it will be useful,
 710 but WITHOUT ANY WARRANTY; without even the implied warranty of
 711 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 712 GNU General Public License for more details.
 713
 714 You should have received a copy of the GNU General Public License
 715 along with this program; if not, write to the Free Software
 716 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.