fish: Implement copy-in and copy-out commands.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index b4cde81..70de8e3 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -14,9 +14,18 @@ guestfish - the libguestfs Filesystem Interactive SHell
 
  guestfish -a disk.img -m dev[:mountpoint]
 
 
  guestfish -a disk.img -m dev[:mountpoint]
 

- guestfish -i libvirt-domain
+ guestfish -d libvirt-domain

 
 

- guestfish -i disk.img [disk.img ...]
+ guestfish -a disk.img -i
+
+ guestfish -d libvirt-domain -i
+
+=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
 
 
 =head1 EXAMPLES
 


@@ -27,10 +36,11 @@ guestfish - the libguestfs Filesystem Interactive SHell
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  
  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
  
        'quit' to quit the shell
  

- ><fs> help
+ ><fs> man

 
 =head2 From shell scripts
 
 
 =head2 From shell scripts
 


@@ -40,7 +50,7 @@ Create a new C</etc/motd> file in a guest:
  add disk.img
  run
  mount /dev/vg_guest/lv_root /
  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:
  _EOF_
 
 List the LVM logical volumes in a guest:


@@ -56,7 +66,7 @@ Update C</etc/resolv.conf> in a guest:
 
  guestfish \
    add disk.img : run : mount /dev/vg_guest/lv_root / : \
 
  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</boot/grub/grub.conf> interactively:
 
 
 Edit C</boot/grub/grub.conf> interactively:
 


@@ -65,13 +75,14 @@ Edit C</boot/grub/grub.conf> interactively:
    --mount /dev/sda1:/boot \
    edit /boot/grub/grub.conf
 
    --mount /dev/sda1:/boot \
    edit /boot/grub/grub.conf
 

-=head2 Using virt-inspector
+=head2 Mount disks automatically
+
+Use the I<-i> option to automatically mount the
+disks from a virtual machine:

 
 

-Use the I<-i> option to get virt-inspector to mount
-the filesystems automatically as they would be mounted
-in the virtual machine:
+ guestfish --ro -a disk.img -i cat /etc/group

 
 

- guestfish --ro -i disk.img cat /etc/group
+ guestfish --ro -d libvirt-domain -i cat /etc/group

 
 =head2 As a script interpreter
 
 
 =head2 As a script interpreter
 


@@ -92,7 +103,7 @@ a single ext2-formatted partition:
 
 To list what is available do:
 
 
 To list what is available do:
 

- guestfish -N list | less
+ guestfish -N help | less

 
 =head2 Remote control
 
 
 =head2 Remote control
 


@@ -112,11 +123,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<virt-rescue(1)> command.
 
 rescue a broken virtual machine image, you should look at the
 L<virt-rescue(1)> 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
 =head1 OPTIONS
 
 =over 4


@@ -137,6 +143,18 @@ Displays detailed help on a single command C<cmd>.
 
 Add a block device or virtual machine image to the shell.
 
 
 Add a block device or virtual machine image to the shell.
 

+=item B<-c URI> | B<--connect URI>
+
+When used in conjunction with the I<-d> option, this specifies
+the libvirt URI to use.  The default is to use the default libvirt
+connection.
+
+=item B<-d libvirt-domain> | B<--domain libvirt-domain>
+
+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.
+

 =item B<-D> | B<--no-dest-paths>
 
 Don't tab-complete paths on the guest filesystem.  It is useful to be
 =item B<-D> | B<--no-dest-paths>
 
 Don't tab-complete paths on the guest filesystem.  It is useful to be


@@ -153,28 +171,33 @@ scripts, use:
 
 =item B<-i> | B<--inspector>
 
 
 =item B<-i> | B<--inspector>
 

-Run virt-inspector on the named libvirt domain or list of disk
-images.  If virt-inspector is available and if it can identify
-the domain or disk images, then partitions will be mounted
-correctly at start-up.
+Using L<virt-inspector(1)> code, inspect the disks looking for
+an operating system and mount filesystems as they would be
+mounted on the real virtual machine.

 
 Typical usage is either:
 
 
 Typical usage is either:
 

- guestfish -i myguest
+ guestfish -d myguest -i

 
 (for an inactive libvirt domain called I<myguest>), or:
 
 
 (for an inactive libvirt domain called I<myguest>), or:
 

