X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=5737c464759ca1577245d41c7d036bc408c8def5;hp=b4cde8169ce8dfa76dc8444a20f1aa0adb4b110e;hb=21bd2db7cf259a17cc3922409937b849e4b83c0f;hpb=ce95be8b185ce697816c3446406d7129e01cc0e1 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index b4cde81..5737c46 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -18,6 +18,13 @@ guestfish - the libguestfs Filesystem Interactive SHell guestfish -i disk.img [disk.img ...] +=head1 WARNING + +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 EXAMPLES =head2 As an interactive shell @@ -27,10 +34,11 @@ guestfish - the libguestfs Filesystem Interactive SHell Welcome to guestfish, the libguestfs filesystem interactive shell for editing virtual machine filesystems. - Type: 'help' for help with commands + Type: 'help' for a list of commands + 'man' to read the manual 'quit' to quit the shell - > help + > man =head2 From shell scripts @@ -40,7 +48,7 @@ Create a new C file in a guest: add disk.img run mount /dev/vg_guest/lv_root / - write_file /etc/motd "Welcome, new users" 0 + write /etc/motd "Welcome, new users" _EOF_ List the LVM logical volumes in a guest: @@ -56,7 +64,7 @@ Update C in a guest: guestfish \ add disk.img : run : mount /dev/vg_guest/lv_root / : \ - write-file /etc/resolv.conf "nameserver 1.2.3.4" 0 + write /etc/resolv.conf "nameserver 1.2.3.4" Edit C interactively: @@ -112,11 +120,6 @@ shell scripts or the command line or interactively. If you want to rescue a broken virtual machine image, you should look at the L 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 @@ -319,9 +322,97 @@ must be escaped with a backslash. =head1 NUMBERS -Commands which take integers as parameters use the C convention which -is to use C<0> to prefix an octal number or C<0x> to prefix a -hexadecimal number. For example: +This section applies to all commands which can take integers +as parameters. + +=head2 SIZE SUFFIX + +When the command takes a parameter measured in bytes, you can use one +of the following suffixes to specify kilobytes, megabytes and larger +sizes: + +=over 4 + +=item B or B or B + +The size in kilobytes (multiplied by 1024). + +=item B + +The size in SI 1000 byte units. + +=item B or B + +The size in megabytes (multiplied by 1048576). + +=item B + +The size in SI 1000000 byte units. + +=item B or B + +The size in gigabytes (multiplied by 2**30). + +=item B + +The size in SI 10**9 byte units. + +=item B or B + +The size in terabytes (multiplied by 2**40). + +=item B + +The size in SI 10**12 byte units. + +=item B

or B + +The size in petabytes (multiplied by 2**50). + +=item B + +The size in SI 10**15 byte units. + +=item B or B + +The size in exabytes (multiplied by 2**60). + +=item B + +The size in SI 10**18 byte units. + +=item B or B + +The size in zettabytes (multiplied by 2**70). + +=item B + +The size in SI 10**21 byte units. + +=item B or B + +The size in yottabytes (multiplied by 2**80). + +=item B + +The size in SI 10**24 byte units. + +=back + +For example: + + truncate-size /file 1G + +would truncate the file to 1 gigabyte. + +Be careful because a few commands take sizes in kilobytes or megabytes +(eg. the parameter to L is specified in megabytes already). +Adding a suffix will probably not do what you expect. + +=head2 OCTAL AND HEXADECIMAL NUMBERS + +For specifying the radix (base) use the C convention: C<0> to prefix +an octal number or C<0x> to prefix a hexadecimal number. For example: 1234 decimal number 1234 02322 octal number, equivalent to decimal 1234 @@ -550,7 +641,7 @@ multiple times (and can be mixed with I<-a>). The new disk is called C for the first I<-N>, C for the second and so on. Existing files in the current directory are -not overwritten, so you may need to do C. +I. The type briefly describes how the disk should be sized, partitioned, how filesystem(s) should be created, and how content should be added. @@ -599,39 +690,7 @@ 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 or CK or CKB - -number of kilobytes, eg: C<1440> = standard 3.5in floppy - -=item CM or CMB - -number of megabytes - -=item CG or CGB - -number of gigabytes - -=item CT or CTB - -number of terabytes - -=item CP or CPB - -number of petabytes - -=item CE or CEB - -number of exabytes - -=item Csects - -number of 512 byte sectors - -=back +Size can be specified using standard suffixes, eg. C<1M>. =head2 echo @@ -679,6 +738,12 @@ itself. Note that C won't do what you might expect. +=head2 man | manual + + man + +Opens the manual page for guestfish. + =head2 more | less more filename @@ -720,39 +785,17 @@ danger you could run out of real disk space during a write operation. For more advanced image creation, see L utility. -Size can be specified (where C means a number): +Size can be specified using standard suffixes, eg. C<1M>. -=over 4 +=head2 supported -=item C or CK or CKB + supported -number of kilobytes, eg: C<1440> = standard 3.5in floppy +This command returns a list of the optional groups +known to the daemon, and indicates which ones are +supported by this build of the libguestfs appliance. -=item CM or CMB - -number of megabytes - -=item CG or CGB - -number of gigabytes - -=item CT or CTB - -number of terabytes - -=item CP or CPB - -number of petabytes - -=item CE or CEB - -number of exabytes - -=item Csects - -number of 512 byte sectors - -=back +See also L. =head2 time @@ -765,6 +808,11 @@ can be useful for benchmarking operations. @ACTIONS@ +=head1 EXIT CODE + +guestfish returns 0 if the commands completed without error, or +1 if there was an error. + =head1 ENVIRONMENT VARIABLES =over 4 @@ -782,8 +830,8 @@ L. =item HOME -If compiled with GNU readline support, then the command history -is saved in C<$HOME/.guestfish> +If compiled with GNU readline support, various files in the +home directory can be used. See L. =item LIBGUESTFS_APPEND @@ -833,10 +881,55 @@ enough. =back -=head1 EXIT CODE +=head1 FILES -guestfish returns 0 if the commands completed without error, or -1 if there was an error. +=over 4 + +=item $HOME/.guestfish + +If compiled with GNU readline support, then the command history +is saved in this file. + +=item $HOME/.inputrc + +=item /etc/inputrc + +If compiled with GNU readline support, then these files can be used to +configure readline. For further information, please see +L. + +To write rules which only apply to guestfish, use: + + $if guestfish + ... + $endif + +Variables that you can set in inputrc that change the behaviour +of guestfish in useful ways include: + +=over 4 + +=item completion-ignore-case (default: on) + +By default, guestfish will ignore case when tab-completing +paths on the disk. Use: + + set completion-ignore-case off + +to make guestfish case sensitive. + +=back + +=item test1.img + +=item test2.img (etc) + +When using the C<-N> or C<--new> option, the prepared disk or +filesystem will be created in the file C in the current +directory. The second use of C<-N> will use C and so on. +Any existing file with the same name will be overwritten. + +=back =head1 SEE ALSO