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 Domain UUIDs can be used instead of names.
178 Using this flag is mostly equivalent to using the "add-domain"
180 command, with "readonly:true" if the --ro flag was given, and with
181 "format:..." if the --format=... flag was given.
182 -D
184 --no-dest-paths
185 Don't tab-complete paths on the guest filesystem. It is useful to
186 be able to hit the tab key to complete paths on the guest
187 filesystem, but this causes extra "hidden" guestfs calls to be
188 made, so this option is here to allow this feature to be disabled.
189 --echo-keys
191 When prompting for keys and passphrases, guestfish normally turns
192 echoing off so you cannot see what you are typing. If you are not
193 worried about Tempest attacks and there is no one else in the room
194 you can specify this flag to see what you are typing.
195 -f file
197 --file file
198 Read commands from "file". To write pure guestfish scripts, use:
199 #!/usr/bin/guestfish -f
201 --format=raw|qcow2|..
203 --format
204 The default for the -a option is to auto-detect the format of the
205 disk image. Using this forces the disk format for -a options which
206 follow on the command line. Using --format with no argument
207 switches back to auto-detection for subsequent -a options.
208 For example:
210 guestfish --format=raw -a disk.img
212 forces raw format (no auto-detection) for "disk.img".
214 guestfish --format=raw -a disk.img --format -a another.img
216 forces raw format (no auto-detection) for "disk.img" and reverts to
218 auto-detection for "another.img".
219 If you have untrusted raw-format guest disk images, you should use
221 this option to specify the disk format. This avoids a possible
222 security problem with malicious guests (CVE-2010-3851). See also
223 "add".
224 -i
226 --inspector
227 Using virt-inspector(1) code, inspect the disks looking for an
228 operating system and mount filesystems as they would be mounted on
229 the real virtual machine.
230 Typical usage is either:
232 guestfish -d myguest -i
234 (for an inactive libvirt domain called myguest), or:
236 guestfish --ro -d myguest -i
238 (for active domains, readonly), or specify the block device
240 directly:
241 guestfish --rw -a /dev/Guests/MyGuest -i
243 Note that the command line syntax changed slightly over older
245 versions of guestfish. You can still use the old syntax:
246 guestfish [--ro] -i disk.img
248 guestfish [--ro] -i libvirt-domain
250 Using this flag is mostly equivalent to using the "inspect-os"
252 command and then using other commands to mount the filesystems that
253 were found.
254 --keys-from-stdin
256 Read key or passphrase parameters from stdin. The default is to
257 try to read passphrases from the user by opening "/dev/tty".
258 --listen
260 Fork into the background and listen for remote commands. See
261 section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
262 --live
264 Connect to a live virtual machine. (Experimental, see "ATTACHING
265 TO RUNNING DAEMONS" in guestfs(3)).
266 -m dev[:mountpoint[:options[:fstype]]]
268 --mount dev[:mountpoint[:options[:fstype]]]
269 Mount the named partition or logical volume on the given
270 mountpoint.
271 If the mountpoint is omitted, it defaults to "/".
273 You have to mount something on "/" before most commands will work.
275 If any -m or --mount options are given, the guest is automatically
277 launched.
278 If you don't know what filesystems a disk image contains, you can
280 either run guestfish without this option, then list the partitions,
281 filesystems and LVs available (see "list-partitions", "list-
282 filesystems" and "lvs" commands), or you can use the
283 virt-filesystems(1) program.
284 The third (and rarely used) part of the mount parameter is the list
286 of mount options used to mount the underlying filesystem. If this
287 is not given, then the mount options are either the empty string or
288 "ro" (the latter if the --ro flag is used). By specifying the
289 mount options, you override this default choice. Probably the only
290 time you would use this is to enable ACLs and/or extended
291 attributes if the filesystem can support them:
292 -m /dev/sda1:/:acl,user_xattr
294 Using this flag is equivalent to using the "mount-options" command.
296 The fourth part of the parameter is the filesystem driver to use,
298 such as "ext3" or "ntfs". This is rarely needed, but can be useful
299 if multiple drivers are valid for a filesystem (eg: "ext2" and
300 "ext3"), or if libguestfs misidentifies a filesystem.
301 --network
303 Enable QEMU user networking in the guest.
304 -N type
306 --new type
307 -N help
308 Prepare a fresh disk image formatted as "type". This is an
309 alternative to the -a option: whereas -a adds an existing disk, -N
310 creates a preformatted disk with a filesystem and adds it. See
311 "PREPARED DISK IMAGES" below.
312 -n
314 --no-sync
315 Disable autosync. This is enabled by default. See the discussion
316 of autosync in the guestfs(3) manpage.
317 --pipe-error
319 If writes fail to pipe commands (see "PIPES" below), then the
320 command returns an error.
321 The default (also for historical reasons) is to ignore such errors
323 so that:
324 ><fs> command_with_lots_of_output | head
326 doesn't give an error.
328 --progress-bars
330 Enable progress bars, even when guestfish is used non-
331 interactively.
332 Progress bars are enabled by default when guestfish is used as an
334 interactive shell.
335 --no-progress-bars
337 Disable progress bars.
338 --remote[=pid]
340 Send remote commands to $GUESTFISH_PID or "pid". See section
341 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
342 -r
344 --ro
345 This changes the -a, -d and -m options so that disks are added and
346 mounts are done read-only.
347 The option must always be used if the disk image or virtual machine
349 might be running, and is generally recommended in cases where you
350 don't need write access to the disk.
351 Note that prepared disk images created with -N are not affected by
353 this option. Also commands like "add" are not affected - you have
354 to specify the "readonly:true" option explicitly if you need it.
355 See also "OPENING DISKS FOR READ AND WRITE" below.
357 --selinux
359 Enable SELinux support for the guest. See "SELINUX" in guestfs(3).
360 -v
362 --verbose
363 Enable very verbose messages. This is particularly useful if you
364 find a bug.
365 -V
367 --version
368 Display the guestfish / libguestfs version number and exit.
369 -w
371 --rw
372 This changes the -a, -d and -m options so that disks are added and
373 mounts are done read-write.
374 See "OPENING DISKS FOR READ AND WRITE" below.
376 -x Echo each command before executing it.
378
380 Any additional (non-option) arguments are treated as commands to
381 execute.
382 Commands to execute should be separated by a colon (":"), where the
384 colon is a separate parameter. Thus:
385 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
387 If there are no additional arguments, then we enter a shell, either an
389 interactive shell with a prompt (if the input is a terminal) or a non-
390 interactive shell.
391 In either command line mode or non-interactive shell, the first command
393 that gives an error causes the whole shell to exit. In interactive
394 mode (with a prompt) if a command fails, you can continue to enter
395 commands.
396
398 As with guestfs(3), you must first configure your guest by adding
399 disks, then launch it, then mount any disks you need, and finally issue
400 actions/commands. So the general order of the day is:
401 · add or -a/--add
403 · launch (aka run)
405 · mount or -m/--mount
407 · any other commands
409 "run" is a synonym for "launch". You must "launch" (or "run") your
411 guest before mounting or performing any other commands.
412 The only exception is that if any of the -i, -m, --mount, -N or --new
414 options were given then "run" is done automatically, simply because
415 guestfish can't perform the action you asked for without doing this.
416
418 The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
419 affect whether the other command line options -a, -c, -d, -i and -m
420 open disk images read-only or for writing.
421 In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
423 to opening disk images supplied on the command line for write. To open
424 a disk image read-only you have to do -a image --ro.
425 This matters: If you accidentally open a live VM disk image writable
427 then you will cause irreversible disk corruption.
428 In a future libguestfs we intend to change the default the other way.
430 Disk images will be opened read-only. You will have to either specify
431 guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
432 configuration file "/etc/libguestfs-tools.conf" in order to get write
433 access for disk images specified by those other command line options.
434 This version of guestfish, guestmount and virt-rescue has a --rw option
436 which does nothing (it is already the default). However it is highly
437 recommended that you use this option to indicate that you need write
438 access, and prepare your scripts for the day when this option will be
439 required for write access.
440 Note: This does not affect commands like "add" and "mount", or any
442 other libguestfs program apart from guestfish and guestmount.
443
445 You can quote ordinary parameters using either single or double quotes.
446 For example:
447 add "file with a space.img"
449 rm '/file name'
451 rm '/"'
453 A few commands require a list of strings to be passed. For these, use
455 a whitespace-separated list, enclosed in quotes. Strings containing
456 whitespace to be passed through must be enclosed in single quotes. A
457 literal single quote must be escaped with a backslash.
458 vgcreate VG "/dev/sda1 /dev/sdb1"
460 command "/bin/echo 'foo bar'"
461 command "/bin/echo \'foo\'"
462 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
464 In double-quoted arguments (only) use backslash to insert special
465 characters:
466 "\a"
468 Alert (bell) character.
469 "\b"
471 Backspace character.
472 "\f"
474 Form feed character.
475 "\n"
477 Newline character.
478 "\r"
480 Carriage return character.
481 "\t"
483 Horizontal tab character.
484 "\v"
486 Vertical tab character.
487 "\""
489 A literal double quote character.
490 "\ooo"
492 A character with octal value ooo. There must be precisely 3 octal
493 digits (unlike C).
494 "\xhh"
496 A character with hex value hh. There must be precisely 2 hex
497 digits.
498 In the current implementation "\000" and "\x00" cannot be used in
500 strings.
501 "\\"
503 A literal backslash character.
504
506 Some commands take optional arguments. These arguments appear in this
507 documentation as "[argname:..]". You can use them as in these
508 examples:
509 add filename
511 add filename readonly:true
513 add filename format:qcow2 readonly:false
515 Each optional argument can appear at most once. All optional arguments
517 must appear after the required ones.
518
520 This section applies to all commands which can take integers as
521 parameters.
522 SIZE SUFFIX
524 When the command takes a parameter measured in bytes, you can use one
525 of the following suffixes to specify kilobytes, megabytes and larger
526 sizes:
527 k or K or KiB
529 The size in kilobytes (multiplied by 1024).
530 KB The size in SI 1000 byte units.
532 M or MiB
534 The size in megabytes (multiplied by 1048576).
535 MB The size in SI 1000000 byte units.
537 G or GiB
539 The size in gigabytes (multiplied by 2**30).
540 GB The size in SI 10**9 byte units.
542 T or TiB
544 The size in terabytes (multiplied by 2**40).
545 TB The size in SI 10**12 byte units.
547 P or PiB
549 The size in petabytes (multiplied by 2**50).
550 PB The size in SI 10**15 byte units.
552 E or EiB
554 The size in exabytes (multiplied by 2**60).
555 EB The size in SI 10**18 byte units.
557 Z or ZiB
559 The size in zettabytes (multiplied by 2**70).
560 ZB The size in SI 10**21 byte units.
562 Y or YiB
564 The size in yottabytes (multiplied by 2**80).
565 YB The size in SI 10**24 byte units.
567 For example:
569 truncate-size /file 1G
571 would truncate the file to 1 gigabyte.
573 Be careful because a few commands take sizes in kilobytes or megabytes
575 (eg. the parameter to "memsize" is specified in megabytes already).
576 Adding a suffix will probably not do what you expect.
577 OCTAL AND HEXADECIMAL NUMBERS
579 For specifying the radix (base) use the C convention: 0 to prefix an
580 octal number or "0x" to prefix a hexadecimal number. For example:
581 1234 decimal number 1234
583 02322 octal number, equivalent to decimal 1234
584 0x4d2 hexadecimal number, equivalent to decimal 1234
585 When using the "chmod" command, you almost always want to specify an
587 octal number for the mode, and you must prefix it with 0 (unlike the
588 Unix chmod(1) program):
589 chmod 0777 /public # OK
591 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
592 Commands that return numbers usually print them in decimal, but some
594 commands print numbers in other radices (eg. "umask" prints the mode in
595 octal, preceded by 0).
596
598 Neither guestfish nor the underlying guestfs API performs wildcard
599 expansion (globbing) by default. So for example the following will not
600 do what you expect:
601 rm-rf /home/*
603 Assuming you don't have a directory called literally "/home/*" then the
605 above command will return an error.
606 To perform wildcard expansion, use the "glob" command.
608 glob rm-rf /home/*
610 runs "rm-rf" on each path that matches (ie. potentially running the
612 command many times), equivalent to:
613 rm-rf /home/jim
615 rm-rf /home/joe
616 rm-rf /home/mary
617 "glob" only works on simple guest paths and not on device names.
619 If you have several parameters, each containing a wildcard, then glob
621 will perform a Cartesian product.
622
624 Any line which starts with a # character is treated as a comment and
625 ignored. The # can optionally be preceded by whitespace, but not by a
626 command. For example:
627 # this is a comment
629 # this is a comment
630 foo # NOT a comment
631 Blank lines are also ignored.
633
635 Any line which starts with a ! character is treated as a command sent
636 to the local shell ("/bin/sh" or whatever system(3) uses). For
637 example:
638 !mkdir local
640 tgz-out /remote local/remote-data.tar.gz
641 will create a directory "local" on the host, and then export the
643 contents of "/remote" on the mounted filesystem to
644 "local/remote-data.tar.gz". (See "tgz-out").
645 To change the local directory, use the "lcd" command. "!cd" will have
647 no effect, due to the way that subprocesses work in Unix.
648 LOCAL COMMANDS WITH INLINE EXECUTION
650 If a line starts with <! then the shell command is executed (as for !),
651 but subsequently any output (stdout) of the shell command is parsed and
652 executed as guestfish commands.
653 Thus you can use shell script to construct arbitrary guestfish commands
655 which are then parsed by guestfish.
656 For example it is tedious to create a sequence of files (eg. "/foo.1"
658 through "/foo.100") using guestfish commands alone. However this is
659 simple if we use a shell script to create the guestfish commands for
660 us:
661 <! for n in `seq 1 100`; do echo write /foo.$n $n; done
663 or with names like "/foo.001":
665 <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
667 When using guestfish interactively it can be helpful to just run the
669 shell script first (ie. remove the initial "<" character so it is just
670 an ordinary ! local command), see what guestfish commands it would run,
671 and when you are happy with those prepend the "<" character to run the
672 guestfish commands for real.
673
675 Use "command <space> | command" to pipe the output of the first command
676 (a guestfish command) to the second command (any host command). For
677 example:
678 cat /etc/passwd | awk -F: '$3 == 0 { print }'
680 (where "cat" is the guestfish cat command, but "awk" is the host awk
682 program). The above command would list all accounts in the guest
683 filesystem which have UID 0, ie. root accounts including backdoors.
684 Other examples:
685 hexdump /bin/ls | head
687 list-devices | tail -1
688 tgz-out / - | tar ztf -
689 The space before the pipe symbol is required, any space after the pipe
691 symbol is optional. Everything after the pipe symbol is just passed
692 straight to the host shell, so it can contain redirections, globs and
693 anything else that makes sense on the host side.
694 To use a literal argument which begins with a pipe symbol, you have to
696 quote it, eg:
697 echo "|"
699
701 If a parameter starts with the character "~" then the tilde may be
702 expanded as a home directory path (either "~" for the current user's
703 home directory, or "~user" for another user).
704 Note that home directory expansion happens for users known on the host,
706 not in the guest filesystem.
707 To use a literal argument which begins with a tilde, you have to quote
709 it, eg:
710 echo "~"
712
714 Libguestfs has some support for Linux guests encrypted according to the
715 Linux Unified Key Setup (LUKS) standard, which includes nearly all
716 whole disk encryption systems used by modern Linux guests. Currently
717 only LVM-on-LUKS is supported.
718 Identify encrypted block devices and partitions using "vfs-type":
720 ><fs> vfs-type /dev/sda2
722 crypto_LUKS
723 Then open those devices using "luks-open". This creates a device-
725 mapper device called "/dev/mapper/luksdev".
726 ><fs> luks-open /dev/sda2 luksdev
728 Enter key or passphrase ("key"): <enter the passphrase>
729 Finally you have to tell LVM to scan for volume groups on the newly
731 created mapper device:
732 vgscan
734 vg-activate-all true
735 The logical volume(s) can now be mounted in the usual way.
737 Before closing a LUKS device you must unmount any logical volumes on it
739 and deactivate the volume groups by calling "vg-activate false VG" on
740 each one. Then you can close the mapper device:
741 vg-activate false /dev/VG
743 luks-close /dev/mapper/luksdev
744
746 If a path is prefixed with "win:" then you can use Windows-style drive
747 letters and paths (with some limitations). The following commands are
748 equivalent:
749 file /WINDOWS/system32/config/system.LOG
751 file win:\windows\system32\config\system.log
753 file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
755 The parameter is rewritten "behind the scenes" by looking up the
757 position where the drive is mounted, prepending that to the path,
758 changing all backslash characters to forward slash, then resolving the
759 result using "case-sensitive-path". For example if the E: drive was
760 mounted on "/e" then the parameter might be rewritten like this:
761 win:e:\foo\bar => /e/FOO/bar
763 This only works in argument positions that expect a path.
765
767 For commands such as "upload", "download", "tar-in", "tar-out" and
768 others which upload from or download to a local file, you can use the
769 special filename "-" to mean "from stdin" or "to stdout". For example:
770 upload - /foo
772 reads stdin and creates from that a file "/foo" in the disk image, and:
774 tar-out /etc - | tar tf -
776 writes the tarball to stdout and then pipes that into the external
778 "tar" command (see "PIPES").
779 When using "-" to read from stdin, the input is read up to the end of
781 stdin. You can also use a special "heredoc"-like syntax to read up to
782 some arbitrary end marker:
783 upload -<<END /foo
785 input line 1
786 input line 2
787 input line 3
788 END
789 Any string of characters can be used instead of "END". The end marker
791 must appear on a line of its own, without any preceding or following
792 characters (not even spaces).
793 Note that the "-<<" syntax only applies to parameters used to upload
795 local files (so-called "FileIn" parameters in the generator).
796
798 By default, guestfish will ignore any errors when in interactive mode
799 (ie. taking commands from a human over a tty), and will exit on the
800 first error in non-interactive mode (scripts, commands given on the
801 command line).
802 If you prefix a command with a - character, then that command will not
804 cause guestfish to exit, even if that (one) command returns an error.
805
807 Guestfish can be remote-controlled over a socket. This is useful
808 particularly in shell scripts where you want to make several different
809 changes to a filesystem, but you don't want the overhead of starting up
810 a guestfish process each time.
811 Start a guestfish server process using:
813 eval "`guestfish --listen`"
815 and then send it commands by doing:
817 guestfish --remote cmd [...]
819 To cause the server to exit, send it the exit command:
821 guestfish --remote exit
823 Note that the server will normally exit if there is an error in a
825 command. You can change this in the usual way. See section "EXIT ON
826 ERROR BEHAVIOUR".
827 CONTROLLING MULTIPLE GUESTFISH PROCESSES
829 The "eval" statement sets the environment variable $GUESTFISH_PID,
830 which is how the --remote option knows where to send the commands. You
831 can have several guestfish listener processes running using:
832 eval "`guestfish --listen`"
834 pid1=$GUESTFISH_PID
835 eval "`guestfish --listen`"
836 pid2=$GUESTFISH_PID
837 ...
838 guestfish --remote=$pid1 cmd
839 guestfish --remote=$pid2 cmd
840 REMOTE CONTROL AND CSH
842 When using csh-like shells (csh, tcsh etc) you have to add the --csh
843 option:
844 eval "`guestfish --listen --csh`"
846 REMOTE CONTROL DETAILS
848 Remote control happens over a Unix domain socket called
849 "/tmp/.guestfish-$UID/socket-$PID", where $UID is the effective user ID
850 of the process, and $PID is the process ID of the server.
851 Guestfish client and server versions must match exactly.
853 Older versions of guestfish were vulnerable to CVE-2013-4419 (see
855 "CVE-2013-4419" in guestfs(3)). This is fixed in the current version.
856 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
858 From Bash, you can use the following code which creates a guestfish
859 instance, correctly quotes the command line, handles failure to start,
860 and cleans up guestfish when the script exits:
861 #!/bin/bash -
863 set -e
865 guestfish[0]="guestfish"
867 guestfish[1]="--listen"
868 guestfish[2]="--ro"
869 guestfish[3]="-a"
870 guestfish[4]="disk.img"
871 GUESTFISH_PID=
873 eval $("${guestfish[@]}")
874 if [ -z "$GUESTFISH_PID" ]; then
875 echo "error: guestfish didn't start up, see error messages above"
876 exit 1
877 fi
878 cleanup_guestfish ()
880 {
881 guestfish --remote -- exit >/dev/null 2>&1 ||:
882 }
883 trap cleanup_guestfish EXIT ERR
884 guestfish --remote -- run
886 # ...
888 REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
890 Options such as -a, --add, -N, --new etc don't interact properly with
891 remote support. They are processed locally, and not sent through to
892 the remote guestfish. In particular this won't do what you expect:
893 guestfish --remote --add disk.img
895 Don't use these options. Use the equivalent commands instead, eg:
897 guestfish --remote add-drive disk.img
899 or:
901 guestfish --remote
903 ><fs> add disk.img
904 REMOTE CONTROL RUN COMMAND HANGING
906 Using the "run" (or "launch") command remotely in a command
907 substitution context hangs, ie. don't do (note the backquotes):
908 a=`guestfish --remote run`
910 Since the "run" command produces no output on stdout, this is not
912 useful anyway. For further information see
913 https://bugzilla.redhat.com/show_bug.cgi?id=592910.
914
916 Use the -N type or --new type parameter to select one of a set of
917 preformatted disk images that guestfish can make for you to save
918 typing. This is particularly useful for testing purposes. This option
919 is used instead of the -a option, and like -a can appear multiple times
920 (and can be mixed with -a).
921 The new disk is called "test1.img" for the first -N, "test2.img" for
923 the second and so on. Existing files in the current directory are
924 overwritten.
925 The type briefly describes how the disk should be sized, partitioned,
927 how filesystem(s) should be created, and how content should be added.
928 Optionally the type can be followed by extra parameters, separated by
929 ":" (colon) characters. For example, -N fs creates a default 100MB,
930 sparsely-allocated disk, containing a single partition, with the
931 partition formatted as ext2. -N fs:ext4:1G is the same, but for an
932 ext4 filesystem on a 1GB disk instead.
933 To list the available types and any extra parameters they take, run:
935 guestfish -N help | less
937 Note that the prepared filesystem is not mounted. You would usually
939 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
940 option.
941 If any -N or --new options are given, the libguestfs appliance is
943 automatically launched.
944 EXAMPLES
946 Create a 100MB disk with an ext4-formatted partition:
947 guestfish -N fs:ext4
949 Create a 32MB disk with a VFAT-formatted partition, and mount it:
951 guestfish -N fs:vfat:32M -m /dev/sda1
953 Create a blank 200MB disk:
955 guestfish -N disk:200M
957
959 Some (not all) long-running commands send progress notification
960 messages as they are running. Guestfish turns these messages into
961 progress bars.
962 When a command that supports progress bars takes longer than two
964 seconds to run, and if progress bars are enabled, then you will see one
965 appearing below the command:
966 ><fs> copy-size /large-file /another-file 2048M
968 / 10% [#####-----------------------------------------] 00:30
969 The spinner on the left hand side moves round once for every progress
971 notification received from the backend. This is a (reasonably) golden
972 assurance that the command is "doing something" even if the progress
973 bar is not moving, because the command is able to send the progress
974 notifications. When the bar reaches 100% and the command finishes, the
975 spinner disappears.
976 Progress bars are enabled by default when guestfish is used
978 interactively. You can enable them even for non-interactive modes
979 using --progress-bars, and you can disable them completely using
980 --no-progress-bars.
981
983 You can change or add colours to the default prompt ("><fs>") by
984 setting the "GUESTFISH_PS1" environment variable. A simple prompt can
985 be set by setting this to an alternate string:
986 $ GUESTFISH_PS1='(type a command) '
988 $ export GUESTFISH_PS1
989 $ guestfish
990 [...]
991 (type a command) ▂
992 You can also use special escape sequences, as described in the table
994 below:
995 \\ A literal backslash character.
997 \[
999 \] Place non-printing characters (eg. terminal control codes for
1000 colours) between "\[...\]". What this does it to tell the
1001 readline(3) library that it should treat this subsequence as zero-
1002 width, so that command-line redisplay, editing etc works.
1003 \a A bell character.
1005 \e An ASCII ESC (escape) character.
1007 \n A newline.
1009 \r A carriage return.
1011 \NNN
1013 The ASCII character whose code is the octal value NNN.
1014 \xNN
1016 The ASCII character whose code is the hex value NN.
1017 EXAMPLES OF PROMPTS
1019 Note these these require a terminal that supports ANSI escape codes.
1020 GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1022 A bold black version of the ordinary prompt.
1024
1026 Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1027 partitions. See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1028 guestfs(3).
1029
1031 The commands in this section are guestfish convenience commands, in
1032 other words, they are not part of the guestfs(3) API.
1033 help
1035 help
1036 help cmd
1037 Without any parameter, this provides general help.
1039 With a "cmd" parameter, this displays detailed help for that command.
1041 exit
1043 quit
1044 This exits guestfish. You can also use "^D" key.
1045 alloc
1047 allocate
1048 alloc filename size
1049 This creates an empty (zeroed) file of the given size, and then adds so
1051 it can be further examined.
1052 For more advanced image creation, see qemu-img(1) utility.
1054 Size can be specified using standard suffixes, eg. "1M".
1056 To create a sparse file, use "sparse" instead. To create a prepared
1058 disk image, see "PREPARED DISK IMAGES".
1059 copy-in
1061 copy-in local [local ...] /remotedir
1062 "copy-in" copies local files or directories recursively into the disk
1064 image, placing them in the directory called "/remotedir" (which must
1065 exist). This guestfish meta-command turns into a sequence of "tar-in"
1066 and other commands as necessary.
1067 Multiple local files and directories can be specified, but the last
1069 parameter must always be a remote directory. Wildcards cannot be used.
1070 copy-out
1072 copy-out remote [remote ...] localdir
1073 "copy-out" copies remote files or directories recursively out of the
1075 disk image, placing them on the host disk in a local directory called
1076 "localdir" (which must exist). This guestfish meta-command turns into
1077 a sequence of "download", "tar-out" and other commands as necessary.
1078 Multiple remote files and directories can be specified, but the last
1080 parameter must always be a local directory. To download to the current
1081 directory, use "." as in:
1082 copy-out /home .
1084 Wildcards cannot be used in the ordinary command, but you can use them
1086 with the help of "glob" like this:
1087 glob copy-out /home/* .
1089 delete-event
1091 delete-event name
1092 Delete the event handler which was previously registered as "name". If
1094 multiple event handlers were registered with the same name, they are
1095 all deleted.
1096 See also the guestfish commands "event" and "list-events".
1098 display
1100 display filename
1101 Use "display" (a graphical display program) to display an image file.
1103 It downloads the file, and runs "display" on it.
1104 To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1106 environment variable. For example to use the GNOME display program:
1107 export GUESTFISH_DISPLAY_IMAGE=eog
1109 See also display(1).
1111 echo
1113 echo [params ...]
1114 This echos the parameters to the terminal.
1116 edit
1118 vi
1119 emacs
1120 edit filename
1121 This is used to edit a file. It downloads the file, edits it locally
1123 using your editor, then uploads the result.
1124 The editor is $EDITOR. However if you use the alternate commands "vi"
1126 or "emacs" you will get those corresponding editors.
1127 event
1129 event name eventset "shell script ..."
1130 Register a shell script fragment which is executed when an event is
1132 raised. See "guestfs_set_event_callback" in guestfs(3) for a
1133 discussion of the event API in libguestfs.
1134 The "name" parameter is a name that you give to this event handler. It
1136 can be any string (even the empty string) and is simply there so you
1137 can delete the handler using the guestfish "delete-event" command.
1138 The "eventset" parameter is a comma-separated list of one or more
1140 events, for example "close" or "close,trace". The special value "*"
1141 means all events.
1142 The third and final parameter is the shell script fragment (or any
1144 external command) that is executed when any of the events in the
1145 eventset occurs. It is executed using "$SHELL -c", or if $SHELL is not
1146 set then "/bin/sh -c".
1147 The shell script fragment receives callback parameters as arguments $1,
1149 $2 etc. The actual event that was called is available in the
1150 environment variable $EVENT.
1151 event "" close "echo closed"
1153 event messages appliance,library,trace "echo $@"
1154 event "" progress "echo progress: $3/$4"
1155 event "" * "echo $EVENT $@"
1156 See also the guestfish commands "delete-event" and "list-events".
1158 glob
1160 glob command args...
1161 Expand wildcards in any paths in the args list, and run "command"
1163 repeatedly on each matching path.
1164 See "WILDCARDS AND GLOBBING".
1166 hexedit
1168 hexedit <filename|device>
1169 hexedit <filename|device> <max>
1170 hexedit <filename|device> <start> <max>
1171 Use a hex editor to edit all or part of a binary file or block device.
1173 This command works by downloading potentially the whole file or device,
1175 editing it locally, then uploading it. If the file or device is large,
1176 you have to specify which part you wish to edit by using "max" and/or
1177 "start" "max" parameters. "start" and "max" are specified in bytes,
1178 with the usual modifiers allowed such as "1M" (1 megabyte).
1179 For example to edit the first few sectors of a disk you might do:
1181 hexedit /dev/sda 1M
1183 which would allow you to edit anywhere within the first megabyte of the
1185 disk.
1186 To edit the superblock of an ext2 filesystem on "/dev/sda1", do:
1188 hexedit /dev/sda1 0x400 0x400
1190 (assuming the superblock is in the standard location).
1192 This command requires an external hexeditor program. You can specify
1194 the program to use by setting the "HEXEDITOR" environment variable. If
1195 "HEXEDITOR" is not set then this prints an error.
1196 See also "hexdump".
1198 lcd
1200 lcd directory
1201 Change the local directory, ie. the current directory of guestfish
1203 itself.
1204 Note that "!cd" won't do what you might expect.
1206 list-events
1208 list-events
1209 List the event handlers registered using the guestfish "event" command.
1211 man
1213 manual
1214 man
1215 Opens the manual page for guestfish.
1217 more
1219 less
1220 more filename
1221 less filename
1223 This is used to view a file.
1225 The default viewer is $PAGER. However if you use the alternate command
1227 "less" you will get the "less" command specifically.
1228 reopen
1230 reopen
1231 Close and reopen the libguestfs handle. It is not necessary to use
1233 this normally, because the handle is closed properly when guestfish
1234 exits. However this is occasionally useful for testing.
1235 setenv
1237 setenv VAR value
1238 Set the environment variable "VAR" to the string "value".
1240 To print the value of an environment variable use a shell command such
1242 as:
1243 !echo $VAR
1245 sparse
1247 sparse filename size
1248 This creates an empty sparse file of the given size, and then adds so
1250 it can be further examined.
1251 In all respects it works the same as the "alloc" command, except that
1253 the image file is allocated sparsely, which means that disk blocks are
1254 not assigned to the file until they are needed. Sparse disk files only
1255 use space when written to, but they are slower and there is a danger
1256 you could run out of real disk space during a write operation.
1257 For more advanced image creation, see qemu-img(1) utility.
1259 Size can be specified using standard suffixes, eg. "1M".
1261 supported
1263 supported
1264 This command returns a list of the optional groups known to the daemon,
1266 and indicates which ones are supported by this build of the libguestfs
1267 appliance.
1268 See also "AVAILABILITY" in guestfs(3).
1270 time
1272 time command args...
1273 Run the command as usual, but print the elapsed time afterwards. This
1275 can be useful for benchmarking operations.
1276 unsetenv
1278 unsetenv VAR
1279 Remove "VAR" from the environment.
1281
1283 acl-delete-def-file
1284 acl-delete-def-file dir
1285 This function deletes the default POSIX Access Control List (ACL)
1287 attached to directory "dir".
1288 acl-get-file
1290 acl-get-file path acltype
1291 This function returns the POSIX Access Control List (ACL) attached to
1293 "path". The ACL is returned in "long text form" (see acl(5)).
1294 The "acltype" parameter may be:
1296 "access"
1298 Return the ordinary (access) ACL for any file, directory or other
1299 filesystem object.
1300 "default"
1302 Return the default ACL. Normally this only makes sense if "path"
1303 is a directory.
1304 acl-set-file
1306 acl-set-file path acltype acl
1307 This function sets the POSIX Access Control List (ACL) attached to
1309 "path".
1310 The "acltype" parameter may be:
1312 "access"
1314 Set the ordinary (access) ACL for any file, directory or other
1315 filesystem object.
1316 "default"
1318 Set the default ACL. Normally this only makes sense if "path" is a
1319 directory.
1320 The "acl" parameter is the new ACL in either "long text form" or "short
1322 text form" (see acl(5)). The new ACL completely replaces any previous
1323 ACL on the file. The ACL must contain the full Unix permissions (eg.
1324 "u::rwx,g::rx,o::rx").
1325 If you are specifying individual users or groups, then the mask field
1327 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1328 "g:ID:..." field(s). A full ACL string might therefore look like this:
1329 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1331 \ Unix permissions / \mask/ \ ACL /
1332 You should use numeric UIDs and GIDs. To map usernames and groupnames
1334 to the correct numeric ID in the context of the guest, use the Augeas
1335 functions (see "aug-init").
1336 add-cdrom
1338 add-cdrom filename
1339 This function adds a virtual CD-ROM disk image to the guest.
1341 Do not use this function! ISO files are just ordinary read-only disk
1343 images. Use "add-drive-ro" instead.
1344 This function is deprecated. In new code, use the "add-drive" call
1346 instead.
1347 Deprecated functions will not be removed from the API, but the fact
1349 that they are deprecated indicates that there are problems with correct
1350 use of these functions.
1351 add-domain
1353 domain
1354 add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..]
1355 This function adds the disk(s) attached to the named libvirt domain
1357 "dom". It works by connecting to libvirt, requesting the domain and
1358 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1359 opts" on each one.
1360 The number of disks added is returned. This operation is atomic: if an
1362 error is returned, then no disks are added.
1363 This function does some minimal checks to make sure the libvirt domain
1365 is not running (unless "readonly" is true). In a future version we
1366 will try to acquire the libvirt lock on each disk.
1367 Disks must be accessible locally. This often means that adding disks
1369 from a remote libvirt connection (see http://libvirt.org/remote.html)
1370 will fail unless those disks are accessible via the same device path
1371 locally too.
1372 The optional "libvirturi" parameter sets the libvirt URI (see
1374 http://libvirt.org/uri.html). If this is not set then we connect to
1375 the default libvirt URI (or one set through an environment variable,
1376 see the libvirt documentation for full details).
1377 The optional "live" flag controls whether this call will try to connect
1379 to a running virtual machine "guestfsd" process if it sees a suitable
1380 <channel> element in the libvirt XML definition. The default (if the
1381 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1382 in guestfs(3) for more information.
1383 If the "allowuuid" flag is true (default is false) then a UUID may be
1385 passed instead of the domain name. The "dom" string is treated as a
1386 UUID first and looked up, and if that lookup fails then we treat "dom"
1387 as a name as usual.
1388 The optional "readonlydisk" parameter controls what we do for disks
1390 which are marked <readonly/> in the libvirt XML. Possible values are:
1391 readonlydisk = "error"
1393 If "readonly" is false:
1394 The whole call is aborted with an error if any disk with the
1396 <readonly/> flag is found.
1397 If "readonly" is true:
1399 Disks with the <readonly/> flag are added read-only.
1401 readonlydisk = "read"
1403 If "readonly" is false:
1404 Disks with the <readonly/> flag are added read-only. Other disks
1406 are added read/write.
1407 If "readonly" is true:
1409 Disks with the <readonly/> flag are added read-only.
1411 readonlydisk = "write" (default)
1413 If "readonly" is false:
1414 Disks with the <readonly/> flag are added read/write.
1416 If "readonly" is true:
1418 Disks with the <readonly/> flag are added read-only.
1420 readonlydisk = "ignore"
1422 If "readonly" is true or false:
1423 Disks with the <readonly/> flag are skipped.
1425 The other optional parameters are passed directly through to "add-
1427 drive-opts".
1428 This command has one or more optional arguments. See "OPTIONAL
1430 ARGUMENTS".
1431 add-drive
1433 add
1434 add-drive-opts
1435 add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [cachemode:..]
1436 This function adds a disk image called "filename" to the handle.
1438 "filename" may be a regular host file or a host device.
1439 When this function is called before "launch" (the usual case) then the
1441 first time you call this function, the disk appears in the API as
1442 "/dev/sda", the second time as "/dev/sdb", and so on.
1443 In libguestfs ≥ 1.20 you can also call this function after launch (with
1445 some restrictions). This is called "hotplugging". When hotplugging,
1446 you must specify a "label" so that the new disk gets a predictable
1447 name. For more information see "HOTPLUGGING" in guestfs(3).
1448 You don't necessarily need to be root when using libguestfs. However
1450 you obviously do need sufficient permissions to access the filename for
1451 whatever operations you want to perform (ie. read access if you just
1452 want to read the image or write access if you want to modify the
1453 image).
1454 This call checks that "filename" exists.
1456 "filename" may be the special string "/dev/null". See "NULL DISKS" in
1458 guestfs(3).
1459 The optional arguments are:
1461 "readonly"
1463 If true then the image is treated as read-only. Writes are still
1464 allowed, but they are stored in a temporary snapshot overlay which
1465 is discarded at the end. The disk that you add is not modified.
1466 "format"
1468 This forces the image format. If you omit this (or use "add-drive"
1469 or "add-drive-ro") then the format is automatically detected.
1470 Possible formats include "raw" and "qcow2".
1471 Automatic detection of the format opens you up to a potential
1473 security hole when dealing with untrusted raw-format images. See
1474 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1475 security hole.
1476 "iface"
1478 This rarely-used option lets you emulate the behaviour of the
1479 deprecated "add-drive-with-if" call (q.v.)
1480 "name"
1482 The name the drive had in the original guest, e.g. "/dev/sdb".
1483 This is used as a hint to the guest inspection process if it is
1484 available.
1485 "label"
1487 Give the disk a label. The label should be a unique, short string
1488 using only ASCII characters "[a-zA-Z]". As well as its usual name
1489 in the API (such as "/dev/sda"), the drive will also be named
1490 "/dev/disk/guestfs/label".
1491 See "DISK LABELS" in guestfs(3).
1493 "cachemode"
1495 Choose whether or not libguestfs will obey sync operations (safe
1496 but slow) or not (unsafe but fast). The possible values for this
1497 string are:
1498 "cachemode = "writeback""
1500 This is the default.
1501 Write operations in the API do not return until a write(2) call
1503 has completed in the host [but note this does not imply that
1504 anything gets written to disk].
1505 Sync operations in the API, including implicit syncs caused by
1507 filesystem journalling, will not return until an fdatasync(2)
1508 call has completed in the host, indicating that data has been
1509 committed to disk.
1510 "cachemode = "unsafe""
1512 In this mode, there are no guarantees. Libguestfs may cache
1513 anything and ignore sync requests. This is suitable only for
1514 scratch or temporary disks.
1515 This command has one or more optional arguments. See "OPTIONAL
1517 ARGUMENTS".
1518 add-drive-ro
1520 add-ro
1521 add-drive-ro filename
1522 This function is the equivalent of calling "add-drive-opts" with the
1524 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1525 disk is added read-only, with the format being detected automatically.
1526 add-drive-ro-with-if
1528 add-drive-ro-with-if filename iface
1529 This is the same as "add-drive-ro" but it allows you to specify the
1531 QEMU interface emulation to use at run time.
1532 This function is deprecated. In new code, use the "add-drive" call
1534 instead.
1535 Deprecated functions will not be removed from the API, but the fact
1537 that they are deprecated indicates that there are problems with correct
1538 use of these functions.
1539 add-drive-with-if
1541 add-drive-with-if filename iface
1542 This is the same as "add-drive" but it allows you to specify the QEMU
1544 interface emulation to use at run time.
1545 This function is deprecated. In new code, use the "add-drive" call
1547 instead.
1548 Deprecated functions will not be removed from the API, but the fact
1550 that they are deprecated indicates that there are problems with correct
1551 use of these functions.
1552 aug-clear
1554 aug-clear augpath
1555 Set the value associated with "path" to "NULL". This is the same as
1557 the augtool(1) "clear" command.
1558 aug-close
1560 aug-close
1561 Close the current Augeas handle and free up any resources used by it.
1563 After calling this, you have to call "aug-init" again before you can
1564 use any other Augeas functions.
1565 aug-defnode
1567 aug-defnode name expr val
1568 Defines a variable "name" whose value is the result of evaluating
1570 "expr".
1571 If "expr" evaluates to an empty nodeset, a node is created, equivalent
1573 to calling "aug-set" "expr", "value". "name" will be the nodeset
1574 containing that single node.
1575 On success this returns a pair containing the number of nodes in the
1577 nodeset, and a boolean flag if a node was created.
1578 aug-defvar
1580 aug-defvar name expr
1581 Defines an Augeas variable "name" whose value is the result of
1583 evaluating "expr". If "expr" is NULL, then "name" is undefined.
1584 On success this returns the number of nodes in "expr", or 0 if "expr"
1586 evaluates to something which is not a nodeset.
1587 aug-get
1589 aug-get augpath
1590 Look up the value associated with "path". If "path" matches exactly
1592 one node, the "value" is returned.
1593 aug-init
1595 aug-init root flags
1596 Create a new Augeas handle for editing configuration files. If there
1598 was any previous Augeas handle associated with this guestfs session,
1599 then it is closed.
1600 You must call this before using any other "aug-*" commands.
1602 "root" is the filesystem root. "root" must not be NULL, use "/"
1604 instead.
1605 The flags are the same as the flags defined in <augeas.h>, the logical
1607 or of the following integers:
1608 "AUG_SAVE_BACKUP" = 1
1610 Keep the original file with a ".augsave" extension.
1611 "AUG_SAVE_NEWFILE" = 2
1613 Save changes into a file with extension ".augnew", and do not
1614 overwrite original. Overrides "AUG_SAVE_BACKUP".
1615 "AUG_TYPE_CHECK" = 4
1617 Typecheck lenses.
1618 This option is only useful when debugging Augeas lenses. Use of
1620 this option may require additional memory for the libguestfs
1621 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
1622 environment variable or call "set-memsize".
1623 "AUG_NO_STDINC" = 8
1625 Do not use standard load path for modules.
1626 "AUG_SAVE_NOOP" = 16
1628 Make save a no-op, just record what would have been changed.
1629 "AUG_NO_LOAD" = 32
1631 Do not load the tree in "aug-init".
1632 To close the handle, you can call "aug-close".
1634 To find out more about Augeas, see http://augeas.net/.
1636 aug-insert
1638 aug-insert augpath label true|false
1639 Create a new sibling "label" for "path", inserting it into the tree
1641 before or after "path" (depending on the boolean flag "before").
1642 "path" must match exactly one existing node in the tree, and "label"
1644 must be a label, ie. not contain "/", "*" or end with a bracketed index
1645 "[N]".
1646 aug-load
1648 aug-load
1649 Load files into the tree.
1651 See "aug_load" in the Augeas documentation for the full gory details.
1653 aug-ls
1655 aug-ls augpath
1656 This is just a shortcut for listing "aug-match" "path/*" and sorting
1658 the resulting nodes into alphabetical order.
1659 aug-match
1661 aug-match augpath
1662 Returns a list of paths which match the path expression "path". The
1664 returned paths are sufficiently qualified so that they match exactly
1665 one node in the current tree.
1666 aug-mv
1668 aug-mv src dest
1669 Move the node "src" to "dest". "src" must match exactly one node.
1671 "dest" is overwritten if it exists.
1672 aug-rm
1674 aug-rm augpath
1675 Remove "path" and all of its children.
1677 On success this returns the number of entries which were removed.
1679 aug-save
1681 aug-save
1682 This writes all pending changes to disk.
1684 The flags which were passed to "aug-init" affect exactly how files are
1686 saved.
1687 aug-set
1689 aug-set augpath val
1690 Set the value associated with "path" to "val".
1692 In the Augeas API, it is possible to clear a node by setting the value
1694 to NULL. Due to an oversight in the libguestfs API you cannot do that
1695 with this call. Instead you must use the "aug-clear" call.
1696 available
1698 available 'groups ...'
1699 This command is used to check the availability of some groups of
1701 functionality in the appliance, which not all builds of the libguestfs
1702 appliance will be able to provide.
1703 The libguestfs groups, and the functions that those groups correspond
1705 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
1706 this list at runtime by calling "available-all-groups".
1707 The argument "groups" is a list of group names, eg: "["inotify",
1709 "augeas"]" would check for the availability of the Linux inotify
1710 functions and Augeas (configuration file editing) functions.
1711 The command returns no error if all requested groups are available.
1713 It fails with an error if one or more of the requested groups is
1715 unavailable in the appliance.
1716 If an unknown group name is included in the list of groups then an
1718 error is always returned.
1719 Notes:
1721 · You must call "launch" before calling this function.
1723 The reason is because we don't know what groups are supported by
1725 the appliance/daemon until it is running and can be queried.
1726 · If a group of functions is available, this does not necessarily
1728 mean that they will work. You still have to check for errors when
1729 calling individual API functions even if they are available.
1730 · It is usually the job of distro packagers to build complete
1732 functionality into the libguestfs appliance. Upstream libguestfs,
1733 if built from source with all requirements satisfied, will support
1734 everything.
1735 · This call was added in version 1.0.80. In previous versions of
1737 libguestfs all you could do would be to speculatively execute a
1738 command to find out if the daemon implemented it. See also
1739 "version".
1740 See also "filesystem-available".
1742 available-all-groups
1744 available-all-groups
1745 This command returns a list of all optional groups that this daemon
1747 knows about. Note this returns both supported and unsupported groups.
1748 To find out which ones the daemon can actually support you have to call
1749 "available" on each member of the returned list.
1750 See also "available" and "AVAILABILITY" in guestfs(3).
1752 base64-in
1754 base64-in (base64file|-) filename
1755 This command uploads base64-encoded data from "base64file" to
1757 "filename".
1758 Use "-" instead of a filename to read/write from stdin/stdout.
1760 base64-out
1762 base64-out filename (base64file|-)
1763 This command downloads the contents of "filename", writing it out to
1765 local file "base64file" encoded as base64.
1766 Use "-" instead of a filename to read/write from stdin/stdout.
1768 blkid
1770 blkid device
1771 This command returns block device attributes for "device". The
1773 following fields are usually present in the returned hash. Other fields
1774 may also be present.
1775 "UUID"
1777 The uuid of this device.
1778 "LABEL"
1780 The label of this device.
1781 "VERSION"
1783 The version of blkid command.
1784 "TYPE"
1786 The filesystem type or RAID of this device.
1787 "USAGE"
1789 The usage of this device, for example "filesystem" or "raid".
1790 blockdev-flushbufs
1792 blockdev-flushbufs device
1793 This tells the kernel to flush internal buffers associated with
1795 "device".
1796 This uses the blockdev(8) command.
1798 blockdev-getbsz
1800 blockdev-getbsz device
1801 This returns the block size of a device.
1803 Note: this is different from both size in blocks and filesystem block
1805 size. Also this setting is not really used by anything. You should
1806 probably not use it for anything. Filesystems have their own idea
1807 about what block size to choose.
1808 This uses the blockdev(8) command.
1810 blockdev-getro
1812 blockdev-getro device
1813 Returns a boolean indicating if the block device is read-only (true if
1815 read-only, false if not).
1816 This uses the blockdev(8) command.
1818 blockdev-getsize64
1820 blockdev-getsize64 device
1821 This returns the size of the device in bytes.
1823 See also "blockdev-getsz".
1825 This uses the blockdev(8) command.
1827 blockdev-getss
1829 blockdev-getss device
1830 This returns the size of sectors on a block device. Usually 512, but
1832 can be larger for modern devices.
1833 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
1835 This uses the blockdev(8) command.
1837 blockdev-getsz
1839 blockdev-getsz device
1840 This returns the size of the device in units of 512-byte sectors (even
1842 if the sectorsize isn't 512 bytes ... weird).
1843 See also "blockdev-getss" for the real sector size of the device, and
1845 "blockdev-getsize64" for the more useful size in bytes.
1846 This uses the blockdev(8) command.
1848 blockdev-rereadpt
1850 blockdev-rereadpt device
1851 Reread the partition table on "device".
1853 This uses the blockdev(8) command.
1855 blockdev-setbsz
1857 blockdev-setbsz device blocksize
1858 This call does nothing and has never done anything because of a bug in
1860 blockdev. Do not use it.
1861 If you need to set the filesystem block size, use the "blocksize"
1863 option of "mkfs".
1864 This function is deprecated. In new code, use the "mkfs" call instead.
1866 Deprecated functions will not be removed from the API, but the fact
1868 that they are deprecated indicates that there are problems with correct
1869 use of these functions.
1870 blockdev-setro
1872 blockdev-setro device
1873 Sets the block device named "device" to read-only.
1875 This uses the blockdev(8) command.
1877 blockdev-setrw
1879 blockdev-setrw device
1880 Sets the block device named "device" to read-write.
1882 This uses the blockdev(8) command.
1884 btrfs-device-add
1886 btrfs-device-add 'devices ...' fs
1887 Add the list of device(s) in "devices" to the btrfs filesystem mounted
1889 at "fs". If "devices" is an empty list, this does nothing.
1890 btrfs-device-delete
1892 btrfs-device-delete 'devices ...' fs
1893 Remove the "devices" from the btrfs filesystem mounted at "fs". If
1895 "devices" is an empty list, this does nothing.
1896 btrfs-filesystem-balance
1898 btrfs-filesystem-balance fs
1899 Balance the chunks in the btrfs filesystem mounted at "fs" across the
1901 underlying devices.
1902 btrfs-filesystem-resize
1904 btrfs-filesystem-resize mountpoint [size:N]
1905 This command resizes a btrfs filesystem.
1907 Note that unlike other resize calls, the filesystem has to be mounted
1909 and the parameter is the mountpoint not the device (this is a
1910 requirement of btrfs itself).
1911 The optional parameters are:
1913 "size"
1915 The new size (in bytes) of the filesystem. If omitted, the
1916 filesystem is resized to the maximum size.
1917 See also btrfs(8).
1919 This command has one or more optional arguments. See "OPTIONAL
1921 ARGUMENTS".
1922 btrfs-filesystem-sync
1924 btrfs-filesystem-sync fs
1925 Force sync on the btrfs filesystem mounted at "fs".
1927 btrfs-fsck
1929 btrfs-fsck device [superblock:N] [repair:true|false]
1930 Used to check a btrfs filesystem, "device" is the device file where the
1932 filesystem is stored.
1933 This command has one or more optional arguments. See "OPTIONAL
1935 ARGUMENTS".
1936 btrfs-set-seeding
1938 btrfs-set-seeding device true|false
1939 Enable or disable the seeding feature of a device that contains a btrfs
1941 filesystem.
1942 btrfs-subvolume-create
1944 btrfs-subvolume-create dest
1945 Create a btrfs subvolume. The "dest" argument is the destination
1947 directory and the name of the snapshot, in the form
1948 "/path/to/dest/name".
1949 btrfs-subvolume-delete
1951 btrfs-subvolume-delete subvolume
1952 Delete the named btrfs subvolume.
1954 btrfs-subvolume-list
1956 btrfs-subvolume-list fs
1957 List the btrfs snapshots and subvolumes of the btrfs filesystem which
1959 is mounted at "fs".
1960 btrfs-subvolume-set-default
1962 btrfs-subvolume-set-default id fs
1963 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
1965 default. See "btrfs-subvolume-list" to get a list of subvolumes.
1966 btrfs-subvolume-snapshot
1968 btrfs-subvolume-snapshot source dest
1969 Create a writable snapshot of the btrfs subvolume "source". The "dest"
1971 argument is the destination directory and the name of the snapshot, in
1972 the form "/path/to/dest/name".
1973 canonical-device-name
1975 canonical-device-name device
1976 This utility function is useful when displaying device names to the
1978 user. It takes a number of irregular device names and returns them in
1979 a consistent format:
1980 "/dev/hdX"
1982 "/dev/vdX"
1983 These are returned as "/dev/sdX". Note this works for device names
1984 and partition names. This is approximately the reverse of the
1985 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
1986 "/dev/mapper/VG-LV"
1988 "/dev/dm-N"
1989 Converted to "/dev/VG/LV" form using "lvm-canonical-lvm-name".
1990 Other strings are returned unmodified.
1992 cap-get-file
1994 cap-get-file path
1995 This function returns the Linux capabilities attached to "path". The
1997 capabilities set is returned in text form (see cap_to_text(3)).
1998 If no capabilities are attached to a file, an empty string is returned.
2000 cap-set-file
2002 cap-set-file path cap
2003 This function sets the Linux capabilities attached to "path". The
2005 capabilities set "cap" should be passed in text form (see
2006 cap_from_text(3)).
2007 case-sensitive-path
2009 case-sensitive-path path
2010 This can be used to resolve case insensitive paths on a filesystem
2012 which is case sensitive. The use case is to resolve paths which you
2013 have read from Windows configuration files or the Windows Registry, to
2014 the true path.
2015 The command handles a peculiarity of the Linux ntfs-3g filesystem
2017 driver (and probably others), which is that although the underlying
2018 filesystem is case-insensitive, the driver exports the filesystem to
2019 Linux as case-sensitive.
2020 One consequence of this is that special directories such as
2022 "c:\windows" may appear as "/WINDOWS" or "/windows" (or other things)
2023 depending on the precise details of how they were created. In Windows
2024 itself this would not be a problem.
2025 Bug or feature? You decide:
2027 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2028 This function resolves the true case of each element in the path and
2030 returns the case-sensitive path.
2031 Thus "case-sensitive-path" ("/Windows/System32") might return
2033 "/WINDOWS/system32" (the exact return value would depend on details of
2034 how the directories were originally created under Windows).
2035 Note: This function does not handle drive names, backslashes etc.
2037 See also "realpath".
2039 cat
2041 cat path
2042 Return the contents of the file named "path".
2044 Because, in C, this function returns a "char *", there is no way to
2046 differentiate between a "\0" character in a file and end of string. To
2047 handle binary files, use the "read-file" or "download" functions.
2048 checksum
2050 checksum csumtype path
2051 This call computes the MD5, SHAx or CRC checksum of the file named
2053 "path".
2054 The type of checksum to compute is given by the "csumtype" parameter
2056 which must have one of the following values:
2057 "crc"
2059 Compute the cyclic redundancy check (CRC) specified by POSIX for
2060 the "cksum" command.
2061 "md5"
2063 Compute the MD5 hash (using the "md5sum" program).
2064 "sha1"
2066 Compute the SHA1 hash (using the "sha1sum" program).
2067 "sha224"
2069 Compute the SHA224 hash (using the "sha224sum" program).
2070 "sha256"
2072 Compute the SHA256 hash (using the "sha256sum" program).
2073 "sha384"
2075 Compute the SHA384 hash (using the "sha384sum" program).
2076 "sha512"
2078 Compute the SHA512 hash (using the "sha512sum" program).
2079 The checksum is returned as a printable string.
2081 To get the checksum for a device, use "checksum-device".
2083 To get the checksums for many files, use "checksums-out".
2085 checksum-device
2087 checksum-device csumtype device
2088 This call computes the MD5, SHAx or CRC checksum of the contents of the
2090 device named "device". For the types of checksums supported see the
2091 "checksum" command.
2092 checksums-out
2094 checksums-out csumtype directory (sumsfile|-)
2095 This command computes the checksums of all regular files in "directory"
2097 and then emits a list of those checksums to the local output file
2098 "sumsfile".
2099 This can be used for verifying the integrity of a virtual machine.
2101 However to be properly secure you should pay attention to the output of
2102 the checksum command (it uses the ones from GNU coreutils). In
2103 particular when the filename is not printable, coreutils uses a special
2104 backslash syntax. For more information, see the GNU coreutils info
2105 file.
2106 Use "-" instead of a filename to read/write from stdin/stdout.
2108 chmod
2110 chmod mode path
2111 Change the mode (permissions) of "path" to "mode". Only numeric modes
2113 are supported.
2114 Note: When using this command from guestfish, "mode" by default would
2116 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2117 700.
2118 The mode actually set is affected by the umask.
2120 chown
2122 chown owner group path
2123 Change the file owner to "owner" and group to "group".
2125 Only numeric uid and gid are supported. If you want to use names, you
2127 will need to locate and parse the password file yourself (Augeas
2128 support makes this relatively easy).
2129 command
2131 command 'arguments ...'
2132 This call runs a command from the guest filesystem. The filesystem
2134 must be mounted, and must contain a compatible operating system (ie.
2135 something Linux, with the same or compatible processor architecture).
2136 The single parameter is an argv-style list of arguments. The first
2138 element is the name of the program to run. Subsequent elements are
2139 parameters. The list must be non-empty (ie. must contain a program
2140 name). Note that the command runs directly, and is not invoked via the
2141 shell (see "sh").
2142 The return value is anything printed to stdout by the command.
2144 If the command returns a non-zero exit status, then this function
2146 returns an error message. The error message string is the content of
2147 stderr from the command.
2148 The $PATH environment variable will contain at least "/usr/bin" and
2150 "/bin". If you require a program from another location, you should
2151 provide the full path in the first parameter.
2152 Shared libraries and data files required by the program must be
2154 available on filesystems which are mounted in the correct places. It
2155 is the caller's responsibility to ensure all filesystems that are
2156 needed are mounted at the right locations.
2157 Because of the message protocol, there is a transfer limit of somewhere
2159 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2160 command-lines
2162 command-lines 'arguments ...'
2163 This is the same as "command", but splits the result into a list of
2165 lines.
2166 See also: "sh-lines"
2168 Because of the message protocol, there is a transfer limit of somewhere
2170 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2171 compress-device-out
2173 compress-device-out ctype device (zdevice|-) [level:N]
2174 This command compresses "device" and writes it out to the local file
2176 "zdevice".
2177 The "ctype" and optional "level" parameters have the same meaning as in
2179 "compress-out".
2180 Use "-" instead of a filename to read/write from stdin/stdout.
2182 This command has one or more optional arguments. See "OPTIONAL
2184 ARGUMENTS".
2185 compress-out
2187 compress-out ctype file (zfile|-) [level:N]
2188 This command compresses "file" and writes it out to the local file
2190 "zfile".
2191 The compression program used is controlled by the "ctype" parameter.
2193 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
2194 Some compression types may not be supported by particular builds of
2195 libguestfs, in which case you will get an error containing the
2196 substring "not supported".
2197 The optional "level" parameter controls compression level. The meaning
2199 and default for this parameter depends on the compression program being
2200 used.
2201 Use "-" instead of a filename to read/write from stdin/stdout.
2203 This command has one or more optional arguments. See "OPTIONAL
2205 ARGUMENTS".
2206 config
2208 config qemuparam qemuvalue
2209 This can be used to add arbitrary qemu command line parameters of the
2211 form -param value. Actually it's not quite arbitrary - we prevent you
2212 from setting some parameters which would interfere with parameters that
2213 we use.
2214 The first character of "qemuparam" string must be a "-" (dash).
2216 "qemuvalue" can be NULL.
2218 copy-device-to-device
2220 copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N]
2221 The four calls "copy-device-to-device", "copy-device-to-file", "copy-
2223 file-to-device", and "copy-file-to-file" let you copy from a source
2224 (device|file) to a destination (device|file).
2225 Partial copies can be made since you can specify optionally the source
2227 offset, destination offset and size to copy. These values are all
2228 specified in bytes. If not given, the offsets both default to zero,
2229 and the size defaults to copying as much as possible until we hit the
2230 end of the source.
2231 The source and destination may be the same object. However overlapping
2233 regions may not be copied correctly.
2234 If the destination is a file, it is created if required. If the
2236 destination file is not large enough, it is extended.
2237 This command has one or more optional arguments. See "OPTIONAL
2239 ARGUMENTS".
2240 copy-device-to-file
2242 copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N]
2243 See "copy-device-to-device" for a general overview of this call.
2245 This command has one or more optional arguments. See "OPTIONAL
2247 ARGUMENTS".
2248 copy-file-to-device
2250 copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N]
2251 See "copy-device-to-device" for a general overview of this call.
2253 This command has one or more optional arguments. See "OPTIONAL
2255 ARGUMENTS".
2256 copy-file-to-file
2258 copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N]
2259 See "copy-device-to-device" for a general overview of this call.
2261 This is not the function you want for copying files. This is for
2263 copying blocks within existing files. See "cp", "cp-a" and "mv" for
2264 general file copying and moving functions.
2265 This command has one or more optional arguments. See "OPTIONAL
2267 ARGUMENTS".
2268 copy-size
2270 copy-size src dest size
2271 This command copies exactly "size" bytes from one source device or file
2273 "src" to another destination device or file "dest".
2274 Note this will fail if the source is too short or if the destination is
2276 not large enough.
2277 This function is deprecated. In new code, use the "copy-device-to-
2279 device" call instead.
2280 Deprecated functions will not be removed from the API, but the fact
2282 that they are deprecated indicates that there are problems with correct
2283 use of these functions.
2284 cp
2286 cp src dest
2287 This copies a file from "src" to "dest" where "dest" is either a
2289 destination filename or destination directory.
2290 cp-a
2292 cp-a src dest
2293 This copies a file or directory from "src" to "dest" recursively using
2295 the "cp -a" command.
2296 dd
2298 dd src dest
2299 This command copies from one source device or file "src" to another
2301 destination device or file "dest". Normally you would use this to copy
2302 to or from a device or partition, for example to duplicate a
2303 filesystem.
2304 If the destination is a device, it must be as large or larger than the
2306 source file or device, otherwise the copy will fail. This command
2307 cannot do partial copies (see "copy-device-to-device").
2308 This function is deprecated. In new code, use the "copy-device-to-
2310 device" call instead.
2311 Deprecated functions will not be removed from the API, but the fact
2313 that they are deprecated indicates that there are problems with correct
2314 use of these functions.
2315 device-index
2317 device-index device
2318 This function takes a device name (eg. "/dev/sdb") and returns the
2320 index of the device in the list of devices.
2321 Index numbers start from 0. The named device must exist, for example
2323 as a string returned from "list-devices".
2324 See also "list-devices", "part-to-dev".
2326 df
2328 df
2329 This command runs the "df" command to report disk space used.
2331 This command is mostly useful for interactive sessions. It is not
2333 intended that you try to parse the output string. Use "statvfs" from
2334 programs.
2335 df-h
2337 df-h
2338 This command runs the "df -h" command to report disk space used in
2340 human-readable format.
2341 This command is mostly useful for interactive sessions. It is not
2343 intended that you try to parse the output string. Use "statvfs" from
2344 programs.
2345 disk-format
2347 disk-format filename
2348 Detect and return the format of the disk image called "filename".
2350 "filename" can also be a host device, etc. If the format of the image
2351 could not be detected, then "unknown" is returned.
2352 Note that detecting the disk format can be insecure under some
2354 circumstances. See "CVE-2010-3851" in guestfs(3).
2355 See also: "DISK IMAGE FORMATS" in guestfs(3)
2357 disk-has-backing-file
2359 disk-has-backing-file filename
2360 Detect and return whether the disk image "filename" has a backing file.
2362 Note that detecting disk features can be insecure under some
2364 circumstances. See "CVE-2010-3851" in guestfs(3).
2365 disk-virtual-size
2367 disk-virtual-size filename
2368 Detect and return the virtual size in bytes of the disk image called
2370 "filename".
2371 Note that detecting disk features can be insecure under some
2373 circumstances. See "CVE-2010-3851" in guestfs(3).
2374 dmesg
2376 dmesg
2377 This returns the kernel messages ("dmesg" output) from the guest
2379 kernel. This is sometimes useful for extended debugging of problems.
2380 Another way to get the same information is to enable verbose messages
2382 with "set-verbose" or by setting the environment variable
2383 "LIBGUESTFS_DEBUG=1" before running the program.
2384 download
2386 download remotefilename (filename|-)
2387 Download file "remotefilename" and save it as "filename" on the local
2389 machine.
2390 "filename" can also be a named pipe.
2392 See also "upload", "cat".
2394 Use "-" instead of a filename to read/write from stdin/stdout.
2396 download-offset
2398 download-offset remotefilename (filename|-) offset size
2399 Download file "remotefilename" and save it as "filename" on the local
2401 machine.
2402 "remotefilename" is read for "size" bytes starting at "offset" (this
2404 region must be within the file or device).
2405 Note that there is no limit on the amount of data that can be
2407 downloaded with this call, unlike with "pread", and this call always
2408 reads the full amount unless an error occurs.
2409 See also "download", "pread".
2411 Use "-" instead of a filename to read/write from stdin/stdout.
2413 drop-caches
2415 drop-caches whattodrop
2416 This instructs the guest kernel to drop its page cache, and/or dentries
2418 and inode caches. The parameter "whattodrop" tells the kernel what
2419 precisely to drop, see http://linux-mm.org/Drop_Caches
2420 Setting "whattodrop" to 3 should drop everything.
2422 This automatically calls sync(2) before the operation, so that the
2424 maximum guest memory is freed.
2425 du
2427 du path
2428 This command runs the "du -s" command to estimate file space usage for
2430 "path".
2431 "path" can be a file or a directory. If "path" is a directory then the
2433 estimate includes the contents of the directory and all subdirectories
2434 (recursively).
2435 The result is the estimated size in kilobytes (ie. units of 1024
2437 bytes).
2438 e2fsck
2440 e2fsck device [correct:true|false] [forceall:true|false]
2441 This runs the ext2/ext3 filesystem checker on "device". It can take
2443 the following optional arguments:
2444 "correct"
2446 Automatically repair the file system. This option will cause e2fsck
2447 to automatically fix any filesystem problems that can be safely
2448 fixed without human intervention.
2449 This option may not be specified at the same time as the "forceall"
2451 option.
2452 "forceall"
2454 Assume an answer of 'yes' to all questions; allows e2fsck to be
2455 used non-interactively.
2456 This option may not be specified at the same time as the "correct"
2458 option.
2459 This command has one or more optional arguments. See "OPTIONAL
2461 ARGUMENTS".
2462 e2fsck-f
2464 e2fsck-f device
2465 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
2467 checker on "device", noninteractively (-p), even if the filesystem
2468 appears to be clean (-f).
2469 This function is deprecated. In new code, use the "e2fsck" call
2471 instead.
2472 Deprecated functions will not be removed from the API, but the fact
2474 that they are deprecated indicates that there are problems with correct
2475 use of these functions.
2476 echo-daemon
2478 echo-daemon 'words ...'
2479 This command concatenates the list of "words" passed with single spaces
2481 between them and returns the resulting string.
2482 You can use this command to test the connection through to the daemon.
2484 See also "ping-daemon".
2486 egrep
2488 egrep regex path
2489 This calls the external "egrep" program and returns the matching lines.
2491 Because of the message protocol, there is a transfer limit of somewhere
2493 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2494 This function is deprecated. In new code, use the "grep" call instead.
2496 Deprecated functions will not be removed from the API, but the fact
2498 that they are deprecated indicates that there are problems with correct
2499 use of these functions.
2500 egrepi
2502 egrepi regex path
2503 This calls the external "egrep -i" program and returns the matching
2505 lines.
2506 Because of the message protocol, there is a transfer limit of somewhere
2508 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2509 This function is deprecated. In new code, use the "grep" call instead.
2511 Deprecated functions will not be removed from the API, but the fact
2513 that they are deprecated indicates that there are problems with correct
2514 use of these functions.
2515 equal
2517 equal file1 file2
2518 This compares the two files "file1" and "file2" and returns true if
2520 their content is exactly equal, or false otherwise.
2521 The external cmp(1) program is used for the comparison.
2523 exists
2525 exists path
2526 This returns "true" if and only if there is a file, directory (or
2528 anything) with the given "path" name.
2529 See also "is-file", "is-dir", "stat".
2531 fallocate
2533 fallocate path len
2534 This command preallocates a file (containing zero bytes) named "path"
2536 of size "len" bytes. If the file exists already, it is overwritten.
2537 Do not confuse this with the guestfish-specific "alloc" command which
2539 allocates a file in the host and attaches it as a device.
2540 This function is deprecated. In new code, use the "fallocate64" call
2542 instead.
2543 Deprecated functions will not be removed from the API, but the fact
2545 that they are deprecated indicates that there are problems with correct
2546 use of these functions.
2547 fallocate64
2549 fallocate64 path len
2550 This command preallocates a file (containing zero bytes) named "path"
2552 of size "len" bytes. If the file exists already, it is overwritten.
2553 Note that this call allocates disk blocks for the file. To create a
2555 sparse file use "truncate-size" instead.
2556 The deprecated call "fallocate" does the same, but owing to an
2558 oversight it only allowed 30 bit lengths to be specified, effectively
2559 limiting the maximum size of files created through that call to 1GB.
2560 Do not confuse this with the guestfish-specific "alloc" and "sparse"
2562 commands which create a file in the host and attach it as a device.
2563 fgrep
2565 fgrep pattern path
2566 This calls the external "fgrep" program and returns the matching lines.
2568 Because of the message protocol, there is a transfer limit of somewhere
2570 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2571 This function is deprecated. In new code, use the "grep" call instead.
2573 Deprecated functions will not be removed from the API, but the fact
2575 that they are deprecated indicates that there are problems with correct
2576 use of these functions.
2577 fgrepi
2579 fgrepi pattern path
2580 This calls the external "fgrep -i" program and returns the matching
2582 lines.
2583 Because of the message protocol, there is a transfer limit of somewhere
2585 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2586 This function is deprecated. In new code, use the "grep" call instead.
2588 Deprecated functions will not be removed from the API, but the fact
2590 that they are deprecated indicates that there are problems with correct
2591 use of these functions.
2592 file
2594 file path
2595 This call uses the standard file(1) command to determine the type or
2597 contents of the file.
2598 This call will also transparently look inside various types of
2600 compressed file.
2601 The exact command which runs is "file -zb path". Note in particular
2603 that the filename is not prepended to the output (the -b option).
2604 The output depends on the output of the underlying file(1) command and
2606 it can change in future in ways beyond our control. In other words,
2607 the output is not guaranteed by the ABI.
2608 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
2610 "is-zero".
2611 file-architecture
2613 file-architecture filename
2614 This detects the architecture of the binary "filename", and returns it
2616 if known.
2617 Currently defined architectures are:
2619 "i386"
2621 This string is returned for all 32 bit i386, i486, i586, i686
2622 binaries irrespective of the precise processor requirements of the
2623 binary.
2624 "x86_64"
2626 64 bit x86-64.
2627 "sparc"
2629 32 bit SPARC.
2630 "sparc64"
2632 64 bit SPARC V9 and above.
2633 "ia64"
2635 Intel Itanium.
2636 "ppc"
2638 32 bit Power PC.
2639 "ppc64"
2641 64 bit Power PC.
2642 Libguestfs may return other architecture strings in future.
2644 The function works on at least the following types of files:
2646 · many types of Un*x and Linux binary
2648 · many types of Un*x and Linux shared library
2650 · Windows Win32 and Win64 binaries
2652 · Windows Win32 and Win64 DLLs
2654 Win32 binaries and DLLs return "i386".
2656 Win64 binaries and DLLs return "x86_64".
2658 · Linux kernel modules
2660 · Linux new-style initrd images
2662 · some non-x86 Linux vmlinuz kernels
2664 What it can't do currently:
2666 · static libraries (libfoo.a)
2668 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
2670 · x86 Linux vmlinuz kernels
2672 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
2674 and compressed code, and are horribly hard to unpack. If you want
2675 to find the architecture of a kernel, use the architecture of the
2676 associated initrd or kernel module(s) instead.
2677 filesize
2679 filesize file
2680 This command returns the size of "file" in bytes.
2682 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
2684 file" etc. To get the size of block devices, use "blockdev-getsize64".
2685 filesystem-available
2687 filesystem-available filesystem
2688 Check whether libguestfs supports the named filesystem. The argument
2690 "filesystem" is a filesystem name, such as "ext3".
2691 You must call "launch" before using this command.
2693 This is mainly useful as a negative test. If this returns true, it
2695 doesn't mean that a particular filesystem can be created or mounted,
2696 since filesystems can fail for other reasons such as it being a later
2697 version of the filesystem, or having incompatible features, or lacking
2698 the right mkfs.<fs> tool.
2699 See also "available", "AVAILABILITY" in guestfs(3).
2701 fill
2703 fill c len path
2704 This command creates a new file called "path". The initial content of
2706 the file is "len" octets of "c", where "c" must be a number in the
2707 range "[0..255]".
2708 To fill a file with zero bytes (sparsely), it is much more efficient to
2710 use "truncate-size". To create a file with a pattern of repeating
2711 bytes use "fill-pattern".
2712 fill-dir
2714 fill-dir dir nr
2715 This function, useful for testing filesystems, creates "nr" empty files
2717 in the directory "dir" with names 00000000 through "nr-1" (ie. each
2718 file name is 8 digits long padded with zeroes).
2719 fill-pattern
2721 fill-pattern pattern len path
2722 This function is like "fill" except that it creates a new file of
2724 length "len" containing the repeating pattern of bytes in "pattern".
2725 The pattern is truncated if necessary to ensure the length of the file
2726 is exactly "len" bytes.
2727 find
2729 find directory
2730 This command lists out all files and directories, recursively, starting
2732 at "directory". It is essentially equivalent to running the shell
2733 command "find directory -print" but some post-processing happens on the
2734 output, described below.
2735 This returns a list of strings without any prefix. Thus if the
2737 directory structure was:
2738 /tmp/a
2740 /tmp/b
2741 /tmp/c/d
2742 then the returned list from "find" "/tmp" would be 4 elements:
2744 a
2746 b
2747 c
2748 c/d
2749 If "directory" is not a directory, then this command returns an error.
2751 The returned list is sorted.
2753 find0
2755 find0 directory (files|-)
2756 This command lists out all files and directories, recursively, starting
2758 at "directory", placing the resulting list in the external file called
2759 "files".
2760 This command works the same way as "find" with the following
2762 exceptions:
2763 · The resulting list is written to an external file.
2765 · Items (filenames) in the result are separated by "\0" characters.
2767 See find(1) option -print0.
2768 · The result list is not sorted.
2770 Use "-" instead of a filename to read/write from stdin/stdout.
2772 findfs-label
2774 findfs-label label
2775 This command searches the filesystems and returns the one which has the
2777 given label. An error is returned if no such filesystem can be found.
2778 To find the label of a filesystem, use "vfs-label".
2780 findfs-uuid
2782 findfs-uuid uuid
2783 This command searches the filesystems and returns the one which has the
2785 given UUID. An error is returned if no such filesystem can be found.
2786 To find the UUID of a filesystem, use "vfs-uuid".
2788 fsck
2790 fsck fstype device
2791 This runs the filesystem checker (fsck) on "device" which should have
2793 filesystem type "fstype".
2794 The returned integer is the status. See fsck(8) for the list of status
2796 codes from "fsck".
2797 Notes:
2799 · Multiple status codes can be summed together.
2801 · A non-zero return code can mean "success", for example if errors
2803 have been corrected on the filesystem.
2804 · Checking or repairing NTFS volumes is not supported (by linux-
2806 ntfs).
2807 This command is entirely equivalent to running "fsck -a -t fstype
2809 device".
2810 get-append
2812 get-append
2813 Return the additional kernel options which are added to the libguestfs
2815 appliance kernel command line.
2816 If "NULL" then no options are added.
2818 get-attach-method
2820 get-attach-method
2821 Return the current attach method.
2823 See "set-attach-method" and "ATTACH METHOD" in guestfs(3).
2825 get-autosync
2827 get-autosync
2828 Get the autosync flag.
2830 get-cachedir
2832 get-cachedir
2833 Get the directory used by the handle to store the appliance cache.
2835 get-direct
2837 get-direct
2838 Return the direct appliance mode flag.
2840 get-e2attrs
2842 get-e2attrs file
2843 This returns the file attributes associated with "file".
2845 The attributes are a set of bits associated with each inode which
2847 affect the behaviour of the file. The attributes are returned as a
2848 string of letters (described below). The string may be empty,
2849 indicating that no file attributes are set for this file.
2850 These attributes are only present when the file is located on an
2852 ext2/3/4 filesystem. Using this call on other filesystem types will
2853 result in an error.
2854 The characters (file attributes) in the returned string are currently:
2856 'A' When the file is accessed, its atime is not modified.
2858 'a' The file is append-only.
2860 'c' The file is compressed on-disk.
2862 'D' (Directories only.) Changes to this directory are written
2864 synchronously to disk.
2865 'd' The file is not a candidate for backup (see dump(8)).
2867 'E' The file has compression errors.
2869 'e' The file is using extents.
2871 'h' The file is storing its blocks in units of the filesystem blocksize
2873 instead of sectors.
2874 'I' (Directories only.) The directory is using hashed trees.
2876 'i' The file is immutable. It cannot be modified, deleted or renamed.
2878 No link can be created to this file.
2879 'j' The file is data-journaled.
2881 's' When the file is deleted, all its blocks will be zeroed.
2883 'S' Changes to this file are written synchronously to disk.
2885 'T' (Directories only.) This is a hint to the block allocator that
2887 subdirectories contained in this directory should be spread across
2888 blocks. If not present, the block allocator will try to group
2889 subdirectories together.
2890 't' For a file, this disables tail-merging. (Not used by upstream
2892 implementations of ext2.)
2893 'u' When the file is deleted, its blocks will be saved, allowing the
2895 file to be undeleted.
2896 'X' The raw contents of the compressed file may be accessed.
2898 'Z' The compressed file is dirty.
2900 More file attributes may be added to this list later. Not all file
2902 attributes may be set for all kinds of files. For detailed
2903 information, consult the chattr(1) man page.
2904 See also "set-e2attrs".
2906 Don't confuse these attributes with extended attributes (see
2908 "getxattr").
2909 get-e2generation
2911 get-e2generation file
2912 This returns the ext2 file generation of a file. The generation (which
2914 used to be called the "version") is a number associated with an inode.
2915 This is most commonly used by NFS servers.
2916 The generation is only present when the file is located on an ext2/3/4
2918 filesystem. Using this call on other filesystem types will result in
2919 an error.
2920 See "set-e2generation".
2922 get-e2label
2924 get-e2label device
2925 This returns the ext2/3/4 filesystem label of the filesystem on
2927 "device".
2928 This function is deprecated. In new code, use the "vfs-label" call
2930 instead.
2931 Deprecated functions will not be removed from the API, but the fact
2933 that they are deprecated indicates that there are problems with correct
2934 use of these functions.
2935 get-e2uuid
2937 get-e2uuid device
2938 This returns the ext2/3/4 filesystem UUID of the filesystem on
2940 "device".
2941 This function is deprecated. In new code, use the "vfs-uuid" call
2943 instead.
2944 Deprecated functions will not be removed from the API, but the fact
2946 that they are deprecated indicates that there are problems with correct
2947 use of these functions.
2948 get-libvirt-requested-credential-challenge
2950 get-libvirt-requested-credential-challenge index
2951 Get the challenge (provided by libvirt) for the "index"'th requested
2953 credential. If libvirt did not provide a challenge, this returns the
2954 empty string "".
2955 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2957 example code.
2958 get-libvirt-requested-credential-defresult
2960 get-libvirt-requested-credential-defresult index
2961 Get the default result (provided by libvirt) for the "index"'th
2963 requested credential. If libvirt did not provide a default result,
2964 this returns the empty string "".
2965 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2967 example code.
2968 get-libvirt-requested-credential-prompt
2970 get-libvirt-requested-credential-prompt index
2971 Get the prompt (provided by libvirt) for the "index"'th requested
2973 credential. If libvirt did not provide a prompt, this returns the
2974 empty string "".
2975 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2977 example code.
2978 get-libvirt-requested-credentials
2980 get-libvirt-requested-credentials
2981 This should only be called during the event callback for events of type
2983 "GUESTFS_EVENT_LIBVIRT_AUTH".
2984 Return the list of credentials requested by libvirt. Possible values
2986 are a subset of the strings provided when you called "set-libvirt-
2987 supported-credentials".
2988 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
2990 example code.
2991 get-memsize
2993 get-memsize
2994 This gets the memory size in megabytes allocated to the qemu
2996 subprocess.
2997 If "set-memsize" was not called on this handle, and if
2999 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
3000 default value for memsize.
3001 For more information on the architecture of libguestfs, see guestfs(3).
3003 get-network
3005 get-network
3006 This returns the enable network flag.
3008 get-path
3010 get-path
3011 Return the current search path.
3013 This is always non-NULL. If it wasn't set already, then this will
3015 return the default path.
3016 get-pgroup
3018 get-pgroup
3019 This returns the process group flag.
3021 get-pid
3023 pid
3024 get-pid
3025 Return the process ID of the qemu subprocess. If there is no qemu
3027 subprocess, then this will return an error.
3028 This is an internal call used for debugging and testing.
3030 get-qemu
3032 get-qemu
3033 Return the current qemu binary.
3035 This is always non-NULL. If it wasn't set already, then this will
3037 return the default qemu binary name.
3038 get-recovery-proc
3040 get-recovery-proc
3041 Return the recovery process enabled flag.
3043 get-selinux
3045 get-selinux
3046 This returns the current setting of the selinux flag which is passed to
3048 the appliance at boot time. See "set-selinux".
3049 For more information on the architecture of libguestfs, see guestfs(3).
3051 get-smp
3053 get-smp
3054 This returns the number of virtual CPUs assigned to the appliance.
3056 get-state
3058 get-state
3059 This returns the current state as an opaque integer. This is only
3061 useful for printing debug and internal error messages.
3062 For more information on states, see guestfs(3).
3064 get-tmpdir
3066 get-tmpdir
3067 Get the directory used by the handle to store temporary files.
3069 get-trace
3071 get-trace
3072 Return the command trace flag.
3074 get-umask
3076 get-umask
3077 Return the current umask. By default the umask is 022 unless it has
3079 been set by calling "umask".
3080 get-verbose
3082 get-verbose
3083 This returns the verbose messages flag.
3085 getcon
3087 getcon
3088 This gets the SELinux security context of the daemon.
3090 See the documentation about SELINUX in guestfs(3), and "setcon"
3092 getxattr
3094 getxattr path name
3095 Get a single extended attribute from file "path" named "name". This
3097 call follows symlinks. If you want to lookup an extended attribute for
3098 the symlink itself, use "lgetxattr".
3099 Normally it is better to get all extended attributes from a file in one
3101 go by calling "getxattrs". However some Linux filesystem
3102 implementations are buggy and do not provide a way to list out
3103 attributes. For these filesystems (notably ntfs-3g) you have to know
3104 the names of the extended attributes you want in advance and call this
3105 function.
3106 Extended attribute values are blobs of binary data. If there is no
3108 extended attribute named "name", this returns an error.
3109 See also: "getxattrs", "lgetxattr", attr(5).
3111 getxattrs
3113 getxattrs path
3114 This call lists the extended attributes of the file or directory
3116 "path".
3117 At the system call level, this is a combination of the listxattr(2) and
3119 getxattr(2) calls.
3120 See also: "lgetxattrs", attr(5).
3122 glob-expand
3124 glob-expand pattern
3125 This command searches for all the pathnames matching "pattern"
3127 according to the wildcard expansion rules used by the shell.
3128 If no paths match, then this returns an empty list (note: not an
3130 error).
3131 It is just a wrapper around the C glob(3) function with flags
3133 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
3134 Notice that there is no equivalent command for expanding a device name
3136 (eg. "/dev/sd*"). Use "list-devices", "list-partitions" etc functions
3137 instead.
3138 grep
3140 grep-opts
3141 grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
3142 This calls the external "grep" program and returns the matching lines.
3144 The optional flags are:
3146 "extended"
3148 Use extended regular expressions. This is the same as using the -E
3149 flag.
3150 "fixed"
3152 Match fixed (don't use regular expressions). This is the same as
3153 using the -F flag.
3154 "insensitive"
3156 Match case-insensitive. This is the same as using the -i flag.
3157 "compressed"
3159 Use "zgrep" instead of "grep". This allows the input to be
3160 compress- or gzip-compressed.
3161 This command has one or more optional arguments. See "OPTIONAL
3163 ARGUMENTS".
3164 Because of the message protocol, there is a transfer limit of somewhere
3166 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3167 grepi
3169 grepi regex path
3170 This calls the external "grep -i" program and returns the matching
3172 lines.
3173 Because of the message protocol, there is a transfer limit of somewhere
3175 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3176 This function is deprecated. In new code, use the "grep" call instead.
3178 Deprecated functions will not be removed from the API, but the fact
3180 that they are deprecated indicates that there are problems with correct
3181 use of these functions.
3182 grub-install
3184 grub-install root device
3185 This command installs GRUB 1 (the Grand Unified Bootloader) on
3187 "device", with the root directory being "root".
3188 Notes:
3190 · There is currently no way in the API to install grub2, which is
3192 used by most modern Linux guests. It is possible to run the grub2
3193 command from the guest, although see the caveats in "RUNNING
3194 COMMANDS" in guestfs(3).
3195 · This uses "grub-install" from the host. Unfortunately grub is not
3197 always compatible with itself, so this only works in rather narrow
3198 circumstances. Careful testing with each guest version is
3199 advisable.
3200 · If grub-install reports the error "No suitable drive was found in
3202 the generated device map." it may be that you need to create a
3203 "/boot/grub/device.map" file first that contains the mapping
3204 between grub device names and Linux device names. It is usually
3205 sufficient to create a file containing:
3206 (hd0) /dev/vda
3208 replacing "/dev/vda" with the name of the installation device.
3210 head
3212 head path
3213 This command returns up to the first 10 lines of a file as a list of
3215 strings.
3216 Because of the message protocol, there is a transfer limit of somewhere
3218 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3219 head-n
3221 head-n nrlines path
3222 If the parameter "nrlines" is a positive number, this returns the first
3224 "nrlines" lines of the file "path".
3225 If the parameter "nrlines" is a negative number, this returns lines
3227 from the file "path", excluding the last "nrlines" lines.
3228 If the parameter "nrlines" is zero, this returns an empty list.
3230 Because of the message protocol, there is a transfer limit of somewhere
3232 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3233 hexdump
3235 hexdump path
3236 This runs "hexdump -C" on the given "path". The result is the human-
3238 readable, canonical hex dump of the file.
3239 Because of the message protocol, there is a transfer limit of somewhere
3241 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3242 hivex-close
3244 hivex-close
3245 Close the current hivex handle.
3247 This is a wrapper around the hivex(3) call of the same name.
3249 hivex-commit
3251 hivex-commit filename
3252 Commit (write) changes to the hive.
3254 If the optional "filename" parameter is null, then the changes are
3256 written back to the same hive that was opened. If this is not null
3257 then they are written to the alternate filename given and the original
3258 hive is left untouched.
3259 This is a wrapper around the hivex(3) call of the same name.
3261 hivex-node-add-child
3263 hivex-node-add-child parent name
3264 Add a child node to "parent" named "name".
3266 This is a wrapper around the hivex(3) call of the same name.
3268 hivex-node-children
3270 hivex-node-children nodeh
3271 Return the list of nodes which are subkeys of "nodeh".
3273 This is a wrapper around the hivex(3) call of the same name.
3275 hivex-node-delete-child
3277 hivex-node-delete-child nodeh
3278 Delete "nodeh", recursively if necessary.
3280 This is a wrapper around the hivex(3) call of the same name.
3282 hivex-node-get-child
3284 hivex-node-get-child nodeh name
3285 Return the child of "nodeh" with the name "name", if it exists. This
3287 can return 0 meaning the name was not found.
3288 This is a wrapper around the hivex(3) call of the same name.
3290 hivex-node-get-value
3292 hivex-node-get-value nodeh key
3293 Return the value attached to "nodeh" which has the name "key", if it
3295 exists. This can return 0 meaning the key was not found.
3296 This is a wrapper around the hivex(3) call of the same name.
3298 hivex-node-name
3300 hivex-node-name nodeh
3301 Return the name of "nodeh".
3303 This is a wrapper around the hivex(3) call of the same name.
3305 hivex-node-parent
3307 hivex-node-parent nodeh
3308 Return the parent node of "nodeh".
3310 This is a wrapper around the hivex(3) call of the same name.
3312 hivex-node-set-value
3314 hivex-node-set-value nodeh key t val
3315 Set or replace a single value under the node "nodeh". The "key" is the
3317 name, "t" is the type, and "val" is the data.
3318 This is a wrapper around the hivex(3) call of the same name.
3320 hivex-node-values
3322 hivex-node-values nodeh
3323 Return the array of (key, datatype, data) tuples attached to "nodeh".
3325 This is a wrapper around the hivex(3) call of the same name.
3327 hivex-open
3329 hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false]
3330 Open the Windows Registry hive file named "filename". If there was any
3332 previous hivex handle associated with this guestfs session, then it is
3333 closed.
3334 This is a wrapper around the hivex(3) call of the same name.
3336 This command has one or more optional arguments. See "OPTIONAL
3338 ARGUMENTS".
3339 hivex-root
3341 hivex-root
3342 Return the root node of the hive.
3344 This is a wrapper around the hivex(3) call of the same name.
3346 hivex-value-key
3348 hivex-value-key valueh
3349 Return the key (name) field of a (key, datatype, data) tuple.
3351 This is a wrapper around the hivex(3) call of the same name.
3353 hivex-value-type
3355 hivex-value-type valueh
3356 Return the data type field from a (key, datatype, data) tuple.
3358 This is a wrapper around the hivex(3) call of the same name.
3360 hivex-value-utf8
3362 hivex-value-utf8 valueh
3363 This calls "hivex-value-value" (which returns the data field from a
3365 hivex value tuple). It then assumes that the field is a UTF-16LE
3366 string and converts the result to UTF-8 (or if this is not possible, it
3367 returns an error).
3368 This is useful for reading strings out of the Windows registry.
3370 However it is not foolproof because the registry is not strongly-typed
3371 and fields can contain arbitrary or unexpected data.
3372 hivex-value-value
3374 hivex-value-value valueh
3375 Return the data field of a (key, datatype, data) tuple.
3377 This is a wrapper around the hivex(3) call of the same name.
3379 See also: "hivex-value-utf8".
3381 initrd-cat
3383 initrd-cat initrdpath filename
3384 This command unpacks the file "filename" from the initrd file called
3386 "initrdpath". The filename must be given without the initial "/"
3387 character.
3388 For example, in guestfish you could use the following command to
3390 examine the boot script (usually called "/init") contained in a Linux
3391 initrd or initramfs image:
3392 initrd-cat /boot/initrd-<version>.img init
3394 See also "initrd-list".
3396 Because of the message protocol, there is a transfer limit of somewhere
3398 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3399 initrd-list
3401 initrd-list path
3402 This command lists out files contained in an initrd.
3404 The files are listed without any initial "/" character. The files are
3406 listed in the order they appear (not necessarily alphabetical).
3407 Directory names are listed as separate items.
3408 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
3410 as initrd. We only support the newer initramfs format (compressed cpio
3411 files).
3412 inotify-add-watch
3414 inotify-add-watch path mask
3415 Watch "path" for the events listed in "mask".
3417 Note that if "path" is a directory then events within that directory
3419 are watched, but this does not happen recursively (in subdirectories).
3420 Note for non-C or non-Linux callers: the inotify events are defined by
3422 the Linux kernel ABI and are listed in "/usr/include/sys/inotify.h".
3423 inotify-close
3425 inotify-close
3426 This closes the inotify handle which was previously opened by
3428 inotify_init. It removes all watches, throws away any pending events,
3429 and deallocates all resources.
3430 inotify-files
3432 inotify-files
3433 This function is a helpful wrapper around "inotify-read" which just
3435 returns a list of pathnames of objects that were touched. The returned
3436 pathnames are sorted and deduplicated.
3437 inotify-init
3439 inotify-init maxevents
3440 This command creates a new inotify handle. The inotify subsystem can
3442 be used to notify events which happen to objects in the guest
3443 filesystem.
3444 "maxevents" is the maximum number of events which will be queued up
3446 between calls to "inotify-read" or "inotify-files". If this is passed
3447 as 0, then the kernel (or previously set) default is used. For Linux
3448 2.6.29 the default was 16384 events. Beyond this limit, the kernel
3449 throws away events, but records the fact that it threw them away by
3450 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
3451 "inotify-read").
3452 Before any events are generated, you have to add some watches to the
3454 internal watch list. See: "inotify-add-watch" and "inotify-rm-watch".
3455 Queued up events should be read periodically by calling "inotify-read"
3457 (or "inotify-files" which is just a helpful wrapper around "inotify-
3458 read"). If you don't read the events out often enough then you risk
3459 the internal queue overflowing.
3460 The handle should be closed after use by calling "inotify-close". This
3462 also removes any watches automatically.
3463 See also inotify(7) for an overview of the inotify interface as exposed
3465 by the Linux kernel, which is roughly what we expose via libguestfs.
3466 Note that there is one global inotify handle per libguestfs instance.
3467 inotify-read
3469 inotify-read
3470 Return the complete queue of events that have happened since the
3472 previous read call.
3473 If no events have happened, this returns an empty list.
3475 Note: In order to make sure that all events have been read, you must
3477 call this function repeatedly until it returns an empty list. The
3478 reason is that the call will read events up to the maximum appliance-
3479 to-host message size and leave remaining events in the queue.
3480 inotify-rm-watch
3482 inotify-rm-watch wd
3483 Remove a previously defined inotify watch. See "inotify-add-watch".
3485 inspect-get-arch
3487 inspect-get-arch root
3488 This returns the architecture of the inspected operating system. The
3490 possible return values are listed under "file-architecture".
3491 If the architecture could not be determined, then the string "unknown"
3493 is returned.
3494 Please read "INSPECTION" in guestfs(3) for more details.
3496 inspect-get-distro
3498 inspect-get-distro root
3499 This returns the distro (distribution) of the inspected operating
3501 system.
3502 Currently defined distros are:
3504 "archlinux"
3506 Arch Linux.
3507 "buildroot"
3509 Buildroot-derived distro, but not one we specifically recognize.
3510 "centos"
3512 CentOS.
3513 "cirros"
3515 Cirros.
3516 "debian"
3518 Debian.
3519 "fedora"
3521 Fedora.
3522 "freedos"
3524 FreeDOS.
3525 "gentoo"
3527 Gentoo.
3528 "linuxmint"
3530 Linux Mint.
3531 "mageia"
3533 Mageia.
3534 "mandriva"
3536 Mandriva.
3537 "meego"
3539 MeeGo.
3540 "openbsd"
3542 OpenBSD.
3543 "opensuse"
3545 OpenSUSE.
3546 "pardus"
3548 Pardus.
3549 "redhat-based"
3551 Some Red Hat-derived distro.
3552 "rhel"
3554 Red Hat Enterprise Linux.
3555 "scientificlinux"
3557 Scientific Linux.
3558 "slackware"
3560 Slackware.
3561 "sles"
3563 SuSE Linux Enterprise Server or Desktop.
3564 "suse-based"
3566 Some openSuSE-derived distro.
3567 "ttylinux"
3569 ttylinux.
3570 "ubuntu"
3572 Ubuntu.
3573 "unknown"
3575 The distro could not be determined.
3576 "windows"
3578 Windows does not have distributions. This string is returned if
3579 the OS type is Windows.
3580 Future versions of libguestfs may return other strings here. The
3582 caller should be prepared to handle any string.
3583 Please read "INSPECTION" in guestfs(3) for more details.
3585 inspect-get-drive-mappings
3587 inspect-get-drive-mappings root
3588 This call is useful for Windows which uses a primitive system of
3590 assigning drive letters (like "C:") to partitions. This inspection API
3591 examines the Windows Registry to find out how disks/partitions are
3592 mapped to drive letters, and returns a hash table as in the example
3593 below:
3594 C => /dev/vda2
3596 E => /dev/vdb1
3597 F => /dev/vdc1
3598 Note that keys are drive letters. For Windows, the key is case
3600 insensitive and just contains the drive letter, without the customary
3601 colon separator character.
3602 In future we may support other operating systems that also used drive
3604 letters, but the keys for those might not be case insensitive and might
3605 be longer than 1 character. For example in OS-9, hard drives were
3606 named "h0", "h1" etc.
3607 For Windows guests, currently only hard drive mappings are returned.
3609 Removable disks (eg. DVD-ROMs) are ignored.
3610 For guests that do not use drive mappings, or if the drive mappings
3612 could not be determined, this returns an empty hash table.
3613 Please read "INSPECTION" in guestfs(3) for more details. See also
3615 "inspect-get-mountpoints", "inspect-get-filesystems".
3616 inspect-get-filesystems
3618 inspect-get-filesystems root
3619 This returns a list of all the filesystems that we think are associated
3621 with this operating system. This includes the root filesystem, other
3622 ordinary filesystems, and non-mounted devices like swap partitions.
3623 In the case of a multi-boot virtual machine, it is possible for a
3625 filesystem to be shared between operating systems.
3626 Please read "INSPECTION" in guestfs(3) for more details. See also
3628 "inspect-get-mountpoints".
3629 inspect-get-format
3631 inspect-get-format root
3632 This returns the format of the inspected operating system. You can use
3634 it to detect install images, live CDs and similar.
3635 Currently defined formats are:
3637 "installed"
3639 This is an installed operating system.
3640 "installer"
3642 The disk image being inspected is not an installed operating
3643 system, but a bootable install disk, live CD, or similar.
3644 "unknown"
3646 The format of this disk image is not known.
3647 Future versions of libguestfs may return other strings here. The
3649 caller should be prepared to handle any string.
3650 Please read "INSPECTION" in guestfs(3) for more details.
3652 inspect-get-hostname
3654 inspect-get-hostname root
3655 This function returns the hostname of the operating system as found by
3657 inspection of the guest's configuration files.
3658 If the hostname could not be determined, then the string "unknown" is
3660 returned.
3661 Please read "INSPECTION" in guestfs(3) for more details.
3663 inspect-get-icon
3665 inspect-get-icon root [favicon:true|false] [highquality:true|false]
3666 This function returns an icon corresponding to the inspected operating
3668 system. The icon is returned as a buffer containing a PNG image (re-
3669 encoded to PNG if necessary).
3670 If it was not possible to get an icon this function returns a zero-
3672 length (non-NULL) buffer. Callers must check for this case.
3673 Libguestfs will start by looking for a file called "/etc/favicon.png"
3675 or "C:\etc\favicon.png" and if it has the correct format, the contents
3676 of this file will be returned. You can disable favicons by passing the
3677 optional "favicon" boolean as false (default is true).
3678 If finding the favicon fails, then we look in other places in the guest
3680 for a suitable icon.
3681 If the optional "highquality" boolean is true then only high quality
3683 icons are returned, which means only icons of high resolution with an
3684 alpha channel. The default (false) is to return any icon we can, even
3685 if it is of substandard quality.
3686 Notes:
3688 · Unlike most other inspection API calls, the guest's disks must be
3690 mounted up before you call this, since it needs to read information
3691 from the guest filesystem during the call.
3692 · Security: The icon data comes from the untrusted guest, and should
3694 be treated with caution. PNG files have been known to contain
3695 exploits. Ensure that libpng (or other relevant libraries) are
3696 fully up to date before trying to process or display the icon.
3697 · The PNG image returned can be any size. It might not be square.
3699 Libguestfs tries to return the largest, highest quality icon
3700 available. The application must scale the icon to the required
3701 size.
3702 · Extracting icons from Windows guests requires the external
3704 "wrestool" program from the "icoutils" package, and several
3705 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
3706 package. These must be installed separately.
3707 · Operating system icons are usually trademarks. Seek legal advice
3709 before using trademarks in applications.
3710 This command has one or more optional arguments. See "OPTIONAL
3712 ARGUMENTS".
3713 inspect-get-major-version
3715 inspect-get-major-version root
3716 This returns the major version number of the inspected operating
3718 system.
3719 Windows uses a consistent versioning scheme which is not reflected in
3721 the popular public names used by the operating system. Notably the
3722 operating system known as "Windows 7" is really version 6.1 (ie. major
3723 = 6, minor = 1). You can find out the real versions corresponding to
3724 releases of Windows by consulting Wikipedia or MSDN.
3725 If the version could not be determined, then 0 is returned.
3727 Please read "INSPECTION" in guestfs(3) for more details.
3729 inspect-get-minor-version
3731 inspect-get-minor-version root
3732 This returns the minor version number of the inspected operating
3734 system.
3735 If the version could not be determined, then 0 is returned.
3737 Please read "INSPECTION" in guestfs(3) for more details. See also
3739 "inspect-get-major-version".
3740 inspect-get-mountpoints
3742 inspect-get-mountpoints root
3743 This returns a hash of where we think the filesystems associated with
3745 this operating system should be mounted. Callers should note that this
3746 is at best an educated guess made by reading configuration files such
3747 as "/etc/fstab". In particular note that this may return filesystems
3748 which are non-existent or not mountable and callers should be prepared
3749 to handle or ignore failures if they try to mount them.
3750 Each element in the returned hashtable has a key which is the path of
3752 the mountpoint (eg. "/boot") and a value which is the filesystem that
3753 would be mounted there (eg. "/dev/sda1").
3754 Non-mounted devices such as swap devices are not returned in this list.
3756 For operating systems like Windows which still use drive letters, this
3758 call will only return an entry for the first drive "mounted on" "/".
3759 For information about the mapping of drive letters to partitions, see
3760 "inspect-get-drive-mappings".
3761 Please read "INSPECTION" in guestfs(3) for more details. See also
3763 "inspect-get-filesystems".
3764 inspect-get-package-format
3766 inspect-get-package-format root
3767 This function and "inspect-get-package-management" return the package
3769 format and package management tool used by the inspected operating
3770 system. For example for Fedora these functions would return "rpm"
3771 (package format) and "yum" (package management).
3772 This returns the string "unknown" if we could not determine the package
3774 format or if the operating system does not have a real packaging system
3775 (eg. Windows).
3776 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
3778 "pkgsrc". Future versions of libguestfs may return other strings.
3779 Please read "INSPECTION" in guestfs(3) for more details.
3781 inspect-get-package-management
3783 inspect-get-package-management root
3784 "inspect-get-package-format" and this function return the package
3786 format and package management tool used by the inspected operating
3787 system. For example for Fedora these functions would return "rpm"
3788 (package format) and "yum" (package management).
3789 This returns the string "unknown" if we could not determine the package
3791 management tool or if the operating system does not have a real
3792 packaging system (eg. Windows).
3793 Possible strings include: "yum", "up2date", "apt" (for all Debian
3795 derivatives), "portage", "pisi", "pacman", "urpmi", "zypper". Future
3796 versions of libguestfs may return other strings.
3797 Please read "INSPECTION" in guestfs(3) for more details.
3799 inspect-get-product-name
3801 inspect-get-product-name root
3802 This returns the product name of the inspected operating system. The
3804 product name is generally some freeform string which can be displayed
3805 to the user, but should not be parsed by programs.
3806 If the product name could not be determined, then the string "unknown"
3808 is returned.
3809 Please read "INSPECTION" in guestfs(3) for more details.
3811 inspect-get-product-variant
3813 inspect-get-product-variant root
3814 This returns the product variant of the inspected operating system.
3816 For Windows guests, this returns the contents of the Registry key
3818 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
3819 which is usually a string such as "Client" or "Server" (other values
3820 are possible). This can be used to distinguish consumer and enterprise
3821 versions of Windows that have the same version number (for example,
3822 Windows 7 and Windows 2008 Server are both version 6.1, but the former
3823 is "Client" and the latter is "Server").
3824 For enterprise Linux guests, in future we intend this to return the
3826 product variant such as "Desktop", "Server" and so on. But this is not
3827 implemented at present.
3828 If the product variant could not be determined, then the string
3830 "unknown" is returned.
3831 Please read "INSPECTION" in guestfs(3) for more details. See also
3833 "inspect-get-product-name", "inspect-get-major-version".
3834 inspect-get-roots
3836 inspect-get-roots
3837 This function is a convenient way to get the list of root devices, as
3839 returned from a previous call to "inspect-os", but without redoing the
3840 whole inspection process.
3841 This returns an empty list if either no root devices were found or the
3843 caller has not called "inspect-os".
3844 Please read "INSPECTION" in guestfs(3) for more details.
3846 inspect-get-type
3848 inspect-get-type root
3849 This returns the type of the inspected operating system. Currently
3851 defined types are:
3852 "linux"
3854 Any Linux-based operating system.
3855 "windows"
3857 Any Microsoft Windows operating system.
3858 "freebsd"
3860 FreeBSD.
3861 "netbsd"
3863 NetBSD.
3864 "openbsd"
3866 OpenBSD.
3867 "hurd"
3869 GNU/Hurd.
3870 "dos"
3872 MS-DOS, FreeDOS and others.
3873 "unknown"
3875 The operating system type could not be determined.
3876 Future versions of libguestfs may return other strings here. The
3878 caller should be prepared to handle any string.
3879 Please read "INSPECTION" in guestfs(3) for more details.
3881 inspect-get-windows-current-control-set
3883 inspect-get-windows-current-control-set root
3884 This returns the Windows CurrentControlSet of the inspected guest. The
3886 CurrentControlSet is a registry key name such as "ControlSet001".
3887 This call assumes that the guest is Windows and that the Registry could
3889 be examined by inspection. If this is not the case then an error is
3890 returned.
3891 Please read "INSPECTION" in guestfs(3) for more details.
3893 inspect-get-windows-systemroot
3895 inspect-get-windows-systemroot root
3896 This returns the Windows systemroot of the inspected guest. The
3898 systemroot is a directory path such as "/WINDOWS".
3899 This call assumes that the guest is Windows and that the systemroot
3901 could be determined by inspection. If this is not the case then an
3902 error is returned.
3903 Please read "INSPECTION" in guestfs(3) for more details.
3905 inspect-is-live
3907 inspect-is-live root
3908 If "inspect-get-format" returns "installer" (this is an install disk),
3910 then this returns true if a live image was detected on the disk.
3911 Please read "INSPECTION" in guestfs(3) for more details.
3913 inspect-is-multipart
3915 inspect-is-multipart root
3916 If "inspect-get-format" returns "installer" (this is an install disk),
3918 then this returns true if the disk is part of a set.
3919 Please read "INSPECTION" in guestfs(3) for more details.
3921 inspect-is-netinst
3923 inspect-is-netinst root
3924 If "inspect-get-format" returns "installer" (this is an install disk),
3926 then this returns true if the disk is a network installer, ie. not a
3927 self-contained install CD but one which is likely to require network
3928 access to complete the install.
3929 Please read "INSPECTION" in guestfs(3) for more details.
3931 inspect-list-applications
3933 inspect-list-applications root
3934 Return the list of applications installed in the operating system.
3936 Note: This call works differently from other parts of the inspection
3938 API. You have to call "inspect-os", then "inspect-get-mountpoints",
3939 then mount up the disks, before calling this. Listing applications is
3940 a significantly more difficult operation which requires access to the
3941 full filesystem. Also note that unlike the other "inspect-get-*" calls
3942 which are just returning data cached in the libguestfs handle, this
3943 call actually reads parts of the mounted filesystems during the call.
3944 This returns an empty list if the inspection code was not able to
3946 determine the list of applications.
3947 The application structure contains the following fields:
3949 "app_name"
3951 The name of the application. For Red Hat-derived and Debian-
3952 derived Linux guests, this is the package name.
3953 "app_display_name"
3955 The display name of the application, sometimes localized to the
3956 install language of the guest operating system.
3957 If unavailable this is returned as an empty string "". Callers
3959 needing to display something can use "app_name" instead.
3960 "app_epoch"
3962 For package managers which use epochs, this contains the epoch of
3963 the package (an integer). If unavailable, this is returned as 0.
3964 "app_version"
3966 The version string of the application or package. If unavailable
3967 this is returned as an empty string "".
3968 "app_release"
3970 The release string of the application or package, for package
3971 managers that use this. If unavailable this is returned as an
3972 empty string "".
3973 "app_install_path"
3975 The installation path of the application (on operating systems such
3976 as Windows which use installation paths). This path is in the
3977 format used by the guest operating system, it is not a libguestfs
3978 path.
3979 If unavailable this is returned as an empty string "".
3981 "app_trans_path"
3983 The install path translated into a libguestfs path. If unavailable
3984 this is returned as an empty string "".
3985 "app_publisher"
3987 The name of the publisher of the application, for package managers
3988 that use this. If unavailable this is returned as an empty string
3989 "".
3990 "app_url"
3992 The URL (eg. upstream URL) of the application. If unavailable this
3993 is returned as an empty string "".
3994 "app_source_package"
3996 For packaging systems which support this, the name of the source
3997 package. If unavailable this is returned as an empty string "".
3998 "app_summary"
4000 A short (usually one line) description of the application or
4001 package. If unavailable this is returned as an empty string "".
4002 "app_description"
4004 A longer description of the application or package. If unavailable
4005 this is returned as an empty string "".
4006 Please read "INSPECTION" in guestfs(3) for more details.
4008 This function is deprecated. In new code, use the
4010 "inspect-list-applications2" call instead.
4011 Deprecated functions will not be removed from the API, but the fact
4013 that they are deprecated indicates that there are problems with correct
4014 use of these functions.
4015 inspect-list-applications2
4017 inspect-list-applications2 root
4018 Return the list of applications installed in the operating system.
4020 Note: This call works differently from other parts of the inspection
4022 API. You have to call "inspect-os", then "inspect-get-mountpoints",
4023 then mount up the disks, before calling this. Listing applications is
4024 a significantly more difficult operation which requires access to the
4025 full filesystem. Also note that unlike the other "inspect-get-*" calls
4026 which are just returning data cached in the libguestfs handle, this
4027 call actually reads parts of the mounted filesystems during the call.
4028 This returns an empty list if the inspection code was not able to
4030 determine the list of applications.
4031 The application structure contains the following fields:
4033 "app2_name"
4035 The name of the application. For Red Hat-derived and Debian-
4036 derived Linux guests, this is the package name.
4037 "app2_display_name"
4039 The display name of the application, sometimes localized to the
4040 install language of the guest operating system.
4041 If unavailable this is returned as an empty string "". Callers
4043 needing to display something can use "app2_name" instead.
4044 "app2_epoch"
4046 For package managers which use epochs, this contains the epoch of
4047 the package (an integer). If unavailable, this is returned as 0.
4048 "app2_version"
4050 The version string of the application or package. If unavailable
4051 this is returned as an empty string "".
4052 "app2_release"
4054 The release string of the application or package, for package
4055 managers that use this. If unavailable this is returned as an
4056 empty string "".
4057 "app2_arch"
4059 The architecture string of the application or package, for package
4060 managers that use this. If unavailable this is returned as an
4061 empty string "".
4062 "app2_install_path"
4064 The installation path of the application (on operating systems such
4065 as Windows which use installation paths). This path is in the
4066 format used by the guest operating system, it is not a libguestfs
4067 path.
4068 If unavailable this is returned as an empty string "".
4070 "app2_trans_path"
4072 The install path translated into a libguestfs path. If unavailable
4073 this is returned as an empty string "".
4074 "app2_publisher"
4076 The name of the publisher of the application, for package managers
4077 that use this. If unavailable this is returned as an empty string
4078 "".
4079 "app2_url"
4081 The URL (eg. upstream URL) of the application. If unavailable this
4082 is returned as an empty string "".
4083 "app2_source_package"
4085 For packaging systems which support this, the name of the source
4086 package. If unavailable this is returned as an empty string "".
4087 "app2_summary"
4089 A short (usually one line) description of the application or
4090 package. If unavailable this is returned as an empty string "".
4091 "app2_description"
4093 A longer description of the application or package. If unavailable
4094 this is returned as an empty string "".
4095 Please read "INSPECTION" in guestfs(3) for more details.
4097 inspect-os
4099 inspect-os
4100 This function uses other libguestfs functions and certain heuristics to
4102 inspect the disk(s) (usually disks belonging to a virtual machine),
4103 looking for operating systems.
4104 The list returned is empty if no operating systems were found.
4106 If one operating system was found, then this returns a list with a
4108 single element, which is the name of the root filesystem of this
4109 operating system. It is also possible for this function to return a
4110 list containing more than one element, indicating a dual-boot or multi-
4111 boot virtual machine, with each element being the root filesystem of
4112 one of the operating systems.
4113 You can pass the root string(s) returned to other "inspect-get-*"
4115 functions in order to query further information about each operating
4116 system, such as the name and version.
4117 This function uses other libguestfs features such as "mount-ro" and
4119 "umount-all" in order to mount and unmount filesystems and look at the
4120 contents. This should be called with no disks currently mounted. The
4121 function may also use Augeas, so any existing Augeas handle will be
4122 closed.
4123 This function cannot decrypt encrypted disks. The caller must do that
4125 first (supplying the necessary keys) if the disk is encrypted.
4126 Please read "INSPECTION" in guestfs(3) for more details.
4128 See also "list-filesystems".
4130 is-blockdev
4132 is-blockdev path
4133 This returns "true" if and only if there is a block device with the
4135 given "path" name.
4136 See also "stat".
4138 is-busy
4140 is-busy
4141 This always returns false. This function is deprecated with no
4143 replacement. Do not use this function.
4144 For more information on states, see guestfs(3).
4146 is-chardev
4148 is-chardev path
4149 This returns "true" if and only if there is a character device with the
4151 given "path" name.
4152 See also "stat".
4154 is-config
4156 is-config
4157 This returns true iff this handle is being configured (in the "CONFIG"
4159 state).
4160 For more information on states, see guestfs(3).
4162 is-dir
4164 is-dir path
4165 This returns "true" if and only if there is a directory with the given
4167 "path" name. Note that it returns false for other objects like files.
4168 See also "stat".
4170 is-fifo
4172 is-fifo path
4173 This returns "true" if and only if there is a FIFO (named pipe) with
4175 the given "path" name.
4176 See also "stat".
4178 is-file
4180 is-file path
4181 This returns "true" if and only if there is a regular file with the
4183 given "path" name. Note that it returns false for other objects like
4184 directories.
4185 See also "stat".
4187 is-launching
4189 is-launching
4190 This returns true iff this handle is launching the subprocess (in the
4192 "LAUNCHING" state).
4193 For more information on states, see guestfs(3).
4195 is-lv
4197 is-lv device
4198 This command tests whether "device" is a logical volume, and returns
4200 true iff this is the case.
4201 is-ready
4203 is-ready
4204 This returns true iff this handle is ready to accept commands (in the
4206 "READY" state).
4207 For more information on states, see guestfs(3).
4209 is-socket
4211 is-socket path
4212 This returns "true" if and only if there is a Unix domain socket with
4214 the given "path" name.
4215 See also "stat".
4217 is-symlink
4219 is-symlink path
4220 This returns "true" if and only if there is a symbolic link with the
4222 given "path" name.
4223 See also "stat".
4225 is-zero
4227 is-zero path
4228 This returns true iff the file exists and the file is empty or it
4230 contains all zero bytes.
4231 is-zero-device
4233 is-zero-device device
4234 This returns true iff the device exists and contains all zero bytes.
4236 Note that for large devices this can take a long time to run.
4238 isoinfo
4240 isoinfo isofile
4241 This is the same as "isoinfo-device" except that it works for an ISO
4243 file located inside some other mounted filesystem. Note that in the
4244 common case where you have added an ISO file as a libguestfs device,
4245 you would not call this. Instead you would call "isoinfo-device".
4246 isoinfo-device
4248 isoinfo-device device
4249 "device" is an ISO device. This returns a struct of information read
4251 from the primary volume descriptor (the ISO equivalent of the
4252 superblock) of the device.
4253 Usually it is more efficient to use the isoinfo(1) command with the -d
4255 option on the host to analyze ISO files, instead of going through
4256 libguestfs.
4257 For information on the primary volume descriptor fields, see
4259 http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
4260 kill-subprocess
4262 kill-subprocess
4263 This kills the qemu subprocess.
4265 Do not call this. See: "shutdown" instead.
4267 This function is deprecated. In new code, use the "shutdown" call
4269 instead.
4270 Deprecated functions will not be removed from the API, but the fact
4272 that they are deprecated indicates that there are problems with correct
4273 use of these functions.
4274 launch
4276 run
4277 launch
4278 Internally libguestfs is implemented by running a virtual machine using
4280 qemu(1).
4281 You should call this after configuring the handle (eg. adding drives)
4283 but before performing any actions.
4284 Do not call "launch" twice on the same handle. Although it will not
4286 give an error (for historical reasons), the precise behaviour when you
4287 do this is not well defined. Handles are very cheap to create, so
4288 create a new one for each launch.
4289 lchown
4291 lchown owner group path
4292 Change the file owner to "owner" and group to "group". This is like
4294 "chown" but if "path" is a symlink then the link itself is changed, not
4295 the target.
4296 Only numeric uid and gid are supported. If you want to use names, you
4298 will need to locate and parse the password file yourself (Augeas
4299 support makes this relatively easy).
4300 ldmtool-create-all
4302 ldmtool-create-all
4303 This function scans all block devices looking for Windows dynamic disk
4305 volumes and partitions, and creates devices for any that were found.
4306 Call "list-ldm-volumes" and "list-ldm-partitions" to return all
4308 devices.
4309 Note that you don't normally need to call this explicitly, since it is
4311 done automatically at "launch" time. However you might want to call
4312 this function if you have hotplugged disks or have just created a
4313 Windows dynamic disk.
4314 ldmtool-diskgroup-disks
4316 ldmtool-diskgroup-disks diskgroup
4317 Return the disks in a Windows dynamic disk group. The "diskgroup"
4319 parameter should be the GUID of a disk group, one element from the list
4320 returned by "ldmtool-scan".
4321 ldmtool-diskgroup-name
4323 ldmtool-diskgroup-name diskgroup
4324 Return the name of a Windows dynamic disk group. The "diskgroup"
4326 parameter should be the GUID of a disk group, one element from the list
4327 returned by "ldmtool-scan".
4328 ldmtool-diskgroup-volumes
4330 ldmtool-diskgroup-volumes diskgroup
4331 Return the volumes in a Windows dynamic disk group. The "diskgroup"
4333 parameter should be the GUID of a disk group, one element from the list
4334 returned by "ldmtool-scan".
4335 ldmtool-remove-all
4337 ldmtool-remove-all
4338 This is essentially the opposite of "ldmtool-create-all". It removes
4340 the device mapper mappings for all Windows dynamic disk volumes
4341 ldmtool-scan
4343 ldmtool-scan
4344 This function scans for Windows dynamic disks. It returns a list of
4346 identifiers (GUIDs) for all disk groups that were found. These
4347 identifiers can be passed to other "ldmtool-*" functions.
4348 This function scans all block devices. To scan a subset of block
4350 devices, call "ldmtool-scan-devices" instead.
4351 ldmtool-scan-devices
4353 ldmtool-scan-devices 'devices ...'
4354 This function scans for Windows dynamic disks. It returns a list of
4356 identifiers (GUIDs) for all disk groups that were found. These
4357 identifiers can be passed to other "ldmtool-*" functions.
4358 The parameter "devices" is a list of block devices which are scanned.
4360 If this list is empty, all block devices are scanned.
4361 ldmtool-volume-hint
4363 ldmtool-volume-hint diskgroup volume
4364 Return the hint field of the volume named "volume" in the disk group
4366 with GUID "diskgroup". This may not be defined, in which case the
4367 empty string is returned. The hint field is often, though not always,
4368 the name of a Windows drive, eg. "E:".
4369 ldmtool-volume-partitions
4371 ldmtool-volume-partitions diskgroup volume
4372 Return the list of partitions in the volume named "volume" in the disk
4374 group with GUID "diskgroup".
4375 ldmtool-volume-type
4377 ldmtool-volume-type diskgroup volume
4378 Return the type of the volume named "volume" in the disk group with
4380 GUID "diskgroup".
4381 Possible volume types that can be returned here include: "simple",
4383 "spanned", "striped", "mirrored", "raid5". Other types may also be
4384 returned.
4385 lgetxattr
4387 lgetxattr path name
4388 Get a single extended attribute from file "path" named "name". If
4390 "path" is a symlink, then this call returns an extended attribute from
4391 the symlink.
4392 Normally it is better to get all extended attributes from a file in one
4394 go by calling "getxattrs". However some Linux filesystem
4395 implementations are buggy and do not provide a way to list out
4396 attributes. For these filesystems (notably ntfs-3g) you have to know
4397 the names of the extended attributes you want in advance and call this
4398 function.
4399 Extended attribute values are blobs of binary data. If there is no
4401 extended attribute named "name", this returns an error.
4402 See also: "lgetxattrs", "getxattr", attr(5).
4404 lgetxattrs
4406 lgetxattrs path
4407 This is the same as "getxattrs", but if "path" is a symbolic link, then
4409 it returns the extended attributes of the link itself.
4410 list-devices
4412 list-devices
4413 List all the block devices.
4415 The full block device names are returned, eg. "/dev/sda".
4417 See also "list-filesystems".
4419 list-disk-labels
4421 list-disk-labels
4422 If you add drives using the optional "label" parameter of "add-drive-
4424 opts", you can use this call to map between disk labels, and raw block
4425 device and partition names (like "/dev/sda" and "/dev/sda1").
4426 This returns a hashtable, where keys are the disk labels (without the
4428 "/dev/disk/guestfs" prefix), and the values are the full raw block
4429 device and partition names (eg. "/dev/sda" and "/dev/sda1").
4430 list-dm-devices
4432 list-dm-devices
4433 List all device mapper devices.
4435 The returned list contains "/dev/mapper/*" devices, eg. ones created by
4437 a previous call to "luks-open".
4438 Device mapper devices which correspond to logical volumes are not
4440 returned in this list. Call "lvs" if you want to list logical volumes.
4441 list-filesystems
4443 list-filesystems
4444 This inspection command looks for filesystems on partitions, block
4446 devices and logical volumes, returning a list of devices containing
4447 filesystems and their type.
4448 The return value is a hash, where the keys are the devices containing
4450 filesystems, and the values are the filesystem types. For example:
4451 "/dev/sda1" => "ntfs"
4453 "/dev/sda2" => "ext2"
4454 "/dev/vg_guest/lv_root" => "ext4"
4455 "/dev/vg_guest/lv_swap" => "swap"
4456 The value can have the special value "unknown", meaning the content of
4458 the device is undetermined or empty. "swap" means a Linux swap
4459 partition.
4460 This command runs other libguestfs commands, which might include
4462 "mount" and "umount", and therefore you should use this soon after
4463 launch and only when nothing is mounted.
4464 Not all of the filesystems returned will be mountable. In particular,
4466 swap partitions are returned in the list. Also this command does not
4467 check that each filesystem found is valid and mountable, and some
4468 filesystems might be mountable but require special options.
4469 Filesystems may not all belong to a single logical operating system
4470 (use "inspect-os" to look for OSes).
4471 list-ldm-partitions
4473 list-ldm-partitions
4474 This function returns all Windows dynamic disk partitions that were
4476 found at launch time. It returns a list of device names.
4477 list-ldm-volumes
4479 list-ldm-volumes
4480 This function returns all Windows dynamic disk volumes that were found
4482 at launch time. It returns a list of device names.
4483 list-md-devices
4485 list-md-devices
4486 List all Linux md devices.
4488 list-partitions
4490 list-partitions
4491 List all the partitions detected on all block devices.
4493 The full partition device names are returned, eg. "/dev/sda1"
4495 This does not return logical volumes. For that you will need to call
4497 "lvs".
4498 See also "list-filesystems".
4500 ll
4502 ll directory
4503 List the files in "directory" (relative to the root directory, there is
4505 no cwd) in the format of 'ls -la'.
4506 This command is mostly useful for interactive sessions. It is not
4508 intended that you try to parse the output string.
4509 llz
4511 llz directory
4512 List the files in "directory" in the format of 'ls -laZ'.
4514 This command is mostly useful for interactive sessions. It is not
4516 intended that you try to parse the output string.
4517 ln
4519 ln target linkname
4520 This command creates a hard link using the "ln" command.
4522 ln-f
4524 ln-f target linkname
4525 This command creates a hard link using the "ln -f" command. The -f
4527 option removes the link ("linkname") if it exists already.
4528 ln-s
4530 ln-s target linkname
4531 This command creates a symbolic link using the "ln -s" command.
4533 ln-sf
4535 ln-sf target linkname
4536 This command creates a symbolic link using the "ln -sf" command, The -f
4538 option removes the link ("linkname") if it exists already.
4539 lremovexattr
4541 lremovexattr xattr path
4542 This is the same as "removexattr", but if "path" is a symbolic link,
4544 then it removes an extended attribute of the link itself.
4545 ls
4547 ls directory
4548 List the files in "directory" (relative to the root directory, there is
4550 no cwd). The '.' and '..' entries are not returned, but hidden files
4551 are shown.
4552 ls0
4554 ls0 dir (filenames|-)
4555 This specialized command is used to get a listing of the filenames in
4557 the directory "dir". The list of filenames is written to the local
4558 file "filenames" (on the host).
4559 In the output file, the filenames are separated by "\0" characters.
4561 "." and ".." are not returned. The filenames are not sorted.
4563 Use "-" instead of a filename to read/write from stdin/stdout.
4565 lsetxattr
4567 lsetxattr xattr val vallen path
4568 This is the same as "setxattr", but if "path" is a symbolic link, then
4570 it sets an extended attribute of the link itself.
4571 lstat
4573 lstat path
4574 Returns file information for the given "path".
4576 This is the same as "stat" except that if "path" is a symbolic link,
4578 then the link is stat-ed, not the file it refers to.
4579 This is the same as the lstat(2) system call.
4581 lstatlist
4583 lstatlist path 'names ...'
4584 This call allows you to perform the "lstat" operation on multiple
4586 files, where all files are in the directory "path". "names" is the
4587 list of files from this directory.
4588 On return you get a list of stat structs, with a one-to-one
4590 correspondence to the "names" list. If any name did not exist or could
4591 not be lstat'd, then the "ino" field of that structure is set to "-1".
4592 This call is intended for programs that want to efficiently list a
4594 directory contents without making many round-trips. See also
4595 "lxattrlist" for a similarly efficient call for getting extended
4596 attributes.
4597 luks-add-key
4599 luks-add-key device keyslot
4600 This command adds a new key on LUKS device "device". "key" is any
4602 existing key, and is used to access the device. "newkey" is the new
4603 key to add. "keyslot" is the key slot that will be replaced.
4604 Note that if "keyslot" already contains a key, then this command will
4606 fail. You have to use "luks-kill-slot" first to remove that key.
4607 This command has one or more key or passphrase parameters. Guestfish
4609 will prompt for these separately.
4610 luks-close
4612 luks-close device
4613 This closes a LUKS device that was created earlier by "luks-open" or
4615 "luks-open-ro". The "device" parameter must be the name of the LUKS
4616 mapping device (ie. "/dev/mapper/mapname") and not the name of the
4617 underlying block device.
4618 luks-format
4620 luks-format device keyslot
4621 This command erases existing data on "device" and formats the device as
4623 a LUKS encrypted device. "key" is the initial key, which is added to
4624 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
4625 This command has one or more key or passphrase parameters. Guestfish
4627 will prompt for these separately.
4628 luks-format-cipher
4630 luks-format-cipher device keyslot cipher
4631 This command is the same as "luks-format" but it also allows you to set
4633 the "cipher" used.
4634 This command has one or more key or passphrase parameters. Guestfish
4636 will prompt for these separately.
4637 luks-kill-slot
4639 luks-kill-slot device keyslot
4640 This command deletes the key in key slot "keyslot" from the encrypted
4642 LUKS device "device". "key" must be one of the other keys.
4643 This command has one or more key or passphrase parameters. Guestfish
4645 will prompt for these separately.
4646 luks-open
4648 luks-open device mapname
4649 This command opens a block device which has been encrypted according to
4651 the Linux Unified Key Setup (LUKS) standard.
4652 "device" is the encrypted block device or partition.
4654 The caller must supply one of the keys associated with the LUKS block
4656 device, in the "key" parameter.
4657 This creates a new block device called "/dev/mapper/mapname". Reads
4659 and writes to this block device are decrypted from and encrypted to the
4660 underlying "device" respectively.
4661 If this block device contains LVM volume groups, then calling "vgscan"
4663 followed by "vg-activate-all" will make them visible.
4664 Use "list-dm-devices" to list all device mapper devices.
4666 This command has one or more key or passphrase parameters. Guestfish
4668 will prompt for these separately.
4669 luks-open-ro
4671 luks-open-ro device mapname
4672 This is the same as "luks-open" except that a read-only mapping is
4674 created.
4675 This command has one or more key or passphrase parameters. Guestfish
4677 will prompt for these separately.
4678 lvcreate
4680 lvcreate logvol volgroup mbytes
4681 This creates an LVM logical volume called "logvol" on the volume group
4683 "volgroup", with "size" megabytes.
4684 lvcreate-free
4686 lvcreate-free logvol volgroup percent
4687 Create an LVM logical volume called "/dev/volgroup/logvol", using
4689 approximately "percent" % of the free space remaining in the volume
4690 group. Most usefully, when "percent" is 100 this will create the
4691 largest possible LV.
4692 lvm-canonical-lv-name
4694 lvm-canonical-lv-name lvname
4695 This converts alternative naming schemes for LVs that you might find to
4697 the canonical name. For example, "/dev/mapper/VG-LV" is converted to
4698 "/dev/VG/LV".
4699 This command returns an error if the "lvname" parameter does not refer
4701 to a logical volume.
4702 See also "is-lv", "canonical-device-name".
4704 lvm-clear-filter
4706 lvm-clear-filter
4707 This undoes the effect of "lvm-set-filter". LVM will be able to see
4709 every block device.
4710 This command also clears the LVM cache and performs a volume group
4712 scan.
4713 lvm-remove-all
4715 lvm-remove-all
4716 This command removes all LVM logical volumes, volume groups and
4718 physical volumes.
4719 lvm-set-filter
4721 lvm-set-filter 'devices ...'
4722 This sets the LVM device filter so that LVM will only be able to "see"
4724 the block devices in the list "devices", and will ignore all other
4725 attached block devices.
4726 Where disk image(s) contain duplicate PVs or VGs, this command is
4728 useful to get LVM to ignore the duplicates, otherwise LVM can get
4729 confused. Note also there are two types of duplication possible:
4730 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
4731 cloned but just happen to have the same name. In normal operation you
4732 cannot create this situation, but you can do it outside LVM, eg. by
4733 cloning disk images or by bit twiddling inside the LVM metadata.
4734 This command also clears the LVM cache and performs a volume group
4736 scan.
4737 You can filter whole block devices or individual partitions.
4739 You cannot use this if any VG is currently in use (eg. contains a
4741 mounted filesystem), even if you are not filtering out that VG.
4742 lvremove
4744 lvremove device
4745 Remove an LVM logical volume "device", where "device" is the path to
4747 the LV, such as "/dev/VG/LV".
4748 You can also remove all LVs in a volume group by specifying the VG
4750 name, "/dev/VG".
4751 lvrename
4753 lvrename logvol newlogvol
4754 Rename a logical volume "logvol" with the new name "newlogvol".
4756 lvresize
4758 lvresize device mbytes
4759 This resizes (expands or shrinks) an existing LVM logical volume to
4761 "mbytes". When reducing, data in the reduced part is lost.
4762 lvresize-free
4764 lvresize-free lv percent
4765 This expands an existing logical volume "lv" so that it fills "pc"% of
4767 the remaining free space in the volume group. Commonly you would call
4768 this with pc = 100 which expands the logical volume as much as
4769 possible, using all remaining free space in the volume group.
4770 lvs
4772 lvs
4773 List all the logical volumes detected. This is the equivalent of the
4775 lvs(8) command.
4776 This returns a list of the logical volume device names (eg.
4778 "/dev/VolGroup00/LogVol00").
4779 See also "lvs-full", "list-filesystems".
4781 lvs-full
4783 lvs-full
4784 List all the logical volumes detected. This is the equivalent of the
4786 lvs(8) command. The "full" version includes all fields.
4787 lvuuid
4789 lvuuid device
4790 This command returns the UUID of the LVM LV "device".
4792 lxattrlist
4794 lxattrlist path 'names ...'
4795 This call allows you to get the extended attributes of multiple files,
4797 where all files are in the directory "path". "names" is the list of
4798 files from this directory.
4799 On return you get a flat list of xattr structs which must be
4801 interpreted sequentially. The first xattr struct always has a zero-
4802 length "attrname". "attrval" in this struct is zero-length to indicate
4803 there was an error doing "lgetxattr" for this file, or is a C string
4804 which is a decimal number (the number of following attributes for this
4805 file, which could be "0"). Then after the first xattr struct are the
4806 zero or more attributes for the first named file. This repeats for the
4807 second and subsequent files.
4808 This call is intended for programs that want to efficiently list a
4810 directory contents without making many round-trips. See also
4811 "lstatlist" for a similarly efficient call for getting standard stats.
4812 max-disks
4814 max-disks
4815 Return the maximum number of disks that may be added to a handle (eg.
4817 by "add-drive-opts" and similar calls).
4818 This function was added in libguestfs 1.19.7. In previous versions of
4820 libguestfs the limit was 25.
4821 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
4823 on this topic.
4824 md-create
4826 md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
4827 Create a Linux md (RAID) device named "name" on the devices in the list
4829 "devices".
4830 The optional parameters are:
4832 "missingbitmap"
4834 A bitmap of missing devices. If a bit is set it means that a
4835 missing device is added to the array. The least significant bit
4836 corresponds to the first device in the array.
4837 As examples:
4839 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
4841 resulting array would be "[<missing>, "/dev/sda"]".
4842 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
4844 resulting array would be "["/dev/sda", <missing>]".
4845 This defaults to 0 (no missing devices).
4847 The length of "devices" + the number of bits set in "missingbitmap"
4849 must equal "nrdevices" + "spare".
4850 "nrdevices"
4852 The number of active RAID devices.
4853 If not set, this defaults to the length of "devices" plus the
4855 number of bits set in "missingbitmap".
4856 "spare"
4858 The number of spare devices.
4859 If not set, this defaults to 0.
4861 "chunk"
4863 The chunk size in bytes.
4864 "level"
4866 The RAID level, which can be one of: linear, raid0, 0, stripe,
4867 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some
4868 of these are synonymous, and more levels may be added in future.
4869 If not set, this defaults to "raid1".
4871 This command has one or more optional arguments. See "OPTIONAL
4873 ARGUMENTS".
4874 md-detail
4876 md-detail md
4877 This command exposes the output of 'mdadm -DY <md>'. The following
4879 fields are usually present in the returned hash. Other fields may also
4880 be present.
4881 "level"
4883 The raid level of the MD device.
4884 "devices"
4886 The number of underlying devices in the MD device.
4887 "metadata"
4889 The metadata version used.
4890 "uuid"
4892 The UUID of the MD device.
4893 "name"
4895 The name of the MD device.
4896 md-stat
4898 md-stat md
4899 This call returns a list of the underlying devices which make up the
4901 single software RAID array device "md".
4902 To get a list of software RAID devices, call "list-md-devices".
4904 Each structure returned corresponds to one device along with additional
4906 status information:
4907 "mdstat_device"
4909 The name of the underlying device.
4910 "mdstat_index"
4912 The index of this device within the array.
4913 "mdstat_flags"
4915 Flags associated with this device. This is a string containing (in
4916 no specific order) zero or more of the following flags:
4917 "W" write-mostly
4919 "F" device is faulty
4921 "S" device is a RAID spare
4923 "R" replacement
4925 md-stop
4927 md-stop md
4928 This command deactivates the MD array named "md". The device is
4930 stopped, but it is not destroyed or zeroed.
4931 mkdir
4933 mkdir path
4934 Create a directory named "path".
4936 mkdir-mode
4938 mkdir-mode path mode
4939 This command creates a directory, setting the initial permissions of
4941 the directory to "mode".
4942 For common Linux filesystems, the actual mode which is set will be
4944 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
4945 the mode in other ways.
4946 See also "mkdir", "umask"
4948 mkdir-p
4950 mkdir-p path
4951 Create a directory named "path", creating any parent directories as
4953 necessary. This is like the "mkdir -p" shell command.
4954 mkdtemp
4956 mkdtemp tmpl
4957 This command creates a temporary directory. The "tmpl" parameter
4959 should be a full pathname for the temporary directory name with the
4960 final six characters being "XXXXXX".
4961 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
4963 one being suitable for Windows filesystems.
4964 The name of the temporary directory that was created is returned.
4966 The temporary directory is created with mode 0700 and is owned by root.
4968 The caller is responsible for deleting the temporary directory and its
4970 contents after use.
4971 See also: mkdtemp(3)
4973 mke2fs
4975 mke2fs device [blockscount:N] [blocksize:N] [fragsize:N] [blockspergroup:N] [numberofgroups:N] [bytesperinode:N] [inodesize:N] [journalsize:N] [numberofinodes:N] [stridesize:N] [stripewidth:N] [maxonlineresize:N] [reservedblockspercentage:N] [mmpupdateinterval:N] [journaldevice:..] [label:..] [lastmounteddir:..] [creatoros:..] [fstype:..] [usagetype:..] [uuid:..] [forcecreate:true|false] [writesbandgrouponly:true|false] [lazyitableinit:true|false] [lazyjournalinit:true|false] [testfs:true|false] [discard:true|false] [quotatype:true|false] [extent:true|false] [filetype:true|false] [flexbg:true|false] [hasjournal:true|false] [journaldev:true|false] [largefile:true|false] [quota:true|false] [resizeinode:true|false] [sparsesuper:true|false] [uninitbg:true|false]
4976 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
4978 "device".
4979 The optional "blockscount" is the size of the filesystem in blocks. If
4981 omitted it defaults to the size of "device". Note if the filesystem is
4982 too small to contain a journal, "mke2fs" will silently create an ext2
4983 filesystem instead.
4984 This command has one or more optional arguments. See "OPTIONAL
4986 ARGUMENTS".
4987 mke2fs-J
4989 mke2fs-J fstype blocksize device journal
4990 This creates an ext2/3/4 filesystem on "device" with an external
4992 journal on "journal". It is equivalent to the command:
4993 mke2fs -t fstype -b blocksize -J device=<journal> <device>
4995 See also "mke2journal".
4997 This function is deprecated. In new code, use the "mke2fs" call
4999 instead.
5000 Deprecated functions will not be removed from the API, but the fact
5002 that they are deprecated indicates that there are problems with correct
5003 use of these functions.
5004 mke2fs-JL
5006 mke2fs-JL fstype blocksize device label
5007 This creates an ext2/3/4 filesystem on "device" with an external
5009 journal on the journal labeled "label".
5010 See also "mke2journal-L".
5012 This function is deprecated. In new code, use the "mke2fs" call
5014 instead.
5015 Deprecated functions will not be removed from the API, but the fact
5017 that they are deprecated indicates that there are problems with correct
5018 use of these functions.
5019 mke2fs-JU
5021 mke2fs-JU fstype blocksize device uuid
5022 This creates an ext2/3/4 filesystem on "device" with an external
5024 journal on the journal with UUID "uuid".
5025 See also "mke2journal-U".
5027 This function is deprecated. In new code, use the "mke2fs" call
5029 instead.
5030 Deprecated functions will not be removed from the API, but the fact
5032 that they are deprecated indicates that there are problems with correct
5033 use of these functions.
5034 mke2journal
5036 mke2journal blocksize device
5037 This creates an ext2 external journal on "device". It is equivalent to
5039 the command:
5040 mke2fs -O journal_dev -b blocksize device
5042 This function is deprecated. In new code, use the "mke2fs" call
5044 instead.
5045 Deprecated functions will not be removed from the API, but the fact
5047 that they are deprecated indicates that there are problems with correct
5048 use of these functions.
5049 mke2journal-L
5051 mke2journal-L blocksize label device
5052 This creates an ext2 external journal on "device" with label "label".
5054 This function is deprecated. In new code, use the "mke2fs" call
5056 instead.
5057 Deprecated functions will not be removed from the API, but the fact
5059 that they are deprecated indicates that there are problems with correct
5060 use of these functions.
5061 mke2journal-U
5063 mke2journal-U blocksize uuid device
5064 This creates an ext2 external journal on "device" with UUID "uuid".
5066 This function is deprecated. In new code, use the "mke2fs" call
5068 instead.
5069 Deprecated functions will not be removed from the API, but the fact
5071 that they are deprecated indicates that there are problems with correct
5072 use of these functions.
5073 mkfifo
5075 mkfifo mode path
5076 This call creates a FIFO (named pipe) called "path" with mode "mode".
5078 It is just a convenient wrapper around "mknod".
5079 The mode actually set is affected by the umask.
5081 mkfs
5083 mkfs-opts
5084 mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N]
5085 This function creates a filesystem on "device". The filesystem type is
5087 "fstype", for example "ext3".
5088 The optional arguments are:
5090 "blocksize"
5092 The filesystem block size. Supported block sizes depend on the
5093 filesystem type, but typically they are 1024, 2048 or 4096 for
5094 Linux ext2/3 filesystems.
5095 For VFAT and NTFS the "blocksize" parameter is treated as the
5097 requested cluster size.
5098 For UFS block sizes, please see mkfs.ufs(8).
5100 "features"
5102 This passes the -O parameter to the external mkfs program.
5103 For certain filesystem types, this allows extra filesystem features
5105 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
5106 You cannot use this optional parameter with the "gfs" or "gfs2"
5108 filesystem type.
5109 "inode"
5111 This passes the -I parameter to the external mke2fs(8) program
5112 which sets the inode size (only for ext2/3/4 filesystems at
5113 present).
5114 "sectorsize"
5116 This passes the -S parameter to external mkfs.ufs(8) program, which
5117 sets sector size for ufs filesystem.
5118 This command has one or more optional arguments. See "OPTIONAL
5120 ARGUMENTS".
5121 mkfs-b
5123 mkfs-b fstype blocksize device
5124 This call is similar to "mkfs", but it allows you to control the block
5126 size of the resulting filesystem. Supported block sizes depend on the
5127 filesystem type, but typically they are 1024, 2048 or 4096 only.
5128 For VFAT and NTFS the "blocksize" parameter is treated as the requested
5130 cluster size.
5131 This function is deprecated. In new code, use the "mkfs" call instead.
5133 Deprecated functions will not be removed from the API, but the fact
5135 that they are deprecated indicates that there are problems with correct
5136 use of these functions.
5137 mkfs-btrfs
5139 mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]
5140 Create a btrfs filesystem, allowing all configurables to be set. For
5142 more information on the optional arguments, see mkfs.btrfs(8).
5143 Since btrfs filesystems can span multiple devices, this takes a non-
5145 empty list of devices.
5146 To create general filesystems, use "mkfs".
5148 This command has one or more optional arguments. See "OPTIONAL
5150 ARGUMENTS".
5151 mklost-and-found
5153 mklost-and-found mountpoint
5154 Make the "lost+found" directory, normally in the root directory of an
5156 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
5157 to create the "lost+found" directory.
5158 mkmountpoint
5160 mkmountpoint exemptpath
5161 "mkmountpoint" and "rmmountpoint" are specialized calls that can be
5163 used to create extra mountpoints before mounting the first filesystem.
5164 These calls are only necessary in some very limited circumstances,
5166 mainly the case where you want to mount a mix of unrelated and/or read-
5167 only filesystems together.
5168 For example, live CDs often contain a "Russian doll" nest of
5170 filesystems, an ISO outer layer, with a squashfs image inside, with an
5171 ext2/3 image inside that. You can unpack this as follows in guestfish:
5172 add-ro Fedora-11-i686-Live.iso
5174 run
5175 mkmountpoint /cd
5176 mkmountpoint /sqsh
5177 mkmountpoint /ext3fs
5178 mount /dev/sda /cd
5179 mount-loop /cd/LiveOS/squashfs.img /sqsh
5180 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
5181 The inner filesystem is now unpacked under the /ext3fs mountpoint.
5183 "mkmountpoint" is not compatible with "umount-all". You may get
5185 unexpected errors if you try to mix these calls. It is safest to
5186 manually unmount filesystems and remove mountpoints after use.
5187 "umount-all" unmounts filesystems by sorting the paths longest first,
5189 so for this to work for manual mountpoints, you must ensure that the
5190 innermost mountpoints have the longest pathnames, as in the example
5191 code above.
5192 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
5194 Autosync [see "set-autosync", this is set by default on handles] can
5196 cause "umount-all" to be called when the handle is closed which can
5197 also trigger these issues.
5198 mknod
5200 mknod mode devmajor devminor path
5201 This call creates block or character special devices, or named pipes
5203 (FIFOs).
5204 The "mode" parameter should be the mode, using the standard constants.
5206 "devmajor" and "devminor" are the device major and minor numbers, only
5207 used when creating block and character special devices.
5208 Note that, just like mknod(2), the mode must be bitwise OR'd with
5210 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
5211 a regular file). These constants are available in the standard Linux
5212 header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
5213 wrappers around this command which bitwise OR in the appropriate
5214 constant for you.
5215 The mode actually set is affected by the umask.
5217 mknod-b
5219 mknod-b mode devmajor devminor path
5220 This call creates a block device node called "path" with mode "mode"
5222 and device major/minor "devmajor" and "devminor". It is just a
5223 convenient wrapper around "mknod".
5224 The mode actually set is affected by the umask.
5226 mknod-c
5228 mknod-c mode devmajor devminor path
5229 This call creates a char device node called "path" with mode "mode" and
5231 device major/minor "devmajor" and "devminor". It is just a convenient
5232 wrapper around "mknod".
5233 The mode actually set is affected by the umask.
5235 mkswap
5237 mkswap-opts
5238 mkswap device [label:..] [uuid:..]
5239 Create a Linux swap partition on "device".
5241 The option arguments "label" and "uuid" allow you to set the label
5243 and/or UUID of the new swap partition.
5244 This command has one or more optional arguments. See "OPTIONAL
5246 ARGUMENTS".
5247 mkswap-L
5249 mkswap-L label device
5250 Create a swap partition on "device" with label "label".
5252 Note that you cannot attach a swap label to a block device (eg.
5254 "/dev/sda"), just to a partition. This appears to be a limitation of
5255 the kernel or swap tools.
5256 This function is deprecated. In new code, use the "mkswap" call
5258 instead.
5259 Deprecated functions will not be removed from the API, but the fact
5261 that they are deprecated indicates that there are problems with correct
5262 use of these functions.
5263 mkswap-U
5265 mkswap-U uuid device
5266 Create a swap partition on "device" with UUID "uuid".
5268 This function is deprecated. In new code, use the "mkswap" call
5270 instead.
5271 Deprecated functions will not be removed from the API, but the fact
5273 that they are deprecated indicates that there are problems with correct
5274 use of these functions.
5275 mkswap-file
5277 mkswap-file path
5278 Create a swap file.
5280 This command just writes a swap file signature to an existing file. To
5282 create the file itself, use something like "fallocate".
5283 mktemp
5285 mktemp tmpl [suffix:..]
5286 This command creates a temporary file. The "tmpl" parameter should be
5288 a full pathname for the temporary directory name with the final six
5289 characters being "XXXXXX".
5290 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
5292 one being suitable for Windows filesystems.
5293 The name of the temporary file that was created is returned.
5295 The temporary file is created with mode 0600 and is owned by root.
5297 The caller is responsible for deleting the temporary file after use.
5299 If the optional "suffix" parameter is given, then the suffix (eg.
5301 ".txt") is appended to the temporary name.
5302 See also: "mkdtemp".
5304 This command has one or more optional arguments. See "OPTIONAL
5306 ARGUMENTS".
5307 modprobe
5309 modprobe modulename
5310 This loads a kernel module in the appliance.
5312 The kernel module must have been whitelisted when libguestfs was built
5314 (see "appliance/kmod.whitelist.in" in the source).
5315 mount
5317 mount device mountpoint
5318 Mount a guest disk at a position in the filesystem. Block devices are
5320 named "/dev/sda", "/dev/sdb" and so on, as they were added to the
5321 guest. If those block devices contain partitions, they will have the
5322 usual names (eg. "/dev/sda1"). Also LVM "/dev/VG/LV"-style names can
5323 be used.
5324 The rules are the same as for mount(2): A filesystem must first be
5326 mounted on "/" before others can be mounted. Other filesystems can
5327 only be mounted on directories which already exist.
5328 The mounted filesystem is writable, if we have sufficient permissions
5330 on the underlying device.
5331 Before libguestfs 1.13.16, this call implicitly added the options
5333 "sync" and "noatime". The "sync" option greatly slowed writes and
5334 caused many problems for users. If your program might need to work
5335 with older versions of libguestfs, use "mount-options" instead (using
5336 an empty string for the first parameter if you don't want any options).
5337 mount-local
5339 mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
5340 This call exports the libguestfs-accessible filesystem to a local
5342 mountpoint (directory) called "localmountpoint". Ordinary reads and
5343 writes to files and directories under "localmountpoint" are redirected
5344 through libguestfs.
5345 If the optional "readonly" flag is set to true, then writes to the
5347 filesystem return error "EROFS".
5348 "options" is a comma-separated list of mount options. See
5350 guestmount(1) for some useful options.
5351 "cachetimeout" sets the timeout (in seconds) for cached directory
5353 entries. The default is 60 seconds. See guestmount(1) for further
5354 information.
5355 If "debugcalls" is set to true, then additional debugging information
5357 is generated for every FUSE call.
5358 When "mount-local" returns, the filesystem is ready, but is not
5360 processing requests (access to it will block). You have to call
5361 "mount-local-run" to run the main loop.
5362 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5364 This command has one or more optional arguments. See "OPTIONAL
5366 ARGUMENTS".
5367 mount-local-run
5369 mount-local-run
5370 Run the main loop which translates kernel calls to libguestfs calls.
5372 This should only be called after "mount-local" returns successfully.
5374 The call will not return until the filesystem is unmounted.
5375 Note you must not make concurrent libguestfs calls on the same handle
5377 from another thread.
5378 You may call this from a different thread than the one which called
5380 "mount-local", subject to the usual rules for threads and libguestfs
5381 (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
5382 See "MOUNT LOCAL" in guestfs(3) for full documentation.
5384 mount-loop
5386 mount-loop file mountpoint
5387 This command lets you mount "file" (a filesystem image in a file) on a
5389 mount point. It is entirely equivalent to the command "mount -o loop
5390 file mountpoint".
5391 mount-options
5393 mount-options options device mountpoint
5394 This is the same as the "mount" command, but it allows you to set the
5396 mount options as for the mount(8) -o flag.
5397 If the "options" parameter is an empty string, then no options are
5399 passed (all options default to whatever the filesystem uses).
5400 mount-ro
5402 mount-ro device mountpoint
5403 This is the same as the "mount" command, but it mounts the filesystem
5405 with the read-only (-o ro) flag.
5406 mount-vfs
5408 mount-vfs options vfstype device mountpoint
5409 This is the same as the "mount" command, but it allows you to set both
5411 the mount options and the vfstype as for the mount(8) -o and -t flags.
5412 mountpoints
5414 mountpoints
5415 This call is similar to "mounts". That call returns a list of devices.
5417 This one returns a hash table (map) of device name to directory where
5418 the device is mounted.
5419 mounts
5421 mounts
5422 This returns the list of currently mounted filesystems. It returns the
5424 list of devices (eg. "/dev/sda1", "/dev/VG/LV").
5425 Some internal mounts are not shown.
5427 See also: "mountpoints"
5429 mv
5431 mv src dest
5432 This moves a file from "src" to "dest" where "dest" is either a
5434 destination filename or destination directory.
5435 See also: "rename".
5437 nr-devices
5439 nr-devices
5440 This returns the number of whole block devices that were added. This
5442 is the same as the number of devices that would be returned if you
5443 called "list-devices".
5444 To find out the maximum number of devices that could be added, call
5446 "max-disks".
5447 ntfs-3g-probe
5449 ntfs-3g-probe true|false device
5450 This command runs the ntfs-3g.probe(8) command which probes an NTFS
5452 "device" for mountability. (Not all NTFS volumes can be mounted read-
5453 write, and some cannot be mounted at all).
5454 "rw" is a boolean flag. Set it to true if you want to test if the
5456 volume can be mounted read-write. Set it to false if you want to test
5457 if the volume can be mounted read-only.
5458 The return value is an integer which 0 if the operation would succeed,
5460 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
5461 ntfsclone-in
5463 ntfsclone-in (backupfile|-) device
5464 Restore the "backupfile" (from a previous call to "ntfsclone-out") to
5466 "device", overwriting any existing contents of this device.
5467 Use "-" instead of a filename to read/write from stdin/stdout.
5469 ntfsclone-out
5471 ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
5472 Stream the NTFS filesystem "device" to the local file "backupfile".
5474 The format used for the backup file is a special format used by the
5475 ntfsclone(8) tool.
5476 If the optional "metadataonly" flag is true, then only the metadata is
5478 saved, losing all the user data (this is useful for diagnosing some
5479 filesystem problems).
5480 The optional "rescue", "ignorefscheck", "preservetimestamps" and
5482 "force" flags have precise meanings detailed in the ntfsclone(8) man
5483 page.
5484 Use "ntfsclone-in" to restore the file back to a libguestfs device.
5486 Use "-" instead of a filename to read/write from stdin/stdout.
5488 This command has one or more optional arguments. See "OPTIONAL
5490 ARGUMENTS".
5491 ntfsfix
5493 ntfsfix device [clearbadsectors:true|false]
5494 This command repairs some fundamental NTFS inconsistencies, resets the
5496 NTFS journal file, and schedules an NTFS consistency check for the
5497 first boot into Windows.
5498 This is not an equivalent of Windows "chkdsk". It does not scan the
5500 filesystem for inconsistencies.
5501 The optional "clearbadsectors" flag clears the list of bad sectors.
5503 This is useful after cloning a disk with bad sectors to a new disk.
5504 This command has one or more optional arguments. See "OPTIONAL
5506 ARGUMENTS".
5507 ntfsresize
5509 ntfsresize-opts
5510 ntfsresize device [size:N] [force:true|false]
5511 This command resizes an NTFS filesystem, expanding or shrinking it to
5513 the size of the underlying device.
5514 The optional parameters are:
5516 "size"
5518 The new size (in bytes) of the filesystem. If omitted, the
5519 filesystem is resized to fit the container (eg. partition).
5520 "force"
5522 If this option is true, then force the resize of the filesystem
5523 even if the filesystem is marked as requiring a consistency check.
5524 After the resize operation, the filesystem is always marked as
5526 requiring a consistency check (for safety). You have to boot into
5527 Windows to perform this check and clear this condition. If you
5528 don't set the "force" option then it is not possible to call
5529 "ntfsresize" multiple times on a single filesystem without booting
5530 into Windows between each resize.
5531 See also ntfsresize(8).
5533 This command has one or more optional arguments. See "OPTIONAL
5535 ARGUMENTS".
5536 ntfsresize-size
5538 ntfsresize-size device size
5539 This command is the same as "ntfsresize" except that it allows you to
5541 specify the new size (in bytes) explicitly.
5542 This function is deprecated. In new code, use the "ntfsresize" call
5544 instead.
5545 Deprecated functions will not be removed from the API, but the fact
5547 that they are deprecated indicates that there are problems with correct
5548 use of these functions.
5549 parse-environment
5551 parse-environment
5552 Parse the program's environment and set flags in the handle
5554 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the 'verbose'
5555 flag is set in the handle.
5556 Most programs do not need to call this. It is done implicitly when you
5558 call "create".
5559 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
5561 variables that can affect libguestfs handles. See also
5562 "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
5563 parse-environment-list
5565 parse-environment-list 'environment ...'
5566 Parse the list of strings in the argument "environment" and set flags
5568 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
5569 string in the list, then the 'verbose' flag is set in the handle.
5570 This is the same as "parse-environment" except that it parses an
5572 explicit list of strings instead of the program's environment.
5573 part-add
5575 part-add device prlogex startsect endsect
5576 This command adds a partition to "device". If there is no partition
5578 table on the device, call "part-init" first.
5579 The "prlogex" parameter is the type of partition. Normally you should
5581 pass "p" or "primary" here, but MBR partition tables also support "l"
5582 (or "logical") and "e" (or "extended") partition types.
5583 "startsect" and "endsect" are the start and end of the partition in
5585 sectors. "endsect" may be negative, which means it counts backwards
5586 from the end of the disk ("-1" is the last sector).
5587 Creating a partition which covers the whole disk is not so easy. Use
5589 "part-disk" to do that.
5590 part-del
5592 part-del device partnum
5593 This command deletes the partition numbered "partnum" on "device".
5595 Note that in the case of MBR partitioning, deleting an extended
5597 partition also deletes any logical partitions it contains.
5598 part-disk
5600 part-disk device parttype
5601 This command is simply a combination of "part-init" followed by "part-
5603 add" to create a single primary partition covering the whole disk.
5604 "parttype" is the partition table type, usually "mbr" or "gpt", but
5606 other possible values are described in "part-init".
5607 part-get-bootable
5609 part-get-bootable device partnum
5610 This command returns true if the partition "partnum" on "device" has
5612 the bootable flag set.
5613 See also "part-set-bootable".
5615 part-get-gpt-type
5617 part-get-gpt-type device partnum
5618 Return the type GUID of numbered GPT partition "partnum". For MBR
5620 partitions, return an appropriate GUID corresponding to the MBR type.
5621 Behaviour is undefined for other partition types.
5622 part-get-mbr-id
5624 part-get-mbr-id device partnum
5625 Returns the MBR type byte (also known as the ID byte) from the numbered
5627 partition "partnum".
5628 Note that only MBR (old DOS-style) partitions have type bytes. You
5630 will get undefined results for other partition table types (see "part-
5631 get-parttype").
5632 part-get-parttype
5634 part-get-parttype device
5635 This command examines the partition table on "device" and returns the
5637 partition table type (format) being used.
5638 Common return values include: "msdos" (a DOS/Windows style MBR
5640 partition table), "gpt" (a GPT/EFI-style partition table). Other
5641 values are possible, although unusual. See "part-init" for a full
5642 list.
5643 part-init
5645 part-init device parttype
5646 This creates an empty partition table on "device" of one of the
5648 partition types listed below. Usually "parttype" should be either
5649 "msdos" or "gpt" (for large disks).
5650 Initially there are no partitions. Following this, you should call
5652 "part-add" for each partition required.
5653 Possible values for "parttype" are:
5655 efi
5657 gpt Intel EFI / GPT partition table.
5658 This is recommended for >= 2 TB partitions that will be accessed
5660 from Linux and Intel-based Mac OS X. It also has limited backwards
5661 compatibility with the "mbr" format.
5662 mbr
5664 msdos
5665 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
5666 and Windows. This partition type will only work for device sizes
5667 up to 2 TB. For large disks we recommend using "gpt".
5668 Other partition table types that may work but are not supported
5670 include:
5671 aix AIX disk labels.
5673 amiga
5675 rdb Amiga "Rigid Disk Block" format.
5676 bsd BSD disk labels.
5678 dasd
5680 DASD, used on IBM mainframes.
5681 dvh MIPS/SGI volumes.
5683 mac Old Mac partition format. Modern Macs use "gpt".
5685 pc98
5687 NEC PC-98 format, common in Japan apparently.
5688 sun Sun disk labels.
5690 part-list
5692 part-list device
5693 This command parses the partition table on "device" and returns the
5695 list of partitions found.
5696 The fields in the returned structure are:
5698 part_num
5700 Partition number, counting from 1.
5701 part_start
5703 Start of the partition in bytes. To get sectors you have to divide
5704 by the device's sector size, see "blockdev-getss".
5705 part_end
5707 End of the partition in bytes.
5708 part_size
5710 Size of the partition in bytes.
5711 part-set-bootable
5713 part-set-bootable device partnum true|false
5714 This sets the bootable flag on partition numbered "partnum" on device
5716 "device". Note that partitions are numbered from 1.
5717 The bootable flag is used by some operating systems (notably Windows)
5719 to determine which partition to boot from. It is by no means
5720 universally recognized.
5721 part-set-gpt-type
5723 part-set-gpt-type device partnum guid
5724 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
5726 an error if the partition table of "device" isn't GPT, or if "guid" is
5727 not a valid GUID.
5728 See
5730 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
5731 for a useful list of type GUIDs.
5732 part-set-mbr-id
5734 part-set-mbr-id device partnum idbyte
5735 Sets the MBR type byte (also known as the ID byte) of the numbered
5737 partition "partnum" to "idbyte". Note that the type bytes quoted in
5738 most documentation are in fact hexadecimal numbers, but usually
5739 documented without any leading "0x" which might be confusing.
5740 Note that only MBR (old DOS-style) partitions have type bytes. You
5742 will get undefined results for other partition table types (see "part-
5743 get-parttype").
5744 part-set-name
5746 part-set-name device partnum name
5747 This sets the partition name on partition numbered "partnum" on device
5749 "device". Note that partitions are numbered from 1.
5750 The partition name can only be set on certain types of partition table.
5752 This works on "gpt" but not on "mbr" partitions.
5753 part-to-dev
5755 part-to-dev partition
5756 This function takes a partition name (eg. "/dev/sdb1") and removes the
5758 partition number, returning the device name (eg. "/dev/sdb").
5759 The named partition must exist, for example as a string returned from
5761 "list-partitions".
5762 See also "part-to-partnum", "device-index".
5764 part-to-partnum
5766 part-to-partnum partition
5767 This function takes a partition name (eg. "/dev/sdb1") and returns the
5769 partition number (eg. 1).
5770 The named partition must exist, for example as a string returned from
5772 "list-partitions".
5773 See also "part-to-dev".
5775 ping-daemon
5777 ping-daemon
5778 This is a test probe into the guestfs daemon running inside the qemu
5780 subprocess. Calling this function checks that the daemon responds to
5781 the ping message, without affecting the daemon or attached block
5782 device(s) in any other way.
5783 pread
5785 pread path count offset
5786 This command lets you read part of a file. It reads "count" bytes of
5788 the file, starting at "offset", from file "path".
5789 This may read fewer bytes than requested. For further details see the
5791 pread(2) system call.
5792 See also "pwrite", "pread-device".
5794 Because of the message protocol, there is a transfer limit of somewhere
5796 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5797 pread-device
5799 pread-device device count offset
5800 This command lets you read part of a block device. It reads "count"
5802 bytes of "device", starting at "offset".
5803 This may read fewer bytes than requested. For further details see the
5805 pread(2) system call.
5806 See also "pread".
5808 Because of the message protocol, there is a transfer limit of somewhere
5810 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5811 pvchange-uuid
5813 pvchange-uuid device
5814 Generate a new random UUID for the physical volume "device".
5816 pvchange-uuid-all
5818 pvchange-uuid-all
5819 Generate new random UUIDs for all physical volumes.
5821 pvcreate
5823 pvcreate device
5824 This creates an LVM physical volume on the named "device", where
5826 "device" should usually be a partition name such as "/dev/sda1".
5827 pvremove
5829 pvremove device
5830 This wipes a physical volume "device" so that LVM will no longer
5832 recognise it.
5833 The implementation uses the "pvremove" command which refuses to wipe
5835 physical volumes that contain any volume groups, so you have to remove
5836 those first.
5837 pvresize
5839 pvresize device
5840 This resizes (expands or shrinks) an existing LVM physical volume to
5842 match the new size of the underlying device.
5843 pvresize-size
5845 pvresize-size device size
5846 This command is the same as "pvresize" except that it allows you to
5848 specify the new size (in bytes) explicitly.
5849 pvs
5851 pvs
5852 List all the physical volumes detected. This is the equivalent of the
5854 pvs(8) command.
5855 This returns a list of just the device names that contain PVs (eg.
5857 "/dev/sda2").
5858 See also "pvs-full".
5860 pvs-full
5862 pvs-full
5863 List all the physical volumes detected. This is the equivalent of the
5865 pvs(8) command. The "full" version includes all fields.
5866 pvuuid
5868 pvuuid device
5869 This command returns the UUID of the LVM PV "device".
5871 pwrite
5873 pwrite path content offset
5874 This command writes to part of a file. It writes the data buffer
5876 "content" to the file "path" starting at offset "offset".
5877 This command implements the pwrite(2) system call, and like that system
5879 call it may not write the full data requested. The return value is the
5880 number of bytes that were actually written to the file. This could
5881 even be 0, although short writes are unlikely for regular files in
5882 ordinary circumstances.
5883 See also "pread", "pwrite-device".
5885 Because of the message protocol, there is a transfer limit of somewhere
5887 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5888 pwrite-device
5890 pwrite-device device content offset
5891 This command writes to part of a device. It writes the data buffer
5893 "content" to "device" starting at offset "offset".
5894 This command implements the pwrite(2) system call, and like that system
5896 call it may not write the full data requested (although short writes to
5897 disk devices and partitions are probably impossible with standard Linux
5898 kernels).
5899 See also "pwrite".
5901 Because of the message protocol, there is a transfer limit of somewhere
5903 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5904 read-file
5906 read-file path
5907 This calls returns the contents of the file "path" as a buffer.
5909 Unlike "cat", this function can correctly handle files that contain
5911 embedded ASCII NUL characters.
5912 read-lines
5914 read-lines path
5915 Return the contents of the file named "path".
5917 The file contents are returned as a list of lines. Trailing "LF" and
5919 "CRLF" character sequences are not returned.
5920 Note that this function cannot correctly handle binary files
5922 (specifically, files containing "\0" character which is treated as end
5923 of string). For those you need to use the "read-file" function and
5924 split the buffer into lines yourself.
5925 readdir
5927 readdir dir
5928 This returns the list of directory entries in directory "dir".
5930 All entries in the directory are returned, including "." and "..". The
5932 entries are not sorted, but returned in the same order as the
5933 underlying filesystem.
5934 Also this call returns basic file type information about each file.
5936 The "ftyp" field will contain one of the following characters:
5937 'b' Block special
5939 'c' Char special
5941 'd' Directory
5943 'f' FIFO (named pipe)
5945 'l' Symbolic link
5947 'r' Regular file
5949 's' Socket
5951 'u' Unknown file type
5953 '?' The readdir(3) call returned a "d_type" field with an unexpected
5955 value
5956 This function is primarily intended for use by programs. To get a
5958 simple list of names, use "ls". To get a printable directory for human
5959 consumption, use "ll".
5960 Because of the message protocol, there is a transfer limit of somewhere
5962 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
5963 readlink
5965 readlink path
5966 This command reads the target of a symbolic link.
5968 readlinklist
5970 readlinklist path 'names ...'
5971 This call allows you to do a "readlink" operation on multiple files,
5973 where all files are in the directory "path". "names" is the list of
5974 files from this directory.
5975 On return you get a list of strings, with a one-to-one correspondence
5977 to the "names" list. Each string is the value of the symbolic link.
5978 If the readlink(2) operation fails on any name, then the corresponding
5980 result string is the empty string "". However the whole operation is
5981 completed even if there were readlink(2) errors, and so you can call
5982 this function with names where you don't know if they are symbolic
5983 links already (albeit slightly less efficient).
5984 This call is intended for programs that want to efficiently list a
5986 directory contents without making many round-trips.
5987 realpath
5989 realpath path
5990 Return the canonicalized absolute pathname of "path". The returned
5992 path has no ".", ".." or symbolic link path elements.
5993 remove-drive
5995 remove-drive label
5996 This function is conceptually the opposite of "add-drive-opts". It
5998 removes the drive that was previously added with label "label".
5999 Note that in order to remove drives, you have to add them with labels
6001 (see the optional "label" argument to "add-drive-opts"). If you didn't
6002 use a label, then they cannot be removed.
6003 You can call this function before or after launching the handle. If
6005 called after launch, if the attach-method supports it, we try to hot
6006 unplug the drive: see "HOTPLUGGING" in guestfs(3). The disk must not
6007 be in use (eg. mounted) when you do this. We try to detect if the disk
6008 is in use and stop you from doing this.
6009 removexattr
6011 removexattr xattr path
6012 This call removes the extended attribute named "xattr" of the file
6014 "path".
6015 See also: "lremovexattr", attr(5).
6017 rename
6019 rename oldpath newpath
6020 Rename a file to a new place on the same filesystem. This is the same
6022 as the Linux rename(2) system call. In most cases you are better to
6023 use "mv" instead.
6024 resize2fs
6026 resize2fs device
6027 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
6029 underlying device.
6030 See also "RESIZE2FS ERRORS" in guestfs(3).
6032 resize2fs-M
6034 resize2fs-M device
6035 This command is the same as "resize2fs", but the filesystem is resized
6037 to its minimum size. This works like the -M option to the "resize2fs"
6038 command.
6039 To get the resulting size of the filesystem you should call "tune2fs-l"
6041 and read the "Block size" and "Block count" values. These two numbers,
6042 multiplied together, give the resulting size of the minimal filesystem
6043 in bytes.
6044 See also "RESIZE2FS ERRORS" in guestfs(3).
6046 resize2fs-size
6048 resize2fs-size device size
6049 This command is the same as "resize2fs" except that it allows you to
6051 specify the new size (in bytes) explicitly.
6052 See also "RESIZE2FS ERRORS" in guestfs(3).
6054 rm
6056 rm path
6057 Remove the single file "path".
6059 rm-f
6061 rm-f path
6062 Remove the file "path".
6064 If the file doesn't exist, that error is ignored. (Other errors, eg.
6066 I/O errors or bad paths, are not ignored)
6067 This call cannot remove directories. Use "rmdir" to remove an empty
6069 directory, or "rm-rf" to remove directories recursively.
6070 rm-rf
6072 rm-rf path
6073 Remove the file or directory "path", recursively removing the contents
6075 if its a directory. This is like the "rm -rf" shell command.
6076 rmdir
6078 rmdir path
6079 Remove the single directory "path".
6081 rmmountpoint
6083 rmmountpoint exemptpath
6084 This calls removes a mountpoint that was previously created with
6086 "mkmountpoint". See "mkmountpoint" for full details.
6087 rsync
6089 rsync src dest [archive:true|false] [deletedest:true|false]
6090 This call may be used to copy or synchronize two directories under the
6092 same libguestfs handle. This uses the rsync(1) program which uses a
6093 fast algorithm that avoids copying files unnecessarily.
6094 "src" and "dest" are the source and destination directories. Files are
6096 copied from "src" to "dest".
6097 The optional arguments are:
6099 "archive"
6101 Turns on archive mode. This is the same as passing the --archive
6102 flag to "rsync".
6103 "deletedest"
6105 Delete files at the destination that do not exist at the source.
6106 This command has one or more optional arguments. See "OPTIONAL
6108 ARGUMENTS".
6109 rsync-in
6111 rsync-in remote dest [archive:true|false] [deletedest:true|false]
6112 This call may be used to copy or synchronize the filesystem on the host
6114 or on a remote computer with the filesystem within libguestfs. This
6115 uses the rsync(1) program which uses a fast algorithm that avoids
6116 copying files unnecessarily.
6117 This call only works if the network is enabled. See "set-network" or
6119 the --network option to various tools like guestfish(1).
6120 Files are copied from the remote server and directory specified by
6122 "remote" to the destination directory "dest".
6123 The format of the remote server string is defined by rsync(1). Note
6125 that there is no way to supply a password or passphrase so the target
6126 must be set up not to require one.
6127 The optional arguments are the same as those of "rsync".
6129 This command has one or more optional arguments. See "OPTIONAL
6131 ARGUMENTS".
6132 rsync-out
6134 rsync-out src remote [archive:true|false] [deletedest:true|false]
6135 This call may be used to copy or synchronize the filesystem within
6137 libguestfs with a filesystem on the host or on a remote computer. This
6138 uses the rsync(1) program which uses a fast algorithm that avoids
6139 copying files unnecessarily.
6140 This call only works if the network is enabled. See "set-network" or
6142 the --network option to various tools like guestfish(1).
6143 Files are copied from the source directory "src" to the remote server
6145 and directory specified by "remote".
6146 The format of the remote server string is defined by rsync(1). Note
6148 that there is no way to supply a password or passphrase so the target
6149 must be set up not to require one.
6150 The optional arguments are the same as those of "rsync".
6152 Globbing does not happen on the "src" parameter. In programs which use
6154 the API directly you have to expand wildcards yourself (see "glob-
6155 expand"). In guestfish you can use the "glob" command (see "glob" in
6156 guestfish(1)), for example:
6157 ><fs> glob rsync-out /* rsync://remote/
6159 This command has one or more optional arguments. See "OPTIONAL
6161 ARGUMENTS".
6162 scrub-device
6164 scrub-device device
6165 This command writes patterns over "device" to make data retrieval more
6167 difficult.
6168 It is an interface to the scrub(1) program. See that manual page for
6170 more details.
6171 scrub-file
6173 scrub-file file
6174 This command writes patterns over a file to make data retrieval more
6176 difficult.
6177 The file is removed after scrubbing.
6179 It is an interface to the scrub(1) program. See that manual page for
6181 more details.
6182 scrub-freespace
6184 scrub-freespace dir
6185 This command creates the directory "dir" and then fills it with files
6187 until the filesystem is full, and scrubs the files as for "scrub-file",
6188 and deletes them. The intention is to scrub any free space on the
6189 partition containing "dir".
6190 It is an interface to the scrub(1) program. See that manual page for
6192 more details.
6193 set-append
6195 append
6196 set-append append
6197 This function is used to add additional options to the libguestfs
6199 appliance kernel command line.
6200 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
6202 environment variable.
6203 Setting "append" to "NULL" means no additional options are passed
6205 (libguestfs always adds a few of its own).
6206 set-attach-method
6208 attach-method
6209 set-attach-method attachmethod
6210 Set the method that libguestfs uses to connect to the back end guestfsd
6212 daemon.
6213 See "ATTACH METHOD" in guestfs(3).
6215 set-autosync
6217 autosync
6218 set-autosync true|false
6219 If "autosync" is true, this enables autosync. Libguestfs will make a
6221 best effort attempt to make filesystems consistent and synchronized
6222 when the handle is closed (also if the program exits without closing
6223 handles).
6224 This is enabled by default (since libguestfs 1.5.24, previously it was
6226 disabled by default).
6227 set-cachedir
6229 cachedir
6230 set-cachedir cachedir
6231 Set the directory used by the handle to store the appliance cache, when
6233 using a supermin appliance. The appliance is cached and shared between
6234 all handles which have the same effective user ID.
6235 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
6237 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
6238 default. Else if "TMPDIR" is set, then that is the default. Else
6239 "/var/tmp" is the default.
6240 set-direct
6242 direct
6243 set-direct true|false
6244 If the direct appliance mode flag is enabled, then stdin and stdout are
6246 passed directly through to the appliance once it is launched.
6247 One consequence of this is that log messages aren't caught by the
6249 library and handled by "set-log-message-callback", but go straight to
6250 stdout.
6251 You probably don't want to use this unless you know what you are doing.
6253 The default is disabled.
6255 set-e2attrs
6257 set-e2attrs file attrs [clear:true|false]
6258 This sets or clears the file attributes "attrs" associated with the
6260 inode "file".
6261 "attrs" is a string of characters representing file attributes. See
6263 "get-e2attrs" for a list of possible attributes. Not all attributes
6264 can be changed.
6265 If optional boolean "clear" is not present or false, then the "attrs"
6267 listed are set in the inode.
6268 If "clear" is true, then the "attrs" listed are cleared in the inode.
6270 In both cases, other attributes not present in the "attrs" string are
6272 left unchanged.
6273 These attributes are only present when the file is located on an
6275 ext2/3/4 filesystem. Using this call on other filesystem types will
6276 result in an error.
6277 This command has one or more optional arguments. See "OPTIONAL
6279 ARGUMENTS".
6280 set-e2generation
6282 set-e2generation file generation
6283 This sets the ext2 file generation of a file.
6285 See "get-e2generation".
6287 set-e2label
6289 set-e2label device label
6290 This sets the ext2/3/4 filesystem label of the filesystem on "device"
6292 to "label". Filesystem labels are limited to 16 characters.
6293 You can use either "tune2fs-l" or "get-e2label" to return the existing
6295 label on a filesystem.
6296 This function is deprecated. In new code, use the "set-label" call
6298 instead.
6299 Deprecated functions will not be removed from the API, but the fact
6301 that they are deprecated indicates that there are problems with correct
6302 use of these functions.
6303 set-e2uuid
6305 set-e2uuid device uuid
6306 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
6308 "uuid". The format of the UUID and alternatives such as "clear",
6309 "random" and "time" are described in the tune2fs(8) manpage.
6310 You can use either "tune2fs-l" or "get-e2uuid" to return the existing
6312 UUID of a filesystem.
6313 set-label
6315 set-label device label
6316 Set the filesystem label on "device" to "label".
6318 Only some filesystem types support labels, and libguestfs supports
6320 setting labels on only a subset of these.
6321 ext2, ext3, ext4
6323 Labels are limited to 16 bytes.
6324 NTFS
6326 Labels are limited to 128 unicode characters.
6327 XFS The label is limited to 12 bytes. The filesystem must not be
6329 mounted when trying to set the label.
6330 btrfs
6332 The label is limited to 255 bytes and some characters are not
6333 allowed. Setting the label on a btrfs subvolume will set the label
6334 on its parent filesystem. The filesystem must not be mounted when
6335 trying to set the label.
6336 To read the label on a filesystem, call "vfs-label".
6338 set-libvirt-requested-credential
6340 set-libvirt-requested-credential index cred
6341 After requesting the "index"'th credential from the user, call this
6343 function to pass the answer back to libvirt.
6344 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6346 example code.
6347 set-libvirt-supported-credentials
6349 set-libvirt-supported-credentials 'creds ...'
6350 Call this function before setting an event handler for
6352 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
6353 that the program knows how to process.
6354 The "creds" list must be a non-empty list of strings. Possible strings
6356 are:
6357 "username"
6359 "authname"
6360 "language"
6361 "cnonce"
6362 "passphrase"
6363 "echoprompt"
6364 "noechoprompt"
6365 "realm"
6366 "external"
6367 See libvirt documentation for the meaning of these credential types.
6369 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
6371 example code.
6372 set-memsize
6374 memsize
6375 set-memsize memsize
6376 This sets the memory size in megabytes allocated to the qemu
6378 subprocess. This only has any effect if called before "launch".
6379 You can also change this by setting the environment variable
6381 "LIBGUESTFS_MEMSIZE" before the handle is created.
6382 For more information on the architecture of libguestfs, see guestfs(3).
6384 set-network
6386 network
6387 set-network true|false
6388 If "network" is true, then the network is enabled in the libguestfs
6390 appliance. The default is false.
6391 This affects whether commands are able to access the network (see
6393 "RUNNING COMMANDS" in guestfs(3)).
6394 You must call this before calling "launch", otherwise it has no effect.
6396 set-path
6398 path
6399 set-path searchpath
6400 Set the path that libguestfs searches for kernel and initrd.img.
6402 The default is "$libdir/guestfs" unless overridden by setting
6404 "LIBGUESTFS_PATH" environment variable.
6405 Setting "path" to "NULL" restores the default path.
6407 set-pgroup
6409 pgroup
6410 set-pgroup true|false
6411 If "pgroup" is true, child processes are placed into their own process
6413 group.
6414 The practical upshot of this is that signals like "SIGINT" (from users
6416 pressing "^C") won't be received by the child process.
6417 The default for this flag is false, because usually you want "^C" to
6419 kill the subprocess. Guestfish sets this flag to true when used
6420 interactively, so that "^C" can cancel long-running commands gracefully
6421 (see "user-cancel").
6422 set-qemu
6424 qemu
6425 set-qemu qemu
6426 Set the qemu binary that we will use.
6428 The default is chosen when the library was compiled by the configure
6430 script.
6431 You can also override this by setting the "LIBGUESTFS_QEMU" environment
6433 variable.
6434 Setting "qemu" to "NULL" restores the default qemu binary.
6436 Note that you should call this function as early as possible after
6438 creating the handle. This is because some pre-launch operations depend
6439 on testing qemu features (by running "qemu -help"). If the qemu binary
6440 changes, we don't retest features, and so you might see inconsistent
6441 results. Using the environment variable "LIBGUESTFS_QEMU" is safest of
6442 all since that picks the qemu binary at the same time as the handle is
6443 created.
6444 set-recovery-proc
6446 recovery-proc
6447 set-recovery-proc true|false
6448 If this is called with the parameter "false" then "launch" does not
6450 create a recovery process. The purpose of the recovery process is to
6451 stop runaway qemu processes in the case where the main program aborts
6452 abruptly.
6453 This only has any effect if called before "launch", and the default is
6455 true.
6456 About the only time when you would want to disable this is if the main
6458 process will fork itself into the background ("daemonize" itself). In
6459 this case the recovery process thinks that the main program has
6460 disappeared and so kills qemu, which is not very helpful.
6461 set-selinux
6463 selinux
6464 set-selinux true|false
6465 This sets the selinux flag that is passed to the appliance at boot
6467 time. The default is "selinux=0" (disabled).
6468 Note that if SELinux is enabled, it is always in Permissive mode
6470 ("enforcing=0").
6471 For more information on the architecture of libguestfs, see guestfs(3).
6473 set-smp
6475 smp
6476 set-smp smp
6477 Change the number of virtual CPUs assigned to the appliance. The
6479 default is 1. Increasing this may improve performance, though often it
6480 has no effect.
6481 This function must be called before "launch".
6483 set-tmpdir
6485 tmpdir
6486 set-tmpdir tmpdir
6487 Set the directory used by the handle to store temporary files.
6489 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
6491 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
6492 Else if "TMPDIR" is set, then that is the default. Else "/tmp" is the
6493 default.
6494 set-trace
6496 trace
6497 set-trace true|false
6498 If the command trace flag is set to 1, then libguestfs calls,
6500 parameters and return values are traced.
6501 If you want to trace C API calls into libguestfs (and other libraries)
6503 then possibly a better way is to use the external ltrace(1) command.
6504 Command traces are disabled unless the environment variable
6506 "LIBGUESTFS_TRACE" is defined and set to 1.
6507 Trace messages are normally sent to "stderr", unless you register a
6509 callback to send them somewhere else (see "set-event-callback").
6510 set-verbose
6512 verbose
6513 set-verbose true|false
6514 If "verbose" is true, this turns on verbose messages.
6516 Verbose messages are disabled unless the environment variable
6518 "LIBGUESTFS_DEBUG" is defined and set to 1.
6519 Verbose messages are normally sent to "stderr", unless you register a
6521 callback to send them somewhere else (see "set-event-callback").
6522 setcon
6524 setcon context
6525 This sets the SELinux security context of the daemon to the string
6527 "context".
6528 See the documentation about SELINUX in guestfs(3).
6530 setxattr
6532 setxattr xattr val vallen path
6533 This call sets the extended attribute named "xattr" of the file "path"
6535 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
6536 data.
6537 See also: "lsetxattr", attr(5).
6539 sfdisk
6541 sfdisk device cyls heads sectors 'lines ...'
6542 This is a direct interface to the sfdisk(8) program for creating
6544 partitions on block devices.
6545 "device" should be a block device, for example "/dev/sda".
6547 "cyls", "heads" and "sectors" are the number of cylinders, heads and
6549 sectors on the device, which are passed directly to sfdisk as the -C,
6550 -H and -S parameters. If you pass 0 for any of these, then the
6551 corresponding parameter is omitted. Usually for 'large' disks, you can
6552 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
6553 rather, the kernel) cannot work out the right geometry and you will
6554 need to tell it.
6555 "lines" is a list of lines that we feed to "sfdisk". For more
6557 information refer to the sfdisk(8) manpage.
6558 To create a single partition occupying the whole disk, you would pass
6560 "lines" as a single element list, when the single element being the
6561 string "," (comma).
6562 See also: "sfdisk-l", "sfdisk-N", "part-init"
6564 This function is deprecated. In new code, use the "part-add" call
6566 instead.
6567 Deprecated functions will not be removed from the API, but the fact
6569 that they are deprecated indicates that there are problems with correct
6570 use of these functions.
6571 sfdiskM
6573 sfdiskM device 'lines ...'
6574 This is a simplified interface to the "sfdisk" command, where partition
6576 sizes are specified in megabytes only (rounded to the nearest cylinder)
6577 and you don't need to specify the cyls, heads and sectors parameters
6578 which were rarely if ever used anyway.
6579 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
6581 This function is deprecated. In new code, use the "part-add" call
6583 instead.
6584 Deprecated functions will not be removed from the API, but the fact
6586 that they are deprecated indicates that there are problems with correct
6587 use of these functions.
6588 sfdisk-N
6590 sfdisk-N device partnum cyls heads sectors line
6591 This runs sfdisk(8) option to modify just the single partition "n"
6593 (note: "n" counts from 1).
6594 For other parameters, see "sfdisk". You should usually pass 0 for the
6596 cyls/heads/sectors parameters.
6597 See also: "part-add"
6599 This function is deprecated. In new code, use the "part-add" call
6601 instead.
6602 Deprecated functions will not be removed from the API, but the fact
6604 that they are deprecated indicates that there are problems with correct
6605 use of these functions.
6606 sfdisk-disk-geometry
6608 sfdisk-disk-geometry device
6609 This displays the disk geometry of "device" read from the partition
6611 table. Especially in the case where the underlying block device has
6612 been resized, this can be different from the kernel's idea of the
6613 geometry (see "sfdisk-kernel-geometry").
6614 The result is in human-readable format, and not designed to be parsed.
6616 sfdisk-kernel-geometry
6618 sfdisk-kernel-geometry device
6619 This displays the kernel's idea of the geometry of "device".
6621 The result is in human-readable format, and not designed to be parsed.
6623 sfdisk-l
6625 sfdisk-l device
6626 This displays the partition table on "device", in the human-readable
6628 output of the sfdisk(8) command. It is not intended to be parsed.
6629 See also: "part-list"
6631 This function is deprecated. In new code, use the "part-list" call
6633 instead.
6634 Deprecated functions will not be removed from the API, but the fact
6636 that they are deprecated indicates that there are problems with correct
6637 use of these functions.
6638 sh
6640 sh command
6641 This call runs a command from the guest filesystem via the guest's
6643 "/bin/sh".
6644 This is like "command", but passes the command to:
6646 /bin/sh -c "command"
6648 Depending on the guest's shell, this usually results in wildcards being
6650 expanded, shell expressions being interpolated and so on.
6651 All the provisos about "command" apply to this call.
6653 sh-lines
6655 sh-lines command
6656 This is the same as "sh", but splits the result into a list of lines.
6658 See also: "command-lines"
6660 shutdown
6662 shutdown
6663 This is the opposite of "launch". It performs an orderly shutdown of
6665 the backend process(es). If the autosync flag is set (which is the
6666 default) then the disk image is synchronized.
6667 If the subprocess exits with an error then this function will return an
6669 error, which should not be ignored (it may indicate that the disk image
6670 could not be written out properly).
6671 It is safe to call this multiple times. Extra calls are ignored.
6673 This call does not close or free up the handle. You still need to call
6675 "close" afterwards.
6676 "close" will call this if you don't do it explicitly, but note that any
6678 errors are ignored in that case.
6679 sleep
6681 sleep secs
6682 Sleep for "secs" seconds.
6684 stat
6686 stat path
6687 Returns file information for the given "path".
6689 This is the same as the stat(2) system call.
6691 statvfs
6693 statvfs path
6694 Returns file system statistics for any mounted file system. "path"
6696 should be a file or directory in the mounted file system (typically it
6697 is the mount point itself, but it doesn't need to be).
6698 This is the same as the statvfs(2) system call.
6700 strings
6702 strings path
6703 This runs the strings(1) command on a file and returns the list of
6705 printable strings found.
6706 Because of the message protocol, there is a transfer limit of somewhere
6708 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6709 strings-e
6711 strings-e encoding path
6712 This is like the "strings" command, but allows you to specify the
6714 encoding of strings that are looked for in the source file "path".
6715 Allowed encodings are:
6717 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
6719 parts of ISO-8859-X (this is what "strings" uses).
6720 S Single 8-bit-byte characters.
6722 b 16-bit big endian strings such as those encoded in UTF-16BE or
6724 UCS-2BE.
6725 l (lower case letter L)
6727 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
6728 for examining binaries in Windows guests.
6729 B 32-bit big endian such as UCS-4BE.
6731 L 32-bit little endian such as UCS-4LE.
6733 The returned strings are transcoded to UTF-8.
6735 Because of the message protocol, there is a transfer limit of somewhere
6737 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6738 swapoff-device
6740 swapoff-device device
6741 This command disables the libguestfs appliance swap device or partition
6743 named "device". See "swapon-device".
6744 swapoff-file
6746 swapoff-file file
6747 This command disables the libguestfs appliance swap on file.
6749 swapoff-label
6751 swapoff-label label
6752 This command disables the libguestfs appliance swap on labeled swap
6754 partition.
6755 swapoff-uuid
6757 swapoff-uuid uuid
6758 This command disables the libguestfs appliance swap partition with the
6760 given UUID.
6761 swapon-device
6763 swapon-device device
6764 This command enables the libguestfs appliance to use the swap device or
6766 partition named "device". The increased memory is made available for
6767 all commands, for example those run using "command" or "sh".
6768 Note that you should not swap to existing guest swap partitions unless
6770 you know what you are doing. They may contain hibernation information,
6771 or other information that the guest doesn't want you to trash. You
6772 also risk leaking information about the host to the guest this way.
6773 Instead, attach a new host device to the guest and swap on that.
6774 swapon-file
6776 swapon-file file
6777 This command enables swap to a file. See "swapon-device" for other
6779 notes.
6780 swapon-label
6782 swapon-label label
6783 This command enables swap to a labeled swap partition. See "swapon-
6785 device" for other notes.
6786 swapon-uuid
6788 swapon-uuid uuid
6789 This command enables swap to a swap partition with the given UUID. See
6791 "swapon-device" for other notes.
6792 sync
6794 sync
6795 This syncs the disk, so that any writes are flushed through to the
6797 underlying disk image.
6798 You should always call this if you have modified a disk image, before
6800 closing the handle.
6801 tail
6803 tail path
6804 This command returns up to the last 10 lines of a file as a list of
6806 strings.
6807 Because of the message protocol, there is a transfer limit of somewhere
6809 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6810 tail-n
6812 tail-n nrlines path
6813 If the parameter "nrlines" is a positive number, this returns the last
6815 "nrlines" lines of the file "path".
6816 If the parameter "nrlines" is a negative number, this returns lines
6818 from the file "path", starting with the "-nrlines"th line.
6819 If the parameter "nrlines" is zero, this returns an empty list.
6821 Because of the message protocol, there is a transfer limit of somewhere
6823 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
6824 tar-in
6826 tar-in-opts
6827 tar-in (tarfile|-) directory [compress:..]
6828 This command uploads and unpacks local file "tarfile" into "directory".
6830 The optional "compress" flag controls compression. If not given, then
6832 the input should be an uncompressed tar file. Otherwise one of the
6833 following strings may be given to select the compression type of the
6834 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
6835 all builds of libguestfs will support all of these compression types).
6836 Use "-" instead of a filename to read/write from stdin/stdout.
6838 This command has one or more optional arguments. See "OPTIONAL
6840 ARGUMENTS".
6841 tar-out
6843 tar-out-opts
6844 tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..]
6845 This command packs the contents of "directory" and downloads it to
6847 local file "tarfile".
6848 The optional "compress" flag controls compression. If not given, then
6850 the output will be an uncompressed tar file. Otherwise one of the
6851 following strings may be given to select the compression type of the
6852 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
6853 all builds of libguestfs will support all of these compression types).
6854 The other optional arguments are:
6856 "excludes"
6858 A list of wildcards. Files are excluded if they match any of the
6859 wildcards.
6860 "numericowner"
6862 If set to true, the output tar file will contain UID/GID numbers
6863 instead of user/group names.
6864 Use "-" instead of a filename to read/write from stdin/stdout.
6866 This command has one or more optional arguments. See "OPTIONAL
6868 ARGUMENTS".
6869 tgz-in
6871 tgz-in (tarball|-) directory
6872 This command uploads and unpacks local file "tarball" (a gzip
6874 compressed tar file) into "directory".
6875 Use "-" instead of a filename to read/write from stdin/stdout.
6877 This function is deprecated. In new code, use the "tar-in" call
6879 instead.
6880 Deprecated functions will not be removed from the API, but the fact
6882 that they are deprecated indicates that there are problems with correct
6883 use of these functions.
6884 tgz-out
6886 tgz-out directory (tarball|-)
6887 This command packs the contents of "directory" and downloads it to
6889 local file "tarball".
6890 Use "-" instead of a filename to read/write from stdin/stdout.
6892 This function is deprecated. In new code, use the "tar-out" call
6894 instead.
6895 Deprecated functions will not be removed from the API, but the fact
6897 that they are deprecated indicates that there are problems with correct
6898 use of these functions.
6899 touch
6901 touch path
6902 Touch acts like the touch(1) command. It can be used to update the
6904 timestamps on a file, or, if the file does not exist, to create a new
6905 zero-length file.
6906 This command only works on regular files, and will fail on other file
6908 types such as directories, symbolic links, block special etc.
6909 truncate
6911 truncate path
6912 This command truncates "path" to a zero-length file. The file must
6914 exist already.
6915 truncate-size
6917 truncate-size path size
6918 This command truncates "path" to size "size" bytes. The file must
6920 exist already.
6921 If the current file size is less than "size" then the file is extended
6923 to the required size with zero bytes. This creates a sparse file (ie.
6924 disk blocks are not allocated for the file until you write to it). To
6925 create a non-sparse file of zeroes, use "fallocate64" instead.
6926 tune2fs
6928 tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
6929 This call allows you to adjust various filesystem parameters of an
6931 ext2/ext3/ext4 filesystem called "device".
6932 The optional parameters are:
6934 "force"
6936 Force tune2fs to complete the operation even in the face of errors.
6937 This is the same as the tune2fs "-f" option.
6938 "maxmountcount"
6940 Set the number of mounts after which the filesystem is checked by
6941 e2fsck(8). If this is 0 then the number of mounts is disregarded.
6942 This is the same as the tune2fs "-c" option.
6943 "mountcount"
6945 Set the number of times the filesystem has been mounted. This is
6946 the same as the tune2fs "-C" option.
6947 "errorbehavior"
6949 Change the behavior of the kernel code when errors are detected.
6950 Possible values currently are: "continue", "remount-ro", "panic".
6951 In practice these options don't really make any difference,
6952 particularly for write errors.
6953 This is the same as the tune2fs "-e" option.
6955 "group"
6957 Set the group which can use reserved filesystem blocks. This is
6958 the same as the tune2fs "-g" option except that it can only be
6959 specified as a number.
6960 "intervalbetweenchecks"
6962 Adjust the maximal time between two filesystem checks (in seconds).
6963 If the option is passed as 0 then time-dependent checking is
6964 disabled.
6965 This is the same as the tune2fs "-i" option.
6967 "reservedblockspercentage"
6969 Set the percentage of the filesystem which may only be allocated by
6970 privileged processes. This is the same as the tune2fs "-m" option.
6971 "lastmounteddirectory"
6973 Set the last mounted directory. This is the same as the tune2fs
6974 "-M" option.
6975 "reservedblockscount" Set the number of reserved filesystem blocks.
6977 This is the same as the tune2fs "-r" option.
6978 "user"
6979 Set the user who can use the reserved filesystem blocks. This is
6980 the same as the tune2fs "-u" option except that it can only be
6981 specified as a number.
6982 To get the current values of filesystem parameters, see "tune2fs-l".
6984 For precise details of how tune2fs works, see the tune2fs(8) man page.
6985 This command has one or more optional arguments. See "OPTIONAL
6987 ARGUMENTS".
6988 tune2fs-l
6990 tune2fs-l device
6991 This returns the contents of the ext2, ext3 or ext4 filesystem
6993 superblock on "device".
6994 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
6996 for more details. The list of fields returned isn't clearly defined,
6997 and depends on both the version of "tune2fs" that libguestfs was built
6998 against, and the filesystem itself.
6999 txz-in
7001 txz-in (tarball|-) directory
7002 This command uploads and unpacks local file "tarball" (an xz compressed
7004 tar file) into "directory".
7005 Use "-" instead of a filename to read/write from stdin/stdout.
7007 This function is deprecated. In new code, use the "tar-in" call
7009 instead.
7010 Deprecated functions will not be removed from the API, but the fact
7012 that they are deprecated indicates that there are problems with correct
7013 use of these functions.
7014 txz-out
7016 txz-out directory (tarball|-)
7017 This command packs the contents of "directory" and downloads it to
7019 local file "tarball" (as an xz compressed tar archive).
7020 Use "-" instead of a filename to read/write from stdin/stdout.
7022 This function is deprecated. In new code, use the "tar-out" call
7024 instead.
7025 Deprecated functions will not be removed from the API, but the fact
7027 that they are deprecated indicates that there are problems with correct
7028 use of these functions.
7029 umask
7031 umask mask
7032 This function sets the mask used for creating new files and device
7034 nodes to "mask & 0777".
7035 Typical umask values would be 022 which creates new files with
7037 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
7038 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
7039 The default umask is 022. This is important because it means that
7041 directories and device nodes will be created with 0644 or 0755 mode
7042 even if you specify 0777.
7043 See also "get-umask", umask(2), "mknod", "mkdir".
7045 This call returns the previous umask.
7047 umount
7049 unmount
7050 umount-opts
7051 umount pathordevice [force:true|false] [lazyunmount:true|false]
7052 This unmounts the given filesystem. The filesystem may be specified
7054 either by its mountpoint (path) or the device which contains the
7055 filesystem.
7056 This command has one or more optional arguments. See "OPTIONAL
7058 ARGUMENTS".
7059 umount-all
7061 unmount-all
7062 umount-all
7063 This unmounts all mounted filesystems.
7065 Some internal mounts are not unmounted by this call.
7067 umount-local
7069 umount-local [retry:true|false]
7070 If libguestfs is exporting the filesystem on a local mountpoint, then
7072 this unmounts it.
7073 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7075 This command has one or more optional arguments. See "OPTIONAL
7077 ARGUMENTS".
7078 upload
7080 upload (filename|-) remotefilename
7081 Upload local file "filename" to "remotefilename" on the filesystem.
7083 "filename" can also be a named pipe.
7085 See also "download".
7087 Use "-" instead of a filename to read/write from stdin/stdout.
7089 upload-offset
7091 upload-offset (filename|-) remotefilename offset
7092 Upload local file "filename" to "remotefilename" on the filesystem.
7094 "remotefilename" is overwritten starting at the byte "offset"
7096 specified. The intention is to overwrite parts of existing files or
7097 devices, although if a non-existent file is specified then it is
7098 created with a "hole" before "offset". The size of the data written is
7099 implicit in the size of the source "filename".
7100 Note that there is no limit on the amount of data that can be uploaded
7102 with this call, unlike with "pwrite", and this call always writes the
7103 full amount unless an error occurs.
7104 See also "upload", "pwrite".
7106 Use "-" instead of a filename to read/write from stdin/stdout.
7108 user-cancel
7110 user-cancel
7111 This function cancels the current upload or download operation.
7113 Unlike most other libguestfs calls, this function is signal safe and
7115 thread safe. You can call it from a signal handler or from another
7116 thread, without needing to do any locking.
7117 The transfer that was in progress (if there is one) will stop shortly
7119 afterwards, and will return an error. The errno (see
7120 "guestfs_last_errno") is set to "EINTR", so you can test for this to
7121 find out if the operation was cancelled or failed because of another
7122 error.
7123 No cleanup is performed: for example, if a file was being uploaded then
7125 after cancellation there may be a partially uploaded file. It is the
7126 caller's responsibility to clean up if necessary.
7127 There are two common places that you might call "user-cancel":
7129 In an interactive text-based program, you might call it from a "SIGINT"
7131 signal handler so that pressing "^C" cancels the current operation.
7132 (You also need to call "guestfs_set_pgroup" so that child processes
7133 don't receive the "^C" signal).
7134 In a graphical program, when the main thread is displaying a progress
7136 bar with a cancel button, wire up the cancel button to call this
7137 function.
7138 utimens
7140 utimens path atsecs atnsecs mtsecs mtnsecs
7141 This command sets the timestamps of a file with nanosecond precision.
7143 "atsecs, atnsecs" are the last access time (atime) in secs and
7145 nanoseconds from the epoch.
7146 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
7148 nanoseconds from the epoch.
7149 If the *nsecs field contains the special value "-1" then the
7151 corresponding timestamp is set to the current time. (The *secs field
7152 is ignored in this case).
7153 If the *nsecs field contains the special value "-2" then the
7155 corresponding timestamp is left unchanged. (The *secs field is ignored
7156 in this case).
7157 utsname
7159 utsname
7160 This returns the kernel version of the appliance, where this is
7162 available. This information is only useful for debugging. Nothing in
7163 the returned structure is defined by the API.
7164 version
7166 version
7167 Return the libguestfs version number that the program is linked
7169 against.
7170 Note that because of dynamic linking this is not necessarily the
7172 version of libguestfs that you compiled against. You can compile the
7173 program, and then at runtime dynamically link against a completely
7174 different "libguestfs.so" library.
7175 This call was added in version 1.0.58. In previous versions of
7177 libguestfs there was no way to get the version number. From C code you
7178 can use dynamic linker functions to find out if this symbol exists (if
7179 it doesn't, then it's an earlier version).
7180 The call returns a structure with four elements. The first three
7182 ("major", "minor" and "release") are numbers and correspond to the
7183 usual version triplet. The fourth element ("extra") is a string and is
7184 normally empty, but may be used for distro-specific information.
7185 To construct the original version string:
7187 "$major.$minor.$release$extra"
7188 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
7190 Note: Don't use this call to test for availability of features. In
7192 enterprise distributions we backport features from later versions into
7193 earlier versions, making this an unreliable way to test for features.
7194 Use "available" instead.
7195 vfs-label
7197 vfs-label device
7198 This returns the filesystem label of the filesystem on "device".
7200 If the filesystem is unlabeled, this returns the empty string.
7202 To find a filesystem from the label, use "findfs-label".
7204 vfs-type
7206 vfs-type device
7207 This command gets the filesystem type corresponding to the filesystem
7209 on "device".
7210 For most filesystems, the result is the name of the Linux VFS module
7212 which would be used to mount this filesystem if you mounted it without
7213 specifying the filesystem type. For example a string such as "ext3" or
7214 "ntfs".
7215 vfs-uuid
7217 vfs-uuid device
7218 This returns the filesystem UUID of the filesystem on "device".
7220 If the filesystem does not have a UUID, this returns the empty string.
7222 To find a filesystem from the UUID, use "findfs-uuid".
7224 vg-activate
7226 vg-activate true|false 'volgroups ...'
7227 This command activates or (if "activate" is false) deactivates all
7229 logical volumes in the listed volume groups "volgroups".
7230 This command is the same as running "vgchange -a y|n volgroups..."
7232 Note that if "volgroups" is an empty list then all volume groups are
7234 activated or deactivated.
7235 vg-activate-all
7237 vg-activate-all true|false
7238 This command activates or (if "activate" is false) deactivates all
7240 logical volumes in all volume groups.
7241 This command is the same as running "vgchange -a y|n"
7243 vgchange-uuid
7245 vgchange-uuid vg
7246 Generate a new random UUID for the volume group "vg".
7248 vgchange-uuid-all
7250 vgchange-uuid-all
7251 Generate new random UUIDs for all volume groups.
7253 vgcreate
7255 vgcreate volgroup 'physvols ...'
7256 This creates an LVM volume group called "volgroup" from the non-empty
7258 list of physical volumes "physvols".
7259 vglvuuids
7261 vglvuuids vgname
7262 Given a VG called "vgname", this returns the UUIDs of all the logical
7264 volumes created in this volume group.
7265 You can use this along with "lvs" and "lvuuid" calls to associate
7267 logical volumes and volume groups.
7268 See also "vgpvuuids".
7270 vgmeta
7272 vgmeta vgname
7273 "vgname" is an LVM volume group. This command examines the volume
7275 group and returns its metadata.
7276 Note that the metadata is an internal structure used by LVM, subject to
7278 change at any time, and is provided for information only.
7279 vgpvuuids
7281 vgpvuuids vgname
7282 Given a VG called "vgname", this returns the UUIDs of all the physical
7284 volumes that this volume group resides on.
7285 You can use this along with "pvs" and "pvuuid" calls to associate
7287 physical volumes and volume groups.
7288 See also "vglvuuids".
7290 vgremove
7292 vgremove vgname
7293 Remove an LVM volume group "vgname", (for example "VG").
7295 This also forcibly removes all logical volumes in the volume group (if
7297 any).
7298 vgrename
7300 vgrename volgroup newvolgroup
7301 Rename a volume group "volgroup" with the new name "newvolgroup".
7303 vgs
7305 vgs
7306 List all the volumes groups detected. This is the equivalent of the
7308 vgs(8) command.
7309 This returns a list of just the volume group names that were detected
7311 (eg. "VolGroup00").
7312 See also "vgs-full".
7314 vgs-full
7316 vgs-full
7317 List all the volumes groups detected. This is the equivalent of the
7319 vgs(8) command. The "full" version includes all fields.
7320 vgscan
7322 vgscan
7323 This rescans all block devices and rebuilds the list of LVM physical
7325 volumes, volume groups and logical volumes.
7326 vguuid
7328 vguuid vgname
7329 This command returns the UUID of the LVM VG named "vgname".
7331 wait-ready
7333 wait-ready
7334 This function is a no op.
7336 In versions of the API < 1.0.71 you had to call this function just
7338 after calling "launch" to wait for the launch to complete. However
7339 this is no longer necessary because "launch" now does the waiting.
7340 If you see any calls to this function in code then you can just remove
7342 them, unless you want to retain compatibility with older versions of
7343 the API.
7344 This function is deprecated. In new code, use the "launch" call
7346 instead.
7347 Deprecated functions will not be removed from the API, but the fact
7349 that they are deprecated indicates that there are problems with correct
7350 use of these functions.
7351 wc-c
7353 wc-c path
7354 This command counts the characters in a file, using the "wc -c"
7356 external command.
7357 wc-l
7359 wc-l path
7360 This command counts the lines in a file, using the "wc -l" external
7362 command.
7363 wc-w
7365 wc-w path
7366 This command counts the words in a file, using the "wc -w" external
7368 command.
7369 wipefs
7371 wipefs device
7372 This command erases filesystem or RAID signatures from the specified
7374 "device" to make the filesystem invisible to libblkid.
7375 This does not erase the filesystem itself nor any other data from the
7377 "device".
7378 Compare with "zero" which zeroes the first few blocks of a device.
7380 write
7382 write path content
7383 This call creates a file called "path". The content of the file is the
7385 string "content" (which can contain any 8 bit data).
7386 See also "write-append".
7388 write-append
7390 write-append path content
7391 This call appends "content" to the end of file "path". If "path" does
7393 not exist, then a new file is created.
7394 See also "write".
7396 write-file
7398 write-file path content size
7399 This call creates a file called "path". The contents of the file is
7401 the string "content" (which can contain any 8 bit data), with length
7402 "size".
7403 As a special case, if "size" is 0 then the length is calculated using
7405 "strlen" (so in this case the content cannot contain embedded ASCII
7406 NULs).
7407 NB. Owing to a bug, writing content containing ASCII NUL characters
7409 does not work, even if the length is specified.
7410 Because of the message protocol, there is a transfer limit of somewhere
7412 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7413 This function is deprecated. In new code, use the "write" call
7415 instead.
7416 Deprecated functions will not be removed from the API, but the fact
7418 that they are deprecated indicates that there are problems with correct
7419 use of these functions.
7420 xfs-admin
7422 xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
7423 Change the parameters of the XFS filesystem on "device".
7425 Devices that are mounted cannot be modified. Administrators must
7427 unmount filesystems before this call can modify parameters.
7428 Some of the parameters of a mounted filesystem can be examined and
7430 modified using the "xfs-info" and "xfs-growfs" calls.
7431 This command has one or more optional arguments. See "OPTIONAL
7433 ARGUMENTS".
7434 xfs-growfs
7436 xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
7437 Grow the XFS filesystem mounted at "path".
7439 The returned struct contains geometry information. Missing fields are
7441 returned as "-1" (for numeric fields) or empty string.
7442 This command has one or more optional arguments. See "OPTIONAL
7444 ARGUMENTS".
7445 xfs-info
7447 xfs-info pathordevice
7448 "pathordevice" is a mounted XFS filesystem or a device containing an
7450 XFS filesystem. This command returns the geometry of the filesystem.
7451 The returned struct contains geometry information. Missing fields are
7453 returned as "-1" (for numeric fields) or empty string.
7454 xfs-repair
7456 xfs-repair device [forcelogzero:true|false] [nomodify:true|false] [noprefetch:true|false] [forcegeometry:true|false] [maxmem:N] [ihashsize:N] [bhashsize:N] [agstride:N] [logdev:..] [rtdev:..]
7457 Repair corrupt or damaged XFS filesystem on "device".
7459 The filesystem is specified using the "device" argument which should be
7461 the device name of the disk partition or volume containing the
7462 filesystem. If given the name of a block device, "xfs_repair" will
7463 attempt to find the raw device associated with the specified block
7464 device and will use the raw device instead.
7465 Regardless, the filesystem to be repaired must be unmounted, otherwise,
7467 the resulting filesystem may be inconsistent or corrupt.
7468 The returned status indicates whether filesystem corruption was
7470 detected (returns 1) or was not detected (returns 0).
7471 This command has one or more optional arguments. See "OPTIONAL
7473 ARGUMENTS".
7474 zegrep
7476 zegrep regex path
7477 This calls the external "zegrep" program and returns the matching
7479 lines.
7480 Because of the message protocol, there is a transfer limit of somewhere
7482 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7483 This function is deprecated. In new code, use the "grep" call instead.
7485 Deprecated functions will not be removed from the API, but the fact
7487 that they are deprecated indicates that there are problems with correct
7488 use of these functions.
7489 zegrepi
7491 zegrepi regex path
7492 This calls the external "zegrep -i" program and returns the matching
7494 lines.
7495 Because of the message protocol, there is a transfer limit of somewhere
7497 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7498 This function is deprecated. In new code, use the "grep" call instead.
7500 Deprecated functions will not be removed from the API, but the fact
7502 that they are deprecated indicates that there are problems with correct
7503 use of these functions.
7504 zero
7506 zero device
7507 This command writes zeroes over the first few blocks of "device".
7509 How many blocks are zeroed isn't specified (but it's not enough to
7511 securely wipe the device). It should be sufficient to remove any
7512 partition tables, filesystem superblocks and so on.
7513 If blocks are already zero, then this command avoids writing zeroes.
7515 This prevents the underlying device from becoming non-sparse or growing
7516 unnecessarily.
7517 See also: "zero-device", "scrub-device", "is-zero-device"
7519 zero-device
7521 zero-device device
7522 This command writes zeroes over the entire "device". Compare with
7524 "zero" which just zeroes the first few blocks of a device.
7525 If blocks are already zero, then this command avoids writing zeroes.
7527 This prevents the underlying device from becoming non-sparse or growing
7528 unnecessarily.
7529 zero-free-space
7531 zero-free-space directory
7532 Zero the free space in the filesystem mounted on "directory". The
7534 filesystem must be mounted read-write.
7535 The filesystem contents are not affected, but any free space in the
7537 filesystem is freed.
7538 Free space is not "trimmed". You may want to call "fstrim" either as
7540 an alternative to this, or after calling this, depending on your
7541 requirements.
7542 zerofree
7544 zerofree device
7545 This runs the zerofree program on "device". This program claims to
7547 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
7548 it possible to compress the filesystem more effectively.
7549 You should not run this program if the filesystem is mounted.
7551 It is possible that using this program can damage the filesystem or
7553 data on the filesystem.
7554 zfgrep
7556 zfgrep pattern path
7557 This calls the external "zfgrep" program and returns the matching
7559 lines.
7560 Because of the message protocol, there is a transfer limit of somewhere
7562 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7563 This function is deprecated. In new code, use the "grep" call instead.
7565 Deprecated functions will not be removed from the API, but the fact
7567 that they are deprecated indicates that there are problems with correct
7568 use of these functions.
7569 zfgrepi
7571 zfgrepi pattern path
7572 This calls the external "zfgrep -i" program and returns the matching
7574 lines.
7575 Because of the message protocol, there is a transfer limit of somewhere
7577 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7578 This function is deprecated. In new code, use the "grep" call instead.
7580 Deprecated functions will not be removed from the API, but the fact
7582 that they are deprecated indicates that there are problems with correct
7583 use of these functions.
7584 zfile
7586 zfile meth path
7587 This command runs "file" after first decompressing "path" using
7589 "method".
7590 "method" must be one of "gzip", "compress" or "bzip2".
7592 Since 1.0.63, use "file" instead which can now process compressed
7594 files.
7595 This function is deprecated. In new code, use the "file" call instead.
7597 Deprecated functions will not be removed from the API, but the fact
7599 that they are deprecated indicates that there are problems with correct
7600 use of these functions.
7601 zgrep
7603 zgrep regex path
7604 This calls the external "zgrep" program and returns the matching lines.
7606 Because of the message protocol, there is a transfer limit of somewhere
7608 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7609 This function is deprecated. In new code, use the "grep" call instead.
7611 Deprecated functions will not be removed from the API, but the fact
7613 that they are deprecated indicates that there are problems with correct
7614 use of these functions.
7615 zgrepi
7617 zgrepi regex path
7618 This calls the external "zgrep -i" program and returns the matching
7620 lines.
7621 Because of the message protocol, there is a transfer limit of somewhere
7623 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7624 This function is deprecated. In new code, use the "grep" call instead.
7626 Deprecated functions will not be removed from the API, but the fact
7628 that they are deprecated indicates that there are problems with correct
7629 use of these functions.
7630
7632 guestfish returns 0 if the commands completed without error, or 1 if
7633 there was an error.
7634
7636 EDITOR
7637 The "edit" command uses $EDITOR as the editor. If not set, it uses
7638 "vi".
7639 FEBOOTSTRAP_KERNEL
7641 FEBOOTSTRAP_MODULES
7642 When using supermin ≥ 4.1.0, these have been renamed
7643 "SUPERMIN_KERNEL" and "SUPERMIN_MODULES".
7644 GUESTFISH_DISPLAY_IMAGE
7646 The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
7647 images. If not set, it uses display(1).
7648 GUESTFISH_PID
7650 Used with the --remote option to specify the remote guestfish
7651 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
7652 SOCKET".
7653 GUESTFISH_PS1
7655 Set the command prompt. See "PROMPT".
7656 HEXEDITOR
7658 The "hexedit" command uses $HEXEDITOR as the external hex editor.
7659 If not set, then an error message is printed.
7660 HOME
7662 If compiled with GNU readline support, various files in the home
7663 directory can be used. See "FILES".
7664 LIBGUESTFS_APPEND
7666 Pass additional options to the guest kernel.
7667 LIBGUESTFS_ATTACH_METHOD
7669 Choose the default way to create the appliance. See
7670 "guestfs_set_attach_method" in guestfs(3).
7671 LIBGUESTFS_CACHEDIR
7673 The location where libguestfs will cache its appliance, when using
7674 a supermin appliance. The appliance is cached and shared between
7675 all handles which have the same effective user ID.
7676 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
7678 "TMPDIR" is not set, then "/var/tmp" is used.
7679 See also "LIBGUESTFS_TMPDIR", "set-cachedir".
7681 LIBGUESTFS_DEBUG
7683 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
7684 same effect as using the -v option.
7685 LIBGUESTFS_MEMSIZE
7687 Set the memory allocated to the qemu process, in megabytes. For
7688 example:
7689 LIBGUESTFS_MEMSIZE=700
7691 LIBGUESTFS_PATH
7693 Set the path that guestfish uses to search for kernel and
7694 initrd.img. See the discussion of paths in guestfs(3).
7695 LIBGUESTFS_QEMU
7697 Set the default qemu binary that libguestfs uses. If not set, then
7698 the qemu which was found at compile time by the configure script is
7699 used.
7700 LIBGUESTFS_TMPDIR
7702 The location where libguestfs will store temporary files used by
7703 each handle.
7704 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
7706 "TMPDIR" is not set, then "/tmp" is used.
7707 See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
7709 LIBGUESTFS_TRACE
7711 Set "LIBGUESTFS_TRACE=1" to enable command traces.
7712 PAGER
7714 The "more" command uses $PAGER as the pager. If not set, it uses
7715 "more".
7716 PATH
7718 Libguestfs and guestfish may run some external programs, and rely
7719 on $PATH being set to a reasonable value. If using the libvirt
7720 attach-method, libvirt will not work at all unless $PATH contains
7721 the path of qemu/KVM.
7722 SUPERMIN_KERNEL
7724 SUPERMIN_MODULES
7725 These two environment variables allow the kernel that libguestfs
7726 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
7727 set, then the most recent host kernel is chosen. For more
7728 information about kernel selection, see supermin-helper(8). This
7729 feature is only available in supermin / febootstrap ≥ 3.8.
7730 TMPDIR
7732 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
7733
7735 $HOME/.libguestfs-tools.rc
7736 /etc/libguestfs-tools.conf
7737 This configuration file controls the default read-only or read-
7738 write mode (--ro or --rw).
7739 See "OPENING DISKS FOR READ AND WRITE".
7741 $HOME/.guestfish
7743 If compiled with GNU readline support, then the command history is
7744 saved in this file.
7745 $HOME/.inputrc
7747 /etc/inputrc
7748 If compiled with GNU readline support, then these files can be used
7749 to configure readline. For further information, please see
7750 "INITIALIZATION FILE" in readline(3).
7751 To write rules which only apply to guestfish, use:
7753 $if guestfish
7755 ...
7756 $endif
7757 Variables that you can set in inputrc that change the behaviour of
7759 guestfish in useful ways include:
7760 completion-ignore-case (default: on)
7762 By default, guestfish will ignore case when tab-completing
7763 paths on the disk. Use:
7764 set completion-ignore-case off
7766 to make guestfish case sensitive.
7768 test1.img
7770 test2.img (etc)
7771 When using the -N or --new option, the prepared disk or filesystem
7772 will be created in the file "test1.img" in the current directory.
7773 The second use of -N will use "test2.img" and so on. Any existing
7774 file with the same name will be overwritten.
7775
7777 guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
7778 virt-cat(1), virt-copy-in(1), virt-copy-out(1), virt-df(1),
7779 virt-edit(1), virt-filesystems(1), virt-inspector(1),
7780 virt-list-filesystems(1), virt-list-partitions(1), virt-ls(1),
7781 virt-make-fs(1), virt-rescue(1), virt-resize(1), virt-sparsify(1),
7782 virt-sysprep(1), virt-tar(1), virt-tar-in(1), virt-tar-out(1),
7783 virt-win-reg(1), display(1), hexedit(1), supermin-helper(8).
7784
7786 Richard W.M. Jones ("rjones at redhat dot com")
7787
7789 Copyright (C) 2009-2013 Red Hat Inc.
7790
7792 This program is free software; you can redistribute it and/or modify it
7793 under the terms of the GNU General Public License as published by the
7794 Free Software Foundation; either version 2 of the License, or (at your
7795 option) any later version.
7796 This program is distributed in the hope that it will be useful, but
7798 WITHOUT ANY WARRANTY; without even the implied warranty of
7799 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7800 General Public License for more details.
7801 You should have received a copy of the GNU General Public License along
7803 with this program; if not, write to the Free Software Foundation, Inc.,
7804 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
7805
7807 To get a list of bugs against libguestfs, use this link:
7808 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
7809 To report a new bug against libguestfs, use this link:
7811 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
7812 When reporting a bug, please supply:
7814 · The version of libguestfs.
7816 · Where you got libguestfs (eg. which Linux distro, compiled from
7818 source, etc)
7819 · Describe the bug accurately and give a way to reproduce it.
7821 · Run libguestfs-test-tool(1) and paste the complete, unedited output
7823 into the bug report.
7824libguestfs-1.20.11 2013-08-27 guestfish(1)