X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=fish%2Fguestfish.pod;h=aeb4c8da81604c11327edafba857d28353f643bd;hp=165cdf28f4fa05a3933d0f143dbd26374a7327db;hb=639ca1828b167bf59353f0cd3c8c79c6289bbd5d;hpb=4a9b979a3199dfef64a342f05d666da540203a7c diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 165cdf2..aeb4c8d 100644 --- 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 -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 @@ -27,10 +36,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 +50,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 +66,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: @@ -65,13 +75,14 @@ Edit C interactively: --mount /dev/sda1:/boot \ edit /boot/grub/grub.conf -=head2 Using virt-inspector +=head2 Mount disks automatically -Use the I<-i> option to get virt-inspector to mount -the filesystems automatically as they would be mounted -in the virtual machine: +Use the I<-i> option to automatically mount the +disks from a virtual machine: - guestfish --ro -i disk.img cat /etc/group + guestfish --ro -a disk.img -i cat /etc/group + + guestfish --ro -d libvirt-domain -i cat /etc/group =head2 As a script interpreter @@ -92,7 +103,7 @@ a single ext2-formatted partition: To list what is available do: - guestfish -N list | less + guestfish -N help | less =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 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 @@ -137,6 +143,18 @@ Displays detailed help on a single command C. 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 @@ -153,28 +171,33 @@ scripts, use: =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 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: - guestfish -i myguest + guestfish -d myguest -i (for an inactive libvirt domain called I), or: - guestfish --ro -i myguest + guestfish --ro -d myguest -i (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 + + guestfish [--ro] -i libvirt-domain -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. +=item B<--keys-from-stdin> -See also: L. +Read key or passphrase parameters from stdin. The default is +to try to read passphrases from the user by opening C. =item B<--listen> @@ -202,13 +225,24 @@ or you can use the L program. Disable autosync. This is enabled by default. See the discussion of autosync in the L 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 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. See section @@ -319,9 +353,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 @@ -434,6 +556,39 @@ it, eg: 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 /dev/sda2 + crypto_LUKS + +Then open those devices using L. This creates a +device-mapper device called C. + + > luks-open /dev/sda2 luksdev + Enter key or passphrase ("key"): + +Finally you have to tell LVM to scan for volume groups on +the newly created mapper device: + + > vgscan + > 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 +on each one. Then you can close the mapper device: + + > vg-activate false /dev/VG + > luks-close /dev/mapper/luksdev + =head1 WINDOWS PATHS If a path is prefixed with C then you can use Windows-style @@ -451,6 +606,39 @@ 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. +=head1 UPLOADING AND DOWNLOADING FILES + +For commands such as C, C, C, C and +others which upload from or download to a local file, you can use the +special filename C<-> to mean "from stdin" or "to stdout". For example: + + upload - /foo + +reads stdin and creates from that a file C in the disk image, +and: + + tar-out /etc - | tar tf - + +writes the tarball to stdout and then pipes that into the external +"tar" command (see L). + +When using C<-> to read from stdin, the input is read up to the end of +stdin. You can also use a special "heredoc"-like syntax to read up to +some arbitrary end marker: + + upload -<. The end +marker must appear on a line of its own, without any preceeding or +following characters (not even spaces). + +Note that the C<-EE> syntax only applies to parameters used to +upload local files (so-called "FileIn" parameters in the generator). + =head1 EXIT ON ERROR BEHAVIOUR By default, guestfish will ignore any errors when in interactive mode @@ -517,7 +705,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. @@ -529,7 +717,7 @@ for an ext4 filesystem on a 1GB disk instead. 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 command or add the @@ -552,38 +740,30 @@ Create a blank 200MB disk: guestfish -N disk:200M -=head1 UPLOADING AND DOWNLOADING FILES - -For commands such as C, C, C, C and -others which upload from or download to a local file, you can use the -special filename C<-> to mean "from stdin" or "to stdout". For example: - - upload - /foo +=head1 PROGRESS BARS -reads stdin and creates from that a file C in the disk image, -and: +Some (not all) long-running commands send progress notification +messages as they are running. Guestfish turns these messages into +progress bars. - tar-out /etc - | tar tf - - -writes the tarball to stdout and then pipes that into the external -"tar" command (see L). - -When using C<-> to read from stdin, the input is read up to the end of -stdin. You can also use a special "heredoc"-like syntax to read up to -some arbitrary end marker: +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: - upload -< copy-size /large-file /another-file 2048M + / 10% [#####-----------------------------------------] 00:30 -Any string of characters can be used instead of C. The end -marker must appear on a line of its own, without any preceeding or -following characters (not even spaces). +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. -Note that the C<-EE> syntax only applies to parameters used to -upload local files (so-called "FileIn" parameters in the generator). +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 @@ -599,39 +779,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 @@ -650,9 +798,6 @@ The editor is C<$EDITOR>. However if you use the alternate commands C or C 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... @@ -679,6 +824,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 @@ -690,9 +841,6 @@ This is used to view a file. The default viewer is C<$PAGER>. However if you use the alternate command C you will get the C 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. @@ -720,39 +868,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): - -=over 4 - -=item C or CK or CKB - -number of kilobytes, eg: C<1440> = standard 3.5in floppy - -=item CM or CMB +Size can be specified using standard suffixes, eg. C<1M>. -number of megabytes +=head2 supported -=item CG or CGB + supported -number of gigabytes +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 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 +891,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 +913,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 +964,55 @@ enough. =back -=head1 EXIT CODE +=head1 FILES + +=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: -guestfish returns I<0> if the commands completed without error, or -I<1> if there was an error. +=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 @@ -860,7 +1036,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009 Red Hat Inc. +Copyright (C) 2009-2010 Red Hat Inc. L This program is free software; you can redistribute it and/or modify