1guestfish(1) Virtualization Support guestfish(1)
2
6 guestfish - the libguestfs Filesystem Interactive SHell
7
9 guestfish [--options] [commands]
10 guestfish
12 guestfish [--ro|--rw] -a disk.img
14 guestfish [--ro|--rw] -a disk.img -m dev[:mountpoint]
16 guestfish -d libvirt-domain
18 guestfish [--ro|--rw] -a disk.img -i
20 guestfish -d libvirt-domain -i
22
24 Using guestfish in read/write mode on live virtual machines can be
25 dangerous, potentially causing disk corruption. Use the --ro (read-
26 only) option to use guestfish safely if the disk image or virtual
27 machine might be live.
28
30 Guestfish is a shell and command-line tool for examining and modifying
31 virtual machine filesystems. It uses libguestfs and exposes all of the
32 functionality of the guestfs API, see guestfs(3).
33 Guestfish gives you structured access to the libguestfs API, from shell
35 scripts or the command line or interactively. If you want to rescue a
36 broken virtual machine image, you should look at the virt-rescue(1)
37 command.
38
40 As an interactive shell
41 $ guestfish
42 Welcome to guestfish, the libguestfs filesystem interactive shell for
44 editing virtual machine filesystems.
45 Type: 'help' for a list of commands
47 'man' to read the manual
48 'quit' to quit the shell
49 ><fs> add-ro disk.img
51 ><fs> run
52 ><fs> list-filesystems
53 /dev/sda1: ext4
54 /dev/vg_guest/lv_root: ext4
55 /dev/vg_guest/lv_swap: swap
56 ><fs> mount /dev/vg_guest/lv_root /
57 ><fs> cat /etc/fstab
58 # /etc/fstab
59 # Created by anaconda
60 [...]
61 ><fs> exit
62 From shell scripts
64 Create a new "/etc/motd" file in a guest or disk image:
65 guestfish <<_EOF_
67 add disk.img
68 run
69 mount /dev/vg_guest/lv_root /
70 write /etc/motd "Welcome, new users"
71 _EOF_
72 List the LVM logical volumes in a disk image:
74 guestfish -a disk.img --ro <<_EOF_
76 run
77 lvs
78 _EOF_
79 List all the filesystems in a disk image:
81 guestfish -a disk.img --ro <<_EOF_
83 run
84 list-filesystems
85 _EOF_
86 On one command line
88 Update "/etc/resolv.conf" in a guest:
89 guestfish \
91 add disk.img : run : mount /dev/vg_guest/lv_root / : \
92 write /etc/resolv.conf "nameserver 1.2.3.4"
93 Edit "/boot/grub/grub.conf" interactively:
95 guestfish --rw --add disk.img \
97 --mount /dev/vg_guest/lv_root \
98 --mount /dev/sda1:/boot \
99 edit /boot/grub/grub.conf
100 Mount disks automatically
102 Use the -i option to automatically mount the disks from a virtual
103 machine:
104 guestfish --ro -a disk.img -i cat /etc/group
106 guestfish --ro -d libvirt-domain -i cat /etc/group
108 Another way to edit "/boot/grub/grub.conf" interactively is:
110 guestfish --rw -a disk.img -i edit /boot/grub/grub.conf
112 As a script interpreter
114 Create a 100MB disk containing an ext2-formatted partition:
115 #!/usr/bin/guestfish -f
117 sparse test1.img 100M
118 run
119 part-disk /dev/sda mbr
120 mkfs ext2 /dev/sda1
121 Start with a prepared disk
123 An alternate way to create a 100MB disk called "test1.img" containing a
124 single ext2-formatted partition:
125 guestfish -N fs
127 To list what is available do:
129 guestfish -N help | less
131 Remote control
133 eval "`guestfish --listen`"
134 guestfish --remote add-ro disk.img
135 guestfish --remote run
136 guestfish --remote lvs
137
139 --help
140 Displays general help on options.
141 -h
143 --cmd-help
144 Lists all available guestfish commands.
145 -h cmd
147 --cmd-help cmd
148 Displays detailed help on a single command "cmd".
149 -a image
151 --add image
152 Add a block device or virtual machine image to the shell.
153 The format of the disk image is auto-detected. To override this
155 and force a particular format use the --format=.. option.
156 Using this flag is mostly equivalent to using the "add" command,
158 with "readonly:true" if the --ro flag was given, and with
159 "format:..." if the --format=... flag was given.
160 -c URI
162 --connect URI
163 When used in conjunction with the -d option, this specifies the
164 libvirt URI to use. The default is to use the default libvirt
165 connection.
166 --csh
168 If using the --listen option and a csh-like shell, use this option.
169 See section "REMOTE CONTROL AND CSH" below.
170 -d libvirt-domain
172 --domain libvirt-domain
173 Add disks from the named libvirt domain. If the --ro option is
174 also used, then any libvirt domain can be used. However in write
175 mode, only libvirt domains which are shut down can be named here.
176 Using this flag is mostly equivalent to using the "add-domain"
178 command, with "readonly:true" if the --ro flag was given, and with
179 "format:..." if the --format:... flag was given.
180 -D
182 --no-dest-paths
183 Don't tab-complete paths on the guest filesystem. It is useful to
184 be able to hit the tab key to complete paths on the guest
185 filesystem, but this causes extra "hidden" guestfs calls to be
186 made, so this option is here to allow this feature to be disabled.
187 --echo-keys
189 When prompting for keys and passphrases, guestfish normally turns
190 echoing off so you cannot see what you are typing. If you are not
191 worried about Tempest attacks and there is no one else in the room
192 you can specify this flag to see what you are typing.
193 -f file
195 --file file
196 Read commands from "file". To write pure guestfish scripts, use:
197 #!/usr/bin/guestfish -f
199 --format=raw|qcow2|..
201 --format
202 The default for the -a option is to auto-detect the format of the
203 disk image. Using this forces the disk format for -a options which
204 follow on the command line. Using --format with no argument
205 switches back to auto-detection for subsequent -a options.
206 For example:
208 guestfish --format=raw -a disk.img
210 forces raw format (no auto-detection) for "disk.img".
212 guestfish --format=raw -a disk.img --format -a another.img
214 forces raw format (no auto-detection) for "disk.img" and reverts to
216 auto-detection for "another.img".
217 If you have untrusted raw-format guest disk images, you should use
219 this option to specify the disk format. This avoids a possible
220 security problem with malicious guests (CVE-2010-3851). See also
221 "add-drive-opts".
222 -i
224 --inspector
225 Using virt-inspector(1) code, inspect the disks looking for an
226 operating system and mount filesystems as they would be mounted on
227 the real virtual machine.
228 Typical usage is either:
230 guestfish -d myguest -i
232 (for an inactive libvirt domain called myguest), or:
234 guestfish --ro -d myguest -i
236 (for active domains, readonly), or specify the block device
238 directly:
239 guestfish --rw -a /dev/Guests/MyGuest -i
241 Note that the command line syntax changed slightly over older
243 versions of guestfish. You can still use the old syntax:
244 guestfish [--ro] -i disk.img
246 guestfish [--ro] -i libvirt-domain
248 Using this flag is mostly equivalent to using the "inspect-os"
250 command and then using other commands to mount the filesystems that
251 were found.
252 --keys-from-stdin
254 Read key or passphrase parameters from stdin. The default is to
255 try to read passphrases from the user by opening "/dev/tty".
256 --listen
258 Fork into the background and listen for remote commands. See
259 section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
260 -m dev[:mountpoint]
262 --mount dev[:mountpoint]
263 Mount the named partition or logical volume on the given
264 mountpoint.
265 If the mountpoint is omitted, it defaults to "/".
267 You have to mount something on "/" before most commands will work.
269 If any -m or --mount options are given, the guest is automatically
271 launched.
272 If you don't know what filesystems a disk image contains, you can
274 either run guestfish without this option, then list the partitions,
275 filesystems and LVs available (see "list-partitions", "list-
276 filesystems" and "lvs" commands), or you can use the
277 virt-filesystems(1) program.
278 Using this flag is mostly equivalent to using the "mount-options"
280 command or the "mount-ro" command if the --ro flag was given.
281 -n
283 --no-sync
284 Disable autosync. This is enabled by default. See the discussion
285 of autosync in the guestfs(3) manpage.
286 -N type
288 --new type
289 -N help
290 Prepare a fresh disk image formatted as "type". This is an
291 alternative to the -a option: whereas -a adds an existing disk, -N
292 creates a preformatted disk with a filesystem and adds it. See
293 "PREPARED DISK IMAGES" below.
294 --progress-bars
296 Enable progress bars, even when guestfish is used non-
297 interactively.
298 Progress bars are enabled by default when guestfish is used as an
300 interactive shell.
301 --no-progress-bars
303 Disable progress bars.
304 --remote[=pid]
306 Send remote commands to $GUESTFISH_PID or "pid". See section
307 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
308 -r
310 --ro
311 This changes the -a, -d and -m options so that disks are added and
312 mounts are done read-only.
313 The option must always be used if the disk image or virtual machine
315 might be running, and is generally recommended in cases where you
316 don't need write access to the disk.
317 Note that prepared disk images created with -N are not affected by
319 this option. Also commands like "add" are not affected - you have
320 to specify the "readonly:true" option explicitly if you need it.
321 See also "OPENING DISKS FOR READ AND WRITE" below.
323 --selinux
325 Enable SELinux support for the guest. See "SELINUX" in guestfs(3).
326 -v
328 --verbose
329 Enable very verbose messages. This is particularly useful if you
330 find a bug.
331 -V
333 --version
334 Display the guestfish / libguestfs version number and exit.
335 -w
337 --rw
338 This option does nothing at the moment. See "OPENING DISKS FOR
339 READ AND WRITE" below.
340 -x Echo each command before executing it.
342
344 Any additional (non-option) arguments are treated as commands to
345 execute.
346 Commands to execute should be separated by a colon (":"), where the
348 colon is a separate parameter. Thus:
349 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
351 If there are no additional arguments, then we enter a shell, either an
353 interactive shell with a prompt (if the input is a terminal) or a non-
354 interactive shell.
355 In either command line mode or non-interactive shell, the first command
357 that gives an error causes the whole shell to exit. In interactive
358 mode (with a prompt) if a command fails, you can continue to enter
359 commands.
360
362 As with guestfs(3), you must first configure your guest by adding
363 disks, then launch it, then mount any disks you need, and finally issue
364 actions/commands. So the general order of the day is:
365 · add or -a/--add
367 · launch (aka run)
369 · mount or -m/--mount
371 · any other commands
373 "run" is a synonym for "launch". You must "launch" (or "run") your
375 guest before mounting or performing any other commands.
376 The only exception is that if any of the -i, -m, --mount, -N or --new
378 options were given then "run" is done automatically, simply because
379 guestfish can't perform the action you asked for without doing this.
380
382 The guestfish (and guestmount(1)) options --ro and --rw affect whether
383 the other command line options -a, -c, -d, -i and -m open disk images
384 read-only or for writing.
385 In libguestfs < 1.6.2, guestfish and guestmount defaulted to opening
387 disk images supplied on the command line for write. To open a disk
388 image read-only you have to do -a image --ro.
389 This matters: If you accidentally open a live VM disk image writable
391 then you will cause irreversible disk corruption.
392 By libguestfs 1.10 we intend to change the default the other way. Disk
394 images will be opened read-only. You will have to either specify
395 guestfish --rw or change a configuration file in order to get write
396 access for disk images specified by those other command line options.
397 This version of guestfish has a --rw option which does nothing (it is
399 already the default). However it is highly recommended that you use
400 this option to indicate that guestfish needs write access, and to
401 prepare your scripts for the day when this option will be required for
402 write access.
403 Note: This does not affect commands like "add" and "mount", or any
405 other libguestfs program apart from guestfish and guestmount.
406
408 You can quote ordinary parameters using either single or double quotes.
409 For example:
410 add "file with a space.img"
412 rm '/file name'
414 rm '/"'
416 A few commands require a list of strings to be passed. For these, use
418 a whitespace-separated list, enclosed in quotes. Strings containing
419 whitespace to be passed through must be enclosed in single quotes. A
420 literal single quote must be escaped with a backslash.
421 vgcreate VG "/dev/sda1 /dev/sdb1"
423 command "/bin/echo 'foo bar'"
424 command "/bin/echo \'foo\'"
425
427 Some commands take optional arguments. These arguments appear in this
428 documentation as "[argname:..]". You can use them as in these
429 examples:
430 add-drive-opts filename
432 add-drive-opts filename readonly:true
434 add-drive-opts filename format:qcow2 readonly:false
436 Each optional argument can appear at most once. All optional arguments
438 must appear after the required ones.
439
441 This section applies to all commands which can take integers as
442 parameters.
443 SIZE SUFFIX
445 When the command takes a parameter measured in bytes, you can use one
446 of the following suffixes to specify kilobytes, megabytes and larger
447 sizes:
448 k or K or KiB
450 The size in kilobytes (multiplied by 1024).
451 KB The size in SI 1000 byte units.
453 M or MiB
455 The size in megabytes (multiplied by 1048576).
456 MB The size in SI 1000000 byte units.
458 G or GiB
460 The size in gigabytes (multiplied by 2**30).
461 GB The size in SI 10**9 byte units.
463 T or TiB
465 The size in terabytes (multiplied by 2**40).
466 TB The size in SI 10**12 byte units.
468 P or PiB
470 The size in petabytes (multiplied by 2**50).
471 PB The size in SI 10**15 byte units.
473 E or EiB
475 The size in exabytes (multiplied by 2**60).
476 EB The size in SI 10**18 byte units.
478 Z or ZiB
480 The size in zettabytes (multiplied by 2**70).
481 ZB The size in SI 10**21 byte units.
483 Y or YiB
485 The size in yottabytes (multiplied by 2**80).
486 YB The size in SI 10**24 byte units.
488 For example:
490 truncate-size /file 1G
492 would truncate the file to 1 gigabyte.
494 Be careful because a few commands take sizes in kilobytes or megabytes
496 (eg. the parameter to "memsize" is specified in megabytes already).
497 Adding a suffix will probably not do what you expect.
498 OCTAL AND HEXADECIMAL NUMBERS
500 For specifying the radix (base) use the C convention: 0 to prefix an
501 octal number or "0x" to prefix a hexadecimal number. For example:
502 1234 decimal number 1234
504 02322 octal number, equivalent to decimal 1234
505 0x4d2 hexadecimal number, equivalent to decimal 1234
506 When using the "chmod" command, you almost always want to specify an
508 octal number for the mode, and you must prefix it with 0 (unlike the
509 Unix chmod(1) program):
510 chmod 0777 /public # OK
512 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
513 Commands that return numbers usually print them in decimal, but some
515 commands print numbers in other radices (eg. "umask" prints the mode in
516 octal, preceeded by 0).
517
519 Neither guestfish nor the underlying guestfs API performs wildcard
520 expansion (globbing) by default. So for example the following will not
521 do what you expect:
522 rm-rf /home/*
524 Assuming you don't have a directory called literally "/home/*" then the
526 above command will return an error.
527 To perform wildcard expansion, use the "glob" command.
529 glob rm-rf /home/*
531 runs "rm-rf" on each path that matches (ie. potentially running the
533 command many times), equivalent to:
534 rm-rf /home/jim
536 rm-rf /home/joe
537 rm-rf /home/mary
538 "glob" only works on simple guest paths and not on device names.
540 If you have several parameters, each containing a wildcard, then glob
542 will perform a Cartesian product.
543
545 Any line which starts with a # character is treated as a comment and
546 ignored. The # can optionally be preceeded by whitespace, but not by a
547 command. For example:
548 # this is a comment
550 # this is a comment
551 foo # NOT a comment
552 Blank lines are also ignored.
554
556 Any line which starts with a ! character is treated as a command sent
557 to the local shell ("/bin/sh" or whatever system(3) uses). For
558 example:
559 !mkdir local
561 tgz-out /remote local/remote-data.tar.gz
562 will create a directory "local" on the host, and then export the
564 contents of "/remote" on the mounted filesystem to
565 "local/remote-data.tar.gz". (See "tgz-out").
566 To change the local directory, use the "lcd" command. "!cd" will have
568 no effect, due to the way that subprocesses work in Unix.
569
571 Use "command <space> | command" to pipe the output of the first command
572 (a guestfish command) to the second command (any host command). For
573 example:
574 cat /etc/passwd | awk -F: '$3 == 0 { print }'
576 (where "cat" is the guestfish cat command, but "awk" is the host awk
578 program). The above command would list all accounts in the guest
579 filesystem which have UID 0, ie. root accounts including backdoors.
580 Other examples:
581 hexdump /bin/ls | head
583 list-devices | tail -1
584 tgz-out / - | tar ztf -
585 The space before the pipe symbol is required, any space after the pipe
587 symbol is optional. Everything after the pipe symbol is just passed
588 straight to the host shell, so it can contain redirections, globs and
589 anything else that makes sense on the host side.
590 To use a literal argument which begins with a pipe symbol, you have to
592 quote it, eg:
593 echo "|"
595
597 If a parameter starts with the character "~" then the tilde may be
598 expanded as a home directory path (either "~" for the current user's
599 home directory, or "~user" for another user).
600 Note that home directory expansion happens for users known on the host,
602 not in the guest filesystem.
603 To use a literal argument which begins with a tilde, you have to quote
605 it, eg:
606 echo "~"
608
610 Libguestfs has some support for Linux guests encrypted according to the
611 Linux Unified Key Setup (LUKS) standard, which includes nearly all
612 whole disk encryption systems used by modern Linux guests. Currently
613 only LVM-on-LUKS is supported.
614 Identify encrypted block devices and partitions using "vfs-type":
616 ><fs> vfs-type /dev/sda2
618 crypto_LUKS
619 Then open those devices using "luks-open". This creates a device-
621 mapper device called "/dev/mapper/luksdev".
622 ><fs> luks-open /dev/sda2 luksdev
624 Enter key or passphrase ("key"): <enter the passphrase>
625 Finally you have to tell LVM to scan for volume groups on the newly
627 created mapper device:
628 vgscan
630 vg-activate-all true
631 The logical volume(s) can now be mounted in the usual way.
633 Before closing a LUKS device you must unmount any logical volumes on it
635 and deactivate the volume groups by calling "vg-activate false VG" on
636 each one. Then you can close the mapper device:
637 vg-activate false /dev/VG
639 luks-close /dev/mapper/luksdev
640
642 If a path is prefixed with "win:" then you can use Windows-style paths
643 (with some limitations). The following commands are equivalent:
644 file /WINDOWS/system32/config/system.LOG
646 file win:/windows/system32/config/system.log
648 file win:\windows\system32\config\system.log
650 file WIN:C:\Windows\SYSTEM32\conFIG\SYSTEM.LOG
652 This syntax implicitly calls "case-sensitive-path" (q.v.) so it also
654 handles case insensitivity like Windows would. This only works in
655 argument positions that expect a path.
656
658 For commands such as "upload", "download", "tar-in", "tar-out" and
659 others which upload from or download to a local file, you can use the
660 special filename "-" to mean "from stdin" or "to stdout". For example:
661 upload - /foo
663 reads stdin and creates from that a file "/foo" in the disk image, and:
665 tar-out /etc - | tar tf -
667 writes the tarball to stdout and then pipes that into the external
669 "tar" command (see "PIPES").
670 When using "-" to read from stdin, the input is read up to the end of
672 stdin. You can also use a special "heredoc"-like syntax to read up to
673 some arbitrary end marker:
674 upload -<<END /foo
676 input line 1
677 input line 2
678 input line 3
679 END
680 Any string of characters can be used instead of "END". The end marker
682 must appear on a line of its own, without any preceeding or following
683 characters (not even spaces).
684 Note that the "-<<" syntax only applies to parameters used to upload
686 local files (so-called "FileIn" parameters in the generator).
687
689 By default, guestfish will ignore any errors when in interactive mode
690 (ie. taking commands from a human over a tty), and will exit on the
691 first error in non-interactive mode (scripts, commands given on the
692 command line).
693 If you prefix a command with a - character, then that command will not
695 cause guestfish to exit, even if that (one) command returns an error.
696
698 Guestfish can be remote-controlled over a socket. This is useful
699 particularly in shell scripts where you want to make several different
700 changes to a filesystem, but you don't want the overhead of starting up
701 a guestfish process each time.
702 Start a guestfish server process using:
704 eval "`guestfish --listen`"
706 and then send it commands by doing:
708 guestfish --remote cmd [...]
710 To cause the server to exit, send it the exit command:
712 guestfish --remote exit
714 Note that the server will normally exit if there is an error in a
716 command. You can change this in the usual way. See section "EXIT ON
717 ERROR BEHAVIOUR".
718 CONTROLLING MULTIPLE GUESTFISH PROCESSES
720 The "eval" statement sets the environment variable $GUESTFISH_PID,
721 which is how the --remote option knows where to send the commands. You
722 can have several guestfish listener processes running using:
723 eval "`guestfish --listen`"
725 pid1=$GUESTFISH_PID
726 eval "`guestfish --listen`"
727 pid2=$GUESTFISH_PID
728 ...
729 guestfish --remote=$pid1 cmd
730 guestfish --remote=$pid2 cmd
731 REMOTE CONTROL AND CSH
733 When using csh-like shells (csh, tcsh etc) you have to add the --csh
734 option:
735 eval "`guestfish --listen --csh`"
737 REMOTE CONTROL DETAILS
739 Remote control happens over a Unix domain socket called
740 "/tmp/.guestfish-$UID/socket-$PID", where $UID is the effective user ID
741 of the process, and $PID is the process ID of the server.
742 Guestfish client and server versions must match exactly.
744 REMOTE CONTROL RUN COMMAND HANGING
746 Using the "run" (or "launch") command remotely in a command
747 substitution context hangs, ie. don't do (note the backquotes):
748 a=`guestfish --remote run`
750 Since the "run" command produces no output on stdout, this is not
752 useful anyway. For further information see
753 <https://bugzilla.redhat.com/show_bug.cgi?id=592910>.
754
756 Use the -N type or --new type parameter to select one of a set of
757 preformatted disk images that guestfish can make for you to save
758 typing. This is particularly useful for testing purposes. This option
759 is used instead of the -a option, and like -a can appear multiple times
760 (and can be mixed with -a).
761 The new disk is called "test1.img" for the first -N, "test2.img" for
763 the second and so on. Existing files in the current directory are
764 overwritten.
765 The type briefly describes how the disk should be sized, partitioned,
767 how filesystem(s) should be created, and how content should be added.
768 Optionally the type can be followed by extra parameters, separated by
769 ":" (colon) characters. For example, -N fs creates a default 100MB,
770 sparsely-allocated disk, containing a single partition, with the
771 partition formatted as ext2. -N fs:ext4:1G is the same, but for an
772 ext4 filesystem on a 1GB disk instead.
773 To list the available types and any extra parameters they take, run:
775 guestfish -N help | less
777 Note that the prepared filesystem is not mounted. You would usually
779 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
780 option.
781 If any -N or --new options are given, the guest is automatically
783 launched.
784 EXAMPLES
786 Create a 100MB disk with an ext4-formatted partition:
787 guestfish -N fs:ext4
789 Create a 32MB disk with a VFAT-formatted partition, and mount it:
791 guestfish -N fs:vfat:32M -m /dev/sda1
793 Create a blank 200MB disk:
795 guestfish -N disk:200M
797
799 Some (not all) long-running commands send progress notification
800 messages as they are running. Guestfish turns these messages into
801 progress bars.
802 When a command that supports progress bars takes longer than two
804 seconds to run, and if progress bars are enabled, then you will see one
805 appearing below the command:
806 ><fs> copy-size /large-file /another-file 2048M
808 / 10% [#####-----------------------------------------] 00:30
809 The spinner on the left hand side moves round once for every progress
811 notification received from the backend. This is a (reasonably) golden
812 assurance that the command is "doing something" even if the progress
813 bar is not moving, because the command is able to send the progress
814 notifications. When the bar reaches 100% and the command finishes, the
815 spinner disappears.
816 Progress bars are enabled by default when guestfish is used
818 interactively. You can enable them even for non-interactive modes
819 using --progress-bars, and you can disable them completely using
820 --no-progress-bars.
821
823 The commands in this section are guestfish convenience commands, in
824 other words, they are not part of the guestfs(3) API.
825 help
827 help
828 help cmd
829 Without any parameter, this provides general help.
831 With a "cmd" parameter, this displays detailed help for that command.
833 quit | exit
835 This exits guestfish. You can also use "^D" key.
836 alloc
838 allocate
839 alloc filename size
840 This creates an empty (zeroed) file of the given size, and then adds so
842 it can be further examined.
843 For more advanced image creation, see qemu-img(1) utility.
845 Size can be specified using standard suffixes, eg. "1M".
847 To create a sparse file, use "sparse" instead. To create a prepared
849 disk image, see "PREPARED DISK IMAGES".
850 copy-in
852 copy-in local [local ...] /remotedir
853 "copy-in" copies local files or directories recursively into the disk
855 image, placing them in the directory called "/remotedir" (which must
856 exist). This guestfish meta-command turns into a sequence of "tar-in"
857 and other commands as necessary.
858 Multiple local files and directories can be specified, but the last
860 parameter must always be a remote directory. Wildcards cannot be used.
861 copy-out
863 copy-out remote [remote ...] localdir
864 "copy-out" copies remote files or directories recursively out of the
866 disk image, placing them on the host disk in a local directory called
867 "localdir" (which must exist). This guestfish meta-command turns into
868 a sequence of "download", "tar-out" and other commands as necessary.
869 Multiple remote files and directories can be specified, but the last
871 parameter must always be a local directory. To download to the current
872 directory, use "." as in:
873 copy-out /home .
875 Wildcards cannot be used in the ordinary command, but you can use them
877 with the help of "glob" like this:
878 glob copy-out /home/* .
880 echo
882 echo [params ...]
883 This echos the parameters to the terminal.
885 edit
887 vi
888 emacs
889 edit filename
890 This is used to edit a file. It downloads the file, edits it locally
892 using your editor, then uploads the result.
893 The editor is $EDITOR. However if you use the alternate commands "vi"
895 or "emacs" you will get those corresponding editors.
896 glob
898 glob command args...
899 Expand wildcards in any paths in the args list, and run "command"
901 repeatedly on each matching path.
902 See "WILDCARDS AND GLOBBING".
904 hexedit
906 hexedit <filename|device>
907 hexedit <filename|device> <max>
908 hexedit <filename|device> <start> <max>
909 Use hexedit (a hex editor) to edit all or part of a binary file or
911 block device.
912 This command works by downloading potentially the whole file or device,
914 editing it locally, then uploading it. If the file or device is large,
915 you have to specify which part you wish to edit by using "max" and/or
916 "start" "max" parameters. "start" and "max" are specified in bytes,
917 with the usual modifiers allowed such as "1M" (1 megabyte).
918 For example to edit the first few sectors of a disk you might do:
920 hexedit /dev/sda 1M
922 which would allow you to edit anywhere within the first megabyte of the
924 disk.
925 To edit the superblock of an ext2 filesystem on "/dev/sda1", do:
927 hexedit /dev/sda1 0x400 0x400
929 (assuming the superblock is in the standard location).
931 This command requires the external hexedit(1) program. You can specify
933 another program to use by setting the "HEXEDITOR" environment variable.
934 See also "hexdump".
936 lcd
938 lcd directory
939 Change the local directory, ie. the current directory of guestfish
941 itself.
942 Note that "!cd" won't do what you might expect.
944 man
946 manual
947 man
948 Opens the manual page for guestfish.
950 more
952 less
953 more filename
954 less filename
956 This is used to view a file.
958 The default viewer is $PAGER. However if you use the alternate command
960 "less" you will get the "less" command specifically.
961 reopen
963 reopen
964 Close and reopen the libguestfs handle. It is not necessary to use
966 this normally, because the handle is closed properly when guestfish
967 exits. However this is occasionally useful for testing.
968 sparse
970 sparse filename size
971 This creates an empty sparse file of the given size, and then adds so
973 it can be further examined.
974 In all respects it works the same as the "alloc" command, except that
976 the image file is allocated sparsely, which means that disk blocks are
977 not assigned to the file until they are needed. Sparse disk files only
978 use space when written to, but they are slower and there is a danger
979 you could run out of real disk space during a write operation.
980 For more advanced image creation, see qemu-img(1) utility.
982 Size can be specified using standard suffixes, eg. "1M".
984 supported
986 supported
987 This command returns a list of the optional groups known to the daemon,
989 and indicates which ones are supported by this build of the libguestfs
990 appliance.
991 See also "AVAILABILITY" in guestfs(3).
993 time
995 time command args...
996 Run the command as usual, but print the elapsed time afterwards. This
998 can be useful for benchmarking operations.
999
1001 add-cdrom
1002 add-cdrom filename
1003 This function adds a virtual CD-ROM disk image to the guest.
1005 This is equivalent to the qemu parameter "-cdrom filename".
1007 Notes:
1009 · This call checks for the existence of "filename". This stops you
1011 from specifying other types of drive which are supported by qemu
1012 such as "nbd:" and "http:" URLs. To specify those, use the general
1013 "config" call instead.
1014 · If you just want to add an ISO file (often you use this as an
1016 efficient way to transfer large files into the guest), then you
1017 should probably use "add-drive-ro" instead.
1018 This function is deprecated. In new code, use the "add_drive_opts"
1020 call instead.
1021 Deprecated functions will not be removed from the API, but the fact
1023 that they are deprecated indicates that there are problems with correct
1024 use of these functions.
1025 add-domain
1027 domain
1028 add-domain dom [libvirturi:..] [readonly:..] [iface:..]
1029 This function adds the disk(s) attached to the named libvirt domain
1031 "dom". It works by connecting to libvirt, requesting the domain and
1032 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1033 opts" on each one.
1034 The number of disks added is returned. This operation is atomic: if an
1036 error is returned, then no disks are added.
1037 This function does some minimal checks to make sure the libvirt domain
1039 is not running (unless "readonly" is true). In a future version we
1040 will try to acquire the libvirt lock on each disk.
1041 Disks must be accessible locally. This often means that adding disks
1043 from a remote libvirt connection (see <http://libvirt.org/remote.html>)
1044 will fail unless those disks are accessible via the same device path
1045 locally too.
1046 The optional "libvirturi" parameter sets the libvirt URI (see
1048 <http://libvirt.org/uri.html>). If this is not set then we connect to
1049 the default libvirt URI (or one set through an environment variable,
1050 see the libvirt documentation for full details).
1051 The other optional parameters are passed directly through to "add-
1053 drive-opts".
1054 This command has one or more optional arguments. See "OPTIONAL
1056 ARGUMENTS".
1057 add-drive
1059 add-drive filename
1060 This function is the equivalent of calling "add-drive-opts" with no
1062 optional parameters, so the disk is added writable, with the format
1063 being detected automatically.
1064 Automatic detection of the format opens you up to a potential security
1066 hole when dealing with untrusted raw-format images. See CVE-2010-3851
1067 and RHBZ#642934. Specifying the format closes this security hole.
1068 Therefore you should think about replacing calls to this function with
1069 calls to "add-drive-opts", and specifying the format.
1070 add-drive-opts
1072 add
1073 add-drive-opts filename [readonly:..] [format:..] [iface:..]
1074 This function adds a virtual machine disk image "filename" to
1076 libguestfs. The first time you call this function, the disk appears as
1077 "/dev/sda", the second time as "/dev/sdb", and so on.
1078 You don't necessarily need to be root when using libguestfs. However
1080 you obviously do need sufficient permissions to access the filename for
1081 whatever operations you want to perform (ie. read access if you just
1082 want to read the image or write access if you want to modify the
1083 image).
1084 This call checks that "filename" exists.
1086 The optional arguments are:
1088 "readonly"
1090 If true then the image is treated as read-only. Writes are still
1091 allowed, but they are stored in a temporary snapshot overlay which
1092 is discarded at the end. The disk that you add is not modified.
1093 "format"
1095 This forces the image format. If you omit this (or use "add-drive"
1096 or "add-drive-ro") then the format is automatically detected.
1097 Possible formats include "raw" and "qcow2".
1098 Automatic detection of the format opens you up to a potential
1100 security hole when dealing with untrusted raw-format images. See
1101 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1102 security hole.
1103 "iface"
1105 This rarely-used option lets you emulate the behaviour of the
1106 deprecated "add-drive-with-if" call (q.v.)
1107 This command has one or more optional arguments. See "OPTIONAL
1109 ARGUMENTS".
1110 add-drive-ro
1112 add-ro
1113 add-drive-ro filename
1114 This function is the equivalent of calling "add-drive-opts" with the
1116 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1117 disk is added read-only, with the format being detected automatically.
1118 add-drive-ro-with-if
1120 add-drive-ro-with-if filename iface
1121 This is the same as "add-drive-ro" but it allows you to specify the
1123 QEMU interface emulation to use at run time.
1124 This function is deprecated. In new code, use the "add_drive_opts"
1126 call instead.
1127 Deprecated functions will not be removed from the API, but the fact
1129 that they are deprecated indicates that there are problems with correct
1130 use of these functions.
1131 add-drive-with-if
1133 add-drive-with-if filename iface
1134 This is the same as "add-drive" but it allows you to specify the QEMU
1136 interface emulation to use at run time.
1137 This function is deprecated. In new code, use the "add_drive_opts"
1139 call instead.
1140 Deprecated functions will not be removed from the API, but the fact
1142 that they are deprecated indicates that there are problems with correct
1143 use of these functions.
1144 aug-clear
1146 aug-clear augpath
1147 Set the value associated with "path" to "NULL". This is the same as
1149 the augtool(1) "clear" command.
1150 aug-close
1152 aug-close
1153 Close the current Augeas handle and free up any resources used by it.
1155 After calling this, you have to call "aug-init" again before you can
1156 use any other Augeas functions.
1157 aug-defnode
1159 aug-defnode name expr val
1160 Defines a variable "name" whose value is the result of evaluating
1162 "expr".
1163 If "expr" evaluates to an empty nodeset, a node is created, equivalent
1165 to calling "aug-set" "expr", "value". "name" will be the nodeset
1166 containing that single node.
1167 On success this returns a pair containing the number of nodes in the
1169 nodeset, and a boolean flag if a node was created.
1170 aug-defvar
1172 aug-defvar name expr
1173 Defines an Augeas variable "name" whose value is the result of
1175 evaluating "expr". If "expr" is NULL, then "name" is undefined.
1176 On success this returns the number of nodes in "expr", or 0 if "expr"
1178 evaluates to something which is not a nodeset.
1179 aug-get
1181 aug-get augpath
1182 Look up the value associated with "path". If "path" matches exactly
1184 one node, the "value" is returned.
1185 aug-init
1187 aug-init root flags
1188 Create a new Augeas handle for editing configuration files. If there
1190 was any previous Augeas handle associated with this guestfs session,
1191 then it is closed.
1192 You must call this before using any other "aug-*" commands.
1194 "root" is the filesystem root. "root" must not be NULL, use "/"
1196 instead.
1197 The flags are the same as the flags defined in <augeas.h>, the logical
1199 or of the following integers:
1200 "AUG_SAVE_BACKUP" = 1
1202 Keep the original file with a ".augsave" extension.
1203 "AUG_SAVE_NEWFILE" = 2
1205 Save changes into a file with extension ".augnew", and do not
1206 overwrite original. Overrides "AUG_SAVE_BACKUP".
1207 "AUG_TYPE_CHECK" = 4
1209 Typecheck lenses.
1210 This option is only useful when debugging Augeas lenses. Use of
1212 this option may require additional memory for the libguestfs
1213 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
1214 environment variable or call "set-memsize".
1215 "AUG_NO_STDINC" = 8
1217 Do not use standard load path for modules.
1218 "AUG_SAVE_NOOP" = 16
1220 Make save a no-op, just record what would have been changed.
1221 "AUG_NO_LOAD" = 32
1223 Do not load the tree in "aug-init".
1224 To close the handle, you can call "aug-close".
1226 To find out more about Augeas, see <http://augeas.net/>.
1228 aug-insert
1230 aug-insert augpath label true|false
1231 Create a new sibling "label" for "path", inserting it into the tree
1233 before or after "path" (depending on the boolean flag "before").
1234 "path" must match exactly one existing node in the tree, and "label"
1236 must be a label, ie. not contain "/", "*" or end with a bracketed index
1237 "[N]".
1238 aug-load
1240 aug-load
1241 Load files into the tree.
1243 See "aug_load" in the Augeas documentation for the full gory details.
1245 aug-ls
1247 aug-ls augpath
1248 This is just a shortcut for listing "aug-match" "path/*" and sorting
1250 the resulting nodes into alphabetical order.
1251 aug-match
1253 aug-match augpath
1254 Returns a list of paths which match the path expression "path". The
1256 returned paths are sufficiently qualified so that they match exactly
1257 one node in the current tree.
1258 aug-mv
1260 aug-mv src dest
1261 Move the node "src" to "dest". "src" must match exactly one node.
1263 "dest" is overwritten if it exists.
1264 aug-rm
1266 aug-rm augpath
1267 Remove "path" and all of its children.
1269 On success this returns the number of entries which were removed.
1271 aug-save
1273 aug-save
1274 This writes all pending changes to disk.
1276 The flags which were passed to "aug-init" affect exactly how files are
1278 saved.
1279 aug-set
1281 aug-set augpath val
1282 Set the value associated with "path" to "val".
1284 In the Augeas API, it is possible to clear a node by setting the value
1286 to NULL. Due to an oversight in the libguestfs API you cannot do that
1287 with this call. Instead you must use the "aug-clear" call.
1288 available
1290 available 'groups ...'
1291 This command is used to check the availability of some groups of
1293 functionality in the appliance, which not all builds of the libguestfs
1294 appliance will be able to provide.
1295 The libguestfs groups, and the functions that those groups correspond
1297 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
1298 this list at runtime by calling "available-all-groups".
1299 The argument "groups" is a list of group names, eg: "["inotify",
1301 "augeas"]" would check for the availability of the Linux inotify
1302 functions and Augeas (configuration file editing) functions.
1303 The command returns no error if all requested groups are available.
1305 It fails with an error if one or more of the requested groups is
1307 unavailable in the appliance.
1308 If an unknown group name is included in the list of groups then an
1310 error is always returned.
1311 Notes:
1313 · You must call "launch" before calling this function.
1315 The reason is because we don't know what groups are supported by
1317 the appliance/daemon until it is running and can be queried.
1318 · If a group of functions is available, this does not necessarily
1320 mean that they will work. You still have to check for errors when
1321 calling individual API functions even if they are available.
1322 · It is usually the job of distro packagers to build complete
1324 functionality into the libguestfs appliance. Upstream libguestfs,
1325 if built from source with all requirements satisfied, will support
1326 everything.
1327 · This call was added in version 1.0.80. In previous versions of
1329 libguestfs all you could do would be to speculatively execute a
1330 command to find out if the daemon implemented it. See also
1331 "version".
1332 available-all-groups
1334 available-all-groups
1335 This command returns a list of all optional groups that this daemon
1337 knows about. Note this returns both supported and unsupported groups.
1338 To find out which ones the daemon can actually support you have to call
1339 "available" on each member of the returned list.
1340 See also "available" and "AVAILABILITY" in guestfs(3).
1342 base64-in
1344 base64-in (base64file|-) filename
1345 This command uploads base64-encoded data from "base64file" to
1347 "filename".
1348 Use "-" instead of a filename to read/write from stdin/stdout.
1350 base64-out
1352 base64-out filename (base64file|-)
1353 This command downloads the contents of "filename", writing it out to
1355 local file "base64file" encoded as base64.
1356 Use "-" instead of a filename to read/write from stdin/stdout.
1358 blockdev-flushbufs
1360 blockdev-flushbufs device
1361 This tells the kernel to flush internal buffers associated with
1363 "device".
1364 This uses the blockdev(8) command.
1366 blockdev-getbsz
1368 blockdev-getbsz device
1369 This returns the block size of a device.
1371 (Note this is different from both size in blocks and filesystem block
1373 size).
1374 This uses the blockdev(8) command.
1376 blockdev-getro
1378 blockdev-getro device
1379 Returns a boolean indicating if the block device is read-only (true if
1381 read-only, false if not).
1382 This uses the blockdev(8) command.
1384 blockdev-getsize64
1386 blockdev-getsize64 device
1387 This returns the size of the device in bytes.
1389 See also "blockdev-getsz".
1391 This uses the blockdev(8) command.
1393 blockdev-getss
1395 blockdev-getss device
1396 This returns the size of sectors on a block device. Usually 512, but
1398 can be larger for modern devices.
1399 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
1401 This uses the blockdev(8) command.
1403 blockdev-getsz
1405 blockdev-getsz device
1406 This returns the size of the device in units of 512-byte sectors (even
1408 if the sectorsize isn't 512 bytes ... weird).
1409 See also "blockdev-getss" for the real sector size of the device, and
1411 "blockdev-getsize64" for the more useful size in bytes.
1412 This uses the blockdev(8) command.
1414 blockdev-rereadpt
1416 blockdev-rereadpt device
1417 Reread the partition table on "device".
1419 This uses the blockdev(8) command.
1421 blockdev-setbsz
1423 blockdev-setbsz device blocksize
1424 This sets the block size of a device.
1426 (Note this is different from both size in blocks and filesystem block
1428 size).
1429 This uses the blockdev(8) command.
1431 blockdev-setro
1433 blockdev-setro device
1434 Sets the block device named "device" to read-only.
1436 This uses the blockdev(8) command.
1438 blockdev-setrw
1440 blockdev-setrw device
1441 Sets the block device named "device" to read-write.
1443 This uses the blockdev(8) command.
1445 case-sensitive-path
1447 case-sensitive-path path
1448 This can be used to resolve case insensitive paths on a filesystem
1450 which is case sensitive. The use case is to resolve paths which you
1451 have read from Windows configuration files or the Windows Registry, to
1452 the true path.
1453 The command handles a peculiarity of the Linux ntfs-3g filesystem
1455 driver (and probably others), which is that although the underlying
1456 filesystem is case-insensitive, the driver exports the filesystem to
1457 Linux as case-sensitive.
1458 One consequence of this is that special directories such as
1460 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other things)
1461 depending on the precise details of how they were created. In Windows
1462 itself this would not be a problem.
1463 Bug or feature? You decide:
1465 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
1466 <http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1>
1467 This function resolves the true case of each element in the path and
1469 returns the case-sensitive path.
1470 Thus "case-sensitive-path" ("/Windows/System32") might return
1472 "/WINDOWS/system32" (the exact return value would depend on details of
1473 how the directories were originally created under Windows).
1474 Note: This function does not handle drive names, backslashes etc.
1476 See also "realpath".
1478 cat
1480 cat path
1481 Return the contents of the file named "path".
1483 Note that this function cannot correctly handle binary files
1485 (specifically, files containing "\0" character which is treated as end
1486 of string). For those you need to use the "read-file" or "download"
1487 functions which have a more complex interface.
1488 Because of the message protocol, there is a transfer limit of somewhere
1490 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1491 checksum
1493 checksum csumtype path
1494 This call computes the MD5, SHAx or CRC checksum of the file named
1496 "path".
1497 The type of checksum to compute is given by the "csumtype" parameter
1499 which must have one of the following values:
1500 "crc"
1502 Compute the cyclic redundancy check (CRC) specified by POSIX for
1503 the "cksum" command.
1504 "md5"
1506 Compute the MD5 hash (using the "md5sum" program).
1507 "sha1"
1509 Compute the SHA1 hash (using the "sha1sum" program).
1510 "sha224"
1512 Compute the SHA224 hash (using the "sha224sum" program).
1513 "sha256"
1515 Compute the SHA256 hash (using the "sha256sum" program).
1516 "sha384"
1518 Compute the SHA384 hash (using the "sha384sum" program).
1519 "sha512"
1521 Compute the SHA512 hash (using the "sha512sum" program).
1522 The checksum is returned as a printable string.
1524 To get the checksum for a device, use "checksum-device".
1526 To get the checksums for many files, use "checksums-out".
1528 checksum-device
1530 checksum-device csumtype device
1531 This call computes the MD5, SHAx or CRC checksum of the contents of the
1533 device named "device". For the types of checksums supported see the
1534 "checksum" command.
1535 checksums-out
1537 checksums-out csumtype directory (sumsfile|-)
1538 This command computes the checksums of all regular files in "directory"
1540 and then emits a list of those checksums to the local output file
1541 "sumsfile".
1542 This can be used for verifying the integrity of a virtual machine.
1544 However to be properly secure you should pay attention to the output of
1545 the checksum command (it uses the ones from GNU coreutils). In
1546 particular when the filename is not printable, coreutils uses a special
1547 backslash syntax. For more information, see the GNU coreutils info
1548 file.
1549 Use "-" instead of a filename to read/write from stdin/stdout.
1551 chmod
1553 chmod mode path
1554 Change the mode (permissions) of "path" to "mode". Only numeric modes
1556 are supported.
1557 Note: When using this command from guestfish, "mode" by default would
1559 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
1560 700.
1561 The mode actually set is affected by the umask.
1563 chown
1565 chown owner group path
1566 Change the file owner to "owner" and group to "group".
1568 Only numeric uid and gid are supported. If you want to use names, you
1570 will need to locate and parse the password file yourself (Augeas
1571 support makes this relatively easy).
1572 command
1574 command 'arguments ...'
1575 This call runs a command from the guest filesystem. The filesystem
1577 must be mounted, and must contain a compatible operating system (ie.
1578 something Linux, with the same or compatible processor architecture).
1579 The single parameter is an argv-style list of arguments. The first
1581 element is the name of the program to run. Subsequent elements are
1582 parameters. The list must be non-empty (ie. must contain a program
1583 name). Note that the command runs directly, and is not invoked via the
1584 shell (see "sh").
1585 The return value is anything printed to stdout by the command.
1587 If the command returns a non-zero exit status, then this function
1589 returns an error message. The error message string is the content of
1590 stderr from the command.
1591 The $PATH environment variable will contain at least "/usr/bin" and
1593 "/bin". If you require a program from another location, you should
1594 provide the full path in the first parameter.
1595 Shared libraries and data files required by the program must be
1597 available on filesystems which are mounted in the correct places. It
1598 is the caller's responsibility to ensure all filesystems that are
1599 needed are mounted at the right locations.
1600 Because of the message protocol, there is a transfer limit of somewhere
1602 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1603 command-lines
1605 command-lines 'arguments ...'
1606 This is the same as "command", but splits the result into a list of
1608 lines.
1609 See also: "sh-lines"
1611 Because of the message protocol, there is a transfer limit of somewhere
1613 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1614 config
1616 config qemuparam qemuvalue
1617 This can be used to add arbitrary qemu command line parameters of the
1619 form "-param value". Actually it's not quite arbitrary - we prevent
1620 you from setting some parameters which would interfere with parameters
1621 that we use.
1622 The first character of "param" string must be a "-" (dash).
1624 "value" can be NULL.
1626 copy-size
1628 copy-size src dest size
1629 This command copies exactly "size" bytes from one source device or file
1631 "src" to another destination device or file "dest".
1632 Note this will fail if the source is too short or if the destination is
1634 not large enough.
1635 cp
1637 cp src dest
1638 This copies a file from "src" to "dest" where "dest" is either a
1640 destination filename or destination directory.
1641 cp-a
1643 cp-a src dest
1644 This copies a file or directory from "src" to "dest" recursively using
1646 the "cp -a" command.
1647 dd
1649 dd src dest
1650 This command copies from one source device or file "src" to another
1652 destination device or file "dest". Normally you would use this to copy
1653 to or from a device or partition, for example to duplicate a
1654 filesystem.
1655 If the destination is a device, it must be as large or larger than the
1657 source file or device, otherwise the copy will fail. This command
1658 cannot do partial copies (see "copy-size").
1659 df
1661 df
1662 This command runs the "df" command to report disk space used.
1664 This command is mostly useful for interactive sessions. It is not
1666 intended that you try to parse the output string. Use "statvfs" from
1667 programs.
1668 df-h
1670 df-h
1671 This command runs the "df -h" command to report disk space used in
1673 human-readable format.
1674 This command is mostly useful for interactive sessions. It is not
1676 intended that you try to parse the output string. Use "statvfs" from
1677 programs.
1678 dmesg
1680 dmesg
1681 This returns the kernel messages ("dmesg" output) from the guest
1683 kernel. This is sometimes useful for extended debugging of problems.
1684 Another way to get the same information is to enable verbose messages
1686 with "set-verbose" or by setting the environment variable
1687 "LIBGUESTFS_DEBUG=1" before running the program.
1688 download
1690 download remotefilename (filename|-)
1691 Download file "remotefilename" and save it as "filename" on the local
1693 machine.
1694 "filename" can also be a named pipe.
1696 See also "upload", "cat".
1698 Use "-" instead of a filename to read/write from stdin/stdout.
1700 download-offset
1702 download-offset remotefilename (filename|-) offset size
1703 Download file "remotefilename" and save it as "filename" on the local
1705 machine.
1706 "remotefilename" is read for "size" bytes starting at "offset" (this
1708 region must be within the file or device).
1709 Note that there is no limit on the amount of data that can be
1711 downloaded with this call, unlike with "pread", and this call always
1712 reads the full amount unless an error occurs.
1713 See also "download", "pread".
1715 Use "-" instead of a filename to read/write from stdin/stdout.
1717 drop-caches
1719 drop-caches whattodrop
1720 This instructs the guest kernel to drop its page cache, and/or dentries
1722 and inode caches. The parameter "whattodrop" tells the kernel what
1723 precisely to drop, see http://linux-mm.org/Drop_Caches <http://linux-
1724 mm.org/Drop_Caches>
1725 Setting "whattodrop" to 3 should drop everything.
1727 This automatically calls sync(2) before the operation, so that the
1729 maximum guest memory is freed.
1730 du
1732 du path
1733 This command runs the "du -s" command to estimate file space usage for
1735 "path".
1736 "path" can be a file or a directory. If "path" is a directory then the
1738 estimate includes the contents of the directory and all subdirectories
1739 (recursively).
1740 The result is the estimated size in kilobytes (ie. units of 1024
1742 bytes).
1743 e2fsck-f
1745 e2fsck-f device
1746 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
1748 checker on "device", noninteractively ("-p"), even if the filesystem
1749 appears to be clean ("-f").
1750 This command is only needed because of "resize2fs" (q.v.). Normally
1752 you should use "fsck".
1753 echo-daemon
1755 echo-daemon 'words ...'
1756 This command concatenates the list of "words" passed with single spaces
1758 between them and returns the resulting string.
1759 You can use this command to test the connection through to the daemon.
1761 See also "ping-daemon".
1763 egrep
1765 egrep regex path
1766 This calls the external "egrep" program and returns the matching lines.
1768 Because of the message protocol, there is a transfer limit of somewhere
1770 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1771 egrepi
1773 egrepi regex path
1774 This calls the external "egrep -i" program and returns the matching
1776 lines.
1777 Because of the message protocol, there is a transfer limit of somewhere
1779 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1780 equal
1782 equal file1 file2
1783 This compares the two files "file1" and "file2" and returns true if
1785 their content is exactly equal, or false otherwise.
1786 The external cmp(1) program is used for the comparison.
1788 exists
1790 exists path
1791 This returns "true" if and only if there is a file, directory (or
1793 anything) with the given "path" name.
1794 See also "is-file", "is-dir", "stat".
1796 fallocate
1798 fallocate path len
1799 This command preallocates a file (containing zero bytes) named "path"
1801 of size "len" bytes. If the file exists already, it is overwritten.
1802 Do not confuse this with the guestfish-specific "alloc" command which
1804 allocates a file in the host and attaches it as a device.
1805 This function is deprecated. In new code, use the "fallocate64" call
1807 instead.
1808 Deprecated functions will not be removed from the API, but the fact
1810 that they are deprecated indicates that there are problems with correct
1811 use of these functions.
1812 fallocate64
1814 fallocate64 path len
1815 This command preallocates a file (containing zero bytes) named "path"
1817 of size "len" bytes. If the file exists already, it is overwritten.
1818 Note that this call allocates disk blocks for the file. To create a
1820 sparse file use "truncate-size" instead.
1821 The deprecated call "fallocate" does the same, but owing to an
1823 oversight it only allowed 30 bit lengths to be specified, effectively
1824 limiting the maximum size of files created through that call to 1GB.
1825 Do not confuse this with the guestfish-specific "alloc" and "sparse"
1827 commands which create a file in the host and attach it as a device.
1828 fgrep
1830 fgrep pattern path
1831 This calls the external "fgrep" program and returns the matching lines.
1833 Because of the message protocol, there is a transfer limit of somewhere
1835 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1836 fgrepi
1838 fgrepi pattern path
1839 This calls the external "fgrep -i" program and returns the matching
1841 lines.
1842 Because of the message protocol, there is a transfer limit of somewhere
1844 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1845 file
1847 file path
1848 This call uses the standard file(1) command to determine the type or
1850 contents of the file.
1851 This call will also transparently look inside various types of
1853 compressed file.
1854 The exact command which runs is "file -zb path". Note in particular
1856 that the filename is not prepended to the output (the "-b" option).
1857 The output depends on the output of the underlying file(1) command and
1859 it can change in future in ways beyond our control. In other words,
1860 the output is not guaranteed by the ABI.
1861 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc).
1863 file-architecture
1865 file-architecture filename
1866 This detects the architecture of the binary "filename", and returns it
1868 if known.
1869 Currently defined architectures are:
1871 "i386"
1873 This string is returned for all 32 bit i386, i486, i586, i686
1874 binaries irrespective of the precise processor requirements of the
1875 binary.
1876 "x86_64"
1878 64 bit x86-64.
1879 "sparc"
1881 32 bit SPARC.
1882 "sparc64"
1884 64 bit SPARC V9 and above.
1885 "ia64"
1887 Intel Itanium.
1888 "ppc"
1890 32 bit Power PC.
1891 "ppc64"
1893 64 bit Power PC.
1894 Libguestfs may return other architecture strings in future.
1896 The function works on at least the following types of files:
1898 · many types of Un*x and Linux binary
1900 · many types of Un*x and Linux shared library
1902 · Windows Win32 and Win64 binaries
1904 · Windows Win32 and Win64 DLLs
1906 Win32 binaries and DLLs return "i386".
1908 Win64 binaries and DLLs return "x86_64".
1910 · Linux kernel modules
1912 · Linux new-style initrd images
1914 · some non-x86 Linux vmlinuz kernels
1916 What it can't do currently:
1918 · static libraries (libfoo.a)
1920 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
1922 · x86 Linux vmlinuz kernels
1924 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
1926 and compressed code, and are horribly hard to unpack. If you want
1927 to find the architecture of a kernel, use the architecture of the
1928 associated initrd or kernel module(s) instead.
1929 filesize
1931 filesize file
1932 This command returns the size of "file" in bytes.
1934 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
1936 file" etc. To get the size of block devices, use "blockdev-getsize64".
1937 fill
1939 fill c len path
1940 This command creates a new file called "path". The initial content of
1942 the file is "len" octets of "c", where "c" must be a number in the
1943 range "[0..255]".
1944 To fill a file with zero bytes (sparsely), it is much more efficient to
1946 use "truncate-size". To create a file with a pattern of repeating
1947 bytes use "fill-pattern".
1948 fill-pattern
1950 fill-pattern pattern len path
1951 This function is like "fill" except that it creates a new file of
1953 length "len" containing the repeating pattern of bytes in "pattern".
1954 The pattern is truncated if necessary to ensure the length of the file
1955 is exactly "len" bytes.
1956 find
1958 find directory
1959 This command lists out all files and directories, recursively, starting
1961 at "directory". It is essentially equivalent to running the shell
1962 command "find directory -print" but some post-processing happens on the
1963 output, described below.
1964 This returns a list of strings without any prefix. Thus if the
1966 directory structure was:
1967 /tmp/a
1969 /tmp/b
1970 /tmp/c/d
1971 then the returned list from "find" "/tmp" would be 4 elements:
1973 a
1975 b
1976 c
1977 c/d
1978 If "directory" is not a directory, then this command returns an error.
1980 The returned list is sorted.
1982 See also "find0".
1984 Because of the message protocol, there is a transfer limit of somewhere
1986 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
1987 find0
1989 find0 directory (files|-)
1990 This command lists out all files and directories, recursively, starting
1992 at "directory", placing the resulting list in the external file called
1993 "files".
1994 This command works the same way as "find" with the following
1996 exceptions:
1997 · The resulting list is written to an external file.
1999 · Items (filenames) in the result are separated by "\0" characters.
2001 See find(1) option -print0.
2002 · This command is not limited in the number of names that it can
2004 return.
2005 · The result list is not sorted.
2007 Use "-" instead of a filename to read/write from stdin/stdout.
2009 findfs-label
2011 findfs-label label
2012 This command searches the filesystems and returns the one which has the
2014 given label. An error is returned if no such filesystem can be found.
2015 To find the label of a filesystem, use "vfs-label".
2017 findfs-uuid
2019 findfs-uuid uuid
2020 This command searches the filesystems and returns the one which has the
2022 given UUID. An error is returned if no such filesystem can be found.
2023 To find the UUID of a filesystem, use "vfs-uuid".
2025 fsck
2027 fsck fstype device
2028 This runs the filesystem checker (fsck) on "device" which should have
2030 filesystem type "fstype".
2031 The returned integer is the status. See fsck(8) for the list of status
2033 codes from "fsck".
2034 Notes:
2036 · Multiple status codes can be summed together.
2038 · A non-zero return code can mean "success", for example if errors
2040 have been corrected on the filesystem.
2041 · Checking or repairing NTFS volumes is not supported (by linux-
2043 ntfs).
2044 This command is entirely equivalent to running "fsck -a -t fstype
2046 device".
2047 get-append
2049 get-append
2050 Return the additional kernel options which are added to the guest
2052 kernel command line.
2053 If "NULL" then no options are added.
2055 get-autosync
2057 get-autosync
2058 Get the autosync flag.
2060 get-direct
2062 get-direct
2063 Return the direct appliance mode flag.
2065 get-e2label
2067 get-e2label device
2068 This returns the ext2/3/4 filesystem label of the filesystem on
2070 "device".
2071 This function is deprecated. In new code, use the "vfs_label" call
2073 instead.
2074 Deprecated functions will not be removed from the API, but the fact
2076 that they are deprecated indicates that there are problems with correct
2077 use of these functions.
2078 get-e2uuid
2080 get-e2uuid device
2081 This returns the ext2/3/4 filesystem UUID of the filesystem on
2083 "device".
2084 This function is deprecated. In new code, use the "vfs_uuid" call
2086 instead.
2087 Deprecated functions will not be removed from the API, but the fact
2089 that they are deprecated indicates that there are problems with correct
2090 use of these functions.
2091 get-memsize
2093 get-memsize
2094 This gets the memory size in megabytes allocated to the qemu
2096 subprocess.
2097 If "set-memsize" was not called on this handle, and if
2099 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
2100 default value for memsize.
2101 For more information on the architecture of libguestfs, see guestfs(3).
2103 get-network
2105 get-network
2106 This returns the enable network flag.
2108 get-path
2110 get-path
2111 Return the current search path.
2113 This is always non-NULL. If it wasn't set already, then this will
2115 return the default path.
2116 get-pid
2118 pid
2119 get-pid
2120 Return the process ID of the qemu subprocess. If there is no qemu
2122 subprocess, then this will return an error.
2123 This is an internal call used for debugging and testing.
2125 get-qemu
2127 get-qemu
2128 Return the current qemu binary.
2130 This is always non-NULL. If it wasn't set already, then this will
2132 return the default qemu binary name.
2133 get-recovery-proc
2135 get-recovery-proc
2136 Return the recovery process enabled flag.
2138 get-selinux
2140 get-selinux
2141 This returns the current setting of the selinux flag which is passed to
2143 the appliance at boot time. See "set-selinux".
2144 For more information on the architecture of libguestfs, see guestfs(3).
2146 get-state
2148 get-state
2149 This returns the current state as an opaque integer. This is only
2151 useful for printing debug and internal error messages.
2152 For more information on states, see guestfs(3).
2154 get-trace
2156 get-trace
2157 Return the command trace flag.
2159 get-umask
2161 get-umask
2162 Return the current umask. By default the umask is 022 unless it has
2164 been set by calling "umask".
2165 get-verbose
2167 get-verbose
2168 This returns the verbose messages flag.
2170 getcon
2172 getcon
2173 This gets the SELinux security context of the daemon.
2175 See the documentation about SELINUX in guestfs(3), and "setcon"
2177 getxattr
2179 getxattr path name
2180 Get a single extended attribute from file "path" named "name". This
2182 call follows symlinks. If you want to lookup an extended attribute for
2183 the symlink itself, use "lgetxattr".
2184 Normally it is better to get all extended attributes from a file in one
2186 go by calling "getxattrs". However some Linux filesystem
2187 implementations are buggy and do not provide a way to list out
2188 attributes. For these filesystems (notably ntfs-3g) you have to know
2189 the names of the extended attributes you want in advance and call this
2190 function.
2191 Extended attribute values are blobs of binary data. If there is no
2193 extended attribute named "name", this returns an error.
2194 See also: "getxattrs", "lgetxattr", attr(5).
2196 getxattrs
2198 getxattrs path
2199 This call lists the extended attributes of the file or directory
2201 "path".
2202 At the system call level, this is a combination of the listxattr(2) and
2204 getxattr(2) calls.
2205 See also: "lgetxattrs", attr(5).
2207 glob-expand
2209 glob-expand pattern
2210 This command searches for all the pathnames matching "pattern"
2212 according to the wildcard expansion rules used by the shell.
2213 If no paths match, then this returns an empty list (note: not an
2215 error).
2216 It is just a wrapper around the C glob(3) function with flags
2218 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
2219 grep
2221 grep regex path
2222 This calls the external "grep" program and returns the matching lines.
2224 Because of the message protocol, there is a transfer limit of somewhere
2226 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2227 grepi
2229 grepi regex path
2230 This calls the external "grep -i" program and returns the matching
2232 lines.
2233 Because of the message protocol, there is a transfer limit of somewhere
2235 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2236 grub-install
2238 grub-install root device
2239 This command installs GRUB 1 (the Grand Unified Bootloader) on
2241 "device", with the root directory being "root".
2242 Notes:
2244 · There is currently no way in the API to install grub2, which is
2246 used by most modern Linux guests. It is possible to run the grub2
2247 command from the guest, although see the caveats in "RUNNING
2248 COMMANDS" in guestfs(3).
2249 · This uses "grub-install" from the host. Unfortunately grub is not
2251 always compatible with itself, so this only works in rather narrow
2252 circumstances. Careful testing with each guest version is
2253 advisable.
2254 · If grub-install reports the error "No suitable drive was found in
2256 the generated device map." it may be that you need to create a
2257 "/boot/grub/device.map" file first that contains the mapping
2258 between grub device names and Linux device names. It is usually
2259 sufficient to create a file containing:
2260 (hd0) /dev/vda
2262 replacing "/dev/vda" with the name of the installation device.
2264 head
2266 head path
2267 This command returns up to the first 10 lines of a file as a list of
2269 strings.
2270 Because of the message protocol, there is a transfer limit of somewhere
2272 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2273 head-n
2275 head-n nrlines path
2276 If the parameter "nrlines" is a positive number, this returns the first
2278 "nrlines" lines of the file "path".
2279 If the parameter "nrlines" is a negative number, this returns lines
2281 from the file "path", excluding the last "nrlines" lines.
2282 If the parameter "nrlines" is zero, this returns an empty list.
2284 Because of the message protocol, there is a transfer limit of somewhere
2286 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2287 hexdump
2289 hexdump path
2290 This runs "hexdump -C" on the given "path". The result is the human-
2292 readable, canonical hex dump of the file.
2293 Because of the message protocol, there is a transfer limit of somewhere
2295 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2296 initrd-cat
2298 initrd-cat initrdpath filename
2299 This command unpacks the file "filename" from the initrd file called
2301 "initrdpath". The filename must be given without the initial "/"
2302 character.
2303 For example, in guestfish you could use the following command to
2305 examine the boot script (usually called "/init") contained in a Linux
2306 initrd or initramfs image:
2307 initrd-cat /boot/initrd-<version>.img init
2309 See also "initrd-list".
2311 Because of the message protocol, there is a transfer limit of somewhere
2313 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2314 initrd-list
2316 initrd-list path
2317 This command lists out files contained in an initrd.
2319 The files are listed without any initial "/" character. The files are
2321 listed in the order they appear (not necessarily alphabetical).
2322 Directory names are listed as separate items.
2323 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
2325 as initrd. We only support the newer initramfs format (compressed cpio
2326 files).
2327 inotify-add-watch
2329 inotify-add-watch path mask
2330 Watch "path" for the events listed in "mask".
2332 Note that if "path" is a directory then events within that directory
2334 are watched, but this does not happen recursively (in subdirectories).
2335 Note for non-C or non-Linux callers: the inotify events are defined by
2337 the Linux kernel ABI and are listed in "/usr/include/sys/inotify.h".
2338 inotify-close
2340 inotify-close
2341 This closes the inotify handle which was previously opened by
2343 inotify_init. It removes all watches, throws away any pending events,
2344 and deallocates all resources.
2345 inotify-files
2347 inotify-files
2348 This function is a helpful wrapper around "inotify-read" which just
2350 returns a list of pathnames of objects that were touched. The returned
2351 pathnames are sorted and deduplicated.
2352 inotify-init
2354 inotify-init maxevents
2355 This command creates a new inotify handle. The inotify subsystem can
2357 be used to notify events which happen to objects in the guest
2358 filesystem.
2359 "maxevents" is the maximum number of events which will be queued up
2361 between calls to "inotify-read" or "inotify-files". If this is passed
2362 as 0, then the kernel (or previously set) default is used. For Linux
2363 2.6.29 the default was 16384 events. Beyond this limit, the kernel
2364 throws away events, but records the fact that it threw them away by
2365 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
2366 "inotify-read").
2367 Before any events are generated, you have to add some watches to the
2369 internal watch list. See: "inotify-add-watch", "inotify-rm-watch" and
2370 "inotify-watch-all".
2371 Queued up events should be read periodically by calling "inotify-read"
2373 (or "inotify-files" which is just a helpful wrapper around "inotify-
2374 read"). If you don't read the events out often enough then you risk
2375 the internal queue overflowing.
2376 The handle should be closed after use by calling "inotify-close". This
2378 also removes any watches automatically.
2379 See also inotify(7) for an overview of the inotify interface as exposed
2381 by the Linux kernel, which is roughly what we expose via libguestfs.
2382 Note that there is one global inotify handle per libguestfs instance.
2383 inotify-read
2385 inotify-read
2386 Return the complete queue of events that have happened since the
2388 previous read call.
2389 If no events have happened, this returns an empty list.
2391 Note: In order to make sure that all events have been read, you must
2393 call this function repeatedly until it returns an empty list. The
2394 reason is that the call will read events up to the maximum appliance-
2395 to-host message size and leave remaining events in the queue.
2396 inotify-rm-watch
2398 inotify-rm-watch wd
2399 Remove a previously defined inotify watch. See "inotify-add-watch".
2401 inspect-get-arch
2403 inspect-get-arch root
2404 This function should only be called with a root device string as
2406 returned by "inspect-os".
2407 This returns the architecture of the inspected operating system. The
2409 possible return values are listed under "file-architecture".
2410 If the architecture could not be determined, then the string "unknown"
2412 is returned.
2413 Please read "INSPECTION" in guestfs(3) for more details.
2415 inspect-get-distro
2417 inspect-get-distro root
2418 This function should only be called with a root device string as
2420 returned by "inspect-os".
2421 This returns the distro (distribution) of the inspected operating
2423 system.
2424 Currently defined distros are:
2426 "archlinux"
2428 Arch Linux.
2429 "debian"
2431 Debian.
2432 "fedora"
2434 Fedora.
2435 "gentoo"
2437 Gentoo.
2438 "linuxmint"
2440 Linux Mint.
2441 "mandriva"
2443 Mandriva.
2444 "meego"
2446 MeeGo.
2447 "pardus"
2449 Pardus.
2450 "redhat-based"
2452 Some Red Hat-derived distro.
2453 "rhel"
2455 Red Hat Enterprise Linux and some derivatives.
2456 "ubuntu"
2458 Ubuntu.
2459 "unknown"
2461 The distro could not be determined.
2462 "windows"
2464 Windows does not have distributions. This string is returned if
2465 the OS type is Windows.
2466 Future versions of libguestfs may return other strings here. The
2468 caller should be prepared to handle any string.
2469 Please read "INSPECTION" in guestfs(3) for more details.
2471 inspect-get-filesystems
2473 inspect-get-filesystems root
2474 This function should only be called with a root device string as
2476 returned by "inspect-os".
2477 This returns a list of all the filesystems that we think are associated
2479 with this operating system. This includes the root filesystem, other
2480 ordinary filesystems, and non-mounted devices like swap partitions.
2481 In the case of a multi-boot virtual machine, it is possible for a
2483 filesystem to be shared between operating systems.
2484 Please read "INSPECTION" in guestfs(3) for more details. See also
2486 "inspect-get-mountpoints".
2487 inspect-get-hostname
2489 inspect-get-hostname root
2490 This function should only be called with a root device string as
2492 returned by "inspect-os".
2493 This function returns the hostname of the operating system as found by
2495 inspection of the guest's configuration files.
2496 If the hostname could not be determined, then the string "unknown" is
2498 returned.
2499 Please read "INSPECTION" in guestfs(3) for more details.
2501 inspect-get-major-version
2503 inspect-get-major-version root
2504 This function should only be called with a root device string as
2506 returned by "inspect-os".
2507 This returns the major version number of the inspected operating
2509 system.
2510 Windows uses a consistent versioning scheme which is not reflected in
2512 the popular public names used by the operating system. Notably the
2513 operating system known as "Windows 7" is really version 6.1 (ie. major
2514 = 6, minor = 1). You can find out the real versions corresponding to
2515 releases of Windows by consulting Wikipedia or MSDN.
2516 If the version could not be determined, then 0 is returned.
2518 Please read "INSPECTION" in guestfs(3) for more details.
2520 inspect-get-minor-version
2522 inspect-get-minor-version root
2523 This function should only be called with a root device string as
2525 returned by "inspect-os".
2526 This returns the minor version number of the inspected operating
2528 system.
2529 If the version could not be determined, then 0 is returned.
2531 Please read "INSPECTION" in guestfs(3) for more details. See also
2533 "inspect-get-major-version".
2534 inspect-get-mountpoints
2536 inspect-get-mountpoints root
2537 This function should only be called with a root device string as
2539 returned by "inspect-os".
2540 This returns a hash of where we think the filesystems associated with
2542 this operating system should be mounted. Callers should note that this
2543 is at best an educated guess made by reading configuration files such
2544 as "/etc/fstab". In particular note that this may return filesystems
2545 which are non-existent or not mountable and callers should be prepared
2546 to handle or ignore failures if they try to mount them.
2547 Each element in the returned hashtable has a key which is the path of
2549 the mountpoint (eg. "/boot") and a value which is the filesystem that
2550 would be mounted there (eg. "/dev/sda1").
2551 Non-mounted devices such as swap devices are not returned in this list.
2553 Please read "INSPECTION" in guestfs(3) for more details. See also
2555 "inspect-get-filesystems".
2556 inspect-get-package-format
2558 inspect-get-package-format root
2559 This function should only be called with a root device string as
2561 returned by "inspect-os".
2562 This function and "inspect-get-package-management" return the package
2564 format and package management tool used by the inspected operating
2565 system. For example for Fedora these functions would return "rpm"
2566 (package format) and "yum" (package management).
2567 This returns the string "unknown" if we could not determine the package
2569 format or if the operating system does not have a real packaging system
2570 (eg. Windows).
2571 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman".
2573 Future versions of libguestfs may return other strings.
2574 Please read "INSPECTION" in guestfs(3) for more details.
2576 inspect-get-package-management
2578 inspect-get-package-management root
2579 This function should only be called with a root device string as
2581 returned by "inspect-os".
2582 "inspect-get-package-format" and this function return the package
2584 format and package management tool used by the inspected operating
2585 system. For example for Fedora these functions would return "rpm"
2586 (package format) and "yum" (package management).
2587 This returns the string "unknown" if we could not determine the package
2589 management tool or if the operating system does not have a real
2590 packaging system (eg. Windows).
2591 Possible strings include: "yum", "up2date", "apt" (for all Debian
2593 derivatives), "portage", "pisi", "pacman", "urpmi". Future versions of
2594 libguestfs may return other strings.
2595 Please read "INSPECTION" in guestfs(3) for more details.
2597 inspect-get-product-name
2599 inspect-get-product-name root
2600 This function should only be called with a root device string as
2602 returned by "inspect-os".
2603 This returns the product name of the inspected operating system. The
2605 product name is generally some freeform string which can be displayed
2606 to the user, but should not be parsed by programs.
2607 If the product name could not be determined, then the string "unknown"
2609 is returned.
2610 Please read "INSPECTION" in guestfs(3) for more details.
2612 inspect-get-roots
2614 inspect-get-roots
2615 This function is a convenient way to get the list of root devices, as
2617 returned from a previous call to "inspect-os", but without redoing the
2618 whole inspection process.
2619 This returns an empty list if either no root devices were found or the
2621 caller has not called "inspect-os".
2622 Please read "INSPECTION" in guestfs(3) for more details.
2624 inspect-get-type
2626 inspect-get-type root
2627 This function should only be called with a root device string as
2629 returned by "inspect-os".
2630 This returns the type of the inspected operating system. Currently
2632 defined types are:
2633 "linux"
2635 Any Linux-based operating system.
2636 "windows"
2638 Any Microsoft Windows operating system.
2639 "freebsd"
2641 FreeBSD.
2642 "unknown"
2644 The operating system type could not be determined.
2645 Future versions of libguestfs may return other strings here. The
2647 caller should be prepared to handle any string.
2648 Please read "INSPECTION" in guestfs(3) for more details.
2650 inspect-get-windows-systemroot
2652 inspect-get-windows-systemroot root
2653 This function should only be called with a root device string as
2655 returned by "inspect-os".
2656 This returns the Windows systemroot of the inspected guest. The
2658 systemroot is a directory path such as "/WINDOWS".
2659 This call assumes that the guest is Windows and that the systemroot
2661 could be determined by inspection. If this is not the case then an
2662 error is returned.
2663 Please read "INSPECTION" in guestfs(3) for more details.
2665 inspect-list-applications
2667 inspect-list-applications root
2668 This function should only be called with a root device string as
2670 returned by "inspect-os".
2671 Return the list of applications installed in the operating system.
2673 Note: This call works differently from other parts of the inspection
2675 API. You have to call "inspect-os", then "inspect-get-mountpoints",
2676 then mount up the disks, before calling this. Listing applications is
2677 a significantly more difficult operation which requires access to the
2678 full filesystem. Also note that unlike the other "inspect-get-*" calls
2679 which are just returning data cached in the libguestfs handle, this
2680 call actually reads parts of the mounted filesystems during the call.
2681 This returns an empty list if the inspection code was not able to
2683 determine the list of applications.
2684 The application structure contains the following fields:
2686 "app_name"
2688 The name of the application. For Red Hat-derived and Debian-
2689 derived Linux guests, this is the package name.
2690 "app_display_name"
2692 The display name of the application, sometimes localized to the
2693 install language of the guest operating system.
2694 If unavailable this is returned as an empty string "". Callers
2696 needing to display something can use "app_name" instead.
2697 "app_epoch"
2699 For package managers which use epochs, this contains the epoch of
2700 the package (an integer). If unavailable, this is returned as 0.
2701 "app_version"
2703 The version string of the application or package. If unavailable
2704 this is returned as an empty string "".
2705 "app_release"
2707 The release string of the application or package, for package
2708 managers that use this. If unavailable this is returned as an
2709 empty string "".
2710 "app_install_path"
2712 The installation path of the application (on operating systems such
2713 as Windows which use installation paths). This path is in the
2714 format used by the guest operating system, it is not a libguestfs
2715 path.
2716 If unavailable this is returned as an empty string "".
2718 "app_trans_path"
2720 The install path translated into a libguestfs path. If unavailable
2721 this is returned as an empty string "".
2722 "app_publisher"
2724 The name of the publisher of the application, for package managers
2725 that use this. If unavailable this is returned as an empty string
2726 "".
2727 "app_url"
2729 The URL (eg. upstream URL) of the application. If unavailable this
2730 is returned as an empty string "".
2731 "app_source_package"
2733 For packaging systems which support this, the name of the source
2734 package. If unavailable this is returned as an empty string "".
2735 "app_summary"
2737 A short (usually one line) description of the application or
2738 package. If unavailable this is returned as an empty string "".
2739 "app_description"
2741 A longer description of the application or package. If unavailable
2742 this is returned as an empty string "".
2743 Please read "INSPECTION" in guestfs(3) for more details.
2745 inspect-os
2747 inspect-os
2748 This function uses other libguestfs functions and certain heuristics to
2750 inspect the disk(s) (usually disks belonging to a virtual machine),
2751 looking for operating systems.
2752 The list returned is empty if no operating systems were found.
2754 If one operating system was found, then this returns a list with a
2756 single element, which is the name of the root filesystem of this
2757 operating system. It is also possible for this function to return a
2758 list containing more than one element, indicating a dual-boot or multi-
2759 boot virtual machine, with each element being the root filesystem of
2760 one of the operating systems.
2761 You can pass the root string(s) returned to other "inspect-get-*"
2763 functions in order to query further information about each operating
2764 system, such as the name and version.
2765 This function uses other libguestfs features such as "mount-ro" and
2767 "umount-all" in order to mount and unmount filesystems and look at the
2768 contents. This should be called with no disks currently mounted. The
2769 function may also use Augeas, so any existing Augeas handle will be
2770 closed.
2771 This function cannot decrypt encrypted disks. The caller must do that
2773 first (supplying the necessary keys) if the disk is encrypted.
2774 Please read "INSPECTION" in guestfs(3) for more details.
2776 See also "list-filesystems".
2778 is-blockdev
2780 is-blockdev path
2781 This returns "true" if and only if there is a block device with the
2783 given "path" name.
2784 See also "stat".
2786 is-busy
2788 is-busy
2789 This returns true iff this handle is busy processing a command (in the
2791 "BUSY" state).
2792 For more information on states, see guestfs(3).
2794 is-chardev
2796 is-chardev path
2797 This returns "true" if and only if there is a character device with the
2799 given "path" name.
2800 See also "stat".
2802 is-config
2804 is-config
2805 This returns true iff this handle is being configured (in the "CONFIG"
2807 state).
2808 For more information on states, see guestfs(3).
2810 is-dir
2812 is-dir path
2813 This returns "true" if and only if there is a directory with the given
2815 "path" name. Note that it returns false for other objects like files.
2816 See also "stat".
2818 is-fifo
2820 is-fifo path
2821 This returns "true" if and only if there is a FIFO (named pipe) with
2823 the given "path" name.
2824 See also "stat".
2826 is-file
2828 is-file path
2829 This returns "true" if and only if there is a regular file with the
2831 given "path" name. Note that it returns false for other objects like
2832 directories.
2833 See also "stat".
2835 is-launching
2837 is-launching
2838 This returns true iff this handle is launching the subprocess (in the
2840 "LAUNCHING" state).
2841 For more information on states, see guestfs(3).
2843 is-lv
2845 is-lv device
2846 This command tests whether "device" is a logical volume, and returns
2848 true iff this is the case.
2849 is-ready
2851 is-ready
2852 This returns true iff this handle is ready to accept commands (in the
2854 "READY" state).
2855 For more information on states, see guestfs(3).
2857 is-socket
2859 is-socket path
2860 This returns "true" if and only if there is a Unix domain socket with
2862 the given "path" name.
2863 See also "stat".
2865 is-symlink
2867 is-symlink path
2868 This returns "true" if and only if there is a symbolic link with the
2870 given "path" name.
2871 See also "stat".
2873 kill-subprocess
2875 kill-subprocess
2876 This kills the qemu subprocess. You should never need to call this.
2878 launch
2880 run
2881 launch
2882 Internally libguestfs is implemented by running a virtual machine using
2884 qemu(1).
2885 You should call this after configuring the handle (eg. adding drives)
2887 but before performing any actions.
2888 lchown
2890 lchown owner group path
2891 Change the file owner to "owner" and group to "group". This is like
2893 "chown" but if "path" is a symlink then the link itself is changed, not
2894 the target.
2895 Only numeric uid and gid are supported. If you want to use names, you
2897 will need to locate and parse the password file yourself (Augeas
2898 support makes this relatively easy).
2899 lgetxattr
2901 lgetxattr path name
2902 Get a single extended attribute from file "path" named "name". If
2904 "path" is a symlink, then this call returns an extended attribute from
2905 the symlink.
2906 Normally it is better to get all extended attributes from a file in one
2908 go by calling "getxattrs". However some Linux filesystem
2909 implementations are buggy and do not provide a way to list out
2910 attributes. For these filesystems (notably ntfs-3g) you have to know
2911 the names of the extended attributes you want in advance and call this
2912 function.
2913 Extended attribute values are blobs of binary data. If there is no
2915 extended attribute named "name", this returns an error.
2916 See also: "lgetxattrs", "getxattr", attr(5).
2918 lgetxattrs
2920 lgetxattrs path
2921 This is the same as "getxattrs", but if "path" is a symbolic link, then
2923 it returns the extended attributes of the link itself.
2924 list-devices
2926 list-devices
2927 List all the block devices.
2929 The full block device names are returned, eg. "/dev/sda".
2931 See also "list-filesystems".
2933 list-filesystems
2935 list-filesystems
2936 This inspection command looks for filesystems on partitions, block
2938 devices and logical volumes, returning a list of devices containing
2939 filesystems and their type.
2940 The return value is a hash, where the keys are the devices containing
2942 filesystems, and the values are the filesystem types. For example:
2943 "/dev/sda1" => "ntfs"
2945 "/dev/sda2" => "ext2"
2946 "/dev/vg_guest/lv_root" => "ext4"
2947 "/dev/vg_guest/lv_swap" => "swap"
2948 The value can have the special value "unknown", meaning the content of
2950 the device is undetermined or empty. "swap" means a Linux swap
2951 partition.
2952 This command runs other libguestfs commands, which might include
2954 "mount" and "umount", and therefore you should use this soon after
2955 launch and only when nothing is mounted.
2956 Not all of the filesystems returned will be mountable. In particular,
2958 swap partitions are returned in the list. Also this command does not
2959 check that each filesystem found is valid and mountable, and some
2960 filesystems might be mountable but require special options.
2961 Filesystems may not all belong to a single logical operating system
2962 (use "inspect-os" to look for OSes).
2963 list-partitions
2965 list-partitions
2966 List all the partitions detected on all block devices.
2968 The full partition device names are returned, eg. "/dev/sda1"
2970 This does not return logical volumes. For that you will need to call
2972 "lvs".
2973 See also "list-filesystems".
2975 ll
2977 ll directory
2978 List the files in "directory" (relative to the root directory, there is
2980 no cwd) in the format of 'ls -la'.
2981 This command is mostly useful for interactive sessions. It is not
2983 intended that you try to parse the output string.
2984 ln
2986 ln target linkname
2987 This command creates a hard link using the "ln" command.
2989 ln-f
2991 ln-f target linkname
2992 This command creates a hard link using the "ln -f" command. The "-f"
2994 option removes the link ("linkname") if it exists already.
2995 ln-s
2997 ln-s target linkname
2998 This command creates a symbolic link using the "ln -s" command.
3000 ln-sf
3002 ln-sf target linkname
3003 This command creates a symbolic link using the "ln -sf" command, The
3005 "-f" option removes the link ("linkname") if it exists already.
3006 lremovexattr
3008 lremovexattr xattr path
3009 This is the same as "removexattr", but if "path" is a symbolic link,
3011 then it removes an extended attribute of the link itself.
3012 ls
3014 ls directory
3015 List the files in "directory" (relative to the root directory, there is
3017 no cwd). The '.' and '..' entries are not returned, but hidden files
3018 are shown.
3019 This command is mostly useful for interactive sessions. Programs
3021 should probably use "readdir" instead.
3022 lsetxattr
3024 lsetxattr xattr val vallen path
3025 This is the same as "setxattr", but if "path" is a symbolic link, then
3027 it sets an extended attribute of the link itself.
3028 lstat
3030 lstat path
3031 Returns file information for the given "path".
3033 This is the same as "stat" except that if "path" is a symbolic link,
3035 then the link is stat-ed, not the file it refers to.
3036 This is the same as the lstat(2) system call.
3038 lstatlist
3040 lstatlist path 'names ...'
3041 This call allows you to perform the "lstat" operation on multiple
3043 files, where all files are in the directory "path". "names" is the
3044 list of files from this directory.
3045 On return you get a list of stat structs, with a one-to-one
3047 correspondence to the "names" list. If any name did not exist or could
3048 not be lstat'd, then the "ino" field of that structure is set to "-1".
3049 This call is intended for programs that want to efficiently list a
3051 directory contents without making many round-trips. See also
3052 "lxattrlist" for a similarly efficient call for getting extended
3053 attributes. Very long directory listings might cause the protocol
3054 message size to be exceeded, causing this call to fail. The caller
3055 must split up such requests into smaller groups of names.
3056 luks-add-key
3058 luks-add-key device keyslot
3059 This command adds a new key on LUKS device "device". "key" is any
3061 existing key, and is used to access the device. "newkey" is the new
3062 key to add. "keyslot" is the key slot that will be replaced.
3063 Note that if "keyslot" already contains a key, then this command will
3065 fail. You have to use "luks-kill-slot" first to remove that key.
3066 This command has one or more key or passphrase parameters. Guestfish
3068 will prompt for these separately.
3069 luks-close
3071 luks-close device
3072 This closes a LUKS device that was created earlier by "luks-open" or
3074 "luks-open-ro". The "device" parameter must be the name of the LUKS
3075 mapping device (ie. "/dev/mapper/mapname") and not the name of the
3076 underlying block device.
3077 luks-format
3079 luks-format device keyslot
3080 This command erases existing data on "device" and formats the device as
3082 a LUKS encrypted device. "key" is the initial key, which is added to
3083 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
3084 This command has one or more key or passphrase parameters. Guestfish
3086 will prompt for these separately.
3087 This command is dangerous. Without careful use you can easily destroy
3089 all your data.
3090 luks-format-cipher
3092 luks-format-cipher device keyslot cipher
3093 This command is the same as "luks-format" but it also allows you to set
3095 the "cipher" used.
3096 This command has one or more key or passphrase parameters. Guestfish
3098 will prompt for these separately.
3099 This command is dangerous. Without careful use you can easily destroy
3101 all your data.
3102 luks-kill-slot
3104 luks-kill-slot device keyslot
3105 This command deletes the key in key slot "keyslot" from the encrypted
3107 LUKS device "device". "key" must be one of the other keys.
3108 This command has one or more key or passphrase parameters. Guestfish
3110 will prompt for these separately.
3111 luks-open
3113 luks-open device mapname
3114 This command opens a block device which has been encrypted according to
3116 the Linux Unified Key Setup (LUKS) standard.
3117 "device" is the encrypted block device or partition.
3119 The caller must supply one of the keys associated with the LUKS block
3121 device, in the "key" parameter.
3122 This creates a new block device called "/dev/mapper/mapname". Reads
3124 and writes to this block device are decrypted from and encrypted to the
3125 underlying "device" respectively.
3126 If this block device contains LVM volume groups, then calling "vgscan"
3128 followed by "vg-activate-all" will make them visible.
3129 This command has one or more key or passphrase parameters. Guestfish
3131 will prompt for these separately.
3132 luks-open-ro
3134 luks-open-ro device mapname
3135 This is the same as "luks-open" except that a read-only mapping is
3137 created.
3138 This command has one or more key or passphrase parameters. Guestfish
3140 will prompt for these separately.
3141 lvcreate
3143 lvcreate logvol volgroup mbytes
3144 This creates an LVM logical volume called "logvol" on the volume group
3146 "volgroup", with "size" megabytes.
3147 lvm-canonical-lv-name
3149 lvm-canonical-lv-name lvname
3150 This converts alternative naming schemes for LVs that you might find to
3152 the canonical name. For example, "/dev/mapper/VG-LV" is converted to
3153 "/dev/VG/LV".
3154 This command returns an error if the "lvname" parameter does not refer
3156 to a logical volume.
3157 See also "is-lv".
3159 lvm-clear-filter
3161 lvm-clear-filter
3162 This undoes the effect of "lvm-set-filter". LVM will be able to see
3164 every block device.
3165 This command also clears the LVM cache and performs a volume group
3167 scan.
3168 lvm-remove-all
3170 lvm-remove-all
3171 This command removes all LVM logical volumes, volume groups and
3173 physical volumes.
3174 This command is dangerous. Without careful use you can easily destroy
3176 all your data.
3177 lvm-set-filter
3179 lvm-set-filter 'devices ...'
3180 This sets the LVM device filter so that LVM will only be able to "see"
3182 the block devices in the list "devices", and will ignore all other
3183 attached block devices.
3184 Where disk image(s) contain duplicate PVs or VGs, this command is
3186 useful to get LVM to ignore the duplicates, otherwise LVM can get
3187 confused. Note also there are two types of duplication possible:
3188 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
3189 cloned but just happen to have the same name. In normal operation you
3190 cannot create this situation, but you can do it outside LVM, eg. by
3191 cloning disk images or by bit twiddling inside the LVM metadata.
3192 This command also clears the LVM cache and performs a volume group
3194 scan.
3195 You can filter whole block devices or individual partitions.
3197 You cannot use this if any VG is currently in use (eg. contains a
3199 mounted filesystem), even if you are not filtering out that VG.
3200 lvremove
3202 lvremove device
3203 Remove an LVM logical volume "device", where "device" is the path to
3205 the LV, such as "/dev/VG/LV".
3206 You can also remove all LVs in a volume group by specifying the VG
3208 name, "/dev/VG".
3209 lvrename
3211 lvrename logvol newlogvol
3212 Rename a logical volume "logvol" with the new name "newlogvol".
3214 lvresize
3216 lvresize device mbytes
3217 This resizes (expands or shrinks) an existing LVM logical volume to
3219 "mbytes". When reducing, data in the reduced part is lost.
3220 lvresize-free
3222 lvresize-free lv percent
3223 This expands an existing logical volume "lv" so that it fills "pc"% of
3225 the remaining free space in the volume group. Commonly you would call
3226 this with pc = 100 which expands the logical volume as much as
3227 possible, using all remaining free space in the volume group.
3228 lvs
3230 lvs
3231 List all the logical volumes detected. This is the equivalent of the
3233 lvs(8) command.
3234 This returns a list of the logical volume device names (eg.
3236 "/dev/VolGroup00/LogVol00").
3237 See also "lvs-full", "list-filesystems".
3239 lvs-full
3241 lvs-full
3242 List all the logical volumes detected. This is the equivalent of the
3244 lvs(8) command. The "full" version includes all fields.
3245 lvuuid
3247 lvuuid device
3248 This command returns the UUID of the LVM LV "device".
3250 lxattrlist
3252 lxattrlist path 'names ...'
3253 This call allows you to get the extended attributes of multiple files,
3255 where all files are in the directory "path". "names" is the list of
3256 files from this directory.
3257 On return you get a flat list of xattr structs which must be
3259 interpreted sequentially. The first xattr struct always has a zero-
3260 length "attrname". "attrval" in this struct is zero-length to indicate
3261 there was an error doing "lgetxattr" for this file, or is a C string
3262 which is a decimal number (the number of following attributes for this
3263 file, which could be "0"). Then after the first xattr struct are the
3264 zero or more attributes for the first named file. This repeats for the
3265 second and subsequent files.
3266 This call is intended for programs that want to efficiently list a
3268 directory contents without making many round-trips. See also
3269 "lstatlist" for a similarly efficient call for getting standard stats.
3270 Very long directory listings might cause the protocol message size to
3271 be exceeded, causing this call to fail. The caller must split up such
3272 requests into smaller groups of names.
3273 mkdir
3275 mkdir path
3276 Create a directory named "path".
3278 mkdir-mode
3280 mkdir-mode path mode
3281 This command creates a directory, setting the initial permissions of
3283 the directory to "mode".
3284 For common Linux filesystems, the actual mode which is set will be
3286 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
3287 the mode in other ways.
3288 See also "mkdir", "umask"
3290 mkdir-p
3292 mkdir-p path
3293 Create a directory named "path", creating any parent directories as
3295 necessary. This is like the "mkdir -p" shell command.
3296 mkdtemp
3298 mkdtemp template
3299 This command creates a temporary directory. The "template" parameter
3301 should be a full pathname for the temporary directory name with the
3302 final six characters being "XXXXXX".
3303 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
3305 one being suitable for Windows filesystems.
3306 The name of the temporary directory that was created is returned.
3308 The temporary directory is created with mode 0700 and is owned by root.
3310 The caller is responsible for deleting the temporary directory and its
3312 contents after use.
3313 See also: mkdtemp(3)
3315 mke2fs-J
3317 mke2fs-J fstype blocksize device journal
3318 This creates an ext2/3/4 filesystem on "device" with an external
3320 journal on "journal". It is equivalent to the command:
3321 mke2fs -t fstype -b blocksize -J device=<journal> <device>
3323 See also "mke2journal".
3325 mke2fs-JL
3327 mke2fs-JL fstype blocksize device label
3328 This creates an ext2/3/4 filesystem on "device" with an external
3330 journal on the journal labeled "label".
3331 See also "mke2journal-L".
3333 mke2fs-JU
3335 mke2fs-JU fstype blocksize device uuid
3336 This creates an ext2/3/4 filesystem on "device" with an external
3338 journal on the journal with UUID "uuid".
3339 See also "mke2journal-U".
3341 mke2journal
3343 mke2journal blocksize device
3344 This creates an ext2 external journal on "device". It is equivalent to
3346 the command:
3347 mke2fs -O journal_dev -b blocksize device
3349 mke2journal-L
3351 mke2journal-L blocksize label device
3352 This creates an ext2 external journal on "device" with label "label".
3354 mke2journal-U
3356 mke2journal-U blocksize uuid device
3357 This creates an ext2 external journal on "device" with UUID "uuid".
3359 mkfifo
3361 mkfifo mode path
3362 This call creates a FIFO (named pipe) called "path" with mode "mode".
3364 It is just a convenient wrapper around "mknod".
3365 The mode actually set is affected by the umask.
3367 mkfs
3369 mkfs fstype device
3370 This creates a filesystem on "device" (usually a partition or LVM
3372 logical volume). The filesystem type is "fstype", for example "ext3".
3373 mkfs-b
3375 mkfs-b fstype blocksize device
3376 This call is similar to "mkfs", but it allows you to control the block
3378 size of the resulting filesystem. Supported block sizes depend on the
3379 filesystem type, but typically they are 1024, 2048 or 4096 only.
3380 For VFAT and NTFS the "blocksize" parameter is treated as the requested
3382 cluster size.
3383 This function is deprecated. In new code, use the "mkfs_opts" call
3385 instead.
3386 Deprecated functions will not be removed from the API, but the fact
3388 that they are deprecated indicates that there are problems with correct
3389 use of these functions.
3390 mkfs-opts
3392 mkfs-opts fstype device [blocksize:..]
3393 This function creates a filesystem on "device". The filesystem type is
3395 "fstype", for example "ext3".
3396 The optional arguments are:
3398 "blocksize"
3400 The filesystem block size. Supported block sizes depend on the
3401 filesystem type, but typically they are 1024, 2048 or 4096 for
3402 Linux ext2/3 filesystems.
3403 For VFAT and NTFS the "blocksize" parameter is treated as the
3405 requested cluster size.
3406 For UFS block sizes, please see mkfs.ufs(8).
3408 This command has one or more optional arguments. See "OPTIONAL
3410 ARGUMENTS".
3411 mkmountpoint
3413 mkmountpoint exemptpath
3414 "mkmountpoint" and "rmmountpoint" are specialized calls that can be
3416 used to create extra mountpoints before mounting the first filesystem.
3417 These calls are only necessary in some very limited circumstances,
3419 mainly the case where you want to mount a mix of unrelated and/or read-
3420 only filesystems together.
3421 For example, live CDs often contain a "Russian doll" nest of
3423 filesystems, an ISO outer layer, with a squashfs image inside, with an
3424 ext2/3 image inside that. You can unpack this as follows in guestfish:
3425 add-ro Fedora-11-i686-Live.iso
3427 run
3428 mkmountpoint /cd
3429 mkmountpoint /sqsh
3430 mkmountpoint /ext3fs
3431 mount /dev/sda /cd
3432 mount-loop /cd/LiveOS/squashfs.img /sqsh
3433 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
3434 The inner filesystem is now unpacked under the /ext3fs mountpoint.
3436 "mkmountpoint" is not compatible with "umount-all". You may get
3438 unexpected errors if you try to mix these calls. It is safest to
3439 manually unmount filesystems and remove mountpoints after use.
3440 "umount-all" unmounts filesystems by sorting the paths longest first,
3442 so for this to work for manual mountpoints, you must ensure that the
3443 innermost mountpoints have the longest pathnames, as in the example
3444 code above.
3445 For more details see
3447 <https://bugzilla.redhat.com/show_bug.cgi?id=599503>
3448 Autosync [see "set-autosync", this is set by default on handles] means
3450 that "umount-all" is called when the handle is closed which can also
3451 trigger these issues.
3452 mknod
3454 mknod mode devmajor devminor path
3455 This call creates block or character special devices, or named pipes
3457 (FIFOs).
3458 The "mode" parameter should be the mode, using the standard constants.
3460 "devmajor" and "devminor" are the device major and minor numbers, only
3461 used when creating block and character special devices.
3462 Note that, just like mknod(2), the mode must be bitwise OR'd with
3464 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
3465 a regular file). These constants are available in the standard Linux
3466 header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
3467 wrappers around this command which bitwise OR in the appropriate
3468 constant for you.
3469 The mode actually set is affected by the umask.
3471 mknod-b
3473 mknod-b mode devmajor devminor path
3474 This call creates a block device node called "path" with mode "mode"
3476 and device major/minor "devmajor" and "devminor". It is just a
3477 convenient wrapper around "mknod".
3478 The mode actually set is affected by the umask.
3480 mknod-c
3482 mknod-c mode devmajor devminor path
3483 This call creates a char device node called "path" with mode "mode" and
3485 device major/minor "devmajor" and "devminor". It is just a convenient
3486 wrapper around "mknod".
3487 The mode actually set is affected by the umask.
3489 mkswap
3491 mkswap device
3492 Create a swap partition on "device".
3494 mkswap-L
3496 mkswap-L label device
3497 Create a swap partition on "device" with label "label".
3499 Note that you cannot attach a swap label to a block device (eg.
3501 "/dev/sda"), just to a partition. This appears to be a limitation of
3502 the kernel or swap tools.
3503 mkswap-U
3505 mkswap-U uuid device
3506 Create a swap partition on "device" with UUID "uuid".
3508 mkswap-file
3510 mkswap-file path
3511 Create a swap file.
3513 This command just writes a swap file signature to an existing file. To
3515 create the file itself, use something like "fallocate".
3516 modprobe
3518 modprobe modulename
3519 This loads a kernel module in the appliance.
3521 The kernel module must have been whitelisted when libguestfs was built
3523 (see "appliance/kmod.whitelist.in" in the source).
3524 mount
3526 mount device mountpoint
3527 Mount a guest disk at a position in the filesystem. Block devices are
3529 named "/dev/sda", "/dev/sdb" and so on, as they were added to the
3530 guest. If those block devices contain partitions, they will have the
3531 usual names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style names can
3532 be used.
3533 The rules are the same as for mount(2): A filesystem must first be
3535 mounted on "/" before others can be mounted. Other filesystems can
3536 only be mounted on directories which already exist.
3537 The mounted filesystem is writable, if we have sufficient permissions
3539 on the underlying device.
3540 Important note: When you use this call, the filesystem options "sync"
3542 and "noatime" are set implicitly. This was originally done because we
3543 thought it would improve reliability, but it turns out that -o sync has
3544 a very large negative performance impact and negligible effect on
3545 reliability. Therefore we recommend that you avoid using "mount" in
3546 any code that needs performance, and instead use "mount-options" (use
3547 an empty string for the first parameter if you don't want any options).
3548 mount-loop
3550 mount-loop file mountpoint
3551 This command lets you mount "file" (a filesystem image in a file) on a
3553 mount point. It is entirely equivalent to the command "mount -o loop
3554 file mountpoint".
3555 mount-options
3557 mount-options options device mountpoint
3558 This is the same as the "mount" command, but it allows you to set the
3560 mount options as for the mount(8) -o flag.
3561 If the "options" parameter is an empty string, then no options are
3563 passed (all options default to whatever the filesystem uses).
3564 mount-ro
3566 mount-ro device mountpoint
3567 This is the same as the "mount" command, but it mounts the filesystem
3569 with the read-only (-o ro) flag.
3570 mount-vfs
3572 mount-vfs options vfstype device mountpoint
3573 This is the same as the "mount" command, but it allows you to set both
3575 the mount options and the vfstype as for the mount(8) -o and -t flags.
3576 mountpoints
3578 mountpoints
3579 This call is similar to "mounts". That call returns a list of devices.
3581 This one returns a hash table (map) of device name to directory where
3582 the device is mounted.
3583 mounts
3585 mounts
3586 This returns the list of currently mounted filesystems. It returns the
3588 list of devices (eg. "/dev/sda1", "/dev/VG/LV").
3589 Some internal mounts are not shown.
3591 See also: "mountpoints"
3593 mv
3595 mv src dest
3596 This moves a file from "src" to "dest" where "dest" is either a
3598 destination filename or destination directory.
3599 ntfs-3g-probe
3601 ntfs-3g-probe true|false device
3602 This command runs the ntfs-3g.probe(8) command which probes an NTFS
3604 "device" for mountability. (Not all NTFS volumes can be mounted read-
3605 write, and some cannot be mounted at all).
3606 "rw" is a boolean flag. Set it to true if you want to test if the
3608 volume can be mounted read-write. Set it to false if you want to test
3609 if the volume can be mounted read-only.
3610 The return value is an integer which 0 if the operation would succeed,
3612 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
3613 ntfsresize
3615 ntfsresize device
3616 This command resizes an NTFS filesystem, expanding or shrinking it to
3618 the size of the underlying device.
3619 Note: After the resize operation, the filesystem is marked as requiring
3621 a consistency check (for safety). You have to boot into Windows to
3622 perform this check and clear this condition. Furthermore, ntfsresize
3623 refuses to resize filesystems which have been marked in this way. So
3624 in effect it is not possible to call ntfsresize multiple times on a
3625 single filesystem without booting into Windows between each resize.
3626 See also ntfsresize(8).
3628 ntfsresize-size
3630 ntfsresize-size device size
3631 This command is the same as "ntfsresize" except that it allows you to
3633 specify the new size (in bytes) explicitly.
3634 part-add
3636 part-add device prlogex startsect endsect
3637 This command adds a partition to "device". If there is no partition
3639 table on the device, call "part-init" first.
3640 The "prlogex" parameter is the type of partition. Normally you should
3642 pass "p" or "primary" here, but MBR partition tables also support "l"
3643 (or "logical") and "e" (or "extended") partition types.
3644 "startsect" and "endsect" are the start and end of the partition in
3646 sectors. "endsect" may be negative, which means it counts backwards
3647 from the end of the disk ("-1" is the last sector).
3648 Creating a partition which covers the whole disk is not so easy. Use
3650 "part-disk" to do that.
3651 part-del
3653 part-del device partnum
3654 This command deletes the partition numbered "partnum" on "device".
3656 Note that in the case of MBR partitioning, deleting an extended
3658 partition also deletes any logical partitions it contains.
3659 part-disk
3661 part-disk device parttype
3662 This command is simply a combination of "part-init" followed by "part-
3664 add" to create a single primary partition covering the whole disk.
3665 "parttype" is the partition table type, usually "mbr" or "gpt", but
3667 other possible values are described in "part-init".
3668 This command is dangerous. Without careful use you can easily destroy
3670 all your data.
3671 part-get-bootable
3673 part-get-bootable device partnum
3674 This command returns true if the partition "partnum" on "device" has
3676 the bootable flag set.
3677 See also "part-set-bootable".
3679 part-get-mbr-id
3681 part-get-mbr-id device partnum
3682 Returns the MBR type byte (also known as the ID byte) from the numbered
3684 partition "partnum".
3685 Note that only MBR (old DOS-style) partitions have type bytes. You
3687 will get undefined results for other partition table types (see "part-
3688 get-parttype").
3689 part-get-parttype
3691 part-get-parttype device
3692 This command examines the partition table on "device" and returns the
3694 partition table type (format) being used.
3695 Common return values include: "msdos" (a DOS/Windows style MBR
3697 partition table), "gpt" (a GPT/EFI-style partition table). Other
3698 values are possible, although unusual. See "part-init" for a full
3699 list.
3700 part-init
3702 part-init device parttype
3703 This creates an empty partition table on "device" of one of the
3705 partition types listed below. Usually "parttype" should be either
3706 "msdos" or "gpt" (for large disks).
3707 Initially there are no partitions. Following this, you should call
3709 "part-add" for each partition required.
3710 Possible values for "parttype" are:
3712 efi | gpt
3714 Intel EFI / GPT partition table.
3715 This is recommended for >= 2 TB partitions that will be accessed
3717 from Linux and Intel-based Mac OS X. It also has limited backwards
3718 compatibility with the "mbr" format.
3719 mbr | msdos
3721 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
3722 and Windows. This partition type will only work for device sizes
3723 up to 2 TB. For large disks we recommend using "gpt".
3724 Other partition table types that may work but are not supported
3726 include:
3727 aix AIX disk labels.
3729 amiga | rdb
3731 Amiga "Rigid Disk Block" format.
3732 bsd BSD disk labels.
3734 dasd
3736 DASD, used on IBM mainframes.
3737 dvh MIPS/SGI volumes.
3739 mac Old Mac partition format. Modern Macs use "gpt".
3741 pc98
3743 NEC PC-98 format, common in Japan apparently.
3744 sun Sun disk labels.
3746 part-list
3748 part-list device
3749 This command parses the partition table on "device" and returns the
3751 list of partitions found.
3752 The fields in the returned structure are:
3754 part_num
3756 Partition number, counting from 1.
3757 part_start
3759 Start of the partition in bytes. To get sectors you have to divide
3760 by the device's sector size, see "blockdev-getss".
3761 part_end
3763 End of the partition in bytes.
3764 part_size
3766 Size of the partition in bytes.
3767 part-set-bootable
3769 part-set-bootable device partnum true|false
3770 This sets the bootable flag on partition numbered "partnum" on device
3772 "device". Note that partitions are numbered from 1.
3773 The bootable flag is used by some operating systems (notably Windows)
3775 to determine which partition to boot from. It is by no means
3776 universally recognized.
3777 part-set-mbr-id
3779 part-set-mbr-id device partnum idbyte
3780 Sets the MBR type byte (also known as the ID byte) of the numbered
3782 partition "partnum" to "idbyte". Note that the type bytes quoted in
3783 most documentation are in fact hexadecimal numbers, but usually
3784 documented without any leading "0x" which might be confusing.
3785 Note that only MBR (old DOS-style) partitions have type bytes. You
3787 will get undefined results for other partition table types (see "part-
3788 get-parttype").
3789 part-set-name
3791 part-set-name device partnum name
3792 This sets the partition name on partition numbered "partnum" on device
3794 "device". Note that partitions are numbered from 1.
3795 The partition name can only be set on certain types of partition table.
3797 This works on "gpt" but not on "mbr" partitions.
3798 part-to-dev
3800 part-to-dev partition
3801 This function takes a partition name (eg. "/dev/sdb1") and removes the
3803 partition number, returning the device name (eg. "/dev/sdb").
3804 The named partition must exist, for example as a string returned from
3806 "list-partitions".
3807 ping-daemon
3809 ping-daemon
3810 This is a test probe into the guestfs daemon running inside the qemu
3812 subprocess. Calling this function checks that the daemon responds to
3813 the ping message, without affecting the daemon or attached block
3814 device(s) in any other way.
3815 pread
3817 pread path count offset
3818 This command lets you read part of a file. It reads "count" bytes of
3820 the file, starting at "offset", from file "path".
3821 This may read fewer bytes than requested. For further details see the
3823 pread(2) system call.
3824 See also "pwrite", "pread-device".
3826 Because of the message protocol, there is a transfer limit of somewhere
3828 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3829 pread-device
3831 pread-device device count offset
3832 This command lets you read part of a file. It reads "count" bytes of
3834 "device", starting at "offset".
3835 This may read fewer bytes than requested. For further details see the
3837 pread(2) system call.
3838 See also "pread".
3840 Because of the message protocol, there is a transfer limit of somewhere
3842 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3843 pvcreate
3845 pvcreate device
3846 This creates an LVM physical volume on the named "device", where
3848 "device" should usually be a partition name such as "/dev/sda1".
3849 pvremove
3851 pvremove device
3852 This wipes a physical volume "device" so that LVM will no longer
3854 recognise it.
3855 The implementation uses the "pvremove" command which refuses to wipe
3857 physical volumes that contain any volume groups, so you have to remove
3858 those first.
3859 pvresize
3861 pvresize device
3862 This resizes (expands or shrinks) an existing LVM physical volume to
3864 match the new size of the underlying device.
3865 pvresize-size
3867 pvresize-size device size
3868 This command is the same as "pvresize" except that it allows you to
3870 specify the new size (in bytes) explicitly.
3871 pvs
3873 pvs
3874 List all the physical volumes detected. This is the equivalent of the
3876 pvs(8) command.
3877 This returns a list of just the device names that contain PVs (eg.
3879 "/dev/sda2").
3880 See also "pvs-full".
3882 pvs-full
3884 pvs-full
3885 List all the physical volumes detected. This is the equivalent of the
3887 pvs(8) command. The "full" version includes all fields.
3888 pvuuid
3890 pvuuid device
3891 This command returns the UUID of the LVM PV "device".
3893 pwrite
3895 pwrite path content offset
3896 This command writes to part of a file. It writes the data buffer
3898 "content" to the file "path" starting at offset "offset".
3899 This command implements the pwrite(2) system call, and like that system
3901 call it may not write the full data requested. The return value is the
3902 number of bytes that were actually written to the file. This could
3903 even be 0, although short writes are unlikely for regular files in
3904 ordinary circumstances.
3905 See also "pread", "pwrite-device".
3907 Because of the message protocol, there is a transfer limit of somewhere
3909 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3910 pwrite-device
3912 pwrite-device device content offset
3913 This command writes to part of a device. It writes the data buffer
3915 "content" to "device" starting at offset "offset".
3916 This command implements the pwrite(2) system call, and like that system
3918 call it may not write the full data requested (although short writes to
3919 disk devices and partitions are probably impossible with standard Linux
3920 kernels).
3921 See also "pwrite".
3923 Because of the message protocol, there is a transfer limit of somewhere
3925 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3926 read-file
3928 read-file path
3929 This calls returns the contents of the file "path" as a buffer.
3931 Unlike "cat", this function can correctly handle files that contain
3933 embedded ASCII NUL characters. However unlike "download", this
3934 function is limited in the total size of file that can be handled.
3935 Because of the message protocol, there is a transfer limit of somewhere
3937 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3938 read-lines
3940 read-lines path
3941 Return the contents of the file named "path".
3943 The file contents are returned as a list of lines. Trailing "LF" and
3945 "CRLF" character sequences are not returned.
3946 Note that this function cannot correctly handle binary files
3948 (specifically, files containing "\0" character which is treated as end
3949 of line). For those you need to use the "read-file" function which has
3950 a more complex interface.
3951 readdir
3953 readdir dir
3954 This returns the list of directory entries in directory "dir".
3956 All entries in the directory are returned, including "." and "..". The
3958 entries are not sorted, but returned in the same order as the
3959 underlying filesystem.
3960 Also this call returns basic file type information about each file.
3962 The "ftyp" field will contain one of the following characters:
3963 'b' Block special
3965 'c' Char special
3967 'd' Directory
3969 'f' FIFO (named pipe)
3971 'l' Symbolic link
3973 'r' Regular file
3975 's' Socket
3977 'u' Unknown file type
3979 '?' The readdir(3) call returned a "d_type" field with an unexpected
3981 value
3982 This function is primarily intended for use by programs. To get a
3984 simple list of names, use "ls". To get a printable directory for human
3985 consumption, use "ll".
3986 readlink
3988 readlink path
3989 This command reads the target of a symbolic link.
3991 readlinklist
3993 readlinklist path 'names ...'
3994 This call allows you to do a "readlink" operation on multiple files,
3996 where all files are in the directory "path". "names" is the list of
3997 files from this directory.
3998 On return you get a list of strings, with a one-to-one correspondence
4000 to the "names" list. Each string is the value of the symbolic link.
4001 If the readlink(2) operation fails on any name, then the corresponding
4003 result string is the empty string "". However the whole operation is
4004 completed even if there were readlink(2) errors, and so you can call
4005 this function with names where you don't know if they are symbolic
4006 links already (albeit slightly less efficient).
4007 This call is intended for programs that want to efficiently list a
4009 directory contents without making many round-trips. Very long
4010 directory listings might cause the protocol message size to be
4011 exceeded, causing this call to fail. The caller must split up such
4012 requests into smaller groups of names.
4013 realpath
4015 realpath path
4016 Return the canonicalized absolute pathname of "path". The returned
4018 path has no ".", ".." or symbolic link path elements.
4019 removexattr
4021 removexattr xattr path
4022 This call removes the extended attribute named "xattr" of the file
4024 "path".
4025 See also: "lremovexattr", attr(5).
4027 resize2fs
4029 resize2fs device
4030 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
4032 underlying device.
4033 Note: It is sometimes required that you run "e2fsck-f" on the "device"
4035 before calling this command. For unknown reasons "resize2fs" sometimes
4036 gives an error about this and sometimes not. In any case, it is always
4037 safe to call "e2fsck-f" before calling this function.
4038 resize2fs-size
4040 resize2fs-size device size
4041 This command is the same as "resize2fs" except that it allows you to
4043 specify the new size (in bytes) explicitly.
4044 rm
4046 rm path
4047 Remove the single file "path".
4049 rm-rf
4051 rm-rf path
4052 Remove the file or directory "path", recursively removing the contents
4054 if its a directory. This is like the "rm -rf" shell command.
4055 rmdir
4057 rmdir path
4058 Remove the single directory "path".
4060 rmmountpoint
4062 rmmountpoint exemptpath
4063 This calls removes a mountpoint that was previously created with
4065 "mkmountpoint". See "mkmountpoint" for full details.
4066 scrub-device
4068 scrub-device device
4069 This command writes patterns over "device" to make data retrieval more
4071 difficult.
4072 It is an interface to the scrub(1) program. See that manual page for
4074 more details.
4075 This command is dangerous. Without careful use you can easily destroy
4077 all your data.
4078 scrub-file
4080 scrub-file file
4081 This command writes patterns over a file to make data retrieval more
4083 difficult.
4084 The file is removed after scrubbing.
4086 It is an interface to the scrub(1) program. See that manual page for
4088 more details.
4089 scrub-freespace
4091 scrub-freespace dir
4092 This command creates the directory "dir" and then fills it with files
4094 until the filesystem is full, and scrubs the files as for "scrub-file",
4095 and deletes them. The intention is to scrub any free space on the
4096 partition containing "dir".
4097 It is an interface to the scrub(1) program. See that manual page for
4099 more details.
4100 set-append
4102 append
4103 set-append append
4104 This function is used to add additional options to the guest kernel
4106 command line.
4107 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
4109 environment variable.
4110 Setting "append" to "NULL" means no additional options are passed
4112 (libguestfs always adds a few of its own).
4113 set-autosync
4115 autosync
4116 set-autosync true|false
4117 If "autosync" is true, this enables autosync. Libguestfs will make a
4119 best effort attempt to run "umount-all" followed by "sync" when the
4120 handle is closed (also if the program exits without closing handles).
4121 This is enabled by default (since libguestfs 1.5.24, previously it was
4123 disabled by default).
4124 set-direct
4126 direct
4127 set-direct true|false
4128 If the direct appliance mode flag is enabled, then stdin and stdout are
4130 passed directly through to the appliance once it is launched.
4131 One consequence of this is that log messages aren't caught by the
4133 library and handled by "set-log-message-callback", but go straight to
4134 stdout.
4135 You probably don't want to use this unless you know what you are doing.
4137 The default is disabled.
4139 set-e2label
4141 set-e2label device label
4142 This sets the ext2/3/4 filesystem label of the filesystem on "device"
4144 to "label". Filesystem labels are limited to 16 characters.
4145 You can use either "tune2fs-l" or "get-e2label" to return the existing
4147 label on a filesystem.
4148 set-e2uuid
4150 set-e2uuid device uuid
4151 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
4153 "uuid". The format of the UUID and alternatives such as "clear",
4154 "random" and "time" are described in the tune2fs(8) manpage.
4155 You can use either "tune2fs-l" or "get-e2uuid" to return the existing
4157 UUID of a filesystem.
4158 set-memsize
4160 memsize
4161 set-memsize memsize
4162 This sets the memory size in megabytes allocated to the qemu
4164 subprocess. This only has any effect if called before "launch".
4165 You can also change this by setting the environment variable
4167 "LIBGUESTFS_MEMSIZE" before the handle is created.
4168 For more information on the architecture of libguestfs, see guestfs(3).
4170 set-network
4172 network
4173 set-network true|false
4174 If "network" is true, then the network is enabled in the libguestfs
4176 appliance. The default is false.
4177 This affects whether commands are able to access the network (see
4179 "RUNNING COMMANDS" in guestfs(3)).
4180 You must call this before calling "launch", otherwise it has no effect.
4182 set-path
4184 path
4185 set-path searchpath
4186 Set the path that libguestfs searches for kernel and initrd.img.
4188 The default is "$libdir/guestfs" unless overridden by setting
4190 "LIBGUESTFS_PATH" environment variable.
4191 Setting "path" to "NULL" restores the default path.
4193 set-qemu
4195 qemu
4196 set-qemu qemu
4197 Set the qemu binary that we will use.
4199 The default is chosen when the library was compiled by the configure
4201 script.
4202 You can also override this by setting the "LIBGUESTFS_QEMU" environment
4204 variable.
4205 Setting "qemu" to "NULL" restores the default qemu binary.
4207 Note that you should call this function as early as possible after
4209 creating the handle. This is because some pre-launch operations depend
4210 on testing qemu features (by running "qemu -help"). If the qemu binary
4211 changes, we don't retest features, and so you might see inconsistent
4212 results. Using the environment variable "LIBGUESTFS_QEMU" is safest of
4213 all since that picks the qemu binary at the same time as the handle is
4214 created.
4215 set-recovery-proc
4217 recovery-proc
4218 set-recovery-proc true|false
4219 If this is called with the parameter "false" then "launch" does not
4221 create a recovery process. The purpose of the recovery process is to
4222 stop runaway qemu processes in the case where the main program aborts
4223 abruptly.
4224 This only has any effect if called before "launch", and the default is
4226 true.
4227 About the only time when you would want to disable this is if the main
4229 process will fork itself into the background ("daemonize" itself). In
4230 this case the recovery process thinks that the main program has
4231 disappeared and so kills qemu, which is not very helpful.
4232 set-selinux
4234 selinux
4235 set-selinux true|false
4236 This sets the selinux flag that is passed to the appliance at boot
4238 time. The default is "selinux=0" (disabled).
4239 Note that if SELinux is enabled, it is always in Permissive mode
4241 ("enforcing=0").
4242 For more information on the architecture of libguestfs, see guestfs(3).
4244 set-trace
4246 trace
4247 set-trace true|false
4248 If the command trace flag is set to 1, then commands are printed on
4250 stderr before they are executed in a format which is very similar to
4251 the one used by guestfish. In other words, you can run a program with
4252 this enabled, and you will get out a script which you can feed to
4253 guestfish to perform the same set of actions.
4254 If you want to trace C API calls into libguestfs (and other libraries)
4256 then possibly a better way is to use the external ltrace(1) command.
4257 Command traces are disabled unless the environment variable
4259 "LIBGUESTFS_TRACE" is defined and set to 1.
4260 set-verbose
4262 verbose
4263 set-verbose true|false
4264 If "verbose" is true, this turns on verbose messages (to "stderr").
4266 Verbose messages are disabled unless the environment variable
4268 "LIBGUESTFS_DEBUG" is defined and set to 1.
4269 setcon
4271 setcon context
4272 This sets the SELinux security context of the daemon to the string
4274 "context".
4275 See the documentation about SELINUX in guestfs(3).
4277 setxattr
4279 setxattr xattr val vallen path
4280 This call sets the extended attribute named "xattr" of the file "path"
4282 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
4283 data.
4284 See also: "lsetxattr", attr(5).
4286 sfdisk
4288 sfdisk device cyls heads sectors 'lines ...'
4289 This is a direct interface to the sfdisk(8) program for creating
4291 partitions on block devices.
4292 "device" should be a block device, for example "/dev/sda".
4294 "cyls", "heads" and "sectors" are the number of cylinders, heads and
4296 sectors on the device, which are passed directly to sfdisk as the -C,
4297 -H and -S parameters. If you pass 0 for any of these, then the
4298 corresponding parameter is omitted. Usually for 'large' disks, you can
4299 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
4300 rather, the kernel) cannot work out the right geometry and you will
4301 need to tell it.
4302 "lines" is a list of lines that we feed to "sfdisk". For more
4304 information refer to the sfdisk(8) manpage.
4305 To create a single partition occupying the whole disk, you would pass
4307 "lines" as a single element list, when the single element being the
4308 string "," (comma).
4309 See also: "sfdisk-l", "sfdisk-N", "part-init"
4311 This command is dangerous. Without careful use you can easily destroy
4313 all your data.
4314 sfdiskM
4316 sfdiskM device 'lines ...'
4317 This is a simplified interface to the "sfdisk" command, where partition
4319 sizes are specified in megabytes only (rounded to the nearest cylinder)
4320 and you don't need to specify the cyls, heads and sectors parameters
4321 which were rarely if ever used anyway.
4322 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
4324 This command is dangerous. Without careful use you can easily destroy
4326 all your data.
4327 sfdisk-N
4329 sfdisk-N device partnum cyls heads sectors line
4330 This runs sfdisk(8) option to modify just the single partition "n"
4332 (note: "n" counts from 1).
4333 For other parameters, see "sfdisk". You should usually pass 0 for the
4335 cyls/heads/sectors parameters.
4336 See also: "part-add"
4338 This command is dangerous. Without careful use you can easily destroy
4340 all your data.
4341 sfdisk-disk-geometry
4343 sfdisk-disk-geometry device
4344 This displays the disk geometry of "device" read from the partition
4346 table. Especially in the case where the underlying block device has
4347 been resized, this can be different from the kernel's idea of the
4348 geometry (see "sfdisk-kernel-geometry").
4349 The result is in human-readable format, and not designed to be parsed.
4351 sfdisk-kernel-geometry
4353 sfdisk-kernel-geometry device
4354 This displays the kernel's idea of the geometry of "device".
4356 The result is in human-readable format, and not designed to be parsed.
4358 sfdisk-l
4360 sfdisk-l device
4361 This displays the partition table on "device", in the human-readable
4363 output of the sfdisk(8) command. It is not intended to be parsed.
4364 See also: "part-list"
4366 sh
4368 sh command
4369 This call runs a command from the guest filesystem via the guest's
4371 "/bin/sh".
4372 This is like "command", but passes the command to:
4374 /bin/sh -c "command"
4376 Depending on the guest's shell, this usually results in wildcards being
4378 expanded, shell expressions being interpolated and so on.
4379 All the provisos about "command" apply to this call.
4381 sh-lines
4383 sh-lines command
4384 This is the same as "sh", but splits the result into a list of lines.
4386 See also: "command-lines"
4388 sleep
4390 sleep secs
4391 Sleep for "secs" seconds.
4393 stat
4395 stat path
4396 Returns file information for the given "path".
4398 This is the same as the stat(2) system call.
4400 statvfs
4402 statvfs path
4403 Returns file system statistics for any mounted file system. "path"
4405 should be a file or directory in the mounted file system (typically it
4406 is the mount point itself, but it doesn't need to be).
4407 This is the same as the statvfs(2) system call.
4409 strings
4411 strings path
4412 This runs the strings(1) command on a file and returns the list of
4414 printable strings found.
4415 Because of the message protocol, there is a transfer limit of somewhere
4417 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4418 strings-e
4420 strings-e encoding path
4421 This is like the "strings" command, but allows you to specify the
4423 encoding of strings that are looked for in the source file "path".
4424 Allowed encodings are:
4426 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
4428 parts of ISO-8859-X (this is what "strings" uses).
4429 S Single 8-bit-byte characters.
4431 b 16-bit big endian strings such as those encoded in UTF-16BE or
4433 UCS-2BE.
4434 l (lower case letter L)
4436 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
4437 for examining binaries in Windows guests.
4438 B 32-bit big endian such as UCS-4BE.
4440 L 32-bit little endian such as UCS-4LE.
4442 The returned strings are transcoded to UTF-8.
4444 Because of the message protocol, there is a transfer limit of somewhere
4446 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4447 swapoff-device
4449 swapoff-device device
4450 This command disables the libguestfs appliance swap device or partition
4452 named "device". See "swapon-device".
4453 swapoff-file
4455 swapoff-file file
4456 This command disables the libguestfs appliance swap on file.
4458 swapoff-label
4460 swapoff-label label
4461 This command disables the libguestfs appliance swap on labeled swap
4463 partition.
4464 swapoff-uuid
4466 swapoff-uuid uuid
4467 This command disables the libguestfs appliance swap partition with the
4469 given UUID.
4470 swapon-device
4472 swapon-device device
4473 This command enables the libguestfs appliance to use the swap device or
4475 partition named "device". The increased memory is made available for
4476 all commands, for example those run using "command" or "sh".
4477 Note that you should not swap to existing guest swap partitions unless
4479 you know what you are doing. They may contain hibernation information,
4480 or other information that the guest doesn't want you to trash. You
4481 also risk leaking information about the host to the guest this way.
4482 Instead, attach a new host device to the guest and swap on that.
4483 swapon-file
4485 swapon-file file
4486 This command enables swap to a file. See "swapon-device" for other
4488 notes.
4489 swapon-label
4491 swapon-label label
4492 This command enables swap to a labeled swap partition. See "swapon-
4494 device" for other notes.
4495 swapon-uuid
4497 swapon-uuid uuid
4498 This command enables swap to a swap partition with the given UUID. See
4500 "swapon-device" for other notes.
4501 sync
4503 sync
4504 This syncs the disk, so that any writes are flushed through to the
4506 underlying disk image.
4507 You should always call this if you have modified a disk image, before
4509 closing the handle.
4510 tail
4512 tail path
4513 This command returns up to the last 10 lines of a file as a list of
4515 strings.
4516 Because of the message protocol, there is a transfer limit of somewhere
4518 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4519 tail-n
4521 tail-n nrlines path
4522 If the parameter "nrlines" is a positive number, this returns the last
4524 "nrlines" lines of the file "path".
4525 If the parameter "nrlines" is a negative number, this returns lines
4527 from the file "path", starting with the "-nrlines"th line.
4528 If the parameter "nrlines" is zero, this returns an empty list.
4530 Because of the message protocol, there is a transfer limit of somewhere
4532 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4533 tar-in
4535 tar-in (tarfile|-) directory
4536 This command uploads and unpacks local file "tarfile" (an uncompressed
4538 tar file) into "directory".
4539 To upload a compressed tarball, use "tgz-in" or "txz-in".
4541 Use "-" instead of a filename to read/write from stdin/stdout.
4543 tar-out
4545 tar-out directory (tarfile|-)
4546 This command packs the contents of "directory" and downloads it to
4548 local file "tarfile".
4549 To download a compressed tarball, use "tgz-out" or "txz-out".
4551 Use "-" instead of a filename to read/write from stdin/stdout.
4553 tgz-in
4555 tgz-in (tarball|-) directory
4556 This command uploads and unpacks local file "tarball" (a gzip
4558 compressed tar file) into "directory".
4559 To upload an uncompressed tarball, use "tar-in".
4561 Use "-" instead of a filename to read/write from stdin/stdout.
4563 tgz-out
4565 tgz-out directory (tarball|-)
4566 This command packs the contents of "directory" and downloads it to
4568 local file "tarball".
4569 To download an uncompressed tarball, use "tar-out".
4571 Use "-" instead of a filename to read/write from stdin/stdout.
4573 touch
4575 touch path
4576 Touch acts like the touch(1) command. It can be used to update the
4578 timestamps on a file, or, if the file does not exist, to create a new
4579 zero-length file.
4580 This command only works on regular files, and will fail on other file
4582 types such as directories, symbolic links, block special etc.
4583 truncate
4585 truncate path
4586 This command truncates "path" to a zero-length file. The file must
4588 exist already.
4589 truncate-size
4591 truncate-size path size
4592 This command truncates "path" to size "size" bytes. The file must
4594 exist already.
4595 If the current file size is less than "size" then the file is extended
4597 to the required size with zero bytes. This creates a sparse file (ie.
4598 disk blocks are not allocated for the file until you write to it). To
4599 create a non-sparse file of zeroes, use "fallocate64" instead.
4600 tune2fs-l
4602 tune2fs-l device
4603 This returns the contents of the ext2, ext3 or ext4 filesystem
4605 superblock on "device".
4606 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
4608 for more details. The list of fields returned isn't clearly defined,
4609 and depends on both the version of "tune2fs" that libguestfs was built
4610 against, and the filesystem itself.
4611 txz-in
4613 txz-in (tarball|-) directory
4614 This command uploads and unpacks local file "tarball" (an xz compressed
4616 tar file) into "directory".
4617 Use "-" instead of a filename to read/write from stdin/stdout.
4619 txz-out
4621 txz-out directory (tarball|-)
4622 This command packs the contents of "directory" and downloads it to
4624 local file "tarball" (as an xz compressed tar archive).
4625 Use "-" instead of a filename to read/write from stdin/stdout.
4627 umask
4629 umask mask
4630 This function sets the mask used for creating new files and device
4632 nodes to "mask & 0777".
4633 Typical umask values would be 022 which creates new files with
4635 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
4636 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
4637 The default umask is 022. This is important because it means that
4639 directories and device nodes will be created with 0644 or 0755 mode
4640 even if you specify 0777.
4641 See also "get-umask", umask(2), "mknod", "mkdir".
4643 This call returns the previous umask.
4645 umount
4647 unmount
4648 umount pathordevice
4649 This unmounts the given filesystem. The filesystem may be specified
4651 either by its mountpoint (path) or the device which contains the
4652 filesystem.
4653 umount-all
4655 unmount-all
4656 umount-all
4657 This unmounts all mounted filesystems.
4659 Some internal mounts are not unmounted by this call.
4661 upload
4663 upload (filename|-) remotefilename
4664 Upload local file "filename" to "remotefilename" on the filesystem.
4666 "filename" can also be a named pipe.
4668 See also "download".
4670 Use "-" instead of a filename to read/write from stdin/stdout.
4672 upload-offset
4674 upload-offset (filename|-) remotefilename offset
4675 Upload local file "filename" to "remotefilename" on the filesystem.
4677 "remotefilename" is overwritten starting at the byte "offset"
4679 specified. The intention is to overwrite parts of existing files or
4680 devices, although if a non-existant file is specified then it is
4681 created with a "hole" before "offset". The size of the data written is
4682 implicit in the size of the source "filename".
4683 Note that there is no limit on the amount of data that can be uploaded
4685 with this call, unlike with "pwrite", and this call always writes the
4686 full amount unless an error occurs.
4687 See also "upload", "pwrite".
4689 Use "-" instead of a filename to read/write from stdin/stdout.
4691 utimens
4693 utimens path atsecs atnsecs mtsecs mtnsecs
4694 This command sets the timestamps of a file with nanosecond precision.
4696 "atsecs, atnsecs" are the last access time (atime) in secs and
4698 nanoseconds from the epoch.
4699 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
4701 nanoseconds from the epoch.
4702 If the *nsecs field contains the special value "-1" then the
4704 corresponding timestamp is set to the current time. (The *secs field
4705 is ignored in this case).
4706 If the *nsecs field contains the special value "-2" then the
4708 corresponding timestamp is left unchanged. (The *secs field is ignored
4709 in this case).
4710 version
4712 version
4713 Return the libguestfs version number that the program is linked
4715 against.
4716 Note that because of dynamic linking this is not necessarily the
4718 version of libguestfs that you compiled against. You can compile the
4719 program, and then at runtime dynamically link against a completely
4720 different "libguestfs.so" library.
4721 This call was added in version 1.0.58. In previous versions of
4723 libguestfs there was no way to get the version number. From C code you
4724 can use dynamic linker functions to find out if this symbol exists (if
4725 it doesn't, then it's an earlier version).
4726 The call returns a structure with four elements. The first three
4728 ("major", "minor" and "release") are numbers and correspond to the
4729 usual version triplet. The fourth element ("extra") is a string and is
4730 normally empty, but may be used for distro-specific information.
4731 To construct the original version string:
4733 "$major.$minor.$release$extra"
4734 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
4736 Note: Don't use this call to test for availability of features. In
4738 enterprise distributions we backport features from later versions into
4739 earlier versions, making this an unreliable way to test for features.
4740 Use "available" instead.
4741 vfs-label
4743 vfs-label device
4744 This returns the filesystem label of the filesystem on "device".
4746 If the filesystem is unlabeled, this returns the empty string.
4748 To find a filesystem from the label, use "findfs-label".
4750 vfs-type
4752 vfs-type device
4753 This command gets the filesystem type corresponding to the filesystem
4755 on "device".
4756 For most filesystems, the result is the name of the Linux VFS module
4758 which would be used to mount this filesystem if you mounted it without
4759 specifying the filesystem type. For example a string such as "ext3" or
4760 "ntfs".
4761 vfs-uuid
4763 vfs-uuid device
4764 This returns the filesystem UUID of the filesystem on "device".
4766 If the filesystem does not have a UUID, this returns the empty string.
4768 To find a filesystem from the UUID, use "findfs-uuid".
4770 vg-activate
4772 vg-activate true|false 'volgroups ...'
4773 This command activates or (if "activate" is false) deactivates all
4775 logical volumes in the listed volume groups "volgroups". If activated,
4776 then they are made known to the kernel, ie. they appear as
4777 "/dev/mapper" devices. If deactivated, then those devices disappear.
4778 This command is the same as running "vgchange -a y|n volgroups..."
4780 Note that if "volgroups" is an empty list then all volume groups are
4782 activated or deactivated.
4783 vg-activate-all
4785 vg-activate-all true|false
4786 This command activates or (if "activate" is false) deactivates all
4788 logical volumes in all volume groups. If activated, then they are made
4789 known to the kernel, ie. they appear as "/dev/mapper" devices. If
4790 deactivated, then those devices disappear.
4791 This command is the same as running "vgchange -a y|n"
4793 vgcreate
4795 vgcreate volgroup 'physvols ...'
4796 This creates an LVM volume group called "volgroup" from the non-empty
4798 list of physical volumes "physvols".
4799 vglvuuids
4801 vglvuuids vgname
4802 Given a VG called "vgname", this returns the UUIDs of all the logical
4804 volumes created in this volume group.
4805 You can use this along with "lvs" and "lvuuid" calls to associate
4807 logical volumes and volume groups.
4808 See also "vgpvuuids".
4810 vgpvuuids
4812 vgpvuuids vgname
4813 Given a VG called "vgname", this returns the UUIDs of all the physical
4815 volumes that this volume group resides on.
4816 You can use this along with "pvs" and "pvuuid" calls to associate
4818 physical volumes and volume groups.
4819 See also "vglvuuids".
4821 vgremove
4823 vgremove vgname
4824 Remove an LVM volume group "vgname", (for example "VG").
4826 This also forcibly removes all logical volumes in the volume group (if
4828 any).
4829 vgrename
4831 vgrename volgroup newvolgroup
4832 Rename a volume group "volgroup" with the new name "newvolgroup".
4834 vgs
4836 vgs
4837 List all the volumes groups detected. This is the equivalent of the
4839 vgs(8) command.
4840 This returns a list of just the volume group names that were detected
4842 (eg. "VolGroup00").
4843 See also "vgs-full".
4845 vgs-full
4847 vgs-full
4848 List all the volumes groups detected. This is the equivalent of the
4850 vgs(8) command. The "full" version includes all fields.
4851 vgscan
4853 vgscan
4854 This rescans all block devices and rebuilds the list of LVM physical
4856 volumes, volume groups and logical volumes.
4857 vguuid
4859 vguuid vgname
4860 This command returns the UUID of the LVM VG named "vgname".
4862 wc-c
4864 wc-c path
4865 This command counts the characters in a file, using the "wc -c"
4867 external command.
4868 wc-l
4870 wc-l path
4871 This command counts the lines in a file, using the "wc -l" external
4873 command.
4874 wc-w
4876 wc-w path
4877 This command counts the words in a file, using the "wc -w" external
4879 command.
4880 write
4882 write path content
4883 This call creates a file called "path". The content of the file is the
4885 string "content" (which can contain any 8 bit data).
4886 Because of the message protocol, there is a transfer limit of somewhere
4888 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4889 write-file
4891 write-file path content size
4892 This call creates a file called "path". The contents of the file is
4894 the string "content" (which can contain any 8 bit data), with length
4895 "size".
4896 As a special case, if "size" is 0 then the length is calculated using
4898 "strlen" (so in this case the content cannot contain embedded ASCII
4899 NULs).
4900 NB. Owing to a bug, writing content containing ASCII NUL characters
4902 does not work, even if the length is specified.
4903 Because of the message protocol, there is a transfer limit of somewhere
4905 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4906 This function is deprecated. In new code, use the "write" call
4908 instead.
4909 Deprecated functions will not be removed from the API, but the fact
4911 that they are deprecated indicates that there are problems with correct
4912 use of these functions.
4913 zegrep
4915 zegrep regex path
4916 This calls the external "zegrep" program and returns the matching
4918 lines.
4919 Because of the message protocol, there is a transfer limit of somewhere
4921 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4922 zegrepi
4924 zegrepi regex path
4925 This calls the external "zegrep -i" program and returns the matching
4927 lines.
4928 Because of the message protocol, there is a transfer limit of somewhere
4930 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4931 zero
4933 zero device
4934 This command writes zeroes over the first few blocks of "device".
4936 How many blocks are zeroed isn't specified (but it's not enough to
4938 securely wipe the device). It should be sufficient to remove any
4939 partition tables, filesystem superblocks and so on.
4940 See also: "zero-device", "scrub-device".
4942 zero-device
4944 zero-device device
4945 This command writes zeroes over the entire "device". Compare with
4947 "zero" which just zeroes the first few blocks of a device.
4948 This command is dangerous. Without careful use you can easily destroy
4950 all your data.
4951 zerofree
4953 zerofree device
4954 This runs the zerofree program on "device". This program claims to
4956 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
4957 it possible to compress the filesystem more effectively.
4958 You should not run this program if the filesystem is mounted.
4960 It is possible that using this program can damage the filesystem or
4962 data on the filesystem.
4963 zfgrep
4965 zfgrep pattern path
4966 This calls the external "zfgrep" program and returns the matching
4968 lines.
4969 Because of the message protocol, there is a transfer limit of somewhere
4971 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4972 zfgrepi
4974 zfgrepi pattern path
4975 This calls the external "zfgrep -i" program and returns the matching
4977 lines.
4978 Because of the message protocol, there is a transfer limit of somewhere
4980 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4981 zfile
4983 zfile meth path
4984 This command runs "file" after first decompressing "path" using
4986 "method".
4987 "method" must be one of "gzip", "compress" or "bzip2".
4989 Since 1.0.63, use "file" instead which can now process compressed
4991 files.
4992 This function is deprecated. In new code, use the "file" call instead.
4994 Deprecated functions will not be removed from the API, but the fact
4996 that they are deprecated indicates that there are problems with correct
4997 use of these functions.
4998 zgrep
5000 zgrep regex path
5001 This calls the external "zgrep" program and returns the matching lines.
5003 Because of the message protocol, there is a transfer limit of somewhere
5005 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5006 zgrepi
5008 zgrepi regex path
5009 This calls the external "zgrep -i" program and returns the matching
5011 lines.
5012 Because of the message protocol, there is a transfer limit of somewhere
5014 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5015
5017 guestfish returns 0 if the commands completed without error, or 1 if
5018 there was an error.
5019
5021 EDITOR
5022 The "edit" command uses $EDITOR as the editor. If not set, it uses
5023 "vi".
5024 GUESTFISH_PID
5026 Used with the --remote option to specify the remote guestfish
5027 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
5028 SOCKET".
5029 HEXEDITOR
5031 The "hexedit" command uses $HEXEDITOR as the external hex editor.
5032 If not specified, the external hexedit(1) program is used.
5033 HOME
5035 If compiled with GNU readline support, various files in the home
5036 directory can be used. See "FILES".
5037 LIBGUESTFS_APPEND
5039 Pass additional options to the guest kernel.
5040 LIBGUESTFS_DEBUG
5042 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
5043 same effect as using the -v option.
5044 LIBGUESTFS_MEMSIZE
5046 Set the memory allocated to the qemu process, in megabytes. For
5047 example:
5048 LIBGUESTFS_MEMSIZE=700
5050 LIBGUESTFS_PATH
5052 Set the path that guestfish uses to search for kernel and
5053 initrd.img. See the discussion of paths in guestfs(3).
5054 LIBGUESTFS_QEMU
5056 Set the default qemu binary that libguestfs uses. If not set, then
5057 the qemu which was found at compile time by the configure script is
5058 used.
5059 LIBGUESTFS_TRACE
5061 Set "LIBGUESTFS_TRACE=1" to enable command traces.
5062 PAGER
5064 The "more" command uses $PAGER as the pager. If not set, it uses
5065 "more".
5066 TMPDIR
5068 Location of temporary directory, defaults to "/tmp".
5069 If libguestfs was compiled to use the supermin appliance then the
5071 real appliance is cached in this directory, shared between all
5072 handles belonging to the same EUID. You can use $TMPDIR to
5073 configure another directory to use in case "/tmp" is not large
5074 enough.
5075
5077 $HOME/.guestfish
5078 If compiled with GNU readline support, then the command history is
5079 saved in this file.
5080 $HOME/.inputrc
5082 /etc/inputrc
5083 If compiled with GNU readline support, then these files can be used
5084 to configure readline. For further information, please see
5085 "INITIALIZATION FILE" in readline(3).
5086 To write rules which only apply to guestfish, use:
5088 $if guestfish
5090 ...
5091 $endif
5092 Variables that you can set in inputrc that change the behaviour of
5094 guestfish in useful ways include:
5095 completion-ignore-case (default: on)
5097 By default, guestfish will ignore case when tab-completing
5098 paths on the disk. Use:
5099 set completion-ignore-case off
5101 to make guestfish case sensitive.
5103 test1.img
5105 test2.img (etc)
5106 When using the "-N" or "--new" option, the prepared disk or
5107 filesystem will be created in the file "test1.img" in the current
5108 directory. The second use of "-N" will use "test2.img" and so on.
5109 Any existing file with the same name will be overwritten.
5110
5112 guestfs(3), <http://libguestfs.org/>, virt-cat(1), virt-df(1),
5113 virt-edit(1), virt-filesystems(1), virt-inspector(1),
5114 virt-list-filesystems(1), virt-list-partitions(1), virt-ls(1),
5115 virt-make-fs(1), virt-rescue(1), virt-resize(1), virt-tar(1),
5116 virt-win-reg(1), hexedit(1).
5117
5119 Richard W.M. Jones ("rjones at redhat dot com")
5120
5122 Copyright (C) 2009-2010 Red Hat Inc. <http://libguestfs.org/>
5123 This program is free software; you can redistribute it and/or modify it
5125 under the terms of the GNU General Public License as published by the
5126 Free Software Foundation; either version 2 of the License, or (at your
5127 option) any later version.
5128 This program is distributed in the hope that it will be useful, but
5130 WITHOUT ANY WARRANTY; without even the implied warranty of
5131 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5132 General Public License for more details.
5133 You should have received a copy of the GNU General Public License along
5135 with this program; if not, write to the Free Software Foundation, Inc.,
5136 675 Mass Ave, Cambridge, MA 02139, USA.
5137libguestfs-1.8.15 2011-11-10 guestfish(1)