X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=1c708693a5eea58e342a0ab8388c2e4cb55de37e;hp=cc974d7142fcf7d5a1461467509e787747201e2b;hb=34a306ab2a7e6d9f468e8194cef8a05624325260;hpb=78d2523ec8997679f7fca810de60620df4001e16 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index cc974d7..1c70869 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 @@ -41,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: @@ -57,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: @@ -113,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 @@ -320,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 @@ -551,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. @@ -600,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 @@ -727,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 - -=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 +=head2 supported -number of exabytes + supported -=item Csects +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. -number of 512 byte sectors - -=back +See also L. =head2 time @@ -772,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 @@ -840,11 +881,6 @@ enough. =back -=head1 EXIT CODE - -guestfish returns 0 if the commands completed without error, or -1 if there was an error. - =head1 SEE ALSO L,