1guestfish(1) Virtualization Support guestfish(1)
2
6 guestfish - the guest filesystem 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 write mode on live virtual machines, or
25 concurrently with other disk editing tools, can be dangerous,
26 potentially causing disk corruption. The virtual machine must be shut
27 down before you use this command, and disk images must not be edited
28 concurrently.
29 Use the --ro (read-only) option to use "guestfish" safely if the disk
31 image or virtual machine might be live. You may see strange or
32 inconsistent results if running concurrently with other changes, but
33 with this option you won't risk disk corruption.
34
36 Guestfish is a shell and command-line tool for examining and modifying
37 virtual machine filesystems. It uses libguestfs and exposes all of the
38 functionality of the guestfs API, see guestfs(3).
39 Guestfish gives you structured access to the libguestfs API, from shell
41 scripts or the command line or interactively. If you want to rescue a
42 broken virtual machine image, you should look at the virt-rescue(1)
43 command.
44
46 As an interactive shell
47 $ guestfish
48 Welcome to guestfish, the guest filesystem shell for
50 editing virtual machine filesystems.
51 Type: 'help' for a list of commands
53 'man' to read the manual
54 'quit' to quit the shell
55 ><fs> add-ro disk.img
57 ><fs> run
58 ><fs> list-filesystems
59 /dev/sda1: ext4
60 /dev/vg_guest/lv_root: ext4
61 /dev/vg_guest/lv_swap: swap
62 ><fs> mount /dev/vg_guest/lv_root /
63 ><fs> cat /etc/fstab
64 # /etc/fstab
65 # Created by anaconda
66 [...]
67 ><fs> exit
68 From shell scripts
70 Create a new /etc/motd file in a guest or disk image:
71 guestfish <<_EOF_
73 add disk.img
74 run
75 mount /dev/vg_guest/lv_root /
76 write /etc/motd "Welcome, new users"
77 _EOF_
78 List the LVM logical volumes in a disk image:
80 guestfish -a disk.img --ro <<_EOF_
82 run
83 lvs
84 _EOF_
85 List all the filesystems in a disk image:
87 guestfish -a disk.img --ro <<_EOF_
89 run
90 list-filesystems
91 _EOF_
92 On one command line
94 Update /etc/resolv.conf in a guest:
95 guestfish \
97 add disk.img : run : mount /dev/vg_guest/lv_root / : \
98 write /etc/resolv.conf "nameserver 1.2.3.4"
99 Edit /boot/grub/grub.conf interactively:
101 guestfish --rw --add disk.img \
103 --mount /dev/vg_guest/lv_root \
104 --mount /dev/sda1:/boot \
105 edit /boot/grub/grub.conf
106 Mount disks automatically
108 Use the -i option to automatically mount the disks from a virtual
109 machine:
110 guestfish --ro -a disk.img -i cat /etc/group
112 guestfish --ro -d libvirt-domain -i cat /etc/group
114 Another way to edit /boot/grub/grub.conf interactively is:
116 guestfish --rw -a disk.img -i edit /boot/grub/grub.conf
118 As a script interpreter
120 Create a 100MB disk containing an ext2-formatted partition:
121 #!/usr/bin/guestfish -f
123 sparse test1.img 100M
124 run
125 part-disk /dev/sda mbr
126 mkfs ext2 /dev/sda1
127 Start with a prepared disk
129 Create a 1G disk called test1.img containing a single ext2-formatted
130 partition:
131 guestfish -N fs
133 To list what is available do:
135 guestfish -N help | less
137 Remote drives
139 Access a remote disk using ssh:
140 guestfish -a ssh://example.com/path/to/disk.img
142 Remote control
144 eval "`guestfish --listen`"
145 guestfish --remote add-ro disk.img
146 guestfish --remote run
147 guestfish --remote lvs
148
150 --help
151 Displays general help on options.
152 -h
154 --cmd-help
155 Lists all available guestfish commands.
156 -h CMD
158 --cmd-help CMD
159 Displays detailed help on a single command "cmd".
160 -a IMAGE
162 --add IMAGE
163 Add a block device or virtual machine image to the shell.
164 The format of the disk image is auto-detected. To override this
166 and force a particular format use the --format=.. option.
167 Using this flag is mostly equivalent to using the "add" command,
169 with "readonly:true" if the --ro flag was given, and with
170 "format:..." if the --format=... flag was given.
171 -a URI
173 --add URI
174 Add a remote disk. See "ADDING REMOTE STORAGE".
175 --blocksize=512
177 --blocksize=4096
178 --blocksize
179 This parameter sets the sector size of the disk image. It affects
180 all explicitly added subsequent disks after this parameter. Using
181 --blocksize with no argument switches the disk sector size to the
182 default value which is usually 512 bytes. See also
183 "guestfs_add_drive_opts" in guestfs(3).
184 -c URI
186 --connect URI
187 When used in conjunction with the -d option, this specifies the
188 libvirt URI to use. The default is to use the default libvirt
189 connection.
190 --csh
192 If using the --listen option and a csh-like shell, use this option.
193 See section "REMOTE CONTROL AND CSH" below.
194 -d LIBVIRT-DOMAIN
196 --domain LIBVIRT-DOMAIN
197 Add disks from the named libvirt domain. If the --ro option is
198 also used, then any libvirt domain can be used. However in write
199 mode, only libvirt domains which are shut down can be named here.
200 Domain UUIDs can be used instead of names.
202 Using this flag is mostly equivalent to using the "add-domain"
204 command, with "readonly:true" if the --ro flag was given, and with
205 "format:..." if the --format=... flag was given.
206 --echo-keys
208 When prompting for keys and passphrases, guestfish normally turns
209 echoing off so you cannot see what you are typing. If you are not
210 worried about Tempest attacks and there is no one else in the room
211 you can specify this flag to see what you are typing.
212 -f FILE
214 --file FILE
215 Read commands from "FILE". To write pure guestfish scripts, use:
216 #!/usr/bin/guestfish -f
218 --format=raw|qcow2|..
220 --format
221 The default for the -a option is to auto-detect the format of the
222 disk image. Using this forces the disk format for -a options which
223 follow on the command line. Using --format with no argument
224 switches back to auto-detection for subsequent -a options.
225 For example:
227 guestfish --format=raw -a disk.img
229 forces raw format (no auto-detection) for disk.img.
231 guestfish --format=raw -a disk.img --format -a another.img
233 forces raw format (no auto-detection) for disk.img and reverts to
235 auto-detection for another.img.
236 If you have untrusted raw-format guest disk images, you should use
238 this option to specify the disk format. This avoids a possible
239 security problem with malicious guests (CVE-2010-3851). See also
240 "add".
241 -i
243 --inspector
244 Using virt-inspector(1) code, inspect the disks looking for an
245 operating system and mount filesystems as they would be mounted on
246 the real virtual machine.
247 Typical usage is either:
249 guestfish -d myguest -i
251 (for an inactive libvirt domain called myguest), or:
253 guestfish --ro -d myguest -i
255 (for active domains, readonly), or specify the block device
257 directly:
258 guestfish --rw -a /dev/Guests/MyGuest -i
260 Note that the command line syntax changed slightly over older
262 versions of guestfish. You can still use the old syntax:
263 guestfish [--ro] -i disk.img
265 guestfish [--ro] -i libvirt-domain
267 Using this flag is mostly equivalent to using the "inspect-os"
269 command and then using other commands to mount the filesystems that
270 were found.
271 --key SELECTOR
273 Specify a key for LUKS, to automatically open a LUKS device when
274 using the inspection. "ID" can be either the libguestfs device
275 name, or the UUID of the LUKS device.
276 --key "ID":key:KEY_STRING
278 Use the specified "KEY_STRING" as passphrase.
279 --key "ID":file:FILENAME
281 Read the passphrase from FILENAME.
282 --keys-from-stdin
284 Read key or passphrase parameters from stdin. The default is to
285 try to read passphrases from the user by opening /dev/tty.
286 --listen
288 Fork into the background and listen for remote commands. See
289 section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
290 --live
292 Connect to a live virtual machine. (Experimental, see "ATTACHING
293 TO RUNNING DAEMONS" in guestfs(3)).
294 -m dev[:mountpoint[:options[:fstype]]]
296 --mount dev[:mountpoint[:options[:fstype]]]
297 Mount the named partition or logical volume on the given
298 mountpoint.
299 If the mountpoint is omitted, it defaults to /.
301 You have to mount something on / before most commands will work.
303 If any -m or --mount options are given, the guest is automatically
305 launched.
306 If you don’t know what filesystems a disk image contains, you can
308 either run guestfish without this option, then list the partitions,
309 filesystems and LVs available (see "list-partitions", "list-
310 filesystems" and "lvs" commands), or you can use the
311 virt-filesystems(1) program.
312 The third (and rarely used) part of the mount parameter is the list
314 of mount options used to mount the underlying filesystem. If this
315 is not given, then the mount options are either the empty string or
316 "ro" (the latter if the --ro flag is used). By specifying the
317 mount options, you override this default choice. Probably the only
318 time you would use this is to enable ACLs and/or extended
319 attributes if the filesystem can support them:
320 -m /dev/sda1:/:acl,user_xattr
322 Using this flag is equivalent to using the "mount-options" command.
324 The fourth part of the parameter is the filesystem driver to use,
326 such as "ext3" or "ntfs". This is rarely needed, but can be useful
327 if multiple drivers are valid for a filesystem (eg: "ext2" and
328 "ext3"), or if libguestfs misidentifies a filesystem.
329 --network
331 Enable QEMU user networking in the guest.
332 -N [FILENAME=]TYPE
334 --new [FILENAME=]TYPE
335 -N help
336 Prepare a fresh disk image formatted as "TYPE". This is an
337 alternative to the -a option: whereas -a adds an existing disk, -N
338 creates a preformatted disk with a filesystem and adds it. See
339 "PREPARED DISK IMAGES" below.
340 -n
342 --no-sync
343 Disable autosync. This is enabled by default. See the discussion
344 of autosync in the guestfs(3) manpage.
345 --no-dest-paths
347 Don’t tab-complete paths on the guest filesystem. It is useful to
348 be able to hit the tab key to complete paths on the guest
349 filesystem, but this causes extra "hidden" guestfs calls to be
350 made, so this option is here to allow this feature to be disabled.
351 --pipe-error
353 If writes fail to pipe commands (see "PIPES" below), then the
354 command returns an error.
355 The default (also for historical reasons) is to ignore such errors
357 so that:
358 ><fs> command_with_lots_of_output | head
360 doesn't give an error.
362 --progress-bars
364 Enable progress bars, even when guestfish is used non-
365 interactively.
366 Progress bars are enabled by default when guestfish is used as an
368 interactive shell.
369 --no-progress-bars
371 Disable progress bars.
372 --remote
374 --remote=PID
375 Send remote commands to $GUESTFISH_PID or "pid". See section
376 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
377 -r
379 --ro
380 This changes the -a, -d and -m options so that disks are added and
381 mounts are done read-only.
382 The option must always be used if the disk image or virtual machine
384 might be running, and is generally recommended in cases where you
385 don't need write access to the disk.
386 Note that prepared disk images created with -N are not affected by
388 this option. Also commands like "add" are not affected - you have
389 to specify the "readonly:true" option explicitly if you need it.
390 See also "OPENING DISKS FOR READ AND WRITE" below.
392 --selinux
394 This option is provided for backwards compatibility and does
395 nothing.
396 -v
398 --verbose
399 Enable very verbose messages. This is particularly useful if you
400 find a bug.
401 -V
403 --version
404 Display the guestfish / libguestfs version number and exit.
405 -w
407 --rw
408 This changes the -a, -d and -m options so that disks are added and
409 mounts are done read-write.
410 See "OPENING DISKS FOR READ AND WRITE" below.
412 -x Echo each command before executing it.
414
416 Any additional (non-option) arguments are treated as commands to
417 execute.
418 Commands to execute should be separated by a colon (":"), where the
420 colon is a separate parameter. Thus:
421 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
423 If there are no additional arguments, then we enter a shell, either an
425 interactive shell with a prompt (if the input is a terminal) or a non-
426 interactive shell.
427 In either command line mode or non-interactive shell, the first command
429 that gives an error causes the whole shell to exit. In interactive
430 mode (with a prompt) if a command fails, you can continue to enter
431 commands.
432 Note that arguments of the commands will be considered as guestfish
434 options if they start with a dash ("-"): you can always separate the
435 guestfish options and the rest of the commands (with their arguments)
436 using a double dash ("--"). For example:
437 guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img
439
441 As with guestfs(3), you must first configure your guest by adding
442 disks, then launch it, then mount any disks you need, and finally issue
443 actions/commands. So the general order of the day is:
444 · add or -a/--add
446 · launch (aka run)
448 · mount or -m/--mount
450 · any other commands
452 "run" is a synonym for "launch". You must "launch" (or "run") your
454 guest before mounting or performing any other commands.
455 The only exception is that if any of the -i, -m, --mount, -N or --new
457 options were given then "run" is done automatically, simply because
458 guestfish can't perform the action you asked for without doing this.
459
461 The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
462 affect whether the other command line options -a, -c, -d, -i and -m
463 open disk images read-only or for writing.
464 In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
466 to opening disk images supplied on the command line for write. To open
467 a disk image read-only you have to do -a image --ro.
468 This matters: If you accidentally open a live VM disk image writable
470 then you will cause irreversible disk corruption.
471 In a future libguestfs we intend to change the default the other way.
473 Disk images will be opened read-only. You will have to either specify
474 guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
475 configuration file in order to get write access for disk images
476 specified by those other command line options.
477 This version of guestfish, guestmount and virt-rescue has a --rw option
479 which does nothing (it is already the default). However it is highly
480 recommended that you use this option to indicate that you need write
481 access, and prepare your scripts for the day when this option will be
482 required for write access.
483 Note: This does not affect commands like "add" and "mount", or any
485 other libguestfs program apart from guestfish and guestmount.
486
488 You can quote ordinary parameters using either single or double quotes.
489 For example:
490 add "file with a space.img"
492 rm '/file name'
494 rm '/"'
496 A few commands require a list of strings to be passed. For these, use
498 a whitespace-separated list, enclosed in quotes. Strings containing
499 whitespace to be passed through must be enclosed in single quotes. A
500 literal single quote must be escaped with a backslash.
501 vgcreate VG "/dev/sda1 /dev/sdb1"
503 command "/bin/echo 'foo bar'"
504 command "/bin/echo \'foo\'"
505 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
507 In double-quoted arguments (only) use backslash to insert special
508 characters:
509 "\a"
511 Alert (bell) character.
512 "\b"
514 Backspace character.
515 "\f"
517 Form feed character.
518 "\n"
520 Newline character.
521 "\r"
523 Carriage return character.
524 "\t"
526 Horizontal tab character.
527 "\v"
529 Vertical tab character.
530 "\""
532 A literal double quote character.
533 "\ooo"
535 A character with octal value ooo. There must be precisely 3 octal
536 digits (unlike C).
537 "\xhh"
539 A character with hex value hh. There must be precisely 2 hex
540 digits.
541 In the current implementation "\000" and "\x00" cannot be used in
543 strings.
544 "\\"
546 A literal backslash character.
547
549 Some commands take optional arguments. These arguments appear in this
550 documentation as "[argname:..]". You can use them as in these
551 examples:
552 add filename
554 add filename readonly:true
556 add filename format:qcow2 readonly:false
558 Each optional argument can appear at most once. All optional arguments
560 must appear after the required ones.
561
563 This section applies to all commands which can take integers as
564 parameters.
565 SIZE SUFFIX
567 When the command takes a parameter measured in bytes, you can use one
568 of the following suffixes to specify kilobytes, megabytes and larger
569 sizes:
570 k or K or KiB
572 The size in kilobytes (multiplied by 1024).
573 KB The size in SI 1000 byte units.
575 M or MiB
577 The size in megabytes (multiplied by 1048576).
578 MB The size in SI 1000000 byte units.
580 G or GiB
582 The size in gigabytes (multiplied by 2**30).
583 GB The size in SI 10**9 byte units.
585 T or TiB
587 The size in terabytes (multiplied by 2**40).
588 TB The size in SI 10**12 byte units.
590 P or PiB
592 The size in petabytes (multiplied by 2**50).
593 PB The size in SI 10**15 byte units.
595 E or EiB
597 The size in exabytes (multiplied by 2**60).
598 EB The size in SI 10**18 byte units.
600 Z or ZiB
602 The size in zettabytes (multiplied by 2**70).
603 ZB The size in SI 10**21 byte units.
605 Y or YiB
607 The size in yottabytes (multiplied by 2**80).
608 YB The size in SI 10**24 byte units.
610 For example:
612 truncate-size /file 1G
614 would truncate the file to 1 gigabyte.
616 Be careful because a few commands take sizes in kilobytes or megabytes
618 (eg. the parameter to "memsize" is specified in megabytes already).
619 Adding a suffix will probably not do what you expect.
620 OCTAL AND HEXADECIMAL NUMBERS
622 For specifying the radix (base) use the C convention: 0 to prefix an
623 octal number or "0x" to prefix a hexadecimal number. For example:
624 1234 decimal number 1234
626 02322 octal number, equivalent to decimal 1234
627 0x4d2 hexadecimal number, equivalent to decimal 1234
628 When using the "chmod" command, you almost always want to specify an
630 octal number for the mode, and you must prefix it with 0 (unlike the
631 Unix chmod(1) program):
632 chmod 0777 /public # OK
634 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
635 Commands that return numbers usually print them in decimal, but some
637 commands print numbers in other radices (eg. "umask" prints the mode in
638 octal, preceded by 0).
639
641 Neither guestfish nor the underlying guestfs API performs wildcard
642 expansion (globbing) by default. So for example the following will not
643 do what you expect:
644 rm-rf /home/*
646 Assuming you don’t have a directory called literally /home/* then the
648 above command will return an error.
649 To perform wildcard expansion, use the "glob" command.
651 glob rm-rf /home/*
653 runs "rm-rf" on each path that matches (ie. potentially running the
655 command many times), equivalent to:
656 rm-rf /home/jim
658 rm-rf /home/joe
659 rm-rf /home/mary
660 "glob" only works on simple guest paths and not on device names.
662 If you have several parameters, each containing a wildcard, then glob
664 will perform a Cartesian product.
665
667 Any line which starts with a # character is treated as a comment and
668 ignored. The # can optionally be preceded by whitespace, but not by a
669 command. For example:
670 # this is a comment
672 # this is a comment
673 foo # NOT a comment
674 Blank lines are also ignored.
676
678 Any line which starts with a ! character is treated as a command sent
679 to the local shell (/bin/sh or whatever system(3) uses). For example:
680 !mkdir local
682 tgz-out /remote local/remote-data.tar.gz
683 will create a directory "local" on the host, and then export the
685 contents of /remote on the mounted filesystem to
686 local/remote-data.tar.gz. (See "tgz-out").
687 To change the local directory, use the "lcd" command. "!cd" will have
689 no effect, due to the way that subprocesses work in Unix.
690 LOCAL COMMANDS WITH INLINE EXECUTION
692 If a line starts with <! then the shell command is executed (as for !),
693 but subsequently any output (stdout) of the shell command is parsed and
694 executed as guestfish commands.
695 Thus you can use shell script to construct arbitrary guestfish commands
697 which are then parsed by guestfish.
698 For example it is tedious to create a sequence of files (eg. /foo.1
700 through /foo.100) using guestfish commands alone. However this is
701 simple if we use a shell script to create the guestfish commands for
702 us:
703 <! for n in `seq 1 100`; do echo write /foo.$n $n; done
705 or with names like /foo.001:
707 <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
709 When using guestfish interactively it can be helpful to just run the
711 shell script first (ie. remove the initial "<" character so it is just
712 an ordinary ! local command), see what guestfish commands it would run,
713 and when you are happy with those prepend the "<" character to run the
714 guestfish commands for real.
715
717 Use "command <space> | command" to pipe the output of the first command
718 (a guestfish command) to the second command (any host command). For
719 example:
720 cat /etc/passwd | awk -F: '$3 == 0 { print }'
722 (where "cat" is the guestfish cat command, but "awk" is the host awk
724 program). The above command would list all accounts in the guest
725 filesystem which have UID 0, ie. root accounts including backdoors.
726 Other examples:
727 hexdump /bin/ls | head
729 list-devices | tail -1
730 tgz-out / - | tar ztf -
731 The space before the pipe symbol is required, any space after the pipe
733 symbol is optional. Everything after the pipe symbol is just passed
734 straight to the host shell, so it can contain redirections, globs and
735 anything else that makes sense on the host side.
736 To use a literal argument which begins with a pipe symbol, you have to
738 quote it, eg:
739 echo "|"
741
743 If a parameter starts with the character "~" then the tilde may be
744 expanded as a home directory path (either "~" for the current user's
745 home directory, or "~user" for another user).
746 Note that home directory expansion happens for users known on the host,
748 not in the guest filesystem.
749 To use a literal argument which begins with a tilde, you have to quote
751 it, eg:
752 echo "~"
754
756 Libguestfs has some support for Linux guests encrypted according to the
757 Linux Unified Key Setup (LUKS) standard, which includes nearly all
758 whole disk encryption systems used by modern Linux guests. Currently
759 only LVM-on-LUKS is supported.
760 Identify encrypted block devices and partitions using "vfs-type":
762 ><fs> vfs-type /dev/sda2
764 crypto_LUKS
765 Then open those devices using "luks-open". This creates a device-
767 mapper device called /dev/mapper/luksdev.
768 ><fs> luks-open /dev/sda2 luksdev
770 Enter key or passphrase ("key"): <enter the passphrase>
771 Finally you have to tell LVM to scan for volume groups on the newly
773 created mapper device:
774 vgscan
776 vg-activate-all true
777 The logical volume(s) can now be mounted in the usual way.
779 Before closing a LUKS device you must unmount any logical volumes on it
781 and deactivate the volume groups by calling "vg-activate false VG" on
782 each one. Then you can close the mapper device:
783 vg-activate false /dev/VG
785 luks-close /dev/mapper/luksdev
786
788 If a path is prefixed with "win:" then you can use Windows-style drive
789 letters and paths (with some limitations). The following commands are
790 equivalent:
791 file /WINDOWS/system32/config/system.LOG
793 file win:\windows\system32\config\system.log
795 file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
797 The parameter is rewritten "behind the scenes" by looking up the
799 position where the drive is mounted, prepending that to the path,
800 changing all backslash characters to forward slash, then resolving the
801 result using "case-sensitive-path". For example if the E: drive was
802 mounted on /e then the parameter might be rewritten like this:
803 win:e:\foo\bar => /e/FOO/bar
805 This only works in argument positions that expect a path.
807
809 For commands such as "upload", "download", "tar-in", "tar-out" and
810 others which upload from or download to a local file, you can use the
811 special filename "-" to mean "from stdin" or "to stdout". For example:
812 upload - /foo
814 reads stdin and creates from that a file /foo in the disk image, and:
816 tar-out /etc - | tar tf -
818 writes the tarball to stdout and then pipes that into the external
820 "tar" command (see "PIPES").
821 When using "-" to read from stdin, the input is read up to the end of
823 stdin. You can also use a special "heredoc"-like syntax to read up to
824 some arbitrary end marker:
825 upload -<<END /foo
827 input line 1
828 input line 2
829 input line 3
830 END
831 Any string of characters can be used instead of "END". The end marker
833 must appear on a line of its own, without any preceding or following
834 characters (not even spaces).
835 Note that the "-<<" syntax only applies to parameters used to upload
837 local files (so-called "FileIn" parameters in the generator).
838
840 By default, guestfish will ignore any errors when in interactive mode
841 (ie. taking commands from a human over a tty), and will exit on the
842 first error in non-interactive mode (scripts, commands given on the
843 command line).
844 If you prefix a command with a - character, then that command will not
846 cause guestfish to exit, even if that (one) command returns an error.
847
849 Guestfish can be remote-controlled over a socket. This is useful
850 particularly in shell scripts where you want to make several different
851 changes to a filesystem, but you don't want the overhead of starting up
852 a guestfish process each time.
853 Start a guestfish server process using:
855 eval "`guestfish --listen`"
857 and then send it commands by doing:
859 guestfish --remote cmd [...]
861 To cause the server to exit, send it the exit command:
863 guestfish --remote exit
865 Note that the server will normally exit if there is an error in a
867 command. You can change this in the usual way. See section "EXIT ON
868 ERROR BEHAVIOUR".
869 CONTROLLING MULTIPLE GUESTFISH PROCESSES
871 The "eval" statement sets the environment variable $GUESTFISH_PID,
872 which is how the --remote option knows where to send the commands. You
873 can have several guestfish listener processes running using:
874 eval "`guestfish --listen`"
876 pid1=$GUESTFISH_PID
877 eval "`guestfish --listen`"
878 pid2=$GUESTFISH_PID
879 ...
880 guestfish --remote=$pid1 cmd
881 guestfish --remote=$pid2 cmd
882 REMOTE CONTROL AND CSH
884 When using csh-like shells (csh, tcsh etc) you have to add the --csh
885 option:
886 eval "`guestfish --listen --csh`"
888 REMOTE CONTROL DETAILS
890 Remote control happens over a Unix domain socket called
891 /tmp/.guestfish-$UID/socket-$PID, where $UID is the effective user ID
892 of the process, and $PID is the process ID of the server.
893 Guestfish client and server versions must match exactly.
895 Older versions of guestfish were vulnerable to CVE-2013-4419 (see
897 "CVE-2013-4419" in guestfs(3)). This is fixed in the current version.
898 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
900 From Bash, you can use the following code which creates a guestfish
901 instance, correctly quotes the command line, handles failure to start,
902 and cleans up guestfish when the script exits:
903 #!/bin/bash -
905 set -e
907 guestfish[0]="guestfish"
909 guestfish[1]="--listen"
910 guestfish[2]="--ro"
911 guestfish[3]="-a"
912 guestfish[4]="disk.img"
913 GUESTFISH_PID=
915 eval $("${guestfish[@]}")
916 if [ -z "$GUESTFISH_PID" ]; then
917 echo "error: guestfish didn't start up, see error messages above"
918 exit 1
919 fi
920 cleanup_guestfish ()
922 {
923 guestfish --remote -- exit >/dev/null 2>&1 ||:
924 }
925 trap cleanup_guestfish EXIT ERR
926 guestfish --remote -- run
928 # ...
930 REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
932 Options such as -a, --add, -N, --new etc don’t interact properly with
933 remote support. They are processed locally, and not sent through to
934 the remote guestfish. In particular this won't do what you expect:
935 guestfish --remote --add disk.img
937 Don’t use these options. Use the equivalent commands instead, eg:
939 guestfish --remote add-drive disk.img
941 or:
943 guestfish --remote
945 ><fs> add disk.img
946 REMOTE CONTROL RUN COMMAND HANGING
948 Using the "run" (or "launch") command remotely in a command
949 substitution context hangs, ie. don't do (note the backquotes):
950 a=`guestfish --remote run`
952 Since the "run" command produces no output on stdout, this is not
954 useful anyway. For further information see
955 https://bugzilla.redhat.com/show_bug.cgi?id=592910.
956
958 Use the -N [filename=]type or --new [filename=]type parameter to select
959 one of a set of preformatted disk images that guestfish can make for
960 you to save typing. This is particularly useful for testing purposes.
961 This option is used instead of the -a option, and like -a can appear
962 multiple times (and can be mixed with -a).
963 The new disk is called test1.img for the first -N, test2.img for the
965 second and so on. Existing files in the current directory are
966 overwritten. You can use a different filename by specifying
967 "filename=" before the type (see examples below).
968 The type briefly describes how the disk should be sized, partitioned,
970 how filesystem(s) should be created, and how content should be added.
971 Optionally the type can be followed by extra parameters, separated by
972 ":" (colon) characters. For example, -N fs creates a default 1G,
973 sparsely-allocated disk, containing a single partition, with the
974 partition formatted as ext2. -N fs:ext4:2G is the same, but for an
975 ext4 filesystem on a 2GB disk instead.
976 Note that the prepared filesystem is not mounted. You would usually
978 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
979 option.
980 If any -N or --new options are given, the libguestfs appliance is
982 automatically launched.
983 EXAMPLES
985 Create a 1G disk with an ext4-formatted partition, called test1.img in
986 the current directory:
987 guestfish -N fs:ext4
989 Create a 32MB disk with a VFAT-formatted partition, and mount it:
991 guestfish -N fs:vfat:32M -m /dev/sda1
993 Create a blank 200MB disk:
995 guestfish -N disk:200M
997 Create a blank 200MB disk called blankdisk.img (instead of test1.img):
999 guestfish -N blankdisk.img=disk:200M
1001 -N disk - create a blank disk
1003 "guestfish -N [filename=]disk[:size]"
1004 Create a blank disk, size 1G (by default).
1006 The default size can be changed by supplying an optional parameter.
1008 The optional parameters are:
1010 Name Default value
1012 size 1G the size of the disk image
1013 -N part - create a partitioned disk
1015 "guestfish -N [filename=]part[:size[:partition]]"
1016 Create a disk with a single partition. By default the size of the disk
1018 is 1G (the available space in the partition will be a tiny bit smaller)
1019 and the partition table will be MBR (old DOS-style).
1020 These defaults can be changed by supplying optional parameters.
1022 The optional parameters are:
1024 Name Default value
1026 size 1G the size of the disk image
1027 partition mbr partition table type
1028 -N fs - create a filesystem
1030 "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"
1031 Create a disk with a single partition, with the partition containing an
1033 empty filesystem. This defaults to creating a 1G disk (the available
1034 space in the filesystem will be a tiny bit smaller) with an MBR (old
1035 DOS-style) partition table and an ext2 filesystem.
1036 These defaults can be changed by supplying optional parameters.
1038 The optional parameters are:
1040 Name Default value
1042 filesystem ext2 the type of filesystem to use
1043 size 1G the size of the disk image
1044 partition mbr partition table type
1045 -N lv - create a disk with logical volume
1047 "guestfish -N [filename=]lv[:name[:size[:partition]]]"
1048 Create a disk with a single partition, set up the partition as an LVM2
1050 physical volume, and place a volume group and logical volume on there.
1051 This defaults to creating a 1G disk with the VG and LV called
1052 "/dev/VG/LV". You can change the name of the VG and LV by supplying an
1053 alternate name as the first optional parameter.
1054 Note this does not create a filesystem. Use 'lvfs' to do that.
1056 The optional parameters are:
1058 Name Default value
1060 name /dev/VG/LV the name of the VG and LV to use
1061 size 1G the size of the disk image
1062 partition mbr partition table type
1063 -N lvfs - create a disk with logical volume and filesystem
1065 "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"
1066 Create a disk with a single partition, set up the partition as an LVM2
1068 physical volume, and place a volume group and logical volume on there.
1069 Then format the LV with a filesystem. This defaults to creating a 1G
1070 disk with the VG and LV called "/dev/VG/LV", with an ext2 filesystem.
1071 The optional parameters are:
1073 Name Default value
1075 name /dev/VG/LV the name of the VG and LV to use
1076 filesystem ext2 the type of filesystem to use
1077 size 1G the size of the disk image
1078 partition mbr partition table type
1079 -N bootroot - create a boot and root filesystem
1081 "guestfish -N
1082 [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"
1083 Create a disk with two partitions, for boot and root filesystem.
1085 Format the two filesystems independently. There are several optional
1086 parameters which control the exact layout and filesystem types.
1087 The optional parameters are:
1089 Name Default value
1091 bootfs ext2 the type of filesystem to use for boot
1092 rootfs ext2 the type of filesystem to use for root
1093 size 1G the size of the disk image
1094 bootsize 128M the size of the boot filesystem
1095 partition mbr partition table type
1096 -N bootrootlv - create a boot and root filesystem using LVM
1098 "guestfish -N
1099 [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"
1100 This is the same as "bootroot" but the root filesystem (only) is placed
1102 on a logical volume, named by default "/dev/VG/LV". There are several
1103 optional parameters which control the exact layout.
1104 The optional parameters are:
1106 Name Default value
1108 name /dev/VG/LV the name of the VG and LV for root
1109 bootfs ext2 the type of filesystem to use for boot
1110 rootfs ext2 the type of filesystem to use for root
1111 size 1G the size of the disk image
1112 bootsize 128M the size of the boot filesystem
1113 partition mbr partition table type
1114
1116 For API-level documentation on this topic, see "guestfs_add_drive_opts"
1117 in guestfs(3) and "REMOTE STORAGE" in guestfs(3).
1118 On the command line, you can use the -a option to add network block
1120 devices using a URI-style format, for example:
1121 guestfish -a ssh://root@example.com/disk.img
1123 URIs cannot be used with the "add" command. The equivalent command
1125 using the API directly is:
1126 ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root
1128 The possible -a URI formats are described below.
1130 -a disk.img
1132 -a file:///path/to/disk.img
1133 Add the local disk image (or device) called disk.img.
1134 -a ftp://[user@]example.com[:port]/disk.img
1136 -a ftps://[user@]example.com[:port]/disk.img
1137 -a http://[user@]example.com[:port]/disk.img
1138 -a https://[user@]example.com[:port]/disk.img
1139 -a tftp://[user@]example.com[:port]/disk.img
1140 Add a disk located on a remote FTP, HTTP or TFTP server.
1141 The equivalent API command would be:
1143 ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com
1145 -a gluster://example.com[:port]/volname/image
1147 Add a disk image located on GlusterFS storage.
1148 The server is the one running "glusterd", and may be "localhost".
1150 The equivalent API command would be:
1152 ><fs> add volname/image protocol:gluster server:tcp:example.com
1154 -a iscsi://example.com[:port]/target-iqn-name[/lun]
1156 Add a disk located on an iSCSI server.
1157 The equivalent API command would be:
1159 ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com
1161 -a nbd://example.com[:port]
1163 -a nbd://example.com[:port]/exportname
1164 -a nbd://?socket=/socket
1165 -a nbd:///exportname?socket=/socket
1166 Add a disk located on Network Block Device (nbd) storage.
1167 The /exportname part of the URI specifies an NBD export name, but is
1169 usually left empty.
1170 The optional ?socket parameter can be used to specify a Unix domain
1172 socket that we talk to the NBD server over. Note that you cannot mix
1173 server name (ie. TCP/IP) and socket path.
1174 The equivalent API command would be (no export name):
1176 ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]
1178 -a rbd:///pool/disk
1180 -a rbd://example.com[:port]/pool/disk
1181 Add a disk image located on a Ceph (RBD/librbd) storage volume.
1182 Although libguestfs and Ceph supports multiple servers, only a single
1184 server can be specified when using this URI syntax.
1185 The equivalent API command would be:
1187 ><fs> add pool/disk protocol:rbd server:tcp:example.com:port
1189 -a sheepdog://[example.com[:port]]/volume/image
1191 Add a disk image located on a Sheepdog volume.
1192 The server name is optional. Although libguestfs and Sheepdog supports
1194 multiple servers, only at most one server can be specified when using
1195 this URI syntax.
1196 The equivalent API command would be:
1198 ><fs> add volume protocol:sheepdog [server:tcp:example.com]
1200 -a ssh://[user@]example.com[:port]/disk.img
1202 Add a disk image located on a remote server, accessed using the Secure
1203 Shell (ssh) SFTP protocol. SFTP is supported out of the box by all
1204 major SSH servers.
1205 The equivalent API command would be:
1207 ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]
1209 Note that the URIs follow the syntax of RFC 3986: in particular, there
1211 are restrictions on the allowed characters for the various components
1212 of the URI. Characters such as ":", "@", and "/" must be percent-
1213 encoded:
1214 $ guestfish -a ssh://user:pass%40word@example.com/disk.img
1216 In this case, the password is "pass@word".
1218
1220 Some (not all) long-running commands send progress notification
1221 messages as they are running. Guestfish turns these messages into
1222 progress bars.
1223 When a command that supports progress bars takes longer than two
1225 seconds to run, and if progress bars are enabled, then you will see one
1226 appearing below the command:
1227 ><fs> copy-size /large-file /another-file 2048M
1229 / 10% [#####-----------------------------------------] 00:30
1230 The spinner on the left hand side moves round once for every progress
1232 notification received from the backend. This is a (reasonably) golden
1233 assurance that the command is "doing something" even if the progress
1234 bar is not moving, because the command is able to send the progress
1235 notifications. When the bar reaches 100% and the command finishes, the
1236 spinner disappears.
1237 Progress bars are enabled by default when guestfish is used
1239 interactively. You can enable them even for non-interactive modes
1240 using --progress-bars, and you can disable them completely using
1241 --no-progress-bars.
1242
1244 You can change or add colours to the default prompt ("><fs>") by
1245 setting the "GUESTFISH_PS1" environment variable. A second string
1246 ("GUESTFISH_OUTPUT") is printed after the command has been entered and
1247 before the output, allowing you to control the colour of the output. A
1248 third string ("GUESTFISH_INIT") is printed before the welcome message,
1249 allowing you to control the colour of that message. A fourth string
1250 ("GUESTFISH_RESTORE") is printed before guestfish exits.
1251 A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate
1253 string:
1254 $ GUESTFISH_PS1='(type a command) '
1256 $ export GUESTFISH_PS1
1257 $ guestfish
1258 [...]
1259 (type a command) ▂
1260 You can also use special escape sequences, as described in the table
1262 below:
1263 \\ A literal backslash character.
1265 \[
1267 \] (These should only be used in "GUESTFISH_PS1".)
1268 Place non-printing characters (eg. terminal control codes for
1270 colours) between "\[...\]". What this does it to tell the
1271 readline(3) library that it should treat this subsequence as zero-
1272 width, so that command-line redisplay, editing etc works.
1273 \a A bell character.
1275 \e An ASCII ESC (escape) character.
1277 \n A newline.
1279 \r A carriage return.
1281 \NNN
1283 The ASCII character whose code is the octal value NNN.
1284 \xNN
1286 The ASCII character whose code is the hex value NN.
1287 EXAMPLES OF PROMPTS
1289 Note that these examples require a terminal that supports ANSI escape
1290 codes.
1291 ·
1293 GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1296 A bold black version of the ordinary prompt.
1298 ·
1300 GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
1303 GUESTFISH_OUTPUT='\e[0m'
1304 GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
1305 GUESTFISH_INIT='\e[1;34m'
1306 Blue welcome text, green prompt, red commands, black command
1308 output.
1309
1311 Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1312 partitions. See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1313 guestfs(3).
1314
1316 The commands in this section are guestfish convenience commands, in
1317 other words, they are not part of the guestfs(3) API.
1318 help
1320 help
1321 help cmd
1322 help -l|--list
1323 Without any parameter, this provides general help.
1325 With a "cmd" parameter, this displays detailed help for that command.
1327 With -l or --list, this list all commands.
1329 exit
1331 quit
1332 This exits guestfish. You can also use "^D" key.
1333 alloc
1335 allocate
1336 alloc filename size
1337 This creates an empty (zeroed) file of the given size, and then adds so
1339 it can be further examined.
1340 For more advanced image creation, see "disk-create".
1342 Size can be specified using standard suffixes, eg. "1M".
1344 To create a sparse file, use "sparse" instead. To create a prepared
1346 disk image, see "PREPARED DISK IMAGES".
1347 copy-in
1349 copy-in local [local ...] /remotedir
1350 "copy-in" copies local files or directories recursively into the disk
1352 image, placing them in the directory called /remotedir (which must
1353 exist). This guestfish meta-command turns into a sequence of "tar-in"
1354 and other commands as necessary.
1355 Multiple local files and directories can be specified, but the last
1357 parameter must always be a remote directory. Wildcards cannot be used.
1358 copy-out
1360 copy-out remote [remote ...] localdir
1361 "copy-out" copies remote files or directories recursively out of the
1363 disk image, placing them on the host disk in a local directory called
1364 "localdir" (which must exist). This guestfish meta-command turns into
1365 a sequence of "download", "tar-out" and other commands as necessary.
1366 Multiple remote files and directories can be specified, but the last
1368 parameter must always be a local directory. To download to the current
1369 directory, use "." as in:
1370 copy-out /home .
1372 Wildcards cannot be used in the ordinary command, but you can use them
1374 with the help of "glob" like this:
1375 glob copy-out /home/* .
1377 delete-event
1379 delete-event name
1380 Delete the event handler which was previously registered as "name". If
1382 multiple event handlers were registered with the same name, they are
1383 all deleted.
1384 See also the guestfish commands "event" and "list-events".
1386 display
1388 display filename
1389 Use "display" (a graphical display program) to display an image file.
1391 It downloads the file, and runs "display" on it.
1392 To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1394 environment variable. For example to use the GNOME display program:
1395 export GUESTFISH_DISPLAY_IMAGE=eog
1397 See also display(1).
1399 echo
1401 echo [params ...]
1402 This echos the parameters to the terminal.
1404 edit
1406 vi
1407 emacs
1408 edit filename
1409 This is used to edit a file. It downloads the file, edits it locally
1411 using your editor, then uploads the result.
1412 The editor is $EDITOR. However if you use the alternate commands "vi"
1414 or "emacs" you will get those corresponding editors.
1415 event
1417 event name eventset "shell script ..."
1418 Register a shell script fragment which is executed when an event is
1420 raised. See "guestfs_set_event_callback" in guestfs(3) for a
1421 discussion of the event API in libguestfs.
1422 The "name" parameter is a name that you give to this event handler. It
1424 can be any string (even the empty string) and is simply there so you
1425 can delete the handler using the guestfish "delete-event" command.
1426 The "eventset" parameter is a comma-separated list of one or more
1428 events, for example "close" or "close,trace". The special value "*"
1429 means all events.
1430 The third and final parameter is the shell script fragment (or any
1432 external command) that is executed when any of the events in the
1433 eventset occurs. It is executed using "$SHELL -c", or if $SHELL is not
1434 set then /bin/sh -c.
1435 The shell script fragment receives callback parameters as arguments $1,
1437 $2 etc. The actual event that was called is available in the
1438 environment variable $EVENT.
1439 event "" close "echo closed"
1441 event messages appliance,library,trace "echo $@"
1442 event "" progress "echo progress: $3/$4"
1443 event "" * "echo $EVENT $@"
1444 See also the guestfish commands "delete-event" and "list-events".
1446 glob
1448 glob command args...
1449 Expand wildcards in any paths in the args list, and run "command"
1451 repeatedly on each matching path.
1452 See "WILDCARDS AND GLOBBING".
1454 hexedit
1456 hexedit <filename|device>
1457 hexedit <filename|device> <max>
1458 hexedit <filename|device> <start> <max>
1459 Use hexedit (a hex editor) to edit all or part of a binary file or
1461 block device.
1462 This command works by downloading potentially the whole file or device,
1464 editing it locally, then uploading it. If the file or device is large,
1465 you have to specify which part you wish to edit by using "max" and/or
1466 "start" "max" parameters. "start" and "max" are specified in bytes,
1467 with the usual modifiers allowed such as "1M" (1 megabyte).
1468 For example to edit the first few sectors of a disk you might do:
1470 hexedit /dev/sda 1M
1472 which would allow you to edit anywhere within the first megabyte of the
1474 disk.
1475 To edit the superblock of an ext2 filesystem on /dev/sda1, do:
1477 hexedit /dev/sda1 0x400 0x400
1479 (assuming the superblock is in the standard location).
1481 This command requires the external hexedit(1) program. You can specify
1483 another program to use by setting the "HEXEDITOR" environment variable.
1484 See also "hexdump".
1486 lcd
1488 lcd directory
1489 Change the local directory, ie. the current directory of guestfish
1491 itself.
1492 Note that "!cd" won't do what you might expect.
1494 list-events
1496 list-events
1497 List the event handlers registered using the guestfish "event" command.
1499 man
1501 manual
1502 man
1503 Opens the manual page for guestfish.
1505 more
1507 less
1508 more filename
1509 less filename
1511 This is used to view a file.
1513 The default viewer is $PAGER. However if you use the alternate command
1515 "less" you will get the "less" command specifically.
1516 reopen
1518 reopen
1519 Close and reopen the libguestfs handle. It is not necessary to use
1521 this normally, because the handle is closed properly when guestfish
1522 exits. However this is occasionally useful for testing.
1523 setenv
1525 setenv VAR value
1526 Set the environment variable "VAR" to the string "value".
1528 To print the value of an environment variable use a shell command such
1530 as:
1531 !echo $VAR
1533 sparse
1535 sparse filename size
1536 This creates an empty sparse file of the given size, and then adds so
1538 it can be further examined.
1539 In all respects it works the same as the "alloc" command, except that
1541 the image file is allocated sparsely, which means that disk blocks are
1542 not assigned to the file until they are needed. Sparse disk files only
1543 use space when written to, but they are slower and there is a danger
1544 you could run out of real disk space during a write operation.
1545 For more advanced image creation, see "disk-create".
1547 Size can be specified using standard suffixes, eg. "1M".
1549 See also the guestfish "scratch" command.
1551 supported
1553 supported
1554 This command returns a list of the optional groups known to the daemon,
1556 and indicates which ones are supported by this build of the libguestfs
1557 appliance.
1558 See also "AVAILABILITY" in guestfs(3).
1560 time
1562 time command args...
1563 Run the command as usual, but print the elapsed time afterwards. This
1565 can be useful for benchmarking operations.
1566 unsetenv
1568 unsetenv VAR
1569 Remove "VAR" from the environment.
1571
1573 acl-delete-def-file
1574 acl-delete-def-file dir
1575 This function deletes the default POSIX Access Control List (ACL)
1577 attached to directory "dir".
1578 This command depends on the feature "acl". See also "feature-
1580 available".
1581 acl-get-file
1583 acl-get-file path acltype
1584 This function returns the POSIX Access Control List (ACL) attached to
1586 "path". The ACL is returned in "long text form" (see acl(5)).
1587 The "acltype" parameter may be:
1589 "access"
1591 Return the ordinary (access) ACL for any file, directory or other
1592 filesystem object.
1593 "default"
1595 Return the default ACL. Normally this only makes sense if "path"
1596 is a directory.
1597 This command depends on the feature "acl". See also "feature-
1599 available".
1600 acl-set-file
1602 acl-set-file path acltype acl
1603 This function sets the POSIX Access Control List (ACL) attached to
1605 "path".
1606 The "acltype" parameter may be:
1608 "access"
1610 Set the ordinary (access) ACL for any file, directory or other
1611 filesystem object.
1612 "default"
1614 Set the default ACL. Normally this only makes sense if "path" is a
1615 directory.
1616 The "acl" parameter is the new ACL in either "long text form" or "short
1618 text form" (see acl(5)). The new ACL completely replaces any previous
1619 ACL on the file. The ACL must contain the full Unix permissions (eg.
1620 "u::rwx,g::rx,o::rx").
1621 If you are specifying individual users or groups, then the mask field
1623 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1624 "g:ID:..." field(s). A full ACL string might therefore look like this:
1625 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1627 \ Unix permissions / \mask/ \ ACL /
1628 You should use numeric UIDs and GIDs. To map usernames and groupnames
1630 to the correct numeric ID in the context of the guest, use the Augeas
1631 functions (see "aug-init").
1632 This command depends on the feature "acl". See also "feature-
1634 available".
1635 add-cdrom
1637 add-cdrom filename
1638 This function adds a virtual CD-ROM disk image to the guest.
1640 The image is added as read-only drive, so this function is equivalent
1642 of "add-drive-ro".
1643 This function is deprecated. In new code, use the "add-drive-ro" call
1645 instead.
1646 Deprecated functions will not be removed from the API, but the fact
1648 that they are deprecated indicates that there are problems with correct
1649 use of these functions.
1650 add-domain
1652 domain
1653 add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]
1654 This function adds the disk(s) attached to the named libvirt domain
1656 "dom". It works by connecting to libvirt, requesting the domain and
1657 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1658 opts" on each one.
1659 The number of disks added is returned. This operation is atomic: if an
1661 error is returned, then no disks are added.
1662 This function does some minimal checks to make sure the libvirt domain
1664 is not running (unless "readonly" is true). In a future version we
1665 will try to acquire the libvirt lock on each disk.
1666 Disks must be accessible locally. This often means that adding disks
1668 from a remote libvirt connection (see https://libvirt.org/remote.html)
1669 will fail unless those disks are accessible via the same device path
1670 locally too.
1671 The optional "libvirturi" parameter sets the libvirt URI (see
1673 https://libvirt.org/uri.html). If this is not set then we connect to
1674 the default libvirt URI (or one set through an environment variable,
1675 see the libvirt documentation for full details).
1676 The optional "live" flag controls whether this call will try to connect
1678 to a running virtual machine "guestfsd" process if it sees a suitable
1679 <channel> element in the libvirt XML definition. The default (if the
1680 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1681 in guestfs(3) for more information.
1682 If the "allowuuid" flag is true (default is false) then a UUID may be
1684 passed instead of the domain name. The "dom" string is treated as a
1685 UUID first and looked up, and if that lookup fails then we treat "dom"
1686 as a name as usual.
1687 The optional "readonlydisk" parameter controls what we do for disks
1689 which are marked <readonly/> in the libvirt XML. Possible values are:
1690 readonlydisk = "error"
1692 If "readonly" is false:
1693 The whole call is aborted with an error if any disk with the
1695 <readonly/> flag is found.
1696 If "readonly" is true:
1698 Disks with the <readonly/> flag are added read-only.
1700 readonlydisk = "read"
1702 If "readonly" is false:
1703 Disks with the <readonly/> flag are added read-only. Other disks
1705 are added read/write.
1706 If "readonly" is true:
1708 Disks with the <readonly/> flag are added read-only.
1710 readonlydisk = "write" (default)
1712 If "readonly" is false:
1713 Disks with the <readonly/> flag are added read/write.
1715 If "readonly" is true:
1717 Disks with the <readonly/> flag are added read-only.
1719 readonlydisk = "ignore"
1721 If "readonly" is true or false:
1722 Disks with the <readonly/> flag are skipped.
1724 If present, the value of "logical_block_size" attribute of <blockio/>
1726 tag in libvirt XML will be passed as "blocksize" parameter to "add-
1727 drive-opts".
1728 The other optional parameters are passed directly through to "add-
1730 drive-opts".
1731 This command has one or more optional arguments. See "OPTIONAL
1733 ARGUMENTS".
1734 add-drive
1736 add
1737 add-drive-opts
1738 add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]
1739 This function adds a disk image called filename to the handle.
1741 filename may be a regular host file or a host device.
1742 When this function is called before "launch" (the usual case) then the
1744 first time you call this function, the disk appears in the API as
1745 /dev/sda, the second time as /dev/sdb, and so on.
1746 In libguestfs ≥ 1.20 you can also call this function after launch (with
1748 some restrictions). This is called "hotplugging". When hotplugging,
1749 you must specify a "label" so that the new disk gets a predictable
1750 name. For more information see "HOTPLUGGING" in guestfs(3).
1751 You don't necessarily need to be root when using libguestfs. However
1753 you obviously do need sufficient permissions to access the filename for
1754 whatever operations you want to perform (ie. read access if you just
1755 want to read the image or write access if you want to modify the
1756 image).
1757 This call checks that filename exists.
1759 filename may be the special string "/dev/null". See "NULL DISKS" in
1761 guestfs(3).
1762 The optional arguments are:
1764 "readonly"
1766 If true then the image is treated as read-only. Writes are still
1767 allowed, but they are stored in a temporary snapshot overlay which
1768 is discarded at the end. The disk that you add is not modified.
1769 "format"
1771 This forces the image format. If you omit this (or use "add-drive"
1772 or "add-drive-ro") then the format is automatically detected.
1773 Possible formats include "raw" and "qcow2".
1774 Automatic detection of the format opens you up to a potential
1776 security hole when dealing with untrusted raw-format images. See
1777 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1778 security hole.
1779 "iface"
1781 This rarely-used option lets you emulate the behaviour of the
1782 deprecated "add-drive-with-if" call (q.v.)
1783 "name"
1785 The name the drive had in the original guest, e.g. /dev/sdb. This
1786 is used as a hint to the guest inspection process if it is
1787 available.
1788 "label"
1790 Give the disk a label. The label should be a unique, short string
1791 using only ASCII characters "[a-zA-Z]". As well as its usual name
1792 in the API (such as /dev/sda), the drive will also be named
1793 /dev/disk/guestfs/label.
1794 See "DISK LABELS" in guestfs(3).
1796 "protocol"
1798 The optional protocol argument can be used to select an alternate
1799 source protocol.
1800 See also: "REMOTE STORAGE" in guestfs(3).
1802 "protocol = "file""
1804 filename is interpreted as a local file or device. This is the
1805 default if the optional protocol parameter is omitted.
1806 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
1808 Connect to a remote FTP, HTTP or TFTP server. The "server"
1809 parameter must also be supplied - see below.
1810 See also: "FTP, HTTP AND TFTP" in guestfs(3)
1812 "protocol = "gluster""
1814 Connect to the GlusterFS server. The "server" parameter must
1815 also be supplied - see below.
1816 See also: "GLUSTER" in guestfs(3)
1818 "protocol = "iscsi""
1820 Connect to the iSCSI server. The "server" parameter must also
1821 be supplied - see below. The "username" parameter may be
1822 supplied. See below. The "secret" parameter may be supplied.
1823 See below.
1824 See also: "ISCSI" in guestfs(3).
1826 "protocol = "nbd""
1828 Connect to the Network Block Device server. The "server"
1829 parameter must also be supplied - see below.
1830 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
1832 "protocol = "rbd""
1834 Connect to the Ceph (librbd/RBD) server. The "server"
1835 parameter must also be supplied - see below. The "username"
1836 parameter may be supplied. See below. The "secret" parameter
1837 may be supplied. See below.
1838 See also: "CEPH" in guestfs(3).
1840 "protocol = "sheepdog""
1842 Connect to the Sheepdog server. The "server" parameter may
1843 also be supplied - see below.
1844 See also: "SHEEPDOG" in guestfs(3).
1846 "protocol = "ssh""
1848 Connect to the Secure Shell (ssh) server.
1849 The "server" parameter must be supplied. The "username"
1851 parameter may be supplied. See below.
1852 See also: "SSH" in guestfs(3).
1854 "server"
1856 For protocols which require access to a remote server, this is a
1857 list of server(s).
1858 Protocol Number of servers required
1860 -------- --------------------------
1861 file List must be empty or param not used at all
1862 ftp|ftps|http|https|tftp Exactly one
1863 gluster Exactly one
1864 iscsi Exactly one
1865 nbd Exactly one
1866 rbd Zero or more
1867 sheepdog Zero or more
1868 ssh Exactly one
1869 Each list element is a string specifying a server. The string must
1871 be in one of the following formats:
1872 hostname
1874 hostname:port
1875 tcp:hostname
1876 tcp:hostname:port
1877 unix:/path/to/socket
1878 If the port number is omitted, then the standard port number for
1880 the protocol is used (see /etc/services).
1881 "username"
1883 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
1884 "tftp" protocols, this specifies the remote username.
1885 If not given, then the local username is used for "ssh", and no
1887 authentication is attempted for ceph. But note this sometimes may
1888 give unexpected results, for example if using the libvirt backend
1889 and if the libvirt backend is configured to start the qemu
1890 appliance as a special user such as "qemu.qemu". If in doubt,
1891 specify the remote username you want.
1892 "secret"
1894 For the "rbd" protocol only, this specifies the ‘secret’ to use
1895 when connecting to the remote device. It must be base64 encoded.
1896 If not given, then a secret matching the given username will be
1898 looked up in the default keychain locations, or if no username is
1899 given, then no authentication will be used.
1900 "cachemode"
1902 Choose whether or not libguestfs will obey sync operations (safe
1903 but slow) or not (unsafe but fast). The possible values for this
1904 string are:
1905 "cachemode = "writeback""
1907 This is the default.
1908 Write operations in the API do not return until a write(2) call
1910 has completed in the host [but note this does not imply that
1911 anything gets written to disk].
1912 Sync operations in the API, including implicit syncs caused by
1914 filesystem journalling, will not return until an fdatasync(2)
1915 call has completed in the host, indicating that data has been
1916 committed to disk.
1917 "cachemode = "unsafe""
1919 In this mode, there are no guarantees. Libguestfs may cache
1920 anything and ignore sync requests. This is suitable only for
1921 scratch or temporary disks.
1922 "discard"
1924 Enable or disable discard (a.k.a. trim or unmap) support on this
1925 drive. If enabled, operations such as "fstrim" will be able to
1926 discard / make thin / punch holes in the underlying host file or
1927 device.
1928 Possible discard settings are:
1930 "discard = "disable""
1932 Disable discard support. This is the default.
1933 "discard = "enable""
1935 Enable discard support. Fail if discard is not possible.
1936 "discard = "besteffort""
1938 Enable discard support if possible, but don't fail if it is not
1939 supported.
1940 Since not all backends and not all underlying systems support
1942 discard, this is a good choice if you want to use discard if
1943 possible, but don't mind if it doesn't work.
1944 "copyonread"
1946 The boolean parameter "copyonread" enables copy-on-read support.
1947 This only affects disk formats which have backing files, and causes
1948 reads to be stored in the overlay layer, speeding up multiple reads
1949 of the same area of disk.
1950 The default is false.
1952 "blocksize"
1954 This parameter sets the sector size of the disk. Possible values
1955 are 512 (the default if the parameter is omitted) or 4096. Use
1956 4096 when handling an "Advanced Format" disk that uses 4K sector
1957 size (https://en.wikipedia.org/wiki/Advanced_Format).
1958 Only a subset of the backends support this parameter (currently
1960 only the libvirt and direct backends do).
1961 This command has one or more optional arguments. See "OPTIONAL
1963 ARGUMENTS".
1964 add-drive-ro
1966 add-ro
1967 add-drive-ro filename
1968 This function is the equivalent of calling "add-drive-opts" with the
1970 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1971 disk is added read-only, with the format being detected automatically.
1972 add-drive-ro-with-if
1974 add-drive-ro-with-if filename iface
1975 This is the same as "add-drive-ro" but it allows you to specify the
1977 QEMU interface emulation to use at run time.
1978 This function is deprecated. In new code, use the "add-drive" call
1980 instead.
1981 Deprecated functions will not be removed from the API, but the fact
1983 that they are deprecated indicates that there are problems with correct
1984 use of these functions.
1985 add-drive-scratch
1987 scratch
1988 add-drive-scratch size [name:..] [label:..] [blocksize:N]
1989 This command adds a temporary scratch drive to the handle. The "size"
1991 parameter is the virtual size (in bytes). The scratch drive is blank
1992 initially (all reads return zeroes until you start writing to it). The
1993 drive is deleted when the handle is closed.
1994 The optional arguments "name", "label" and "blocksize" are passed
1996 through to "add-drive-opts".
1997 This command has one or more optional arguments. See "OPTIONAL
1999 ARGUMENTS".
2000 add-drive-with-if
2002 add-drive-with-if filename iface
2003 This is the same as "add-drive" but it allows you to specify the QEMU
2005 interface emulation to use at run time.
2006 This function is deprecated. In new code, use the "add-drive" call
2008 instead.
2009 Deprecated functions will not be removed from the API, but the fact
2011 that they are deprecated indicates that there are problems with correct
2012 use of these functions.
2013 aug-clear
2015 aug-clear augpath
2016 Set the value associated with "path" to "NULL". This is the same as
2018 the augtool(1) "clear" command.
2019 aug-close
2021 aug-close
2022 Close the current Augeas handle and free up any resources used by it.
2024 After calling this, you have to call "aug-init" again before you can
2025 use any other Augeas functions.
2026 aug-defnode
2028 aug-defnode name expr val
2029 Defines a variable "name" whose value is the result of evaluating
2031 "expr".
2032 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2034 to calling "aug-set" "expr", "val". "name" will be the nodeset
2035 containing that single node.
2036 On success this returns a pair containing the number of nodes in the
2038 nodeset, and a boolean flag if a node was created.
2039 aug-defvar
2041 aug-defvar name expr
2042 Defines an Augeas variable "name" whose value is the result of
2044 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2045 On success this returns the number of nodes in "expr", or 0 if "expr"
2047 evaluates to something which is not a nodeset.
2048 aug-get
2050 aug-get augpath
2051 Look up the value associated with "path". If "path" matches exactly
2053 one node, the "value" is returned.
2054 aug-init
2056 aug-init root flags
2057 Create a new Augeas handle for editing configuration files. If there
2059 was any previous Augeas handle associated with this guestfs session,
2060 then it is closed.
2061 You must call this before using any other "aug-*" commands.
2063 "root" is the filesystem root. "root" must not be NULL, use / instead.
2065 The flags are the same as the flags defined in <augeas.h>, the logical
2067 or of the following integers:
2068 "AUG_SAVE_BACKUP" = 1
2070 Keep the original file with a ".augsave" extension.
2071 "AUG_SAVE_NEWFILE" = 2
2073 Save changes into a file with extension ".augnew", and do not
2074 overwrite original. Overrides "AUG_SAVE_BACKUP".
2075 "AUG_TYPE_CHECK" = 4
2077 Typecheck lenses.
2078 This option is only useful when debugging Augeas lenses. Use of
2080 this option may require additional memory for the libguestfs
2081 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2082 environment variable or call "set-memsize".
2083 "AUG_NO_STDINC" = 8
2085 Do not use standard load path for modules.
2086 "AUG_SAVE_NOOP" = 16
2088 Make save a no-op, just record what would have been changed.
2089 "AUG_NO_LOAD" = 32
2091 Do not load the tree in "aug-init".
2092 To close the handle, you can call "aug-close".
2094 To find out more about Augeas, see http://augeas.net/.
2096 aug-insert
2098 aug-insert augpath label true|false
2099 Create a new sibling "label" for "path", inserting it into the tree
2101 before or after "path" (depending on the boolean flag "before").
2102 "path" must match exactly one existing node in the tree, and "label"
2104 must be a label, ie. not contain /, "*" or end with a bracketed index
2105 "[N]".
2106 aug-label
2108 aug-label augpath
2109 The label (name of the last element) of the Augeas path expression
2111 "augpath" is returned. "augpath" must match exactly one node, else
2112 this function returns an error.
2113 aug-load
2115 aug-load
2116 Load files into the tree.
2118 See "aug_load" in the Augeas documentation for the full gory details.
2120 aug-ls
2122 aug-ls augpath
2123 This is just a shortcut for listing "aug-match" "path/*" and sorting
2125 the resulting nodes into alphabetical order.
2126 aug-match
2128 aug-match augpath
2129 Returns a list of paths which match the path expression "path". The
2131 returned paths are sufficiently qualified so that they match exactly
2132 one node in the current tree.
2133 aug-mv
2135 aug-mv src dest
2136 Move the node "src" to "dest". "src" must match exactly one node.
2138 "dest" is overwritten if it exists.
2139 aug-rm
2141 aug-rm augpath
2142 Remove "path" and all of its children.
2144 On success this returns the number of entries which were removed.
2146 aug-save
2148 aug-save
2149 This writes all pending changes to disk.
2151 The flags which were passed to "aug-init" affect exactly how files are
2153 saved.
2154 aug-set
2156 aug-set augpath val
2157 Set the value associated with "augpath" to "val".
2159 In the Augeas API, it is possible to clear a node by setting the value
2161 to NULL. Due to an oversight in the libguestfs API you cannot do that
2162 with this call. Instead you must use the "aug-clear" call.
2163 aug-setm
2165 aug-setm base sub val
2166 Change multiple Augeas nodes in a single operation. "base" is an
2168 expression matching multiple nodes. "sub" is a path expression
2169 relative to "base". All nodes matching "base" are found, and then for
2170 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2171 which case the "base" nodes are modified.
2172 This returns the number of nodes modified.
2174 aug-transform
2176 aug-transform lens file [remove:true|false]
2177 Add an Augeas transformation for the specified "lens" so it can handle
2179 "file".
2180 If "remove" is true ("false" by default), then the transformation is
2182 removed.
2183 This command has one or more optional arguments. See "OPTIONAL
2185 ARGUMENTS".
2186 available
2188 available 'groups ...'
2189 This command is used to check the availability of some groups of
2191 functionality in the appliance, which not all builds of the libguestfs
2192 appliance will be able to provide.
2193 The libguestfs groups, and the functions that those groups correspond
2195 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
2196 this list at runtime by calling "available-all-groups".
2197 The argument "groups" is a list of group names, eg: "["inotify",
2199 "augeas"]" would check for the availability of the Linux inotify
2200 functions and Augeas (configuration file editing) functions.
2201 The command returns no error if all requested groups are available.
2203 It fails with an error if one or more of the requested groups is
2205 unavailable in the appliance.
2206 If an unknown group name is included in the list of groups then an
2208 error is always returned.
2209 Notes:
2211 · "feature-available" is the same as this call, but with a slightly
2213 simpler to use API: that call returns a boolean true/false instead
2214 of throwing an error.
2215 · You must call "launch" before calling this function.
2217 The reason is because we don't know what groups are supported by
2219 the appliance/daemon until it is running and can be queried.
2220 · If a group of functions is available, this does not necessarily
2222 mean that they will work. You still have to check for errors when
2223 calling individual API functions even if they are available.
2224 · It is usually the job of distro packagers to build complete
2226 functionality into the libguestfs appliance. Upstream libguestfs,
2227 if built from source with all requirements satisfied, will support
2228 everything.
2229 · This call was added in version 1.0.80. In previous versions of
2231 libguestfs all you could do would be to speculatively execute a
2232 command to find out if the daemon implemented it. See also
2233 "version".
2234 See also "filesystem-available".
2236 available-all-groups
2238 available-all-groups
2239 This command returns a list of all optional groups that this daemon
2241 knows about. Note this returns both supported and unsupported groups.
2242 To find out which ones the daemon can actually support you have to call
2243 "available" / "feature-available" on each member of the returned list.
2244 See also "available", "feature-available" and "AVAILABILITY" in
2246 guestfs(3).
2247 base64-in
2249 base64-in (base64file|-) filename
2250 This command uploads base64-encoded data from "base64file" to filename.
2252 Use "-" instead of a filename to read/write from stdin/stdout.
2254 base64-out
2256 base64-out filename (base64file|-)
2257 This command downloads the contents of filename, writing it out to
2259 local file "base64file" encoded as base64.
2260 Use "-" instead of a filename to read/write from stdin/stdout.
2262 blkdiscard
2264 blkdiscard device
2265 This discards all blocks on the block device "device", giving the free
2267 space back to the host.
2268 This operation requires support in libguestfs, the host filesystem,
2270 qemu and the host kernel. If this support isn't present it may give an
2271 error or even appear to run but do nothing. You must also set the
2272 "discard" attribute on the underlying drive (see "add-drive-opts").
2273 This command depends on the feature "blkdiscard". See also "feature-
2275 available".
2276 blkdiscardzeroes
2278 blkdiscardzeroes device
2279 This call returns true if blocks on "device" that have been discarded
2281 by a call to "blkdiscard" are returned as blocks of zero bytes when
2282 read the next time.
2283 If it returns false, then it may be that discarded blocks are read as
2285 stale or random data.
2286 This command depends on the feature "blkdiscardzeroes". See also
2288 "feature-available".
2289 blkid
2291 blkid device
2292 This command returns block device attributes for "device". The
2294 following fields are usually present in the returned hash. Other fields
2295 may also be present.
2296 "UUID"
2298 The uuid of this device.
2299 "LABEL"
2301 The label of this device.
2302 "VERSION"
2304 The version of blkid command.
2305 "TYPE"
2307 The filesystem type or RAID of this device.
2308 "USAGE"
2310 The usage of this device, for example "filesystem" or "raid".
2311 blockdev-flushbufs
2313 blockdev-flushbufs device
2314 This tells the kernel to flush internal buffers associated with
2316 "device".
2317 This uses the blockdev(8) command.
2319 blockdev-getbsz
2321 blockdev-getbsz device
2322 This returns the block size of a device.
2324 Note: this is different from both size in blocks and filesystem block
2326 size. Also this setting is not really used by anything. You should
2327 probably not use it for anything. Filesystems have their own idea
2328 about what block size to choose.
2329 This uses the blockdev(8) command.
2331 blockdev-getro
2333 blockdev-getro device
2334 Returns a boolean indicating if the block device is read-only (true if
2336 read-only, false if not).
2337 This uses the blockdev(8) command.
2339 blockdev-getsize64
2341 blockdev-getsize64 device
2342 This returns the size of the device in bytes.
2344 See also "blockdev-getsz".
2346 This uses the blockdev(8) command.
2348 blockdev-getss
2350 blockdev-getss device
2351 This returns the size of sectors on a block device. Usually 512, but
2353 can be larger for modern devices.
2354 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
2356 This uses the blockdev(8) command.
2358 blockdev-getsz
2360 blockdev-getsz device
2361 This returns the size of the device in units of 512-byte sectors (even
2363 if the sectorsize isn't 512 bytes ... weird).
2364 See also "blockdev-getss" for the real sector size of the device, and
2366 "blockdev-getsize64" for the more useful size in bytes.
2367 This uses the blockdev(8) command.
2369 blockdev-rereadpt
2371 blockdev-rereadpt device
2372 Reread the partition table on "device".
2374 This uses the blockdev(8) command.
2376 blockdev-setbsz
2378 blockdev-setbsz device blocksize
2379 This call does nothing and has never done anything because of a bug in
2381 blockdev. Do not use it.
2382 If you need to set the filesystem block size, use the "blocksize"
2384 option of "mkfs".
2385 This function is deprecated. There is no replacement. Consult the API
2387 documentation in guestfs(3) for further information.
2388 Deprecated functions will not be removed from the API, but the fact
2390 that they are deprecated indicates that there are problems with correct
2391 use of these functions.
2392 blockdev-setra
2394 blockdev-setra device sectors
2395 Set readahead (in 512-byte sectors) for the device.
2397 This uses the blockdev(8) command.
2399 blockdev-setro
2401 blockdev-setro device
2402 Sets the block device named "device" to read-only.
2404 This uses the blockdev(8) command.
2406 blockdev-setrw
2408 blockdev-setrw device
2409 Sets the block device named "device" to read-write.
2411 This uses the blockdev(8) command.
2413 btrfs-balance-cancel
2415 btrfs-balance-cancel path
2416 Cancel a running balance on a btrfs filesystem.
2418 This command depends on the feature "btrfs". See also "feature-
2420 available".
2421 btrfs-balance-pause
2423 btrfs-balance-pause path
2424 Pause a running balance on a btrfs filesystem.
2426 This command depends on the feature "btrfs". See also "feature-
2428 available".
2429 btrfs-balance-resume
2431 btrfs-balance-resume path
2432 Resume a paused balance on a btrfs filesystem.
2434 This command depends on the feature "btrfs". See also "feature-
2436 available".
2437 btrfs-balance-status
2439 btrfs-balance-status path
2440 Show the status of a running or paused balance on a btrfs filesystem.
2442 This command depends on the feature "btrfs". See also "feature-
2444 available".
2445 btrfs-device-add
2447 btrfs-device-add 'devices ...' fs
2448 Add the list of device(s) in "devices" to the btrfs filesystem mounted
2450 at "fs". If "devices" is an empty list, this does nothing.
2451 This command depends on the feature "btrfs". See also "feature-
2453 available".
2454 btrfs-device-delete
2456 btrfs-device-delete 'devices ...' fs
2457 Remove the "devices" from the btrfs filesystem mounted at "fs". If
2459 "devices" is an empty list, this does nothing.
2460 This command depends on the feature "btrfs". See also "feature-
2462 available".
2463 btrfs-filesystem-balance
2465 btrfs-balance
2466 btrfs-filesystem-balance fs
2467 Balance the chunks in the btrfs filesystem mounted at "fs" across the
2469 underlying devices.
2470 This command depends on the feature "btrfs". See also "feature-
2472 available".
2473 btrfs-filesystem-defragment
2475 btrfs-filesystem-defragment path [flush:true|false] [compress:..]
2476 Defragment a file or directory on a btrfs filesystem. compress is one
2478 of zlib or lzo.
2479 This command has one or more optional arguments. See "OPTIONAL
2481 ARGUMENTS".
2482 This command depends on the feature "btrfs". See also "feature-
2484 available".
2485 btrfs-filesystem-resize
2487 btrfs-filesystem-resize mountpoint [size:N]
2488 This command resizes a btrfs filesystem.
2490 Note that unlike other resize calls, the filesystem has to be mounted
2492 and the parameter is the mountpoint not the device (this is a
2493 requirement of btrfs itself).
2494 The optional parameters are:
2496 "size"
2498 The new size (in bytes) of the filesystem. If omitted, the
2499 filesystem is resized to the maximum size.
2500 See also btrfs(8).
2502 This command has one or more optional arguments. See "OPTIONAL
2504 ARGUMENTS".
2505 This command depends on the feature "btrfs". See also "feature-
2507 available".
2508 btrfs-filesystem-show
2510 btrfs-filesystem-show device
2511 Show all the devices where the filesystems in "device" is spanned over.
2513 If not all the devices for the filesystems are present, then this
2515 function fails and the "errno" is set to "ENODEV".
2516 This command depends on the feature "btrfs". See also "feature-
2518 available".
2519 btrfs-filesystem-sync
2521 btrfs-filesystem-sync fs
2522 Force sync on the btrfs filesystem mounted at "fs".
2524 This command depends on the feature "btrfs". See also "feature-
2526 available".
2527 btrfs-fsck
2529 btrfs-fsck device [superblock:N] [repair:true|false]
2530 Used to check a btrfs filesystem, "device" is the device file where the
2532 filesystem is stored.
2533 This command has one or more optional arguments. See "OPTIONAL
2535 ARGUMENTS".
2536 This command depends on the feature "btrfs". See also "feature-
2538 available".
2539 btrfs-image
2541 btrfs-image 'source ...' image [compresslevel:N]
2542 This is used to create an image of a btrfs filesystem. All data will
2544 be zeroed, but metadata and the like is preserved.
2545 This command has one or more optional arguments. See "OPTIONAL
2547 ARGUMENTS".
2548 This command depends on the feature "btrfs". See also "feature-
2550 available".
2551 btrfs-qgroup-assign
2553 btrfs-qgroup-assign src dst path
2554 Add qgroup "src" to parent qgroup "dst". This command can group several
2556 qgroups into a parent qgroup to share common limit.
2557 This command depends on the feature "btrfs". See also "feature-
2559 available".
2560 btrfs-qgroup-create
2562 btrfs-qgroup-create qgroupid subvolume
2563 Create a quota group (qgroup) for subvolume at "subvolume".
2565 This command depends on the feature "btrfs". See also "feature-
2567 available".
2568 btrfs-qgroup-destroy
2570 btrfs-qgroup-destroy qgroupid subvolume
2571 Destroy a quota group.
2573 This command depends on the feature "btrfs". See also "feature-
2575 available".
2576 btrfs-qgroup-limit
2578 btrfs-qgroup-limit subvolume size
2579 Limit the size of the subvolume with path "subvolume".
2581 This command depends on the feature "btrfs". See also "feature-
2583 available".
2584 btrfs-qgroup-remove
2586 btrfs-qgroup-remove src dst path
2587 Remove qgroup "src" from the parent qgroup "dst".
2589 This command depends on the feature "btrfs". See also "feature-
2591 available".
2592 btrfs-qgroup-show
2594 btrfs-qgroup-show path
2595 Show all subvolume quota groups in a btrfs filesystem, including their
2597 usages.
2598 This command depends on the feature "btrfs". See also "feature-
2600 available".
2601 btrfs-quota-enable
2603 btrfs-quota-enable fs true|false
2604 Enable or disable subvolume quota support for filesystem which contains
2606 "path".
2607 This command depends on the feature "btrfs". See also "feature-
2609 available".
2610 btrfs-quota-rescan
2612 btrfs-quota-rescan fs
2613 Trash all qgroup numbers and scan the metadata again with the current
2615 config.
2616 This command depends on the feature "btrfs". See also "feature-
2618 available".
2619 btrfs-replace
2621 btrfs-replace srcdev targetdev mntpoint
2622 Replace device of a btrfs filesystem. On a live filesystem, duplicate
2624 the data to the target device which is currently stored on the source
2625 device. After completion of the operation, the source device is wiped
2626 out and removed from the filesystem.
2627 The "targetdev" needs to be same size or larger than the "srcdev".
2629 Devices which are currently mounted are never allowed to be used as the
2630 "targetdev".
2631 This command depends on the feature "btrfs". See also "feature-
2633 available".
2634 btrfs-rescue-chunk-recover
2636 btrfs-rescue-chunk-recover device
2637 Recover the chunk tree of btrfs filesystem by scanning the devices one
2639 by one.
2640 This command depends on the feature "btrfs". See also "feature-
2642 available".
2643 btrfs-rescue-super-recover
2645 btrfs-rescue-super-recover device
2646 Recover bad superblocks from good copies.
2648 This command depends on the feature "btrfs". See also "feature-
2650 available".
2651 btrfs-scrub-cancel
2653 btrfs-scrub-cancel path
2654 Cancel a running scrub on a btrfs filesystem.
2656 This command depends on the feature "btrfs". See also "feature-
2658 available".
2659 btrfs-scrub-resume
2661 btrfs-scrub-resume path
2662 Resume a previously canceled or interrupted scrub on a btrfs
2664 filesystem.
2665 This command depends on the feature "btrfs". See also "feature-
2667 available".
2668 btrfs-scrub-start
2670 btrfs-scrub-start path
2671 Reads all the data and metadata on the filesystem, and uses checksums
2673 and the duplicate copies from RAID storage to identify and repair any
2674 corrupt data.
2675 This command depends on the feature "btrfs". See also "feature-
2677 available".
2678 btrfs-scrub-status
2680 btrfs-scrub-status path
2681 Show status of running or finished scrub on a btrfs filesystem.
2683 This command depends on the feature "btrfs". See also "feature-
2685 available".
2686 btrfs-set-seeding
2688 btrfs-set-seeding device true|false
2689 Enable or disable the seeding feature of a device that contains a btrfs
2691 filesystem.
2692 This command depends on the feature "btrfs". See also "feature-
2694 available".
2695 btrfs-subvolume-create
2697 btrfs-subvolume-create-opts
2698 btrfs-subvolume-create dest [qgroupid:..]
2699 Create a btrfs subvolume. The "dest" argument is the destination
2701 directory and the name of the subvolume, in the form
2702 /path/to/dest/name. The optional parameter "qgroupid" represents the
2703 qgroup which the newly created subvolume will be added to.
2704 This command has one or more optional arguments. See "OPTIONAL
2706 ARGUMENTS".
2707 This command depends on the feature "btrfs". See also "feature-
2709 available".
2710 btrfs-subvolume-delete
2712 btrfs-subvolume-delete subvolume
2713 Delete the named btrfs subvolume or snapshot.
2715 This command depends on the feature "btrfs". See also "feature-
2717 available".
2718 btrfs-subvolume-get-default
2720 btrfs-subvolume-get-default fs
2721 Get the default subvolume or snapshot of a filesystem mounted at
2723 "mountpoint".
2724 This command depends on the feature "btrfs". See also "feature-
2726 available".
2727 btrfs-subvolume-list
2729 btrfs-subvolume-list fs
2730 List the btrfs snapshots and subvolumes of the btrfs filesystem which
2732 is mounted at "fs".
2733 This command depends on the feature "btrfs". See also "feature-
2735 available".
2736 btrfs-subvolume-set-default
2738 btrfs-subvolume-set-default id fs
2739 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2741 default. See "btrfs-subvolume-list" to get a list of subvolumes.
2742 This command depends on the feature "btrfs". See also "feature-
2744 available".
2745 btrfs-subvolume-show
2747 btrfs-subvolume-show subvolume
2748 Return detailed information of the subvolume.
2750 This command depends on the feature "btrfs". See also "feature-
2752 available".
2753 btrfs-subvolume-snapshot
2755 btrfs-subvolume-snapshot-opts
2756 btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]
2757 Create a snapshot of the btrfs subvolume "source". The "dest" argument
2759 is the destination directory and the name of the snapshot, in the form
2760 /path/to/dest/name. By default the newly created snapshot is writable,
2761 if the value of optional parameter "ro" is true, then a readonly
2762 snapshot is created. The optional parameter "qgroupid" represents the
2763 qgroup which the newly created snapshot will be added to.
2764 This command has one or more optional arguments. See "OPTIONAL
2766 ARGUMENTS".
2767 This command depends on the feature "btrfs". See also "feature-
2769 available".
2770 btrfstune-enable-extended-inode-refs
2772 btrfstune-enable-extended-inode-refs device
2773 This will Enable extended inode refs.
2775 This command depends on the feature "btrfs". See also "feature-
2777 available".
2778 btrfstune-enable-skinny-metadata-extent-refs
2780 btrfstune-enable-skinny-metadata-extent-refs device
2781 This enable skinny metadata extent refs.
2783 This command depends on the feature "btrfs". See also "feature-
2785 available".
2786 btrfstune-seeding
2788 btrfstune-seeding device true|false
2789 Enable seeding of a btrfs device, this will force a fs readonly so that
2791 you can use it to build other filesystems.
2792 This command depends on the feature "btrfs". See also "feature-
2794 available".
2795 c-pointer
2797 c-pointer
2798 In non-C language bindings, this allows you to retrieve the underlying
2800 C pointer to the handle (ie. "h *"). The purpose of this is to allow
2801 other libraries to interwork with libguestfs.
2802 canonical-device-name
2804 canonical-device-name device
2805 This utility function is useful when displaying device names to the
2807 user. It takes a number of irregular device names and returns them in
2808 a consistent format:
2809 /dev/hdX
2811 /dev/vdX
2812 These are returned as /dev/sdX. Note this works for device names
2813 and partition names. This is approximately the reverse of the
2814 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2815 /dev/mapper/VG-LV
2817 /dev/dm-N
2818 Converted to /dev/VG/LV form using "lvm-canonical-lv-name".
2819 Other strings are returned unmodified.
2821 cap-get-file
2823 cap-get-file path
2824 This function returns the Linux capabilities attached to "path". The
2826 capabilities set is returned in text form (see cap_to_text(3)).
2827 If no capabilities are attached to a file, an empty string is returned.
2829 This command depends on the feature "linuxcaps". See also "feature-
2831 available".
2832 cap-set-file
2834 cap-set-file path cap
2835 This function sets the Linux capabilities attached to "path". The
2837 capabilities set "cap" should be passed in text form (see
2838 cap_from_text(3)).
2839 This command depends on the feature "linuxcaps". See also "feature-
2841 available".
2842 case-sensitive-path
2844 case-sensitive-path path
2845 This can be used to resolve case insensitive paths on a filesystem
2847 which is case sensitive. The use case is to resolve paths which you
2848 have read from Windows configuration files or the Windows Registry, to
2849 the true path.
2850 The command handles a peculiarity of the Linux ntfs-3g filesystem
2852 driver (and probably others), which is that although the underlying
2853 filesystem is case-insensitive, the driver exports the filesystem to
2854 Linux as case-sensitive.
2855 One consequence of this is that special directories such as C:\windows
2857 may appear as /WINDOWS or /windows (or other things) depending on the
2858 precise details of how they were created. In Windows itself this would
2859 not be a problem.
2860 Bug or feature? You decide:
2862 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2863 "case-sensitive-path" attempts to resolve the true case of each element
2865 in the path. It will return a resolved path if either the full path or
2866 its parent directory exists. If the parent directory exists but the
2867 full path does not, the case of the parent directory will be correctly
2868 resolved, and the remainder appended unmodified. For example, if the
2869 file "/Windows/System32/netkvm.sys" exists:
2870 "case-sensitive-path" ("/windows/system32/netkvm.sys")
2872 "Windows/System32/netkvm.sys"
2873 "case-sensitive-path" ("/windows/system32/NoSuchFile")
2875 "Windows/System32/NoSuchFile"
2876 "case-sensitive-path" ("/windows/system33/netkvm.sys")
2878 ERROR
2879 Note: Because of the above behaviour, "case-sensitive-path" cannot be
2881 used to check for the existence of a file.
2882 Note: This function does not handle drive names, backslashes etc.
2884 See also "realpath".
2886 cat
2888 cat path
2889 Return the contents of the file named "path".
2891 Because, in C, this function returns a "char *", there is no way to
2893 differentiate between a "\0" character in a file and end of string. To
2894 handle binary files, use the "read-file" or "download" functions.
2895 checksum
2897 checksum csumtype path
2898 This call computes the MD5, SHAx or CRC checksum of the file named
2900 "path".
2901 The type of checksum to compute is given by the "csumtype" parameter
2903 which must have one of the following values:
2904 "crc"
2906 Compute the cyclic redundancy check (CRC) specified by POSIX for
2907 the "cksum" command.
2908 "md5"
2910 Compute the MD5 hash (using the md5sum(1) program).
2911 "sha1"
2913 Compute the SHA1 hash (using the sha1sum(1) program).
2914 "sha224"
2916 Compute the SHA224 hash (using the sha224sum(1) program).
2917 "sha256"
2919 Compute the SHA256 hash (using the sha256sum(1) program).
2920 "sha384"
2922 Compute the SHA384 hash (using the sha384sum(1) program).
2923 "sha512"
2925 Compute the SHA512 hash (using the sha512sum(1) program).
2926 The checksum is returned as a printable string.
2928 To get the checksum for a device, use "checksum-device".
2930 To get the checksums for many files, use "checksums-out".
2932 checksum-device
2934 checksum-device csumtype device
2935 This call computes the MD5, SHAx or CRC checksum of the contents of the
2937 device named "device". For the types of checksums supported see the
2938 "checksum" command.
2939 checksums-out
2941 checksums-out csumtype directory (sumsfile|-)
2942 This command computes the checksums of all regular files in directory
2944 and then emits a list of those checksums to the local output file
2945 "sumsfile".
2946 This can be used for verifying the integrity of a virtual machine.
2948 However to be properly secure you should pay attention to the output of
2949 the checksum command (it uses the ones from GNU coreutils). In
2950 particular when the filename is not printable, coreutils uses a special
2951 backslash syntax. For more information, see the GNU coreutils info
2952 file.
2953 Use "-" instead of a filename to read/write from stdin/stdout.
2955 chmod
2957 chmod mode path
2958 Change the mode (permissions) of "path" to "mode". Only numeric modes
2960 are supported.
2961 Note: When using this command from guestfish, "mode" by default would
2963 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2964 700.
2965 The mode actually set is affected by the umask.
2967 chown
2969 chown owner group path
2970 Change the file owner to "owner" and group to "group".
2972 Only numeric uid and gid are supported. If you want to use names, you
2974 will need to locate and parse the password file yourself (Augeas
2975 support makes this relatively easy).
2976 clear-backend-setting
2978 clear-backend-setting name
2979 If there is a backend setting string matching "name" or beginning with
2981 "name=", then that string is removed from the backend settings.
2982 This call returns the number of strings which were removed (which may
2984 be 0, 1 or greater than 1).
2985 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2987 command
2989 command 'arguments ...'
2990 This call runs a command from the guest filesystem. The filesystem
2992 must be mounted, and must contain a compatible operating system (ie.
2993 something Linux, with the same or compatible processor architecture).
2994 The single parameter is an argv-style list of arguments. The first
2996 element is the name of the program to run. Subsequent elements are
2997 parameters. The list must be non-empty (ie. must contain a program
2998 name). Note that the command runs directly, and is not invoked via the
2999 shell (see "sh").
3000 The return value is anything printed to stdout by the command.
3002 If the command returns a non-zero exit status, then this function
3004 returns an error message. The error message string is the content of
3005 stderr from the command.
3006 The $PATH environment variable will contain at least /usr/bin and /bin.
3008 If you require a program from another location, you should provide the
3009 full path in the first parameter.
3010 Shared libraries and data files required by the program must be
3012 available on filesystems which are mounted in the correct places. It
3013 is the caller’s responsibility to ensure all filesystems that are
3014 needed are mounted at the right locations.
3015 Because of the message protocol, there is a transfer limit of somewhere
3017 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3018 command-lines
3020 command-lines 'arguments ...'
3021 This is the same as "command", but splits the result into a list of
3023 lines.
3024 See also: "sh-lines"
3026 Because of the message protocol, there is a transfer limit of somewhere
3028 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3029 compress-device-out
3031 compress-device-out ctype device (zdevice|-) [level:N]
3032 This command compresses "device" and writes it out to the local file
3034 "zdevice".
3035 The "ctype" and optional "level" parameters have the same meaning as in
3037 "compress-out".
3038 Use "-" instead of a filename to read/write from stdin/stdout.
3040 This command has one or more optional arguments. See "OPTIONAL
3042 ARGUMENTS".
3043 compress-out
3045 compress-out ctype file (zfile|-) [level:N]
3046 This command compresses file and writes it out to the local file zfile.
3048 The compression program used is controlled by the "ctype" parameter.
3050 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3051 Some compression types may not be supported by particular builds of
3052 libguestfs, in which case you will get an error containing the
3053 substring "not supported".
3054 The optional "level" parameter controls compression level. The meaning
3056 and default for this parameter depends on the compression program being
3057 used.
3058 Use "-" instead of a filename to read/write from stdin/stdout.
3060 This command has one or more optional arguments. See "OPTIONAL
3062 ARGUMENTS".
3063 config
3065 config hvparam hvvalue
3066 This can be used to add arbitrary hypervisor parameters of the form
3068 -param value. Actually it’s not quite arbitrary - we prevent you from
3069 setting some parameters which would interfere with parameters that we
3070 use.
3071 The first character of "hvparam" string must be a "-" (dash).
3073 "hvvalue" can be NULL.
3075 copy-attributes
3077 copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]
3078 Copy the attributes of a path (which can be a file or a directory) to
3080 another path.
3081 By default no attribute is copied, so make sure to specify any (or
3083 "all" to copy everything).
3084 The optional arguments specify which attributes can be copied:
3086 "mode"
3088 Copy part of the file mode from "source" to "destination". Only the
3089 UNIX permissions and the sticky/setuid/setgid bits can be copied.
3090 "xattributes"
3092 Copy the Linux extended attributes (xattrs) from "source" to
3093 "destination". This flag does nothing if the linuxxattrs feature
3094 is not available (see "feature-available").
3095 "ownership"
3097 Copy the owner uid and the group gid of "source" to "destination".
3098 "all"
3100 Copy all the attributes from "source" to "destination". Enabling it
3101 enables all the other flags, if they are not specified already.
3102 This command has one or more optional arguments. See "OPTIONAL
3104 ARGUMENTS".
3105 copy-device-to-device
3107 copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3108 The four calls "copy-device-to-device", "copy-device-to-file", "copy-
3110 file-to-device", and "copy-file-to-file" let you copy from a source
3111 (device|file) to a destination (device|file).
3112 Partial copies can be made since you can specify optionally the source
3114 offset, destination offset and size to copy. These values are all
3115 specified in bytes. If not given, the offsets both default to zero,
3116 and the size defaults to copying as much as possible until we hit the
3117 end of the source.
3118 The source and destination may be the same object. However overlapping
3120 regions may not be copied correctly.
3121 If the destination is a file, it is created if required. If the
3123 destination file is not large enough, it is extended.
3124 If the destination is a file and the "append" flag is not set, then the
3126 destination file is truncated. If the "append" flag is set, then the
3127 copy appends to the destination file. The "append" flag currently
3128 cannot be set for devices.
3129 If the "sparse" flag is true then the call avoids writing blocks that
3131 contain only zeroes, which can help in some situations where the
3132 backing disk is thin-provisioned. Note that unless the target is
3133 already zeroed, using this option will result in incorrect copying.
3134 This command has one or more optional arguments. See "OPTIONAL
3136 ARGUMENTS".
3137 copy-device-to-file
3139 copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3140 See "copy-device-to-device" for a general overview of this call.
3142 This command has one or more optional arguments. See "OPTIONAL
3144 ARGUMENTS".
3145 copy-file-to-device
3147 copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3148 See "copy-device-to-device" for a general overview of this call.
3150 This command has one or more optional arguments. See "OPTIONAL
3152 ARGUMENTS".
3153 copy-file-to-file
3155 copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3156 See "copy-device-to-device" for a general overview of this call.
3158 This is not the function you want for copying files. This is for
3160 copying blocks within existing files. See "cp", "cp-a" and "mv" for
3161 general file copying and moving functions.
3162 This command has one or more optional arguments. See "OPTIONAL
3164 ARGUMENTS".
3165 copy-size
3167 copy-size src dest size
3168 This command copies exactly "size" bytes from one source device or file
3170 "src" to another destination device or file "dest".
3171 Note this will fail if the source is too short or if the destination is
3173 not large enough.
3174 This function is deprecated. In new code, use the "copy-device-to-
3176 device" call instead.
3177 Deprecated functions will not be removed from the API, but the fact
3179 that they are deprecated indicates that there are problems with correct
3180 use of these functions.
3181 cp
3183 cp src dest
3184 This copies a file from "src" to "dest" where "dest" is either a
3186 destination filename or destination directory.
3187 cp-a
3189 cp-a src dest
3190 This copies a file or directory from "src" to "dest" recursively using
3192 the "cp -a" command.
3193 cp-r
3195 cp-r src dest
3196 This copies a file or directory from "src" to "dest" recursively using
3198 the "cp -rP" command.
3199 Most users should use "cp-a" instead. This command is useful when you
3201 don't want to preserve permissions, because the target filesystem does
3202 not support it (primarily when writing to DOS FAT filesystems).
3203 cpio-out
3205 cpio-out directory (cpiofile|-) [format:..]
3206 This command packs the contents of directory and downloads it to local
3208 file "cpiofile".
3209 The optional "format" parameter can be used to select the format. Only
3211 the following formats are currently permitted:
3212 "newc"
3214 New (SVR4) portable format. This format happens to be compatible
3215 with the cpio-like format used by the Linux kernel for initramfs.
3216 This is the default format.
3218 "crc"
3220 New (SVR4) portable format with a checksum.
3221 Use "-" instead of a filename to read/write from stdin/stdout.
3223 This command has one or more optional arguments. See "OPTIONAL
3225 ARGUMENTS".
3226 dd
3228 dd src dest
3229 This command copies from one source device or file "src" to another
3231 destination device or file "dest". Normally you would use this to copy
3232 to or from a device or partition, for example to duplicate a
3233 filesystem.
3234 If the destination is a device, it must be as large or larger than the
3236 source file or device, otherwise the copy will fail. This command
3237 cannot do partial copies (see "copy-device-to-device").
3238 This function is deprecated. In new code, use the "copy-device-to-
3240 device" call instead.
3241 Deprecated functions will not be removed from the API, but the fact
3243 that they are deprecated indicates that there are problems with correct
3244 use of these functions.
3245 device-index
3247 device-index device
3248 This function takes a device name (eg. "/dev/sdb") and returns the
3250 index of the device in the list of devices.
3251 Index numbers start from 0. The named device must exist, for example
3253 as a string returned from "list-devices".
3254 See also "list-devices", "part-to-dev".
3256 df
3258 df
3259 This command runs the df(1) command to report disk space used.
3261 This command is mostly useful for interactive sessions. It is not
3263 intended that you try to parse the output string. Use "statvfs" from
3264 programs.
3265 df-h
3267 df-h
3268 This command runs the "df -h" command to report disk space used in
3270 human-readable format.
3271 This command is mostly useful for interactive sessions. It is not
3273 intended that you try to parse the output string. Use "statvfs" from
3274 programs.
3275 disk-create
3277 disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]
3278 Create a blank disk image called filename (a host file) with format
3280 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
3281 If used with the optional "backingfile" parameter, then a snapshot is
3283 created on top of the backing file. In this case, "size" must be
3284 passed as "-1". The size of the snapshot is the same as the size of
3285 the backing file, which is discovered automatically. You are
3286 encouraged to also pass "backingformat" to describe the format of
3287 "backingfile".
3288 If filename refers to a block device, then the device is formatted.
3290 The "size" is ignored since block devices have an intrinsic size.
3291 The other optional parameters are:
3293 "preallocation"
3295 If format is "raw", then this can be either "off" (or "sparse") or
3296 "full" to create a sparse or fully allocated file respectively.
3297 The default is "off".
3298 If format is "qcow2", then this can be "off" (or "sparse"),
3300 "metadata" or "full". Preallocating metadata can be faster when
3301 doing lots of writes, but uses more space. The default is "off".
3302 "compat"
3304 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
3305 supported by qemu ≥ 1.1.
3306 "clustersize"
3308 "qcow2" only: Change the qcow2 cluster size. The default is 65536
3309 (bytes) and this setting may be any power of two between 512 and
3310 2097152.
3311 Note that this call does not add the new disk to the handle. You may
3313 need to call "add-drive-opts" separately.
3314 This command has one or more optional arguments. See "OPTIONAL
3316 ARGUMENTS".
3317 disk-format
3319 disk-format filename
3320 Detect and return the format of the disk image called filename.
3322 filename can also be a host device, etc. If the format of the image
3323 could not be detected, then "unknown" is returned.
3324 Note that detecting the disk format can be insecure under some
3326 circumstances. See "CVE-2010-3851" in guestfs(3).
3327 See also: "DISK IMAGE FORMATS" in guestfs(3)
3329 disk-has-backing-file
3331 disk-has-backing-file filename
3332 Detect and return whether the disk image filename has a backing file.
3334 Note that detecting disk features can be insecure under some
3336 circumstances. See "CVE-2010-3851" in guestfs(3).
3337 disk-virtual-size
3339 disk-virtual-size filename
3340 Detect and return the virtual size in bytes of the disk image called
3342 filename.
3343 Note that detecting disk features can be insecure under some
3345 circumstances. See "CVE-2010-3851" in guestfs(3).
3346 dmesg
3348 dmesg
3349 This returns the kernel messages (dmesg(1) output) from the guest
3351 kernel. This is sometimes useful for extended debugging of problems.
3352 Another way to get the same information is to enable verbose messages
3354 with "set-verbose" or by setting the environment variable
3355 "LIBGUESTFS_DEBUG=1" before running the program.
3356 download
3358 download remotefilename (filename|-)
3359 Download file remotefilename and save it as filename on the local
3361 machine.
3362 filename can also be a named pipe.
3364 See also "upload", "cat".
3366 Use "-" instead of a filename to read/write from stdin/stdout.
3368 download-blocks
3370 download-blocks device start stop (filename|-) [unallocated:true|false]
3371 Download the data units from start address to stop from the disk
3373 partition (eg. /dev/sda1) and save them as filename on the local
3374 machine.
3375 The use of this API on sparse disk image formats such as QCOW, may
3377 result in large zero-filled files downloaded on the host.
3378 The size of a data unit varies across filesystem implementations. On
3380 NTFS filesystems data units are referred as clusters while on ExtX ones
3381 they are referred as fragments.
3382 If the optional "unallocated" flag is true (default is false), only the
3384 unallocated blocks will be extracted. This is useful to detect hidden
3385 data or to retrieve deleted files which data units have not been
3386 overwritten yet.
3387 Use "-" instead of a filename to read/write from stdin/stdout.
3389 This command has one or more optional arguments. See "OPTIONAL
3391 ARGUMENTS".
3392 This command depends on the feature "sleuthkit". See also "feature-
3394 available".
3395 download-inode
3397 download-inode device inode (filename|-)
3398 Download a file given its inode from the disk partition (eg. /dev/sda1)
3400 and save it as filename on the local machine.
3401 It is not required to mount the disk to run this command.
3403 The command is capable of downloading deleted or inaccessible files.
3405 Use "-" instead of a filename to read/write from stdin/stdout.
3407 This command depends on the feature "sleuthkit". See also "feature-
3409 available".
3410 download-offset
3412 download-offset remotefilename (filename|-) offset size
3413 Download file remotefilename and save it as filename on the local
3415 machine.
3416 remotefilename is read for "size" bytes starting at "offset" (this
3418 region must be within the file or device).
3419 Note that there is no limit on the amount of data that can be
3421 downloaded with this call, unlike with "pread", and this call always
3422 reads the full amount unless an error occurs.
3423 See also "download", "pread".
3425 Use "-" instead of a filename to read/write from stdin/stdout.
3427 drop-caches
3429 drop-caches whattodrop
3430 This instructs the guest kernel to drop its page cache, and/or dentries
3432 and inode caches. The parameter "whattodrop" tells the kernel what
3433 precisely to drop, see https://linux-mm.org/Drop_Caches
3434 Setting "whattodrop" to 3 should drop everything.
3436 This automatically calls sync(2) before the operation, so that the
3438 maximum guest memory is freed.
3439 du
3441 du path
3442 This command runs the "du -s" command to estimate file space usage for
3444 "path".
3445 "path" can be a file or a directory. If "path" is a directory then the
3447 estimate includes the contents of the directory and all subdirectories
3448 (recursively).
3449 The result is the estimated size in kilobytes (ie. units of 1024
3451 bytes).
3452 e2fsck
3454 e2fsck device [correct:true|false] [forceall:true|false]
3455 This runs the ext2/ext3 filesystem checker on "device". It can take
3457 the following optional arguments:
3458 "correct"
3460 Automatically repair the file system. This option will cause e2fsck
3461 to automatically fix any filesystem problems that can be safely
3462 fixed without human intervention.
3463 This option may not be specified at the same time as the "forceall"
3465 option.
3466 "forceall"
3468 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
3469 used non-interactively.
3470 This option may not be specified at the same time as the "correct"
3472 option.
3473 This command has one or more optional arguments. See "OPTIONAL
3475 ARGUMENTS".
3476 e2fsck-f
3478 e2fsck-f device
3479 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3481 checker on "device", noninteractively (-p), even if the filesystem
3482 appears to be clean (-f).
3483 This function is deprecated. In new code, use the "e2fsck" call
3485 instead.
3486 Deprecated functions will not be removed from the API, but the fact
3488 that they are deprecated indicates that there are problems with correct
3489 use of these functions.
3490 echo-daemon
3492 echo-daemon 'words ...'
3493 This command concatenates the list of "words" passed with single spaces
3495 between them and returns the resulting string.
3496 You can use this command to test the connection through to the daemon.
3498 See also "ping-daemon".
3500 egrep
3502 egrep regex path
3503 This calls the external egrep(1) program and returns the matching
3505 lines.
3506 Because of the message protocol, there is a transfer limit of somewhere
3508 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3509 This function is deprecated. In new code, use the "grep" call instead.
3511 Deprecated functions will not be removed from the API, but the fact
3513 that they are deprecated indicates that there are problems with correct
3514 use of these functions.
3515 egrepi
3517 egrepi regex path
3518 This calls the external "egrep -i" program and returns the matching
3520 lines.
3521 Because of the message protocol, there is a transfer limit of somewhere
3523 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3524 This function is deprecated. In new code, use the "grep" call instead.
3526 Deprecated functions will not be removed from the API, but the fact
3528 that they are deprecated indicates that there are problems with correct
3529 use of these functions.
3530 equal
3532 equal file1 file2
3533 This compares the two files file1 and file2 and returns true if their
3535 content is exactly equal, or false otherwise.
3536 The external cmp(1) program is used for the comparison.
3538 exists
3540 exists path
3541 This returns "true" if and only if there is a file, directory (or
3543 anything) with the given "path" name.
3544 See also "is-file", "is-dir", "stat".
3546 extlinux
3548 extlinux directory
3549 Install the SYSLINUX bootloader on the device mounted at directory.
3551 Unlike "syslinux" which requires a FAT filesystem, this can be used on
3552 an ext2/3/4 or btrfs filesystem.
3553 The directory parameter can be either a mountpoint, or a directory
3555 within the mountpoint.
3556 You also have to mark the partition as "active" ("part-set-bootable")
3558 and a Master Boot Record must be installed (eg. using "pwrite-device")
3559 on the first sector of the whole disk. The SYSLINUX package comes with
3560 some suitable Master Boot Records. See the extlinux(1) man page for
3561 further information.
3562 Additional configuration can be supplied to SYSLINUX by placing a file
3564 called extlinux.conf on the filesystem under directory. For further
3565 information about the contents of this file, see extlinux(1).
3566 See also "syslinux".
3568 This command depends on the feature "extlinux". See also "feature-
3570 available".
3571 f2fs-expand
3573 f2fs-expand device
3574 This expands a f2fs filesystem to match the size of the underlying
3576 device.
3577 This command depends on the feature "f2fs". See also "feature-
3579 available".
3580 fallocate
3582 fallocate path len
3583 This command preallocates a file (containing zero bytes) named "path"
3585 of size "len" bytes. If the file exists already, it is overwritten.
3586 Do not confuse this with the guestfish-specific "alloc" command which
3588 allocates a file in the host and attaches it as a device.
3589 This function is deprecated. In new code, use the "fallocate64" call
3591 instead.
3592 Deprecated functions will not be removed from the API, but the fact
3594 that they are deprecated indicates that there are problems with correct
3595 use of these functions.
3596 fallocate64
3598 fallocate64 path len
3599 This command preallocates a file (containing zero bytes) named "path"
3601 of size "len" bytes. If the file exists already, it is overwritten.
3602 Note that this call allocates disk blocks for the file. To create a
3604 sparse file use "truncate-size" instead.
3605 The deprecated call "fallocate" does the same, but owing to an
3607 oversight it only allowed 30 bit lengths to be specified, effectively
3608 limiting the maximum size of files created through that call to 1GB.
3609 Do not confuse this with the guestfish-specific "alloc" and "sparse"
3611 commands which create a file in the host and attach it as a device.
3612 feature-available
3614 feature-available 'groups ...'
3615 This is the same as "available", but unlike that call it returns a
3617 simple true/false boolean result, instead of throwing an exception if a
3618 feature is not found. For other documentation see "available".
3619 fgrep
3621 fgrep pattern path
3622 This calls the external fgrep(1) program and returns the matching
3624 lines.
3625 Because of the message protocol, there is a transfer limit of somewhere
3627 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3628 This function is deprecated. In new code, use the "grep" call instead.
3630 Deprecated functions will not be removed from the API, but the fact
3632 that they are deprecated indicates that there are problems with correct
3633 use of these functions.
3634 fgrepi
3636 fgrepi pattern path
3637 This calls the external "fgrep -i" program and returns the matching
3639 lines.
3640 Because of the message protocol, there is a transfer limit of somewhere
3642 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3643 This function is deprecated. In new code, use the "grep" call instead.
3645 Deprecated functions will not be removed from the API, but the fact
3647 that they are deprecated indicates that there are problems with correct
3648 use of these functions.
3649 file
3651 file path
3652 This call uses the standard file(1) command to determine the type or
3654 contents of the file.
3655 This call will also transparently look inside various types of
3657 compressed file.
3658 The exact command which runs is "file -zb path". Note in particular
3660 that the filename is not prepended to the output (the -b option).
3661 The output depends on the output of the underlying file(1) command and
3663 it can change in future in ways beyond our control. In other words,
3664 the output is not guaranteed by the ABI.
3665 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
3667 "is-zero".
3668 file-architecture
3670 file-architecture filename
3671 This detects the architecture of the binary filename, and returns it if
3673 known.
3674 Currently defined architectures are:
3676 "aarch64"
3678 64 bit ARM.
3679 "arm"
3681 32 bit ARM.
3682 "i386"
3684 This string is returned for all 32 bit i386, i486, i586, i686
3685 binaries irrespective of the precise processor requirements of the
3686 binary.
3687 "ia64"
3689 Intel Itanium.
3690 "ppc"
3692 32 bit Power PC.
3693 "ppc64"
3695 64 bit Power PC (big endian).
3696 "ppc64le"
3698 64 bit Power PC (little endian).
3699 "riscv32"
3701 "riscv64"
3702 "riscv128"
3703 RISC-V 32-, 64- or 128-bit variants.
3704 "s390"
3706 31 bit IBM S/390.
3707 "s390x"
3709 64 bit IBM S/390.
3710 "sparc"
3712 32 bit SPARC.
3713 "sparc64"
3715 64 bit SPARC V9 and above.
3716 "x86_64"
3718 64 bit x86-64.
3719 Libguestfs may return other architecture strings in future.
3721 The function works on at least the following types of files:
3723 · many types of Un*x and Linux binary
3725 · many types of Un*x and Linux shared library
3727 · Windows Win32 and Win64 binaries
3729 · Windows Win32 and Win64 DLLs
3731 Win32 binaries and DLLs return "i386".
3733 Win64 binaries and DLLs return "x86_64".
3735 · Linux kernel modules
3737 · Linux new-style initrd images
3739 · some non-x86 Linux vmlinuz kernels
3741 What it can't do currently:
3743 · static libraries (libfoo.a)
3745 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
3747 · x86 Linux vmlinuz kernels
3749 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
3751 and compressed code, and are horribly hard to unpack. If you want
3752 to find the architecture of a kernel, use the architecture of the
3753 associated initrd or kernel module(s) instead.
3754 filesize
3756 filesize file
3757 This command returns the size of file in bytes.
3759 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
3761 file" etc. To get the size of block devices, use "blockdev-getsize64".
3762 filesystem-available
3764 filesystem-available filesystem
3765 Check whether libguestfs supports the named filesystem. The argument
3767 "filesystem" is a filesystem name, such as "ext3".
3768 You must call "launch" before using this command.
3770 This is mainly useful as a negative test. If this returns true, it
3772 doesn't mean that a particular filesystem can be created or mounted,
3773 since filesystems can fail for other reasons such as it being a later
3774 version of the filesystem, or having incompatible features, or lacking
3775 the right mkfs.<fs> tool.
3776 See also "available", "feature-available", "AVAILABILITY" in
3778 guestfs(3).
3779 filesystem-walk
3781 filesystem-walk device
3782 Walk through the internal structures of a disk partition (eg.
3784 /dev/sda1) in order to return a list of all the files and directories
3785 stored within.
3786 It is not necessary to mount the disk partition to run this command.
3788 All entries in the filesystem are returned. This function can list
3790 deleted or unaccessible files. The entries are not sorted.
3791 The "tsk_dirent" structure contains the following fields.
3793 "tsk_inode"
3795 Filesystem reference number of the node. It might be 0 if the node
3796 has been deleted.
3797 "tsk_type"
3799 Basic file type information. See below for a detailed list of
3800 values.
3801 "tsk_size"
3803 File size in bytes. It might be "-1" if the node has been deleted.
3804 "tsk_name"
3806 The file path relative to its directory.
3807 "tsk_flags"
3809 Bitfield containing extra information regarding the entry. It
3810 contains the logical OR of the following values:
3811 0x0001
3813 If set to 1, the file is allocated and visible within the
3814 filesystem. Otherwise, the file has been deleted. Under
3815 certain circumstances, the function "download_inode" can be
3816 used to recover deleted files.
3817 0x0002
3819 Filesystem such as NTFS and Ext2 or greater, separate the file
3820 name from the metadata structure. The bit is set to 1 when the
3821 file name is in an unallocated state and the metadata structure
3822 is in an allocated one. This generally implies the metadata
3823 has been reallocated to a new file. Therefore, information
3824 such as file type, file size, timestamps, number of links and
3825 symlink target might not correspond with the ones of the
3826 original deleted entry.
3827 0x0004
3829 The bit is set to 1 when the file is compressed using
3830 filesystem native compression support (NTFS). The API is not
3831 able to detect application level compression.
3832 "tsk_atime_sec"
3834 "tsk_atime_nsec"
3835 "tsk_mtime_sec"
3836 "tsk_mtime_nsec"
3837 "tsk_ctime_sec"
3838 "tsk_ctime_nsec"
3839 "tsk_crtime_sec"
3840 "tsk_crtime_nsec"
3841 Respectively, access, modification, last status change and creation
3842 time in Unix format in seconds and nanoseconds.
3843 "tsk_nlink"
3845 Number of file names pointing to this entry.
3846 "tsk_link"
3848 If the entry is a symbolic link, this field will contain the path
3849 to the target file.
3850 The "tsk_type" field will contain one of the following characters:
3852 'b' Block special
3854 'c' Char special
3856 'd' Directory
3858 'f' FIFO (named pipe)
3860 'l' Symbolic link
3862 'r' Regular file
3864 's' Socket
3866 'h' Shadow inode (Solaris)
3868 'w' Whiteout inode (BSD)
3870 'u' Unknown file type
3872 This command depends on the feature "libtsk". See also "feature-
3874 available".
3875 fill
3877 fill c len path
3878 This command creates a new file called "path". The initial content of
3880 the file is "len" octets of "c", where "c" must be a number in the
3881 range "[0..255]".
3882 To fill a file with zero bytes (sparsely), it is much more efficient to
3884 use "truncate-size". To create a file with a pattern of repeating
3885 bytes use "fill-pattern".
3886 fill-dir
3888 fill-dir dir nr
3889 This function, useful for testing filesystems, creates "nr" empty files
3891 in the directory "dir" with names 00000000 through "nr-1" (ie. each
3892 file name is 8 digits long padded with zeroes).
3893 fill-pattern
3895 fill-pattern pattern len path
3896 This function is like "fill" except that it creates a new file of
3898 length "len" containing the repeating pattern of bytes in "pattern".
3899 The pattern is truncated if necessary to ensure the length of the file
3900 is exactly "len" bytes.
3901 find
3903 find directory
3904 This command lists out all files and directories, recursively, starting
3906 at directory. It is essentially equivalent to running the shell
3907 command "find directory -print" but some post-processing happens on the
3908 output, described below.
3909 This returns a list of strings without any prefix. Thus if the
3911 directory structure was:
3912 /tmp/a
3914 /tmp/b
3915 /tmp/c/d
3916 then the returned list from "find" /tmp would be 4 elements:
3918 a
3920 b
3921 c
3922 c/d
3923 If directory is not a directory, then this command returns an error.
3925 The returned list is sorted.
3927 find0
3929 find0 directory (files|-)
3930 This command lists out all files and directories, recursively, starting
3932 at directory, placing the resulting list in the external file called
3933 files.
3934 This command works the same way as "find" with the following
3936 exceptions:
3937 · The resulting list is written to an external file.
3939 · Items (filenames) in the result are separated by "\0" characters.
3941 See find(1) option -print0.
3942 · The result list is not sorted.
3944 Use "-" instead of a filename to read/write from stdin/stdout.
3946 find-inode
3948 find-inode device inode
3949 Searches all the entries associated with the given inode.
3951 For each entry, a "tsk_dirent" structure is returned. See
3953 "filesystem_walk" for more information about "tsk_dirent" structures.
3954 This command depends on the feature "libtsk". See also "feature-
3956 available".
3957 findfs-label
3959 findfs-label label
3960 This command searches the filesystems and returns the one which has the
3962 given label. An error is returned if no such filesystem can be found.
3963 To find the label of a filesystem, use "vfs-label".
3965 findfs-uuid
3967 findfs-uuid uuid
3968 This command searches the filesystems and returns the one which has the
3970 given UUID. An error is returned if no such filesystem can be found.
3971 To find the UUID of a filesystem, use "vfs-uuid".
3973 fsck
3975 fsck fstype device
3976 This runs the filesystem checker (fsck) on "device" which should have
3978 filesystem type "fstype".
3979 The returned integer is the status. See fsck(8) for the list of status
3981 codes from "fsck".
3982 Notes:
3984 · Multiple status codes can be summed together.
3986 · A non-zero return code can mean "success", for example if errors
3988 have been corrected on the filesystem.
3989 · Checking or repairing NTFS volumes is not supported (by linux-
3991 ntfs).
3992 This command is entirely equivalent to running "fsck -a -t fstype
3994 device".
3995 fstrim
3997 fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]
3998 Trim the free space in the filesystem mounted on "mountpoint". The
4000 filesystem must be mounted read-write.
4001 The filesystem contents are not affected, but any free space in the
4003 filesystem is "trimmed", that is, given back to the host device, thus
4004 making disk images more sparse, allowing unused space in qcow2 files to
4005 be reused, etc.
4006 This operation requires support in libguestfs, the mounted filesystem,
4008 the host filesystem, qemu and the host kernel. If this support isn't
4009 present it may give an error or even appear to run but do nothing.
4010 In the case where the kernel vfs driver does not support trimming, this
4012 call will fail with errno set to "ENOTSUP". Currently this happens
4013 when trying to trim FAT filesystems.
4014 See also "zero-free-space". That is a slightly different operation
4016 that turns free space in the filesystem into zeroes. It is valid to
4017 call "fstrim" either instead of, or after calling "zero-free-space".
4018 This command has one or more optional arguments. See "OPTIONAL
4020 ARGUMENTS".
4021 This command depends on the feature "fstrim". See also "feature-
4023 available".
4024 get-append
4026 get-append
4027 Return the additional kernel options which are added to the libguestfs
4029 appliance kernel command line.
4030 If "NULL" then no options are added.
4032 get-attach-method
4034 get-attach-method
4035 Return the current backend.
4037 See "set-backend" and "BACKEND" in guestfs(3).
4039 This function is deprecated. In new code, use the "get-backend" call
4041 instead.
4042 Deprecated functions will not be removed from the API, but the fact
4044 that they are deprecated indicates that there are problems with correct
4045 use of these functions.
4046 get-autosync
4048 get-autosync
4049 Get the autosync flag.
4051 get-backend
4053 get-backend
4054 Return the current backend.
4056 This handle property was previously called the "attach method".
4058 See "set-backend" and "BACKEND" in guestfs(3).
4060 get-backend-setting
4062 get-backend-setting name
4063 Find a backend setting string which is either "name" or begins with
4065 "name=". If "name", this returns the string "1". If "name=", this
4066 returns the part after the equals sign (which may be an empty string).
4067 If no such setting is found, this function throws an error. The errno
4069 (see "last-errno") will be "ESRCH" in this case.
4070 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4072 get-backend-settings
4074 get-backend-settings
4075 Return the current backend settings.
4077 This call returns all backend settings strings. If you want to find a
4079 single backend setting, see "get-backend-setting".
4080 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4082 get-cachedir
4084 get-cachedir
4085 Get the directory used by the handle to store the appliance cache.
4087 get-direct
4089 get-direct
4090 Return the direct appliance mode flag.
4092 This function is deprecated. In new code, use the "internal-get-
4094 console-socket" call instead.
4095 Deprecated functions will not be removed from the API, but the fact
4097 that they are deprecated indicates that there are problems with correct
4098 use of these functions.
4099 get-e2attrs
4101 get-e2attrs file
4102 This returns the file attributes associated with file.
4104 The attributes are a set of bits associated with each inode which
4106 affect the behaviour of the file. The attributes are returned as a
4107 string of letters (described below). The string may be empty,
4108 indicating that no file attributes are set for this file.
4109 These attributes are only present when the file is located on an
4111 ext2/3/4 filesystem. Using this call on other filesystem types will
4112 result in an error.
4113 The characters (file attributes) in the returned string are currently:
4115 'A' When the file is accessed, its atime is not modified.
4117 'a' The file is append-only.
4119 'c' The file is compressed on-disk.
4121 'D' (Directories only.) Changes to this directory are written
4123 synchronously to disk.
4124 'd' The file is not a candidate for backup (see dump(8)).
4126 'E' The file has compression errors.
4128 'e' The file is using extents.
4130 'h' The file is storing its blocks in units of the filesystem blocksize
4132 instead of sectors.
4133 'I' (Directories only.) The directory is using hashed trees.
4135 'i' The file is immutable. It cannot be modified, deleted or renamed.
4137 No link can be created to this file.
4138 'j' The file is data-journaled.
4140 's' When the file is deleted, all its blocks will be zeroed.
4142 'S' Changes to this file are written synchronously to disk.
4144 'T' (Directories only.) This is a hint to the block allocator that
4146 subdirectories contained in this directory should be spread across
4147 blocks. If not present, the block allocator will try to group
4148 subdirectories together.
4149 't' For a file, this disables tail-merging. (Not used by upstream
4151 implementations of ext2.)
4152 'u' When the file is deleted, its blocks will be saved, allowing the
4154 file to be undeleted.
4155 'X' The raw contents of the compressed file may be accessed.
4157 'Z' The compressed file is dirty.
4159 More file attributes may be added to this list later. Not all file
4161 attributes may be set for all kinds of files. For detailed
4162 information, consult the chattr(1) man page.
4163 See also "set-e2attrs".
4165 Don't confuse these attributes with extended attributes (see
4167 "getxattr").
4168 get-e2generation
4170 get-e2generation file
4171 This returns the ext2 file generation of a file. The generation (which
4173 used to be called the "version") is a number associated with an inode.
4174 This is most commonly used by NFS servers.
4175 The generation is only present when the file is located on an ext2/3/4
4177 filesystem. Using this call on other filesystem types will result in
4178 an error.
4179 See "set-e2generation".
4181 get-e2label
4183 get-e2label device
4184 This returns the ext2/3/4 filesystem label of the filesystem on
4186 "device".
4187 This function is deprecated. In new code, use the "vfs-label" call
4189 instead.
4190 Deprecated functions will not be removed from the API, but the fact
4192 that they are deprecated indicates that there are problems with correct
4193 use of these functions.
4194 get-e2uuid
4196 get-e2uuid device
4197 This returns the ext2/3/4 filesystem UUID of the filesystem on
4199 "device".
4200 This function is deprecated. In new code, use the "vfs-uuid" call
4202 instead.
4203 Deprecated functions will not be removed from the API, but the fact
4205 that they are deprecated indicates that there are problems with correct
4206 use of these functions.
4207 get-hv
4209 get-hv
4210 Return the current hypervisor binary.
4212 This is always non-NULL. If it wasn't set already, then this will
4214 return the default qemu binary name.
4215 get-identifier
4217 get-identifier
4218 Get the handle identifier. See "set-identifier".
4220 get-libvirt-requested-credential-challenge
4222 get-libvirt-requested-credential-challenge index
4223 Get the challenge (provided by libvirt) for the "index"'th requested
4225 credential. If libvirt did not provide a challenge, this returns the
4226 empty string "".
4227 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4229 example code.
4230 get-libvirt-requested-credential-defresult
4232 get-libvirt-requested-credential-defresult index
4233 Get the default result (provided by libvirt) for the "index"'th
4235 requested credential. If libvirt did not provide a default result,
4236 this returns the empty string "".
4237 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4239 example code.
4240 get-libvirt-requested-credential-prompt
4242 get-libvirt-requested-credential-prompt index
4243 Get the prompt (provided by libvirt) for the "index"'th requested
4245 credential. If libvirt did not provide a prompt, this returns the
4246 empty string "".
4247 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4249 example code.
4250 get-libvirt-requested-credentials
4252 get-libvirt-requested-credentials
4253 This should only be called during the event callback for events of type
4255 "GUESTFS_EVENT_LIBVIRT_AUTH".
4256 Return the list of credentials requested by libvirt. Possible values
4258 are a subset of the strings provided when you called "set-libvirt-
4259 supported-credentials".
4260 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4262 example code.
4263 get-memsize
4265 get-memsize
4266 This gets the memory size in megabytes allocated to the hypervisor.
4268 If "set-memsize" was not called on this handle, and if
4270 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4271 default value for memsize.
4272 For more information on the architecture of libguestfs, see guestfs(3).
4274 get-network
4276 get-network
4277 This returns the enable network flag.
4279 get-path
4281 get-path
4282 Return the current search path.
4284 This is always non-NULL. If it wasn't set already, then this will
4286 return the default path.
4287 get-pgroup
4289 get-pgroup
4290 This returns the process group flag.
4292 get-pid
4294 pid
4295 get-pid
4296 Return the process ID of the hypervisor. If there is no hypervisor
4298 running, then this will return an error.
4299 This is an internal call used for debugging and testing.
4301 get-program
4303 get-program
4304 Get the program name. See "set-program".
4306 get-qemu
4308 get-qemu
4309 Return the current hypervisor binary (usually qemu).
4311 This is always non-NULL. If it wasn't set already, then this will
4313 return the default qemu binary name.
4314 This function is deprecated. In new code, use the "get-hv" call
4316 instead.
4317 Deprecated functions will not be removed from the API, but the fact
4319 that they are deprecated indicates that there are problems with correct
4320 use of these functions.
4321 get-recovery-proc
4323 get-recovery-proc
4324 Return the recovery process enabled flag.
4326 get-selinux
4328 get-selinux
4329 This returns the current setting of the selinux flag which is passed to
4331 the appliance at boot time. See "set-selinux".
4332 For more information on the architecture of libguestfs, see guestfs(3).
4334 This function is deprecated. In new code, use the "selinux-relabel"
4336 call instead.
4337 Deprecated functions will not be removed from the API, but the fact
4339 that they are deprecated indicates that there are problems with correct
4340 use of these functions.
4341 get-smp
4343 get-smp
4344 This returns the number of virtual CPUs assigned to the appliance.
4346 get-sockdir
4348 get-sockdir
4349 Get the directory used by the handle to store temporary socket files.
4351 This is different from "get-tmpdir", as we need shorter paths for
4353 sockets (due to the limited buffers of filenames for UNIX sockets), and
4354 "get-tmpdir" may be too long for them.
4355 The environment variable "XDG_RUNTIME_DIR" controls the default value:
4357 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
4358 the default.
4359 get-tmpdir
4361 get-tmpdir
4362 Get the directory used by the handle to store temporary files.
4364 get-trace
4366 get-trace
4367 Return the command trace flag.
4369 get-umask
4371 get-umask
4372 Return the current umask. By default the umask is 022 unless it has
4374 been set by calling "umask".
4375 get-verbose
4377 get-verbose
4378 This returns the verbose messages flag.
4380 getcon
4382 getcon
4383 This gets the SELinux security context of the daemon.
4385 See the documentation about SELINUX in guestfs(3), and "setcon"
4387 This function is deprecated. In new code, use the "selinux-relabel"
4389 call instead.
4390 Deprecated functions will not be removed from the API, but the fact
4392 that they are deprecated indicates that there are problems with correct
4393 use of these functions.
4394 This command depends on the feature "selinux". See also "feature-
4396 available".
4397 getxattr
4399 getxattr path name
4400 Get a single extended attribute from file "path" named "name". This
4402 call follows symlinks. If you want to lookup an extended attribute for
4403 the symlink itself, use "lgetxattr".
4404 Normally it is better to get all extended attributes from a file in one
4406 go by calling "getxattrs". However some Linux filesystem
4407 implementations are buggy and do not provide a way to list out
4408 attributes. For these filesystems (notably ntfs-3g) you have to know
4409 the names of the extended attributes you want in advance and call this
4410 function.
4411 Extended attribute values are blobs of binary data. If there is no
4413 extended attribute named "name", this returns an error.
4414 See also: "getxattrs", "lgetxattr", attr(5).
4416 This command depends on the feature "linuxxattrs". See also "feature-
4418 available".
4419 getxattrs
4421 getxattrs path
4422 This call lists the extended attributes of the file or directory
4424 "path".
4425 At the system call level, this is a combination of the listxattr(2) and
4427 getxattr(2) calls.
4428 See also: "lgetxattrs", attr(5).
4430 This command depends on the feature "linuxxattrs". See also "feature-
4432 available".
4433 glob-expand
4435 glob-expand-opts
4436 glob-expand pattern [directoryslash:true|false]
4437 This command searches for all the pathnames matching "pattern"
4439 according to the wildcard expansion rules used by the shell.
4440 If no paths match, then this returns an empty list (note: not an
4442 error).
4443 It is just a wrapper around the C glob(3) function with flags
4445 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
4446 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
4448 and it defaults to true. It can be explicitly set as off to return no
4449 trailing slashes in filenames of directories.
4450 Notice that there is no equivalent command for expanding a device name
4452 (eg. /dev/sd*). Use "list-devices", "list-partitions" etc functions
4453 instead.
4454 This command has one or more optional arguments. See "OPTIONAL
4456 ARGUMENTS".
4457 grep
4459 grep-opts
4460 grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
4461 This calls the external grep(1) program and returns the matching lines.
4463 The optional flags are:
4465 "extended"
4467 Use extended regular expressions. This is the same as using the -E
4468 flag.
4469 "fixed"
4471 Match fixed (don't use regular expressions). This is the same as
4472 using the -F flag.
4473 "insensitive"
4475 Match case-insensitive. This is the same as using the -i flag.
4476 "compressed"
4478 Use zgrep(1) instead of grep(1). This allows the input to be
4479 compress- or gzip-compressed.
4480 This command has one or more optional arguments. See "OPTIONAL
4482 ARGUMENTS".
4483 Because of the message protocol, there is a transfer limit of somewhere
4485 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4486 grepi
4488 grepi regex path
4489 This calls the external "grep -i" program and returns the matching
4491 lines.
4492 Because of the message protocol, there is a transfer limit of somewhere
4494 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4495 This function is deprecated. In new code, use the "grep" call instead.
4497 Deprecated functions will not be removed from the API, but the fact
4499 that they are deprecated indicates that there are problems with correct
4500 use of these functions.
4501 grub-install
4503 grub-install root device
4504 This command installs GRUB 1 (the Grand Unified Bootloader) on
4506 "device", with the root directory being "root".
4507 Notes:
4509 · There is currently no way in the API to install grub2, which is
4511 used by most modern Linux guests. It is possible to run the grub2
4512 command from the guest, although see the caveats in "RUNNING
4513 COMMANDS" in guestfs(3).
4514 · This uses grub-install(8) from the host. Unfortunately grub is not
4516 always compatible with itself, so this only works in rather narrow
4517 circumstances. Careful testing with each guest version is
4518 advisable.
4519 · If grub-install reports the error "No suitable drive was found in
4521 the generated device map." it may be that you need to create a
4522 /boot/grub/device.map file first that contains the mapping between
4523 grub device names and Linux device names. It is usually sufficient
4524 to create a file containing:
4525 (hd0) /dev/vda
4527 replacing /dev/vda with the name of the installation device.
4529 This command depends on the feature "grub". See also "feature-
4531 available".
4532 head
4534 head path
4535 This command returns up to the first 10 lines of a file as a list of
4537 strings.
4538 Because of the message protocol, there is a transfer limit of somewhere
4540 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4541 head-n
4543 head-n nrlines path
4544 If the parameter "nrlines" is a positive number, this returns the first
4546 "nrlines" lines of the file "path".
4547 If the parameter "nrlines" is a negative number, this returns lines
4549 from the file "path", excluding the last "nrlines" lines.
4550 If the parameter "nrlines" is zero, this returns an empty list.
4552 Because of the message protocol, there is a transfer limit of somewhere
4554 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4555 hexdump
4557 hexdump path
4558 This runs "hexdump -C" on the given "path". The result is the human-
4560 readable, canonical hex dump of the file.
4561 Because of the message protocol, there is a transfer limit of somewhere
4563 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4564 hivex-close
4566 hivex-close
4567 Close the current hivex handle.
4569 This is a wrapper around the hivex(3) call of the same name.
4571 This command depends on the feature "hivex". See also "feature-
4573 available".
4574 hivex-commit
4576 hivex-commit filename
4577 Commit (write) changes to the hive.
4579 If the optional filename parameter is null, then the changes are
4581 written back to the same hive that was opened. If this is not null
4582 then they are written to the alternate filename given and the original
4583 hive is left untouched.
4584 This is a wrapper around the hivex(3) call of the same name.
4586 This command depends on the feature "hivex". See also "feature-
4588 available".
4589 hivex-node-add-child
4591 hivex-node-add-child parent name
4592 Add a child node to "parent" named "name".
4594 This is a wrapper around the hivex(3) call of the same name.
4596 This command depends on the feature "hivex". See also "feature-
4598 available".
4599 hivex-node-children
4601 hivex-node-children nodeh
4602 Return the list of nodes which are subkeys of "nodeh".
4604 This is a wrapper around the hivex(3) call of the same name.
4606 This command depends on the feature "hivex". See also "feature-
4608 available".
4609 hivex-node-delete-child
4611 hivex-node-delete-child nodeh
4612 Delete "nodeh", recursively if necessary.
4614 This is a wrapper around the hivex(3) call of the same name.
4616 This command depends on the feature "hivex". See also "feature-
4618 available".
4619 hivex-node-get-child
4621 hivex-node-get-child nodeh name
4622 Return the child of "nodeh" with the name "name", if it exists. This
4624 can return 0 meaning the name was not found.
4625 This is a wrapper around the hivex(3) call of the same name.
4627 This command depends on the feature "hivex". See also "feature-
4629 available".
4630 hivex-node-get-value
4632 hivex-node-get-value nodeh key
4633 Return the value attached to "nodeh" which has the name "key", if it
4635 exists. This can return 0 meaning the key was not found.
4636 This is a wrapper around the hivex(3) call of the same name.
4638 This command depends on the feature "hivex". See also "feature-
4640 available".
4641 hivex-node-name
4643 hivex-node-name nodeh
4644 Return the name of "nodeh".
4646 This is a wrapper around the hivex(3) call of the same name.
4648 This command depends on the feature "hivex". See also "feature-
4650 available".
4651 hivex-node-parent
4653 hivex-node-parent nodeh
4654 Return the parent node of "nodeh".
4656 This is a wrapper around the hivex(3) call of the same name.
4658 This command depends on the feature "hivex". See also "feature-
4660 available".
4661 hivex-node-set-value
4663 hivex-node-set-value nodeh key t val
4664 Set or replace a single value under the node "nodeh". The "key" is the
4666 name, "t" is the type, and "val" is the data.
4667 This is a wrapper around the hivex(3) call of the same name.
4669 This command depends on the feature "hivex". See also "feature-
4671 available".
4672 hivex-node-values
4674 hivex-node-values nodeh
4675 Return the array of (key, datatype, data) tuples attached to "nodeh".
4677 This is a wrapper around the hivex(3) call of the same name.
4679 This command depends on the feature "hivex". See also "feature-
4681 available".
4682 hivex-open
4684 hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]
4685 Open the Windows Registry hive file named filename. If there was any
4687 previous hivex handle associated with this guestfs session, then it is
4688 closed.
4689 This is a wrapper around the hivex(3) call of the same name.
4691 This command has one or more optional arguments. See "OPTIONAL
4693 ARGUMENTS".
4694 This command depends on the feature "hivex". See also "feature-
4696 available".
4697 hivex-root
4699 hivex-root
4700 Return the root node of the hive.
4702 This is a wrapper around the hivex(3) call of the same name.
4704 This command depends on the feature "hivex". See also "feature-
4706 available".
4707 hivex-value-key
4709 hivex-value-key valueh
4710 Return the key (name) field of a (key, datatype, data) tuple.
4712 This is a wrapper around the hivex(3) call of the same name.
4714 This command depends on the feature "hivex". See also "feature-
4716 available".
4717 hivex-value-string
4719 hivex-value-string valueh
4720 This calls "hivex-value-value" (which returns the data field from a
4722 hivex value tuple). It then assumes that the field is a UTF-16LE
4723 string and converts the result to UTF-8 (or if this is not possible, it
4724 returns an error).
4725 This is useful for reading strings out of the Windows registry.
4727 However it is not foolproof because the registry is not strongly-typed
4728 and fields can contain arbitrary or unexpected data.
4729 This command depends on the feature "hivex". See also "feature-
4731 available".
4732 hivex-value-type
4734 hivex-value-type valueh
4735 Return the data type field from a (key, datatype, data) tuple.
4737 This is a wrapper around the hivex(3) call of the same name.
4739 This command depends on the feature "hivex". See also "feature-
4741 available".
4742 hivex-value-utf8
4744 hivex-value-utf8 valueh
4745 This calls "hivex-value-value" (which returns the data field from a
4747 hivex value tuple). It then assumes that the field is a UTF-16LE
4748 string and converts the result to UTF-8 (or if this is not possible, it
4749 returns an error).
4750 This is useful for reading strings out of the Windows registry.
4752 However it is not foolproof because the registry is not strongly-typed
4753 and fields can contain arbitrary or unexpected data.
4754 This function is deprecated. In new code, use the "hivex-value-string"
4756 call instead.
4757 Deprecated functions will not be removed from the API, but the fact
4759 that they are deprecated indicates that there are problems with correct
4760 use of these functions.
4761 This command depends on the feature "hivex". See also "feature-
4763 available".
4764 hivex-value-value
4766 hivex-value-value valueh
4767 Return the data field of a (key, datatype, data) tuple.
4769 This is a wrapper around the hivex(3) call of the same name.
4771 See also: "hivex-value-utf8".
4773 This command depends on the feature "hivex". See also "feature-
4775 available".
4776 initrd-cat
4778 initrd-cat initrdpath filename
4779 This command unpacks the file filename from the initrd file called
4781 initrdpath. The filename must be given without the initial /
4782 character.
4783 For example, in guestfish you could use the following command to
4785 examine the boot script (usually called /init) contained in a Linux
4786 initrd or initramfs image:
4787 initrd-cat /boot/initrd-<version>.img init
4789 See also "initrd-list".
4791 Because of the message protocol, there is a transfer limit of somewhere
4793 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4794 initrd-list
4796 initrd-list path
4797 This command lists out files contained in an initrd.
4799 The files are listed without any initial / character. The files are
4801 listed in the order they appear (not necessarily alphabetical).
4802 Directory names are listed as separate items.
4803 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
4805 as initrd. We only support the newer initramfs format (compressed cpio
4806 files).
4807 inotify-add-watch
4809 inotify-add-watch path mask
4810 Watch "path" for the events listed in "mask".
4812 Note that if "path" is a directory then events within that directory
4814 are watched, but this does not happen recursively (in subdirectories).
4815 Note for non-C or non-Linux callers: the inotify events are defined by
4817 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
4818 This command depends on the feature "inotify". See also "feature-
4820 available".
4821 inotify-close
4823 inotify-close
4824 This closes the inotify handle which was previously opened by
4826 inotify_init. It removes all watches, throws away any pending events,
4827 and deallocates all resources.
4828 This command depends on the feature "inotify". See also "feature-
4830 available".
4831 inotify-files
4833 inotify-files
4834 This function is a helpful wrapper around "inotify-read" which just
4836 returns a list of pathnames of objects that were touched. The returned
4837 pathnames are sorted and deduplicated.
4838 This command depends on the feature "inotify". See also "feature-
4840 available".
4841 inotify-init
4843 inotify-init maxevents
4844 This command creates a new inotify handle. The inotify subsystem can
4846 be used to notify events which happen to objects in the guest
4847 filesystem.
4848 "maxevents" is the maximum number of events which will be queued up
4850 between calls to "inotify-read" or "inotify-files". If this is passed
4851 as 0, then the kernel (or previously set) default is used. For Linux
4852 2.6.29 the default was 16384 events. Beyond this limit, the kernel
4853 throws away events, but records the fact that it threw them away by
4854 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
4855 "inotify-read").
4856 Before any events are generated, you have to add some watches to the
4858 internal watch list. See: "inotify-add-watch" and "inotify-rm-watch".
4859 Queued up events should be read periodically by calling "inotify-read"
4861 (or "inotify-files" which is just a helpful wrapper around "inotify-
4862 read"). If you don't read the events out often enough then you risk
4863 the internal queue overflowing.
4864 The handle should be closed after use by calling "inotify-close". This
4866 also removes any watches automatically.
4867 See also inotify(7) for an overview of the inotify interface as exposed
4869 by the Linux kernel, which is roughly what we expose via libguestfs.
4870 Note that there is one global inotify handle per libguestfs instance.
4871 This command depends on the feature "inotify". See also "feature-
4873 available".
4874 inotify-read
4876 inotify-read
4877 Return the complete queue of events that have happened since the
4879 previous read call.
4880 If no events have happened, this returns an empty list.
4882 Note: In order to make sure that all events have been read, you must
4884 call this function repeatedly until it returns an empty list. The
4885 reason is that the call will read events up to the maximum appliance-
4886 to-host message size and leave remaining events in the queue.
4887 This command depends on the feature "inotify". See also "feature-
4889 available".
4890 inotify-rm-watch
4892 inotify-rm-watch wd
4893 Remove a previously defined inotify watch. See "inotify-add-watch".
4895 This command depends on the feature "inotify". See also "feature-
4897 available".
4898 inspect-get-arch
4900 inspect-get-arch root
4901 This returns the architecture of the inspected operating system. The
4903 possible return values are listed under "file-architecture".
4904 If the architecture could not be determined, then the string "unknown"
4906 is returned.
4907 Please read "INSPECTION" in guestfs(3) for more details.
4909 inspect-get-distro
4911 inspect-get-distro root
4912 This returns the distro (distribution) of the inspected operating
4914 system.
4915 Currently defined distros are:
4917 "alpinelinux"
4919 Alpine Linux.
4920 "altlinux"
4922 ALT Linux.
4923 "archlinux"
4925 Arch Linux.
4926 "buildroot"
4928 Buildroot-derived distro, but not one we specifically recognize.
4929 "centos"
4931 CentOS.
4932 "cirros"
4934 Cirros.
4935 "coreos"
4937 CoreOS.
4938 "debian"
4940 Debian.
4941 "fedora"
4943 Fedora.
4944 "freebsd"
4946 FreeBSD.
4947 "freedos"
4949 FreeDOS.
4950 "frugalware"
4952 Frugalware.
4953 "gentoo"
4955 Gentoo.
4956 "kalilinux"
4958 Kali Linux.
4959 "linuxmint"
4961 Linux Mint.
4962 "mageia"
4964 Mageia.
4965 "mandriva"
4967 Mandriva.
4968 "meego"
4970 MeeGo.
4971 "msdos"
4973 Microsoft DOS.
4974 "neokylin"
4976 NeoKylin.
4977 "netbsd"
4979 NetBSD.
4980 "openbsd"
4982 OpenBSD.
4983 "openmandriva"
4985 OpenMandriva Lx.
4986 "opensuse"
4988 OpenSUSE.
4989 "oraclelinux"
4991 Oracle Linux.
4992 "pardus"
4994 Pardus.
4995 "pldlinux"
4997 PLD Linux.
4998 "redhat-based"
5000 Some Red Hat-derived distro.
5001 "rhel"
5003 Red Hat Enterprise Linux.
5004 "scientificlinux"
5006 Scientific Linux.
5007 "slackware"
5009 Slackware.
5010 "sles"
5012 SuSE Linux Enterprise Server or Desktop.
5013 "suse-based"
5015 Some openSuSE-derived distro.
5016 "ttylinux"
5018 ttylinux.
5019 "ubuntu"
5021 Ubuntu.
5022 "unknown"
5024 The distro could not be determined.
5025 "voidlinux"
5027 Void Linux.
5028 "windows"
5030 Windows does not have distributions. This string is returned if
5031 the OS type is Windows.
5032 Future versions of libguestfs may return other strings here. The
5034 caller should be prepared to handle any string.
5035 Please read "INSPECTION" in guestfs(3) for more details.
5037 inspect-get-drive-mappings
5039 inspect-get-drive-mappings root
5040 This call is useful for Windows which uses a primitive system of
5042 assigning drive letters (like C:\) to partitions. This inspection API
5043 examines the Windows Registry to find out how disks/partitions are
5044 mapped to drive letters, and returns a hash table as in the example
5045 below:
5046 C => /dev/vda2
5048 E => /dev/vdb1
5049 F => /dev/vdc1
5050 Note that keys are drive letters. For Windows, the key is case
5052 insensitive and just contains the drive letter, without the customary
5053 colon separator character.
5054 In future we may support other operating systems that also used drive
5056 letters, but the keys for those might not be case insensitive and might
5057 be longer than 1 character. For example in OS-9, hard drives were
5058 named "h0", "h1" etc.
5059 For Windows guests, currently only hard drive mappings are returned.
5061 Removable disks (eg. DVD-ROMs) are ignored.
5062 For guests that do not use drive mappings, or if the drive mappings
5064 could not be determined, this returns an empty hash table.
5065 Please read "INSPECTION" in guestfs(3) for more details. See also
5067 "inspect-get-mountpoints", "inspect-get-filesystems".
5068 inspect-get-filesystems
5070 inspect-get-filesystems root
5071 This returns a list of all the filesystems that we think are associated
5073 with this operating system. This includes the root filesystem, other
5074 ordinary filesystems, and non-mounted devices like swap partitions.
5075 In the case of a multi-boot virtual machine, it is possible for a
5077 filesystem to be shared between operating systems.
5078 Please read "INSPECTION" in guestfs(3) for more details. See also
5080 "inspect-get-mountpoints".
5081 inspect-get-format
5083 inspect-get-format root
5084 Before libguestfs 1.38, there was some unreliable support for detecting
5086 installer CDs. This API would return:
5087 "installed"
5089 This is an installed operating system.
5090 "installer"
5092 The disk image being inspected is not an installed operating
5093 system, but a bootable install disk, live CD, or similar.
5094 "unknown"
5096 The format of this disk image is not known.
5097 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
5099 directly to detect installer CDs.
5100 Please read "INSPECTION" in guestfs(3) for more details.
5102 This function is deprecated. There is no replacement. Consult the API
5104 documentation in guestfs(3) for further information.
5105 Deprecated functions will not be removed from the API, but the fact
5107 that they are deprecated indicates that there are problems with correct
5108 use of these functions.
5109 inspect-get-hostname
5111 inspect-get-hostname root
5112 This function returns the hostname of the operating system as found by
5114 inspection of the guest’s configuration files.
5115 If the hostname could not be determined, then the string "unknown" is
5117 returned.
5118 Please read "INSPECTION" in guestfs(3) for more details.
5120 inspect-get-icon
5122 inspect-get-icon root [favicon:true|false] [highquality:true|false]
5123 This function returns an icon corresponding to the inspected operating
5125 system. The icon is returned as a buffer containing a PNG image (re-
5126 encoded to PNG if necessary).
5127 If it was not possible to get an icon this function returns a zero-
5129 length (non-NULL) buffer. Callers must check for this case.
5130 Libguestfs will start by looking for a file called /etc/favicon.png or
5132 C:\etc\favicon.png and if it has the correct format, the contents of
5133 this file will be returned. You can disable favicons by passing the
5134 optional "favicon" boolean as false (default is true).
5135 If finding the favicon fails, then we look in other places in the guest
5137 for a suitable icon.
5138 If the optional "highquality" boolean is true then only high quality
5140 icons are returned, which means only icons of high resolution with an
5141 alpha channel. The default (false) is to return any icon we can, even
5142 if it is of substandard quality.
5143 Notes:
5145 · Unlike most other inspection API calls, the guest’s disks must be
5147 mounted up before you call this, since it needs to read information
5148 from the guest filesystem during the call.
5149 · Security: The icon data comes from the untrusted guest, and should
5151 be treated with caution. PNG files have been known to contain
5152 exploits. Ensure that libpng (or other relevant libraries) are
5153 fully up to date before trying to process or display the icon.
5154 · The PNG image returned can be any size. It might not be square.
5156 Libguestfs tries to return the largest, highest quality icon
5157 available. The application must scale the icon to the required
5158 size.
5159 · Extracting icons from Windows guests requires the external
5161 wrestool(1) program from the "icoutils" package, and several
5162 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
5163 package. These must be installed separately.
5164 · Operating system icons are usually trademarks. Seek legal advice
5166 before using trademarks in applications.
5167 This command has one or more optional arguments. See "OPTIONAL
5169 ARGUMENTS".
5170 inspect-get-major-version
5172 inspect-get-major-version root
5173 This returns the major version number of the inspected operating
5175 system.
5176 Windows uses a consistent versioning scheme which is not reflected in
5178 the popular public names used by the operating system. Notably the
5179 operating system known as "Windows 7" is really version 6.1 (ie. major
5180 = 6, minor = 1). You can find out the real versions corresponding to
5181 releases of Windows by consulting Wikipedia or MSDN.
5182 If the version could not be determined, then 0 is returned.
5184 Please read "INSPECTION" in guestfs(3) for more details.
5186 inspect-get-minor-version
5188 inspect-get-minor-version root
5189 This returns the minor version number of the inspected operating
5191 system.
5192 If the version could not be determined, then 0 is returned.
5194 Please read "INSPECTION" in guestfs(3) for more details. See also
5196 "inspect-get-major-version".
5197 inspect-get-mountpoints
5199 inspect-get-mountpoints root
5200 This returns a hash of where we think the filesystems associated with
5202 this operating system should be mounted. Callers should note that this
5203 is at best an educated guess made by reading configuration files such
5204 as /etc/fstab. In particular note that this may return filesystems
5205 which are non-existent or not mountable and callers should be prepared
5206 to handle or ignore failures if they try to mount them.
5207 Each element in the returned hashtable has a key which is the path of
5209 the mountpoint (eg. /boot) and a value which is the filesystem that
5210 would be mounted there (eg. /dev/sda1).
5211 Non-mounted devices such as swap devices are not returned in this list.
5213 For operating systems like Windows which still use drive letters, this
5215 call will only return an entry for the first drive "mounted on" /. For
5216 information about the mapping of drive letters to partitions, see
5217 "inspect-get-drive-mappings".
5218 Please read "INSPECTION" in guestfs(3) for more details. See also
5220 "inspect-get-filesystems".
5221 inspect-get-osinfo
5223 inspect-get-osinfo root
5224 This function returns a possible short ID for libosinfo corresponding
5226 to the guest.
5227 Note: The returned ID is only a guess by libguestfs, and nothing
5229 ensures that it actually exists in osinfo-db.
5230 If no ID could not be determined, then the string "unknown" is
5232 returned.
5233 inspect-get-package-format
5235 inspect-get-package-format root
5236 This function and "inspect-get-package-management" return the package
5238 format and package management tool used by the inspected operating
5239 system. For example for Fedora these functions would return "rpm"
5240 (package format), and "yum" or "dnf" (package management).
5241 This returns the string "unknown" if we could not determine the package
5243 format or if the operating system does not have a real packaging system
5244 (eg. Windows).
5245 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5247 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
5248 other strings.
5249 Please read "INSPECTION" in guestfs(3) for more details.
5251 inspect-get-package-management
5253 inspect-get-package-management root
5254 "inspect-get-package-format" and this function return the package
5256 format and package management tool used by the inspected operating
5257 system. For example for Fedora these functions would return "rpm"
5258 (package format), and "yum" or "dnf" (package management).
5259 This returns the string "unknown" if we could not determine the package
5261 management tool or if the operating system does not have a real
5262 packaging system (eg. Windows).
5263 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
5265 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
5266 "apk", "xbps". Future versions of libguestfs may return other strings.
5267 Please read "INSPECTION" in guestfs(3) for more details.
5269 inspect-get-product-name
5271 inspect-get-product-name root
5272 This returns the product name of the inspected operating system. The
5274 product name is generally some freeform string which can be displayed
5275 to the user, but should not be parsed by programs.
5276 If the product name could not be determined, then the string "unknown"
5278 is returned.
5279 Please read "INSPECTION" in guestfs(3) for more details.
5281 inspect-get-product-variant
5283 inspect-get-product-variant root
5284 This returns the product variant of the inspected operating system.
5286 For Windows guests, this returns the contents of the Registry key
5288 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
5289 which is usually a string such as "Client" or "Server" (other values
5290 are possible). This can be used to distinguish consumer and enterprise
5291 versions of Windows that have the same version number (for example,
5292 Windows 7 and Windows 2008 Server are both version 6.1, but the former
5293 is "Client" and the latter is "Server").
5294 For enterprise Linux guests, in future we intend this to return the
5296 product variant such as "Desktop", "Server" and so on. But this is not
5297 implemented at present.
5298 If the product variant could not be determined, then the string
5300 "unknown" is returned.
5301 Please read "INSPECTION" in guestfs(3) for more details. See also
5303 "inspect-get-product-name", "inspect-get-major-version".
5304 inspect-get-roots
5306 inspect-get-roots
5307 This function is a convenient way to get the list of root devices, as
5309 returned from a previous call to "inspect-os", but without redoing the
5310 whole inspection process.
5311 This returns an empty list if either no root devices were found or the
5313 caller has not called "inspect-os".
5314 Please read "INSPECTION" in guestfs(3) for more details.
5316 inspect-get-type
5318 inspect-get-type root
5319 This returns the type of the inspected operating system. Currently
5321 defined types are:
5322 "linux"
5324 Any Linux-based operating system.
5325 "windows"
5327 Any Microsoft Windows operating system.
5328 "freebsd"
5330 FreeBSD.
5331 "netbsd"
5333 NetBSD.
5334 "openbsd"
5336 OpenBSD.
5337 "hurd"
5339 GNU/Hurd.
5340 "dos"
5342 MS-DOS, FreeDOS and others.
5343 "minix"
5345 MINIX.
5346 "unknown"
5348 The operating system type could not be determined.
5349 Future versions of libguestfs may return other strings here. The
5351 caller should be prepared to handle any string.
5352 Please read "INSPECTION" in guestfs(3) for more details.
5354 inspect-get-windows-current-control-set
5356 inspect-get-windows-current-control-set root
5357 This returns the Windows CurrentControlSet of the inspected guest. The
5359 CurrentControlSet is a registry key name such as "ControlSet001".
5360 This call assumes that the guest is Windows and that the Registry could
5362 be examined by inspection. If this is not the case then an error is
5363 returned.
5364 Please read "INSPECTION" in guestfs(3) for more details.
5366 inspect-get-windows-software-hive
5368 inspect-get-windows-software-hive root
5369 This returns the path to the hive (binary Windows Registry file)
5371 corresponding to HKLM\SOFTWARE.
5372 This call assumes that the guest is Windows and that the guest has a
5374 software hive file with the right name. If this is not the case then
5375 an error is returned. This call does not check that the hive is a
5376 valid Windows Registry hive.
5377 You can use "hivex-open" to read or write to the hive.
5379 Please read "INSPECTION" in guestfs(3) for more details.
5381 inspect-get-windows-system-hive
5383 inspect-get-windows-system-hive root
5384 This returns the path to the hive (binary Windows Registry file)
5386 corresponding to HKLM\SYSTEM.
5387 This call assumes that the guest is Windows and that the guest has a
5389 system hive file with the right name. If this is not the case then an
5390 error is returned. This call does not check that the hive is a valid
5391 Windows Registry hive.
5392 You can use "hivex-open" to read or write to the hive.
5394 Please read "INSPECTION" in guestfs(3) for more details.
5396 inspect-get-windows-systemroot
5398 inspect-get-windows-systemroot root
5399 This returns the Windows systemroot of the inspected guest. The
5401 systemroot is a directory path such as /WINDOWS.
5402 This call assumes that the guest is Windows and that the systemroot
5404 could be determined by inspection. If this is not the case then an
5405 error is returned.
5406 Please read "INSPECTION" in guestfs(3) for more details.
5408 inspect-is-live
5410 inspect-is-live root
5411 This is deprecated and always returns "false".
5413 Please read "INSPECTION" in guestfs(3) for more details.
5415 This function is deprecated. There is no replacement. Consult the API
5417 documentation in guestfs(3) for further information.
5418 Deprecated functions will not be removed from the API, but the fact
5420 that they are deprecated indicates that there are problems with correct
5421 use of these functions.
5422 inspect-is-multipart
5424 inspect-is-multipart root
5425 This is deprecated and always returns "false".
5427 Please read "INSPECTION" in guestfs(3) for more details.
5429 This function is deprecated. There is no replacement. Consult the API
5431 documentation in guestfs(3) for further information.
5432 Deprecated functions will not be removed from the API, but the fact
5434 that they are deprecated indicates that there are problems with correct
5435 use of these functions.
5436 inspect-is-netinst
5438 inspect-is-netinst root
5439 This is deprecated and always returns "false".
5441 Please read "INSPECTION" in guestfs(3) for more details.
5443 This function is deprecated. There is no replacement. Consult the API
5445 documentation in guestfs(3) for further information.
5446 Deprecated functions will not be removed from the API, but the fact
5448 that they are deprecated indicates that there are problems with correct
5449 use of these functions.
5450 inspect-list-applications
5452 inspect-list-applications root
5453 Return the list of applications installed in the operating system.
5455 Note: This call works differently from other parts of the inspection
5457 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5458 then mount up the disks, before calling this. Listing applications is
5459 a significantly more difficult operation which requires access to the
5460 full filesystem. Also note that unlike the other "inspect-get-*" calls
5461 which are just returning data cached in the libguestfs handle, this
5462 call actually reads parts of the mounted filesystems during the call.
5463 This returns an empty list if the inspection code was not able to
5465 determine the list of applications.
5466 The application structure contains the following fields:
5468 "app_name"
5470 The name of the application. For Linux guests, this is the package
5471 name.
5472 "app_display_name"
5474 The display name of the application, sometimes localized to the
5475 install language of the guest operating system.
5476 If unavailable this is returned as an empty string "". Callers
5478 needing to display something can use "app_name" instead.
5479 "app_epoch"
5481 For package managers which use epochs, this contains the epoch of
5482 the package (an integer). If unavailable, this is returned as 0.
5483 "app_version"
5485 The version string of the application or package. If unavailable
5486 this is returned as an empty string "".
5487 "app_release"
5489 The release string of the application or package, for package
5490 managers that use this. If unavailable this is returned as an
5491 empty string "".
5492 "app_install_path"
5494 The installation path of the application (on operating systems such
5495 as Windows which use installation paths). This path is in the
5496 format used by the guest operating system, it is not a libguestfs
5497 path.
5498 If unavailable this is returned as an empty string "".
5500 "app_trans_path"
5502 The install path translated into a libguestfs path. If unavailable
5503 this is returned as an empty string "".
5504 "app_publisher"
5506 The name of the publisher of the application, for package managers
5507 that use this. If unavailable this is returned as an empty string
5508 "".
5509 "app_url"
5511 The URL (eg. upstream URL) of the application. If unavailable this
5512 is returned as an empty string "".
5513 "app_source_package"
5515 For packaging systems which support this, the name of the source
5516 package. If unavailable this is returned as an empty string "".
5517 "app_summary"
5519 A short (usually one line) description of the application or
5520 package. If unavailable this is returned as an empty string "".
5521 "app_description"
5523 A longer description of the application or package. If unavailable
5524 this is returned as an empty string "".
5525 Please read "INSPECTION" in guestfs(3) for more details.
5527 This function is deprecated. In new code, use the
5529 "inspect-list-applications2" call instead.
5530 Deprecated functions will not be removed from the API, but the fact
5532 that they are deprecated indicates that there are problems with correct
5533 use of these functions.
5534 inspect-list-applications2
5536 inspect-list-applications2 root
5537 Return the list of applications installed in the operating system.
5539 Note: This call works differently from other parts of the inspection
5541 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5542 then mount up the disks, before calling this. Listing applications is
5543 a significantly more difficult operation which requires access to the
5544 full filesystem. Also note that unlike the other "inspect-get-*" calls
5545 which are just returning data cached in the libguestfs handle, this
5546 call actually reads parts of the mounted filesystems during the call.
5547 This returns an empty list if the inspection code was not able to
5549 determine the list of applications.
5550 The application structure contains the following fields:
5552 "app2_name"
5554 The name of the application. For Linux guests, this is the package
5555 name.
5556 "app2_display_name"
5558 The display name of the application, sometimes localized to the
5559 install language of the guest operating system.
5560 If unavailable this is returned as an empty string "". Callers
5562 needing to display something can use "app2_name" instead.
5563 "app2_epoch"
5565 For package managers which use epochs, this contains the epoch of
5566 the package (an integer). If unavailable, this is returned as 0.
5567 "app2_version"
5569 The version string of the application or package. If unavailable
5570 this is returned as an empty string "".
5571 "app2_release"
5573 The release string of the application or package, for package
5574 managers that use this. If unavailable this is returned as an
5575 empty string "".
5576 "app2_arch"
5578 The architecture string of the application or package, for package
5579 managers that use this. If unavailable this is returned as an
5580 empty string "".
5581 "app2_install_path"
5583 The installation path of the application (on operating systems such
5584 as Windows which use installation paths). This path is in the
5585 format used by the guest operating system, it is not a libguestfs
5586 path.
5587 If unavailable this is returned as an empty string "".
5589 "app2_trans_path"
5591 The install path translated into a libguestfs path. If unavailable
5592 this is returned as an empty string "".
5593 "app2_publisher"
5595 The name of the publisher of the application, for package managers
5596 that use this. If unavailable this is returned as an empty string
5597 "".
5598 "app2_url"
5600 The URL (eg. upstream URL) of the application. If unavailable this
5601 is returned as an empty string "".
5602 "app2_source_package"
5604 For packaging systems which support this, the name of the source
5605 package. If unavailable this is returned as an empty string "".
5606 "app2_summary"
5608 A short (usually one line) description of the application or
5609 package. If unavailable this is returned as an empty string "".
5610 "app2_description"
5612 A longer description of the application or package. If unavailable
5613 this is returned as an empty string "".
5614 Please read "INSPECTION" in guestfs(3) for more details.
5616 inspect-os
5618 inspect-os
5619 This function uses other libguestfs functions and certain heuristics to
5621 inspect the disk(s) (usually disks belonging to a virtual machine),
5622 looking for operating systems.
5623 The list returned is empty if no operating systems were found.
5625 If one operating system was found, then this returns a list with a
5627 single element, which is the name of the root filesystem of this
5628 operating system. It is also possible for this function to return a
5629 list containing more than one element, indicating a dual-boot or multi-
5630 boot virtual machine, with each element being the root filesystem of
5631 one of the operating systems.
5632 You can pass the root string(s) returned to other "inspect-get-*"
5634 functions in order to query further information about each operating
5635 system, such as the name and version.
5636 This function uses other libguestfs features such as "mount-ro" and
5638 "umount-all" in order to mount and unmount filesystems and look at the
5639 contents. This should be called with no disks currently mounted. The
5640 function may also use Augeas, so any existing Augeas handle will be
5641 closed.
5642 This function cannot decrypt encrypted disks. The caller must do that
5644 first (supplying the necessary keys) if the disk is encrypted.
5645 Please read "INSPECTION" in guestfs(3) for more details.
5647 See also "list-filesystems".
5649 is-blockdev
5651 is-blockdev-opts
5652 is-blockdev path [followsymlinks:true|false]
5653 This returns "true" if and only if there is a block device with the
5655 given "path" name.
5656 If the optional flag "followsymlinks" is true, then a symlink (or chain
5658 of symlinks) that ends with a block device also causes the function to
5659 return true.
5660 This call only looks at files within the guest filesystem. Libguestfs
5662 partitions and block devices (eg. /dev/sda) cannot be used as the
5663 "path" parameter of this call.
5664 See also "stat".
5666 This command has one or more optional arguments. See "OPTIONAL
5668 ARGUMENTS".
5669 is-chardev
5671 is-chardev-opts
5672 is-chardev path [followsymlinks:true|false]
5673 This returns "true" if and only if there is a character device with the
5675 given "path" name.
5676 If the optional flag "followsymlinks" is true, then a symlink (or chain
5678 of symlinks) that ends with a chardev also causes the function to
5679 return true.
5680 See also "stat".
5682 This command has one or more optional arguments. See "OPTIONAL
5684 ARGUMENTS".
5685 is-config
5687 is-config
5688 This returns true iff this handle is being configured (in the "CONFIG"
5690 state).
5691 For more information on states, see guestfs(3).
5693 is-dir
5695 is-dir-opts
5696 is-dir path [followsymlinks:true|false]
5697 This returns "true" if and only if there is a directory with the given
5699 "path" name. Note that it returns false for other objects like files.
5700 If the optional flag "followsymlinks" is true, then a symlink (or chain
5702 of symlinks) that ends with a directory also causes the function to
5703 return true.
5704 See also "stat".
5706 This command has one or more optional arguments. See "OPTIONAL
5708 ARGUMENTS".
5709 is-fifo
5711 is-fifo-opts
5712 is-fifo path [followsymlinks:true|false]
5713 This returns "true" if and only if there is a FIFO (named pipe) with
5715 the given "path" name.
5716 If the optional flag "followsymlinks" is true, then a symlink (or chain
5718 of symlinks) that ends with a FIFO also causes the function to return
5719 true.
5720 See also "stat".
5722 This command has one or more optional arguments. See "OPTIONAL
5724 ARGUMENTS".
5725 is-file
5727 is-file-opts
5728 is-file path [followsymlinks:true|false]
5729 This returns "true" if and only if there is a regular file with the
5731 given "path" name. Note that it returns false for other objects like
5732 directories.
5733 If the optional flag "followsymlinks" is true, then a symlink (or chain
5735 of symlinks) that ends with a file also causes the function to return
5736 true.
5737 See also "stat".
5739 This command has one or more optional arguments. See "OPTIONAL
5741 ARGUMENTS".
5742 is-lv
5744 is-lv mountable
5745 This command tests whether "mountable" is a logical volume, and returns
5747 true iff this is the case.
5748 is-socket
5750 is-socket-opts
5751 is-socket path [followsymlinks:true|false]
5752 This returns "true" if and only if there is a Unix domain socket with
5754 the given "path" name.
5755 If the optional flag "followsymlinks" is true, then a symlink (or chain
5757 of symlinks) that ends with a socket also causes the function to return
5758 true.
5759 See also "stat".
5761 This command has one or more optional arguments. See "OPTIONAL
5763 ARGUMENTS".
5764 is-symlink
5766 is-symlink path
5767 This returns "true" if and only if there is a symbolic link with the
5769 given "path" name.
5770 See also "stat".
5772 is-whole-device
5774 is-whole-device device
5775 This returns "true" if and only if "device" refers to a whole block
5777 device. That is, not a partition or a logical device.
5778 is-zero
5780 is-zero path
5781 This returns true iff the file exists and the file is empty or it
5783 contains all zero bytes.
5784 is-zero-device
5786 is-zero-device device
5787 This returns true iff the device exists and contains all zero bytes.
5789 Note that for large devices this can take a long time to run.
5791 isoinfo
5793 isoinfo isofile
5794 This is the same as "isoinfo-device" except that it works for an ISO
5796 file located inside some other mounted filesystem. Note that in the
5797 common case where you have added an ISO file as a libguestfs device,
5798 you would not call this. Instead you would call "isoinfo-device".
5799 isoinfo-device
5801 isoinfo-device device
5802 "device" is an ISO device. This returns a struct of information read
5804 from the primary volume descriptor (the ISO equivalent of the
5805 superblock) of the device.
5806 Usually it is more efficient to use the isoinfo(1) command with the -d
5808 option on the host to analyze ISO files, instead of going through
5809 libguestfs.
5810 For information on the primary volume descriptor fields, see
5812 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
5813 journal-close
5815 journal-close
5816 Close the journal handle.
5818 This command depends on the feature "journal". See also "feature-
5820 available".
5821 journal-get
5823 journal-get
5824 Read the current journal entry. This returns all the fields in the
5826 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
5827 field name (a string).
5828 The "attrval" is the field value (a binary blob, often but not always a
5830 string). Please note that "attrval" is a byte array, not a
5831 \0-terminated C string.
5832 The length of data may be truncated to the data threshold (see:
5834 "journal-set-data-threshold", "journal-get-data-threshold").
5835 If you set the data threshold to unlimited (0) then this call can read
5837 a journal entry of any size, ie. it is not limited by the libguestfs
5838 protocol.
5839 This command depends on the feature "journal". See also "feature-
5841 available".
5842 journal-get-data-threshold
5844 journal-get-data-threshold
5845 Get the current data threshold for reading journal entries. This is a
5847 hint to the journal that it may truncate data fields to this size when
5848 reading them (note also that it may not truncate them). If this
5849 returns 0, then the threshold is unlimited.
5850 See also "journal-set-data-threshold".
5852 This command depends on the feature "journal". See also "feature-
5854 available".
5855 journal-get-realtime-usec
5857 journal-get-realtime-usec
5858 Get the realtime (wallclock) timestamp of the current journal entry.
5860 This command depends on the feature "journal". See also "feature-
5862 available".
5863 journal-next
5865 journal-next
5866 Move to the next journal entry. You have to call this at least once
5868 after opening the handle before you are able to read data.
5869 The returned boolean tells you if there are any more journal records to
5871 read. "true" means you can read the next record (eg. using "journal-
5872 get"), and "false" means you have reached the end of the journal.
5873 This command depends on the feature "journal". See also "feature-
5875 available".
5876 journal-open
5878 journal-open directory
5879 Open the systemd journal located in directory. Any previously opened
5881 journal handle is closed.
5882 The contents of the journal can be read using "journal-next" and
5884 "journal-get".
5885 After you have finished using the journal, you should close the handle
5887 by calling "journal-close".
5888 This command depends on the feature "journal". See also "feature-
5890 available".
5891 journal-set-data-threshold
5893 journal-set-data-threshold threshold
5894 Set the data threshold for reading journal entries. This is a hint to
5896 the journal that it may truncate data fields to this size when reading
5897 them (note also that it may not truncate them). If you set this to 0,
5898 then the threshold is unlimited.
5899 See also "journal-get-data-threshold".
5901 This command depends on the feature "journal". See also "feature-
5903 available".
5904 journal-skip
5906 journal-skip skip
5907 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
5909 The number of entries actually skipped is returned (note "rskip ≥ 0").
5911 If this is not the same as the absolute value of the skip parameter
5912 ("|skip|") you passed in then it means you have reached the end or the
5913 start of the journal.
5914 This command depends on the feature "journal". See also "feature-
5916 available".
5917 kill-subprocess
5919 kill-subprocess
5920 This kills the hypervisor.
5922 Do not call this. See: "shutdown" instead.
5924 This function is deprecated. In new code, use the "shutdown" call
5926 instead.
5927 Deprecated functions will not be removed from the API, but the fact
5929 that they are deprecated indicates that there are problems with correct
5930 use of these functions.
5931 launch
5933 run
5934 launch
5935 You should call this after configuring the handle (eg. adding drives)
5937 but before performing any actions.
5938 Do not call "launch" twice on the same handle. Although it will not
5940 give an error (for historical reasons), the precise behaviour when you
5941 do this is not well defined. Handles are very cheap to create, so
5942 create a new one for each launch.
5943 lchown
5945 lchown owner group path
5946 Change the file owner to "owner" and group to "group". This is like
5948 "chown" but if "path" is a symlink then the link itself is changed, not
5949 the target.
5950 Only numeric uid and gid are supported. If you want to use names, you
5952 will need to locate and parse the password file yourself (Augeas
5953 support makes this relatively easy).
5954 ldmtool-create-all
5956 ldmtool-create-all
5957 This function scans all block devices looking for Windows dynamic disk
5959 volumes and partitions, and creates devices for any that were found.
5960 Call "list-ldm-volumes" and "list-ldm-partitions" to return all
5962 devices.
5963 Note that you don't normally need to call this explicitly, since it is
5965 done automatically at "launch" time. However you might want to call
5966 this function if you have hotplugged disks or have just created a
5967 Windows dynamic disk.
5968 This command depends on the feature "ldm". See also "feature-
5970 available".
5971 ldmtool-diskgroup-disks
5973 ldmtool-diskgroup-disks diskgroup
5974 Return the disks in a Windows dynamic disk group. The "diskgroup"
5976 parameter should be the GUID of a disk group, one element from the list
5977 returned by "ldmtool-scan".
5978 This command depends on the feature "ldm". See also "feature-
5980 available".
5981 ldmtool-diskgroup-name
5983 ldmtool-diskgroup-name diskgroup
5984 Return the name of a Windows dynamic disk group. The "diskgroup"
5986 parameter should be the GUID of a disk group, one element from the list
5987 returned by "ldmtool-scan".
5988 This command depends on the feature "ldm". See also "feature-
5990 available".
5991 ldmtool-diskgroup-volumes
5993 ldmtool-diskgroup-volumes diskgroup
5994 Return the volumes in a Windows dynamic disk group. The "diskgroup"
5996 parameter should be the GUID of a disk group, one element from the list
5997 returned by "ldmtool-scan".
5998 This command depends on the feature "ldm". See also "feature-
6000 available".
6001 ldmtool-remove-all
6003 ldmtool-remove-all
6004 This is essentially the opposite of "ldmtool-create-all". It removes
6006 the device mapper mappings for all Windows dynamic disk volumes
6007 This command depends on the feature "ldm". See also "feature-
6009 available".
6010 ldmtool-scan
6012 ldmtool-scan
6013 This function scans for Windows dynamic disks. It returns a list of
6015 identifiers (GUIDs) for all disk groups that were found. These
6016 identifiers can be passed to other "ldmtool-*" functions.
6017 This function scans all block devices. To scan a subset of block
6019 devices, call "ldmtool-scan-devices" instead.
6020 This command depends on the feature "ldm". See also "feature-
6022 available".
6023 ldmtool-scan-devices
6025 ldmtool-scan-devices 'devices ...'
6026 This function scans for Windows dynamic disks. It returns a list of
6028 identifiers (GUIDs) for all disk groups that were found. These
6029 identifiers can be passed to other "ldmtool-*" functions.
6030 The parameter "devices" is a list of block devices which are scanned.
6032 If this list is empty, all block devices are scanned.
6033 This command depends on the feature "ldm". See also "feature-
6035 available".
6036 ldmtool-volume-hint
6038 ldmtool-volume-hint diskgroup volume
6039 Return the hint field of the volume named "volume" in the disk group
6041 with GUID "diskgroup". This may not be defined, in which case the
6042 empty string is returned. The hint field is often, though not always,
6043 the name of a Windows drive, eg. "E:".
6044 This command depends on the feature "ldm". See also "feature-
6046 available".
6047 ldmtool-volume-partitions
6049 ldmtool-volume-partitions diskgroup volume
6050 Return the list of partitions in the volume named "volume" in the disk
6052 group with GUID "diskgroup".
6053 This command depends on the feature "ldm". See also "feature-
6055 available".
6056 ldmtool-volume-type
6058 ldmtool-volume-type diskgroup volume
6059 Return the type of the volume named "volume" in the disk group with
6061 GUID "diskgroup".
6062 Possible volume types that can be returned here include: "simple",
6064 "spanned", "striped", "mirrored", "raid5". Other types may also be
6065 returned.
6066 This command depends on the feature "ldm". See also "feature-
6068 available".
6069 lgetxattr
6071 lgetxattr path name
6072 Get a single extended attribute from file "path" named "name". If
6074 "path" is a symlink, then this call returns an extended attribute from
6075 the symlink.
6076 Normally it is better to get all extended attributes from a file in one
6078 go by calling "getxattrs". However some Linux filesystem
6079 implementations are buggy and do not provide a way to list out
6080 attributes. For these filesystems (notably ntfs-3g) you have to know
6081 the names of the extended attributes you want in advance and call this
6082 function.
6083 Extended attribute values are blobs of binary data. If there is no
6085 extended attribute named "name", this returns an error.
6086 See also: "lgetxattrs", "getxattr", attr(5).
6088 This command depends on the feature "linuxxattrs". See also "feature-
6090 available".
6091 lgetxattrs
6093 lgetxattrs path
6094 This is the same as "getxattrs", but if "path" is a symbolic link, then
6096 it returns the extended attributes of the link itself.
6097 This command depends on the feature "linuxxattrs". See also "feature-
6099 available".
6100 list-9p
6102 list-9p
6103 List all 9p filesystems attached to the guest. A list of mount tags is
6105 returned.
6106 list-devices
6108 list-devices
6109 List all the block devices.
6111 The full block device names are returned, eg. /dev/sda.
6113 See also "list-filesystems".
6115 list-disk-labels
6117 list-disk-labels
6118 If you add drives using the optional "label" parameter of "add-drive-
6120 opts", you can use this call to map between disk labels, and raw block
6121 device and partition names (like /dev/sda and /dev/sda1).
6122 This returns a hashtable, where keys are the disk labels (without the
6124 /dev/disk/guestfs prefix), and the values are the full raw block device
6125 and partition names (eg. /dev/sda and /dev/sda1).
6126 list-dm-devices
6128 list-dm-devices
6129 List all device mapper devices.
6131 The returned list contains /dev/mapper/* devices, eg. ones created by a
6133 previous call to "luks-open".
6134 Device mapper devices which correspond to logical volumes are not
6136 returned in this list. Call "lvs" if you want to list logical volumes.
6137 list-filesystems
6139 list-filesystems
6140 This inspection command looks for filesystems on partitions, block
6142 devices and logical volumes, returning a list of "mountables"
6143 containing filesystems and their type.
6144 The return value is a hash, where the keys are the devices containing
6146 filesystems, and the values are the filesystem types. For example:
6147 "/dev/sda1" => "ntfs"
6149 "/dev/sda2" => "ext2"
6150 "/dev/vg_guest/lv_root" => "ext4"
6151 "/dev/vg_guest/lv_swap" => "swap"
6152 The key is not necessarily a block device. It may also be an opaque
6154 ‘mountable’ string which can be passed to "mount".
6155 The value can have the special value "unknown", meaning the content of
6157 the device is undetermined or empty. "swap" means a Linux swap
6158 partition.
6159 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
6161 might have included "mount" and "umount", and therefore you had to use
6162 this soon after launch and only when nothing else was mounted. This
6163 restriction is removed in libguestfs ≥ 1.38.
6164 Not all of the filesystems returned will be mountable. In particular,
6166 swap partitions are returned in the list. Also this command does not
6167 check that each filesystem found is valid and mountable, and some
6168 filesystems might be mountable but require special options.
6169 Filesystems may not all belong to a single logical operating system
6170 (use "inspect-os" to look for OSes).
6171 list-ldm-partitions
6173 list-ldm-partitions
6174 This function returns all Windows dynamic disk partitions that were
6176 found at launch time. It returns a list of device names.
6177 This command depends on the feature "ldm". See also "feature-
6179 available".
6180 list-ldm-volumes
6182 list-ldm-volumes
6183 This function returns all Windows dynamic disk volumes that were found
6185 at launch time. It returns a list of device names.
6186 This command depends on the feature "ldm". See also "feature-
6188 available".
6189 list-md-devices
6191 list-md-devices
6192 List all Linux md devices.
6194 list-partitions
6196 list-partitions
6197 List all the partitions detected on all block devices.
6199 The full partition device names are returned, eg. /dev/sda1
6201 This does not return logical volumes. For that you will need to call
6203 "lvs".
6204 See also "list-filesystems".
6206 ll
6208 ll directory
6209 List the files in directory (relative to the root directory, there is
6211 no cwd) in the format of "ls -la".
6212 This command is mostly useful for interactive sessions. It is not
6214 intended that you try to parse the output string.
6215 llz
6217 llz directory
6218 List the files in directory in the format of "ls -laZ".
6220 This command is mostly useful for interactive sessions. It is not
6222 intended that you try to parse the output string.
6223 This function is deprecated. In new code, use the "lgetxattrs" call
6225 instead.
6226 Deprecated functions will not be removed from the API, but the fact
6228 that they are deprecated indicates that there are problems with correct
6229 use of these functions.
6230 ln
6232 ln target linkname
6233 This command creates a hard link.
6235 ln-f
6237 ln-f target linkname
6238 This command creates a hard link, removing the link "linkname" if it
6240 exists already.
6241 ln-s
6243 ln-s target linkname
6244 This command creates a symbolic link using the "ln -s" command.
6246 ln-sf
6248 ln-sf target linkname
6249 This command creates a symbolic link using the "ln -sf" command, The -f
6251 option removes the link ("linkname") if it exists already.
6252 lremovexattr
6254 lremovexattr xattr path
6255 This is the same as "removexattr", but if "path" is a symbolic link,
6257 then it removes an extended attribute of the link itself.
6258 This command depends on the feature "linuxxattrs". See also "feature-
6260 available".
6261 ls
6263 ls directory
6264 List the files in directory (relative to the root directory, there is
6266 no cwd). The "." and ".." entries are not returned, but hidden files
6267 are shown.
6268 ls0
6270 ls0 dir (filenames|-)
6271 This specialized command is used to get a listing of the filenames in
6273 the directory "dir". The list of filenames is written to the local
6274 file filenames (on the host).
6275 In the output file, the filenames are separated by "\0" characters.
6277 "." and ".." are not returned. The filenames are not sorted.
6279 Use "-" instead of a filename to read/write from stdin/stdout.
6281 lsetxattr
6283 lsetxattr xattr val vallen path
6284 This is the same as "setxattr", but if "path" is a symbolic link, then
6286 it sets an extended attribute of the link itself.
6287 This command depends on the feature "linuxxattrs". See also "feature-
6289 available".
6290 lstat
6292 lstat path
6293 Returns file information for the given "path".
6295 This is the same as "stat" except that if "path" is a symbolic link,
6297 then the link is stat-ed, not the file it refers to.
6298 This is the same as the lstat(2) system call.
6300 This function is deprecated. In new code, use the "lstatns" call
6302 instead.
6303 Deprecated functions will not be removed from the API, but the fact
6305 that they are deprecated indicates that there are problems with correct
6306 use of these functions.
6307 lstatlist
6309 lstatlist path 'names ...'
6310 This call allows you to perform the "lstat" operation on multiple
6312 files, where all files are in the directory "path". "names" is the
6313 list of files from this directory.
6314 On return you get a list of stat structs, with a one-to-one
6316 correspondence to the "names" list. If any name did not exist or could
6317 not be lstat'd, then the "st_ino" field of that structure is set to
6318 "-1".
6319 This call is intended for programs that want to efficiently list a
6321 directory contents without making many round-trips. See also
6322 "lxattrlist" for a similarly efficient call for getting extended
6323 attributes.
6324 This function is deprecated. In new code, use the "lstatnslist" call
6326 instead.
6327 Deprecated functions will not be removed from the API, but the fact
6329 that they are deprecated indicates that there are problems with correct
6330 use of these functions.
6331 lstatns
6333 lstatns path
6334 Returns file information for the given "path".
6336 This is the same as "statns" except that if "path" is a symbolic link,
6338 then the link is stat-ed, not the file it refers to.
6339 This is the same as the lstat(2) system call.
6341 lstatnslist
6343 lstatnslist path 'names ...'
6344 This call allows you to perform the "lstatns" operation on multiple
6346 files, where all files are in the directory "path". "names" is the
6347 list of files from this directory.
6348 On return you get a list of stat structs, with a one-to-one
6350 correspondence to the "names" list. If any name did not exist or could
6351 not be lstat'd, then the "st_ino" field of that structure is set to
6352 "-1".
6353 This call is intended for programs that want to efficiently list a
6355 directory contents without making many round-trips. See also
6356 "lxattrlist" for a similarly efficient call for getting extended
6357 attributes.
6358 luks-add-key
6360 luks-add-key device keyslot
6361 This command adds a new key on LUKS device "device". "key" is any
6363 existing key, and is used to access the device. "newkey" is the new
6364 key to add. "keyslot" is the key slot that will be replaced.
6365 Note that if "keyslot" already contains a key, then this command will
6367 fail. You have to use "luks-kill-slot" first to remove that key.
6368 This command has one or more key or passphrase parameters. Guestfish
6370 will prompt for these separately.
6371 This command depends on the feature "luks". See also "feature-
6373 available".
6374 luks-close
6376 luks-close device
6377 This closes a LUKS device that was created earlier by "luks-open" or
6379 "luks-open-ro". The "device" parameter must be the name of the LUKS
6380 mapping device (ie. /dev/mapper/mapname) and not the name of the
6381 underlying block device.
6382 This command depends on the feature "luks". See also "feature-
6384 available".
6385 luks-format
6387 luks-format device keyslot
6388 This command erases existing data on "device" and formats the device as
6390 a LUKS encrypted device. "key" is the initial key, which is added to
6391 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
6392 This command has one or more key or passphrase parameters. Guestfish
6394 will prompt for these separately.
6395 This command depends on the feature "luks". See also "feature-
6397 available".
6398 luks-format-cipher
6400 luks-format-cipher device keyslot cipher
6401 This command is the same as "luks-format" but it also allows you to set
6403 the "cipher" used.
6404 This command has one or more key or passphrase parameters. Guestfish
6406 will prompt for these separately.
6407 This command depends on the feature "luks". See also "feature-
6409 available".
6410 luks-kill-slot
6412 luks-kill-slot device keyslot
6413 This command deletes the key in key slot "keyslot" from the encrypted
6415 LUKS device "device". "key" must be one of the other keys.
6416 This command has one or more key or passphrase parameters. Guestfish
6418 will prompt for these separately.
6419 This command depends on the feature "luks". See also "feature-
6421 available".
6422 luks-open
6424 luks-open device mapname
6425 This command opens a block device which has been encrypted according to
6427 the Linux Unified Key Setup (LUKS) standard.
6428 "device" is the encrypted block device or partition.
6430 The caller must supply one of the keys associated with the LUKS block
6432 device, in the "key" parameter.
6433 This creates a new block device called /dev/mapper/mapname. Reads and
6435 writes to this block device are decrypted from and encrypted to the
6436 underlying "device" respectively.
6437 If this block device contains LVM volume groups, then calling "lvm-
6439 scan" with the "activate" parameter "true" will make them visible.
6440 Use "list-dm-devices" to list all device mapper devices.
6442 This command has one or more key or passphrase parameters. Guestfish
6444 will prompt for these separately.
6445 This command depends on the feature "luks". See also "feature-
6447 available".
6448 luks-open-ro
6450 luks-open-ro device mapname
6451 This is the same as "luks-open" except that a read-only mapping is
6453 created.
6454 This command has one or more key or passphrase parameters. Guestfish
6456 will prompt for these separately.
6457 This command depends on the feature "luks". See also "feature-
6459 available".
6460 luks-uuid
6462 luks-uuid device
6463 This returns the UUID of the LUKS device "device".
6465 This command depends on the feature "luks". See also "feature-
6467 available".
6468 lvcreate
6470 lvcreate logvol volgroup mbytes
6471 This creates an LVM logical volume called "logvol" on the volume group
6473 "volgroup", with "size" megabytes.
6474 This command depends on the feature "lvm2". See also "feature-
6476 available".
6477 lvcreate-free
6479 lvcreate-free logvol volgroup percent
6480 Create an LVM logical volume called /dev/volgroup/logvol, using
6482 approximately "percent" % of the free space remaining in the volume
6483 group. Most usefully, when "percent" is 100 this will create the
6484 largest possible LV.
6485 This command depends on the feature "lvm2". See also "feature-
6487 available".
6488 lvm-canonical-lv-name
6490 lvm-canonical-lv-name lvname
6491 This converts alternative naming schemes for LVs that you might find to
6493 the canonical name. For example, /dev/mapper/VG-LV is converted to
6494 /dev/VG/LV.
6495 This command returns an error if the "lvname" parameter does not refer
6497 to a logical volume.
6498 See also "is-lv", "canonical-device-name".
6500 lvm-clear-filter
6502 lvm-clear-filter
6503 This undoes the effect of "lvm-set-filter". LVM will be able to see
6505 every block device.
6506 This command also clears the LVM cache and performs a volume group
6508 scan.
6509 lvm-remove-all
6511 lvm-remove-all
6512 This command removes all LVM logical volumes, volume groups and
6514 physical volumes.
6515 This command depends on the feature "lvm2". See also "feature-
6517 available".
6518 lvm-scan
6520 lvm-scan true|false
6521 This scans all block devices and rebuilds the list of LVM physical
6523 volumes, volume groups and logical volumes.
6524 If the "activate" parameter is "true" then newly found volume groups
6526 and logical volumes are activated, meaning the LV /dev/VG/LV devices
6527 become visible.
6528 When a libguestfs handle is launched it scans for existing devices, so
6530 you do not normally need to use this API. However it is useful when
6531 you have added a new device or deleted an existing device (such as when
6532 the "luks-open" API is used).
6533 lvm-set-filter
6535 lvm-set-filter 'devices ...'
6536 This sets the LVM device filter so that LVM will only be able to "see"
6538 the block devices in the list "devices", and will ignore all other
6539 attached block devices.
6540 Where disk image(s) contain duplicate PVs or VGs, this command is
6542 useful to get LVM to ignore the duplicates, otherwise LVM can get
6543 confused. Note also there are two types of duplication possible:
6544 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
6545 cloned but just happen to have the same name. In normal operation you
6546 cannot create this situation, but you can do it outside LVM, eg. by
6547 cloning disk images or by bit twiddling inside the LVM metadata.
6548 This command also clears the LVM cache and performs a volume group
6550 scan.
6551 You can filter whole block devices or individual partitions.
6553 You cannot use this if any VG is currently in use (eg. contains a
6555 mounted filesystem), even if you are not filtering out that VG.
6556 This command depends on the feature "lvm2". See also "feature-
6558 available".
6559 lvremove
6561 lvremove device
6562 Remove an LVM logical volume "device", where "device" is the path to
6564 the LV, such as /dev/VG/LV.
6565 You can also remove all LVs in a volume group by specifying the VG
6567 name, /dev/VG.
6568 This command depends on the feature "lvm2". See also "feature-
6570 available".
6571 lvrename
6573 lvrename logvol newlogvol
6574 Rename a logical volume "logvol" with the new name "newlogvol".
6576 lvresize
6578 lvresize device mbytes
6579 This resizes (expands or shrinks) an existing LVM logical volume to
6581 "mbytes". When reducing, data in the reduced part is lost.
6582 This command depends on the feature "lvm2". See also "feature-
6584 available".
6585 lvresize-free
6587 lvresize-free lv percent
6588 This expands an existing logical volume "lv" so that it fills "pc" % of
6590 the remaining free space in the volume group. Commonly you would call
6591 this with pc = 100 which expands the logical volume as much as
6592 possible, using all remaining free space in the volume group.
6593 This command depends on the feature "lvm2". See also "feature-
6595 available".
6596 lvs
6598 lvs
6599 List all the logical volumes detected. This is the equivalent of the
6601 lvs(8) command.
6602 This returns a list of the logical volume device names (eg.
6604 /dev/VolGroup00/LogVol00).
6605 See also "lvs-full", "list-filesystems".
6607 This command depends on the feature "lvm2". See also "feature-
6609 available".
6610 lvs-full
6612 lvs-full
6613 List all the logical volumes detected. This is the equivalent of the
6615 lvs(8) command. The "full" version includes all fields.
6616 This command depends on the feature "lvm2". See also "feature-
6618 available".
6619 lvuuid
6621 lvuuid device
6622 This command returns the UUID of the LVM LV "device".
6624 lxattrlist
6626 lxattrlist path 'names ...'
6627 This call allows you to get the extended attributes of multiple files,
6629 where all files are in the directory "path". "names" is the list of
6630 files from this directory.
6631 On return you get a flat list of xattr structs which must be
6633 interpreted sequentially. The first xattr struct always has a zero-
6634 length "attrname". "attrval" in this struct is zero-length to indicate
6635 there was an error doing "lgetxattr" for this file, or is a C string
6636 which is a decimal number (the number of following attributes for this
6637 file, which could be "0"). Then after the first xattr struct are the
6638 zero or more attributes for the first named file. This repeats for the
6639 second and subsequent files.
6640 This call is intended for programs that want to efficiently list a
6642 directory contents without making many round-trips. See also
6643 "lstatlist" for a similarly efficient call for getting standard stats.
6644 This command depends on the feature "linuxxattrs". See also "feature-
6646 available".
6647 max-disks
6649 max-disks
6650 Return the maximum number of disks that may be added to a handle (eg.
6652 by "add-drive-opts" and similar calls).
6653 This function was added in libguestfs 1.19.7. In previous versions of
6655 libguestfs the limit was 25.
6656 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
6658 on this topic.
6659 md-create
6661 md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
6662 Create a Linux md (RAID) device named "name" on the devices in the list
6664 "devices".
6665 The optional parameters are:
6667 "missingbitmap"
6669 A bitmap of missing devices. If a bit is set it means that a
6670 missing device is added to the array. The least significant bit
6671 corresponds to the first device in the array.
6672 As examples:
6674 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
6676 resulting array would be "[<missing>, "/dev/sda"]".
6677 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
6679 resulting array would be "["/dev/sda", <missing>]".
6680 This defaults to 0 (no missing devices).
6682 The length of "devices" + the number of bits set in "missingbitmap"
6684 must equal "nrdevices" + "spare".
6685 "nrdevices"
6687 The number of active RAID devices.
6688 If not set, this defaults to the length of "devices" plus the
6690 number of bits set in "missingbitmap".
6691 "spare"
6693 The number of spare devices.
6694 If not set, this defaults to 0.
6696 "chunk"
6698 The chunk size in bytes.
6699 "level"
6701 The RAID level, which can be one of: "linear", "raid0", 0,
6702 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
6703 "raid10", 10. Some of these are synonymous, and more levels may be
6704 added in future.
6705 If not set, this defaults to "raid1".
6707 This command has one or more optional arguments. See "OPTIONAL
6709 ARGUMENTS".
6710 This command depends on the feature "mdadm". See also "feature-
6712 available".
6713 md-detail
6715 md-detail md
6716 This command exposes the output of "mdadm -DY <md>". The following
6718 fields are usually present in the returned hash. Other fields may also
6719 be present.
6720 "level"
6722 The raid level of the MD device.
6723 "devices"
6725 The number of underlying devices in the MD device.
6726 "metadata"
6728 The metadata version used.
6729 "uuid"
6731 The UUID of the MD device.
6732 "name"
6734 The name of the MD device.
6735 This command depends on the feature "mdadm". See also "feature-
6737 available".
6738 md-stat
6740 md-stat md
6741 This call returns a list of the underlying devices which make up the
6743 single software RAID array device "md".
6744 To get a list of software RAID devices, call "list-md-devices".
6746 Each structure returned corresponds to one device along with additional
6748 status information:
6749 "mdstat_device"
6751 The name of the underlying device.
6752 "mdstat_index"
6754 The index of this device within the array.
6755 "mdstat_flags"
6757 Flags associated with this device. This is a string containing (in
6758 no specific order) zero or more of the following flags:
6759 "W" write-mostly
6761 "F" device is faulty
6763 "S" device is a RAID spare
6765 "R" replacement
6767 This command depends on the feature "mdadm". See also "feature-
6769 available".
6770 md-stop
6772 md-stop md
6773 This command deactivates the MD array named "md". The device is
6775 stopped, but it is not destroyed or zeroed.
6776 This command depends on the feature "mdadm". See also "feature-
6778 available".
6779 mkdir
6781 mkdir path
6782 Create a directory named "path".
6784 mkdir-mode
6786 mkdir-mode path mode
6787 This command creates a directory, setting the initial permissions of
6789 the directory to "mode".
6790 For common Linux filesystems, the actual mode which is set will be
6792 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
6793 the mode in other ways.
6794 See also "mkdir", "umask"
6796 mkdir-p
6798 mkdir-p path
6799 Create a directory named "path", creating any parent directories as
6801 necessary. This is like the "mkdir -p" shell command.
6802 mkdtemp
6804 mkdtemp tmpl
6805 This command creates a temporary directory. The "tmpl" parameter
6807 should be a full pathname for the temporary directory name with the
6808 final six characters being "XXXXXX".
6809 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
6811 one being suitable for Windows filesystems.
6812 The name of the temporary directory that was created is returned.
6814 The temporary directory is created with mode 0700 and is owned by root.
6816 The caller is responsible for deleting the temporary directory and its
6818 contents after use.
6819 See also: mkdtemp(3)
6821 mke2fs
6823 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]
6824 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
6826 "device".
6827 The optional "blockscount" is the size of the filesystem in blocks. If
6829 omitted it defaults to the size of "device". Note if the filesystem is
6830 too small to contain a journal, "mke2fs" will silently create an ext2
6831 filesystem instead.
6832 This command has one or more optional arguments. See "OPTIONAL
6834 ARGUMENTS".
6835 mke2fs-J
6837 mke2fs-J fstype blocksize device journal
6838 This creates an ext2/3/4 filesystem on "device" with an external
6840 journal on "journal". It is equivalent to the command:
6841 mke2fs -t fstype -b blocksize -J device=<journal> <device>
6843 See also "mke2journal".
6845 This function is deprecated. In new code, use the "mke2fs" call
6847 instead.
6848 Deprecated functions will not be removed from the API, but the fact
6850 that they are deprecated indicates that there are problems with correct
6851 use of these functions.
6852 mke2fs-JL
6854 mke2fs-JL fstype blocksize device label
6855 This creates an ext2/3/4 filesystem on "device" with an external
6857 journal on the journal labeled "label".
6858 See also "mke2journal-L".
6860 This function is deprecated. In new code, use the "mke2fs" call
6862 instead.
6863 Deprecated functions will not be removed from the API, but the fact
6865 that they are deprecated indicates that there are problems with correct
6866 use of these functions.
6867 mke2fs-JU
6869 mke2fs-JU fstype blocksize device uuid
6870 This creates an ext2/3/4 filesystem on "device" with an external
6872 journal on the journal with UUID "uuid".
6873 See also "mke2journal-U".
6875 This function is deprecated. In new code, use the "mke2fs" call
6877 instead.
6878 Deprecated functions will not be removed from the API, but the fact
6880 that they are deprecated indicates that there are problems with correct
6881 use of these functions.
6882 This command depends on the feature "linuxfsuuid". See also "feature-
6884 available".
6885 mke2journal
6887 mke2journal blocksize device
6888 This creates an ext2 external journal on "device". It is equivalent to
6890 the command:
6891 mke2fs -O journal_dev -b blocksize device
6893 This function is deprecated. In new code, use the "mke2fs" call
6895 instead.
6896 Deprecated functions will not be removed from the API, but the fact
6898 that they are deprecated indicates that there are problems with correct
6899 use of these functions.
6900 mke2journal-L
6902 mke2journal-L blocksize label device
6903 This creates an ext2 external journal on "device" with label "label".
6905 This function is deprecated. In new code, use the "mke2fs" call
6907 instead.
6908 Deprecated functions will not be removed from the API, but the fact
6910 that they are deprecated indicates that there are problems with correct
6911 use of these functions.
6912 mke2journal-U
6914 mke2journal-U blocksize uuid device
6915 This creates an ext2 external journal on "device" with UUID "uuid".
6917 This function is deprecated. In new code, use the "mke2fs" call
6919 instead.
6920 Deprecated functions will not be removed from the API, but the fact
6922 that they are deprecated indicates that there are problems with correct
6923 use of these functions.
6924 This command depends on the feature "linuxfsuuid". See also "feature-
6926 available".
6927 mkfifo
6929 mkfifo mode path
6930 This call creates a FIFO (named pipe) called "path" with mode "mode".
6932 It is just a convenient wrapper around "mknod".
6933 Unlike with "mknod", "mode" must contain only permissions bits.
6935 The mode actually set is affected by the umask.
6937 This command depends on the feature "mknod". See also "feature-
6939 available".
6940 mkfs
6942 mkfs-opts
6943 mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N] [label:..]
6944 This function creates a filesystem on "device". The filesystem type is
6946 "fstype", for example "ext3".
6947 The optional arguments are:
6949 "blocksize"
6951 The filesystem block size. Supported block sizes depend on the
6952 filesystem type, but typically they are 1024, 2048 or 4096 for
6953 Linux ext2/3 filesystems.
6954 For VFAT and NTFS the "blocksize" parameter is treated as the
6956 requested cluster size.
6957 For UFS block sizes, please see mkfs.ufs(8).
6959 "features"
6961 This passes the -O parameter to the external mkfs program.
6962 For certain filesystem types, this allows extra filesystem features
6964 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
6965 You cannot use this optional parameter with the "gfs" or "gfs2"
6967 filesystem type.
6968 "inode"
6970 This passes the -I parameter to the external mke2fs(8) program
6971 which sets the inode size (only for ext2/3/4 filesystems at
6972 present).
6973 "sectorsize"
6975 This passes the -S parameter to external mkfs.ufs(8) program, which
6976 sets sector size for ufs filesystem.
6977 This command has one or more optional arguments. See "OPTIONAL
6979 ARGUMENTS".
6980 mkfs-b
6982 mkfs-b fstype blocksize device
6983 This call is similar to "mkfs", but it allows you to control the block
6985 size of the resulting filesystem. Supported block sizes depend on the
6986 filesystem type, but typically they are 1024, 2048 or 4096 only.
6987 For VFAT and NTFS the "blocksize" parameter is treated as the requested
6989 cluster size.
6990 This function is deprecated. In new code, use the "mkfs" call instead.
6992 Deprecated functions will not be removed from the API, but the fact
6994 that they are deprecated indicates that there are problems with correct
6995 use of these functions.
6996 mkfs-btrfs
6998 mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]
6999 Create a btrfs filesystem, allowing all configurables to be set. For
7001 more information on the optional arguments, see mkfs.btrfs(8).
7002 Since btrfs filesystems can span multiple devices, this takes a non-
7004 empty list of devices.
7005 To create general filesystems, use "mkfs".
7007 This command has one or more optional arguments. See "OPTIONAL
7009 ARGUMENTS".
7010 This command depends on the feature "btrfs". See also "feature-
7012 available".
7013 mklost-and-found
7015 mklost-and-found mountpoint
7016 Make the "lost+found" directory, normally in the root directory of an
7018 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
7019 to create the "lost+found" directory.
7020 mkmountpoint
7022 mkmountpoint exemptpath
7023 "mkmountpoint" and "rmmountpoint" are specialized calls that can be
7025 used to create extra mountpoints before mounting the first filesystem.
7026 These calls are only necessary in some very limited circumstances,
7028 mainly the case where you want to mount a mix of unrelated and/or read-
7029 only filesystems together.
7030 For example, live CDs often contain a "Russian doll" nest of
7032 filesystems, an ISO outer layer, with a squashfs image inside, with an
7033 ext2/3 image inside that. You can unpack this as follows in guestfish:
7034 add-ro Fedora-11-i686-Live.iso
7036 run
7037 mkmountpoint /cd
7038 mkmountpoint /sqsh
7039 mkmountpoint /ext3fs
7040 mount /dev/sda /cd
7041 mount-loop /cd/LiveOS/squashfs.img /sqsh
7042 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
7043 The inner filesystem is now unpacked under the /ext3fs mountpoint.
7045 "mkmountpoint" is not compatible with "umount-all". You may get
7047 unexpected errors if you try to mix these calls. It is safest to
7048 manually unmount filesystems and remove mountpoints after use.
7049 "umount-all" unmounts filesystems by sorting the paths longest first,
7051 so for this to work for manual mountpoints, you must ensure that the
7052 innermost mountpoints have the longest pathnames, as in the example
7053 code above.
7054 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
7056 Autosync [see "set-autosync", this is set by default on handles] can
7058 cause "umount-all" to be called when the handle is closed which can
7059 also trigger these issues.
7060 mknod
7062 mknod mode devmajor devminor path
7063 This call creates block or character special devices, or named pipes
7065 (FIFOs).
7066 The "mode" parameter should be the mode, using the standard constants.
7068 "devmajor" and "devminor" are the device major and minor numbers, only
7069 used when creating block and character special devices.
7070 Note that, just like mknod(2), the mode must be bitwise OR'd with
7072 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
7073 a regular file). These constants are available in the standard Linux
7074 header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
7075 wrappers around this command which bitwise OR in the appropriate
7076 constant for you.
7077 The mode actually set is affected by the umask.
7079 This command depends on the feature "mknod". See also "feature-
7081 available".
7082 mknod-b
7084 mknod-b mode devmajor devminor path
7085 This call creates a block device node called "path" with mode "mode"
7087 and device major/minor "devmajor" and "devminor". It is just a
7088 convenient wrapper around "mknod".
7089 Unlike with "mknod", "mode" must contain only permissions bits.
7091 The mode actually set is affected by the umask.
7093 This command depends on the feature "mknod". See also "feature-
7095 available".
7096 mknod-c
7098 mknod-c mode devmajor devminor path
7099 This call creates a char device node called "path" with mode "mode" and
7101 device major/minor "devmajor" and "devminor". It is just a convenient
7102 wrapper around "mknod".
7103 Unlike with "mknod", "mode" must contain only permissions bits.
7105 The mode actually set is affected by the umask.
7107 This command depends on the feature "mknod". See also "feature-
7109 available".
7110 mksquashfs
7112 mksquashfs path (filename|-) [compress:..] [excludes:..]
7113 Create a squashfs filesystem for the specified "path".
7115 The optional "compress" flag controls compression. If not given, then
7117 the output compressed using "gzip". Otherwise one of the following
7118 strings may be given to select the compression type of the squashfs:
7119 "gzip", "lzma", "lzo", "lz4", "xz".
7120 The other optional arguments are:
7122 "excludes"
7124 A list of wildcards. Files are excluded if they match any of the
7125 wildcards.
7126 Please note that this API may fail when used to compress directories
7128 with large files, such as the resulting squashfs will be over 3GB big.
7129 Use "-" instead of a filename to read/write from stdin/stdout.
7131 This command has one or more optional arguments. See "OPTIONAL
7133 ARGUMENTS".
7134 This command depends on the feature "squashfs". See also "feature-
7136 available".
7137 mkswap
7139 mkswap-opts
7140 mkswap device [label:..] [uuid:..]
7141 Create a Linux swap partition on "device".
7143 The option arguments "label" and "uuid" allow you to set the label
7145 and/or UUID of the new swap partition.
7146 This command has one or more optional arguments. See "OPTIONAL
7148 ARGUMENTS".
7149 mkswap-L
7151 mkswap-L label device
7152 Create a swap partition on "device" with label "label".
7154 Note that you cannot attach a swap label to a block device (eg.
7156 /dev/sda), just to a partition. This appears to be a limitation of the
7157 kernel or swap tools.
7158 This function is deprecated. In new code, use the "mkswap" call
7160 instead.
7161 Deprecated functions will not be removed from the API, but the fact
7163 that they are deprecated indicates that there are problems with correct
7164 use of these functions.
7165 mkswap-U
7167 mkswap-U uuid device
7168 Create a swap partition on "device" with UUID "uuid".
7170 This function is deprecated. In new code, use the "mkswap" call
7172 instead.
7173 Deprecated functions will not be removed from the API, but the fact
7175 that they are deprecated indicates that there are problems with correct
7176 use of these functions.
7177 This command depends on the feature "linuxfsuuid". See also "feature-
7179 available".
7180 mkswap-file
7182 mkswap-file path
7183 Create a swap file.
7185 This command just writes a swap file signature to an existing file. To
7187 create the file itself, use something like "fallocate".
7188 mktemp
7190 mktemp tmpl [suffix:..]
7191 This command creates a temporary file. The "tmpl" parameter should be
7193 a full pathname for the temporary directory name with the final six
7194 characters being "XXXXXX".
7195 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
7197 one being suitable for Windows filesystems.
7198 The name of the temporary file that was created is returned.
7200 The temporary file is created with mode 0600 and is owned by root.
7202 The caller is responsible for deleting the temporary file after use.
7204 If the optional "suffix" parameter is given, then the suffix (eg.
7206 ".txt") is appended to the temporary name.
7207 See also: "mkdtemp".
7209 This command has one or more optional arguments. See "OPTIONAL
7211 ARGUMENTS".
7212 modprobe
7214 modprobe modulename
7215 This loads a kernel module in the appliance.
7217 This command depends on the feature "linuxmodules". See also
7219 "feature-available".
7220 mount
7222 mount mountable mountpoint
7223 Mount a guest disk at a position in the filesystem. Block devices are
7225 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
7226 If those block devices contain partitions, they will have the usual
7227 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
7228 ‘mountable’ strings returned by "list-filesystems" or "inspect-get-
7229 mountpoints".
7230 The rules are the same as for mount(2): A filesystem must first be
7232 mounted on / before others can be mounted. Other filesystems can only
7233 be mounted on directories which already exist.
7234 The mounted filesystem is writable, if we have sufficient permissions
7236 on the underlying device.
7237 Before libguestfs 1.13.16, this call implicitly added the options
7239 "sync" and "noatime". The "sync" option greatly slowed writes and
7240 caused many problems for users. If your program might need to work
7241 with older versions of libguestfs, use "mount-options" instead (using
7242 an empty string for the first parameter if you don't want any options).
7243 mount-9p
7245 mount-9p mounttag mountpoint [options:..]
7246 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
7248 "mountpoint".
7249 If required, "trans=virtio" will be automatically added to the options.
7251 Any other options required can be passed in the optional "options"
7252 parameter.
7253 This command has one or more optional arguments. See "OPTIONAL
7255 ARGUMENTS".
7256 mount-local
7258 mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
7259 This call exports the libguestfs-accessible filesystem to a local
7261 mountpoint (directory) called "localmountpoint". Ordinary reads and
7262 writes to files and directories under "localmountpoint" are redirected
7263 through libguestfs.
7264 If the optional "readonly" flag is set to true, then writes to the
7266 filesystem return error "EROFS".
7267 "options" is a comma-separated list of mount options. See
7269 guestmount(1) for some useful options.
7270 "cachetimeout" sets the timeout (in seconds) for cached directory
7272 entries. The default is 60 seconds. See guestmount(1) for further
7273 information.
7274 If "debugcalls" is set to true, then additional debugging information
7276 is generated for every FUSE call.
7277 When "mount-local" returns, the filesystem is ready, but is not
7279 processing requests (access to it will block). You have to call
7280 "mount-local-run" to run the main loop.
7281 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7283 This command has one or more optional arguments. See "OPTIONAL
7285 ARGUMENTS".
7286 mount-local-run
7288 mount-local-run
7289 Run the main loop which translates kernel calls to libguestfs calls.
7291 This should only be called after "mount-local" returns successfully.
7293 The call will not return until the filesystem is unmounted.
7294 Note you must not make concurrent libguestfs calls on the same handle
7296 from another thread.
7297 You may call this from a different thread than the one which called
7299 "mount-local", subject to the usual rules for threads and libguestfs
7300 (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
7301 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7303 mount-loop
7305 mount-loop file mountpoint
7306 This command lets you mount file (a filesystem image in a file) on a
7308 mount point. It is entirely equivalent to the command "mount -o loop
7309 file mountpoint".
7310 mount-options
7312 mount-options options mountable mountpoint
7313 This is the same as the "mount" command, but it allows you to set the
7315 mount options as for the mount(8) -o flag.
7316 If the "options" parameter is an empty string, then no options are
7318 passed (all options default to whatever the filesystem uses).
7319 mount-ro
7321 mount-ro mountable mountpoint
7322 This is the same as the "mount" command, but it mounts the filesystem
7324 with the read-only (-o ro) flag.
7325 mount-vfs
7327 mount-vfs options vfstype mountable mountpoint
7328 This is the same as the "mount" command, but it allows you to set both
7330 the mount options and the vfstype as for the mount(8) -o and -t flags.
7331 mountable-device
7333 mountable-device mountable
7334 Returns the device name of a mountable. In quite a lot of cases, the
7336 mountable is the device name.
7337 However this doesn't apply for btrfs subvolumes, where the mountable is
7339 a combination of both the device name and the subvolume path (see also
7340 "mountable-subvolume" to extract the subvolume path of the mountable if
7341 any).
7342 mountable-subvolume
7344 mountable-subvolume mountable
7345 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
7347 are a combination of both the device name and the subvolume path (see
7348 also "mountable-device" to extract the device of the mountable).
7349 If the mountable does not represent a btrfs subvolume, then this
7351 function fails and the "errno" is set to "EINVAL".
7352 mountpoints
7354 mountpoints
7355 This call is similar to "mounts". That call returns a list of devices.
7357 This one returns a hash table (map) of device name to directory where
7358 the device is mounted.
7359 mounts
7361 mounts
7362 This returns the list of currently mounted filesystems. It returns the
7364 list of devices (eg. /dev/sda1, /dev/VG/LV).
7365 Some internal mounts are not shown.
7367 See also: "mountpoints"
7369 mv
7371 mv src dest
7372 This moves a file from "src" to "dest" where "dest" is either a
7374 destination filename or destination directory.
7375 See also: "rename".
7377 nr-devices
7379 nr-devices
7380 This returns the number of whole block devices that were added. This
7382 is the same as the number of devices that would be returned if you
7383 called "list-devices".
7384 To find out the maximum number of devices that could be added, call
7386 "max-disks".
7387 ntfs-3g-probe
7389 ntfs-3g-probe true|false device
7390 This command runs the ntfs-3g.probe(8) command which probes an NTFS
7392 "device" for mountability. (Not all NTFS volumes can be mounted read-
7393 write, and some cannot be mounted at all).
7394 "rw" is a boolean flag. Set it to true if you want to test if the
7396 volume can be mounted read-write. Set it to false if you want to test
7397 if the volume can be mounted read-only.
7398 The return value is an integer which 0 if the operation would succeed,
7400 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
7401 This command depends on the feature "ntfs3g". See also "feature-
7403 available".
7404 ntfscat-i
7406 ntfscat-i device inode (filename|-)
7407 Download a file given its inode from a NTFS filesystem and save it as
7409 filename on the local machine.
7410 This allows to download some otherwise inaccessible files such as the
7412 ones within the $Extend folder.
7413 The filesystem from which to extract the file must be unmounted,
7415 otherwise the call will fail.
7416 Use "-" instead of a filename to read/write from stdin/stdout.
7418 ntfsclone-in
7420 ntfsclone-in (backupfile|-) device
7421 Restore the "backupfile" (from a previous call to "ntfsclone-out") to
7423 "device", overwriting any existing contents of this device.
7424 Use "-" instead of a filename to read/write from stdin/stdout.
7426 This command depends on the feature "ntfs3g". See also "feature-
7428 available".
7429 ntfsclone-out
7431 ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
7432 Stream the NTFS filesystem "device" to the local file "backupfile".
7434 The format used for the backup file is a special format used by the
7435 ntfsclone(8) tool.
7436 If the optional "metadataonly" flag is true, then only the metadata is
7438 saved, losing all the user data (this is useful for diagnosing some
7439 filesystem problems).
7440 The optional "rescue", "ignorefscheck", "preservetimestamps" and
7442 "force" flags have precise meanings detailed in the ntfsclone(8) man
7443 page.
7444 Use "ntfsclone-in" to restore the file back to a libguestfs device.
7446 Use "-" instead of a filename to read/write from stdin/stdout.
7448 This command has one or more optional arguments. See "OPTIONAL
7450 ARGUMENTS".
7451 This command depends on the feature "ntfs3g". See also "feature-
7453 available".
7454 ntfsfix
7456 ntfsfix device [clearbadsectors:true|false]
7457 This command repairs some fundamental NTFS inconsistencies, resets the
7459 NTFS journal file, and schedules an NTFS consistency check for the
7460 first boot into Windows.
7461 This is not an equivalent of Windows "chkdsk". It does not scan the
7463 filesystem for inconsistencies.
7464 The optional "clearbadsectors" flag clears the list of bad sectors.
7466 This is useful after cloning a disk with bad sectors to a new disk.
7467 This command has one or more optional arguments. See "OPTIONAL
7469 ARGUMENTS".
7470 This command depends on the feature "ntfs3g". See also "feature-
7472 available".
7473 ntfsresize
7475 ntfsresize-opts
7476 ntfsresize device [size:N] [force:true|false]
7477 This command resizes an NTFS filesystem, expanding or shrinking it to
7479 the size of the underlying device.
7480 The optional parameters are:
7482 "size"
7484 The new size (in bytes) of the filesystem. If omitted, the
7485 filesystem is resized to fit the container (eg. partition).
7486 "force"
7488 If this option is true, then force the resize of the filesystem
7489 even if the filesystem is marked as requiring a consistency check.
7490 After the resize operation, the filesystem is always marked as
7492 requiring a consistency check (for safety). You have to boot into
7493 Windows to perform this check and clear this condition. If you
7494 don't set the "force" option then it is not possible to call
7495 "ntfsresize" multiple times on a single filesystem without booting
7496 into Windows between each resize.
7497 See also ntfsresize(8).
7499 This command has one or more optional arguments. See "OPTIONAL
7501 ARGUMENTS".
7502 This command depends on the feature "ntfsprogs". See also "feature-
7504 available".
7505 ntfsresize-size
7507 ntfsresize-size device size
7508 This command is the same as "ntfsresize" except that it allows you to
7510 specify the new size (in bytes) explicitly.
7511 This function is deprecated. In new code, use the "ntfsresize" call
7513 instead.
7514 Deprecated functions will not be removed from the API, but the fact
7516 that they are deprecated indicates that there are problems with correct
7517 use of these functions.
7518 This command depends on the feature "ntfsprogs". See also "feature-
7520 available".
7521 parse-environment
7523 parse-environment
7524 Parse the program’s environment and set flags in the handle
7526 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
7527 flag is set in the handle.
7528 Most programs do not need to call this. It is done implicitly when you
7530 call "create".
7531 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
7533 variables that can affect libguestfs handles. See also
7534 "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
7535 parse-environment-list
7537 parse-environment-list 'environment ...'
7538 Parse the list of strings in the argument "environment" and set flags
7540 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
7541 string in the list, then the ‘verbose’ flag is set in the handle.
7542 This is the same as "parse-environment" except that it parses an
7544 explicit list of strings instead of the program's environment.
7545 part-add
7547 part-add device prlogex startsect endsect
7548 This command adds a partition to "device". If there is no partition
7550 table on the device, call "part-init" first.
7551 The "prlogex" parameter is the type of partition. Normally you should
7553 pass "p" or "primary" here, but MBR partition tables also support "l"
7554 (or "logical") and "e" (or "extended") partition types.
7555 "startsect" and "endsect" are the start and end of the partition in
7557 sectors. "endsect" may be negative, which means it counts backwards
7558 from the end of the disk ("-1" is the last sector).
7559 Creating a partition which covers the whole disk is not so easy. Use
7561 "part-disk" to do that.
7562 part-del
7564 part-del device partnum
7565 This command deletes the partition numbered "partnum" on "device".
7567 Note that in the case of MBR partitioning, deleting an extended
7569 partition also deletes any logical partitions it contains.
7570 part-disk
7572 part-disk device parttype
7573 This command is simply a combination of "part-init" followed by "part-
7575 add" to create a single primary partition covering the whole disk.
7576 "parttype" is the partition table type, usually "mbr" or "gpt", but
7578 other possible values are described in "part-init".
7579 part-expand-gpt
7581 part-expand-gpt device
7582 Move backup GPT data structures to the end of the disk. This is useful
7584 in case of in-place image expand since disk space after backup GPT
7585 header is not usable. This is equivalent to "sgdisk -e".
7586 See also sgdisk(8).
7588 This command depends on the feature "gdisk". See also "feature-
7590 available".
7591 part-get-bootable
7593 part-get-bootable device partnum
7594 This command returns true if the partition "partnum" on "device" has
7596 the bootable flag set.
7597 See also "part-set-bootable".
7599 part-get-disk-guid
7601 part-get-disk-guid device
7602 Return the disk identifier (GUID) of a GPT-partitioned "device".
7604 Behaviour is undefined for other partition types.
7605 This command depends on the feature "gdisk". See also "feature-
7607 available".
7608 part-get-gpt-attributes
7610 part-get-gpt-attributes device partnum
7611 Return the attribute flags of numbered GPT partition "partnum". An
7613 error is returned for MBR partitions.
7614 This command depends on the feature "gdisk". See also "feature-
7616 available".
7617 part-get-gpt-guid
7619 part-get-gpt-guid device partnum
7620 Return the GUID of numbered GPT partition "partnum".
7622 This command depends on the feature "gdisk". See also "feature-
7624 available".
7625 part-get-gpt-type
7627 part-get-gpt-type device partnum
7628 Return the type GUID of numbered GPT partition "partnum". For MBR
7630 partitions, return an appropriate GUID corresponding to the MBR type.
7631 Behaviour is undefined for other partition types.
7632 This command depends on the feature "gdisk". See also "feature-
7634 available".
7635 part-get-mbr-id
7637 part-get-mbr-id device partnum
7638 Returns the MBR type byte (also known as the ID byte) from the numbered
7640 partition "partnum".
7641 Note that only MBR (old DOS-style) partitions have type bytes. You
7643 will get undefined results for other partition table types (see "part-
7644 get-parttype").
7645 part-get-mbr-part-type
7647 part-get-mbr-part-type device partnum
7648 This returns the partition type of an MBR partition numbered "partnum"
7650 on device "device".
7651 It returns "primary", "logical", or "extended".
7653 part-get-name
7655 part-get-name device partnum
7656 This gets the partition name on partition numbered "partnum" on device
7658 "device". Note that partitions are numbered from 1.
7659 The partition name can only be read on certain types of partition
7661 table. This works on "gpt" but not on "mbr" partitions.
7662 part-get-parttype
7664 part-get-parttype device
7665 This command examines the partition table on "device" and returns the
7667 partition table type (format) being used.
7668 Common return values include: "msdos" (a DOS/Windows style MBR
7670 partition table), "gpt" (a GPT/EFI-style partition table). Other
7671 values are possible, although unusual. See "part-init" for a full
7672 list.
7673 part-init
7675 part-init device parttype
7676 This creates an empty partition table on "device" of one of the
7678 partition types listed below. Usually "parttype" should be either
7679 "msdos" or "gpt" (for large disks).
7680 Initially there are no partitions. Following this, you should call
7682 "part-add" for each partition required.
7683 Possible values for "parttype" are:
7685 "efi"
7687 "gpt"
7688 Intel EFI / GPT partition table.
7689 This is recommended for >= 2 TB partitions that will be accessed
7691 from Linux and Intel-based Mac OS X. It also has limited backwards
7692 compatibility with the "mbr" format.
7693 "mbr"
7695 "msdos"
7696 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
7697 and Windows. This partition type will only work for device sizes
7698 up to 2 TB. For large disks we recommend using "gpt".
7699 Other partition table types that may work but are not supported
7701 include:
7702 "aix"
7704 AIX disk labels.
7705 "amiga"
7707 "rdb"
7708 Amiga "Rigid Disk Block" format.
7709 "bsd"
7711 BSD disk labels.
7712 "dasd"
7714 DASD, used on IBM mainframes.
7715 "dvh"
7717 MIPS/SGI volumes.
7718 "mac"
7720 Old Mac partition format. Modern Macs use "gpt".
7721 "pc98"
7723 NEC PC-98 format, common in Japan apparently.
7724 "sun"
7726 Sun disk labels.
7727 part-list
7729 part-list device
7730 This command parses the partition table on "device" and returns the
7732 list of partitions found.
7733 The fields in the returned structure are:
7735 "part_num"
7737 Partition number, counting from 1.
7738 "part_start"
7740 Start of the partition in bytes. To get sectors you have to divide
7741 by the device’s sector size, see "blockdev-getss".
7742 "part_end"
7744 End of the partition in bytes.
7745 "part_size"
7747 Size of the partition in bytes.
7748 part-resize
7750 part-resize device partnum endsect
7751 This command resizes the partition numbered "partnum" on "device" by
7753 moving the end position.
7754 Note that this does not modify any filesystem present in the partition.
7756 If you wish to do this, you will need to use filesystem resizing
7757 commands like "resize2fs".
7758 When growing a partition you will want to grow the filesystem
7760 afterwards, but when shrinking, you need to shrink the filesystem
7761 before the partition.
7762 part-set-bootable
7764 part-set-bootable device partnum true|false
7765 This sets the bootable flag on partition numbered "partnum" on device
7767 "device". Note that partitions are numbered from 1.
7768 The bootable flag is used by some operating systems (notably Windows)
7770 to determine which partition to boot from. It is by no means
7771 universally recognized.
7772 part-set-disk-guid
7774 part-set-disk-guid device guid
7775 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
7777 Return an error if the partition table of "device" isn't GPT, or if
7778 "guid" is not a valid GUID.
7779 This command depends on the feature "gdisk". See also "feature-
7781 available".
7782 part-set-disk-guid-random
7784 part-set-disk-guid-random device
7785 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
7787 randomly generated value. Return an error if the partition table of
7788 "device" isn't GPT.
7789 This command depends on the feature "gdisk". See also "feature-
7791 available".
7792 part-set-gpt-attributes
7794 part-set-gpt-attributes device partnum attributes
7795 Set the attribute flags of numbered GPT partition "partnum" to
7797 "attributes". Return an error if the partition table of "device" isn't
7798 GPT.
7799 See
7801 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
7802 for a useful list of partition attributes.
7803 This command depends on the feature "gdisk". See also "feature-
7805 available".
7806 part-set-gpt-guid
7808 part-set-gpt-guid device partnum guid
7809 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
7811 error if the partition table of "device" isn't GPT, or if "guid" is not
7812 a valid GUID.
7813 This command depends on the feature "gdisk". See also "feature-
7815 available".
7816 part-set-gpt-type
7818 part-set-gpt-type device partnum guid
7819 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
7821 an error if the partition table of "device" isn't GPT, or if "guid" is
7822 not a valid GUID.
7823 See
7825 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
7826 for a useful list of type GUIDs.
7827 This command depends on the feature "gdisk". See also "feature-
7829 available".
7830 part-set-mbr-id
7832 part-set-mbr-id device partnum idbyte
7833 Sets the MBR type byte (also known as the ID byte) of the numbered
7835 partition "partnum" to "idbyte". Note that the type bytes quoted in
7836 most documentation are in fact hexadecimal numbers, but usually
7837 documented without any leading "0x" which might be confusing.
7838 Note that only MBR (old DOS-style) partitions have type bytes. You
7840 will get undefined results for other partition table types (see "part-
7841 get-parttype").
7842 part-set-name
7844 part-set-name device partnum name
7845 This sets the partition name on partition numbered "partnum" on device
7847 "device". Note that partitions are numbered from 1.
7848 The partition name can only be set on certain types of partition table.
7850 This works on "gpt" but not on "mbr" partitions.
7851 part-to-dev
7853 part-to-dev partition
7854 This function takes a partition name (eg. "/dev/sdb1") and removes the
7856 partition number, returning the device name (eg. "/dev/sdb").
7857 The named partition must exist, for example as a string returned from
7859 "list-partitions".
7860 See also "part-to-partnum", "device-index".
7862 part-to-partnum
7864 part-to-partnum partition
7865 This function takes a partition name (eg. "/dev/sdb1") and returns the
7867 partition number (eg. 1).
7868 The named partition must exist, for example as a string returned from
7870 "list-partitions".
7871 See also "part-to-dev".
7873 ping-daemon
7875 ping-daemon
7876 This is a test probe into the guestfs daemon running inside the
7878 libguestfs appliance. Calling this function checks that the daemon
7879 responds to the ping message, without affecting the daemon or attached
7880 block device(s) in any other way.
7881 pread
7883 pread path count offset
7884 This command lets you read part of a file. It reads "count" bytes of
7886 the file, starting at "offset", from file "path".
7887 This may read fewer bytes than requested. For further details see the
7889 pread(2) system call.
7890 See also "pwrite", "pread-device".
7892 Because of the message protocol, there is a transfer limit of somewhere
7894 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7895 pread-device
7897 pread-device device count offset
7898 This command lets you read part of a block device. It reads "count"
7900 bytes of "device", starting at "offset".
7901 This may read fewer bytes than requested. For further details see the
7903 pread(2) system call.
7904 See also "pread".
7906 Because of the message protocol, there is a transfer limit of somewhere
7908 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7909 pvchange-uuid
7911 pvchange-uuid device
7912 Generate a new random UUID for the physical volume "device".
7914 This command depends on the feature "lvm2". See also "feature-
7916 available".
7917 pvchange-uuid-all
7919 pvchange-uuid-all
7920 Generate new random UUIDs for all physical volumes.
7922 This command depends on the feature "lvm2". See also "feature-
7924 available".
7925 pvcreate
7927 pvcreate device
7928 This creates an LVM physical volume on the named "device", where
7930 "device" should usually be a partition name such as /dev/sda1.
7931 This command depends on the feature "lvm2". See also "feature-
7933 available".
7934 pvremove
7936 pvremove device
7937 This wipes a physical volume "device" so that LVM will no longer
7939 recognise it.
7940 The implementation uses the pvremove(8) command which refuses to wipe
7942 physical volumes that contain any volume groups, so you have to remove
7943 those first.
7944 This command depends on the feature "lvm2". See also "feature-
7946 available".
7947 pvresize
7949 pvresize device
7950 This resizes (expands or shrinks) an existing LVM physical volume to
7952 match the new size of the underlying device.
7953 This command depends on the feature "lvm2". See also "feature-
7955 available".
7956 pvresize-size
7958 pvresize-size device size
7959 This command is the same as "pvresize" except that it allows you to
7961 specify the new size (in bytes) explicitly.
7962 This command depends on the feature "lvm2". See also "feature-
7964 available".
7965 pvs
7967 pvs
7968 List all the physical volumes detected. This is the equivalent of the
7970 pvs(8) command.
7971 This returns a list of just the device names that contain PVs (eg.
7973 /dev/sda2).
7974 See also "pvs-full".
7976 This command depends on the feature "lvm2". See also "feature-
7978 available".
7979 pvs-full
7981 pvs-full
7982 List all the physical volumes detected. This is the equivalent of the
7984 pvs(8) command. The "full" version includes all fields.
7985 This command depends on the feature "lvm2". See also "feature-
7987 available".
7988 pvuuid
7990 pvuuid device
7991 This command returns the UUID of the LVM PV "device".
7993 pwrite
7995 pwrite path content offset
7996 This command writes to part of a file. It writes the data buffer
7998 "content" to the file "path" starting at offset "offset".
7999 This command implements the pwrite(2) system call, and like that system
8001 call it may not write the full data requested. The return value is the
8002 number of bytes that were actually written to the file. This could
8003 even be 0, although short writes are unlikely for regular files in
8004 ordinary circumstances.
8005 See also "pread", "pwrite-device".
8007 Because of the message protocol, there is a transfer limit of somewhere
8009 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8010 pwrite-device
8012 pwrite-device device content offset
8013 This command writes to part of a device. It writes the data buffer
8015 "content" to "device" starting at offset "offset".
8016 This command implements the pwrite(2) system call, and like that system
8018 call it may not write the full data requested (although short writes to
8019 disk devices and partitions are probably impossible with standard Linux
8020 kernels).
8021 See also "pwrite".
8023 Because of the message protocol, there is a transfer limit of somewhere
8025 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8026 read-file
8028 read-file path
8029 This calls returns the contents of the file "path" as a buffer.
8031 Unlike "cat", this function can correctly handle files that contain
8033 embedded ASCII NUL characters.
8034 read-lines
8036 read-lines path
8037 Return the contents of the file named "path".
8039 The file contents are returned as a list of lines. Trailing "LF" and
8041 "CRLF" character sequences are not returned.
8042 Note that this function cannot correctly handle binary files
8044 (specifically, files containing "\0" character which is treated as end
8045 of string). For those you need to use the "read-file" function and
8046 split the buffer into lines yourself.
8047 readdir
8049 readdir dir
8050 This returns the list of directory entries in directory "dir".
8052 All entries in the directory are returned, including "." and "..". The
8054 entries are not sorted, but returned in the same order as the
8055 underlying filesystem.
8056 Also this call returns basic file type information about each file.
8058 The "ftyp" field will contain one of the following characters:
8059 'b' Block special
8061 'c' Char special
8063 'd' Directory
8065 'f' FIFO (named pipe)
8067 'l' Symbolic link
8069 'r' Regular file
8071 's' Socket
8073 'u' Unknown file type
8075 '?' The readdir(3) call returned a "d_type" field with an unexpected
8077 value
8078 This function is primarily intended for use by programs. To get a
8080 simple list of names, use "ls". To get a printable directory for human
8081 consumption, use "ll".
8082 Because of the message protocol, there is a transfer limit of somewhere
8084 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8085 readlink
8087 readlink path
8088 This command reads the target of a symbolic link.
8090 readlinklist
8092 readlinklist path 'names ...'
8093 This call allows you to do a "readlink" operation on multiple files,
8095 where all files are in the directory "path". "names" is the list of
8096 files from this directory.
8097 On return you get a list of strings, with a one-to-one correspondence
8099 to the "names" list. Each string is the value of the symbolic link.
8100 If the readlink(2) operation fails on any name, then the corresponding
8102 result string is the empty string "". However the whole operation is
8103 completed even if there were readlink(2) errors, and so you can call
8104 this function with names where you don't know if they are symbolic
8105 links already (albeit slightly less efficient).
8106 This call is intended for programs that want to efficiently list a
8108 directory contents without making many round-trips.
8109 realpath
8111 realpath path
8112 Return the canonicalized absolute pathname of "path". The returned
8114 path has no ".", ".." or symbolic link path elements.
8115 remount
8117 remount mountpoint [rw:true|false]
8118 This call allows you to change the "rw" (readonly/read-write) flag on
8120 an already mounted filesystem at "mountpoint", converting a readonly
8121 filesystem to be read-write, or vice-versa.
8122 Note that at the moment you must supply the "optional" "rw" parameter.
8124 In future we may allow other flags to be adjusted.
8125 This command has one or more optional arguments. See "OPTIONAL
8127 ARGUMENTS".
8128 remove-drive
8130 remove-drive label
8131 This function is conceptually the opposite of "add-drive-opts". It
8133 removes the drive that was previously added with label "label".
8134 Note that in order to remove drives, you have to add them with labels
8136 (see the optional "label" argument to "add-drive-opts"). If you didn't
8137 use a label, then they cannot be removed.
8138 You can call this function before or after launching the handle. If
8140 called after launch, if the backend supports it, we try to hot unplug
8141 the drive: see "HOTPLUGGING" in guestfs(3). The disk must not be in
8142 use (eg. mounted) when you do this. We try to detect if the disk is in
8143 use and stop you from doing this.
8144 removexattr
8146 removexattr xattr path
8147 This call removes the extended attribute named "xattr" of the file
8149 "path".
8150 See also: "lremovexattr", attr(5).
8152 This command depends on the feature "linuxxattrs". See also "feature-
8154 available".
8155 rename
8157 rename oldpath newpath
8158 Rename a file to a new place on the same filesystem. This is the same
8160 as the Linux rename(2) system call. In most cases you are better to
8161 use "mv" instead.
8162 resize2fs
8164 resize2fs device
8165 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
8167 underlying device.
8168 See also "RESIZE2FS ERRORS" in guestfs(3).
8170 resize2fs-M
8172 resize2fs-M device
8173 This command is the same as "resize2fs", but the filesystem is resized
8175 to its minimum size. This works like the -M option to the resize2fs(8)
8176 command.
8177 To get the resulting size of the filesystem you should call "tune2fs-l"
8179 and read the "Block size" and "Block count" values. These two numbers,
8180 multiplied together, give the resulting size of the minimal filesystem
8181 in bytes.
8182 See also "RESIZE2FS ERRORS" in guestfs(3).
8184 resize2fs-size
8186 resize2fs-size device size
8187 This command is the same as "resize2fs" except that it allows you to
8189 specify the new size (in bytes) explicitly.
8190 See also "RESIZE2FS ERRORS" in guestfs(3).
8192 rm
8194 rm path
8195 Remove the single file "path".
8197 rm-f
8199 rm-f path
8200 Remove the file "path".
8202 If the file doesn't exist, that error is ignored. (Other errors, eg.
8204 I/O errors or bad paths, are not ignored)
8205 This call cannot remove directories. Use "rmdir" to remove an empty
8207 directory, or "rm-rf" to remove directories recursively.
8208 rm-rf
8210 rm-rf path
8211 Remove the file or directory "path", recursively removing the contents
8213 if its a directory. This is like the "rm -rf" shell command.
8214 rmdir
8216 rmdir path
8217 Remove the single directory "path".
8219 rmmountpoint
8221 rmmountpoint exemptpath
8222 This call removes a mountpoint that was previously created with
8224 "mkmountpoint". See "mkmountpoint" for full details.
8225 rsync
8227 rsync src dest [archive:true|false] [deletedest:true|false]
8228 This call may be used to copy or synchronize two directories under the
8230 same libguestfs handle. This uses the rsync(1) program which uses a
8231 fast algorithm that avoids copying files unnecessarily.
8232 "src" and "dest" are the source and destination directories. Files are
8234 copied from "src" to "dest".
8235 The optional arguments are:
8237 "archive"
8239 Turns on archive mode. This is the same as passing the --archive
8240 flag to "rsync".
8241 "deletedest"
8243 Delete files at the destination that do not exist at the source.
8244 This command has one or more optional arguments. See "OPTIONAL
8246 ARGUMENTS".
8247 This command depends on the feature "rsync". See also "feature-
8249 available".
8250 rsync-in
8252 rsync-in remote dest [archive:true|false] [deletedest:true|false]
8253 This call may be used to copy or synchronize the filesystem on the host
8255 or on a remote computer with the filesystem within libguestfs. This
8256 uses the rsync(1) program which uses a fast algorithm that avoids
8257 copying files unnecessarily.
8258 This call only works if the network is enabled. See "set-network" or
8260 the --network option to various tools like guestfish(1).
8261 Files are copied from the remote server and directory specified by
8263 "remote" to the destination directory "dest".
8264 The format of the remote server string is defined by rsync(1). Note
8266 that there is no way to supply a password or passphrase so the target
8267 must be set up not to require one.
8268 The optional arguments are the same as those of "rsync".
8270 This command has one or more optional arguments. See "OPTIONAL
8272 ARGUMENTS".
8273 This command depends on the feature "rsync". See also "feature-
8275 available".
8276 rsync-out
8278 rsync-out src remote [archive:true|false] [deletedest:true|false]
8279 This call may be used to copy or synchronize the filesystem within
8281 libguestfs with a filesystem on the host or on a remote computer. This
8282 uses the rsync(1) program which uses a fast algorithm that avoids
8283 copying files unnecessarily.
8284 This call only works if the network is enabled. See "set-network" or
8286 the --network option to various tools like guestfish(1).
8287 Files are copied from the source directory "src" to the remote server
8289 and directory specified by "remote".
8290 The format of the remote server string is defined by rsync(1). Note
8292 that there is no way to supply a password or passphrase so the target
8293 must be set up not to require one.
8294 The optional arguments are the same as those of "rsync".
8296 Globbing does not happen on the "src" parameter. In programs which use
8298 the API directly you have to expand wildcards yourself (see "glob-
8299 expand"). In guestfish you can use the "glob" command (see "glob"),
8300 for example:
8301 ><fs> glob rsync-out /* rsync://remote/
8303 This command has one or more optional arguments. See "OPTIONAL
8305 ARGUMENTS".
8306 This command depends on the feature "rsync". See also "feature-
8308 available".
8309 scrub-device
8311 scrub-device device
8312 This command writes patterns over "device" to make data retrieval more
8314 difficult.
8315 It is an interface to the scrub(1) program. See that manual page for
8317 more details.
8318 This command depends on the feature "scrub". See also "feature-
8320 available".
8321 scrub-file
8323 scrub-file file
8324 This command writes patterns over a file to make data retrieval more
8326 difficult.
8327 The file is removed after scrubbing.
8329 It is an interface to the scrub(1) program. See that manual page for
8331 more details.
8332 This command depends on the feature "scrub". See also "feature-
8334 available".
8335 scrub-freespace
8337 scrub-freespace dir
8338 This command creates the directory "dir" and then fills it with files
8340 until the filesystem is full, and scrubs the files as for "scrub-file",
8341 and deletes them. The intention is to scrub any free space on the
8342 partition containing "dir".
8343 It is an interface to the scrub(1) program. See that manual page for
8345 more details.
8346 This command depends on the feature "scrub". See also "feature-
8348 available".
8349 selinux-relabel
8351 selinux-relabel specfile path [force:true|false]
8352 SELinux relabel parts of the filesystem.
8354 The "specfile" parameter controls the policy spec file used. You have
8356 to parse "/etc/selinux/config" to find the correct SELinux policy and
8357 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
8358 "/contexts/files/file_contexts".
8359 The required "path" parameter is the top level directory where
8361 relabelling starts. Normally you should pass "path" as "/" to relabel
8362 the whole guest filesystem.
8363 The optional "force" boolean controls whether the context is reset for
8365 customizable files, and also whether the user, role and range parts of
8366 the file context is changed.
8367 This command has one or more optional arguments. See "OPTIONAL
8369 ARGUMENTS".
8370 This command depends on the feature "selinuxrelabel". See also
8372 "feature-available".
8373 set-append
8375 append
8376 set-append append
8377 This function is used to add additional options to the libguestfs
8379 appliance kernel command line.
8380 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
8382 environment variable.
8383 Setting "append" to "NULL" means no additional options are passed
8385 (libguestfs always adds a few of its own).
8386 set-attach-method
8388 attach-method
8389 set-attach-method backend
8390 Set the method that libguestfs uses to connect to the backend guestfsd
8392 daemon.
8393 See "BACKEND" in guestfs(3).
8395 This function is deprecated. In new code, use the "set-backend" call
8397 instead.
8398 Deprecated functions will not be removed from the API, but the fact
8400 that they are deprecated indicates that there are problems with correct
8401 use of these functions.
8402 set-autosync
8404 autosync
8405 set-autosync true|false
8406 If "autosync" is true, this enables autosync. Libguestfs will make a
8408 best effort attempt to make filesystems consistent and synchronized
8409 when the handle is closed (also if the program exits without closing
8410 handles).
8411 This is enabled by default (since libguestfs 1.5.24, previously it was
8413 disabled by default).
8414 set-backend
8416 backend
8417 set-backend backend
8418 Set the method that libguestfs uses to connect to the backend guestfsd
8420 daemon.
8421 This handle property was previously called the "attach method".
8423 See "BACKEND" in guestfs(3).
8425 set-backend-setting
8427 set-backend-setting name val
8428 Append "name=value" to the backend settings string list. However if a
8430 string already exists matching "name" or beginning with "name=", then
8431 that setting is replaced.
8432 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8434 set-backend-settings
8436 set-backend-settings 'settings ...'
8437 Set a list of zero or more settings which are passed through to the
8439 current backend. Each setting is a string which is interpreted in a
8440 backend-specific way, or ignored if not understood by the backend.
8441 The default value is an empty list, unless the environment variable
8443 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
8444 This environment variable contains a colon-separated list of settings.
8445 This call replaces all backend settings. If you want to replace a
8447 single backend setting, see "set-backend-setting". If you want to
8448 clear a single backend setting, see "clear-backend-setting".
8449 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8451 set-cachedir
8453 cachedir
8454 set-cachedir cachedir
8455 Set the directory used by the handle to store the appliance cache, when
8457 using a supermin appliance. The appliance is cached and shared between
8458 all handles which have the same effective user ID.
8459 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
8461 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
8462 default. Else if "TMPDIR" is set, then that is the default. Else
8463 /var/tmp is the default.
8464 set-direct
8466 direct
8467 set-direct true|false
8468 If the direct appliance mode flag is enabled, then stdin and stdout are
8470 passed directly through to the appliance once it is launched.
8471 One consequence of this is that log messages aren't caught by the
8473 library and handled by "set-log-message-callback", but go straight to
8474 stdout.
8475 You probably don't want to use this unless you know what you are doing.
8477 The default is disabled.
8479 This function is deprecated. In new code, use the "internal-get-
8481 console-socket" call instead.
8482 Deprecated functions will not be removed from the API, but the fact
8484 that they are deprecated indicates that there are problems with correct
8485 use of these functions.
8486 set-e2attrs
8488 set-e2attrs file attrs [clear:true|false]
8489 This sets or clears the file attributes "attrs" associated with the
8491 inode file.
8492 "attrs" is a string of characters representing file attributes. See
8494 "get-e2attrs" for a list of possible attributes. Not all attributes
8495 can be changed.
8496 If optional boolean "clear" is not present or false, then the "attrs"
8498 listed are set in the inode.
8499 If "clear" is true, then the "attrs" listed are cleared in the inode.
8501 In both cases, other attributes not present in the "attrs" string are
8503 left unchanged.
8504 These attributes are only present when the file is located on an
8506 ext2/3/4 filesystem. Using this call on other filesystem types will
8507 result in an error.
8508 This command has one or more optional arguments. See "OPTIONAL
8510 ARGUMENTS".
8511 set-e2generation
8513 set-e2generation file generation
8514 This sets the ext2 file generation of a file.
8516 See "get-e2generation".
8518 set-e2label
8520 set-e2label device label
8521 This sets the ext2/3/4 filesystem label of the filesystem on "device"
8523 to "label". Filesystem labels are limited to 16 characters.
8524 You can use either "tune2fs-l" or "get-e2label" to return the existing
8526 label on a filesystem.
8527 This function is deprecated. In new code, use the "set-label" call
8529 instead.
8530 Deprecated functions will not be removed from the API, but the fact
8532 that they are deprecated indicates that there are problems with correct
8533 use of these functions.
8534 set-e2uuid
8536 set-e2uuid device uuid
8537 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
8539 "uuid". The format of the UUID and alternatives such as "clear",
8540 "random" and "time" are described in the tune2fs(8) manpage.
8541 You can use "vfs-uuid" to return the existing UUID of a filesystem.
8543 This function is deprecated. In new code, use the "set-uuid" call
8545 instead.
8546 Deprecated functions will not be removed from the API, but the fact
8548 that they are deprecated indicates that there are problems with correct
8549 use of these functions.
8550 set-hv
8552 hv
8553 set-hv hv
8554 Set the hypervisor binary that we will use. The hypervisor depends on
8556 the backend, but is usually the location of the qemu/KVM hypervisor.
8557 For the uml backend, it is the location of the "linux" or "vmlinux"
8558 binary.
8559 The default is chosen when the library was compiled by the configure
8561 script.
8562 You can also override this by setting the "LIBGUESTFS_HV" environment
8564 variable.
8565 Note that you should call this function as early as possible after
8567 creating the handle. This is because some pre-launch operations depend
8568 on testing qemu features (by running "qemu -help"). If the qemu binary
8569 changes, we don't retest features, and so you might see inconsistent
8570 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8571 all since that picks the qemu binary at the same time as the handle is
8572 created.
8573 set-identifier
8575 identifier
8576 set-identifier identifier
8577 This is an informative string which the caller may optionally set in
8579 the handle. It is printed in various places, allowing the current
8580 handle to be identified in debugging output.
8581 One important place is when tracing is enabled. If the identifier
8583 string is not an empty string, then trace messages change from this:
8584 libguestfs: trace: get_tmpdir
8586 libguestfs: trace: get_tmpdir = "/tmp"
8587 to this:
8589 libguestfs: trace: ID: get_tmpdir
8591 libguestfs: trace: ID: get_tmpdir = "/tmp"
8592 where "ID" is the identifier string set by this call.
8594 The identifier must only contain alphanumeric ASCII characters,
8596 underscore and minus sign. The default is the empty string.
8597 See also "set-program", "set-trace", "get-identifier".
8599 set-label
8601 set-label mountable label
8602 Set the filesystem label on "mountable" to "label".
8604 Only some filesystem types support labels, and libguestfs supports
8606 setting labels on only a subset of these.
8607 ext2, ext3, ext4
8609 Labels are limited to 16 bytes.
8610 NTFS
8612 Labels are limited to 128 unicode characters.
8613 XFS The label is limited to 12 bytes. The filesystem must not be
8615 mounted when trying to set the label.
8616 btrfs
8618 The label is limited to 255 bytes and some characters are not
8619 allowed. Setting the label on a btrfs subvolume will set the label
8620 on its parent filesystem. The filesystem must not be mounted when
8621 trying to set the label.
8622 fat The label is limited to 11 bytes.
8624 swap
8626 The label is limited to 16 bytes.
8627 If there is no support for changing the label for the type of the
8629 specified filesystem, set_label will fail and set errno as ENOTSUP.
8630 To read the label on a filesystem, call "vfs-label".
8632 set-libvirt-requested-credential
8634 set-libvirt-requested-credential index cred
8635 After requesting the "index"'th credential from the user, call this
8637 function to pass the answer back to libvirt.
8638 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8640 example code.
8641 set-libvirt-supported-credentials
8643 set-libvirt-supported-credentials 'creds ...'
8644 Call this function before setting an event handler for
8646 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
8647 that the program knows how to process.
8648 The "creds" list must be a non-empty list of strings. Possible strings
8650 are:
8651 "username"
8653 "authname"
8654 "language"
8655 "cnonce"
8656 "passphrase"
8657 "echoprompt"
8658 "noechoprompt"
8659 "realm"
8660 "external"
8661 See libvirt documentation for the meaning of these credential types.
8663 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8665 example code.
8666 set-memsize
8668 memsize
8669 set-memsize memsize
8670 This sets the memory size in megabytes allocated to the hypervisor.
8672 This only has any effect if called before "launch".
8673 You can also change this by setting the environment variable
8675 "LIBGUESTFS_MEMSIZE" before the handle is created.
8676 For more information on the architecture of libguestfs, see guestfs(3).
8678 set-network
8680 network
8681 set-network true|false
8682 If "network" is true, then the network is enabled in the libguestfs
8684 appliance. The default is false.
8685 This affects whether commands are able to access the network (see
8687 "RUNNING COMMANDS" in guestfs(3)).
8688 You must call this before calling "launch", otherwise it has no effect.
8690 set-path
8692 path
8693 set-path searchpath
8694 Set the path that libguestfs searches for kernel and initrd.img.
8696 The default is "$libdir/guestfs" unless overridden by setting
8698 "LIBGUESTFS_PATH" environment variable.
8699 Setting "path" to "NULL" restores the default path.
8701 set-pgroup
8703 pgroup
8704 set-pgroup true|false
8705 If "pgroup" is true, child processes are placed into their own process
8707 group.
8708 The practical upshot of this is that signals like "SIGINT" (from users
8710 pressing "^C") won't be received by the child process.
8711 The default for this flag is false, because usually you want "^C" to
8713 kill the subprocess. Guestfish sets this flag to true when used
8714 interactively, so that "^C" can cancel long-running commands gracefully
8715 (see "user-cancel").
8716 set-program
8718 program
8719 set-program program
8720 Set the program name. This is an informative string which the main
8722 program may optionally set in the handle.
8723 When the handle is created, the program name in the handle is set to
8725 the basename from "argv[0]". The program name can never be "NULL".
8726 set-qemu
8728 qemu
8729 set-qemu hv
8730 Set the hypervisor binary (usually qemu) that we will use.
8732 The default is chosen when the library was compiled by the configure
8734 script.
8735 You can also override this by setting the "LIBGUESTFS_HV" environment
8737 variable.
8738 Setting "hv" to "NULL" restores the default qemu binary.
8740 Note that you should call this function as early as possible after
8742 creating the handle. This is because some pre-launch operations depend
8743 on testing qemu features (by running "qemu -help"). If the qemu binary
8744 changes, we don't retest features, and so you might see inconsistent
8745 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8746 all since that picks the qemu binary at the same time as the handle is
8747 created.
8748 This function is deprecated. In new code, use the "set-hv" call
8750 instead.
8751 Deprecated functions will not be removed from the API, but the fact
8753 that they are deprecated indicates that there are problems with correct
8754 use of these functions.
8755 set-recovery-proc
8757 recovery-proc
8758 set-recovery-proc true|false
8759 If this is called with the parameter "false" then "launch" does not
8761 create a recovery process. The purpose of the recovery process is to
8762 stop runaway hypervisor processes in the case where the main program
8763 aborts abruptly.
8764 This only has any effect if called before "launch", and the default is
8766 true.
8767 About the only time when you would want to disable this is if the main
8769 process will fork itself into the background ("daemonize" itself). In
8770 this case the recovery process thinks that the main program has
8771 disappeared and so kills the hypervisor, which is not very helpful.
8772 set-selinux
8774 selinux
8775 set-selinux true|false
8776 This sets the selinux flag that is passed to the appliance at boot
8778 time. The default is "selinux=0" (disabled).
8779 Note that if SELinux is enabled, it is always in Permissive mode
8781 ("enforcing=0").
8782 For more information on the architecture of libguestfs, see guestfs(3).
8784 This function is deprecated. In new code, use the "selinux-relabel"
8786 call instead.
8787 Deprecated functions will not be removed from the API, but the fact
8789 that they are deprecated indicates that there are problems with correct
8790 use of these functions.
8791 set-smp
8793 smp
8794 set-smp smp
8795 Change the number of virtual CPUs assigned to the appliance. The
8797 default is 1. Increasing this may improve performance, though often it
8798 has no effect.
8799 This function must be called before "launch".
8801 set-tmpdir
8803 tmpdir
8804 set-tmpdir tmpdir
8805 Set the directory used by the handle to store temporary files.
8807 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
8809 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
8810 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
8811 default.
8812 set-trace
8814 trace
8815 set-trace true|false
8816 If the command trace flag is set to 1, then libguestfs calls,
8818 parameters and return values are traced.
8819 If you want to trace C API calls into libguestfs (and other libraries)
8821 then possibly a better way is to use the external ltrace(1) command.
8822 Command traces are disabled unless the environment variable
8824 "LIBGUESTFS_TRACE" is defined and set to 1.
8825 Trace messages are normally sent to "stderr", unless you register a
8827 callback to send them somewhere else (see "set-event-callback").
8828 set-uuid
8830 set-uuid device uuid
8831 Set the filesystem UUID on "device" to "uuid". If this fails and the
8833 errno is ENOTSUP, means that there is no support for changing the UUID
8834 for the type of the specified filesystem.
8835 Only some filesystem types support setting UUIDs.
8837 To read the UUID on a filesystem, call "vfs-uuid".
8839 set-uuid-random
8841 set-uuid-random device
8842 Set the filesystem UUID on "device" to a random UUID. If this fails
8844 and the errno is ENOTSUP, means that there is no support for changing
8845 the UUID for the type of the specified filesystem.
8846 Only some filesystem types support setting UUIDs.
8848 To read the UUID on a filesystem, call "vfs-uuid".
8850 set-verbose
8852 verbose
8853 set-verbose true|false
8854 If "verbose" is true, this turns on verbose messages.
8856 Verbose messages are disabled unless the environment variable
8858 "LIBGUESTFS_DEBUG" is defined and set to 1.
8859 Verbose messages are normally sent to "stderr", unless you register a
8861 callback to send them somewhere else (see "set-event-callback").
8862 setcon
8864 setcon context
8865 This sets the SELinux security context of the daemon to the string
8867 "context".
8868 See the documentation about SELINUX in guestfs(3).
8870 This function is deprecated. In new code, use the "selinux-relabel"
8872 call instead.
8873 Deprecated functions will not be removed from the API, but the fact
8875 that they are deprecated indicates that there are problems with correct
8876 use of these functions.
8877 This command depends on the feature "selinux". See also "feature-
8879 available".
8880 setxattr
8882 setxattr xattr val vallen path
8883 This call sets the extended attribute named "xattr" of the file "path"
8885 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
8886 data.
8887 See also: "lsetxattr", attr(5).
8889 This command depends on the feature "linuxxattrs". See also "feature-
8891 available".
8892 sfdisk
8894 sfdisk device cyls heads sectors 'lines ...'
8895 This is a direct interface to the sfdisk(8) program for creating
8897 partitions on block devices.
8898 "device" should be a block device, for example /dev/sda.
8900 "cyls", "heads" and "sectors" are the number of cylinders, heads and
8902 sectors on the device, which are passed directly to sfdisk(8) as the
8903 -C, -H and -S parameters. If you pass 0 for any of these, then the
8904 corresponding parameter is omitted. Usually for ‘large’ disks, you can
8905 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
8906 (or rather, the kernel) cannot work out the right geometry and you will
8907 need to tell it.
8908 "lines" is a list of lines that we feed to sfdisk(8). For more
8910 information refer to the sfdisk(8) manpage.
8911 To create a single partition occupying the whole disk, you would pass
8913 "lines" as a single element list, when the single element being the
8914 string "," (comma).
8915 See also: "sfdisk-l", "sfdisk-N", "part-init"
8917 This function is deprecated. In new code, use the "part-add" call
8919 instead.
8920 Deprecated functions will not be removed from the API, but the fact
8922 that they are deprecated indicates that there are problems with correct
8923 use of these functions.
8924 sfdiskM
8926 sfdiskM device 'lines ...'
8927 This is a simplified interface to the "sfdisk" command, where partition
8929 sizes are specified in megabytes only (rounded to the nearest cylinder)
8930 and you don't need to specify the cyls, heads and sectors parameters
8931 which were rarely if ever used anyway.
8932 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
8934 This function is deprecated. In new code, use the "part-add" call
8936 instead.
8937 Deprecated functions will not be removed from the API, but the fact
8939 that they are deprecated indicates that there are problems with correct
8940 use of these functions.
8941 sfdisk-N
8943 sfdisk-N device partnum cyls heads sectors line
8944 This runs sfdisk(8) option to modify just the single partition "n"
8946 (note: "n" counts from 1).
8947 For other parameters, see "sfdisk". You should usually pass 0 for the
8949 cyls/heads/sectors parameters.
8950 See also: "part-add"
8952 This function is deprecated. In new code, use the "part-add" call
8954 instead.
8955 Deprecated functions will not be removed from the API, but the fact
8957 that they are deprecated indicates that there are problems with correct
8958 use of these functions.
8959 sfdisk-disk-geometry
8961 sfdisk-disk-geometry device
8962 This displays the disk geometry of "device" read from the partition
8964 table. Especially in the case where the underlying block device has
8965 been resized, this can be different from the kernel’s idea of the
8966 geometry (see "sfdisk-kernel-geometry").
8967 The result is in human-readable format, and not designed to be parsed.
8969 sfdisk-kernel-geometry
8971 sfdisk-kernel-geometry device
8972 This displays the kernel’s idea of the geometry of "device".
8974 The result is in human-readable format, and not designed to be parsed.
8976 sfdisk-l
8978 sfdisk-l device
8979 This displays the partition table on "device", in the human-readable
8981 output of the sfdisk(8) command. It is not intended to be parsed.
8982 See also: "part-list"
8984 This function is deprecated. In new code, use the "part-list" call
8986 instead.
8987 Deprecated functions will not be removed from the API, but the fact
8989 that they are deprecated indicates that there are problems with correct
8990 use of these functions.
8991 sh
8993 sh command
8994 This call runs a command from the guest filesystem via the guest’s
8996 /bin/sh.
8997 This is like "command", but passes the command to:
8999 /bin/sh -c "command"
9001 Depending on the guest’s shell, this usually results in wildcards being
9003 expanded, shell expressions being interpolated and so on.
9004 All the provisos about "command" apply to this call.
9006 sh-lines
9008 sh-lines command
9009 This is the same as "sh", but splits the result into a list of lines.
9011 See also: "command-lines"
9013 shutdown
9015 shutdown
9016 This is the opposite of "launch". It performs an orderly shutdown of
9018 the backend process(es). If the autosync flag is set (which is the
9019 default) then the disk image is synchronized.
9020 If the subprocess exits with an error then this function will return an
9022 error, which should not be ignored (it may indicate that the disk image
9023 could not be written out properly).
9024 It is safe to call this multiple times. Extra calls are ignored.
9026 This call does not close or free up the handle. You still need to call
9028 "close" afterwards.
9029 "close" will call this if you don't do it explicitly, but note that any
9031 errors are ignored in that case.
9032 sleep
9034 sleep secs
9035 Sleep for "secs" seconds.
9037 stat
9039 stat path
9040 Returns file information for the given "path".
9042 This is the same as the stat(2) system call.
9044 This function is deprecated. In new code, use the "statns" call
9046 instead.
9047 Deprecated functions will not be removed from the API, but the fact
9049 that they are deprecated indicates that there are problems with correct
9050 use of these functions.
9051 statns
9053 statns path
9054 Returns file information for the given "path".
9056 This is the same as the stat(2) system call.
9058 statvfs
9060 statvfs path
9061 Returns file system statistics for any mounted file system. "path"
9063 should be a file or directory in the mounted file system (typically it
9064 is the mount point itself, but it doesn't need to be).
9065 This is the same as the statvfs(2) system call.
9067 strings
9069 strings path
9070 This runs the strings(1) command on a file and returns the list of
9072 printable strings found.
9073 The "strings" command has, in the past, had problems with parsing
9075 untrusted files. These are mitigated in the current version of
9076 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9077 Because of the message protocol, there is a transfer limit of somewhere
9079 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9080 strings-e
9082 strings-e encoding path
9083 This is like the "strings" command, but allows you to specify the
9085 encoding of strings that are looked for in the source file "path".
9086 Allowed encodings are:
9088 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
9090 parts of ISO-8859-X (this is what "strings" uses).
9091 S Single 8-bit-byte characters.
9093 b 16-bit big endian strings such as those encoded in UTF-16BE or
9095 UCS-2BE.
9096 l (lower case letter L)
9098 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
9099 for examining binaries in Windows guests.
9100 B 32-bit big endian such as UCS-4BE.
9102 L 32-bit little endian such as UCS-4LE.
9104 The returned strings are transcoded to UTF-8.
9106 The "strings" command has, in the past, had problems with parsing
9108 untrusted files. These are mitigated in the current version of
9109 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9110 Because of the message protocol, there is a transfer limit of somewhere
9112 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9113 swapoff-device
9115 swapoff-device device
9116 This command disables the libguestfs appliance swap device or partition
9118 named "device". See "swapon-device".
9119 swapoff-file
9121 swapoff-file file
9122 This command disables the libguestfs appliance swap on file.
9124 swapoff-label
9126 swapoff-label label
9127 This command disables the libguestfs appliance swap on labeled swap
9129 partition.
9130 swapoff-uuid
9132 swapoff-uuid uuid
9133 This command disables the libguestfs appliance swap partition with the
9135 given UUID.
9136 This command depends on the feature "linuxfsuuid". See also "feature-
9138 available".
9139 swapon-device
9141 swapon-device device
9142 This command enables the libguestfs appliance to use the swap device or
9144 partition named "device". The increased memory is made available for
9145 all commands, for example those run using "command" or "sh".
9146 Note that you should not swap to existing guest swap partitions unless
9148 you know what you are doing. They may contain hibernation information,
9149 or other information that the guest doesn't want you to trash. You
9150 also risk leaking information about the host to the guest this way.
9151 Instead, attach a new host device to the guest and swap on that.
9152 swapon-file
9154 swapon-file file
9155 This command enables swap to a file. See "swapon-device" for other
9157 notes.
9158 swapon-label
9160 swapon-label label
9161 This command enables swap to a labeled swap partition. See "swapon-
9163 device" for other notes.
9164 swapon-uuid
9166 swapon-uuid uuid
9167 This command enables swap to a swap partition with the given UUID. See
9169 "swapon-device" for other notes.
9170 This command depends on the feature "linuxfsuuid". See also "feature-
9172 available".
9173 sync
9175 sync
9176 This syncs the disk, so that any writes are flushed through to the
9178 underlying disk image.
9179 You should always call this if you have modified a disk image, before
9181 closing the handle.
9182 syslinux
9184 syslinux device [directory:..]
9185 Install the SYSLINUX bootloader on "device".
9187 The device parameter must be either a whole disk formatted as a FAT
9189 filesystem, or a partition formatted as a FAT filesystem. In the
9190 latter case, the partition should be marked as "active" ("part-set-
9191 bootable") and a Master Boot Record must be installed (eg. using
9192 "pwrite-device") on the first sector of the whole disk. The SYSLINUX
9193 package comes with some suitable Master Boot Records. See the
9194 syslinux(1) man page for further information.
9195 The optional arguments are:
9197 directory
9199 Install SYSLINUX in the named subdirectory, instead of in the root
9200 directory of the FAT filesystem.
9201 Additional configuration can be supplied to SYSLINUX by placing a file
9203 called syslinux.cfg on the FAT filesystem, either in the root
9204 directory, or under directory if that optional argument is being used.
9205 For further information about the contents of this file, see
9206 syslinux(1).
9207 See also "extlinux".
9209 This command has one or more optional arguments. See "OPTIONAL
9211 ARGUMENTS".
9212 This command depends on the feature "syslinux". See also "feature-
9214 available".
9215 tail
9217 tail path
9218 This command returns up to the last 10 lines of a file as a list of
9220 strings.
9221 Because of the message protocol, there is a transfer limit of somewhere
9223 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9224 tail-n
9226 tail-n nrlines path
9227 If the parameter "nrlines" is a positive number, this returns the last
9229 "nrlines" lines of the file "path".
9230 If the parameter "nrlines" is a negative number, this returns lines
9232 from the file "path", starting with the "-nrlines"'th line.
9233 If the parameter "nrlines" is zero, this returns an empty list.
9235 Because of the message protocol, there is a transfer limit of somewhere
9237 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9238 tar-in
9240 tar-in-opts
9241 tar-in (tarfile|-) directory [compress:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9242 This command uploads and unpacks local file "tarfile" into directory.
9244 The optional "compress" flag controls compression. If not given, then
9246 the input should be an uncompressed tar file. Otherwise one of the
9247 following strings may be given to select the compression type of the
9248 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9249 all builds of libguestfs will support all of these compression types).
9250 The other optional arguments are:
9252 "xattrs"
9254 If set to true, extended attributes are restored from the tar file.
9255 "selinux"
9257 If set to true, SELinux contexts are restored from the tar file.
9258 "acls"
9260 If set to true, POSIX ACLs are restored from the tar file.
9261 Use "-" instead of a filename to read/write from stdin/stdout.
9263 This command has one or more optional arguments. See "OPTIONAL
9265 ARGUMENTS".
9266 tar-out
9268 tar-out-opts
9269 tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9270 This command packs the contents of directory and downloads it to local
9272 file "tarfile".
9273 The optional "compress" flag controls compression. If not given, then
9275 the output will be an uncompressed tar file. Otherwise one of the
9276 following strings may be given to select the compression type of the
9277 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9278 all builds of libguestfs will support all of these compression types).
9279 The other optional arguments are:
9281 "excludes"
9283 A list of wildcards. Files are excluded if they match any of the
9284 wildcards.
9285 "numericowner"
9287 If set to true, the output tar file will contain UID/GID numbers
9288 instead of user/group names.
9289 "xattrs"
9291 If set to true, extended attributes are saved in the output tar.
9292 "selinux"
9294 If set to true, SELinux contexts are saved in the output tar.
9295 "acls"
9297 If set to true, POSIX ACLs are saved in the output tar.
9298 Use "-" instead of a filename to read/write from stdin/stdout.
9300 This command has one or more optional arguments. See "OPTIONAL
9302 ARGUMENTS".
9303 tgz-in
9305 tgz-in (tarball|-) directory
9306 This command uploads and unpacks local file "tarball" (a gzip
9308 compressed tar file) into directory.
9309 Use "-" instead of a filename to read/write from stdin/stdout.
9311 This function is deprecated. In new code, use the "tar-in" call
9313 instead.
9314 Deprecated functions will not be removed from the API, but the fact
9316 that they are deprecated indicates that there are problems with correct
9317 use of these functions.
9318 tgz-out
9320 tgz-out directory (tarball|-)
9321 This command packs the contents of directory and downloads it to local
9323 file "tarball".
9324 Use "-" instead of a filename to read/write from stdin/stdout.
9326 This function is deprecated. In new code, use the "tar-out" call
9328 instead.
9329 Deprecated functions will not be removed from the API, but the fact
9331 that they are deprecated indicates that there are problems with correct
9332 use of these functions.
9333 touch
9335 touch path
9336 Touch acts like the touch(1) command. It can be used to update the
9338 timestamps on a file, or, if the file does not exist, to create a new
9339 zero-length file.
9340 This command only works on regular files, and will fail on other file
9342 types such as directories, symbolic links, block special etc.
9343 truncate
9345 truncate path
9346 This command truncates "path" to a zero-length file. The file must
9348 exist already.
9349 truncate-size
9351 truncate-size path size
9352 This command truncates "path" to size "size" bytes. The file must
9354 exist already.
9355 If the current file size is less than "size" then the file is extended
9357 to the required size with zero bytes. This creates a sparse file (ie.
9358 disk blocks are not allocated for the file until you write to it). To
9359 create a non-sparse file of zeroes, use "fallocate64" instead.
9360 tune2fs
9362 tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
9363 This call allows you to adjust various filesystem parameters of an
9365 ext2/ext3/ext4 filesystem called "device".
9366 The optional parameters are:
9368 "force"
9370 Force tune2fs to complete the operation even in the face of errors.
9371 This is the same as the tune2fs(8) "-f" option.
9372 "maxmountcount"
9374 Set the number of mounts after which the filesystem is checked by
9375 e2fsck(8). If this is 0 then the number of mounts is disregarded.
9376 This is the same as the tune2fs(8) "-c" option.
9377 "mountcount"
9379 Set the number of times the filesystem has been mounted. This is
9380 the same as the tune2fs(8) "-C" option.
9381 "errorbehavior"
9383 Change the behavior of the kernel code when errors are detected.
9384 Possible values currently are: "continue", "remount-ro", "panic".
9385 In practice these options don't really make any difference,
9386 particularly for write errors.
9387 This is the same as the tune2fs(8) "-e" option.
9389 "group"
9391 Set the group which can use reserved filesystem blocks. This is
9392 the same as the tune2fs(8) "-g" option except that it can only be
9393 specified as a number.
9394 "intervalbetweenchecks"
9396 Adjust the maximal time between two filesystem checks (in seconds).
9397 If the option is passed as 0 then time-dependent checking is
9398 disabled.
9399 This is the same as the tune2fs(8) "-i" option.
9401 "reservedblockspercentage"
9403 Set the percentage of the filesystem which may only be allocated by
9404 privileged processes. This is the same as the tune2fs(8) "-m"
9405 option.
9406 "lastmounteddirectory"
9408 Set the last mounted directory. This is the same as the tune2fs(8)
9409 "-M" option.
9410 "reservedblockscount" Set the number of reserved filesystem blocks.
9412 This is the same as the tune2fs(8) "-r" option.
9413 "user"
9414 Set the user who can use the reserved filesystem blocks. This is
9415 the same as the tune2fs(8) "-u" option except that it can only be
9416 specified as a number.
9417 To get the current values of filesystem parameters, see "tune2fs-l".
9419 For precise details of how tune2fs works, see the tune2fs(8) man page.
9420 This command has one or more optional arguments. See "OPTIONAL
9422 ARGUMENTS".
9423 tune2fs-l
9425 tune2fs-l device
9426 This returns the contents of the ext2, ext3 or ext4 filesystem
9428 superblock on "device".
9429 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
9431 for more details. The list of fields returned isn't clearly defined,
9432 and depends on both the version of "tune2fs" that libguestfs was built
9433 against, and the filesystem itself.
9434 txz-in
9436 txz-in (tarball|-) directory
9437 This command uploads and unpacks local file "tarball" (an xz compressed
9439 tar file) into directory.
9440 Use "-" instead of a filename to read/write from stdin/stdout.
9442 This function is deprecated. In new code, use the "tar-in" call
9444 instead.
9445 Deprecated functions will not be removed from the API, but the fact
9447 that they are deprecated indicates that there are problems with correct
9448 use of these functions.
9449 This command depends on the feature "xz". See also "feature-
9451 available".
9452 txz-out
9454 txz-out directory (tarball|-)
9455 This command packs the contents of directory and downloads it to local
9457 file "tarball" (as an xz compressed tar archive).
9458 Use "-" instead of a filename to read/write from stdin/stdout.
9460 This function is deprecated. In new code, use the "tar-out" call
9462 instead.
9463 Deprecated functions will not be removed from the API, but the fact
9465 that they are deprecated indicates that there are problems with correct
9466 use of these functions.
9467 This command depends on the feature "xz". See also "feature-
9469 available".
9470 umask
9472 umask mask
9473 This function sets the mask used for creating new files and device
9475 nodes to "mask & 0777".
9476 Typical umask values would be 022 which creates new files with
9478 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
9479 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
9480 The default umask is 022. This is important because it means that
9482 directories and device nodes will be created with 0644 or 0755 mode
9483 even if you specify 0777.
9484 See also "get-umask", umask(2), "mknod", "mkdir".
9486 This call returns the previous umask.
9488 umount
9490 unmount
9491 umount-opts
9492 umount pathordevice [force:true|false] [lazyunmount:true|false]
9493 This unmounts the given filesystem. The filesystem may be specified
9495 either by its mountpoint (path) or the device which contains the
9496 filesystem.
9497 This command has one or more optional arguments. See "OPTIONAL
9499 ARGUMENTS".
9500 umount-all
9502 unmount-all
9503 umount-all
9504 This unmounts all mounted filesystems.
9506 Some internal mounts are not unmounted by this call.
9508 umount-local
9510 umount-local [retry:true|false]
9511 If libguestfs is exporting the filesystem on a local mountpoint, then
9513 this unmounts it.
9514 See "MOUNT LOCAL" in guestfs(3) for full documentation.
9516 This command has one or more optional arguments. See "OPTIONAL
9518 ARGUMENTS".
9519 upload
9521 upload (filename|-) remotefilename
9522 Upload local file filename to remotefilename on the filesystem.
9524 filename can also be a named pipe.
9526 See also "download".
9528 Use "-" instead of a filename to read/write from stdin/stdout.
9530 upload-offset
9532 upload-offset (filename|-) remotefilename offset
9533 Upload local file filename to remotefilename on the filesystem.
9535 remotefilename is overwritten starting at the byte "offset" specified.
9537 The intention is to overwrite parts of existing files or devices,
9538 although if a non-existent file is specified then it is created with a
9539 "hole" before "offset". The size of the data written is implicit in
9540 the size of the source filename.
9541 Note that there is no limit on the amount of data that can be uploaded
9543 with this call, unlike with "pwrite", and this call always writes the
9544 full amount unless an error occurs.
9545 See also "upload", "pwrite".
9547 Use "-" instead of a filename to read/write from stdin/stdout.
9549 user-cancel
9551 user-cancel
9552 This function cancels the current upload or download operation.
9554 Unlike most other libguestfs calls, this function is signal safe and
9556 thread safe. You can call it from a signal handler or from another
9557 thread, without needing to do any locking.
9558 The transfer that was in progress (if there is one) will stop shortly
9560 afterwards, and will return an error. The errno (see
9561 "guestfs_last_errno") is set to "EINTR", so you can test for this to
9562 find out if the operation was cancelled or failed because of another
9563 error.
9564 No cleanup is performed: for example, if a file was being uploaded then
9566 after cancellation there may be a partially uploaded file. It is the
9567 caller’s responsibility to clean up if necessary.
9568 There are two common places that you might call "user-cancel":
9570 In an interactive text-based program, you might call it from a "SIGINT"
9572 signal handler so that pressing "^C" cancels the current operation.
9573 (You also need to call "set-pgroup" so that child processes don't
9574 receive the "^C" signal).
9575 In a graphical program, when the main thread is displaying a progress
9577 bar with a cancel button, wire up the cancel button to call this
9578 function.
9579 utimens
9581 utimens path atsecs atnsecs mtsecs mtnsecs
9582 This command sets the timestamps of a file with nanosecond precision.
9584 "atsecs", "atnsecs" are the last access time (atime) in secs and
9586 nanoseconds from the epoch.
9587 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
9589 nanoseconds from the epoch.
9590 If the *nsecs field contains the special value "-1" then the
9592 corresponding timestamp is set to the current time. (The *secs field
9593 is ignored in this case).
9594 If the *nsecs field contains the special value "-2" then the
9596 corresponding timestamp is left unchanged. (The *secs field is ignored
9597 in this case).
9598 utsname
9600 utsname
9601 This returns the kernel version of the appliance, where this is
9603 available. This information is only useful for debugging. Nothing in
9604 the returned structure is defined by the API.
9605 version
9607 version
9608 Return the libguestfs version number that the program is linked
9610 against.
9611 Note that because of dynamic linking this is not necessarily the
9613 version of libguestfs that you compiled against. You can compile the
9614 program, and then at runtime dynamically link against a completely
9615 different libguestfs.so library.
9616 This call was added in version 1.0.58. In previous versions of
9618 libguestfs there was no way to get the version number. From C code you
9619 can use dynamic linker functions to find out if this symbol exists (if
9620 it doesn't, then it’s an earlier version).
9621 The call returns a structure with four elements. The first three
9623 ("major", "minor" and "release") are numbers and correspond to the
9624 usual version triplet. The fourth element ("extra") is a string and is
9625 normally empty, but may be used for distro-specific information.
9626 To construct the original version string:
9628 "$major.$minor.$release$extra"
9629 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
9631 Note: Don't use this call to test for availability of features. In
9633 enterprise distributions we backport features from later versions into
9634 earlier versions, making this an unreliable way to test for features.
9635 Use "available" or "feature-available" instead.
9636 vfs-label
9638 vfs-label mountable
9639 This returns the label of the filesystem on "mountable".
9641 If the filesystem is unlabeled, this returns the empty string.
9643 To find a filesystem from the label, use "findfs-label".
9645 vfs-minimum-size
9647 vfs-minimum-size mountable
9648 Get the minimum size of filesystem in bytes. This is the minimum
9650 possible size for filesystem shrinking.
9651 If getting minimum size of specified filesystem is not supported, this
9653 will fail and set errno as ENOTSUP.
9654 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
9656 vfs-type
9658 vfs-type mountable
9659 This command gets the filesystem type corresponding to the filesystem
9661 on "mountable".
9662 For most filesystems, the result is the name of the Linux VFS module
9664 which would be used to mount this filesystem if you mounted it without
9665 specifying the filesystem type. For example a string such as "ext3" or
9666 "ntfs".
9667 vfs-uuid
9669 get-uuid
9670 vfs-uuid mountable
9671 This returns the filesystem UUID of the filesystem on "mountable".
9673 If the filesystem does not have a UUID, this returns the empty string.
9675 To find a filesystem from the UUID, use "findfs-uuid".
9677 vg-activate
9679 vg-activate true|false 'volgroups ...'
9680 This command activates or (if "activate" is false) deactivates all
9682 logical volumes in the listed volume groups "volgroups".
9683 This command is the same as running "vgchange -a y|n volgroups..."
9685 Note that if "volgroups" is an empty list then all volume groups are
9687 activated or deactivated.
9688 This command depends on the feature "lvm2". See also "feature-
9690 available".
9691 vg-activate-all
9693 vg-activate-all true|false
9694 This command activates or (if "activate" is false) deactivates all
9696 logical volumes in all volume groups.
9697 This command is the same as running "vgchange -a y|n"
9699 This command depends on the feature "lvm2". See also "feature-
9701 available".
9702 vgchange-uuid
9704 vgchange-uuid vg
9705 Generate a new random UUID for the volume group "vg".
9707 This command depends on the feature "lvm2". See also "feature-
9709 available".
9710 vgchange-uuid-all
9712 vgchange-uuid-all
9713 Generate new random UUIDs for all volume groups.
9715 This command depends on the feature "lvm2". See also "feature-
9717 available".
9718 vgcreate
9720 vgcreate volgroup 'physvols ...'
9721 This creates an LVM volume group called "volgroup" from the non-empty
9723 list of physical volumes "physvols".
9724 This command depends on the feature "lvm2". See also "feature-
9726 available".
9727 vglvuuids
9729 vglvuuids vgname
9730 Given a VG called "vgname", this returns the UUIDs of all the logical
9732 volumes created in this volume group.
9733 You can use this along with "lvs" and "lvuuid" calls to associate
9735 logical volumes and volume groups.
9736 See also "vgpvuuids".
9738 vgmeta
9740 vgmeta vgname
9741 "vgname" is an LVM volume group. This command examines the volume
9743 group and returns its metadata.
9744 Note that the metadata is an internal structure used by LVM, subject to
9746 change at any time, and is provided for information only.
9747 This command depends on the feature "lvm2". See also "feature-
9749 available".
9750 vgpvuuids
9752 vgpvuuids vgname
9753 Given a VG called "vgname", this returns the UUIDs of all the physical
9755 volumes that this volume group resides on.
9756 You can use this along with "pvs" and "pvuuid" calls to associate
9758 physical volumes and volume groups.
9759 See also "vglvuuids".
9761 vgremove
9763 vgremove vgname
9764 Remove an LVM volume group "vgname", (for example "VG").
9766 This also forcibly removes all logical volumes in the volume group (if
9768 any).
9769 This command depends on the feature "lvm2". See also "feature-
9771 available".
9772 vgrename
9774 vgrename volgroup newvolgroup
9775 Rename a volume group "volgroup" with the new name "newvolgroup".
9777 vgs
9779 vgs
9780 List all the volumes groups detected. This is the equivalent of the
9782 vgs(8) command.
9783 This returns a list of just the volume group names that were detected
9785 (eg. "VolGroup00").
9786 See also "vgs-full".
9788 This command depends on the feature "lvm2". See also "feature-
9790 available".
9791 vgs-full
9793 vgs-full
9794 List all the volumes groups detected. This is the equivalent of the
9796 vgs(8) command. The "full" version includes all fields.
9797 This command depends on the feature "lvm2". See also "feature-
9799 available".
9800 vgscan
9802 vgscan
9803 This rescans all block devices and rebuilds the list of LVM physical
9805 volumes, volume groups and logical volumes.
9806 This function is deprecated. In new code, use the "lvm-scan" call
9808 instead.
9809 Deprecated functions will not be removed from the API, but the fact
9811 that they are deprecated indicates that there are problems with correct
9812 use of these functions.
9813 vguuid
9815 vguuid vgname
9816 This command returns the UUID of the LVM VG named "vgname".
9818 wc-c
9820 wc-c path
9821 This command counts the characters in a file, using the "wc -c"
9823 external command.
9824 wc-l
9826 wc-l path
9827 This command counts the lines in a file, using the "wc -l" external
9829 command.
9830 wc-w
9832 wc-w path
9833 This command counts the words in a file, using the "wc -w" external
9835 command.
9836 wipefs
9838 wipefs device
9839 This command erases filesystem or RAID signatures from the specified
9841 "device" to make the filesystem invisible to libblkid.
9842 This does not erase the filesystem itself nor any other data from the
9844 "device".
9845 Compare with "zero" which zeroes the first few blocks of a device.
9847 This command depends on the feature "wipefs". See also "feature-
9849 available".
9850 write
9852 write path content
9853 This call creates a file called "path". The content of the file is the
9855 string "content" (which can contain any 8 bit data).
9856 See also "write-append".
9858 write-append
9860 write-append path content
9861 This call appends "content" to the end of file "path". If "path" does
9863 not exist, then a new file is created.
9864 See also "write".
9866 write-file
9868 write-file path content size
9869 This call creates a file called "path". The contents of the file is
9871 the string "content" (which can contain any 8 bit data), with length
9872 "size".
9873 As a special case, if "size" is 0 then the length is calculated using
9875 "strlen" (so in this case the content cannot contain embedded ASCII
9876 NULs).
9877 NB. Owing to a bug, writing content containing ASCII NUL characters
9879 does not work, even if the length is specified.
9880 Because of the message protocol, there is a transfer limit of somewhere
9882 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9883 This function is deprecated. In new code, use the "write" call
9885 instead.
9886 Deprecated functions will not be removed from the API, but the fact
9888 that they are deprecated indicates that there are problems with correct
9889 use of these functions.
9890 xfs-admin
9892 xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
9893 Change the parameters of the XFS filesystem on "device".
9895 Devices that are mounted cannot be modified. Administrators must
9897 unmount filesystems before this call can modify parameters.
9898 Some of the parameters of a mounted filesystem can be examined and
9900 modified using the "xfs-info" and "xfs-growfs" calls.
9901 This command has one or more optional arguments. See "OPTIONAL
9903 ARGUMENTS".
9904 This command depends on the feature "xfs". See also "feature-
9906 available".
9907 xfs-growfs
9909 xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
9910 Grow the XFS filesystem mounted at "path".
9912 The returned struct contains geometry information. Missing fields are
9914 returned as "-1" (for numeric fields) or empty string.
9915 This command has one or more optional arguments. See "OPTIONAL
9917 ARGUMENTS".
9918 This command depends on the feature "xfs". See also "feature-
9920 available".
9921 xfs-info
9923 xfs-info pathordevice
9924 "pathordevice" is a mounted XFS filesystem or a device containing an
9926 XFS filesystem. This command returns the geometry of the filesystem.
9927 The returned struct contains geometry information. Missing fields are
9929 returned as "-1" (for numeric fields) or empty string.
9930 This command depends on the feature "xfs". See also "feature-
9932 available".
9933 xfs-repair
9935 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:..]
9936 Repair corrupt or damaged XFS filesystem on "device".
9938 The filesystem is specified using the "device" argument which should be
9940 the device name of the disk partition or volume containing the
9941 filesystem. If given the name of a block device, "xfs_repair" will
9942 attempt to find the raw device associated with the specified block
9943 device and will use the raw device instead.
9944 Regardless, the filesystem to be repaired must be unmounted, otherwise,
9946 the resulting filesystem may be inconsistent or corrupt.
9947 The returned status indicates whether filesystem corruption was
9949 detected (returns 1) or was not detected (returns 0).
9950 This command has one or more optional arguments. See "OPTIONAL
9952 ARGUMENTS".
9953 This command depends on the feature "xfs". See also "feature-
9955 available".
9956 yara-destroy
9958 yara-destroy
9959 Destroy previously loaded Yara rules in order to free libguestfs
9961 resources.
9962 This command depends on the feature "libyara". See also "feature-
9964 available".
9965 yara-load
9967 yara-load (filename|-)
9968 Upload a set of Yara rules from local file filename.
9970 Yara rules allow to categorize files based on textual or binary
9972 patterns within their content. See "yara-scan" to see how to scan
9973 files with the loaded rules.
9974 Rules can be in binary format, as when compiled with yarac command, or
9976 in source code format. In the latter case, the rules will be first
9977 compiled and then loaded.
9978 Rules in source code format cannot include external files. In such
9980 cases, it is recommended to compile them first.
9981 Previously loaded rules will be destroyed.
9983 Use "-" instead of a filename to read/write from stdin/stdout.
9985 This command depends on the feature "libyara". See also "feature-
9987 available".
9988 yara-scan
9990 yara-scan path
9991 Scan a file with the previously loaded Yara rules.
9993 For each matching rule, a "yara_detection" structure is returned.
9995 The "yara_detection" structure contains the following fields.
9997 "yara_name"
9999 Path of the file matching a Yara rule.
10000 "yara_rule"
10002 Identifier of the Yara rule which matched against the given file.
10003 This command depends on the feature "libyara". See also "feature-
10005 available".
10006 zegrep
10008 zegrep regex path
10009 This calls the external "zegrep" program and returns the matching
10011 lines.
10012 Because of the message protocol, there is a transfer limit of somewhere
10014 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10015 This function is deprecated. In new code, use the "grep" call instead.
10017 Deprecated functions will not be removed from the API, but the fact
10019 that they are deprecated indicates that there are problems with correct
10020 use of these functions.
10021 zegrepi
10023 zegrepi regex path
10024 This calls the external "zegrep -i" program and returns the matching
10026 lines.
10027 Because of the message protocol, there is a transfer limit of somewhere
10029 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10030 This function is deprecated. In new code, use the "grep" call instead.
10032 Deprecated functions will not be removed from the API, but the fact
10034 that they are deprecated indicates that there are problems with correct
10035 use of these functions.
10036 zero
10038 zero device
10039 This command writes zeroes over the first few blocks of "device".
10041 How many blocks are zeroed isn't specified (but it’s not enough to
10043 securely wipe the device). It should be sufficient to remove any
10044 partition tables, filesystem superblocks and so on.
10045 If blocks are already zero, then this command avoids writing zeroes.
10047 This prevents the underlying device from becoming non-sparse or growing
10048 unnecessarily.
10049 See also: "zero-device", "scrub-device", "is-zero-device"
10051 zero-device
10053 zero-device device
10054 This command writes zeroes over the entire "device". Compare with
10056 "zero" which just zeroes the first few blocks of a device.
10057 If blocks are already zero, then this command avoids writing zeroes.
10059 This prevents the underlying device from becoming non-sparse or growing
10060 unnecessarily.
10061 zero-free-space
10063 zero-free-space directory
10064 Zero the free space in the filesystem mounted on directory. The
10066 filesystem must be mounted read-write.
10067 The filesystem contents are not affected, but any free space in the
10069 filesystem is freed.
10070 Free space is not "trimmed". You may want to call "fstrim" either as
10072 an alternative to this, or after calling this, depending on your
10073 requirements.
10074 zerofree
10076 zerofree device
10077 This runs the zerofree program on "device". This program claims to
10079 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
10080 it possible to compress the filesystem more effectively.
10081 You should not run this program if the filesystem is mounted.
10083 It is possible that using this program can damage the filesystem or
10085 data on the filesystem.
10086 This command depends on the feature "zerofree". See also "feature-
10088 available".
10089 zfgrep
10091 zfgrep pattern path
10092 This calls the external "zfgrep" program and returns the matching
10094 lines.
10095 Because of the message protocol, there is a transfer limit of somewhere
10097 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10098 This function is deprecated. In new code, use the "grep" call instead.
10100 Deprecated functions will not be removed from the API, but the fact
10102 that they are deprecated indicates that there are problems with correct
10103 use of these functions.
10104 zfgrepi
10106 zfgrepi pattern path
10107 This calls the external "zfgrep -i" program and returns the matching
10109 lines.
10110 Because of the message protocol, there is a transfer limit of somewhere
10112 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10113 This function is deprecated. In new code, use the "grep" call instead.
10115 Deprecated functions will not be removed from the API, but the fact
10117 that they are deprecated indicates that there are problems with correct
10118 use of these functions.
10119 zfile
10121 zfile meth path
10122 This command runs file(1) after first decompressing "path" using
10124 "meth".
10125 "meth" must be one of "gzip", "compress" or "bzip2".
10127 Since 1.0.63, use "file" instead which can now process compressed
10129 files.
10130 This function is deprecated. In new code, use the "file" call instead.
10132 Deprecated functions will not be removed from the API, but the fact
10134 that they are deprecated indicates that there are problems with correct
10135 use of these functions.
10136 zgrep
10138 zgrep regex path
10139 This calls the external zgrep(1) program and returns the matching
10141 lines.
10142 Because of the message protocol, there is a transfer limit of somewhere
10144 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10145 This function is deprecated. In new code, use the "grep" call instead.
10147 Deprecated functions will not be removed from the API, but the fact
10149 that they are deprecated indicates that there are problems with correct
10150 use of these functions.
10151 zgrepi
10153 zgrepi regex path
10154 This calls the external "zgrep -i" program and returns the matching
10156 lines.
10157 Because of the message protocol, there is a transfer limit of somewhere
10159 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10160 This function is deprecated. In new code, use the "grep" call instead.
10162 Deprecated functions will not be removed from the API, but the fact
10164 that they are deprecated indicates that there are problems with correct
10165 use of these functions.
10166
10168 guestfish returns 0 if the commands completed without error, or 1 if
10169 there was an error.
10170
10172 EDITOR
10173 The "edit" command uses $EDITOR as the editor. If not set, it uses
10174 "vi".
10175 GUESTFISH_DISPLAY_IMAGE
10177 The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
10178 images. If not set, it uses display(1).
10179 GUESTFISH_INIT
10181 Printed when guestfish starts. See "PROMPT".
10182 GUESTFISH_OUTPUT
10184 Printed before guestfish output. See "PROMPT".
10185 GUESTFISH_PID
10187 Used with the --remote option to specify the remote guestfish
10188 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
10189 SOCKET".
10190 GUESTFISH_PS1
10192 Set the command prompt. See "PROMPT".
10193 GUESTFISH_RESTORE
10195 Printed before guestfish exits. See "PROMPT".
10196 HEXEDITOR
10198 The "hexedit" command uses $HEXEDITOR as the external hex editor.
10199 If not specified, the external hexedit(1) program is used.
10200 HOME
10202 If compiled with GNU readline support, various files in the home
10203 directory can be used. See "FILES".
10204 LIBGUESTFS_APPEND
10206 Pass additional options to the guest kernel.
10207 LIBGUESTFS_ATTACH_METHOD
10209 This is the old way to set "LIBGUESTFS_BACKEND".
10210 LIBGUESTFS_BACKEND
10212 Choose the default way to create the appliance. See
10213 "guestfs_set_backend" in guestfs(3).
10214 LIBGUESTFS_BACKEND_SETTINGS
10216 A colon-separated list of backend-specific settings. See "BACKEND"
10217 in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
10218 LIBGUESTFS_CACHEDIR
10220 The location where libguestfs will cache its appliance, when using
10221 a supermin appliance. The appliance is cached and shared between
10222 all handles which have the same effective user ID.
10223 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
10225 "TMPDIR" is not set, then /var/tmp is used.
10226 See also "LIBGUESTFS_TMPDIR", "set-cachedir".
10228 LIBGUESTFS_DEBUG
10230 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
10231 same effect as using the -v option.
10232 LIBGUESTFS_HV
10234 Set the default hypervisor (usually qemu) binary that libguestfs
10235 uses. If not set, then the qemu which was found at compile time by
10236 the configure script is used.
10237 LIBGUESTFS_MEMSIZE
10239 Set the memory allocated to the qemu process, in megabytes. For
10240 example:
10241 LIBGUESTFS_MEMSIZE=700
10243 LIBGUESTFS_PATH
10245 Set the path that guestfish uses to search for kernel and
10246 initrd.img. See the discussion of paths in guestfs(3).
10247 LIBGUESTFS_QEMU
10249 This is the old way to set "LIBGUESTFS_HV".
10250 LIBGUESTFS_TMPDIR
10252 The location where libguestfs will store temporary files used by
10253 each handle.
10254 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
10256 "TMPDIR" is not set, then /tmp is used.
10257 See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
10259 LIBGUESTFS_TRACE
10261 Set "LIBGUESTFS_TRACE=1" to enable command traces.
10262 PAGER
10264 The "more" command uses $PAGER as the pager. If not set, it uses
10265 "more".
10266 PATH
10268 Libguestfs and guestfish may run some external programs, and rely
10269 on $PATH being set to a reasonable value. If using the libvirt
10270 backend, libvirt will not work at all unless $PATH contains the
10271 path of qemu/KVM.
10272 SUPERMIN_KERNEL
10274 SUPERMIN_KERNEL_VERSION
10275 SUPERMIN_MODULES
10276 These three environment variables allow the kernel that libguestfs
10277 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
10278 set, then the most recent host kernel is chosen. For more
10279 information about kernel selection, see supermin(1).
10280 TMPDIR
10282 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
10283 XDG_RUNTIME_DIR
10285 This directory represents a user-specific directory for storing
10286 non-essential runtime files.
10287 If it is set, then is used to store temporary sockets. Otherwise,
10289 /tmp is used.
10290 See also "get-sockdir",
10292 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
10293
10295 $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
10296 $HOME/.libguestfs-tools.rc
10297 $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
10298 /etc/libguestfs-tools.conf
10299 This configuration file controls the default read-only or read-
10300 write mode (--ro or --rw).
10301 See libguestfs-tools.conf(5).
10303 $HOME/.guestfish
10305 If compiled with GNU readline support, then the command history is
10306 saved in this file.
10307 $HOME/.inputrc
10309 /etc/inputrc
10310 If compiled with GNU readline support, then these files can be used
10311 to configure readline. For further information, please see
10312 "INITIALIZATION FILE" in readline(3).
10313 To write rules which only apply to guestfish, use:
10315 $if guestfish
10317 ...
10318 $endif
10319 Variables that you can set in inputrc that change the behaviour of
10321 guestfish in useful ways include:
10322 completion-ignore-case (default: on)
10324 By default, guestfish will ignore case when tab-completing
10325 paths on the disk. Use:
10326 set completion-ignore-case off
10328 to make guestfish case sensitive.
10330 test1.img
10332 test2.img (etc)
10333 When using the -N or --new option, the prepared disk or filesystem
10334 will be created in the file test1.img in the current directory.
10335 The second use of -N will use test2.img and so on. Any existing
10336 file with the same name will be overwritten. You can use a
10337 different filename by using the "filename=" prefix.
10338
10340 guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
10341 virt-builder(1), virt-builder-repository(1), virt-cat(1),
10342 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
10343 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1),
10344 virt-list-filesystems(1), virt-list-partitions(1), virt-log(1),
10345 virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
10346 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
10347 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
10348 virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1),
10349 supermin(1).
10350
10352 Richard W.M. Jones ("rjones at redhat dot com")
10353
10355 Copyright (C) 2009-2020 Red Hat Inc.
10356
10358 This program is free software; you can redistribute it and/or modify it
10359 under the terms of the GNU General Public License as published by the
10360 Free Software Foundation; either version 2 of the License, or (at your
10361 option) any later version.
10362 This program is distributed in the hope that it will be useful, but
10364 WITHOUT ANY WARRANTY; without even the implied warranty of
10365 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10366 General Public License for more details.
10367 You should have received a copy of the GNU General Public License along
10369 with this program; if not, write to the Free Software Foundation, Inc.,
10370 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
10371
10373 To get a list of bugs against libguestfs, use this link:
10374 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
10375 To report a new bug against libguestfs, use this link:
10377 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
10378 When reporting a bug, please supply:
10380 · The version of libguestfs.
10382 · Where you got libguestfs (eg. which Linux distro, compiled from
10384 source, etc)
10385 · Describe the bug accurately and give a way to reproduce it.
10387 · Run libguestfs-test-tool(1) and paste the complete, unedited output
10389 into the bug report.
10390libguestfs-1.42.0 2020-03-09 guestfish(1)