- guestfish --ro -i myguest
+ guestfish --ro -d myguest -i

 
 (for active domains, readonly), or specify the block device directly:
 
 
 (for active domains, readonly), or specify the block device directly:
 

- guestfish -i /dev/Guests/MyGuest
+ guestfish -a /dev/Guests/MyGuest -i
+
+Note that the command line syntax changed slightly over older
+versions of guestfish.  You can still use the old syntax:
+
+ guestfish [--ro] -i disk.img

 
 

-You cannot use I<-a>, I<-m>, I<-N>, I<--listen>, I<--remote> or
-I<--selinux> in conjunction with this option, and options other than
-I<--ro> might not behave correctly.
+ guestfish [--ro] -i libvirt-domain

 
 

-See also: L<virt-inspector(1)>.
+=item B<--keys-from-stdin>
+
+Read key or passphrase parameters from stdin.  The default is
+to try to read passphrases from the user by opening C</dev/tty>.

 
 =item B<--listen>
 
 
 =item B<--listen>
 


@@ -202,13 +225,24 @@ or you can use the L<virt-list-filesystems(1)> program.
 Disable autosync.  This is enabled by default.  See the discussion
 of autosync in the L<guestfs(3)> manpage.
 
 Disable autosync.  This is enabled by default.  See the discussion
 of autosync in the L<guestfs(3)> manpage.
 

-=item B<-N type> | B<--new type> | B<-N list>
+=item B<-N type> | B<--new type> | B<-N help>

 
 Prepare a fresh disk image formatted as "type".  This is an
 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
 I<-N> creates a preformatted disk with a filesystem and adds it.
 See L</PREPARED DISK IMAGES> below.
 
 
 Prepare a fresh disk image formatted as "type".  This is an
 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
 I<-N> creates a preformatted disk with a filesystem and adds it.
 See L</PREPARED DISK IMAGES> below.
 

+=item B<--progress-bars>
+
+Enable progress bars, even when guestfish is used non-interactively.
+
+Progress bars are enabled by default when guestfish is used as an
+interactive shell.
+
+=item B<--no-progress-bars>
+
+Disable progress bars.
+

 =item B<--remote[=pid]>
 
 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
 =item B<--remote[=pid]>
 
 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section


@@ -319,9 +353,97 @@ must be escaped with a backslash.
 
 =head1 NUMBERS
 
 
 =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<k> or B<K> or B<KiB>
+
+The size in kilobytes (multiplied by 1024).
+
+=item B<KB>
+
+The size in SI 1000 byte units.
+
+=item B<M> or B<MiB>
+
+The size in megabytes (multiplied by 1048576).
+
+=item B<MB>
+
+The size in SI 1000000 byte units.
+
+=item B<G> or B<GiB>
+
+The size in gigabytes (multiplied by 2**30).
+
+=item B<GB>
+
+The size in SI 10**9 byte units.
+
+=item B<T> or B<TiB>
+
+The size in terabytes (multiplied by 2**40).
+
+=item B<TB>
+
+The size in SI 10**12 byte units.
+
+=item B<P> or B<PiB>
+
+The size in petabytes (multiplied by 2**50).
+
+=item B<PB>
+
+The size in SI 10**15 byte units.
+
+=item B<E> or B<EiB>
+
+The size in exabytes (multiplied by 2**60).
+
+=item B<EB>
+
+The size in SI 10**18 byte units.
+
+=item B<Z> or B<ZiB>
+
+The size in zettabytes (multiplied by 2**70).
+
+=item B<ZB>
+
+The size in SI 10**21 byte units.
+
+=item B<Y> or B<YiB>
+
+The size in yottabytes (multiplied by 2**80).
+
+=item B<YB>
+
+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</memsize> 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
 
  1234      decimal number 1234
  02322     octal number, equivalent to decimal 1234


@@ -434,6 +556,39 @@ it, eg:
 
  echo "~"
 
 
  echo "~"
 

