X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=172729ad9a8fdbb784ea547e5da71c1b300185bd;hp=93699d3e888917129273ab9c2f273c7806dac5f6;hb=a3cce465570bf192e993a67feedfbab7e662c75a;hpb=f341624668d10c58e2899354cef1e11c4175992a diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 93699d3..172729a 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -174,6 +174,10 @@ Add a block device or virtual machine image to the shell. The format of the disk image is auto-detected. To override this and 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. + =item B<-c URI> =item B<--connect URI> @@ -195,6 +199,10 @@ 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. +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. + =item B<-D> =item B<--no-dest-paths> @@ -272,6 +280,10 @@ versions of guestfish. You can still use the old syntax: guestfish [--ro] -i libvirt-domain +Using this flag is mostly equivalent to using the C +command and then using other commands to mount the filesystems that +were found. + =item B<--keys-from-stdin> Read key or passphrase parameters from stdin. The default is @@ -282,9 +294,14 @@ to try to read passphrases from the user by opening C. Fork into the background and listen for remote commands. See section L below. -=item B<-m dev[:mountpoint]> +=item B<--live> -=item B<--mount dev[:mountpoint]> +Connect to a live virtual machine. +(Experimental, see L). + +=item B<-m dev[:mountpoint[:options]]> + +=item B<--mount dev[:mountpoint[:options]]> Mount the named partition or logical volume on the given mountpoint. @@ -301,6 +318,18 @@ filesystems and LVs available (see L, L and L commands), or you can use the L program. +The third (and rarely used) part of the mount parameter is the list of +mount options used to mount the underlying filesystem. If this is not +given, then the mount options are either the empty string or C +(the latter if the I<--ro> flag is used). By specifying the mount +options, you override this default choice. Probably the only time you +would use this is to enable ACLs and/or extended attributes if the +filesystem can support them: + + -m /dev/sda1:/:acl,user_xattr + +Using this flag is equivalent to using the C command. + =item B<-n> =item B<--no-sync> @@ -339,15 +368,16 @@ L below. =item B<--ro> -This changes the I<-a> and I<-m> options so that disks are added and -mounts are done read-only (see L). +This changes the I<-a>, I<-d> and I<-m> options so that disks are +added and mounts are done read-only. 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. Note that prepared disk images created with I<-N> are not affected by -the I<--ro> option. +this option. Also commands like C are not affected - you have to +specify the C option explicitly if you need it. See also L below. @@ -372,7 +402,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> @@ -436,27 +468,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.8 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. +By libguestfs 1.12 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. @@ -660,6 +695,32 @@ C. (See C). To change the local directory, use the C command. C will have no effect, due to the way that subprocesses work in Unix. +=head2 LOCAL COMMANDS WITH INLINE EXECUTION + +If a line starts with I!> then the shell command is executed (as +for I), but subsequently any output (stdout) of the shell command +is parsed and executed as guestfish commands. + +Thus you can use shell script to construct arbitrary guestfish +commands which are then parsed by guestfish. + +For example it is tedious to create a sequence of files +(eg. C through C) using guestfish commands +alone. However this is simple if we use a shell script to +create the guestfish commands for us: + + : + + > character so it is +just an ordinary I local command), see what guestfish commands it +would run, and when you are happy with those prepend the C> +character to run the guestfish commands for real. + =head1 PIPES Use CspaceE | command> to pipe the output of the @@ -737,19 +798,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 @@ -1010,12 +1076,13 @@ set, it uses C. =item TMPDIR -Location of temporary directory, defaults to C. +Location of temporary directory, defaults to C except for the +cached supermin appliance which defaults to C. If libguestfs was compiled to use the supermin appliance then the real appliance is cached in this directory, shared between all handles belonging to the same EUID. You can use C<$TMPDIR> to -configure another directory to use in case C is not large +configure another directory to use in case C is not large enough. =back @@ -1024,6 +1091,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 @@ -1075,6 +1151,8 @@ Any existing file with the same name will be overwritten. L, L, L, +L, +L, L, L, L, @@ -1086,6 +1164,8 @@ L, L, L, L, +L, +L, L, L. @@ -1095,7 +1175,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