From: Richard Jones Date: Tue, 7 Apr 2009 13:55:25 +0000 (+0100) Subject: Added guestfish(1) manpage. X-Git-Tag: 0.5~12 X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=21ba59ce3cbc594ce9c7aeecd4dadb8430e4042d;hp=bccbfe5ab55c8aa5bbb0fb6e209936ff1359605a Added guestfish(1) manpage. --- diff --git a/.gitignore b/.gitignore index 2e02d96..2992bb4 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ emptydisk examples/df examples/hello fish/guestfish +guestfish.1 guestfs.3 initramfs initramfs.timestamp diff --git a/Makefile.am b/Makefile.am index d34b942..241a0a8 100644 --- a/Makefile.am +++ b/Makefile.am @@ -32,6 +32,7 @@ endif EXTRA_DIST = \ make-initramfs.sh update-initramfs.sh \ guestfs.pod guestfs-actions.pod guestfs-structs.pod \ + guestfish.pod guestfish-actions.pod \ libguestfs.spec \ HACKING @@ -66,11 +67,11 @@ CLEANFILES = $(fs_DATA) emptydisk clean-local: rm -rf initramfs -# Manual page. +# Manual pages. # guestfs-actions.pod and guestfs-structs are autogenerated. There is # no include mechanism for POD, so we have to do it by hand. -man_MANS = guestfs.3 +man_MANS = guestfs.3 guestfish.1 guestfs.3: guestfs.pod guestfs-actions.pod guestfs-structs.pod sed \ @@ -84,6 +85,17 @@ guestfs.3: guestfs.pod guestfs-actions.pod guestfs-structs.pod --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ > $@ +guestfish.1: guestfish.pod guestfish-actions.pod + sed \ + -e '/@ACTIONS@/rguestfish-actions.pod' -e 's/@ACTIONS@//' \ + < $< | \ + $(POD2MAN) \ + --section 1 \ + -c "Virtualization Support" \ + --name "guestfish" \ + --release "$(PACKAGE_NAME)-$(PACKAGE_VERSION)" \ + > $@ + # Test-boot the image. test-boot: emptydisk diff --git a/guestfish-actions.pod b/guestfish-actions.pod new file mode 100644 index 0000000..8a6ce29 --- /dev/null +++ b/guestfish-actions.pod @@ -0,0 +1,148 @@ +=head2 cat + + cat path + +Return the contents of the file named C. + +Note that this function cannot correctly handle binary files +(specifically, files containing C<\0> character which is treated +as end of string). For those you need to use the C +function which has a more complex interface. + +=head2 list-devices + + list-devices + +List all the block devices. + +The full block device names are returned, eg. C + + +=head2 list-partitions + + list-partitions + +List all the partitions detected on all block devices. + +The full partition device names are returned, eg. C + +This does not return logical volumes. For that you will need to +call C. + +=head2 ll + + ll directory + +List the files in C (relative to the root directory, +there is no cwd) in the format of 'ls -la'. + +This command is mostly useful for interactive sessions. It +is I intended that you try to parse the output string. + +=head2 ls + + ls directory + +List the files in C (relative to the root directory, +there is no cwd). The '.' and '..' entries are not returned, but +hidden files are shown. + +This command is mostly useful for interactive sessions. Programs +should probably use C instead. + +=head2 lvs + + lvs + +List all the logical volumes detected. This is the equivalent +of the L command. + +This returns a list of the logical volume device names +(eg. C). + +See also C. + +=head2 lvs-full + + lvs-full + +List all the logical volumes detected. This is the equivalent +of the L command. The "full" version includes all fields. + +=head2 mount + + mount device mountpoint + +Mount a guest disk at a position in the filesystem. Block devices +are named C, C and so on, as they were added to +the guest. If those block devices contain partitions, they will have +the usual names (eg. C). Also LVM C-style +names can be used. + +The rules are the same as for L: A filesystem must +first be mounted on C before others can be mounted. Other +filesystems can only be mounted on directories which already +exist. + +The mounted filesystem is writable, if we have sufficient permissions +on the underlying device. + +The filesystem options C and C are set with this +call, in order to improve reliability. + +=head2 pvs + + pvs + +List all the physical volumes detected. This is the equivalent +of the L command. + +This returns a list of just the device names that contain +PVs (eg. C). + +See also C. + +=head2 pvs-full + + pvs-full + +List all the physical volumes detected. This is the equivalent +of the L command. The "full" version includes all fields. + +=head2 sync + + sync + +This syncs the disk, so that any writes are flushed through to the +underlying disk image. + +You should always call this if you have modified a disk image, before +calling C. + +=head2 touch + + touch path + +Touch acts like the L command. It can be used to +update the timestamps on a file, or, if the file does not exist, +to create a new zero-length file. + +=head2 vgs + + vgs + +List all the volumes groups detected. This is the equivalent +of the L command. + +This returns a list of just the volume group names that were +detected (eg. C). + +See also C. + +=head2 vgs-full + + vgs-full + +List all the volumes groups detected. This is the equivalent +of the L command. The "full" version includes all fields. + diff --git a/guestfish.pod b/guestfish.pod new file mode 100644 index 0000000..e3e9c14 --- /dev/null +++ b/guestfish.pod @@ -0,0 +1,268 @@ +=encoding utf8 + +=head1 NAME + +guestfish - the libguestfs filesystem interactive shell + +=head1 SYNOPSIS + + guestfish [--options] [commands] + +=head1 EXAMPLES + +=head2 From shell scripts + +Create a new C file in a guest: + + guestfish <<_EOF_ + add disk.img + run + mount /dev/VolGroup00/LogVol00 / + upload new_motd /etc/motd + _EOF_ + +List the LVs in a guest: + + guestfish <<_EOF_ + add disk.img + run + lvs + _EOF_ + +=head2 On the command line + +List the LVM PVs in a guest image: + + guestfish add disk.img : run : pvs + +Remove C (in reality not such a great idea): + + guestfish --add disk.img \ + --mount /dev/VolGroup00/LogVol00 \ + --mount /dev/sda1:/boot \ + rm /boot/grub/menu.lst : \ + sync : exit + +=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 + + > help + +=head1 DESCRIPTION + +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. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Displays general help on options. + +=item B<-h> | B<--cmd-help> + +Lists all available guestfish commands. + +=item B<-h cmd> | B<--cmd-help cmd> + +Displays detailed help on a single command C. + +=item B<-a image> | B<--add image> + +Add a block device or virtual machine image to the shell. + +=item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]> + +Mount the named partition or logical volume on the given mountpoint. + +If the mountpoint is omitted, it defaults to C. + +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. + +=item B<-n> | B<--no-sync> + +Disable autosync. This is enabled by default. See the discussion +of autosync in the L manpage. + +=item B<-v> | B<--verbose> + +Enable very verbose messages. This is particularly useful if you find +a bug. + +=back + +=head1 COMMANDS ON COMMAND LINE + +Any additional (non-option) arguments are treated as commands to +execute. + +Commands to execute should be separated by a colon (C<:>), where the +colon is a separate parameter. Thus: + + guestfish cmd [args...] : cmd [args...] : cmd [args...] ... + +If there are no additional arguments, then we enter a shell, either an +interactive shell with a prompt (if the input is a terminal) or a +non-interactive shell. + +In either command line mode or non-interactive shell, the first +command that gives an error causes the whole shell to exit. In +interactive mode (with a prompt) if a command fails, you can continue +to enter commands. + +=head1 USING launch (OR run) + +As with L, you must first configure your guest by adding +disks, then launch it, then mount any disks you need, and finally +issue actions/commands. So the general order of the day is: + +=over 4 + +=item * + +add or -a/--add + +=item * + +launch (aka run) + +=item * + +mount or -m/--mount + +=item * + +any other commands + +=back + +C is a synonym for C. You must C (or C) +your guest before mounting or performing any other commands. + +The only exception is that if the C<-m> or C<--mount> option was +given, the guest is automatically run for you (simply because +guestfish can't mount the disks you asked for without doing this). + +=head1 COMMANDS + +=head2 help + + help + help cmd + +Without any parameter, this lists all commands. With a C +parameter, this displays detailed help for a command. + +=head2 quit | exit + +This exits guestfish. You can also use C<^D> key. + +=head2 add | drive | add-drive + + add filename + +This adds a block device to be examined or modified. + +=head2 cdrom | add-cdrom + + cdrom iso-file + +This adds a CD-ROM device to be examined. + +=head2 alloc | allocate + + alloc filename size + +This creates an empty (zeroed) file of the given size, and then adds +so it can be further examined. + +For more advanced image creation, see L utility. + +Size can be specified (where C means a number): + +=over 4 + +=item C + +number of kilobytes, eg: C<1440> = standard 3.5in floppy + +=item CK or CKB + +number of kilobytes + +=item CM or CMB + +number of megabytes + +=item CG or CGB + +number of gigabytes + +=item Csects + +number of 512 byte sectors + +=back + +=head2 launch | run + +Launch the guest so that you can issue other commands (see below). + +@ACTIONS@ + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item LIBGUESTFS_DEBUG + +Set C to enable verbose messages. This has the +same effect as using the B<-v> option. + +=item LIBGUESTFS_PATH + +Set the path that guestfish uses to search for kernel and initrd.img. +See the discussion of paths in L. + +=back + +=head1 SEE ALSO + +L, +L. + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. diff --git a/libguestfs.spec.in b/libguestfs.spec.in index edbc171..d4ca7b0 100644 --- a/libguestfs.spec.in +++ b/libguestfs.spec.in @@ -121,6 +121,7 @@ rm -rf $RPM_BUILD_ROOT %files -n guestfish %defattr(-,root,root,-) %{_bindir}/guestfish +%{_mandir}/man1/guestfish.1* %changelog diff --git a/src/generator.ml b/src/generator.ml index 5aaea82..427c9df 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -1249,6 +1249,22 @@ FTP." pr "}\n"; pr "\n" +(* Generate the POD documentation for guestfish. *) +and generate_fish_actions_pod () = + List.iter ( + fun (name, style, _, _, _, longdesc) -> + let name = replace name '_' '-' in + pr "=head2 %s\n\n" name; + pr " %s" name; + iter_args ( + function + | String n -> pr " %s" n + ) (snd style); + pr "\n"; + pr "\n"; + pr "%s\n\n" longdesc + ) sorted_functions + (* Generate a C function prototype. *) and generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true) ?(single_line = false) ?(newline = false) ?(in_daemon = false) @@ -1355,4 +1371,8 @@ let () = let close = output_to "guestfs-actions.pod" in generate_actions_pod (); + close (); + + let close = output_to "guestfish-actions.pod" in + generate_fish_actions_pod (); close ()