X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=17e0da0abb96be0e759b97602c52081a6042859d;hp=98286d188e8966aec91cdd591ad08bbaa65a6d3c;hb=fac15924f59a076c903d453d20305e00e1ae258a;hpb=4e529e06a4500959cd783f5029354fea47a253a6 diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 98286d1..17e0da0 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -176,7 +176,7 @@ force a particular format use the I<--format=..> option. Using this flag is mostly equivalent to using the C command, with C if the I<--ro> flag was given, and -with C if the I<--format:...> flag was given. +with C if the I<--format=...> flag was given. =item B<-c URI> @@ -199,6 +199,8 @@ Add disks from the named libvirt domain. If the I<--ro> option is also used, then any libvirt domain can be used. However in write mode, only libvirt domains which are shut down can be named here. +Domain UUIDs can be used instead of names. + Using this flag is mostly equivalent to using the C command, with C if the I<--ro> flag was given, and with C if the I<--format:...> flag was given. @@ -402,7 +404,9 @@ Display the guestfish / libguestfs version number and exit. =item B<--rw> -This option does nothing at the moment. +This changes the I<-a>, I<-d> and I<-m> options so that disks are +added and mounts are done read-write. + See L below. =item B<-x> @@ -466,27 +470,30 @@ asked for without doing this. =head1 OPENING DISKS FOR READ AND WRITE -The guestfish (and L) options I<--ro> and I<--rw> -affect whether the other command line options I<-a>, I<-c>, I<-d>, -I<-i> and I<-m> open disk images read-only or for writing. +The guestfish, L and L options I<--ro> +and I<--rw> affect whether the other command line options I<-a>, +I<-c>, I<-d>, I<-i> and I<-m> open disk images read-only or for +writing. -In libguestfs E 1.6.2, guestfish and guestmount defaulted to -opening disk images supplied on the command line for write. To open a -disk image read-only you have to do I<-a image --ro>. +In libguestfs E 1.10, guestfish, guestmount and virt-rescue +defaulted to opening disk images supplied on the command line for +write. To open a disk image read-only you have to do I<-a image --ro>. This matters: If you accidentally open a live VM disk image writable then you will cause irreversible disk corruption. -By libguestfs 1.10 we intend to change the default the other way. Disk -images will be opened read-only. You will have to either specify -I or change a configuration file in order to get write -access for disk images specified by those other command line options. +In a future libguestfs we intend to change the default the other way. +Disk images will be opened read-only. You will have to either specify +I, I, I, or change +the configuration file C in order to get +write access for disk images specified by those other command line +options. -This version of guestfish has a I<--rw> option which does nothing (it -is already the default). However it is highly recommended that you -use this option to indicate that guestfish needs write access, and to -prepare your scripts for the day when this option will be required for -write access. +This version of guestfish, guestmount and virt-rescue has a I<--rw> +option which does nothing (it is already the default). However it is +highly recommended that you use this option to indicate that you need +write access, and prepare your scripts for the day when this option +will be required for write access. B This does I affect commands like L and L, or any other libguestfs program apart from guestfish and guestmount. @@ -511,6 +518,64 @@ must be escaped with a backslash. command "/bin/echo 'foo bar'" command "/bin/echo \'foo\'" +=head2 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS + +In double-quoted arguments (only) use backslash to insert special +characters: + +=over 4 + +=item C<\a> + +Alert (bell) character. + +=item C<\b> + +Backspace character. + +=item C<\f> + +Form feed character. + +=item C<\n> + +Newline character. + +=item C<\r> + +Carriage return character. + +=item C<\t> + +Horizontal tab character. + +=item C<\v> + +Vertical tab character. + +=item C<\"> + +A literal double quote character. + +=item C<\ooo> + +A character with octal value I. There must be precisely 3 octal +digits (unlike C). + +=item C<\xhh> + +A character with hex value I. There must be precisely 2 hex +digits. + +In the current implementation C<\000> and C<\x00> cannot be used +in strings. + +=item C<\\> + +A literal backslash character. + +=back + =head1 OPTIONAL ARGUMENTS Some commands take optional arguments. These arguments appear in this @@ -793,19 +858,24 @@ on each one. Then you can close the mapper device: =head1 WINDOWS PATHS If a path is prefixed with C then you can use Windows-style -paths (with some limitations). The following commands are equivalent: +drive letters and paths (with some limitations). The following +commands are equivalent: file /WINDOWS/system32/config/system.LOG - file win:/windows/system32/config/system.log - file win:\windows\system32\config\system.log - file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG + file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG -This syntax implicitly calls C (q.v.) so it also -handles case insensitivity like Windows would. This only works in -argument positions that expect a path. +The parameter is rewritten "behind the scenes" by looking up the +position where the drive is mounted, prepending that to the path, +changing all backslash characters to forward slash, then resolving the +result using L. For example if the E: drive +was mounted on C then the parameter might be rewritten like this: + + win:e:\foo\bar => /e/FOO/bar + +This only works in argument positions that expect a path. =head1 UPLOADING AND DOWNLOADING FILES @@ -903,6 +973,17 @@ user ID of the process, and C<$PID> is the process ID of the server. Guestfish client and server versions must match exactly. +=head2 REMOTE CONTROL RUN COMMAND HANGING + +Using the C (or C) command remotely in a command +substitution context hangs, ie. don't do (note the backquotes): + + a=`guestfish --remote run` + +Since the C command produces no output on stdout, this is not +useful anyway. For further information see +L. + =head1 PREPARED DISK IMAGES Use the I<-N type> or I<--new type> parameter to select one of a set @@ -997,7 +1078,7 @@ This exits guestfish. You can also use C<^D> key. @ACTIONS@ -=head1 EXIT CODE +=head1 EXIT STATUS guestfish returns 0 if the commands completed without error, or 1 if there was an error. @@ -1011,6 +1092,21 @@ guestfish returns 0 if the commands completed without error, or The C command uses C<$EDITOR> as the editor. If not set, it uses C. +=item FEBOOTSTRAP_KERNEL + +=item FEBOOTSTRAP_MODULES + +These two environment variables allow the kernel that libguestfs uses +in the appliance to be selected. If C<$FEBOOTSTRAP_KERNEL> is not +set, then the most recent host kernel is chosen. For more information +about kernel selection, see L. This +feature is only available in febootstrap E 3.8. + +=item GUESTFISH_DISPLAY_IMAGE + +The C command uses C<$GUESTFISH_DISPLAY_IMAGE> to +display images. If not set, it uses L. + =item GUESTFISH_PID Used with the I<--remote> option to specify the remote guestfish @@ -1081,6 +1177,15 @@ enough. =over 4 +=item $HOME/.libguestfs-tools.rc + +=item /etc/libguestfs-tools.conf + +This configuration file controls the default read-only or read-write +mode (I<--ro> or I<--rw>). + +See L. + =item $HOME/.guestfish If compiled with GNU readline support, then the command history @@ -1120,9 +1225,9 @@ to make guestfish case sensitive. =item test2.img (etc) -When using the C<-N> or C<--new> option, the prepared disk or +When using the I<-N> or I<--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. +directory. The second use of I<-N> will use C and so on. Any existing file with the same name will be overwritten. =back @@ -1144,11 +1249,14 @@ L, L, L, L, +L, L, L, L, L, -L. +L, +L, +L. =head1 AUTHORS @@ -1156,7 +1264,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009-2010 Red Hat Inc. +Copyright (C) 2009-2011 Red Hat Inc. L This program is free software; you can redistribute it and/or modify