+=head1 ENCRYPTED DISKS
+
+Libguestfs has some support for Linux guests encrypted according to
+the Linux Unified Key Setup (LUKS) standard, which includes nearly all
+whole disk encryption systems used by modern Linux guests.  Currently
+only LVM-on-LUKS is supported.
+
+Identify encrypted block devices and partitions using L</vfs-type>:
+
+ ><fs> vfs-type /dev/sda2
+ crypto_LUKS
+
+Then open those devices using L</luks-open>.  This creates a
+device-mapper device called C</dev/mapper/luksdev>.
+
+ ><fs> luks-open /dev/sda2 luksdev
+ Enter key or passphrase ("key"): <enter the passphrase>
+
+Finally you have to tell LVM to scan for volume groups on
+the newly created mapper device:
+
+ ><fs> vgscan
+ ><fs> vg-activate-all true
+
+The logical volume(s) can now be mounted in the usual way.
+
+Before closing a LUKS device you must unmount any logical volumes on
+it and deactivate the volume groups by calling C<vg-activate false VG>
+on each one.  Then you can close the mapper device:
+
+ ><fs> vg-activate false /dev/VG
+ ><fs> luks-close /dev/mapper/luksdev
+

 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style
 =head1 WINDOWS PATHS
 
 If a path is prefixed with C<win:> then you can use Windows-style


@@ -550,7 +705,7 @@ multiple times (and can be mixed with I<-a>).
 
 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
 for the second and so on.  Existing files in the current directory are
 
 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
 for the second and so on.  Existing files in the current directory are

-not overwritten, so you may need to do C<rm -f test1.img>.
+I<overwritten>.

 
 The type briefly describes how the disk should be sized, partitioned,
 how filesystem(s) should be created, and how content should be added.
 
 The type briefly describes how the disk should be sized, partitioned,
 how filesystem(s) should be created, and how content should be added.


@@ -562,7 +717,7 @@ for an ext4 filesystem on a 1GB disk instead.
 
 To list the available types and any extra parameters they take, run:
 
 
 To list the available types and any extra parameters they take, run:
 

- guestfish -N list | less
+ guestfish -N help | less

 
 Note that the prepared filesystem is not mounted.  You would usually
 have to use the C<mount /dev/sda1 /> command or add the
 
 Note that the prepared filesystem is not mounted.  You would usually
 have to use the C<mount /dev/sda1 /> command or add the


@@ -585,6 +740,31 @@ Create a blank 200MB disk:
 
  guestfish -N disk:200M
 
 
  guestfish -N disk:200M
 

