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<-v> | B<--verbose>
 101
 102 Enable very verbose messages.  This is particularly useful if you find
 103 a bug.
 104
 105 =back
 106
 107 =head1 COMMANDS ON COMMAND LINE
 108
 109 Any additional (non-option) arguments are treated as commands to
 110 execute.
 111
 112 Commands to execute should be separated by a colon (C<:>), where the
 113 colon is a separate parameter.  Thus:
 114
 115  guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
 116
 117 If there are no additional arguments, then we enter a shell, either an
 118 interactive shell with a prompt (if the input is a terminal) or a
 119 non-interactive shell.
 120
 121 In either command line mode or non-interactive shell, the first
 122 command that gives an error causes the whole shell to exit.  In
 123 interactive mode (with a prompt) if a command fails, you can continue
 124 to enter commands.
 125
 126 =head1 USING launch (OR run)
 127
 128 As with L<guestfs(3)>, you must first configure your guest by adding
 129 disks, then launch it, then mount any disks you need, and finally
 130 issue actions/commands.  So the general order of the day is:
 131
 132 =over 4
 133
 134 =item *
 135
 136 add or -a/--add
 137
 138 =item *
 139
 140 launch (aka run)
 141
 142 =item *
 143
 144 mount or -m/--mount
 145
 146 =item *
 147
 148 any other commands
 149
 150 =back
 151
 152 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 153 your guest before mounting or performing any other commands.
 154
 155 The only exception is that if the C<-m> or C<--mount> option was
 156 given, the guest is automatically run for you (simply because
 157 guestfish can't mount the disks you asked for without doing this).
 158
 159 =head1 QUOTING
 160
 161 You can quote ordinary parameters using either single or double
 162 quotes.  For example:
 163
 164  add "file with a space.img"
 165
 166  rm '/file name'
 167
 168  rm '/"'
 169
 170 A few commands require a list of strings to be passed.  For these, use
 171 a space-separated list, enclosed in quotes.  For example:
 172
 173  vgcreate VG "/dev/sda1 /dev/sdb1"
 174
 175 =head1 COMMANDS
 176
 177 =head2 help
 178
 179  help
 180  help cmd
 181
 182 Without any parameter, this lists all commands.  With a C<cmd>
 183 parameter, this displays detailed help for a command.
 184
 185 =head2 quit | exit
 186
 187 This exits guestfish.  You can also use C<^D> key.
 188
 189 =head2 alloc | allocate
 190
 191  alloc filename size
 192
 193 This creates an empty (zeroed) file of the given size, and then adds
 194 so it can be further examined.
 195
 196 For more advanced image creation, see L<qemu-img(1)> utility.
 197
 198 Size can be specified (where C<nn> means a number):
 199
 200 =over 4
 201
 202 =item C<nn> or C<nn>K or C<nn>KB
 203
 204 number of kilobytes, eg: C<1440> = standard 3.5in floppy
 205
 206 =item C<nn>M or C<nn>MB
 207
 208 number of megabytes
 209
 210 =item C<nn>G or C<nn>GB
 211
 212 number of gigabytes
 213
 214 =item C<nn>sects
 215
 216 number of 512 byte sectors
 217
 218 =back
 219
 220 @ACTIONS@
 221
 222 =head1 ENVIRONMENT VARIABLES
 223
 224 =over 4
 225
 226 =item LIBGUESTFS_DEBUG
 227
 228 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This has the
 229 same effect as using the B<-v> option.
 230
 231 =item LIBGUESTFS_PATH
 232
 233 Set the path that guestfish uses to search for kernel and initrd.img.
 234 See the discussion of paths in L<guestfs(3)>.
 235
 236 =item HOME
 237
 238 If compiled with GNU readline support, then the command history
 239 is saved in C<$HOME/.guestfish>
 240
 241 =back
 242
 243 =head1 SEE ALSO
 244
 245 L<guestfs(3)>,
 246 L<http://et.redhat.com/~rjones/libguestfs>.
 247
 248 =head1 AUTHORS
 249
 250 Richard W.M. Jones (C<rjones at redhat dot com>)
 251
 252 =head1 COPYRIGHT
 253
 254 Copyright (C) 2009 Red Hat Inc.
 255 L<http://et.redhat.com/~rjones/libguestfs>
 256
 257 This program is free software; you can redistribute it and/or modify
 258 it under the terms of the GNU General Public License as published by
 259 the Free Software Foundation; either version 2 of the License, or
 260 (at your option) any later version.
 261
 262 This program is distributed in the hope that it will be useful,
 263 but WITHOUT ANY WARRANTY; without even the implied warranty of
 264 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 265 GNU General Public License for more details.
 266
 267 You should have received a copy of the GNU General Public License
 268 along with this program; if not, write to the Free Software
 269 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.