5 guestfish - the libguestfs Filesystem Interactive SHell
9 guestfish [--options] [commands]
15 guestfish -a disk.img -m dev[:mountpoint]
17 guestfish -d libvirt-domain
19 guestfish -a disk.img -i
21 guestfish -d libvirt-domain -i
25 Using guestfish in read/write mode on live virtual machines can be
26 dangerous, potentially causing disk corruption. Use the I<--ro>
27 (read-only) option to use guestfish safely if the disk image or
28 virtual machine might be live.
32 =head2 As an interactive shell
36 Welcome to guestfish, the libguestfs filesystem interactive shell for
37 editing virtual machine filesystems.
39 Type: 'help' for a list of commands
40 'man' to read the manual
41 'quit' to quit the shell
45 =head2 From shell scripts
47 Create a new C</etc/motd> file in a guest:
52 mount /dev/vg_guest/lv_root /
53 write /etc/motd "Welcome, new users"
56 List the LVM logical volumes in a guest:
58 guestfish -a disk.img --ro <<_EOF_
63 =head2 On one command line
65 Update C</etc/resolv.conf> in a guest:
68 add disk.img : run : mount /dev/vg_guest/lv_root / : \
69 write /etc/resolv.conf "nameserver 1.2.3.4"
71 Edit C</boot/grub/grub.conf> interactively:
73 guestfish --add disk.img \
74 --mount /dev/vg_guest/lv_root \
75 --mount /dev/sda1:/boot \
76 edit /boot/grub/grub.conf
78 =head2 Mount disks automatically
80 Use the I<-i> option to automatically mount the
81 disks from a virtual machine:
83 guestfish --ro -a disk.img -i cat /etc/group
85 guestfish --ro -d libvirt-domain -i cat /etc/group
87 =head2 As a script interpreter
89 Create a 100MB disk containing an ext2-formatted partition:
91 #!/usr/bin/guestfish -f
94 part-disk /dev/sda mbr
97 =head2 Start with a prepared disk
99 An alternate way to create a 100MB disk called C<test1.img> containing
100 a single ext2-formatted partition:
104 To list what is available do:
106 guestfish -N list | less
108 =head2 Remote control
110 eval `guestfish --listen --ro`
111 guestfish --remote add disk.img
112 guestfish --remote run
113 guestfish --remote lvs
117 Guestfish is a shell and command-line tool for examining and modifying
118 virtual machine filesystems. It uses libguestfs and exposes all of
119 the functionality of the guestfs API, see L<guestfs(3)>.
121 Guestfish gives you structured access to the libguestfs API, from
122 shell scripts or the command line or interactively. If you want to
123 rescue a broken virtual machine image, you should look at the
124 L<virt-rescue(1)> command.
132 Displays general help on options.
134 =item B<-h> | B<--cmd-help>
136 Lists all available guestfish commands.
138 =item B<-h cmd> | B<--cmd-help cmd>
140 Displays detailed help on a single command C<cmd>.
142 =item B<-a image> | B<--add image>
144 Add a block device or virtual machine image to the shell.
146 =item B<-c URI> | B<--connect URI>
148 When used in conjunction with the I<-d> option, this specifies
149 the libvirt URI to use. The default is to use the default libvirt
152 =item B<-d libvirt-domain> | B<--domain libvirt-domain>
154 Add disks from the named libvirt domain. If the I<--ro> option is
155 also used, then any libvirt domain can be used. However in write
156 mode, only libvirt domains which are shut down can be named here.
158 =item B<-D> | B<--no-dest-paths>
160 Don't tab-complete paths on the guest filesystem. It is useful to be
161 able to hit the tab key to complete paths on the guest filesystem, but
162 this causes extra "hidden" guestfs calls to be made, so this option is
163 here to allow this feature to be disabled.
165 =item B<-f file> | B<--file file>
167 Read commands from C<file>. To write pure guestfish
170 #!/usr/bin/guestfish -f
172 =item B<-i> | B<--inspector>
174 Using L<virt-inspector(1)> code, inspect the disks looking for
175 an operating system and mount filesystems as they would be
176 mounted on the real virtual machine.
178 Typical usage is either:
180 guestfish -d myguest -i
182 (for an inactive libvirt domain called I<myguest>), or:
184 guestfish --ro -d myguest -i
186 (for active domains, readonly), or specify the block device directly:
188 guestfish -a /dev/Guests/MyGuest -i
190 Note that the command line syntax changed slightly over older
191 versions of guestfish. You can still use the old syntax:
193 guestfish [--ro] -i disk.img
195 guestfish [--ro] -i libvirt-domain
197 =item B<--keys-from-stdin>
199 Read key or passphrase parameters from stdin. The default is
200 to try to read passphrases from the user by opening C</dev/tty>.
204 Fork into the background and listen for remote commands. See section
205 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
207 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
209 Mount the named partition or logical volume on the given mountpoint.
211 If the mountpoint is omitted, it defaults to C</>.
213 You have to mount something on C</> before most commands will work.
215 If any I<-m> or I<--mount> options are given, the guest is
216 automatically launched.
218 If you don't know what filesystems a disk image contains, you
219 can either run guestfish without this option, then list the partitions
220 and LVs available (see L</list-partitions> and L</lvs> commands),
221 or you can use the L<virt-list-filesystems(1)> program.
223 =item B<-n> | B<--no-sync>
225 Disable autosync. This is enabled by default. See the discussion
226 of autosync in the L<guestfs(3)> manpage.
228 =item B<-N type> | B<--new type> | B<-N list>
230 Prepare a fresh disk image formatted as "type". This is an
231 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
232 I<-N> creates a preformatted disk with a filesystem and adds it.
233 See L</PREPARED DISK IMAGES> below.
235 =item B<--remote[=pid]>
237 Send remote commands to C<$GUESTFISH_PID> or C<pid>. See section
238 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
240 =item B<-r> | B<--ro>
242 This changes the I<-a> and I<-m> options so that disks are added and
243 mounts are done read-only (see L<guestfs(3)/guestfs_mount_ro>).
245 The option must always be used if the disk image or virtual machine
246 might be running, and is generally recommended in cases where you
247 don't need write access to the disk.
249 Note that prepared disk images created with I<-N> are not affected by
254 Enable SELinux support for the guest. See L<guestfs(3)/SELINUX>.
256 =item B<-v> | B<--verbose>
258 Enable very verbose messages. This is particularly useful if you find
261 =item B<-V> | B<--version>
263 Display the guestfish / libguestfs version number and exit.
267 Echo each command before executing it.
271 =head1 COMMANDS ON COMMAND LINE
273 Any additional (non-option) arguments are treated as commands to
276 Commands to execute should be separated by a colon (C<:>), where the
277 colon is a separate parameter. Thus:
279 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
281 If there are no additional arguments, then we enter a shell, either an
282 interactive shell with a prompt (if the input is a terminal) or a
283 non-interactive shell.
285 In either command line mode or non-interactive shell, the first
286 command that gives an error causes the whole shell to exit. In
287 interactive mode (with a prompt) if a command fails, you can continue
290 =head1 USING launch (OR run)
292 As with L<guestfs(3)>, you must first configure your guest by adding
293 disks, then launch it, then mount any disks you need, and finally
294 issue actions/commands. So the general order of the day is:
316 C<run> is a synonym for C<launch>. You must C<launch> (or C<run>)
317 your guest before mounting or performing any other commands.
319 The only exception is that if the I<-m> or I<--mount> option was
320 given, the guest is automatically run for you (simply because
321 guestfish can't mount the disks you asked for without doing this).
325 You can quote ordinary parameters using either single or double
328 add "file with a space.img"
334 A few commands require a list of strings to be passed. For these, use
335 a whitespace-separated list, enclosed in quotes. Strings containing whitespace
336 to be passed through must be enclosed in single quotes. A literal single quote
337 must be escaped with a backslash.
339 vgcreate VG "/dev/sda1 /dev/sdb1"
340 command "/bin/echo 'foo bar'"
341 command "/bin/echo \'foo\'"
345 This section applies to all commands which can take integers
350 When the command takes a parameter measured in bytes, you can use one
351 of the following suffixes to specify kilobytes, megabytes and larger
356 =item B<k> or B<K> or B<KiB>
358 The size in kilobytes (multiplied by 1024).
362 The size in SI 1000 byte units.
366 The size in megabytes (multiplied by 1048576).
370 The size in SI 1000000 byte units.
374 The size in gigabytes (multiplied by 2**30).
378 The size in SI 10**9 byte units.
382 The size in terabytes (multiplied by 2**40).
386 The size in SI 10**12 byte units.
390 The size in petabytes (multiplied by 2**50).
394 The size in SI 10**15 byte units.
398 The size in exabytes (multiplied by 2**60).
402 The size in SI 10**18 byte units.
406 The size in zettabytes (multiplied by 2**70).
410 The size in SI 10**21 byte units.
414 The size in yottabytes (multiplied by 2**80).
418 The size in SI 10**24 byte units.
424 truncate-size /file 1G
426 would truncate the file to 1 gigabyte.
428 Be careful because a few commands take sizes in kilobytes or megabytes
429 (eg. the parameter to L</memsize> is specified in megabytes already).
430 Adding a suffix will probably not do what you expect.
432 =head2 OCTAL AND HEXADECIMAL NUMBERS
434 For specifying the radix (base) use the C convention: C<0> to prefix
435 an octal number or C<0x> to prefix a hexadecimal number. For example:
437 1234 decimal number 1234
438 02322 octal number, equivalent to decimal 1234
439 0x4d2 hexadecimal number, equivalent to decimal 1234
441 When using the C<chmod> command, you almost always want to specify an
442 octal number for the mode, and you must prefix it with C<0> (unlike
443 the Unix L<chmod(1)> program):
445 chmod 0777 /public # OK
446 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
448 Commands that return numbers usually print them in decimal, but
449 some commands print numbers in other radices (eg. C<umask> prints
450 the mode in octal, preceeded by C<0>).
452 =head1 WILDCARDS AND GLOBBING
454 Neither guestfish nor the underlying guestfs API performs
455 wildcard expansion (globbing) by default. So for example the
456 following will not do what you expect:
460 Assuming you don't have a directory literally called C</home/*>
461 then the above command will return an error.
463 To perform wildcard expansion, use the C<glob> command.
467 runs C<rm-rf> on each path that matches (ie. potentially running
468 the command many times), equivalent to:
474 C<glob> only works on simple guest paths and not on device names.
476 If you have several parameters, each containing a wildcard, then glob
477 will perform a cartesian product.
481 Any line which starts with a I<#> character is treated as a comment
482 and ignored. The I<#> can optionally be preceeded by whitespace,
483 but B<not> by a command. For example:
489 Blank lines are also ignored.
491 =head1 RUNNING COMMANDS LOCALLY
493 Any line which starts with a I<!> character is treated as a command
494 sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
498 tgz-out /remote local/remote-data.tar.gz
500 will create a directory C<local> on the host, and then export
501 the contents of C</remote> on the mounted filesystem to
502 C<local/remote-data.tar.gz>. (See C<tgz-out>).
504 To change the local directory, use the C<lcd> command. C<!cd> will
505 have no effect, due to the way that subprocesses work in Unix.
509 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
510 first command (a guestfish command) to the second command (any host
511 command). For example:
513 cat /etc/passwd | awk -F: '$3 == 0 { print }'
515 (where C<cat> is the guestfish cat command, but C<awk> is the host awk
516 program). The above command would list all accounts in the guest
517 filesystem which have UID 0, ie. root accounts including backdoors.
520 hexdump /bin/ls | head
521 list-devices | tail -1
522 tgz-out / - | tar ztf -
524 The space before the pipe symbol is required, any space after the pipe
525 symbol is optional. Everything after the pipe symbol is just passed
526 straight to the host shell, so it can contain redirections, globs and
527 anything else that makes sense on the host side.
529 To use a literal argument which begins with a pipe symbol, you have
534 =head1 HOME DIRECTORIES
536 If a parameter starts with the character C<~> then the tilde may be
537 expanded as a home directory path (either C<~> for the current user's
538 home directory, or C<~user> for another user).
540 Note that home directory expansion happens for users known I<on the
541 host>, not in the guest filesystem.
543 To use a literal argument which begins with a tilde, you have to quote
548 =head1 ENCRYPTED DISKS
550 Libguestfs has some support for Linux guests encrypted according to
551 the Linux Unified Key Setup (LUKS) standard, which includes nearly all
552 whole disk encryption systems used by modern Linux guests. Currently
553 only LVM-on-LUKS is supported.
555 Identify encrypted block devices and partitions using L</vfs-type>:
557 ><fs> vfs-type /dev/sda2
560 Then open those devices using L</luks-open>. This creates a
561 device-mapper device called C</dev/mapper/luksdev>.
563 ><fs> luks-open /dev/sda2 luksdev
564 Enter key or passphrase ("key"): <enter the passphrase>
566 Finally you have to tell LVM to scan for volume groups on
567 the newly created mapper device:
570 ><fs> vg-activate-all true
572 The logical volume(s) can now be mounted in the usual way.
574 Before closing a LUKS device you must unmount any logical volumes on
575 it and deactivate the volume groups by calling C<vg-activate false VG>
576 on each one. Then you can close the mapper device:
578 ><fs> vg-activate false /dev/VG
579 ><fs> luks-close /dev/mapper/luksdev
583 If a path is prefixed with C<win:> then you can use Windows-style
584 paths (with some limitations). The following commands are equivalent:
586 file /WINDOWS/system32/config/system.LOG
588 file win:/windows/system32/config/system.log
590 file win:\windows\system32\config\system.log
592 file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
594 This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
595 handles case insensitivity like Windows would. This only works in
596 argument positions that expect a path.
598 =head1 UPLOADING AND DOWNLOADING FILES
600 For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
601 others which upload from or download to a local file, you can use the
602 special filename C<-> to mean "from stdin" or "to stdout". For example:
606 reads stdin and creates from that a file C</foo> in the disk image,
609 tar-out /etc - | tar tf -
611 writes the tarball to stdout and then pipes that into the external
612 "tar" command (see L</PIPES>).
614 When using C<-> to read from stdin, the input is read up to the end of
615 stdin. You can also use a special "heredoc"-like syntax to read up to
616 some arbitrary end marker:
624 Any string of characters can be used instead of C<END>. The end
625 marker must appear on a line of its own, without any preceeding or
626 following characters (not even spaces).
628 Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
629 upload local files (so-called "FileIn" parameters in the generator).
631 =head1 EXIT ON ERROR BEHAVIOUR
633 By default, guestfish will ignore any errors when in interactive mode
634 (ie. taking commands from a human over a tty), and will exit on the
635 first error in non-interactive mode (scripts, commands given on the
638 If you prefix a command with a I<-> character, then that command will
639 not cause guestfish to exit, even if that (one) command returns an
642 =head1 REMOTE CONTROL GUESTFISH OVER A SOCKET
644 Guestfish can be remote-controlled over a socket. This is useful
645 particularly in shell scripts where you want to make several different
646 changes to a filesystem, but you don't want the overhead of starting
647 up a guestfish process each time.
649 Start a guestfish server process using:
651 eval `guestfish --listen`
653 and then send it commands by doing:
655 guestfish --remote cmd [...]
657 To cause the server to exit, send it the exit command:
659 guestfish --remote exit
661 Note that the server will normally exit if there is an error in a
662 command. You can change this in the usual way. See section
663 L</EXIT ON ERROR BEHAVIOUR>.
665 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
667 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
668 which is how the I<--remote> option knows where to send the commands.
669 You can have several guestfish listener processes running using:
671 eval `guestfish --listen`
673 eval `guestfish --listen`
676 guestfish --remote=$pid1 cmd
677 guestfish --remote=$pid2 cmd
679 =head2 REMOTE CONTROL DETAILS
681 Remote control happens over a Unix domain socket called
682 C</tmp/.guestfish-$UID/socket-$PID>, where C<$UID> is the effective
683 user ID of the process, and C<$PID> is the process ID of the server.
685 Guestfish client and server versions must match exactly.
687 =head1 PREPARED DISK IMAGES
689 Use the I<-N type> or I<--new type> parameter to select one of a set
690 of preformatted disk images that guestfish can make for you to save
691 typing. This is particularly useful for testing purposes. This
692 option is used instead of the I<-a> option, and like I<-a> can appear
693 multiple times (and can be mixed with I<-a>).
695 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
696 for the second and so on. Existing files in the current directory are
699 The type briefly describes how the disk should be sized, partitioned,
700 how filesystem(s) should be created, and how content should be added.
701 Optionally the type can be followed by extra parameters, separated by
702 C<:> (colon) characters. For example, I<-N fs> creates a default
703 100MB, sparsely-allocated disk, containing a single partition, with
704 the partition formatted as ext2. I<-N fs:ext4:1G> is the same, but
705 for an ext4 filesystem on a 1GB disk instead.
707 To list the available types and any extra parameters they take, run:
709 guestfish -N list | less
711 Note that the prepared filesystem is not mounted. You would usually
712 have to use the C<mount /dev/sda1 /> command or add the
713 I<-m /dev/sda1> option.
715 If any I<-N> or I<--new> options are given, the guest is automatically
720 Create a 100MB disk with an ext4-formatted partition:
724 Create a 32MB disk with a VFAT-formatted partition, and mount it:
726 guestfish -N fs:vfat:32M -m /dev/sda1
728 Create a blank 200MB disk:
730 guestfish -N disk:200M
732 =head1 GUESTFISH COMMANDS
734 The commands in this section are guestfish convenience commands, in
735 other words, they are not part of the L<guestfs(3)> API.
737 =head2 alloc | allocate
741 This creates an empty (zeroed) file of the given size, and then adds
742 so it can be further examined.
744 For more advanced image creation, see L<qemu-img(1)> utility.
746 Size can be specified using standard suffixes, eg. C<1M>.
752 This echos the parameters to the terminal.
754 =head2 edit | vi | emacs
758 This is used to edit a file. It downloads the file, edits it
759 locally using your editor, then uploads the result.
761 The editor is C<$EDITOR>. However if you use the alternate
762 commands C<vi> or C<emacs> you will get those corresponding
765 NOTE: This will not work reliably for large files
766 (> 2 MB) or binary files containing \0 bytes.
772 Expand wildcards in any paths in the args list, and run C<command>
773 repeatedly on each matching path.
775 See section WILDCARDS AND GLOBBING.
782 Without any parameter, this lists all commands. With a C<cmd>
783 parameter, this displays detailed help for a command.
789 Change the local directory, ie. the current directory of guestfish
792 Note that C<!cd> won't do what you might expect.
798 Opens the manual page for guestfish.
806 This is used to view a file.
808 The default viewer is C<$PAGER>. However if you use the alternate
809 command C<less> you will get the C<less> command specifically.
811 NOTE: This will not work reliably for large files
812 (> 2 MB) or binary files containing \0 bytes.
816 This exits guestfish. You can also use C<^D> key.
822 Close and reopen the libguestfs handle. It is not necessary to use
823 this normally, because the handle is closed properly when guestfish
824 exits. However this is occasionally useful for testing.
830 This creates an empty sparse file of the given size, and then adds
831 so it can be further examined.
833 In all respects it works the same as the C<alloc> command, except that
834 the image file is allocated sparsely, which means that disk blocks are
835 not assigned to the file until they are needed. Sparse disk files
836 only use space when written to, but they are slower and there is a
837 danger you could run out of real disk space during a write operation.
839 For more advanced image creation, see L<qemu-img(1)> utility.
841 Size can be specified using standard suffixes, eg. C<1M>.
847 This command returns a list of the optional groups
848 known to the daemon, and indicates which ones are
849 supported by this build of the libguestfs appliance.
851 See also L<guestfs(3)/AVAILABILITY>.
857 Run the command as usual, but print the elapsed time afterwards. This
858 can be useful for benchmarking operations.
866 guestfish returns 0 if the commands completed without error, or
867 1 if there was an error.
869 =head1 ENVIRONMENT VARIABLES
875 The C<edit> command uses C<$EDITOR> as the editor. If not
880 Used with the I<--remote> option to specify the remote guestfish
881 process to control. See section
882 L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
886 If compiled with GNU readline support, various files in the
887 home directory can be used. See L</FILES>.
889 =item LIBGUESTFS_APPEND
891 Pass additional options to the guest kernel.
893 =item LIBGUESTFS_DEBUG
895 Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This has the
896 same effect as using the B<-v> option.
898 =item LIBGUESTFS_MEMSIZE
900 Set the memory allocated to the qemu process, in megabytes. For
903 LIBGUESTFS_MEMSIZE=700
905 =item LIBGUESTFS_PATH
907 Set the path that guestfish uses to search for kernel and initrd.img.
908 See the discussion of paths in L<guestfs(3)>.
910 =item LIBGUESTFS_QEMU
912 Set the default qemu binary that libguestfs uses. If not set, then
913 the qemu which was found at compile time by the configure script is
916 =item LIBGUESTFS_TRACE
918 Set C<LIBGUESTFS_TRACE=1> to enable command traces.
922 The C<more> command uses C<$PAGER> as the pager. If not
923 set, it uses C<more>.
927 Location of temporary directory, defaults to C</tmp>.
929 If libguestfs was compiled to use the supermin appliance then each
930 handle will require rather a large amount of space in this directory
931 for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
932 configure another directory to use in case C</tmp> is not large
941 =item $HOME/.guestfish
943 If compiled with GNU readline support, then the command history
944 is saved in this file.
950 If compiled with GNU readline support, then these files can be used to
951 configure readline. For further information, please see
952 L<readline(3)/INITIALIZATION FILE>.
954 To write rules which only apply to guestfish, use:
960 Variables that you can set in inputrc that change the behaviour
961 of guestfish in useful ways include:
965 =item completion-ignore-case (default: on)
967 By default, guestfish will ignore case when tab-completing
968 paths on the disk. Use:
970 set completion-ignore-case off
972 to make guestfish case sensitive.
978 =item test2.img (etc)
980 When using the C<-N> or C<--new> option, the prepared disk or
981 filesystem will be created in the file C<test1.img> in the current
982 directory. The second use of C<-N> will use C<test2.img> and so on.
983 Any existing file with the same name will be overwritten.
990 L<http://libguestfs.org/>,
994 L<virt-list-filesystems(1)>,
995 L<virt-list-partitions(1)>,
1005 Richard W.M. Jones (C<rjones at redhat dot com>)
1009 Copyright (C) 2009-2010 Red Hat Inc.
1010 L<http://libguestfs.org/>
1012 This program is free software; you can redistribute it and/or modify
1013 it under the terms of the GNU General Public License as published by
1014 the Free Software Foundation; either version 2 of the License, or
1015 (at your option) any later version.
1017 This program is distributed in the hope that it will be useful,
1018 but WITHOUT ANY WARRANTY; without even the implied warranty of
1019 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1020 GNU General Public License for more details.
1022 You should have received a copy of the GNU General Public License
1023 along with this program; if not, write to the Free Software
1024 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.