+=head1 PROGRESS BARS
+
+Some (not all) long-running commands send progress notification
+messages as they are running.  Guestfish turns these messages into
+progress bars.
+
+When a command that supports progress bars takes longer than two
+seconds to run, and if progress bars are enabled, then you will see
+one appearing below the command:
+
+ ><fs> copy-size /large-file /another-file 2048M
+ / 10% [#####-----------------------------------------] 00:30
+
+The spinner on the left hand side moves round once for every progress
+notification received from the backend.  This is a (reasonably) golden
+assurance that the command is "doing something" even if the progress
+bar is not moving, because the command is able to send the progress
+notifications.  When the bar reaches 100% and the command finishes,
+the spinner disappears.
+
+Progress bars are enabled by default when guestfish is used
+interactively.  You can enable them even for non-interactive modes
+using I<--progress-bars>, and you can disable them completely using
+I<--no-progress-bars>.
+

 =head1 GUESTFISH COMMANDS
 
 The commands in this section are guestfish convenience commands, in
 =head1 GUESTFISH COMMANDS
 
 The commands in this section are guestfish convenience commands, in


@@ -599,39 +779,41 @@ so it can be further examined.
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 

-Size can be specified (where C<nn> means a number):
-
-=over 4
-
-=item C<nn> or C<nn>K or C<nn>KB
-
-number of kilobytes, eg: C<1440> = standard 3.5in floppy
-
-=item C<nn>M or C<nn>MB
-
-number of megabytes
+Size can be specified using standard suffixes, eg. C<1M>.

 
 

-=item C<nn>G or C<nn>GB
+=head2 copy-in

 
 

-number of gigabytes
+ copy-in local [local ...] /remotedir

 
 

-=item C<nn>T or C<nn>TB
+C<copy-in> copies local files or directories recursively into the disk
+image, placing them in the directory called C</remotedir> (which must
+exist).  This guestfish meta-command turns into a sequence of
+L</tar-in> and other commands as necessary.

 
 

-number of terabytes
+Multiple local files and directories can be specified, but the last
+parameter must always be a remote directory.  Wildcards cannot be
+used.

 
 

-=item C<nn>P or C<nn>PB
+=head2 copy-out

 
 

-number of petabytes
+ copy-out remote [remote ...] localdir

 
 

-=item C<nn>E or C<nn>EB
+C<copy-out> copies remote files or directories recursively out of the
+disk image, placing them on the host disk in a local directory called
+C<localdir> (which must exist).  This guestfish meta-command turns
+into a sequence of L</download>, L</tar-out> and other commands as
+necessary.

 
 

-number of exabytes
+Multiple remote files and directories can be specified, but the last
+parameter must always be a local directory.  To download to the
+current directory, use C<.> as in:

 
 

-=item C<nn>sects
+ copy-out /home .

 
 

-number of 512 byte sectors
+Wildcards cannot be used in the ordinary command, but you can use
+this with the help of L</glob> like this:

 
 

-=back
+ glob copy-out /home/* .

 
 =head2 echo
 
 
 =head2 echo
 


@@ -650,9 +832,6 @@ The editor is C<$EDITOR>.  However if you use the alternate
 commands C<vi> or C<emacs> you will get those corresponding
 editors.
 
 commands C<vi> or C<emacs> you will get those corresponding
 editors.
 

-NOTE: This will not work reliably for large files
-(> 2 MB) or binary files containing \0 bytes.
-

 =head2 glob
 
  glob command args...
 =head2 glob
 
  glob command args...


@@ -679,6 +858,12 @@ itself.
 
 Note that C<!cd> won't do what you might expect.
 
 
 Note that C<!cd> won't do what you might expect.
 

+=head2 man | manual
+
+ man
+
+Opens the manual page for guestfish.
+

 =head2 more | less
 
  more filename
 =head2 more | less
 
  more filename


@@ -690,9 +875,6 @@ This is used to view a file.
 The default viewer is C<$PAGER>.  However if you use the alternate
 command C<less> you will get the C<less> command specifically.
 
 The default viewer is C<$PAGER>.  However if you use the alternate
 command C<less> you will get the C<less> command specifically.
 

-NOTE: This will not work reliably for large files
-(> 2 MB) or binary files containing \0 bytes.
-

 =head2 quit | exit
 
 This exits guestfish.  You can also use C<^D> key.
 =head2 quit | exit
 
 This exits guestfish.  You can also use C<^D> key.


@@ -720,39 +902,17 @@ danger you could run out of real disk space during a write operation.
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 
 
 For more advanced image creation, see L<qemu-img(1)> utility.
 

-Size can be specified (where C<nn> means a number):
-
-=over 4
-
-=item C<nn> or C<nn>K or C<nn>KB
-
-number of kilobytes, eg: C<1440> = standard 3.5in floppy
-
-=item C<nn>M or C<nn>MB
-
-number of megabytes
-
-=item C<nn>G or C<nn>GB
-
-number of gigabytes
-
-=item C<nn>T or C<nn>TB
-
-number of terabytes
-
-=item C<nn>P or C<nn>PB
+Size can be specified using standard suffixes, eg. C<1M>.

 
 

-number of petabytes
+=head2 supported

 
 

-=item C<nn>E or C<nn>EB
+ supported

 
 

-number of exabytes
+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 C<nn>sects
-
-number of 512 byte sectors
-
-=back
+See also L<guestfs(3)/AVAILABILITY>.

 
 =head2 time
 
 
 =head2 time
 


@@ -765,6 +925,11 @@ can be useful for benchmarking operations.
 
 @ACTIONS@
 
 
 @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
 =head1 ENVIRONMENT VARIABLES
 
 =over 4


@@ -782,8 +947,8 @@ L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
 
 =item HOME
 
 
 =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</FILES>.

 
 =item LIBGUESTFS_APPEND
 
 
 =item LIBGUESTFS_APPEND
 


@@ -833,10 +998,55 @@ enough.
 
 =back
 
 
 =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<readline(3)/INITIALIZATION FILE>.
+
+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<test1.img> in the current
+directory.  The second use of C<-N> will use C<test2.img> and so on.
+Any existing file with the same name will be overwritten.
+
+=back

 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO