Whitespace change.

[libguestfs.git] / guestfish.pod

diff --git a/guestfish.pod b/guestfish.pod
index 7755cc6..13a9fa7 100644 (file)
--- a/guestfish.pod
+++ b/guestfish.pod
@@ -2,18 +2,36 @@
 
 =head1 NAME
 
-guestfish - the libguestfs filesystem interactive shell
+guestfish - the libguestfs Filesystem Interactive SHell
 
 =head1 SYNOPSIS
 
  guestfish [--options] [commands]
 
+ guestfish
+
+ guestfish -a disk.img
+
+ guestfish -a disk.img -m dev[:mountpoint]
+
  guestfish -i libvirt-domain
 
- guestfish -i disk-image(s)
+ guestfish -i disk.img [disk.img ...]
 
 =head1 EXAMPLES
 
+=head2 As an interactive shell
+
+ $ guestfish
+ 
+ Welcome to guestfish, the libguestfs filesystem interactive shell for
+ editing virtual machine filesystems.
+ 
+ Type: 'help' for help with commands
+       'quit' to quit the shell
+ 
+ ><fs> help
+
 =head2 From shell scripts
 
 Create a new C</etc/motd> file in a guest:
@@ -21,55 +39,56 @@ Create a new C</etc/motd> file in a guest:
  guestfish <<_EOF_
  add disk.img
  run
- mount /dev/VolGroup00/LogVol00 /
- write_file /etc/motd "Hello users" 0
+ mount /dev/vg_guest/lv_root /
+ write_file /etc/motd "Welcome, new users" 0
  _EOF_
 
-List the LVs in a guest:
+List the LVM logical volumes in a guest:
 
- guestfish <<_EOF_
- add disk.img
+ guestfish -a disk.img --ro <<_EOF_
  run
  lvs
  _EOF_
 
-=head2 On the command line
+=head2 On one command line
 
-List the LVM PVs in a guest image:
+Update C</etc/resolv.conf> in a guest:
 
- guestfish add disk.img : run : pvs
+ guestfish \
+   add disk.img : run : mount /dev/vg_guest/lv_root / : \
+   write-file /etc/resolv.conf "nameserver 1.2.3.4" 0
 
-Remove C</boot/grub/menu.lst> (in reality not such a great idea):
+Edit C</boot/grub/grub.conf> interactively:
 
  guestfish --add disk.img \
-   --mount /dev/VolGroup00/LogVol00 \
+   --mount /dev/vg_guest/lv_root \
    --mount /dev/sda1:/boot \
-   rm /boot/grub/menu.lst
-
-=head2 As an interactive shell
+   edit /boot/grub/grub.conf
 
- $ guestfish
+=head2 Using virt-inspector
 
- Welcome to guestfish, the libguestfs filesystem interactive shell for
- editing virtual machine filesystems.
+Use the I<-i> option to get virt-inspector to mount
+the filesystems automatically as they would be mounted
+in the virtual machine:
 
- Type: 'help' for help with commands
-       'quit' to quit the shell
-
- ><fs> help
+ guestfish --ro -i disk.img cat /etc/group
 
 =head2 As a script interpreter
 
+Create a 50MB disk containing an ext2-formatted partition:
+
  #!/usr/bin/guestfish -f
- alloc /tmp/output.img 10M
+ alloc /tmp/output.img 50M
  run
- sfdisk /dev/sda 0 0 0 ,
+ part-disk /dev/sda mbr
  mkfs ext2 /dev/sda1
 
 =head2 Remote control
 
- eval `guestfish --listen`
- guestfish --remote cmd
+ eval `guestfish --listen --ro`
+ guestfish --remote add disk.img
+ guestfish --remote run
+ guestfish --remote lvs
 
 =head1 DESCRIPTION
 
@@ -77,6 +96,16 @@ Guestfish is a shell and command-line tool for examining and modifying
 virtual machine filesystems.  It uses libguestfs and exposes all of
 the functionality of the guestfs API, see L<guestfs(3)>.
 
+Guestfish gives you structured access to the libguestfs API, from
+shell scripts or the command line or interactively.  If you want to
+rescue a broken virtual machine image, you might want to look at the
+L<virt-rescue(1)> command.
+
+Using guestfish in read/write mode on live virtual machines can be
+dangerous, potentially causing disk corruption.  Use the I<--ro>
+(read-only) option to use guestfish safely if the disk image or
+virtual machine might be live.
+
 =head1 OPTIONS
 
 =over 4
@@ -152,6 +181,11 @@ You have to mount something on C</> before most commands will work.
 If any C<-m> or C<--mount> options are given, the guest is
 automatically launched.
 
+If you don't know what filesystems a disk image contains, you
+can either run guestfish without this option, then list the partitions
+and LVs available (see L</list-partitions> and L</lvs> commands),
+or you can use the L<virt-list-filesystems(1)> program.
+
 =item B<-n> | B<--no-sync>
 
 Disable autosync.  This is enabled by default.  See the discussion
@@ -164,8 +198,12 @@ I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 
 =item B<-r> | B<--ro>
 
-This changes the C<-m> option so that mounts are done read-only
-(see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
+This changes the C<-a> and C<-m> options so that disks are added and
+mounts are done read-only (see L<guestfs(3)/guestfs_mount_ro>).
+
+The option must always be used if the disk image or virtual machine
+might be running, and is generally recommended in cases where you
+don't need write access to the disk.
 
 =item B<--selinux>
 
@@ -453,6 +491,18 @@ number of megabytes
 
 number of gigabytes
 
+=item C<nn>T or C<nn>TB
+
+number of terabytes
+
+=item C<nn>P or C<nn>PB
+
+number of petabytes
+
+=item C<nn>E or C<nn>EB
+
+number of exabytes
+
 =item C<nn>sects
 
 number of 512 byte sectors
@@ -562,6 +612,18 @@ number of megabytes
 
 number of gigabytes
 
+=item C<nn>T or C<nn>TB
+
+number of terabytes
+
+=item C<nn>P or C<nn>PB
+
+number of petabytes
+
+=item C<nn>E or C<nn>EB
+
+number of exabytes
+
 =item C<nn>sects
 
 number of 512 byte sectors
@@ -658,6 +720,7 @@ L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,
 L<virt-edit(1)>,
+L<virt-list-filesystems(1)>,
 L<virt-ls(1)>,
 L<virt-rescue(1)>,
 L<virt-tar(1)>.