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 =head1 EXAMPLES
  12
  13 =head2 From shell scripts
  14
  15 Create a new C</etc/motd> file in a guest:
  16
  17  guestfish <<_EOF_
  18  add disk.img
  19  run
  20  mount /dev/VolGroup00/LogVol00 /
  21  write_file /etc/motd "Hello users" 0
  22  _EOF_
  23
  24 List the LVs in a guest:
  25
  26  guestfish <<_EOF_
  27  add disk.img
  28  run
  29  lvs
  30  _EOF_
  31
  32 =head2 On the command line
  33
  34 List the LVM PVs in a guest image:
  35
  36  guestfish add disk.img : run : pvs
  37
  38 Remove C</boot/grub/menu.lst> (in reality not such a great idea):
  39
  40  guestfish --add disk.img \
  41    --mount /dev/VolGroup00/LogVol00 \
  42    --mount /dev/sda1:/boot \
  43    rm /boot/grub/menu.lst : \
  44    sync : exit
  45
  46 =head2 As an interactive shell
  47
  48  $ guestfish
  49
  50  Welcome to guestfish, the libguestfs filesystem interactive shell for
  51  editing virtual machine filesystems.
  52
  53  Type: 'help' for help with commands
  54        'quit' to quit the shell
  55
  56  ><fs> help
  57
  58 =head1 DESCRIPTION
  59
  60 Guestfish is a shell and command-line tool for examining and modifying
  61 virtual machine filesystems.  It uses libguestfs and exposes all of
  62 the functionality of the guestfs API, see L<guestfs(3)>.
  63
  64 =head1 OPTIONS
  65
  66 =over 4
  67
  68 =item B<--help>
  69
  70 Displays general help on options.
  71
  72 =item B<-h> | B<--cmd-help>
  73
  74 Lists all available guestfish commands.
  75
  76 =item B<-h cmd> | B<--cmd-help cmd>
  77
  78 Displays detailed help on a single command C<cmd>.
  79
  80 =item B<-a image> | B<--add image>
  81
  82 Add a block device or virtual machine image to the shell.
  83
  84 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
  85
  86 Mount the named partition or logical volume on the given mountpoint.
  87
  88 If the mountpoint is omitted, it defaults to C</>.
  89
  90 You have to mount something on C</> before most commands will work.
  91
  92 If any C<-m> or C<--mount> options are given, the guest is
  93 automatically launched.
  94
  95 =item B<-n> | B<--no-sync>
  96
  97 Disable autosync.  This is enabled by default.  See the discussion
  98 of autosync in the L<guestfs(3)> manpage.
  99
 100 =item B<-r> | B<--ro>
 101
 102 This changes the C<-m> option so that mounts are done read-only
 103 (see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
 104
 105 =item B<-v> | B<--verbose>
 106
 107 Enable very verbose messages.  This is particularly useful if you find
 108 a bug.
 109
 110 =back
 111
 112 =head1 COMMANDS ON COMMAND LINE
 113
 114 Any additional (non-option) arguments are treated as commands to
 115 execute.
 116
 117 Commands to execute should be separated by a colon (C<:>), where the
 118 colon is a separate parameter.  Thus:
 119
 120  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
 121
 122 If there are no additional arguments, then we enter a shell, either an
 123 interactive shell with a prompt (if the input is a terminal) or a
 124 non-interactive shell.
 125
 126 In either command line mode or non-interactive shell, the first
 127 command that gives an error causes the whole shell to exit.  In
 128 interactive mode (with a prompt) if a command fails, you can continue
 129 to enter commands.
 130
 131 =head1 USING launch (OR run)
 132
 133 As with L<guestfs(3)>, you must first configure your guest by adding
 134 disks, then launch it, then mount any disks you need, and finally
 135 issue actions/commands.  So the general order of the day is:
 136
 137 =over 4
 138
 139 =item *
 140
 141 add or -a/--add
 142
 143 =item *
 144
 145 launch (aka run)
 146
 147 =item *
 148
 149 mount or -m/--mount
 150
 151 =item *
 152
 153 any other commands
 154
 155 =back
 156
 157 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 158 your guest before mounting or performing any other commands.
 159
 160 The only exception is that if the C<-m> or C<--mount> option was
 161 given, the guest is automatically run for you (simply because
 162 guestfish can't mount the disks you asked for without doing this).
 163
 164 =head1 QUOTING
 165
 166 You can quote ordinary parameters using either single or double
 167 quotes.  For example:
 168
 169  add "file with a space.img"
 170
 171  rm '/file name'
 172
 173  rm '/"'
 174
 175 A few commands require a list of strings to be passed.  For these, use
 176 a space-separated list, enclosed in quotes.  For example:
 177
 178  vgcreate VG "/dev/sda1 /dev/sdb1"
 179
 180 =head1 COMMENTS
 181
 182 Any line which starts with a I<#> character is treated as a comment
 183 and ignored.  The I<#> can optionally be preceeded by whitespace,
 184 but B<not> by a command.  For example:
 185
 186  # this is a comment
 187          # this is a comment
 188  foo # NOT a comment
 189
 190 Blank lines are also ignored.
 191
 192 =head1 RUNNING COMMANDS LOCALLY
 193
 194 Any line which starts with a I<!> character is treated as a command
 195 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
 196 For example:
 197
 198  !mkdir local
 199  tgz-out /remote local/remote-data.tar.gz
 200
 201 will create a directory C<local> on the host, and then export
 202 the contents of C</remote> on the mounted filesystem to
 203 C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 204
 205 =head1 EXIT ON ERROR BEHAVIOUR
 206
 207 By default, guestfish will ignore any errors when in interactive mode
 208 (ie. taking commands from a human over a tty), and will exit on the
 209 first error in non-interactive mode (scripts, commands given on the
 210 command line).
 211
 212 If you prefix a command with a I<-> character, then that command will
 213 not cause guestfish to exit, even if that (one) command returns an
 214 error.
 215
 216 =head1 COMMANDS
 217
 218 =head2 help
 219
 220  help
 221  help cmd
 222
 223 Without any parameter, this lists all commands.  With a C<cmd>
 224 parameter, this displays detailed help for a command.
 225
 226 =head2 quit | exit
 227
 228 This exits guestfish.  You can also use C<^D> key.
 229
 230 =head2 alloc | allocate
 231
 232  alloc filename size
 233
 234 This creates an empty (zeroed) file of the given size, and then adds
 235 so it can be further examined.
 236
 237 For more advanced image creation, see L<qemu-img(1)> utility.
 238
 239 Size can be specified (where C<nn> means a number):
 240
 241 =over 4
 242
 243 =item C<nn> or C<nn>K or C<nn>KB
 244
 245 number of kilobytes, eg: C<1440> = standard 3.5in floppy
 246
 247 =item C<nn>M or C<nn>MB
 248
 249 number of megabytes
 250
 251 =item C<nn>G or C<nn>GB
 252
 253 number of gigabytes
 254
 255 =item C<nn>sects
 256
 257 number of 512 byte sectors
 258
 259 =back
 260
 261 =head2 echo
 262
 263  echo [params ...]
 264
 265 This echos the parameters to the terminal.
 266
 267 =head2 edit | vi | emacs
 268
 269  edit filename
 270
 271 This is used to edit a file.  It downloads the file, edits it
 272 locally using your editor, then uploads the result.
 273
 274 The editor is C<$EDITOR>.  However if you use the alternate
 275 commands C<vi> or C<emacs> you will get those corresponding
 276 editors.
 277
 278 NOTE: This will not work reliably for large files
 279 (> 2 MB) or binary files containing \0 bytes.
 280
 281 =head2 lcd
 282
 283  lcd directory
 284
 285 Change the local directory, ie. the current directory of guestfish
 286 itself.
 287
 288 Note that C<!cd> won't do what you might expect.
 289
 290 @ACTIONS@
 291
 292 =head1 ENVIRONMENT VARIABLES
 293
 294 =over 4
 295
 296 =item LIBGUESTFS_DEBUG
 297
 298 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
 299 same effect as using the B<-v> option.
 300
 301 =item LIBGUESTFS_PATH
 302
 303 Set the path that guestfish uses to search for kernel and initrd.img.
 304 See the discussion of paths in L<guestfs(3)>.
 305
 306 =item LIBGUESTFS_QEMU
 307
 308 Set the default qemu binary that libguestfs uses.  If not set, then
 309 the qemu which was found at compile time by the configure script is
 310 used.
 311
 312 =item LIBGUESTFS_APPEND
 313
 314 Pass additional options to the guest kernel.
 315
 316 =item HOME
 317
 318 If compiled with GNU readline support, then the command history
 319 is saved in C<$HOME/.guestfish>
 320
 321 =item EDITOR
 322
 323 The C<edit> command uses C<$EDITOR> as the editor.  If not
 324 set, it uses C<vi>.
 325
 326 =back
 327
 328 =head1 EXIT CODE
 329
 330 guestfish returns I<0> if the commands completed without error, or
 331 I<1> if there was an error.
 332
 333 =head1 SEE ALSO
 334
 335 L<guestfs(3)>,
 336 L<http://et.redhat.com/~rjones/libguestfs>.
 337
 338 =head1 AUTHORS
 339
 340 Richard W.M. Jones (C<rjones at redhat dot com>)
 341
 342 =head1 COPYRIGHT
 343
 344 Copyright (C) 2009 Red Hat Inc.
 345 L<http://et.redhat.com/~rjones/libguestfs>
 346
 347 This program is free software; you can redistribute it and/or modify
 348 it under the terms of the GNU General Public License as published by
 349 the Free Software Foundation; either version 2 of the License, or
 350 (at your option) any later version.
 351
 352 This program is distributed in the hope that it will be useful,
 353 but WITHOUT ANY WARRANTY; without even the implied warranty of
 354 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 355 GNU General Public License for more details.
 356
 357 You should have received a copy of the GNU General Public License
 358 along with this program; if not, write to the Free Software
 359 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.