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 If there are multiple encrypted devices then you may need to supply
288 multiple keys on stdin, one per line.
289 --listen
291 Fork into the background and listen for remote commands. See
292 section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
293 --live
295 Connect to a live virtual machine. (Experimental, see "ATTACHING
296 TO RUNNING DAEMONS" in guestfs(3)).
297 -m dev[:mountpoint[:options[:fstype]]]
299 --mount dev[:mountpoint[:options[:fstype]]]
300 Mount the named partition or logical volume on the given
301 mountpoint.
302 If the mountpoint is omitted, it defaults to /.
304 You have to mount something on / before most commands will work.
306 If any -m or --mount options are given, the guest is automatically
308 launched.
309 If you don’t know what filesystems a disk image contains, you can
311 either run guestfish without this option, then list the partitions,
312 filesystems and LVs available (see "list-partitions", "list-
313 filesystems" and "lvs" commands), or you can use the
314 virt-filesystems(1) program.
315 The third (and rarely used) part of the mount parameter is the list
317 of mount options used to mount the underlying filesystem. If this
318 is not given, then the mount options are either the empty string or
319 "ro" (the latter if the --ro flag is used). By specifying the
320 mount options, you override this default choice. Probably the only
321 time you would use this is to enable ACLs and/or extended
322 attributes if the filesystem can support them:
323 -m /dev/sda1:/:acl,user_xattr
325 Using this flag is equivalent to using the "mount-options" command.
327 The fourth part of the parameter is the filesystem driver to use,
329 such as "ext3" or "ntfs". This is rarely needed, but can be useful
330 if multiple drivers are valid for a filesystem (eg: "ext2" and
331 "ext3"), or if libguestfs misidentifies a filesystem.
332 --network
334 Enable QEMU user networking in the guest.
335 -N [FILENAME=]TYPE
337 --new [FILENAME=]TYPE
338 -N help
339 Prepare a fresh disk image formatted as "TYPE". This is an
340 alternative to the -a option: whereas -a adds an existing disk, -N
341 creates a preformatted disk with a filesystem and adds it. See
342 "PREPARED DISK IMAGES" below.
343 -n
345 --no-sync
346 Disable autosync. This is enabled by default. See the discussion
347 of autosync in the guestfs(3) manpage.
348 --no-dest-paths
350 Don’t tab-complete paths on the guest filesystem. It is useful to
351 be able to hit the tab key to complete paths on the guest
352 filesystem, but this causes extra "hidden" guestfs calls to be
353 made, so this option is here to allow this feature to be disabled.
354 --pipe-error
356 If writes fail to pipe commands (see "PIPES" below), then the
357 command returns an error.
358 The default (also for historical reasons) is to ignore such errors
360 so that:
361 ><fs> command_with_lots_of_output | head
363 doesn't give an error.
365 --progress-bars
367 Enable progress bars, even when guestfish is used non-
368 interactively.
369 Progress bars are enabled by default when guestfish is used as an
371 interactive shell.
372 --no-progress-bars
374 Disable progress bars.
375 --remote
377 --remote=PID
378 Send remote commands to $GUESTFISH_PID or "pid". See section
379 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
380 -r
382 --ro
383 This changes the -a, -d and -m options so that disks are added and
384 mounts are done read-only.
385 The option must always be used if the disk image or virtual machine
387 might be running, and is generally recommended in cases where you
388 don't need write access to the disk.
389 Note that prepared disk images created with -N are not affected by
391 this option. Also commands like "add" are not affected - you have
392 to specify the "readonly:true" option explicitly if you need it.
393 See also "OPENING DISKS FOR READ AND WRITE" below.
395 --selinux
397 This option is provided for backwards compatibility and does
398 nothing.
399 -v
401 --verbose
402 Enable very verbose messages. This is particularly useful if you
403 find a bug.
404 -V
406 --version
407 Display the guestfish / libguestfs version number and exit.
408 -w
410 --rw
411 This changes the -a, -d and -m options so that disks are added and
412 mounts are done read-write.
413 See "OPENING DISKS FOR READ AND WRITE" below.
415 -x Echo each command before executing it.
417
419 Any additional (non-option) arguments are treated as commands to
420 execute.
421 Commands to execute should be separated by a colon (":"), where the
423 colon is a separate parameter. Thus:
424 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
426 If there are no additional arguments, then we enter a shell, either an
428 interactive shell with a prompt (if the input is a terminal) or a non-
429 interactive shell.
430 In either command line mode or non-interactive shell, the first command
432 that gives an error causes the whole shell to exit. In interactive
433 mode (with a prompt) if a command fails, you can continue to enter
434 commands.
435 Note that arguments of the commands will be considered as guestfish
437 options if they start with a dash ("-"): you can always separate the
438 guestfish options and the rest of the commands (with their arguments)
439 using a double dash ("--"). For example:
440 guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img
442
444 As with guestfs(3), you must first configure your guest by adding
445 disks, then launch it, then mount any disks you need, and finally issue
446 actions/commands. So the general order of the day is:
447 • add or -a/--add
449 • launch (aka run)
451 • mount or -m/--mount
453 • any other commands
455 "run" is a synonym for "launch". You must "launch" (or "run") your
457 guest before mounting or performing any other commands.
458 The only exception is that if any of the -i, -m, --mount, -N or --new
460 options were given then "run" is done automatically, simply because
461 guestfish can't perform the action you asked for without doing this.
462
464 The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
465 affect whether the other command line options -a, -c, -d, -i and -m
466 open disk images read-only or for writing.
467 In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
469 to opening disk images supplied on the command line for write. To open
470 a disk image read-only you have to do -a image --ro.
471 This matters: If you accidentally open a live VM disk image writable
473 then you will cause irreversible disk corruption.
474 In a future libguestfs we intend to change the default the other way.
476 Disk images will be opened read-only. You will have to either specify
477 guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
478 configuration file in order to get write access for disk images
479 specified by those other command line options.
480 This version of guestfish, guestmount and virt-rescue has a --rw option
482 which does nothing (it is already the default). However it is highly
483 recommended that you use this option to indicate that you need write
484 access, and prepare your scripts for the day when this option will be
485 required for write access.
486 Note: This does not affect commands like "add" and "mount", or any
488 other libguestfs program apart from guestfish and guestmount.
489
491 You can quote ordinary parameters using either single or double quotes.
492 For example:
493 add "file with a space.img"
495 rm '/file name'
497 rm '/"'
499 A few commands require a list of strings to be passed. For these, use
501 a whitespace-separated list, enclosed in quotes. Strings containing
502 whitespace to be passed through must be enclosed in single quotes. A
503 literal single quote must be escaped with a backslash.
504 vgcreate VG "/dev/sda1 /dev/sdb1"
506 command "/bin/echo 'foo bar'"
507 command "/bin/echo \'foo\'"
508 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
510 In double-quoted arguments (only) use backslash to insert special
511 characters:
512 "\a"
514 Alert (bell) character.
515 "\b"
517 Backspace character.
518 "\f"
520 Form feed character.
521 "\n"
523 Newline character.
524 "\r"
526 Carriage return character.
527 "\t"
529 Horizontal tab character.
530 "\v"
532 Vertical tab character.
533 "\""
535 A literal double quote character.
536 "\ooo"
538 A character with octal value ooo. There must be precisely 3 octal
539 digits (unlike C).
540 "\xhh"
542 A character with hex value hh. There must be precisely 2 hex
543 digits.
544 In the current implementation "\000" and "\x00" cannot be used in
546 strings.
547 "\\"
549 A literal backslash character.
550
552 Some commands take optional arguments. These arguments appear in this
553 documentation as "[argname:..]". You can use them as in these
554 examples:
555 add filename
557 add filename readonly:true
559 add filename format:qcow2 readonly:false
561 Each optional argument can appear at most once. All optional arguments
563 must appear after the required ones.
564
566 This section applies to all commands which can take integers as
567 parameters.
568 SIZE SUFFIX
570 When the command takes a parameter measured in bytes, you can use one
571 of the following suffixes to specify kilobytes, megabytes and larger
572 sizes:
573 k or K or KiB
575 The size in kilobytes (multiplied by 1024).
576 KB The size in SI 1000 byte units.
578 M or MiB
580 The size in megabytes (multiplied by 1048576).
581 MB The size in SI 1000000 byte units.
583 G or GiB
585 The size in gigabytes (multiplied by 2**30).
586 GB The size in SI 10**9 byte units.
588 T or TiB
590 The size in terabytes (multiplied by 2**40).
591 TB The size in SI 10**12 byte units.
593 P or PiB
595 The size in petabytes (multiplied by 2**50).
596 PB The size in SI 10**15 byte units.
598 E or EiB
600 The size in exabytes (multiplied by 2**60).
601 EB The size in SI 10**18 byte units.
603 Z or ZiB
605 The size in zettabytes (multiplied by 2**70).
606 ZB The size in SI 10**21 byte units.
608 Y or YiB
610 The size in yottabytes (multiplied by 2**80).
611 YB The size in SI 10**24 byte units.
613 For example:
615 truncate-size /file 1G
617 would truncate the file to 1 gigabyte.
619 Be careful because a few commands take sizes in kilobytes or megabytes
621 (eg. the parameter to "memsize" is specified in megabytes already).
622 Adding a suffix will probably not do what you expect.
623 OCTAL AND HEXADECIMAL NUMBERS
625 For specifying the radix (base) use the C convention: 0 to prefix an
626 octal number or "0x" to prefix a hexadecimal number. For example:
627 1234 decimal number 1234
629 02322 octal number, equivalent to decimal 1234
630 0x4d2 hexadecimal number, equivalent to decimal 1234
631 When using the "chmod" command, you almost always want to specify an
633 octal number for the mode, and you must prefix it with 0 (unlike the
634 Unix chmod(1) program):
635 chmod 0777 /public # OK
637 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
638 Commands that return numbers usually print them in decimal, but some
640 commands print numbers in other radices (eg. "umask" prints the mode in
641 octal, preceded by 0).
642
644 Neither guestfish nor the underlying guestfs API performs wildcard
645 expansion (globbing) by default. So for example the following will not
646 do what you expect:
647 rm-rf /home/*
649 Assuming you don’t have a directory called literally /home/* then the
651 above command will return an error.
652 To perform wildcard expansion, use the "glob" command.
654 glob rm-rf /home/*
656 runs "rm-rf" on each path that matches (ie. potentially running the
658 command many times), equivalent to:
659 rm-rf /home/jim
661 rm-rf /home/joe
662 rm-rf /home/mary
663 "glob" only works on simple guest paths and not on device names.
665 If you have several parameters, each containing a wildcard, then glob
667 will perform a Cartesian product.
668
670 Any line which starts with a # character is treated as a comment and
671 ignored. The # can optionally be preceded by whitespace, but not by a
672 command. For example:
673 # this is a comment
675 # this is a comment
676 foo # NOT a comment
677 Blank lines are also ignored.
679
681 Any line which starts with a ! character is treated as a command sent
682 to the local shell (/bin/sh or whatever system(3) uses). For example:
683 !mkdir local
685 tgz-out /remote local/remote-data.tar.gz
686 will create a directory "local" on the host, and then export the
688 contents of /remote on the mounted filesystem to
689 local/remote-data.tar.gz. (See "tgz-out").
690 To change the local directory, use the "lcd" command. "!cd" will have
692 no effect, due to the way that subprocesses work in Unix.
693 LOCAL COMMANDS WITH INLINE EXECUTION
695 If a line starts with <! then the shell command is executed (as for !),
696 but subsequently any output (stdout) of the shell command is parsed and
697 executed as guestfish commands.
698 Thus you can use shell script to construct arbitrary guestfish commands
700 which are then parsed by guestfish.
701 For example it is tedious to create a sequence of files (eg. /foo.1
703 through /foo.100) using guestfish commands alone. However this is
704 simple if we use a shell script to create the guestfish commands for
705 us:
706 <! for n in `seq 1 100`; do echo write /foo.$n $n; done
708 or with names like /foo.001:
710 <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
712 When using guestfish interactively it can be helpful to just run the
714 shell script first (ie. remove the initial "<" character so it is just
715 an ordinary ! local command), see what guestfish commands it would run,
716 and when you are happy with those prepend the "<" character to run the
717 guestfish commands for real.
718
720 Use "command <space> | command" to pipe the output of the first command
721 (a guestfish command) to the second command (any host command). For
722 example:
723 cat /etc/passwd | awk -F: '$3 == 0 { print }'
725 (where "cat" is the guestfish cat command, but "awk" is the host awk
727 program). The above command would list all accounts in the guest
728 filesystem which have UID 0, ie. root accounts including backdoors.
729 Other examples:
730 hexdump /bin/ls | head
732 list-devices | tail -1
733 tgz-out / - | tar ztf -
734 The space before the pipe symbol is required, any space after the pipe
736 symbol is optional. Everything after the pipe symbol is just passed
737 straight to the host shell, so it can contain redirections, globs and
738 anything else that makes sense on the host side.
739 To use a literal argument which begins with a pipe symbol, you have to
741 quote it, eg:
742 echo "|"
744
746 If a parameter starts with the character "~" then the tilde may be
747 expanded as a home directory path (either "~" for the current user's
748 home directory, or "~user" for another user).
749 Note that home directory expansion happens for users known on the host,
751 not in the guest filesystem.
752 To use a literal argument which begins with a tilde, you have to quote
754 it, eg:
755 echo "~"
757
759 Libguestfs has some support for Linux guests encrypted according to the
760 Linux Unified Key Setup (LUKS) standard, which includes nearly all
761 whole disk encryption systems used by modern Linux guests, and Windows
762 BitLocker.
763 Identify encrypted block devices and partitions using "vfs-type":
765 ><fs> vfs-type /dev/sda2
767 crypto_LUKS
768 or:
770 ><fs> vfs-type /dev/sda2
772 BitLocker
773 Then open those devices using "cryptsetup-open". This creates a
775 device-mapper device called /dev/mapper/name.
776 ><fs> cryptsetup-open /dev/sda2 name
778 Enter key or passphrase ("key"): <enter the passphrase>
779 For Linux guests you have to tell LVM to scan for volume groups on the
781 newly created mapper device:
782 vgscan
784 vg-activate-all true
785 The filesystems or logical volumes can now be mounted in the usual way.
787 Before closing an encrypted device you must unmount any logical volumes
789 on it and deactivate the volume groups by calling "vg-activate false
790 VG" on each one. Then you can close the mapper device:
791 vg-activate false /dev/VG
793 cryptsetup-close /dev/mapper/name
794
796 If a path is prefixed with "win:" then you can use Windows-style drive
797 letters and paths (with some limitations). The following commands are
798 equivalent:
799 file /WINDOWS/system32/config/system.LOG
801 file win:\windows\system32\config\system.log
803 file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
805 The parameter is rewritten "behind the scenes" by looking up the
807 position where the drive is mounted, prepending that to the path,
808 changing all backslash characters to forward slash, then resolving the
809 result using "case-sensitive-path". For example if the E: drive was
810 mounted on /e then the parameter might be rewritten like this:
811 win:e:\foo\bar => /e/FOO/bar
813 This only works in argument positions that expect a path.
815
817 For commands such as "upload", "download", "tar-in", "tar-out" and
818 others which upload from or download to a local file, you can use the
819 special filename "-" to mean "from stdin" or "to stdout". For example:
820 upload - /foo
822 reads stdin and creates from that a file /foo in the disk image, and:
824 tar-out /etc - | tar tf -
826 writes the tarball to stdout and then pipes that into the external
828 "tar" command (see "PIPES").
829 When using "-" to read from stdin, the input is read up to the end of
831 stdin. You can also use a special "heredoc"-like syntax to read up to
832 some arbitrary end marker:
833 upload -<<END /foo
835 input line 1
836 input line 2
837 input line 3
838 END
839 Any string of characters can be used instead of "END". The end marker
841 must appear on a line of its own, without any preceding or following
842 characters (not even spaces).
843 Note that the "-<<" syntax only applies to parameters used to upload
845 local files (so-called "FileIn" parameters in the generator).
846
848 By default, guestfish will ignore any errors when in interactive mode
849 (ie. taking commands from a human over a tty), and will exit on the
850 first error in non-interactive mode (scripts, commands given on the
851 command line).
852 If you prefix a command with a - character, then that command will not
854 cause guestfish to exit, even if that (one) command returns an error.
855
857 Guestfish can be remote-controlled over a socket. This is useful
858 particularly in shell scripts where you want to make several different
859 changes to a filesystem, but you don't want the overhead of starting up
860 a guestfish process each time.
861 Start a guestfish server process using:
863 eval "`guestfish --listen`"
865 and then send it commands by doing:
867 guestfish --remote cmd [...]
869 To cause the server to exit, send it the exit command:
871 guestfish --remote exit
873 Note that the server will normally exit if there is an error in a
875 command. You can change this in the usual way. See section "EXIT ON
876 ERROR BEHAVIOUR".
877 CONTROLLING MULTIPLE GUESTFISH PROCESSES
879 The "eval" statement sets the environment variable $GUESTFISH_PID,
880 which is how the --remote option knows where to send the commands. You
881 can have several guestfish listener processes running using:
882 eval "`guestfish --listen`"
884 pid1=$GUESTFISH_PID
885 eval "`guestfish --listen`"
886 pid2=$GUESTFISH_PID
887 ...
888 guestfish --remote=$pid1 cmd
889 guestfish --remote=$pid2 cmd
890 REMOTE CONTROL AND CSH
892 When using csh-like shells (csh, tcsh etc) you have to add the --csh
893 option:
894 eval "`guestfish --listen --csh`"
896 REMOTE CONTROL DETAILS
898 Remote control happens over a Unix domain socket called
899 /tmp/.guestfish-$UID/socket-$PID, where $UID is the effective user ID
900 of the process, and $PID is the process ID of the server.
901 Guestfish client and server versions must match exactly.
903 Older versions of guestfish were vulnerable to CVE-2013-4419 (see
905 "CVE-2013-4419" in guestfs(3)). This is fixed in the current version.
906 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
908 From Bash, you can use the following code which creates a guestfish
909 instance, correctly quotes the command line, handles failure to start,
910 and cleans up guestfish when the script exits:
911 #!/bin/bash -
913 set -e
915 guestfish[0]="guestfish"
917 guestfish[1]="--listen"
918 guestfish[2]="--ro"
919 guestfish[3]="-a"
920 guestfish[4]="disk.img"
921 GUESTFISH_PID=
923 eval $("${guestfish[@]}")
924 if [ -z "$GUESTFISH_PID" ]; then
925 echo "error: guestfish didn't start up, see error messages above"
926 exit 1
927 fi
928 cleanup_guestfish ()
930 {
931 guestfish --remote -- exit >/dev/null 2>&1 ||:
932 }
933 trap cleanup_guestfish EXIT ERR
934 guestfish --remote -- run
936 # ...
938 REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
940 Options such as -a, --add, -N, --new etc don’t interact properly with
941 remote support. They are processed locally, and not sent through to
942 the remote guestfish. In particular this won't do what you expect:
943 guestfish --remote --add disk.img
945 Don’t use these options. Use the equivalent commands instead, eg:
947 guestfish --remote add-drive disk.img
949 or:
951 guestfish --remote
953 ><fs> add disk.img
954 REMOTE CONTROL RUN COMMAND HANGING
956 Using the "run" (or "launch") command remotely in a command
957 substitution context hangs, ie. don't do (note the backquotes):
958 a=`guestfish --remote run`
960 Since the "run" command produces no output on stdout, this is not
962 useful anyway. For further information see
963 https://bugzilla.redhat.com/show_bug.cgi?id=592910.
964
966 Use the -N [filename=]type or --new [filename=]type parameter to select
967 one of a set of preformatted disk images that guestfish can make for
968 you to save typing. This is particularly useful for testing purposes.
969 This option is used instead of the -a option, and like -a can appear
970 multiple times (and can be mixed with -a).
971 The new disk is called test1.img for the first -N, test2.img for the
973 second and so on. Existing files in the current directory are
974 overwritten. You can use a different filename by specifying
975 "filename=" before the type (see examples below).
976 The type briefly describes how the disk should be sized, partitioned,
978 how filesystem(s) should be created, and how content should be added.
979 Optionally the type can be followed by extra parameters, separated by
980 ":" (colon) characters. For example, -N fs creates a default 1G,
981 sparsely-allocated disk, containing a single partition, with the
982 partition formatted as ext2. -N fs:ext4:2G is the same, but for an
983 ext4 filesystem on a 2GB disk instead.
984 Note that the prepared filesystem is not mounted. You would usually
986 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
987 option.
988 If any -N or --new options are given, the libguestfs appliance is
990 automatically launched.
991 EXAMPLES
993 Create a 1G disk with an ext4-formatted partition, called test1.img in
994 the current directory:
995 guestfish -N fs:ext4
997 Create a 32MB disk with a VFAT-formatted partition, and mount it:
999 guestfish -N fs:vfat:32M -m /dev/sda1
1001 Create a blank 200MB disk:
1003 guestfish -N disk:200M
1005 Create a blank 200MB disk called blankdisk.img (instead of test1.img):
1007 guestfish -N blankdisk.img=disk:200M
1009 -N disk - create a blank disk
1011 "guestfish -N [filename=]disk[:size]"
1012 Create a blank disk, size 1G (by default).
1014 The default size can be changed by supplying an optional parameter.
1016 The optional parameters are:
1018 Name Default value
1020 size 1G the size of the disk image
1021 -N part - create a partitioned disk
1023 "guestfish -N [filename=]part[:size[:partition]]"
1024 Create a disk with a single partition. By default the size of the disk
1026 is 1G (the available space in the partition will be a tiny bit smaller)
1027 and the partition table will be MBR (old DOS-style).
1028 These defaults can be changed by supplying optional parameters.
1030 The optional parameters are:
1032 Name Default value
1034 size 1G the size of the disk image
1035 partition mbr partition table type
1036 -N fs - create a filesystem
1038 "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"
1039 Create a disk with a single partition, with the partition containing an
1041 empty filesystem. This defaults to creating a 1G disk (the available
1042 space in the filesystem will be a tiny bit smaller) with an MBR (old
1043 DOS-style) partition table and an ext2 filesystem.
1044 These defaults can be changed by supplying optional parameters.
1046 The optional parameters are:
1048 Name Default value
1050 filesystem ext2 the type of filesystem to use
1051 size 1G the size of the disk image
1052 partition mbr partition table type
1053 -N lv - create a disk with logical volume
1055 "guestfish -N [filename=]lv[:name[:size[:partition]]]"
1056 Create a disk with a single partition, set up the partition as an LVM2
1058 physical volume, and place a volume group and logical volume on there.
1059 This defaults to creating a 1G disk with the VG and LV called
1060 "/dev/VG/LV". You can change the name of the VG and LV by supplying an
1061 alternate name as the first optional parameter.
1062 Note this does not create a filesystem. Use 'lvfs' to do that.
1064 The optional parameters are:
1066 Name Default value
1068 name /dev/VG/LV the name of the VG and LV to use
1069 size 1G the size of the disk image
1070 partition mbr partition table type
1071 -N lvfs - create a disk with logical volume and filesystem
1073 "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"
1074 Create a disk with a single partition, set up the partition as an LVM2
1076 physical volume, and place a volume group and logical volume on there.
1077 Then format the LV with a filesystem. This defaults to creating a 1G
1078 disk with the VG and LV called "/dev/VG/LV", with an ext2 filesystem.
1079 The optional parameters are:
1081 Name Default value
1083 name /dev/VG/LV the name of the VG and LV to use
1084 filesystem ext2 the type of filesystem to use
1085 size 1G the size of the disk image
1086 partition mbr partition table type
1087 -N bootroot - create a boot and root filesystem
1089 "guestfish -N
1090 [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"
1091 Create a disk with two partitions, for boot and root filesystem.
1093 Format the two filesystems independently. There are several optional
1094 parameters which control the exact layout and filesystem types.
1095 The optional parameters are:
1097 Name Default value
1099 bootfs ext2 the type of filesystem to use for boot
1100 rootfs ext2 the type of filesystem to use for root
1101 size 1G the size of the disk image
1102 bootsize 128M the size of the boot filesystem
1103 partition mbr partition table type
1104 -N bootrootlv - create a boot and root filesystem using LVM
1106 "guestfish -N
1107 [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"
1108 This is the same as "bootroot" but the root filesystem (only) is placed
1110 on a logical volume, named by default "/dev/VG/LV". There are several
1111 optional parameters which control the exact layout.
1112 The optional parameters are:
1114 Name Default value
1116 name /dev/VG/LV the name of the VG and LV for root
1117 bootfs ext2 the type of filesystem to use for boot
1118 rootfs ext2 the type of filesystem to use for root
1119 size 1G the size of the disk image
1120 bootsize 128M the size of the boot filesystem
1121 partition mbr partition table type
1122
1124 For API-level documentation on this topic, see "guestfs_add_drive_opts"
1125 in guestfs(3) and "REMOTE STORAGE" in guestfs(3).
1126 On the command line, you can use the -a option to add network block
1128 devices using a URI-style format, for example:
1129 guestfish -a ssh://root@example.com/disk.img
1131 URIs cannot be used with the "add" command. The equivalent command
1133 using the API directly is:
1134 ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root
1136 The possible -a URI formats are described below.
1138 -a disk.img
1140 -a file:///path/to/disk.img
1141 Add the local disk image (or device) called disk.img.
1142 -a ftp://[user@]example.com[:port]/disk.img
1144 -a ftps://[user@]example.com[:port]/disk.img
1145 -a http://[user@]example.com[:port]/disk.img
1146 -a https://[user@]example.com[:port]/disk.img
1147 -a tftp://[user@]example.com[:port]/disk.img
1148 Add a disk located on a remote FTP, HTTP or TFTP server.
1149 The equivalent API command would be:
1151 ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com
1153 -a gluster://example.com[:port]/volname/image
1155 Add a disk image located on GlusterFS storage.
1156 The server is the one running "glusterd", and may be "localhost".
1158 The equivalent API command would be:
1160 ><fs> add volname/image protocol:gluster server:tcp:example.com
1162 -a iscsi://example.com[:port]/target-iqn-name[/lun]
1164 Add a disk located on an iSCSI server.
1165 The equivalent API command would be:
1167 ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com
1169 -a nbd://example.com[:port]
1171 -a nbd://example.com[:port]/exportname
1172 -a nbd://?socket=/socket
1173 -a nbd:///exportname?socket=/socket
1174 Add a disk located on Network Block Device (nbd) storage.
1175 The exportname part of the URI specifies an NBD export name, but is
1177 usually left empty.
1178 The optional ?socket parameter can be used to specify a Unix domain
1180 socket that we talk to the NBD server over. Note that you cannot mix
1181 server name (ie. TCP/IP) and socket path.
1182 The equivalent API command would be (no export name):
1184 ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]
1186 -a rbd:///pool/disk
1188 -a rbd://example.com[:port]/pool/disk
1189 Add a disk image located on a Ceph (RBD/librbd) storage volume.
1190 Although libguestfs and Ceph supports multiple servers, only a single
1192 server can be specified when using this URI syntax.
1193 The equivalent API command would be:
1195 ><fs> add pool/disk protocol:rbd server:tcp:example.com:port
1197 -a sheepdog://[example.com[:port]]/volume/image
1199 Add a disk image located on a Sheepdog volume.
1200 The server name is optional. Although libguestfs and Sheepdog supports
1202 multiple servers, only at most one server can be specified when using
1203 this URI syntax.
1204 The equivalent API command would be:
1206 ><fs> add volume protocol:sheepdog [server:tcp:example.com]
1208 -a ssh://[user@]example.com[:port]/disk.img
1210 Add a disk image located on a remote server, accessed using the Secure
1211 Shell (ssh) SFTP protocol. SFTP is supported out of the box by all
1212 major SSH servers.
1213 The equivalent API command would be:
1215 ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]
1217 Note that the URIs follow the syntax of RFC 3986: in particular, there
1219 are restrictions on the allowed characters for the various components
1220 of the URI. Characters such as ":", "@", and "/" must be percent-
1221 encoded:
1222 $ guestfish -a ssh://user:pass%40word@example.com/disk.img
1224 In this case, the password is "pass@word".
1226
1228 Some (not all) long-running commands send progress notification
1229 messages as they are running. Guestfish turns these messages into
1230 progress bars.
1231 When a command that supports progress bars takes longer than two
1233 seconds to run, and if progress bars are enabled, then you will see one
1234 appearing below the command:
1235 ><fs> copy-size /large-file /another-file 2048M
1237 / 10% [#####-----------------------------------------] 00:30
1238 The spinner on the left hand side moves round once for every progress
1240 notification received from the backend. This is a (reasonably) golden
1241 assurance that the command is "doing something" even if the progress
1242 bar is not moving, because the command is able to send the progress
1243 notifications. When the bar reaches 100% and the command finishes, the
1244 spinner disappears.
1245 Progress bars are enabled by default when guestfish is used
1247 interactively. You can enable them even for non-interactive modes
1248 using --progress-bars, and you can disable them completely using
1249 --no-progress-bars.
1250
1252 You can change or add colours to the default prompt ("><fs>") by
1253 setting the "GUESTFISH_PS1" environment variable. A second string
1254 ("GUESTFISH_OUTPUT") is printed after the command has been entered and
1255 before the output, allowing you to control the colour of the output. A
1256 third string ("GUESTFISH_INIT") is printed before the welcome message,
1257 allowing you to control the colour of that message. A fourth string
1258 ("GUESTFISH_RESTORE") is printed before guestfish exits.
1259 A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate
1261 string:
1262 $ GUESTFISH_PS1='(type a command) '
1264 $ export GUESTFISH_PS1
1265 $ guestfish
1266 [...]
1267 (type a command) ▂
1268 You can also use special escape sequences, as described in the table
1270 below:
1271 \\ A literal backslash character.
1273 \[
1275 \] (These should only be used in "GUESTFISH_PS1".)
1276 Place non-printing characters (eg. terminal control codes for
1278 colours) between "\[...\]". What this does it to tell the
1279 readline(3) library that it should treat this subsequence as zero-
1280 width, so that command-line redisplay, editing etc works.
1281 \a A bell character.
1283 \e An ASCII ESC (escape) character.
1285 \n A newline.
1287 \r A carriage return.
1289 \NNN
1291 The ASCII character whose code is the octal value NNN.
1292 \xNN
1294 The ASCII character whose code is the hex value NN.
1295 EXAMPLES OF PROMPTS
1297 Note that these examples require a terminal that supports ANSI escape
1298 codes.
1299 •
1301 GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1304 A bold black version of the ordinary prompt.
1306 •
1308 GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
1311 GUESTFISH_OUTPUT='\e[0m'
1312 GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
1313 GUESTFISH_INIT='\e[1;34m'
1314 Blue welcome text, green prompt, red commands, black command
1316 output.
1317
1319 Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1320 partitions. See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1321 guestfs(3).
1322
1324 The commands in this section are guestfish convenience commands, in
1325 other words, they are not part of the guestfs(3) API.
1326 help
1328 help
1329 help cmd
1330 help -l|--list
1331 Without any parameter, this provides general help.
1333 With a "cmd" parameter, this displays detailed help for that command.
1335 With -l or --list, this list all commands.
1337 exit
1339 quit
1340 This exits guestfish. You can also use "^D" key.
1341 alloc
1343 allocate
1344 alloc filename size
1345 This creates an empty (zeroed) file of the given size, and then adds so
1347 it can be further examined.
1348 For more advanced image creation, see "disk-create".
1350 Size can be specified using standard suffixes, eg. "1M".
1352 To create a sparse file, use "sparse" instead. To create a prepared
1354 disk image, see "PREPARED DISK IMAGES".
1355 copy-in
1357 copy-in local [local ...] /remotedir
1358 "copy-in" copies local files or directories recursively into the disk
1360 image, placing them in the directory called /remotedir (which must
1361 exist). This guestfish meta-command turns into a sequence of "tar-in"
1362 and other commands as necessary.
1363 Multiple local files and directories can be specified, but the last
1365 parameter must always be a remote directory. Wildcards cannot be used.
1366 copy-out
1368 copy-out remote [remote ...] localdir
1369 "copy-out" copies remote files or directories recursively out of the
1371 disk image, placing them on the host disk in a local directory called
1372 "localdir" (which must exist). This guestfish meta-command turns into
1373 a sequence of "download", "tar-out" and other commands as necessary.
1374 Multiple remote files and directories can be specified, but the last
1376 parameter must always be a local directory. To download to the current
1377 directory, use "." as in:
1378 copy-out /home .
1380 Wildcards cannot be used in the ordinary command, but you can use them
1382 with the help of "glob" like this:
1383 glob copy-out /home/* .
1385 delete-event
1387 delete-event name
1388 Delete the event handler which was previously registered as "name". If
1390 multiple event handlers were registered with the same name, they are
1391 all deleted.
1392 See also the guestfish commands "event" and "list-events".
1394 display
1396 display filename
1397 Use "display" (a graphical display program) to display an image file.
1399 It downloads the file, and runs "display" on it.
1400 To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1402 environment variable. For example to use the GNOME display program:
1403 export GUESTFISH_DISPLAY_IMAGE=eog
1405 See also display(1).
1407 echo
1409 echo [params ...]
1410 This echos the parameters to the terminal.
1412 edit
1414 vi
1415 emacs
1416 edit filename
1417 This is used to edit a file. It downloads the file, edits it locally
1419 using your editor, then uploads the result.
1420 The editor is $EDITOR. However if you use the alternate commands "vi"
1422 or "emacs" you will get those corresponding editors.
1423 event
1425 event name eventset "shell script ..."
1426 Register a shell script fragment which is executed when an event is
1428 raised. See "guestfs_set_event_callback" in guestfs(3) for a
1429 discussion of the event API in libguestfs.
1430 The "name" parameter is a name that you give to this event handler. It
1432 can be any string (even the empty string) and is simply there so you
1433 can delete the handler using the guestfish "delete-event" command.
1434 The "eventset" parameter is a comma-separated list of one or more
1436 events, for example "close" or "close,trace". The special value "*"
1437 means all events.
1438 The third and final parameter is the shell script fragment (or any
1440 external command) that is executed when any of the events in the
1441 eventset occurs. It is executed using "$SHELL -c", or if $SHELL is not
1442 set then /bin/sh -c.
1443 The shell script fragment receives callback parameters as arguments $1,
1445 $2 etc. The actual event that was called is available in the
1446 environment variable $EVENT.
1447 event "" close "echo closed"
1449 event messages appliance,library,trace "echo $@"
1450 event "" progress "echo progress: $3/$4"
1451 event "" * "echo $EVENT $@"
1452 See also the guestfish commands "delete-event" and "list-events".
1454 glob
1456 glob command args...
1457 Expand wildcards in any paths in the args list, and run "command"
1459 repeatedly on each matching path.
1460 See "WILDCARDS AND GLOBBING".
1462 hexedit
1464 hexedit <filename|device>
1465 hexedit <filename|device> <max>
1466 hexedit <filename|device> <start> <max>
1467 Use hexedit (a hex editor) to edit all or part of a binary file or
1469 block device.
1470 This command works by downloading potentially the whole file or device,
1472 editing it locally, then uploading it. If the file or device is large,
1473 you have to specify which part you wish to edit by using "max" and/or
1474 "start" "max" parameters. "start" and "max" are specified in bytes,
1475 with the usual modifiers allowed such as "1M" (1 megabyte).
1476 For example to edit the first few sectors of a disk you might do:
1478 hexedit /dev/sda 1M
1480 which would allow you to edit anywhere within the first megabyte of the
1482 disk.
1483 To edit the superblock of an ext2 filesystem on /dev/sda1, do:
1485 hexedit /dev/sda1 0x400 0x400
1487 (assuming the superblock is in the standard location).
1489 This command requires the external hexedit(1) program. You can specify
1491 another program to use by setting the "HEXEDITOR" environment variable.
1492 See also "hexdump".
1494 lcd
1496 lcd directory
1497 Change the local directory, ie. the current directory of guestfish
1499 itself.
1500 Note that "!cd" won't do what you might expect.
1502 list-events
1504 list-events
1505 List the event handlers registered using the guestfish "event" command.
1507 man
1509 manual
1510 man
1511 Opens the manual page for guestfish.
1513 more
1515 less
1516 more filename
1517 less filename
1519 This is used to view a file.
1521 The default viewer is $PAGER. However if you use the alternate command
1523 "less" you will get the "less" command specifically.
1524 reopen
1526 reopen
1527 Close and reopen the libguestfs handle. It is not necessary to use
1529 this normally, because the handle is closed properly when guestfish
1530 exits. However this is occasionally useful for testing.
1531 setenv
1533 setenv VAR value
1534 Set the environment variable "VAR" to the string "value".
1536 To print the value of an environment variable use a shell command such
1538 as:
1539 !echo $VAR
1541 sparse
1543 sparse filename size
1544 This creates an empty sparse file of the given size, and then adds so
1546 it can be further examined.
1547 In all respects it works the same as the "alloc" command, except that
1549 the image file is allocated sparsely, which means that disk blocks are
1550 not assigned to the file until they are needed. Sparse disk files only
1551 use space when written to, but they are slower and there is a danger
1552 you could run out of real disk space during a write operation.
1553 For more advanced image creation, see "disk-create".
1555 Size can be specified using standard suffixes, eg. "1M".
1557 See also the guestfish "scratch" command.
1559 supported
1561 supported
1562 This command returns a list of the optional groups known to the daemon,
1564 and indicates which ones are supported by this build of the libguestfs
1565 appliance.
1566 See also "AVAILABILITY" in guestfs(3).
1568 time
1570 time command args...
1571 Run the command as usual, but print the elapsed time afterwards. This
1573 can be useful for benchmarking operations.
1574 unsetenv
1576 unsetenv VAR
1577 Remove "VAR" from the environment.
1579
1581 acl-delete-def-file
1582 acl-delete-def-file dir
1583 This function deletes the default POSIX Access Control List (ACL)
1585 attached to directory "dir".
1586 This command depends on the feature "acl". See also "feature-
1588 available".
1589 acl-get-file
1591 acl-get-file path acltype
1592 This function returns the POSIX Access Control List (ACL) attached to
1594 "path". The ACL is returned in "long text form" (see acl(5)).
1595 The "acltype" parameter may be:
1597 "access"
1599 Return the ordinary (access) ACL for any file, directory or other
1600 filesystem object.
1601 "default"
1603 Return the default ACL. Normally this only makes sense if "path"
1604 is a directory.
1605 This command depends on the feature "acl". See also "feature-
1607 available".
1608 acl-set-file
1610 acl-set-file path acltype acl
1611 This function sets the POSIX Access Control List (ACL) attached to
1613 "path".
1614 The "acltype" parameter may be:
1616 "access"
1618 Set the ordinary (access) ACL for any file, directory or other
1619 filesystem object.
1620 "default"
1622 Set the default ACL. Normally this only makes sense if "path" is a
1623 directory.
1624 The "acl" parameter is the new ACL in either "long text form" or "short
1626 text form" (see acl(5)). The new ACL completely replaces any previous
1627 ACL on the file. The ACL must contain the full Unix permissions (eg.
1628 "u::rwx,g::rx,o::rx").
1629 If you are specifying individual users or groups, then the mask field
1631 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1632 "g:ID:..." field(s). A full ACL string might therefore look like this:
1633 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1635 \ Unix permissions / \mask/ \ ACL /
1636 You should use numeric UIDs and GIDs. To map usernames and groupnames
1638 to the correct numeric ID in the context of the guest, use the Augeas
1639 functions (see "aug-init").
1640 This command depends on the feature "acl". See also "feature-
1642 available".
1643 add-cdrom
1645 add-cdrom filename
1646 This function adds a virtual CD-ROM disk image to the guest.
1648 The image is added as read-only drive, so this function is equivalent
1650 of "add-drive-ro".
1651 This function is deprecated. In new code, use the "add-drive-ro" call
1653 instead.
1654 Deprecated functions will not be removed from the API, but the fact
1656 that they are deprecated indicates that there are problems with correct
1657 use of these functions.
1658 add-domain
1660 domain
1661 add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]
1662 This function adds the disk(s) attached to the named libvirt domain
1664 "dom". It works by connecting to libvirt, requesting the domain and
1665 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1666 opts" on each one.
1667 The number of disks added is returned. This operation is atomic: if an
1669 error is returned, then no disks are added.
1670 This function does some minimal checks to make sure the libvirt domain
1672 is not running (unless "readonly" is true). In a future version we
1673 will try to acquire the libvirt lock on each disk.
1674 Disks must be accessible locally. This often means that adding disks
1676 from a remote libvirt connection (see https://libvirt.org/remote.html)
1677 will fail unless those disks are accessible via the same device path
1678 locally too.
1679 The optional "libvirturi" parameter sets the libvirt URI (see
1681 https://libvirt.org/uri.html). If this is not set then we connect to
1682 the default libvirt URI (or one set through an environment variable,
1683 see the libvirt documentation for full details).
1684 The optional "live" flag controls whether this call will try to connect
1686 to a running virtual machine "guestfsd" process if it sees a suitable
1687 <channel> element in the libvirt XML definition. The default (if the
1688 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1689 in guestfs(3) for more information.
1690 If the "allowuuid" flag is true (default is false) then a UUID may be
1692 passed instead of the domain name. The "dom" string is treated as a
1693 UUID first and looked up, and if that lookup fails then we treat "dom"
1694 as a name as usual.
1695 The optional "readonlydisk" parameter controls what we do for disks
1697 which are marked <readonly/> in the libvirt XML. Possible values are:
1698 readonlydisk = "error"
1700 If "readonly" is false:
1701 The whole call is aborted with an error if any disk with the
1703 <readonly/> flag is found.
1704 If "readonly" is true:
1706 Disks with the <readonly/> flag are added read-only.
1708 readonlydisk = "read"
1710 If "readonly" is false:
1711 Disks with the <readonly/> flag are added read-only. Other disks
1713 are added read/write.
1714 If "readonly" is true:
1716 Disks with the <readonly/> flag are added read-only.
1718 readonlydisk = "write" (default)
1720 If "readonly" is false:
1721 Disks with the <readonly/> flag are added read/write.
1723 If "readonly" is true:
1725 Disks with the <readonly/> flag are added read-only.
1727 readonlydisk = "ignore"
1729 If "readonly" is true or false:
1730 Disks with the <readonly/> flag are skipped.
1732 If present, the value of "logical_block_size" attribute of <blockio/>
1734 tag in libvirt XML will be passed as "blocksize" parameter to "add-
1735 drive-opts".
1736 The other optional parameters are passed directly through to "add-
1738 drive-opts".
1739 This command has one or more optional arguments. See "OPTIONAL
1741 ARGUMENTS".
1742 add-drive
1744 add
1745 add-drive-opts
1746 add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]
1747 This function adds a disk image called filename to the handle.
1749 filename may be a regular host file or a host device.
1750 When this function is called before "launch" (the usual case) then the
1752 first time you call this function, the disk appears in the API as
1753 /dev/sda, the second time as /dev/sdb, and so on.
1754 In libguestfs ≥ 1.20 you can also call this function after launch (with
1756 some restrictions). This is called "hotplugging". When hotplugging,
1757 you must specify a "label" so that the new disk gets a predictable
1758 name. For more information see "HOTPLUGGING" in guestfs(3).
1759 You don't necessarily need to be root when using libguestfs. However
1761 you obviously do need sufficient permissions to access the filename for
1762 whatever operations you want to perform (ie. read access if you just
1763 want to read the image or write access if you want to modify the
1764 image).
1765 This call checks that filename exists.
1767 filename may be the special string "/dev/null". See "NULL DISKS" in
1769 guestfs(3).
1770 The optional arguments are:
1772 "readonly"
1774 If true then the image is treated as read-only. Writes are still
1775 allowed, but they are stored in a temporary snapshot overlay which
1776 is discarded at the end. The disk that you add is not modified.
1777 "format"
1779 This forces the image format. If you omit this (or use "add-drive"
1780 or "add-drive-ro") then the format is automatically detected.
1781 Possible formats include "raw" and "qcow2".
1782 Automatic detection of the format opens you up to a potential
1784 security hole when dealing with untrusted raw-format images. See
1785 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1786 security hole.
1787 "iface"
1789 This rarely-used option lets you emulate the behaviour of the
1790 deprecated "add-drive-with-if" call (q.v.)
1791 "name"
1793 The name the drive had in the original guest, e.g. /dev/sdb. This
1794 is used as a hint to the guest inspection process if it is
1795 available.
1796 "label"
1798 Give the disk a label. The label should be a unique, short string
1799 using only ASCII characters "[a-zA-Z]". As well as its usual name
1800 in the API (such as /dev/sda), the drive will also be named
1801 /dev/disk/guestfs/label.
1802 See "DISK LABELS" in guestfs(3).
1804 "protocol"
1806 The optional protocol argument can be used to select an alternate
1807 source protocol.
1808 See also: "REMOTE STORAGE" in guestfs(3).
1810 "protocol = "file""
1812 filename is interpreted as a local file or device. This is the
1813 default if the optional protocol parameter is omitted.
1814 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
1816 Connect to a remote FTP, HTTP or TFTP server. The "server"
1817 parameter must also be supplied - see below.
1818 See also: "FTP, HTTP AND TFTP" in guestfs(3)
1820 "protocol = "gluster""
1822 Connect to the GlusterFS server. The "server" parameter must
1823 also be supplied - see below.
1824 See also: "GLUSTER" in guestfs(3)
1826 "protocol = "iscsi""
1828 Connect to the iSCSI server. The "server" parameter must also
1829 be supplied - see below. The "username" parameter may be
1830 supplied. See below. The "secret" parameter may be supplied.
1831 See below.
1832 See also: "ISCSI" in guestfs(3).
1834 "protocol = "nbd""
1836 Connect to the Network Block Device server. The "server"
1837 parameter must also be supplied - see below.
1838 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
1840 "protocol = "rbd""
1842 Connect to the Ceph (librbd/RBD) server. The "server"
1843 parameter must also be supplied - see below. The "username"
1844 parameter may be supplied. See below. The "secret" parameter
1845 may be supplied. See below.
1846 See also: "CEPH" in guestfs(3).
1848 "protocol = "sheepdog""
1850 Connect to the Sheepdog server. The "server" parameter may
1851 also be supplied - see below.
1852 See also: "SHEEPDOG" in guestfs(3).
1854 "protocol = "ssh""
1856 Connect to the Secure Shell (ssh) server.
1857 The "server" parameter must be supplied. The "username"
1859 parameter may be supplied. See below.
1860 See also: "SSH" in guestfs(3).
1862 "server"
1864 For protocols which require access to a remote server, this is a
1865 list of server(s).
1866 Protocol Number of servers required
1868 -------- --------------------------
1869 file List must be empty or param not used at all
1870 ftp|ftps|http|https|tftp Exactly one
1871 gluster Exactly one
1872 iscsi Exactly one
1873 nbd Exactly one
1874 rbd Zero or more
1875 sheepdog Zero or more
1876 ssh Exactly one
1877 Each list element is a string specifying a server. The string must
1879 be in one of the following formats:
1880 hostname
1882 hostname:port
1883 tcp:hostname
1884 tcp:hostname:port
1885 unix:/path/to/socket
1886 If the port number is omitted, then the standard port number for
1888 the protocol is used (see /etc/services).
1889 "username"
1891 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
1892 "tftp" protocols, this specifies the remote username.
1893 If not given, then the local username is used for "ssh", and no
1895 authentication is attempted for ceph. But note this sometimes may
1896 give unexpected results, for example if using the libvirt backend
1897 and if the libvirt backend is configured to start the qemu
1898 appliance as a special user such as "qemu.qemu". If in doubt,
1899 specify the remote username you want.
1900 "secret"
1902 For the "rbd" protocol only, this specifies the ‘secret’ to use
1903 when connecting to the remote device. It must be base64 encoded.
1904 If not given, then a secret matching the given username will be
1906 looked up in the default keychain locations, or if no username is
1907 given, then no authentication will be used.
1908 "cachemode"
1910 Choose whether or not libguestfs will obey sync operations (safe
1911 but slow) or not (unsafe but fast). The possible values for this
1912 string are:
1913 "cachemode = "writeback""
1915 This is the default.
1916 Write operations in the API do not return until a write(2) call
1918 has completed in the host [but note this does not imply that
1919 anything gets written to disk].
1920 Sync operations in the API, including implicit syncs caused by
1922 filesystem journalling, will not return until an fdatasync(2)
1923 call has completed in the host, indicating that data has been
1924 committed to disk.
1925 "cachemode = "unsafe""
1927 In this mode, there are no guarantees. Libguestfs may cache
1928 anything and ignore sync requests. This is suitable only for
1929 scratch or temporary disks.
1930 "discard"
1932 Enable or disable discard (a.k.a. trim or unmap) support on this
1933 drive. If enabled, operations such as "fstrim" will be able to
1934 discard / make thin / punch holes in the underlying host file or
1935 device.
1936 Possible discard settings are:
1938 "discard = "disable""
1940 Disable discard support. This is the default.
1941 "discard = "enable""
1943 Enable discard support. Fail if discard is not possible.
1944 "discard = "besteffort""
1946 Enable discard support if possible, but don't fail if it is not
1947 supported.
1948 Since not all backends and not all underlying systems support
1950 discard, this is a good choice if you want to use discard if
1951 possible, but don't mind if it doesn't work.
1952 "copyonread"
1954 The boolean parameter "copyonread" enables copy-on-read support.
1955 This only affects disk formats which have backing files, and causes
1956 reads to be stored in the overlay layer, speeding up multiple reads
1957 of the same area of disk.
1958 The default is false.
1960 "blocksize"
1962 This parameter sets the sector size of the disk. Possible values
1963 are 512 (the default if the parameter is omitted) or 4096. Use
1964 4096 when handling an "Advanced Format" disk that uses 4K sector
1965 size (https://en.wikipedia.org/wiki/Advanced_Format).
1966 Only a subset of the backends support this parameter (currently
1968 only the libvirt and direct backends do).
1969 This command has one or more optional arguments. See "OPTIONAL
1971 ARGUMENTS".
1972 add-drive-ro
1974 add-ro
1975 add-drive-ro filename
1976 This function is the equivalent of calling "add-drive-opts" with the
1978 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1979 disk is added read-only, with the format being detected automatically.
1980 add-drive-ro-with-if
1982 add-drive-ro-with-if filename iface
1983 This is the same as "add-drive-ro" but it allows you to specify the
1985 QEMU interface emulation to use at run time.
1986 This function is deprecated. In new code, use the "add-drive" call
1988 instead.
1989 Deprecated functions will not be removed from the API, but the fact
1991 that they are deprecated indicates that there are problems with correct
1992 use of these functions.
1993 add-drive-scratch
1995 scratch
1996 add-drive-scratch size [name:..] [label:..] [blocksize:N]
1997 This command adds a temporary scratch drive to the handle. The "size"
1999 parameter is the virtual size (in bytes). The scratch drive is blank
2000 initially (all reads return zeroes until you start writing to it). The
2001 drive is deleted when the handle is closed.
2002 The optional arguments "name", "label" and "blocksize" are passed
2004 through to "add-drive-opts".
2005 This command has one or more optional arguments. See "OPTIONAL
2007 ARGUMENTS".
2008 add-drive-with-if
2010 add-drive-with-if filename iface
2011 This is the same as "add-drive" but it allows you to specify the QEMU
2013 interface emulation to use at run time.
2014 This function is deprecated. In new code, use the "add-drive" call
2016 instead.
2017 Deprecated functions will not be removed from the API, but the fact
2019 that they are deprecated indicates that there are problems with correct
2020 use of these functions.
2021 aug-clear
2023 aug-clear augpath
2024 Set the value associated with "path" to "NULL". This is the same as
2026 the augtool(1) "clear" command.
2027 aug-close
2029 aug-close
2030 Close the current Augeas handle and free up any resources used by it.
2032 After calling this, you have to call "aug-init" again before you can
2033 use any other Augeas functions.
2034 aug-defnode
2036 aug-defnode name expr val
2037 Defines a variable "name" whose value is the result of evaluating
2039 "expr".
2040 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2042 to calling "aug-set" "expr", "val". "name" will be the nodeset
2043 containing that single node.
2044 On success this returns a pair containing the number of nodes in the
2046 nodeset, and a boolean flag if a node was created.
2047 aug-defvar
2049 aug-defvar name expr
2050 Defines an Augeas variable "name" whose value is the result of
2052 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2053 On success this returns the number of nodes in "expr", or 0 if "expr"
2055 evaluates to something which is not a nodeset.
2056 aug-get
2058 aug-get augpath
2059 Look up the value associated with "path". If "path" matches exactly
2061 one node, the "value" is returned.
2062 aug-init
2064 aug-init root flags
2065 Create a new Augeas handle for editing configuration files. If there
2067 was any previous Augeas handle associated with this guestfs session,
2068 then it is closed.
2069 You must call this before using any other "aug-*" commands.
2071 "root" is the filesystem root. "root" must not be NULL, use / instead.
2073 The flags are the same as the flags defined in <augeas.h>, the logical
2075 or of the following integers:
2076 "AUG_SAVE_BACKUP" = 1
2078 Keep the original file with a ".augsave" extension.
2079 "AUG_SAVE_NEWFILE" = 2
2081 Save changes into a file with extension ".augnew", and do not
2082 overwrite original. Overrides "AUG_SAVE_BACKUP".
2083 "AUG_TYPE_CHECK" = 4
2085 Typecheck lenses.
2086 This option is only useful when debugging Augeas lenses. Use of
2088 this option may require additional memory for the libguestfs
2089 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2090 environment variable or call "set-memsize".
2091 "AUG_NO_STDINC" = 8
2093 Do not use standard load path for modules.
2094 "AUG_SAVE_NOOP" = 16
2096 Make save a no-op, just record what would have been changed.
2097 "AUG_NO_LOAD" = 32
2099 Do not load the tree in "aug-init".
2100 To close the handle, you can call "aug-close".
2102 To find out more about Augeas, see http://augeas.net/.
2104 aug-insert
2106 aug-insert augpath label true|false
2107 Create a new sibling "label" for "path", inserting it into the tree
2109 before or after "path" (depending on the boolean flag "before").
2110 "path" must match exactly one existing node in the tree, and "label"
2112 must be a label, ie. not contain /, "*" or end with a bracketed index
2113 "[N]".
2114 aug-label
2116 aug-label augpath
2117 The label (name of the last element) of the Augeas path expression
2119 "augpath" is returned. "augpath" must match exactly one node, else
2120 this function returns an error.
2121 aug-load
2123 aug-load
2124 Load files into the tree.
2126 See "aug_load" in the Augeas documentation for the full gory details.
2128 aug-ls
2130 aug-ls augpath
2131 This is just a shortcut for listing "aug-match" "path/*" and sorting
2133 the resulting nodes into alphabetical order.
2134 aug-match
2136 aug-match augpath
2137 Returns a list of paths which match the path expression "path". The
2139 returned paths are sufficiently qualified so that they match exactly
2140 one node in the current tree.
2141 aug-mv
2143 aug-mv src dest
2144 Move the node "src" to "dest". "src" must match exactly one node.
2146 "dest" is overwritten if it exists.
2147 aug-rm
2149 aug-rm augpath
2150 Remove "path" and all of its children.
2152 On success this returns the number of entries which were removed.
2154 aug-save
2156 aug-save
2157 This writes all pending changes to disk.
2159 The flags which were passed to "aug-init" affect exactly how files are
2161 saved.
2162 aug-set
2164 aug-set augpath val
2165 Set the value associated with "augpath" to "val".
2167 In the Augeas API, it is possible to clear a node by setting the value
2169 to NULL. Due to an oversight in the libguestfs API you cannot do that
2170 with this call. Instead you must use the "aug-clear" call.
2171 aug-setm
2173 aug-setm base sub val
2174 Change multiple Augeas nodes in a single operation. "base" is an
2176 expression matching multiple nodes. "sub" is a path expression
2177 relative to "base". All nodes matching "base" are found, and then for
2178 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2179 which case the "base" nodes are modified.
2180 This returns the number of nodes modified.
2182 aug-transform
2184 aug-transform lens file [remove:true|false]
2185 Add an Augeas transformation for the specified "lens" so it can handle
2187 "file".
2188 If "remove" is true ("false" by default), then the transformation is
2190 removed.
2191 This command has one or more optional arguments. See "OPTIONAL
2193 ARGUMENTS".
2194 available
2196 available 'groups ...'
2197 This command is used to check the availability of some groups of
2199 functionality in the appliance, which not all builds of the libguestfs
2200 appliance will be able to provide.
2201 The libguestfs groups, and the functions that those groups correspond
2203 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
2204 this list at runtime by calling "available-all-groups".
2205 The argument "groups" is a list of group names, eg: "["inotify",
2207 "augeas"]" would check for the availability of the Linux inotify
2208 functions and Augeas (configuration file editing) functions.
2209 The command returns no error if all requested groups are available.
2211 It fails with an error if one or more of the requested groups is
2213 unavailable in the appliance.
2214 If an unknown group name is included in the list of groups then an
2216 error is always returned.
2217 Notes:
2219 • "feature-available" is the same as this call, but with a slightly
2221 simpler to use API: that call returns a boolean true/false instead
2222 of throwing an error.
2223 • You must call "launch" before calling this function.
2225 The reason is because we don't know what groups are supported by
2227 the appliance/daemon until it is running and can be queried.
2228 • If a group of functions is available, this does not necessarily
2230 mean that they will work. You still have to check for errors when
2231 calling individual API functions even if they are available.
2232 • It is usually the job of distro packagers to build complete
2234 functionality into the libguestfs appliance. Upstream libguestfs,
2235 if built from source with all requirements satisfied, will support
2236 everything.
2237 • This call was added in version 1.0.80. In previous versions of
2239 libguestfs all you could do would be to speculatively execute a
2240 command to find out if the daemon implemented it. See also
2241 "version".
2242 See also "filesystem-available".
2244 available-all-groups
2246 available-all-groups
2247 This command returns a list of all optional groups that this daemon
2249 knows about. Note this returns both supported and unsupported groups.
2250 To find out which ones the daemon can actually support you have to call
2251 "available" / "feature-available" on each member of the returned list.
2252 See also "available", "feature-available" and "AVAILABILITY" in
2254 guestfs(3).
2255 base64-in
2257 base64-in (base64file|-) filename
2258 This command uploads base64-encoded data from "base64file" to filename.
2260 Use "-" instead of a filename to read/write from stdin/stdout.
2262 base64-out
2264 base64-out filename (base64file|-)
2265 This command downloads the contents of filename, writing it out to
2267 local file "base64file" encoded as base64.
2268 Use "-" instead of a filename to read/write from stdin/stdout.
2270 blkdiscard
2272 blkdiscard device
2273 This discards all blocks on the block device "device", giving the free
2275 space back to the host.
2276 This operation requires support in libguestfs, the host filesystem,
2278 qemu and the host kernel. If this support isn't present it may give an
2279 error or even appear to run but do nothing. You must also set the
2280 "discard" attribute on the underlying drive (see "add-drive-opts").
2281 This command depends on the feature "blkdiscard". See also "feature-
2283 available".
2284 blkdiscardzeroes
2286 blkdiscardzeroes device
2287 This call returns true if blocks on "device" that have been discarded
2289 by a call to "blkdiscard" are returned as blocks of zero bytes when
2290 read the next time.
2291 If it returns false, then it may be that discarded blocks are read as
2293 stale or random data.
2294 This command depends on the feature "blkdiscardzeroes". See also
2296 "feature-available".
2297 blkid
2299 blkid device
2300 This command returns block device attributes for "device". The
2302 following fields are usually present in the returned hash. Other fields
2303 may also be present.
2304 "UUID"
2306 The uuid of this device.
2307 "LABEL"
2309 The label of this device.
2310 "VERSION"
2312 The version of blkid command.
2313 "TYPE"
2315 The filesystem type or RAID of this device.
2316 "USAGE"
2318 The usage of this device, for example "filesystem" or "raid".
2319 blockdev-flushbufs
2321 blockdev-flushbufs device
2322 This tells the kernel to flush internal buffers associated with
2324 "device".
2325 This uses the blockdev(8) command.
2327 blockdev-getbsz
2329 blockdev-getbsz device
2330 This returns the block size of a device.
2332 Note: this is different from both size in blocks and filesystem block
2334 size. Also this setting is not really used by anything. You should
2335 probably not use it for anything. Filesystems have their own idea
2336 about what block size to choose.
2337 This uses the blockdev(8) command.
2339 blockdev-getro
2341 blockdev-getro device
2342 Returns a boolean indicating if the block device is read-only (true if
2344 read-only, false if not).
2345 This uses the blockdev(8) command.
2347 blockdev-getsize64
2349 blockdev-getsize64 device
2350 This returns the size of the device in bytes.
2352 See also "blockdev-getsz".
2354 This uses the blockdev(8) command.
2356 blockdev-getss
2358 blockdev-getss device
2359 This returns the size of sectors on a block device. Usually 512, but
2361 can be larger for modern devices.
2362 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
2364 This uses the blockdev(8) command.
2366 blockdev-getsz
2368 blockdev-getsz device
2369 This returns the size of the device in units of 512-byte sectors (even
2371 if the sectorsize isn't 512 bytes ... weird).
2372 See also "blockdev-getss" for the real sector size of the device, and
2374 "blockdev-getsize64" for the more useful size in bytes.
2375 This uses the blockdev(8) command.
2377 blockdev-rereadpt
2379 blockdev-rereadpt device
2380 Reread the partition table on "device".
2382 This uses the blockdev(8) command.
2384 blockdev-setbsz
2386 blockdev-setbsz device blocksize
2387 This call does nothing and has never done anything because of a bug in
2389 blockdev. Do not use it.
2390 If you need to set the filesystem block size, use the "blocksize"
2392 option of "mkfs".
2393 This function is deprecated. There is no replacement. Consult the API
2395 documentation in guestfs(3) for further information.
2396 Deprecated functions will not be removed from the API, but the fact
2398 that they are deprecated indicates that there are problems with correct
2399 use of these functions.
2400 blockdev-setra
2402 blockdev-setra device sectors
2403 Set readahead (in 512-byte sectors) for the device.
2405 This uses the blockdev(8) command.
2407 blockdev-setro
2409 blockdev-setro device
2410 Sets the block device named "device" to read-only.
2412 This uses the blockdev(8) command.
2414 blockdev-setrw
2416 blockdev-setrw device
2417 Sets the block device named "device" to read-write.
2419 This uses the blockdev(8) command.
2421 btrfs-balance-cancel
2423 btrfs-balance-cancel path
2424 Cancel a running balance on a btrfs filesystem.
2426 This command depends on the feature "btrfs". See also "feature-
2428 available".
2429 btrfs-balance-pause
2431 btrfs-balance-pause path
2432 Pause a running balance on a btrfs filesystem.
2434 This command depends on the feature "btrfs". See also "feature-
2436 available".
2437 btrfs-balance-resume
2439 btrfs-balance-resume path
2440 Resume a paused balance on a btrfs filesystem.
2442 This command depends on the feature "btrfs". See also "feature-
2444 available".
2445 btrfs-balance-status
2447 btrfs-balance-status path
2448 Show the status of a running or paused balance on a btrfs filesystem.
2450 This command depends on the feature "btrfs". See also "feature-
2452 available".
2453 btrfs-device-add
2455 btrfs-device-add 'devices ...' fs
2456 Add the list of device(s) in "devices" to the btrfs filesystem mounted
2458 at "fs". If "devices" is an empty list, this does nothing.
2459 This command depends on the feature "btrfs". See also "feature-
2461 available".
2462 btrfs-device-delete
2464 btrfs-device-delete 'devices ...' fs
2465 Remove the "devices" from the btrfs filesystem mounted at "fs". If
2467 "devices" is an empty list, this does nothing.
2468 This command depends on the feature "btrfs". See also "feature-
2470 available".
2471 btrfs-filesystem-balance
2473 btrfs-balance
2474 btrfs-filesystem-balance fs
2475 Balance the chunks in the btrfs filesystem mounted at "fs" across the
2477 underlying devices.
2478 This command depends on the feature "btrfs". See also "feature-
2480 available".
2481 btrfs-filesystem-defragment
2483 btrfs-filesystem-defragment path [flush:true|false] [compress:..]
2484 Defragment a file or directory on a btrfs filesystem. compress is one
2486 of zlib or lzo.
2487 This command has one or more optional arguments. See "OPTIONAL
2489 ARGUMENTS".
2490 This command depends on the feature "btrfs". See also "feature-
2492 available".
2493 btrfs-filesystem-resize
2495 btrfs-filesystem-resize mountpoint [size:N]
2496 This command resizes a btrfs filesystem.
2498 Note that unlike other resize calls, the filesystem has to be mounted
2500 and the parameter is the mountpoint not the device (this is a
2501 requirement of btrfs itself).
2502 The optional parameters are:
2504 "size"
2506 The new size (in bytes) of the filesystem. If omitted, the
2507 filesystem is resized to the maximum size.
2508 See also btrfs(8).
2510 This command has one or more optional arguments. See "OPTIONAL
2512 ARGUMENTS".
2513 This command depends on the feature "btrfs". See also "feature-
2515 available".
2516 btrfs-filesystem-show
2518 btrfs-filesystem-show device
2519 Show all the devices where the filesystems in "device" is spanned over.
2521 If not all the devices for the filesystems are present, then this
2523 function fails and the "errno" is set to "ENODEV".
2524 This command depends on the feature "btrfs". See also "feature-
2526 available".
2527 btrfs-filesystem-sync
2529 btrfs-filesystem-sync fs
2530 Force sync on the btrfs filesystem mounted at "fs".
2532 This command depends on the feature "btrfs". See also "feature-
2534 available".
2535 btrfs-fsck
2537 btrfs-fsck device [superblock:N] [repair:true|false]
2538 Used to check a btrfs filesystem, "device" is the device file where the
2540 filesystem is stored.
2541 This command has one or more optional arguments. See "OPTIONAL
2543 ARGUMENTS".
2544 This command depends on the feature "btrfs". See also "feature-
2546 available".
2547 btrfs-image
2549 btrfs-image 'source ...' image [compresslevel:N]
2550 This is used to create an image of a btrfs filesystem. All data will
2552 be zeroed, but metadata and the like is preserved.
2553 This command has one or more optional arguments. See "OPTIONAL
2555 ARGUMENTS".
2556 This command depends on the feature "btrfs". See also "feature-
2558 available".
2559 btrfs-qgroup-assign
2561 btrfs-qgroup-assign src dst path
2562 Add qgroup "src" to parent qgroup "dst". This command can group several
2564 qgroups into a parent qgroup to share common limit.
2565 This command depends on the feature "btrfs". See also "feature-
2567 available".
2568 btrfs-qgroup-create
2570 btrfs-qgroup-create qgroupid subvolume
2571 Create a quota group (qgroup) for subvolume at "subvolume".
2573 This command depends on the feature "btrfs". See also "feature-
2575 available".
2576 btrfs-qgroup-destroy
2578 btrfs-qgroup-destroy qgroupid subvolume
2579 Destroy a quota group.
2581 This command depends on the feature "btrfs". See also "feature-
2583 available".
2584 btrfs-qgroup-limit
2586 btrfs-qgroup-limit subvolume size
2587 Limit the size of the subvolume with path "subvolume".
2589 This command depends on the feature "btrfs". See also "feature-
2591 available".
2592 btrfs-qgroup-remove
2594 btrfs-qgroup-remove src dst path
2595 Remove qgroup "src" from the parent qgroup "dst".
2597 This command depends on the feature "btrfs". See also "feature-
2599 available".
2600 btrfs-qgroup-show
2602 btrfs-qgroup-show path
2603 Show all subvolume quota groups in a btrfs filesystem, including their
2605 usages.
2606 This command depends on the feature "btrfs". See also "feature-
2608 available".
2609 btrfs-quota-enable
2611 btrfs-quota-enable fs true|false
2612 Enable or disable subvolume quota support for filesystem which contains
2614 "path".
2615 This command depends on the feature "btrfs". See also "feature-
2617 available".
2618 btrfs-quota-rescan
2620 btrfs-quota-rescan fs
2621 Trash all qgroup numbers and scan the metadata again with the current
2623 config.
2624 This command depends on the feature "btrfs". See also "feature-
2626 available".
2627 btrfs-replace
2629 btrfs-replace srcdev targetdev mntpoint
2630 Replace device of a btrfs filesystem. On a live filesystem, duplicate
2632 the data to the target device which is currently stored on the source
2633 device. After completion of the operation, the source device is wiped
2634 out and removed from the filesystem.
2635 The "targetdev" needs to be same size or larger than the "srcdev".
2637 Devices which are currently mounted are never allowed to be used as the
2638 "targetdev".
2639 This command depends on the feature "btrfs". See also "feature-
2641 available".
2642 btrfs-rescue-chunk-recover
2644 btrfs-rescue-chunk-recover device
2645 Recover the chunk tree of btrfs filesystem by scanning the devices one
2647 by one.
2648 This command depends on the feature "btrfs". See also "feature-
2650 available".
2651 btrfs-rescue-super-recover
2653 btrfs-rescue-super-recover device
2654 Recover bad superblocks from good copies.
2656 This command depends on the feature "btrfs". See also "feature-
2658 available".
2659 btrfs-scrub-cancel
2661 btrfs-scrub-cancel path
2662 Cancel a running scrub on a btrfs filesystem.
2664 This command depends on the feature "btrfs". See also "feature-
2666 available".
2667 btrfs-scrub-resume
2669 btrfs-scrub-resume path
2670 Resume a previously canceled or interrupted scrub on a btrfs
2672 filesystem.
2673 This command depends on the feature "btrfs". See also "feature-
2675 available".
2676 btrfs-scrub-start
2678 btrfs-scrub-start path
2679 Reads all the data and metadata on the filesystem, and uses checksums
2681 and the duplicate copies from RAID storage to identify and repair any
2682 corrupt data.
2683 This command depends on the feature "btrfs". See also "feature-
2685 available".
2686 btrfs-scrub-status
2688 btrfs-scrub-status path
2689 Show status of running or finished scrub on a btrfs filesystem.
2691 This command depends on the feature "btrfs". See also "feature-
2693 available".
2694 btrfs-set-seeding
2696 btrfs-set-seeding device true|false
2697 Enable or disable the seeding feature of a device that contains a btrfs
2699 filesystem.
2700 This command depends on the feature "btrfs". See also "feature-
2702 available".
2703 btrfs-subvolume-create
2705 btrfs-subvolume-create-opts
2706 btrfs-subvolume-create dest [qgroupid:..]
2707 Create a btrfs subvolume. The "dest" argument is the destination
2709 directory and the name of the subvolume, in the form
2710 /path/to/dest/name. The optional parameter "qgroupid" represents the
2711 qgroup which the newly created subvolume will be added to.
2712 This command has one or more optional arguments. See "OPTIONAL
2714 ARGUMENTS".
2715 This command depends on the feature "btrfs". See also "feature-
2717 available".
2718 btrfs-subvolume-delete
2720 btrfs-subvolume-delete subvolume
2721 Delete the named btrfs subvolume or snapshot.
2723 This command depends on the feature "btrfs". See also "feature-
2725 available".
2726 btrfs-subvolume-get-default
2728 btrfs-subvolume-get-default fs
2729 Get the default subvolume or snapshot of a filesystem mounted at
2731 "mountpoint".
2732 This command depends on the feature "btrfs". See also "feature-
2734 available".
2735 btrfs-subvolume-list
2737 btrfs-subvolume-list fs
2738 List the btrfs snapshots and subvolumes of the btrfs filesystem which
2740 is mounted at "fs".
2741 This command depends on the feature "btrfs". See also "feature-
2743 available".
2744 btrfs-subvolume-set-default
2746 btrfs-subvolume-set-default id fs
2747 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2749 default. See "btrfs-subvolume-list" to get a list of subvolumes.
2750 This command depends on the feature "btrfs". See also "feature-
2752 available".
2753 btrfs-subvolume-show
2755 btrfs-subvolume-show subvolume
2756 Return detailed information of the subvolume.
2758 This command depends on the feature "btrfs". See also "feature-
2760 available".
2761 btrfs-subvolume-snapshot
2763 btrfs-subvolume-snapshot-opts
2764 btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]
2765 Create a snapshot of the btrfs subvolume "source". The "dest" argument
2767 is the destination directory and the name of the snapshot, in the form
2768 /path/to/dest/name. By default the newly created snapshot is writable,
2769 if the value of optional parameter "ro" is true, then a readonly
2770 snapshot is created. The optional parameter "qgroupid" represents the
2771 qgroup which the newly created snapshot will be added to.
2772 This command has one or more optional arguments. See "OPTIONAL
2774 ARGUMENTS".
2775 This command depends on the feature "btrfs". See also "feature-
2777 available".
2778 btrfstune-enable-extended-inode-refs
2780 btrfstune-enable-extended-inode-refs device
2781 This will Enable extended inode refs.
2783 This command depends on the feature "btrfs". See also "feature-
2785 available".
2786 btrfstune-enable-skinny-metadata-extent-refs
2788 btrfstune-enable-skinny-metadata-extent-refs device
2789 This enable skinny metadata extent refs.
2791 This command depends on the feature "btrfs". See also "feature-
2793 available".
2794 btrfstune-seeding
2796 btrfstune-seeding device true|false
2797 Enable seeding of a btrfs device, this will force a fs readonly so that
2799 you can use it to build other filesystems.
2800 This command depends on the feature "btrfs". See also "feature-
2802 available".
2803 c-pointer
2805 c-pointer
2806 In non-C language bindings, this allows you to retrieve the underlying
2808 C pointer to the handle (ie. "h *"). The purpose of this is to allow
2809 other libraries to interwork with libguestfs.
2810 canonical-device-name
2812 canonical-device-name device
2813 This utility function is useful when displaying device names to the
2815 user. It takes a number of irregular device names and returns them in
2816 a consistent format:
2817 /dev/hdX
2819 /dev/vdX
2820 These are returned as /dev/sdX. Note this works for device names
2821 and partition names. This is approximately the reverse of the
2822 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2823 /dev/mapper/VG-LV
2825 /dev/dm-N
2826 Converted to /dev/VG/LV form using "lvm-canonical-lv-name".
2827 Other strings are returned unmodified.
2829 cap-get-file
2831 cap-get-file path
2832 This function returns the Linux capabilities attached to "path". The
2834 capabilities set is returned in text form (see cap_to_text(3)).
2835 If no capabilities are attached to a file, an empty string is returned.
2837 This command depends on the feature "linuxcaps". See also "feature-
2839 available".
2840 cap-set-file
2842 cap-set-file path cap
2843 This function sets the Linux capabilities attached to "path". The
2845 capabilities set "cap" should be passed in text form (see
2846 cap_from_text(3)).
2847 This command depends on the feature "linuxcaps". See also "feature-
2849 available".
2850 case-sensitive-path
2852 case-sensitive-path path
2853 This can be used to resolve case insensitive paths on a filesystem
2855 which is case sensitive. The use case is to resolve paths which you
2856 have read from Windows configuration files or the Windows Registry, to
2857 the true path.
2858 The command handles a peculiarity of the Linux ntfs-3g filesystem
2860 driver (and probably others), which is that although the underlying
2861 filesystem is case-insensitive, the driver exports the filesystem to
2862 Linux as case-sensitive.
2863 One consequence of this is that special directories such as C:\windows
2865 may appear as /WINDOWS or /windows (or other things) depending on the
2866 precise details of how they were created. In Windows itself this would
2867 not be a problem.
2868 Bug or feature? You decide:
2870 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2871 "case-sensitive-path" attempts to resolve the true case of each element
2873 in the path. It will return a resolved path if either the full path or
2874 its parent directory exists. If the parent directory exists but the
2875 full path does not, the case of the parent directory will be correctly
2876 resolved, and the remainder appended unmodified. For example, if the
2877 file "/Windows/System32/netkvm.sys" exists:
2878 "case-sensitive-path" ("/windows/system32/netkvm.sys")
2880 "Windows/System32/netkvm.sys"
2881 "case-sensitive-path" ("/windows/system32/NoSuchFile")
2883 "Windows/System32/NoSuchFile"
2884 "case-sensitive-path" ("/windows/system33/netkvm.sys")
2886 ERROR
2887 Note: Because of the above behaviour, "case-sensitive-path" cannot be
2889 used to check for the existence of a file.
2890 Note: This function does not handle drive names, backslashes etc.
2892 See also "realpath".
2894 cat
2896 cat path
2897 Return the contents of the file named "path".
2899 Because, in C, this function returns a "char *", there is no way to
2901 differentiate between a "\0" character in a file and end of string. To
2902 handle binary files, use the "read-file" or "download" functions.
2903 checksum
2905 checksum csumtype path
2906 This call computes the MD5, SHAx or CRC checksum of the file named
2908 "path".
2909 The type of checksum to compute is given by the "csumtype" parameter
2911 which must have one of the following values:
2912 "crc"
2914 Compute the cyclic redundancy check (CRC) specified by POSIX for
2915 the "cksum" command.
2916 "md5"
2918 Compute the MD5 hash (using the md5sum(1) program).
2919 "sha1"
2921 Compute the SHA1 hash (using the sha1sum(1) program).
2922 "sha224"
2924 Compute the SHA224 hash (using the sha224sum(1) program).
2925 "sha256"
2927 Compute the SHA256 hash (using the sha256sum(1) program).
2928 "sha384"
2930 Compute the SHA384 hash (using the sha384sum(1) program).
2931 "sha512"
2933 Compute the SHA512 hash (using the sha512sum(1) program).
2934 The checksum is returned as a printable string.
2936 To get the checksum for a device, use "checksum-device".
2938 To get the checksums for many files, use "checksums-out".
2940 checksum-device
2942 checksum-device csumtype device
2943 This call computes the MD5, SHAx or CRC checksum of the contents of the
2945 device named "device". For the types of checksums supported see the
2946 "checksum" command.
2947 checksums-out
2949 checksums-out csumtype directory (sumsfile|-)
2950 This command computes the checksums of all regular files in directory
2952 and then emits a list of those checksums to the local output file
2953 "sumsfile".
2954 This can be used for verifying the integrity of a virtual machine.
2956 However to be properly secure you should pay attention to the output of
2957 the checksum command (it uses the ones from GNU coreutils). In
2958 particular when the filename is not printable, coreutils uses a special
2959 backslash syntax. For more information, see the GNU coreutils info
2960 file.
2961 Use "-" instead of a filename to read/write from stdin/stdout.
2963 chmod
2965 chmod mode path
2966 Change the mode (permissions) of "path" to "mode". Only numeric modes
2968 are supported.
2969 Note: When using this command from guestfish, "mode" by default would
2971 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2972 700.
2973 The mode actually set is affected by the umask.
2975 chown
2977 chown owner group path
2978 Change the file owner to "owner" and group to "group".
2980 Only numeric uid and gid are supported. If you want to use names, you
2982 will need to locate and parse the password file yourself (Augeas
2983 support makes this relatively easy).
2984 clear-backend-setting
2986 clear-backend-setting name
2987 If there is a backend setting string matching "name" or beginning with
2989 "name=", then that string is removed from the backend settings.
2990 This call returns the number of strings which were removed (which may
2992 be 0, 1 or greater than 1).
2993 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2995 command
2997 command 'arguments ...'
2998 This call runs a command from the guest filesystem. The filesystem
3000 must be mounted, and must contain a compatible operating system (ie.
3001 something Linux, with the same or compatible processor architecture).
3002 The single parameter is an argv-style list of arguments. The first
3004 element is the name of the program to run. Subsequent elements are
3005 parameters. The list must be non-empty (ie. must contain a program
3006 name). Note that the command runs directly, and is not invoked via the
3007 shell (see "sh").
3008 The return value is anything printed to stdout by the command.
3010 If the command returns a non-zero exit status, then this function
3012 returns an error message. The error message string is the content of
3013 stderr from the command.
3014 The $PATH environment variable will contain at least /usr/bin and /bin.
3016 If you require a program from another location, you should provide the
3017 full path in the first parameter.
3018 Shared libraries and data files required by the program must be
3020 available on filesystems which are mounted in the correct places. It
3021 is the caller’s responsibility to ensure all filesystems that are
3022 needed are mounted at the right locations.
3023 Because of the message protocol, there is a transfer limit of somewhere
3025 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3026 command-lines
3028 command-lines 'arguments ...'
3029 This is the same as "command", but splits the result into a list of
3031 lines.
3032 See also: "sh-lines"
3034 Because of the message protocol, there is a transfer limit of somewhere
3036 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3037 compress-device-out
3039 compress-device-out ctype device (zdevice|-) [level:N]
3040 This command compresses "device" and writes it out to the local file
3042 "zdevice".
3043 The "ctype" and optional "level" parameters have the same meaning as in
3045 "compress-out".
3046 Use "-" instead of a filename to read/write from stdin/stdout.
3048 This command has one or more optional arguments. See "OPTIONAL
3050 ARGUMENTS".
3051 compress-out
3053 compress-out ctype file (zfile|-) [level:N]
3054 This command compresses file and writes it out to the local file zfile.
3056 The compression program used is controlled by the "ctype" parameter.
3058 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3059 Some compression types may not be supported by particular builds of
3060 libguestfs, in which case you will get an error containing the
3061 substring "not supported".
3062 The optional "level" parameter controls compression level. The meaning
3064 and default for this parameter depends on the compression program being
3065 used.
3066 Use "-" instead of a filename to read/write from stdin/stdout.
3068 This command has one or more optional arguments. See "OPTIONAL
3070 ARGUMENTS".
3071 config
3073 config hvparam hvvalue
3074 This can be used to add arbitrary hypervisor parameters of the form
3076 -param value. Actually it’s not quite arbitrary - we prevent you from
3077 setting some parameters which would interfere with parameters that we
3078 use.
3079 The first character of "hvparam" string must be a "-" (dash).
3081 "hvvalue" can be NULL.
3083 copy-attributes
3085 copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]
3086 Copy the attributes of a path (which can be a file or a directory) to
3088 another path.
3089 By default no attribute is copied, so make sure to specify any (or
3091 "all" to copy everything).
3092 The optional arguments specify which attributes can be copied:
3094 "mode"
3096 Copy part of the file mode from "source" to "destination". Only the
3097 UNIX permissions and the sticky/setuid/setgid bits can be copied.
3098 "xattributes"
3100 Copy the Linux extended attributes (xattrs) from "source" to
3101 "destination". This flag does nothing if the linuxxattrs feature
3102 is not available (see "feature-available").
3103 "ownership"
3105 Copy the owner uid and the group gid of "source" to "destination".
3106 "all"
3108 Copy all the attributes from "source" to "destination". Enabling it
3109 enables all the other flags, if they are not specified already.
3110 This command has one or more optional arguments. See "OPTIONAL
3112 ARGUMENTS".
3113 copy-device-to-device
3115 copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3116 The four calls "copy-device-to-device", "copy-device-to-file", "copy-
3118 file-to-device", and "copy-file-to-file" let you copy from a source
3119 (device|file) to a destination (device|file).
3120 Partial copies can be made since you can specify optionally the source
3122 offset, destination offset and size to copy. These values are all
3123 specified in bytes. If not given, the offsets both default to zero,
3124 and the size defaults to copying as much as possible until we hit the
3125 end of the source.
3126 The source and destination may be the same object. However overlapping
3128 regions may not be copied correctly.
3129 If the destination is a file, it is created if required. If the
3131 destination file is not large enough, it is extended.
3132 If the destination is a file and the "append" flag is not set, then the
3134 destination file is truncated. If the "append" flag is set, then the
3135 copy appends to the destination file. The "append" flag currently
3136 cannot be set for devices.
3137 If the "sparse" flag is true then the call avoids writing blocks that
3139 contain only zeroes, which can help in some situations where the
3140 backing disk is thin-provisioned. Note that unless the target is
3141 already zeroed, using this option will result in incorrect copying.
3142 This command has one or more optional arguments. See "OPTIONAL
3144 ARGUMENTS".
3145 copy-device-to-file
3147 copy-device-to-file 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-device
3155 copy-file-to-device 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 command has one or more optional arguments. See "OPTIONAL
3160 ARGUMENTS".
3161 copy-file-to-file
3163 copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3164 See "copy-device-to-device" for a general overview of this call.
3166 This is not the function you want for copying files. This is for
3168 copying blocks within existing files. See "cp", "cp-a" and "mv" for
3169 general file copying and moving functions.
3170 This command has one or more optional arguments. See "OPTIONAL
3172 ARGUMENTS".
3173 copy-size
3175 copy-size src dest size
3176 This command copies exactly "size" bytes from one source device or file
3178 "src" to another destination device or file "dest".
3179 Note this will fail if the source is too short or if the destination is
3181 not large enough.
3182 This function is deprecated. In new code, use the "copy-device-to-
3184 device" call instead.
3185 Deprecated functions will not be removed from the API, but the fact
3187 that they are deprecated indicates that there are problems with correct
3188 use of these functions.
3189 cp
3191 cp src dest
3192 This copies a file from "src" to "dest" where "dest" is either a
3194 destination filename or destination directory.
3195 cp-a
3197 cp-a src dest
3198 This copies a file or directory from "src" to "dest" recursively using
3200 the "cp -a" command.
3201 cp-r
3203 cp-r src dest
3204 This copies a file or directory from "src" to "dest" recursively using
3206 the "cp -rP" command.
3207 Most users should use "cp-a" instead. This command is useful when you
3209 don't want to preserve permissions, because the target filesystem does
3210 not support it (primarily when writing to DOS FAT filesystems).
3211 cpio-out
3213 cpio-out directory (cpiofile|-) [format:..]
3214 This command packs the contents of directory and downloads it to local
3216 file "cpiofile".
3217 The optional "format" parameter can be used to select the format. Only
3219 the following formats are currently permitted:
3220 "newc"
3222 New (SVR4) portable format. This format happens to be compatible
3223 with the cpio-like format used by the Linux kernel for initramfs.
3224 This is the default format.
3226 "crc"
3228 New (SVR4) portable format with a checksum.
3229 Use "-" instead of a filename to read/write from stdin/stdout.
3231 This command has one or more optional arguments. See "OPTIONAL
3233 ARGUMENTS".
3234 cryptsetup-close
3236 cryptsetup-close device
3237 This closes an encrypted device that was created earlier by
3239 "cryptsetup-open". The "device" parameter must be the name of the
3240 mapping device (ie. /dev/mapper/mapname) and not the name of the
3241 underlying block device.
3242 This command depends on the feature "luks". See also "feature-
3244 available".
3245 cryptsetup-open
3247 cryptsetup-open device mapname [readonly:true|false] [crypttype:..]
3248 This command opens a block device which has been encrypted according to
3250 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
3251 other types.
3252 "device" is the encrypted block device or partition.
3254 The caller must supply one of the keys associated with the encrypted
3256 block device, in the "key" parameter.
3257 This creates a new block device called /dev/mapper/mapname. Reads and
3259 writes to this block device are decrypted from and encrypted to the
3260 underlying "device" respectively.
3261 "mapname" cannot be "control" because that name is reserved by device-
3263 mapper.
3264 If the optional "crypttype" parameter is not present then libguestfs
3266 tries to guess the correct type (for example LUKS or BitLocker).
3267 However you can override this by specifying one of the following types:
3268 "luks"
3270 A Linux LUKS device.
3271 "bitlk"
3273 A Windows BitLocker device.
3274 The optional "readonly" flag, if set to true, creates a read-only
3276 mapping.
3277 If this block device contains LVM volume groups, then calling "lvm-
3279 scan" with the "activate" parameter "true" will make them visible.
3280 Use "list-dm-devices" to list all device mapper devices.
3282 This command has one or more key or passphrase parameters. Guestfish
3284 will prompt for these separately.
3285 This command has one or more optional arguments. See "OPTIONAL
3287 ARGUMENTS".
3288 This command depends on the feature "luks". See also "feature-
3290 available".
3291 dd
3293 dd src dest
3294 This command copies from one source device or file "src" to another
3296 destination device or file "dest". Normally you would use this to copy
3297 to or from a device or partition, for example to duplicate a
3298 filesystem.
3299 If the destination is a device, it must be as large or larger than the
3301 source file or device, otherwise the copy will fail. This command
3302 cannot do partial copies (see "copy-device-to-device").
3303 This function is deprecated. In new code, use the "copy-device-to-
3305 device" call instead.
3306 Deprecated functions will not be removed from the API, but the fact
3308 that they are deprecated indicates that there are problems with correct
3309 use of these functions.
3310 device-index
3312 device-index device
3313 This function takes a device name (eg. "/dev/sdb") and returns the
3315 index of the device in the list of devices.
3316 Index numbers start from 0. The named device must exist, for example
3318 as a string returned from "list-devices".
3319 See also "list-devices", "part-to-dev".
3321 df
3323 df
3324 This command runs the df(1) command to report disk space used.
3326 This command is mostly useful for interactive sessions. It is not
3328 intended that you try to parse the output string. Use "statvfs" from
3329 programs.
3330 df-h
3332 df-h
3333 This command runs the "df -h" command to report disk space used in
3335 human-readable format.
3336 This command is mostly useful for interactive sessions. It is not
3338 intended that you try to parse the output string. Use "statvfs" from
3339 programs.
3340 disk-create
3342 disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]
3343 Create a blank disk image called filename (a host file) with format
3345 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
3346 If used with the optional "backingfile" parameter, then a snapshot is
3348 created on top of the backing file. In this case, "size" must be
3349 passed as "-1". The size of the snapshot is the same as the size of
3350 the backing file, which is discovered automatically. You are
3351 encouraged to also pass "backingformat" to describe the format of
3352 "backingfile".
3353 If filename refers to a block device, then the device is formatted.
3355 The "size" is ignored since block devices have an intrinsic size.
3356 The other optional parameters are:
3358 "preallocation"
3360 If format is "raw", then this can be either "off" (or "sparse") or
3361 "full" to create a sparse or fully allocated file respectively.
3362 The default is "off".
3363 If format is "qcow2", then this can be "off" (or "sparse"),
3365 "metadata" or "full". Preallocating metadata can be faster when
3366 doing lots of writes, but uses more space. The default is "off".
3367 "compat"
3369 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
3370 supported by qemu ≥ 1.1.
3371 "clustersize"
3373 "qcow2" only: Change the qcow2 cluster size. The default is 65536
3374 (bytes) and this setting may be any power of two between 512 and
3375 2097152.
3376 Note that this call does not add the new disk to the handle. You may
3378 need to call "add-drive-opts" separately.
3379 This command has one or more optional arguments. See "OPTIONAL
3381 ARGUMENTS".
3382 disk-format
3384 disk-format filename
3385 Detect and return the format of the disk image called filename.
3387 filename can also be a host device, etc. If the format of the image
3388 could not be detected, then "unknown" is returned.
3389 Note that detecting the disk format can be insecure under some
3391 circumstances. See "CVE-2010-3851" in guestfs(3).
3392 See also: "DISK IMAGE FORMATS" in guestfs(3)
3394 disk-has-backing-file
3396 disk-has-backing-file filename
3397 Detect and return whether the disk image filename has a backing file.
3399 Note that detecting disk features can be insecure under some
3401 circumstances. See "CVE-2010-3851" in guestfs(3).
3402 disk-virtual-size
3404 disk-virtual-size filename
3405 Detect and return the virtual size in bytes of the disk image called
3407 filename.
3408 Note that detecting disk features can be insecure under some
3410 circumstances. See "CVE-2010-3851" in guestfs(3).
3411 dmesg
3413 dmesg
3414 This returns the kernel messages (dmesg(1) output) from the guest
3416 kernel. This is sometimes useful for extended debugging of problems.
3417 Another way to get the same information is to enable verbose messages
3419 with "set-verbose" or by setting the environment variable
3420 "LIBGUESTFS_DEBUG=1" before running the program.
3421 download
3423 download remotefilename (filename|-)
3424 Download file remotefilename and save it as filename on the local
3426 machine.
3427 filename can also be a named pipe.
3429 See also "upload", "cat".
3431 Use "-" instead of a filename to read/write from stdin/stdout.
3433 download-blocks
3435 download-blocks device start stop (filename|-) [unallocated:true|false]
3436 Download the data units from start address to stop from the disk
3438 partition (eg. /dev/sda1) and save them as filename on the local
3439 machine.
3440 The use of this API on sparse disk image formats such as QCOW, may
3442 result in large zero-filled files downloaded on the host.
3443 The size of a data unit varies across filesystem implementations. On
3445 NTFS filesystems data units are referred as clusters while on ExtX ones
3446 they are referred as fragments.
3447 If the optional "unallocated" flag is true (default is false), only the
3449 unallocated blocks will be extracted. This is useful to detect hidden
3450 data or to retrieve deleted files which data units have not been
3451 overwritten yet.
3452 Use "-" instead of a filename to read/write from stdin/stdout.
3454 This command has one or more optional arguments. See "OPTIONAL
3456 ARGUMENTS".
3457 This command depends on the feature "sleuthkit". See also "feature-
3459 available".
3460 download-inode
3462 download-inode device inode (filename|-)
3463 Download a file given its inode from the disk partition (eg. /dev/sda1)
3465 and save it as filename on the local machine.
3466 It is not required to mount the disk to run this command.
3468 The command is capable of downloading deleted or inaccessible files.
3470 Use "-" instead of a filename to read/write from stdin/stdout.
3472 This command depends on the feature "sleuthkit". See also "feature-
3474 available".
3475 download-offset
3477 download-offset remotefilename (filename|-) offset size
3478 Download file remotefilename and save it as filename on the local
3480 machine.
3481 remotefilename is read for "size" bytes starting at "offset" (this
3483 region must be within the file or device).
3484 Note that there is no limit on the amount of data that can be
3486 downloaded with this call, unlike with "pread", and this call always
3487 reads the full amount unless an error occurs.
3488 See also "download", "pread".
3490 Use "-" instead of a filename to read/write from stdin/stdout.
3492 drop-caches
3494 drop-caches whattodrop
3495 This instructs the guest kernel to drop its page cache, and/or dentries
3497 and inode caches. The parameter "whattodrop" tells the kernel what
3498 precisely to drop, see https://linux-mm.org/Drop_Caches
3499 Setting "whattodrop" to 3 should drop everything.
3501 This automatically calls sync(2) before the operation, so that the
3503 maximum guest memory is freed.
3504 du
3506 du path
3507 This command runs the "du -s" command to estimate file space usage for
3509 "path".
3510 "path" can be a file or a directory. If "path" is a directory then the
3512 estimate includes the contents of the directory and all subdirectories
3513 (recursively).
3514 The result is the estimated size in kilobytes (ie. units of 1024
3516 bytes).
3517 e2fsck
3519 e2fsck device [correct:true|false] [forceall:true|false]
3520 This runs the ext2/ext3 filesystem checker on "device". It can take
3522 the following optional arguments:
3523 "correct"
3525 Automatically repair the file system. This option will cause e2fsck
3526 to automatically fix any filesystem problems that can be safely
3527 fixed without human intervention.
3528 This option may not be specified at the same time as the "forceall"
3530 option.
3531 "forceall"
3533 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
3534 used non-interactively.
3535 This option may not be specified at the same time as the "correct"
3537 option.
3538 This command has one or more optional arguments. See "OPTIONAL
3540 ARGUMENTS".
3541 e2fsck-f
3543 e2fsck-f device
3544 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3546 checker on "device", noninteractively (-p), even if the filesystem
3547 appears to be clean (-f).
3548 This function is deprecated. In new code, use the "e2fsck" call
3550 instead.
3551 Deprecated functions will not be removed from the API, but the fact
3553 that they are deprecated indicates that there are problems with correct
3554 use of these functions.
3555 echo-daemon
3557 echo-daemon 'words ...'
3558 This command concatenates the list of "words" passed with single spaces
3560 between them and returns the resulting string.
3561 You can use this command to test the connection through to the daemon.
3563 See also "ping-daemon".
3565 egrep
3567 egrep regex path
3568 This calls the external egrep(1) program and returns the matching
3570 lines.
3571 Because of the message protocol, there is a transfer limit of somewhere
3573 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3574 This function is deprecated. In new code, use the "grep" call instead.
3576 Deprecated functions will not be removed from the API, but the fact
3578 that they are deprecated indicates that there are problems with correct
3579 use of these functions.
3580 egrepi
3582 egrepi regex path
3583 This calls the external "egrep -i" program and returns the matching
3585 lines.
3586 Because of the message protocol, there is a transfer limit of somewhere
3588 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3589 This function is deprecated. In new code, use the "grep" call instead.
3591 Deprecated functions will not be removed from the API, but the fact
3593 that they are deprecated indicates that there are problems with correct
3594 use of these functions.
3595 equal
3597 equal file1 file2
3598 This compares the two files file1 and file2 and returns true if their
3600 content is exactly equal, or false otherwise.
3601 The external cmp(1) program is used for the comparison.
3603 exists
3605 exists path
3606 This returns "true" if and only if there is a file, directory (or
3608 anything) with the given "path" name.
3609 See also "is-file", "is-dir", "stat".
3611 extlinux
3613 extlinux directory
3614 Install the SYSLINUX bootloader on the device mounted at directory.
3616 Unlike "syslinux" which requires a FAT filesystem, this can be used on
3617 an ext2/3/4 or btrfs filesystem.
3618 The directory parameter can be either a mountpoint, or a directory
3620 within the mountpoint.
3621 You also have to mark the partition as "active" ("part-set-bootable")
3623 and a Master Boot Record must be installed (eg. using "pwrite-device")
3624 on the first sector of the whole disk. The SYSLINUX package comes with
3625 some suitable Master Boot Records. See the extlinux(1) man page for
3626 further information.
3627 Additional configuration can be supplied to SYSLINUX by placing a file
3629 called extlinux.conf on the filesystem under directory. For further
3630 information about the contents of this file, see extlinux(1).
3631 See also "syslinux".
3633 This command depends on the feature "extlinux". See also "feature-
3635 available".
3636 f2fs-expand
3638 f2fs-expand device
3639 This expands a f2fs filesystem to match the size of the underlying
3641 device.
3642 This command depends on the feature "f2fs". See also "feature-
3644 available".
3645 fallocate
3647 fallocate path len
3648 This command preallocates a file (containing zero bytes) named "path"
3650 of size "len" bytes. If the file exists already, it is overwritten.
3651 Do not confuse this with the guestfish-specific "alloc" command which
3653 allocates a file in the host and attaches it as a device.
3654 This function is deprecated. In new code, use the "fallocate64" call
3656 instead.
3657 Deprecated functions will not be removed from the API, but the fact
3659 that they are deprecated indicates that there are problems with correct
3660 use of these functions.
3661 fallocate64
3663 fallocate64 path len
3664 This command preallocates a file (containing zero bytes) named "path"
3666 of size "len" bytes. If the file exists already, it is overwritten.
3667 Note that this call allocates disk blocks for the file. To create a
3669 sparse file use "truncate-size" instead.
3670 The deprecated call "fallocate" does the same, but owing to an
3672 oversight it only allowed 30 bit lengths to be specified, effectively
3673 limiting the maximum size of files created through that call to 1GB.
3674 Do not confuse this with the guestfish-specific "alloc" and "sparse"
3676 commands which create a file in the host and attach it as a device.
3677 feature-available
3679 feature-available 'groups ...'
3680 This is the same as "available", but unlike that call it returns a
3682 simple true/false boolean result, instead of throwing an exception if a
3683 feature is not found. For other documentation see "available".
3684 fgrep
3686 fgrep pattern path
3687 This calls the external fgrep(1) program and returns the matching
3689 lines.
3690 Because of the message protocol, there is a transfer limit of somewhere
3692 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3693 This function is deprecated. In new code, use the "grep" call instead.
3695 Deprecated functions will not be removed from the API, but the fact
3697 that they are deprecated indicates that there are problems with correct
3698 use of these functions.
3699 fgrepi
3701 fgrepi pattern path
3702 This calls the external "fgrep -i" program and returns the matching
3704 lines.
3705 Because of the message protocol, there is a transfer limit of somewhere
3707 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3708 This function is deprecated. In new code, use the "grep" call instead.
3710 Deprecated functions will not be removed from the API, but the fact
3712 that they are deprecated indicates that there are problems with correct
3713 use of these functions.
3714 file
3716 file path
3717 This call uses the standard file(1) command to determine the type or
3719 contents of the file.
3720 This call will also transparently look inside various types of
3722 compressed file.
3723 The exact command which runs is "file -zb path". Note in particular
3725 that the filename is not prepended to the output (the -b option).
3726 The output depends on the output of the underlying file(1) command and
3728 it can change in future in ways beyond our control. In other words,
3729 the output is not guaranteed by the ABI.
3730 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
3732 "is-zero".
3733 file-architecture
3735 file-architecture filename
3736 This detects the architecture of the binary filename, and returns it if
3738 known.
3739 Currently defined architectures are:
3741 "aarch64"
3743 64 bit ARM.
3744 "arm"
3746 32 bit ARM.
3747 "i386"
3749 This string is returned for all 32 bit i386, i486, i586, i686
3750 binaries irrespective of the precise processor requirements of the
3751 binary.
3752 "ia64"
3754 Intel Itanium.
3755 "ppc"
3757 32 bit Power PC.
3758 "ppc64"
3760 64 bit Power PC (big endian).
3761 "ppc64le"
3763 64 bit Power PC (little endian).
3764 "riscv32"
3766 "riscv64"
3767 "riscv128"
3768 RISC-V 32-, 64- or 128-bit variants.
3769 "s390"
3771 31 bit IBM S/390.
3772 "s390x"
3774 64 bit IBM S/390.
3775 "sparc"
3777 32 bit SPARC.
3778 "sparc64"
3780 64 bit SPARC V9 and above.
3781 "x86_64"
3783 64 bit x86-64.
3784 Libguestfs may return other architecture strings in future.
3786 The function works on at least the following types of files:
3788 • many types of Un*x and Linux binary
3790 • many types of Un*x and Linux shared library
3792 • Windows Win32 and Win64 binaries
3794 • Windows Win32 and Win64 DLLs
3796 Win32 binaries and DLLs return "i386".
3798 Win64 binaries and DLLs return "x86_64".
3800 • Linux kernel modules
3802 • Linux new-style initrd images
3804 • some non-x86 Linux vmlinuz kernels
3806 What it can't do currently:
3808 • static libraries (libfoo.a)
3810 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
3812 • x86 Linux vmlinuz kernels
3814 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
3816 and compressed code, and are horribly hard to unpack. If you want
3817 to find the architecture of a kernel, use the architecture of the
3818 associated initrd or kernel module(s) instead.
3819 filesize
3821 filesize file
3822 This command returns the size of file in bytes.
3824 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
3826 file" etc. To get the size of block devices, use "blockdev-getsize64".
3827 filesystem-available
3829 filesystem-available filesystem
3830 Check whether libguestfs supports the named filesystem. The argument
3832 "filesystem" is a filesystem name, such as "ext3".
3833 You must call "launch" before using this command.
3835 This is mainly useful as a negative test. If this returns true, it
3837 doesn't mean that a particular filesystem can be created or mounted,
3838 since filesystems can fail for other reasons such as it being a later
3839 version of the filesystem, or having incompatible features, or lacking
3840 the right mkfs.<fs> tool.
3841 See also "available", "feature-available", "AVAILABILITY" in
3843 guestfs(3).
3844 filesystem-walk
3846 filesystem-walk device
3847 Walk through the internal structures of a disk partition (eg.
3849 /dev/sda1) in order to return a list of all the files and directories
3850 stored within.
3851 It is not necessary to mount the disk partition to run this command.
3853 All entries in the filesystem are returned. This function can list
3855 deleted or unaccessible files. The entries are not sorted.
3856 The "tsk_dirent" structure contains the following fields.
3858 "tsk_inode"
3860 Filesystem reference number of the node. It might be 0 if the node
3861 has been deleted.
3862 "tsk_type"
3864 Basic file type information. See below for a detailed list of
3865 values.
3866 "tsk_size"
3868 File size in bytes. It might be "-1" if the node has been deleted.
3869 "tsk_name"
3871 The file path relative to its directory.
3872 "tsk_flags"
3874 Bitfield containing extra information regarding the entry. It
3875 contains the logical OR of the following values:
3876 0x0001
3878 If set to 1, the file is allocated and visible within the
3879 filesystem. Otherwise, the file has been deleted. Under
3880 certain circumstances, the function "download_inode" can be
3881 used to recover deleted files.
3882 0x0002
3884 Filesystem such as NTFS and Ext2 or greater, separate the file
3885 name from the metadata structure. The bit is set to 1 when the
3886 file name is in an unallocated state and the metadata structure
3887 is in an allocated one. This generally implies the metadata
3888 has been reallocated to a new file. Therefore, information
3889 such as file type, file size, timestamps, number of links and
3890 symlink target might not correspond with the ones of the
3891 original deleted entry.
3892 0x0004
3894 The bit is set to 1 when the file is compressed using
3895 filesystem native compression support (NTFS). The API is not
3896 able to detect application level compression.
3897 "tsk_atime_sec"
3899 "tsk_atime_nsec"
3900 "tsk_mtime_sec"
3901 "tsk_mtime_nsec"
3902 "tsk_ctime_sec"
3903 "tsk_ctime_nsec"
3904 "tsk_crtime_sec"
3905 "tsk_crtime_nsec"
3906 Respectively, access, modification, last status change and creation
3907 time in Unix format in seconds and nanoseconds.
3908 "tsk_nlink"
3910 Number of file names pointing to this entry.
3911 "tsk_link"
3913 If the entry is a symbolic link, this field will contain the path
3914 to the target file.
3915 The "tsk_type" field will contain one of the following characters:
3917 'b' Block special
3919 'c' Char special
3921 'd' Directory
3923 'f' FIFO (named pipe)
3925 'l' Symbolic link
3927 'r' Regular file
3929 's' Socket
3931 'h' Shadow inode (Solaris)
3933 'w' Whiteout inode (BSD)
3935 'u' Unknown file type
3937 This command depends on the feature "libtsk". See also "feature-
3939 available".
3940 fill
3942 fill c len path
3943 This command creates a new file called "path". The initial content of
3945 the file is "len" octets of "c", where "c" must be a number in the
3946 range "[0..255]".
3947 To fill a file with zero bytes (sparsely), it is much more efficient to
3949 use "truncate-size". To create a file with a pattern of repeating
3950 bytes use "fill-pattern".
3951 fill-dir
3953 fill-dir dir nr
3954 This function, useful for testing filesystems, creates "nr" empty files
3956 in the directory "dir" with names 00000000 through "nr-1" (ie. each
3957 file name is 8 digits long padded with zeroes).
3958 fill-pattern
3960 fill-pattern pattern len path
3961 This function is like "fill" except that it creates a new file of
3963 length "len" containing the repeating pattern of bytes in "pattern".
3964 The pattern is truncated if necessary to ensure the length of the file
3965 is exactly "len" bytes.
3966 find
3968 find directory
3969 This command lists out all files and directories, recursively, starting
3971 at directory. It is essentially equivalent to running the shell
3972 command "find directory -print" but some post-processing happens on the
3973 output, described below.
3974 This returns a list of strings without any prefix. Thus if the
3976 directory structure was:
3977 /tmp/a
3979 /tmp/b
3980 /tmp/c/d
3981 then the returned list from "find" /tmp would be 4 elements:
3983 a
3985 b
3986 c
3987 c/d
3988 If directory is not a directory, then this command returns an error.
3990 The returned list is sorted.
3992 find0
3994 find0 directory (files|-)
3995 This command lists out all files and directories, recursively, starting
3997 at directory, placing the resulting list in the external file called
3998 files.
3999 This command works the same way as "find" with the following
4001 exceptions:
4002 • The resulting list is written to an external file.
4004 • Items (filenames) in the result are separated by "\0" characters.
4006 See find(1) option -print0.
4007 • The result list is not sorted.
4009 Use "-" instead of a filename to read/write from stdin/stdout.
4011 find-inode
4013 find-inode device inode
4014 Searches all the entries associated with the given inode.
4016 For each entry, a "tsk_dirent" structure is returned. See
4018 "filesystem_walk" for more information about "tsk_dirent" structures.
4019 This command depends on the feature "libtsk". See also "feature-
4021 available".
4022 findfs-label
4024 findfs-label label
4025 This command searches the filesystems and returns the one which has the
4027 given label. An error is returned if no such filesystem can be found.
4028 To find the label of a filesystem, use "vfs-label".
4030 findfs-uuid
4032 findfs-uuid uuid
4033 This command searches the filesystems and returns the one which has the
4035 given UUID. An error is returned if no such filesystem can be found.
4036 To find the UUID of a filesystem, use "vfs-uuid".
4038 fsck
4040 fsck fstype device
4041 This runs the filesystem checker (fsck) on "device" which should have
4043 filesystem type "fstype".
4044 The returned integer is the status. See fsck(8) for the list of status
4046 codes from "fsck".
4047 Notes:
4049 • Multiple status codes can be summed together.
4051 • A non-zero return code can mean "success", for example if errors
4053 have been corrected on the filesystem.
4054 • Checking or repairing NTFS volumes is not supported (by linux-
4056 ntfs).
4057 This command is entirely equivalent to running "fsck -a -t fstype
4059 device".
4060 fstrim
4062 fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]
4063 Trim the free space in the filesystem mounted on "mountpoint". The
4065 filesystem must be mounted read-write.
4066 The filesystem contents are not affected, but any free space in the
4068 filesystem is "trimmed", that is, given back to the host device, thus
4069 making disk images more sparse, allowing unused space in qcow2 files to
4070 be reused, etc.
4071 This operation requires support in libguestfs, the mounted filesystem,
4073 the host filesystem, qemu and the host kernel. If this support isn't
4074 present it may give an error or even appear to run but do nothing.
4075 In the case where the kernel vfs driver does not support trimming, this
4077 call will fail with errno set to "ENOTSUP". Currently this happens
4078 when trying to trim FAT filesystems.
4079 See also "zero-free-space". That is a slightly different operation
4081 that turns free space in the filesystem into zeroes. It is valid to
4082 call "fstrim" either instead of, or after calling "zero-free-space".
4083 This command has one or more optional arguments. See "OPTIONAL
4085 ARGUMENTS".
4086 This command depends on the feature "fstrim". See also "feature-
4088 available".
4089 get-append
4091 get-append
4092 Return the additional kernel options which are added to the libguestfs
4094 appliance kernel command line.
4095 If "NULL" then no options are added.
4097 get-attach-method
4099 get-attach-method
4100 Return the current backend.
4102 See "set-backend" and "BACKEND" in guestfs(3).
4104 This function is deprecated. In new code, use the "get-backend" call
4106 instead.
4107 Deprecated functions will not be removed from the API, but the fact
4109 that they are deprecated indicates that there are problems with correct
4110 use of these functions.
4111 get-autosync
4113 get-autosync
4114 Get the autosync flag.
4116 get-backend
4118 get-backend
4119 Return the current backend.
4121 This handle property was previously called the "attach method".
4123 See "set-backend" and "BACKEND" in guestfs(3).
4125 get-backend-setting
4127 get-backend-setting name
4128 Find a backend setting string which is either "name" or begins with
4130 "name=". If "name", this returns the string "1". If "name=", this
4131 returns the part after the equals sign (which may be an empty string).
4132 If no such setting is found, this function throws an error. The errno
4134 (see "last-errno") will be "ESRCH" in this case.
4135 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4137 get-backend-settings
4139 get-backend-settings
4140 Return the current backend settings.
4142 This call returns all backend settings strings. If you want to find a
4144 single backend setting, see "get-backend-setting".
4145 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4147 get-cachedir
4149 get-cachedir
4150 Get the directory used by the handle to store the appliance cache.
4152 get-direct
4154 get-direct
4155 Return the direct appliance mode flag.
4157 This function is deprecated. In new code, use the "internal-get-
4159 console-socket" call instead.
4160 Deprecated functions will not be removed from the API, but the fact
4162 that they are deprecated indicates that there are problems with correct
4163 use of these functions.
4164 get-e2attrs
4166 get-e2attrs file
4167 This returns the file attributes associated with file.
4169 The attributes are a set of bits associated with each inode which
4171 affect the behaviour of the file. The attributes are returned as a
4172 string of letters (described below). The string may be empty,
4173 indicating that no file attributes are set for this file.
4174 These attributes are only present when the file is located on an
4176 ext2/3/4 filesystem. Using this call on other filesystem types will
4177 result in an error.
4178 The characters (file attributes) in the returned string are currently:
4180 'A' When the file is accessed, its atime is not modified.
4182 'a' The file is append-only.
4184 'c' The file is compressed on-disk.
4186 'D' (Directories only.) Changes to this directory are written
4188 synchronously to disk.
4189 'd' The file is not a candidate for backup (see dump(8)).
4191 'E' The file has compression errors.
4193 'e' The file is using extents.
4195 'h' The file is storing its blocks in units of the filesystem blocksize
4197 instead of sectors.
4198 'I' (Directories only.) The directory is using hashed trees.
4200 'i' The file is immutable. It cannot be modified, deleted or renamed.
4202 No link can be created to this file.
4203 'j' The file is data-journaled.
4205 's' When the file is deleted, all its blocks will be zeroed.
4207 'S' Changes to this file are written synchronously to disk.
4209 'T' (Directories only.) This is a hint to the block allocator that
4211 subdirectories contained in this directory should be spread across
4212 blocks. If not present, the block allocator will try to group
4213 subdirectories together.
4214 't' For a file, this disables tail-merging. (Not used by upstream
4216 implementations of ext2.)
4217 'u' When the file is deleted, its blocks will be saved, allowing the
4219 file to be undeleted.
4220 'X' The raw contents of the compressed file may be accessed.
4222 'Z' The compressed file is dirty.
4224 More file attributes may be added to this list later. Not all file
4226 attributes may be set for all kinds of files. For detailed
4227 information, consult the chattr(1) man page.
4228 See also "set-e2attrs".
4230 Don't confuse these attributes with extended attributes (see
4232 "getxattr").
4233 get-e2generation
4235 get-e2generation file
4236 This returns the ext2 file generation of a file. The generation (which
4238 used to be called the "version") is a number associated with an inode.
4239 This is most commonly used by NFS servers.
4240 The generation is only present when the file is located on an ext2/3/4
4242 filesystem. Using this call on other filesystem types will result in
4243 an error.
4244 See "set-e2generation".
4246 get-e2label
4248 get-e2label device
4249 This returns the ext2/3/4 filesystem label of the filesystem on
4251 "device".
4252 This function is deprecated. In new code, use the "vfs-label" call
4254 instead.
4255 Deprecated functions will not be removed from the API, but the fact
4257 that they are deprecated indicates that there are problems with correct
4258 use of these functions.
4259 get-e2uuid
4261 get-e2uuid device
4262 This returns the ext2/3/4 filesystem UUID of the filesystem on
4264 "device".
4265 This function is deprecated. In new code, use the "vfs-uuid" call
4267 instead.
4268 Deprecated functions will not be removed from the API, but the fact
4270 that they are deprecated indicates that there are problems with correct
4271 use of these functions.
4272 get-hv
4274 get-hv
4275 Return the current hypervisor binary.
4277 This is always non-NULL. If it wasn't set already, then this will
4279 return the default qemu binary name.
4280 get-identifier
4282 get-identifier
4283 Get the handle identifier. See "set-identifier".
4285 get-libvirt-requested-credential-challenge
4287 get-libvirt-requested-credential-challenge index
4288 Get the challenge (provided by libvirt) for the "index"'th requested
4290 credential. If libvirt did not provide a challenge, this returns the
4291 empty string "".
4292 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4294 example code.
4295 get-libvirt-requested-credential-defresult
4297 get-libvirt-requested-credential-defresult index
4298 Get the default result (provided by libvirt) for the "index"'th
4300 requested credential. If libvirt did not provide a default result,
4301 this returns the empty string "".
4302 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4304 example code.
4305 get-libvirt-requested-credential-prompt
4307 get-libvirt-requested-credential-prompt index
4308 Get the prompt (provided by libvirt) for the "index"'th requested
4310 credential. If libvirt did not provide a prompt, this returns the
4311 empty string "".
4312 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4314 example code.
4315 get-libvirt-requested-credentials
4317 get-libvirt-requested-credentials
4318 This should only be called during the event callback for events of type
4320 "GUESTFS_EVENT_LIBVIRT_AUTH".
4321 Return the list of credentials requested by libvirt. Possible values
4323 are a subset of the strings provided when you called "set-libvirt-
4324 supported-credentials".
4325 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4327 example code.
4328 get-memsize
4330 get-memsize
4331 This gets the memory size in megabytes allocated to the hypervisor.
4333 If "set-memsize" was not called on this handle, and if
4335 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4336 default value for memsize.
4337 For more information on the architecture of libguestfs, see guestfs(3).
4339 get-network
4341 get-network
4342 This returns the enable network flag.
4344 get-path
4346 get-path
4347 Return the current search path.
4349 This is always non-NULL. If it wasn't set already, then this will
4351 return the default path.
4352 get-pgroup
4354 get-pgroup
4355 This returns the process group flag.
4357 get-pid
4359 pid
4360 get-pid
4361 Return the process ID of the hypervisor. If there is no hypervisor
4363 running, then this will return an error.
4364 This is an internal call used for debugging and testing.
4366 get-program
4368 get-program
4369 Get the program name. See "set-program".
4371 get-qemu
4373 get-qemu
4374 Return the current hypervisor binary (usually qemu).
4376 This is always non-NULL. If it wasn't set already, then this will
4378 return the default qemu binary name.
4379 This function is deprecated. In new code, use the "get-hv" call
4381 instead.
4382 Deprecated functions will not be removed from the API, but the fact
4384 that they are deprecated indicates that there are problems with correct
4385 use of these functions.
4386 get-recovery-proc
4388 get-recovery-proc
4389 Return the recovery process enabled flag.
4391 get-selinux
4393 get-selinux
4394 This returns the current setting of the selinux flag which is passed to
4396 the appliance at boot time. See "set-selinux".
4397 For more information on the architecture of libguestfs, see guestfs(3).
4399 This function is deprecated. In new code, use the "selinux-relabel"
4401 call instead.
4402 Deprecated functions will not be removed from the API, but the fact
4404 that they are deprecated indicates that there are problems with correct
4405 use of these functions.
4406 get-smp
4408 get-smp
4409 This returns the number of virtual CPUs assigned to the appliance.
4411 get-sockdir
4413 get-sockdir
4414 Get the directory used by the handle to store temporary socket files.
4416 This is different from "get-tmpdir", as we need shorter paths for
4418 sockets (due to the limited buffers of filenames for UNIX sockets), and
4419 "get-tmpdir" may be too long for them.
4420 The environment variable "XDG_RUNTIME_DIR" controls the default value:
4422 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
4423 the default.
4424 get-tmpdir
4426 get-tmpdir
4427 Get the directory used by the handle to store temporary files.
4429 get-trace
4431 get-trace
4432 Return the command trace flag.
4434 get-umask
4436 get-umask
4437 Return the current umask. By default the umask is 022 unless it has
4439 been set by calling "umask".
4440 get-verbose
4442 get-verbose
4443 This returns the verbose messages flag.
4445 getcon
4447 getcon
4448 This gets the SELinux security context of the daemon.
4450 See the documentation about SELINUX in guestfs(3), and "setcon"
4452 This function is deprecated. In new code, use the "selinux-relabel"
4454 call instead.
4455 Deprecated functions will not be removed from the API, but the fact
4457 that they are deprecated indicates that there are problems with correct
4458 use of these functions.
4459 This command depends on the feature "selinux". See also "feature-
4461 available".
4462 getxattr
4464 getxattr path name
4465 Get a single extended attribute from file "path" named "name". This
4467 call follows symlinks. If you want to lookup an extended attribute for
4468 the symlink itself, use "lgetxattr".
4469 Normally it is better to get all extended attributes from a file in one
4471 go by calling "getxattrs". However some Linux filesystem
4472 implementations are buggy and do not provide a way to list out
4473 attributes. For these filesystems (notably ntfs-3g) you have to know
4474 the names of the extended attributes you want in advance and call this
4475 function.
4476 Extended attribute values are blobs of binary data. If there is no
4478 extended attribute named "name", this returns an error.
4479 See also: "getxattrs", "lgetxattr", attr(5).
4481 This command depends on the feature "linuxxattrs". See also "feature-
4483 available".
4484 getxattrs
4486 getxattrs path
4487 This call lists the extended attributes of the file or directory
4489 "path".
4490 At the system call level, this is a combination of the listxattr(2) and
4492 getxattr(2) calls.
4493 See also: "lgetxattrs", attr(5).
4495 This command depends on the feature "linuxxattrs". See also "feature-
4497 available".
4498 glob-expand
4500 glob-expand-opts
4501 glob-expand pattern [directoryslash:true|false]
4502 This command searches for all the pathnames matching "pattern"
4504 according to the wildcard expansion rules used by the shell.
4505 If no paths match, then this returns an empty list (note: not an
4507 error).
4508 It is just a wrapper around the C glob(3) function with flags
4510 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
4511 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
4513 and it defaults to true. It can be explicitly set as off to return no
4514 trailing slashes in filenames of directories.
4515 Notice that there is no equivalent command for expanding a device name
4517 (eg. /dev/sd*). Use "list-devices", "list-partitions" etc functions
4518 instead.
4519 This command has one or more optional arguments. See "OPTIONAL
4521 ARGUMENTS".
4522 grep
4524 grep-opts
4525 grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
4526 This calls the external grep(1) program and returns the matching lines.
4528 The optional flags are:
4530 "extended"
4532 Use extended regular expressions. This is the same as using the -E
4533 flag.
4534 "fixed"
4536 Match fixed (don't use regular expressions). This is the same as
4537 using the -F flag.
4538 "insensitive"
4540 Match case-insensitive. This is the same as using the -i flag.
4541 "compressed"
4543 Use zgrep(1) instead of grep(1). This allows the input to be
4544 compress- or gzip-compressed.
4545 This command has one or more optional arguments. See "OPTIONAL
4547 ARGUMENTS".
4548 Because of the message protocol, there is a transfer limit of somewhere
4550 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4551 grepi
4553 grepi regex path
4554 This calls the external "grep -i" program and returns the matching
4556 lines.
4557 Because of the message protocol, there is a transfer limit of somewhere
4559 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4560 This function is deprecated. In new code, use the "grep" call instead.
4562 Deprecated functions will not be removed from the API, but the fact
4564 that they are deprecated indicates that there are problems with correct
4565 use of these functions.
4566 grub-install
4568 grub-install root device
4569 This command installs GRUB 1 (the Grand Unified Bootloader) on
4571 "device", with the root directory being "root".
4572 Notes:
4574 • There is currently no way in the API to install grub2, which is
4576 used by most modern Linux guests. It is possible to run the grub2
4577 command from the guest, although see the caveats in "RUNNING
4578 COMMANDS" in guestfs(3).
4579 • This uses grub-install(8) from the host. Unfortunately grub is not
4581 always compatible with itself, so this only works in rather narrow
4582 circumstances. Careful testing with each guest version is
4583 advisable.
4584 • If grub-install reports the error "No suitable drive was found in
4586 the generated device map." it may be that you need to create a
4587 /boot/grub/device.map file first that contains the mapping between
4588 grub device names and Linux device names. It is usually sufficient
4589 to create a file containing:
4590 (hd0) /dev/vda
4592 replacing /dev/vda with the name of the installation device.
4594 This command depends on the feature "grub". See also "feature-
4596 available".
4597 head
4599 head path
4600 This command returns up to the first 10 lines of a file as a list of
4602 strings.
4603 Because of the message protocol, there is a transfer limit of somewhere
4605 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4606 head-n
4608 head-n nrlines path
4609 If the parameter "nrlines" is a positive number, this returns the first
4611 "nrlines" lines of the file "path".
4612 If the parameter "nrlines" is a negative number, this returns lines
4614 from the file "path", excluding the last "nrlines" lines.
4615 If the parameter "nrlines" is zero, this returns an empty list.
4617 Because of the message protocol, there is a transfer limit of somewhere
4619 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4620 hexdump
4622 hexdump path
4623 This runs "hexdump -C" on the given "path". The result is the human-
4625 readable, canonical hex dump of the file.
4626 Because of the message protocol, there is a transfer limit of somewhere
4628 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4629 hivex-close
4631 hivex-close
4632 Close the current hivex handle.
4634 This is a wrapper around the hivex(3) call of the same name.
4636 This command depends on the feature "hivex". See also "feature-
4638 available".
4639 hivex-commit
4641 hivex-commit filename
4642 Commit (write) changes to the hive.
4644 If the optional filename parameter is null, then the changes are
4646 written back to the same hive that was opened. If this is not null
4647 then they are written to the alternate filename given and the original
4648 hive is left untouched.
4649 This is a wrapper around the hivex(3) call of the same name.
4651 This command depends on the feature "hivex". See also "feature-
4653 available".
4654 hivex-node-add-child
4656 hivex-node-add-child parent name
4657 Add a child node to "parent" named "name".
4659 This is a wrapper around the hivex(3) call of the same name.
4661 This command depends on the feature "hivex". See also "feature-
4663 available".
4664 hivex-node-children
4666 hivex-node-children nodeh
4667 Return the list of nodes which are subkeys of "nodeh".
4669 This is a wrapper around the hivex(3) call of the same name.
4671 This command depends on the feature "hivex". See also "feature-
4673 available".
4674 hivex-node-delete-child
4676 hivex-node-delete-child nodeh
4677 Delete "nodeh", recursively if necessary.
4679 This is a wrapper around the hivex(3) call of the same name.
4681 This command depends on the feature "hivex". See also "feature-
4683 available".
4684 hivex-node-get-child
4686 hivex-node-get-child nodeh name
4687 Return the child of "nodeh" with the name "name", if it exists. This
4689 can return 0 meaning the name was not found.
4690 This is a wrapper around the hivex(3) call of the same name.
4692 This command depends on the feature "hivex". See also "feature-
4694 available".
4695 hivex-node-get-value
4697 hivex-node-get-value nodeh key
4698 Return the value attached to "nodeh" which has the name "key", if it
4700 exists. This can return 0 meaning the key was not found.
4701 This is a wrapper around the hivex(3) call of the same name.
4703 This command depends on the feature "hivex". See also "feature-
4705 available".
4706 hivex-node-name
4708 hivex-node-name nodeh
4709 Return the name of "nodeh".
4711 This is a wrapper around the hivex(3) call of the same name.
4713 This command depends on the feature "hivex". See also "feature-
4715 available".
4716 hivex-node-parent
4718 hivex-node-parent nodeh
4719 Return the parent node of "nodeh".
4721 This is a wrapper around the hivex(3) call of the same name.
4723 This command depends on the feature "hivex". See also "feature-
4725 available".
4726 hivex-node-set-value
4728 hivex-node-set-value nodeh key t val
4729 Set or replace a single value under the node "nodeh". The "key" is the
4731 name, "t" is the type, and "val" is the data.
4732 This is a wrapper around the hivex(3) call of the same name.
4734 This command depends on the feature "hivex". See also "feature-
4736 available".
4737 hivex-node-values
4739 hivex-node-values nodeh
4740 Return the array of (key, datatype, data) tuples attached to "nodeh".
4742 This is a wrapper around the hivex(3) call of the same name.
4744 This command depends on the feature "hivex". See also "feature-
4746 available".
4747 hivex-open
4749 hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]
4750 Open the Windows Registry hive file named filename. If there was any
4752 previous hivex handle associated with this guestfs session, then it is
4753 closed.
4754 This is a wrapper around the hivex(3) call of the same name.
4756 This command has one or more optional arguments. See "OPTIONAL
4758 ARGUMENTS".
4759 This command depends on the feature "hivex". See also "feature-
4761 available".
4762 hivex-root
4764 hivex-root
4765 Return the root node of the hive.
4767 This is a wrapper around the hivex(3) call of the same name.
4769 This command depends on the feature "hivex". See also "feature-
4771 available".
4772 hivex-value-key
4774 hivex-value-key valueh
4775 Return the key (name) field of a (key, datatype, data) tuple.
4777 This is a wrapper around the hivex(3) call of the same name.
4779 This command depends on the feature "hivex". See also "feature-
4781 available".
4782 hivex-value-string
4784 hivex-value-string valueh
4785 This calls "hivex-value-value" (which returns the data field from a
4787 hivex value tuple). It then assumes that the field is a UTF-16LE
4788 string and converts the result to UTF-8 (or if this is not possible, it
4789 returns an error).
4790 This is useful for reading strings out of the Windows registry.
4792 However it is not foolproof because the registry is not strongly-typed
4793 and fields can contain arbitrary or unexpected data.
4794 This command depends on the feature "hivex". See also "feature-
4796 available".
4797 hivex-value-type
4799 hivex-value-type valueh
4800 Return the data type field from a (key, datatype, data) tuple.
4802 This is a wrapper around the hivex(3) call of the same name.
4804 This command depends on the feature "hivex". See also "feature-
4806 available".
4807 hivex-value-utf8
4809 hivex-value-utf8 valueh
4810 This calls "hivex-value-value" (which returns the data field from a
4812 hivex value tuple). It then assumes that the field is a UTF-16LE
4813 string and converts the result to UTF-8 (or if this is not possible, it
4814 returns an error).
4815 This is useful for reading strings out of the Windows registry.
4817 However it is not foolproof because the registry is not strongly-typed
4818 and fields can contain arbitrary or unexpected data.
4819 This function is deprecated. In new code, use the "hivex-value-string"
4821 call instead.
4822 Deprecated functions will not be removed from the API, but the fact
4824 that they are deprecated indicates that there are problems with correct
4825 use of these functions.
4826 This command depends on the feature "hivex". See also "feature-
4828 available".
4829 hivex-value-value
4831 hivex-value-value valueh
4832 Return the data field of a (key, datatype, data) tuple.
4834 This is a wrapper around the hivex(3) call of the same name.
4836 See also: "hivex-value-utf8".
4838 This command depends on the feature "hivex". See also "feature-
4840 available".
4841 initrd-cat
4843 initrd-cat initrdpath filename
4844 This command unpacks the file filename from the initrd file called
4846 initrdpath. The filename must be given without the initial /
4847 character.
4848 For example, in guestfish you could use the following command to
4850 examine the boot script (usually called /init) contained in a Linux
4851 initrd or initramfs image:
4852 initrd-cat /boot/initrd-<version>.img init
4854 See also "initrd-list".
4856 Because of the message protocol, there is a transfer limit of somewhere
4858 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4859 initrd-list
4861 initrd-list path
4862 This command lists out files contained in an initrd.
4864 The files are listed without any initial / character. The files are
4866 listed in the order they appear (not necessarily alphabetical).
4867 Directory names are listed as separate items.
4868 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
4870 as initrd. We only support the newer initramfs format (compressed cpio
4871 files).
4872 inotify-add-watch
4874 inotify-add-watch path mask
4875 Watch "path" for the events listed in "mask".
4877 Note that if "path" is a directory then events within that directory
4879 are watched, but this does not happen recursively (in subdirectories).
4880 Note for non-C or non-Linux callers: the inotify events are defined by
4882 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
4883 This command depends on the feature "inotify". See also "feature-
4885 available".
4886 inotify-close
4888 inotify-close
4889 This closes the inotify handle which was previously opened by
4891 inotify_init. It removes all watches, throws away any pending events,
4892 and deallocates all resources.
4893 This command depends on the feature "inotify". See also "feature-
4895 available".
4896 inotify-files
4898 inotify-files
4899 This function is a helpful wrapper around "inotify-read" which just
4901 returns a list of pathnames of objects that were touched. The returned
4902 pathnames are sorted and deduplicated.
4903 This command depends on the feature "inotify". See also "feature-
4905 available".
4906 inotify-init
4908 inotify-init maxevents
4909 This command creates a new inotify handle. The inotify subsystem can
4911 be used to notify events which happen to objects in the guest
4912 filesystem.
4913 "maxevents" is the maximum number of events which will be queued up
4915 between calls to "inotify-read" or "inotify-files". If this is passed
4916 as 0, then the kernel (or previously set) default is used. For Linux
4917 2.6.29 the default was 16384 events. Beyond this limit, the kernel
4918 throws away events, but records the fact that it threw them away by
4919 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
4920 "inotify-read").
4921 Before any events are generated, you have to add some watches to the
4923 internal watch list. See: "inotify-add-watch" and "inotify-rm-watch".
4924 Queued up events should be read periodically by calling "inotify-read"
4926 (or "inotify-files" which is just a helpful wrapper around "inotify-
4927 read"). If you don't read the events out often enough then you risk
4928 the internal queue overflowing.
4929 The handle should be closed after use by calling "inotify-close". This
4931 also removes any watches automatically.
4932 See also inotify(7) for an overview of the inotify interface as exposed
4934 by the Linux kernel, which is roughly what we expose via libguestfs.
4935 Note that there is one global inotify handle per libguestfs instance.
4936 This command depends on the feature "inotify". See also "feature-
4938 available".
4939 inotify-read
4941 inotify-read
4942 Return the complete queue of events that have happened since the
4944 previous read call.
4945 If no events have happened, this returns an empty list.
4947 Note: In order to make sure that all events have been read, you must
4949 call this function repeatedly until it returns an empty list. The
4950 reason is that the call will read events up to the maximum appliance-
4951 to-host message size and leave remaining events in the queue.
4952 This command depends on the feature "inotify". See also "feature-
4954 available".
4955 inotify-rm-watch
4957 inotify-rm-watch wd
4958 Remove a previously defined inotify watch. See "inotify-add-watch".
4960 This command depends on the feature "inotify". See also "feature-
4962 available".
4963 inspect-get-arch
4965 inspect-get-arch root
4966 This returns the architecture of the inspected operating system. The
4968 possible return values are listed under "file-architecture".
4969 If the architecture could not be determined, then the string "unknown"
4971 is returned.
4972 Please read "INSPECTION" in guestfs(3) for more details.
4974 inspect-get-distro
4976 inspect-get-distro root
4977 This returns the distro (distribution) of the inspected operating
4979 system.
4980 Currently defined distros are:
4982 "alpinelinux"
4984 Alpine Linux.
4985 "altlinux"
4987 ALT Linux.
4988 "archlinux"
4990 Arch Linux.
4991 "buildroot"
4993 Buildroot-derived distro, but not one we specifically recognize.
4994 "centos"
4996 CentOS.
4997 "cirros"
4999 Cirros.
5000 "coreos"
5002 CoreOS.
5003 "debian"
5005 Debian.
5006 "fedora"
5008 Fedora.
5009 "freebsd"
5011 FreeBSD.
5012 "freedos"
5014 FreeDOS.
5015 "frugalware"
5017 Frugalware.
5018 "gentoo"
5020 Gentoo.
5021 "kalilinux"
5023 Kali Linux.
5024 "linuxmint"
5026 Linux Mint.
5027 "mageia"
5029 Mageia.
5030 "mandriva"
5032 Mandriva.
5033 "meego"
5035 MeeGo.
5036 "msdos"
5038 Microsoft DOS.
5039 "neokylin"
5041 NeoKylin.
5042 "netbsd"
5044 NetBSD.
5045 "openbsd"
5047 OpenBSD.
5048 "openmandriva"
5050 OpenMandriva Lx.
5051 "opensuse"
5053 OpenSUSE.
5054 "oraclelinux"
5056 Oracle Linux.
5057 "pardus"
5059 Pardus.
5060 "pldlinux"
5062 PLD Linux.
5063 "redhat-based"
5065 Some Red Hat-derived distro.
5066 "rhel"
5068 Red Hat Enterprise Linux.
5069 "scientificlinux"
5071 Scientific Linux.
5072 "slackware"
5074 Slackware.
5075 "sles"
5077 SuSE Linux Enterprise Server or Desktop.
5078 "suse-based"
5080 Some openSuSE-derived distro.
5081 "ttylinux"
5083 ttylinux.
5084 "ubuntu"
5086 Ubuntu.
5087 "unknown"
5089 The distro could not be determined.
5090 "voidlinux"
5092 Void Linux.
5093 "windows"
5095 Windows does not have distributions. This string is returned if
5096 the OS type is Windows.
5097 Future versions of libguestfs may return other strings here. The
5099 caller should be prepared to handle any string.
5100 Please read "INSPECTION" in guestfs(3) for more details.
5102 inspect-get-drive-mappings
5104 inspect-get-drive-mappings root
5105 This call is useful for Windows which uses a primitive system of
5107 assigning drive letters (like C:\) to partitions. This inspection API
5108 examines the Windows Registry to find out how disks/partitions are
5109 mapped to drive letters, and returns a hash table as in the example
5110 below:
5111 C => /dev/vda2
5113 E => /dev/vdb1
5114 F => /dev/vdc1
5115 Note that keys are drive letters. For Windows, the key is case
5117 insensitive and just contains the drive letter, without the customary
5118 colon separator character.
5119 In future we may support other operating systems that also used drive
5121 letters, but the keys for those might not be case insensitive and might
5122 be longer than 1 character. For example in OS-9, hard drives were
5123 named "h0", "h1" etc.
5124 For Windows guests, currently only hard drive mappings are returned.
5126 Removable disks (eg. DVD-ROMs) are ignored.
5127 For guests that do not use drive mappings, or if the drive mappings
5129 could not be determined, this returns an empty hash table.
5130 Please read "INSPECTION" in guestfs(3) for more details. See also
5132 "inspect-get-mountpoints", "inspect-get-filesystems".
5133 inspect-get-filesystems
5135 inspect-get-filesystems root
5136 This returns a list of all the filesystems that we think are associated
5138 with this operating system. This includes the root filesystem, other
5139 ordinary filesystems, and non-mounted devices like swap partitions.
5140 In the case of a multi-boot virtual machine, it is possible for a
5142 filesystem to be shared between operating systems.
5143 Please read "INSPECTION" in guestfs(3) for more details. See also
5145 "inspect-get-mountpoints".
5146 inspect-get-format
5148 inspect-get-format root
5149 Before libguestfs 1.38, there was some unreliable support for detecting
5151 installer CDs. This API would return:
5152 "installed"
5154 This is an installed operating system.
5155 "installer"
5157 The disk image being inspected is not an installed operating
5158 system, but a bootable install disk, live CD, or similar.
5159 "unknown"
5161 The format of this disk image is not known.
5162 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
5164 directly to detect installer CDs.
5165 Please read "INSPECTION" in guestfs(3) for more details.
5167 This function is deprecated. There is no replacement. Consult the API
5169 documentation in guestfs(3) for further information.
5170 Deprecated functions will not be removed from the API, but the fact
5172 that they are deprecated indicates that there are problems with correct
5173 use of these functions.
5174 inspect-get-hostname
5176 inspect-get-hostname root
5177 This function returns the hostname of the operating system as found by
5179 inspection of the guest’s configuration files.
5180 If the hostname could not be determined, then the string "unknown" is
5182 returned.
5183 Please read "INSPECTION" in guestfs(3) for more details.
5185 inspect-get-icon
5187 inspect-get-icon root [favicon:true|false] [highquality:true|false]
5188 This function returns an icon corresponding to the inspected operating
5190 system. The icon is returned as a buffer containing a PNG image (re-
5191 encoded to PNG if necessary).
5192 If it was not possible to get an icon this function returns a zero-
5194 length (non-NULL) buffer. Callers must check for this case.
5195 Libguestfs will start by looking for a file called /etc/favicon.png or
5197 C:\etc\favicon.png and if it has the correct format, the contents of
5198 this file will be returned. You can disable favicons by passing the
5199 optional "favicon" boolean as false (default is true).
5200 If finding the favicon fails, then we look in other places in the guest
5202 for a suitable icon.
5203 If the optional "highquality" boolean is true then only high quality
5205 icons are returned, which means only icons of high resolution with an
5206 alpha channel. The default (false) is to return any icon we can, even
5207 if it is of substandard quality.
5208 Notes:
5210 • Unlike most other inspection API calls, the guest’s disks must be
5212 mounted up before you call this, since it needs to read information
5213 from the guest filesystem during the call.
5214 • Security: The icon data comes from the untrusted guest, and should
5216 be treated with caution. PNG files have been known to contain
5217 exploits. Ensure that libpng (or other relevant libraries) are
5218 fully up to date before trying to process or display the icon.
5219 • The PNG image returned can be any size. It might not be square.
5221 Libguestfs tries to return the largest, highest quality icon
5222 available. The application must scale the icon to the required
5223 size.
5224 • Extracting icons from Windows guests requires the external
5226 wrestool(1) program from the "icoutils" package, and several
5227 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
5228 package. These must be installed separately.
5229 • Operating system icons are usually trademarks. Seek legal advice
5231 before using trademarks in applications.
5232 This command has one or more optional arguments. See "OPTIONAL
5234 ARGUMENTS".
5235 inspect-get-major-version
5237 inspect-get-major-version root
5238 This returns the major version number of the inspected operating
5240 system.
5241 Windows uses a consistent versioning scheme which is not reflected in
5243 the popular public names used by the operating system. Notably the
5244 operating system known as "Windows 7" is really version 6.1 (ie. major
5245 = 6, minor = 1). You can find out the real versions corresponding to
5246 releases of Windows by consulting Wikipedia or MSDN.
5247 If the version could not be determined, then 0 is returned.
5249 Please read "INSPECTION" in guestfs(3) for more details.
5251 inspect-get-minor-version
5253 inspect-get-minor-version root
5254 This returns the minor version number of the inspected operating
5256 system.
5257 If the version could not be determined, then 0 is returned.
5259 Please read "INSPECTION" in guestfs(3) for more details. See also
5261 "inspect-get-major-version".
5262 inspect-get-mountpoints
5264 inspect-get-mountpoints root
5265 This returns a hash of where we think the filesystems associated with
5267 this operating system should be mounted. Callers should note that this
5268 is at best an educated guess made by reading configuration files such
5269 as /etc/fstab. In particular note that this may return filesystems
5270 which are non-existent or not mountable and callers should be prepared
5271 to handle or ignore failures if they try to mount them.
5272 Each element in the returned hashtable has a key which is the path of
5274 the mountpoint (eg. /boot) and a value which is the filesystem that
5275 would be mounted there (eg. /dev/sda1).
5276 Non-mounted devices such as swap devices are not returned in this list.
5278 For operating systems like Windows which still use drive letters, this
5280 call will only return an entry for the first drive "mounted on" /. For
5281 information about the mapping of drive letters to partitions, see
5282 "inspect-get-drive-mappings".
5283 Please read "INSPECTION" in guestfs(3) for more details. See also
5285 "inspect-get-filesystems".
5286 inspect-get-osinfo
5288 inspect-get-osinfo root
5289 This function returns a possible short ID for libosinfo corresponding
5291 to the guest.
5292 Note: The returned ID is only a guess by libguestfs, and nothing
5294 ensures that it actually exists in osinfo-db.
5295 If no ID could not be determined, then the string "unknown" is
5297 returned.
5298 inspect-get-package-format
5300 inspect-get-package-format root
5301 This function and "inspect-get-package-management" return the package
5303 format and package management tool used by the inspected operating
5304 system. For example for Fedora these functions would return "rpm"
5305 (package format), and "yum" or "dnf" (package management).
5306 This returns the string "unknown" if we could not determine the package
5308 format or if the operating system does not have a real packaging system
5309 (eg. Windows).
5310 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5312 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
5313 other strings.
5314 Please read "INSPECTION" in guestfs(3) for more details.
5316 inspect-get-package-management
5318 inspect-get-package-management root
5319 "inspect-get-package-format" and this function return the package
5321 format and package management tool used by the inspected operating
5322 system. For example for Fedora these functions would return "rpm"
5323 (package format), and "yum" or "dnf" (package management).
5324 This returns the string "unknown" if we could not determine the package
5326 management tool or if the operating system does not have a real
5327 packaging system (eg. Windows).
5328 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
5330 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
5331 "apk", "xbps". Future versions of libguestfs may return other strings.
5332 Please read "INSPECTION" in guestfs(3) for more details.
5334 inspect-get-product-name
5336 inspect-get-product-name root
5337 This returns the product name of the inspected operating system. The
5339 product name is generally some freeform string which can be displayed
5340 to the user, but should not be parsed by programs.
5341 If the product name could not be determined, then the string "unknown"
5343 is returned.
5344 Please read "INSPECTION" in guestfs(3) for more details.
5346 inspect-get-product-variant
5348 inspect-get-product-variant root
5349 This returns the product variant of the inspected operating system.
5351 For Windows guests, this returns the contents of the Registry key
5353 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
5354 which is usually a string such as "Client" or "Server" (other values
5355 are possible). This can be used to distinguish consumer and enterprise
5356 versions of Windows that have the same version number (for example,
5357 Windows 7 and Windows 2008 Server are both version 6.1, but the former
5358 is "Client" and the latter is "Server").
5359 For enterprise Linux guests, in future we intend this to return the
5361 product variant such as "Desktop", "Server" and so on. But this is not
5362 implemented at present.
5363 If the product variant could not be determined, then the string
5365 "unknown" is returned.
5366 Please read "INSPECTION" in guestfs(3) for more details. See also
5368 "inspect-get-product-name", "inspect-get-major-version".
5369 inspect-get-roots
5371 inspect-get-roots
5372 This function is a convenient way to get the list of root devices, as
5374 returned from a previous call to "inspect-os", but without redoing the
5375 whole inspection process.
5376 This returns an empty list if either no root devices were found or the
5378 caller has not called "inspect-os".
5379 Please read "INSPECTION" in guestfs(3) for more details.
5381 inspect-get-type
5383 inspect-get-type root
5384 This returns the type of the inspected operating system. Currently
5386 defined types are:
5387 "linux"
5389 Any Linux-based operating system.
5390 "windows"
5392 Any Microsoft Windows operating system.
5393 "freebsd"
5395 FreeBSD.
5396 "netbsd"
5398 NetBSD.
5399 "openbsd"
5401 OpenBSD.
5402 "hurd"
5404 GNU/Hurd.
5405 "dos"
5407 MS-DOS, FreeDOS and others.
5408 "minix"
5410 MINIX.
5411 "unknown"
5413 The operating system type could not be determined.
5414 Future versions of libguestfs may return other strings here. The
5416 caller should be prepared to handle any string.
5417 Please read "INSPECTION" in guestfs(3) for more details.
5419 inspect-get-windows-current-control-set
5421 inspect-get-windows-current-control-set root
5422 This returns the Windows CurrentControlSet of the inspected guest. The
5424 CurrentControlSet is a registry key name such as "ControlSet001".
5425 This call assumes that the guest is Windows and that the Registry could
5427 be examined by inspection. If this is not the case then an error is
5428 returned.
5429 Please read "INSPECTION" in guestfs(3) for more details.
5431 inspect-get-windows-software-hive
5433 inspect-get-windows-software-hive root
5434 This returns the path to the hive (binary Windows Registry file)
5436 corresponding to HKLM\SOFTWARE.
5437 This call assumes that the guest is Windows and that the guest has a
5439 software hive file with the right name. If this is not the case then
5440 an error is returned. This call does not check that the hive is a
5441 valid Windows Registry hive.
5442 You can use "hivex-open" to read or write to the hive.
5444 Please read "INSPECTION" in guestfs(3) for more details.
5446 inspect-get-windows-system-hive
5448 inspect-get-windows-system-hive root
5449 This returns the path to the hive (binary Windows Registry file)
5451 corresponding to HKLM\SYSTEM.
5452 This call assumes that the guest is Windows and that the guest has a
5454 system hive file with the right name. If this is not the case then an
5455 error is returned. This call does not check that the hive is a valid
5456 Windows Registry hive.
5457 You can use "hivex-open" to read or write to the hive.
5459 Please read "INSPECTION" in guestfs(3) for more details.
5461 inspect-get-windows-systemroot
5463 inspect-get-windows-systemroot root
5464 This returns the Windows systemroot of the inspected guest. The
5466 systemroot is a directory path such as /WINDOWS.
5467 This call assumes that the guest is Windows and that the systemroot
5469 could be determined by inspection. If this is not the case then an
5470 error is returned.
5471 Please read "INSPECTION" in guestfs(3) for more details.
5473 inspect-is-live
5475 inspect-is-live root
5476 This is deprecated and always returns "false".
5478 Please read "INSPECTION" in guestfs(3) for more details.
5480 This function is deprecated. There is no replacement. Consult the API
5482 documentation in guestfs(3) for further information.
5483 Deprecated functions will not be removed from the API, but the fact
5485 that they are deprecated indicates that there are problems with correct
5486 use of these functions.
5487 inspect-is-multipart
5489 inspect-is-multipart root
5490 This is deprecated and always returns "false".
5492 Please read "INSPECTION" in guestfs(3) for more details.
5494 This function is deprecated. There is no replacement. Consult the API
5496 documentation in guestfs(3) for further information.
5497 Deprecated functions will not be removed from the API, but the fact
5499 that they are deprecated indicates that there are problems with correct
5500 use of these functions.
5501 inspect-is-netinst
5503 inspect-is-netinst root
5504 This is deprecated and always returns "false".
5506 Please read "INSPECTION" in guestfs(3) for more details.
5508 This function is deprecated. There is no replacement. Consult the API
5510 documentation in guestfs(3) for further information.
5511 Deprecated functions will not be removed from the API, but the fact
5513 that they are deprecated indicates that there are problems with correct
5514 use of these functions.
5515 inspect-list-applications
5517 inspect-list-applications root
5518 Return the list of applications installed in the operating system.
5520 Note: This call works differently from other parts of the inspection
5522 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5523 then mount up the disks, before calling this. Listing applications is
5524 a significantly more difficult operation which requires access to the
5525 full filesystem. Also note that unlike the other "inspect-get-*" calls
5526 which are just returning data cached in the libguestfs handle, this
5527 call actually reads parts of the mounted filesystems during the call.
5528 This returns an empty list if the inspection code was not able to
5530 determine the list of applications.
5531 The application structure contains the following fields:
5533 "app_name"
5535 The name of the application. For Linux guests, this is the package
5536 name.
5537 "app_display_name"
5539 The display name of the application, sometimes localized to the
5540 install language of the guest operating system.
5541 If unavailable this is returned as an empty string "". Callers
5543 needing to display something can use "app_name" instead.
5544 "app_epoch"
5546 For package managers which use epochs, this contains the epoch of
5547 the package (an integer). If unavailable, this is returned as 0.
5548 "app_version"
5550 The version string of the application or package. If unavailable
5551 this is returned as an empty string "".
5552 "app_release"
5554 The release string of the application or package, for package
5555 managers that use this. If unavailable this is returned as an
5556 empty string "".
5557 "app_install_path"
5559 The installation path of the application (on operating systems such
5560 as Windows which use installation paths). This path is in the
5561 format used by the guest operating system, it is not a libguestfs
5562 path.
5563 If unavailable this is returned as an empty string "".
5565 "app_trans_path"
5567 The install path translated into a libguestfs path. If unavailable
5568 this is returned as an empty string "".
5569 "app_publisher"
5571 The name of the publisher of the application, for package managers
5572 that use this. If unavailable this is returned as an empty string
5573 "".
5574 "app_url"
5576 The URL (eg. upstream URL) of the application. If unavailable this
5577 is returned as an empty string "".
5578 "app_source_package"
5580 For packaging systems which support this, the name of the source
5581 package. If unavailable this is returned as an empty string "".
5582 "app_summary"
5584 A short (usually one line) description of the application or
5585 package. If unavailable this is returned as an empty string "".
5586 "app_description"
5588 A longer description of the application or package. If unavailable
5589 this is returned as an empty string "".
5590 Please read "INSPECTION" in guestfs(3) for more details.
5592 This function is deprecated. In new code, use the
5594 "inspect-list-applications2" call instead.
5595 Deprecated functions will not be removed from the API, but the fact
5597 that they are deprecated indicates that there are problems with correct
5598 use of these functions.
5599 inspect-list-applications2
5601 inspect-list-applications2 root
5602 Return the list of applications installed in the operating system.
5604 Note: This call works differently from other parts of the inspection
5606 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5607 then mount up the disks, before calling this. Listing applications is
5608 a significantly more difficult operation which requires access to the
5609 full filesystem. Also note that unlike the other "inspect-get-*" calls
5610 which are just returning data cached in the libguestfs handle, this
5611 call actually reads parts of the mounted filesystems during the call.
5612 This returns an empty list if the inspection code was not able to
5614 determine the list of applications.
5615 The application structure contains the following fields:
5617 "app2_name"
5619 The name of the application. For Linux guests, this is the package
5620 name.
5621 "app2_display_name"
5623 The display name of the application, sometimes localized to the
5624 install language of the guest operating system.
5625 If unavailable this is returned as an empty string "". Callers
5627 needing to display something can use "app2_name" instead.
5628 "app2_epoch"
5630 For package managers which use epochs, this contains the epoch of
5631 the package (an integer). If unavailable, this is returned as 0.
5632 "app2_version"
5634 The version string of the application or package. If unavailable
5635 this is returned as an empty string "".
5636 "app2_release"
5638 The release string of the application or package, for package
5639 managers that use this. If unavailable this is returned as an
5640 empty string "".
5641 "app2_arch"
5643 The architecture string of the application or package, for package
5644 managers that use this. If unavailable this is returned as an
5645 empty string "".
5646 "app2_install_path"
5648 The installation path of the application (on operating systems such
5649 as Windows which use installation paths). This path is in the
5650 format used by the guest operating system, it is not a libguestfs
5651 path.
5652 If unavailable this is returned as an empty string "".
5654 "app2_trans_path"
5656 The install path translated into a libguestfs path. If unavailable
5657 this is returned as an empty string "".
5658 "app2_publisher"
5660 The name of the publisher of the application, for package managers
5661 that use this. If unavailable this is returned as an empty string
5662 "".
5663 "app2_url"
5665 The URL (eg. upstream URL) of the application. If unavailable this
5666 is returned as an empty string "".
5667 "app2_source_package"
5669 For packaging systems which support this, the name of the source
5670 package. If unavailable this is returned as an empty string "".
5671 "app2_summary"
5673 A short (usually one line) description of the application or
5674 package. If unavailable this is returned as an empty string "".
5675 "app2_description"
5677 A longer description of the application or package. If unavailable
5678 this is returned as an empty string "".
5679 Please read "INSPECTION" in guestfs(3) for more details.
5681 inspect-os
5683 inspect-os
5684 This function uses other libguestfs functions and certain heuristics to
5686 inspect the disk(s) (usually disks belonging to a virtual machine),
5687 looking for operating systems.
5688 The list returned is empty if no operating systems were found.
5690 If one operating system was found, then this returns a list with a
5692 single element, which is the name of the root filesystem of this
5693 operating system. It is also possible for this function to return a
5694 list containing more than one element, indicating a dual-boot or multi-
5695 boot virtual machine, with each element being the root filesystem of
5696 one of the operating systems.
5697 You can pass the root string(s) returned to other "inspect-get-*"
5699 functions in order to query further information about each operating
5700 system, such as the name and version.
5701 This function uses other libguestfs features such as "mount-ro" and
5703 "umount-all" in order to mount and unmount filesystems and look at the
5704 contents. This should be called with no disks currently mounted. The
5705 function may also use Augeas, so any existing Augeas handle will be
5706 closed.
5707 This function cannot decrypt encrypted disks. The caller must do that
5709 first (supplying the necessary keys) if the disk is encrypted.
5710 Please read "INSPECTION" in guestfs(3) for more details.
5712 See also "list-filesystems".
5714 is-blockdev
5716 is-blockdev-opts
5717 is-blockdev path [followsymlinks:true|false]
5718 This returns "true" if and only if there is a block device with the
5720 given "path" name.
5721 If the optional flag "followsymlinks" is true, then a symlink (or chain
5723 of symlinks) that ends with a block device also causes the function to
5724 return true.
5725 This call only looks at files within the guest filesystem. Libguestfs
5727 partitions and block devices (eg. /dev/sda) cannot be used as the
5728 "path" parameter of this call.
5729 See also "stat".
5731 This command has one or more optional arguments. See "OPTIONAL
5733 ARGUMENTS".
5734 is-chardev
5736 is-chardev-opts
5737 is-chardev path [followsymlinks:true|false]
5738 This returns "true" if and only if there is a character device with the
5740 given "path" name.
5741 If the optional flag "followsymlinks" is true, then a symlink (or chain
5743 of symlinks) that ends with a chardev also causes the function to
5744 return true.
5745 See also "stat".
5747 This command has one or more optional arguments. See "OPTIONAL
5749 ARGUMENTS".
5750 is-config
5752 is-config
5753 This returns true iff this handle is being configured (in the "CONFIG"
5755 state).
5756 For more information on states, see guestfs(3).
5758 is-dir
5760 is-dir-opts
5761 is-dir path [followsymlinks:true|false]
5762 This returns "true" if and only if there is a directory with the given
5764 "path" name. Note that it returns false for other objects like files.
5765 If the optional flag "followsymlinks" is true, then a symlink (or chain
5767 of symlinks) that ends with a directory also causes the function to
5768 return true.
5769 See also "stat".
5771 This command has one or more optional arguments. See "OPTIONAL
5773 ARGUMENTS".
5774 is-fifo
5776 is-fifo-opts
5777 is-fifo path [followsymlinks:true|false]
5778 This returns "true" if and only if there is a FIFO (named pipe) with
5780 the given "path" name.
5781 If the optional flag "followsymlinks" is true, then a symlink (or chain
5783 of symlinks) that ends with a FIFO also causes the function to return
5784 true.
5785 See also "stat".
5787 This command has one or more optional arguments. See "OPTIONAL
5789 ARGUMENTS".
5790 is-file
5792 is-file-opts
5793 is-file path [followsymlinks:true|false]
5794 This returns "true" if and only if there is a regular file with the
5796 given "path" name. Note that it returns false for other objects like
5797 directories.
5798 If the optional flag "followsymlinks" is true, then a symlink (or chain
5800 of symlinks) that ends with a file also causes the function to return
5801 true.
5802 See also "stat".
5804 This command has one or more optional arguments. See "OPTIONAL
5806 ARGUMENTS".
5807 is-lv
5809 is-lv mountable
5810 This command tests whether "mountable" is a logical volume, and returns
5812 true iff this is the case.
5813 is-socket
5815 is-socket-opts
5816 is-socket path [followsymlinks:true|false]
5817 This returns "true" if and only if there is a Unix domain socket with
5819 the given "path" name.
5820 If the optional flag "followsymlinks" is true, then a symlink (or chain
5822 of symlinks) that ends with a socket also causes the function to return
5823 true.
5824 See also "stat".
5826 This command has one or more optional arguments. See "OPTIONAL
5828 ARGUMENTS".
5829 is-symlink
5831 is-symlink path
5832 This returns "true" if and only if there is a symbolic link with the
5834 given "path" name.
5835 See also "stat".
5837 is-whole-device
5839 is-whole-device device
5840 This returns "true" if and only if "device" refers to a whole block
5842 device. That is, not a partition or a logical device.
5843 is-zero
5845 is-zero path
5846 This returns true iff the file exists and the file is empty or it
5848 contains all zero bytes.
5849 is-zero-device
5851 is-zero-device device
5852 This returns true iff the device exists and contains all zero bytes.
5854 Note that for large devices this can take a long time to run.
5856 isoinfo
5858 isoinfo isofile
5859 This is the same as "isoinfo-device" except that it works for an ISO
5861 file located inside some other mounted filesystem. Note that in the
5862 common case where you have added an ISO file as a libguestfs device,
5863 you would not call this. Instead you would call "isoinfo-device".
5864 isoinfo-device
5866 isoinfo-device device
5867 "device" is an ISO device. This returns a struct of information read
5869 from the primary volume descriptor (the ISO equivalent of the
5870 superblock) of the device.
5871 Usually it is more efficient to use the isoinfo(1) command with the -d
5873 option on the host to analyze ISO files, instead of going through
5874 libguestfs.
5875 For information on the primary volume descriptor fields, see
5877 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
5878 journal-close
5880 journal-close
5881 Close the journal handle.
5883 This command depends on the feature "journal". See also "feature-
5885 available".
5886 journal-get
5888 journal-get
5889 Read the current journal entry. This returns all the fields in the
5891 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
5892 field name (a string).
5893 The "attrval" is the field value (a binary blob, often but not always a
5895 string). Please note that "attrval" is a byte array, not a
5896 \0-terminated C string.
5897 The length of data may be truncated to the data threshold (see:
5899 "journal-set-data-threshold", "journal-get-data-threshold").
5900 If you set the data threshold to unlimited (0) then this call can read
5902 a journal entry of any size, ie. it is not limited by the libguestfs
5903 protocol.
5904 This command depends on the feature "journal". See also "feature-
5906 available".
5907 journal-get-data-threshold
5909 journal-get-data-threshold
5910 Get the current data threshold for reading journal entries. This is a
5912 hint to the journal that it may truncate data fields to this size when
5913 reading them (note also that it may not truncate them). If this
5914 returns 0, then the threshold is unlimited.
5915 See also "journal-set-data-threshold".
5917 This command depends on the feature "journal". See also "feature-
5919 available".
5920 journal-get-realtime-usec
5922 journal-get-realtime-usec
5923 Get the realtime (wallclock) timestamp of the current journal entry.
5925 This command depends on the feature "journal". See also "feature-
5927 available".
5928 journal-next
5930 journal-next
5931 Move to the next journal entry. You have to call this at least once
5933 after opening the handle before you are able to read data.
5934 The returned boolean tells you if there are any more journal records to
5936 read. "true" means you can read the next record (eg. using "journal-
5937 get"), and "false" means you have reached the end of the journal.
5938 This command depends on the feature "journal". See also "feature-
5940 available".
5941 journal-open
5943 journal-open directory
5944 Open the systemd journal located in directory. Any previously opened
5946 journal handle is closed.
5947 The contents of the journal can be read using "journal-next" and
5949 "journal-get".
5950 After you have finished using the journal, you should close the handle
5952 by calling "journal-close".
5953 This command depends on the feature "journal". See also "feature-
5955 available".
5956 journal-set-data-threshold
5958 journal-set-data-threshold threshold
5959 Set the data threshold for reading journal entries. This is a hint to
5961 the journal that it may truncate data fields to this size when reading
5962 them (note also that it may not truncate them). If you set this to 0,
5963 then the threshold is unlimited.
5964 See also "journal-get-data-threshold".
5966 This command depends on the feature "journal". See also "feature-
5968 available".
5969 journal-skip
5971 journal-skip skip
5972 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
5974 The number of entries actually skipped is returned (note "rskip ≥ 0").
5976 If this is not the same as the absolute value of the skip parameter
5977 ("|skip|") you passed in then it means you have reached the end or the
5978 start of the journal.
5979 This command depends on the feature "journal". See also "feature-
5981 available".
5982 kill-subprocess
5984 kill-subprocess
5985 This kills the hypervisor.
5987 Do not call this. See: "shutdown" instead.
5989 This function is deprecated. In new code, use the "shutdown" call
5991 instead.
5992 Deprecated functions will not be removed from the API, but the fact
5994 that they are deprecated indicates that there are problems with correct
5995 use of these functions.
5996 launch
5998 run
5999 launch
6000 You should call this after configuring the handle (eg. adding drives)
6002 but before performing any actions.
6003 Do not call "launch" twice on the same handle. Although it will not
6005 give an error (for historical reasons), the precise behaviour when you
6006 do this is not well defined. Handles are very cheap to create, so
6007 create a new one for each launch.
6008 lchown
6010 lchown owner group path
6011 Change the file owner to "owner" and group to "group". This is like
6013 "chown" but if "path" is a symlink then the link itself is changed, not
6014 the target.
6015 Only numeric uid and gid are supported. If you want to use names, you
6017 will need to locate and parse the password file yourself (Augeas
6018 support makes this relatively easy).
6019 ldmtool-create-all
6021 ldmtool-create-all
6022 This function scans all block devices looking for Windows dynamic disk
6024 volumes and partitions, and creates devices for any that were found.
6025 Call "list-ldm-volumes" and "list-ldm-partitions" to return all
6027 devices.
6028 Note that you don't normally need to call this explicitly, since it is
6030 done automatically at "launch" time. However you might want to call
6031 this function if you have hotplugged disks or have just created a
6032 Windows dynamic disk.
6033 This command depends on the feature "ldm". See also "feature-
6035 available".
6036 ldmtool-diskgroup-disks
6038 ldmtool-diskgroup-disks diskgroup
6039 Return the disks in a Windows dynamic disk group. The "diskgroup"
6041 parameter should be the GUID of a disk group, one element from the list
6042 returned by "ldmtool-scan".
6043 This command depends on the feature "ldm". See also "feature-
6045 available".
6046 ldmtool-diskgroup-name
6048 ldmtool-diskgroup-name diskgroup
6049 Return the name of a Windows dynamic disk group. The "diskgroup"
6051 parameter should be the GUID of a disk group, one element from the list
6052 returned by "ldmtool-scan".
6053 This command depends on the feature "ldm". See also "feature-
6055 available".
6056 ldmtool-diskgroup-volumes
6058 ldmtool-diskgroup-volumes diskgroup
6059 Return the volumes in a Windows dynamic disk group. The "diskgroup"
6061 parameter should be the GUID of a disk group, one element from the list
6062 returned by "ldmtool-scan".
6063 This command depends on the feature "ldm". See also "feature-
6065 available".
6066 ldmtool-remove-all
6068 ldmtool-remove-all
6069 This is essentially the opposite of "ldmtool-create-all". It removes
6071 the device mapper mappings for all Windows dynamic disk volumes
6072 This command depends on the feature "ldm". See also "feature-
6074 available".
6075 ldmtool-scan
6077 ldmtool-scan
6078 This function scans for Windows dynamic disks. It returns a list of
6080 identifiers (GUIDs) for all disk groups that were found. These
6081 identifiers can be passed to other "ldmtool-*" functions.
6082 This function scans all block devices. To scan a subset of block
6084 devices, call "ldmtool-scan-devices" instead.
6085 This command depends on the feature "ldm". See also "feature-
6087 available".
6088 ldmtool-scan-devices
6090 ldmtool-scan-devices 'devices ...'
6091 This function scans for Windows dynamic disks. It returns a list of
6093 identifiers (GUIDs) for all disk groups that were found. These
6094 identifiers can be passed to other "ldmtool-*" functions.
6095 The parameter "devices" is a list of block devices which are scanned.
6097 If this list is empty, all block devices are scanned.
6098 This command depends on the feature "ldm". See also "feature-
6100 available".
6101 ldmtool-volume-hint
6103 ldmtool-volume-hint diskgroup volume
6104 Return the hint field of the volume named "volume" in the disk group
6106 with GUID "diskgroup". This may not be defined, in which case the
6107 empty string is returned. The hint field is often, though not always,
6108 the name of a Windows drive, eg. "E:".
6109 This command depends on the feature "ldm". See also "feature-
6111 available".
6112 ldmtool-volume-partitions
6114 ldmtool-volume-partitions diskgroup volume
6115 Return the list of partitions in the volume named "volume" in the disk
6117 group with GUID "diskgroup".
6118 This command depends on the feature "ldm". See also "feature-
6120 available".
6121 ldmtool-volume-type
6123 ldmtool-volume-type diskgroup volume
6124 Return the type of the volume named "volume" in the disk group with
6126 GUID "diskgroup".
6127 Possible volume types that can be returned here include: "simple",
6129 "spanned", "striped", "mirrored", "raid5". Other types may also be
6130 returned.
6131 This command depends on the feature "ldm". See also "feature-
6133 available".
6134 lgetxattr
6136 lgetxattr path name
6137 Get a single extended attribute from file "path" named "name". If
6139 "path" is a symlink, then this call returns an extended attribute from
6140 the symlink.
6141 Normally it is better to get all extended attributes from a file in one
6143 go by calling "getxattrs". However some Linux filesystem
6144 implementations are buggy and do not provide a way to list out
6145 attributes. For these filesystems (notably ntfs-3g) you have to know
6146 the names of the extended attributes you want in advance and call this
6147 function.
6148 Extended attribute values are blobs of binary data. If there is no
6150 extended attribute named "name", this returns an error.
6151 See also: "lgetxattrs", "getxattr", attr(5).
6153 This command depends on the feature "linuxxattrs". See also "feature-
6155 available".
6156 lgetxattrs
6158 lgetxattrs path
6159 This is the same as "getxattrs", but if "path" is a symbolic link, then
6161 it returns the extended attributes of the link itself.
6162 This command depends on the feature "linuxxattrs". See also "feature-
6164 available".
6165 list-9p
6167 list-9p
6168 List all 9p filesystems attached to the guest. A list of mount tags is
6170 returned.
6171 list-devices
6173 list-devices
6174 List all the block devices.
6176 The full block device names are returned, eg. /dev/sda.
6178 See also "list-filesystems".
6180 list-disk-labels
6182 list-disk-labels
6183 If you add drives using the optional "label" parameter of "add-drive-
6185 opts", you can use this call to map between disk labels, and raw block
6186 device and partition names (like /dev/sda and /dev/sda1).
6187 This returns a hashtable, where keys are the disk labels (without the
6189 /dev/disk/guestfs prefix), and the values are the full raw block device
6190 and partition names (eg. /dev/sda and /dev/sda1).
6191 list-dm-devices
6193 list-dm-devices
6194 List all device mapper devices.
6196 The returned list contains /dev/mapper/* devices, eg. ones created by a
6198 previous call to "luks-open".
6199 Device mapper devices which correspond to logical volumes are not
6201 returned in this list. Call "lvs" if you want to list logical volumes.
6202 list-filesystems
6204 list-filesystems
6205 This inspection command looks for filesystems on partitions, block
6207 devices and logical volumes, returning a list of "mountables"
6208 containing filesystems and their type.
6209 The return value is a hash, where the keys are the devices containing
6211 filesystems, and the values are the filesystem types. For example:
6212 "/dev/sda1" => "ntfs"
6214 "/dev/sda2" => "ext2"
6215 "/dev/vg_guest/lv_root" => "ext4"
6216 "/dev/vg_guest/lv_swap" => "swap"
6217 The key is not necessarily a block device. It may also be an opaque
6219 ‘mountable’ string which can be passed to "mount".
6220 The value can have the special value "unknown", meaning the content of
6222 the device is undetermined or empty. "swap" means a Linux swap
6223 partition.
6224 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
6226 might have included "mount" and "umount", and therefore you had to use
6227 this soon after launch and only when nothing else was mounted. This
6228 restriction is removed in libguestfs ≥ 1.38.
6229 Not all of the filesystems returned will be mountable. In particular,
6231 swap partitions are returned in the list. Also this command does not
6232 check that each filesystem found is valid and mountable, and some
6233 filesystems might be mountable but require special options.
6234 Filesystems may not all belong to a single logical operating system
6235 (use "inspect-os" to look for OSes).
6236 list-ldm-partitions
6238 list-ldm-partitions
6239 This function returns all Windows dynamic disk partitions that were
6241 found at launch time. It returns a list of device names.
6242 This command depends on the feature "ldm". See also "feature-
6244 available".
6245 list-ldm-volumes
6247 list-ldm-volumes
6248 This function returns all Windows dynamic disk volumes that were found
6250 at launch time. It returns a list of device names.
6251 This command depends on the feature "ldm". See also "feature-
6253 available".
6254 list-md-devices
6256 list-md-devices
6257 List all Linux md devices.
6259 list-partitions
6261 list-partitions
6262 List all the partitions detected on all block devices.
6264 The full partition device names are returned, eg. /dev/sda1
6266 This does not return logical volumes. For that you will need to call
6268 "lvs".
6269 See also "list-filesystems".
6271 ll
6273 ll directory
6274 List the files in directory (relative to the root directory, there is
6276 no cwd) in the format of "ls -la".
6277 This command is mostly useful for interactive sessions. It is not
6279 intended that you try to parse the output string.
6280 llz
6282 llz directory
6283 List the files in directory in the format of "ls -laZ".
6285 This command is mostly useful for interactive sessions. It is not
6287 intended that you try to parse the output string.
6288 This function is deprecated. In new code, use the "lgetxattrs" call
6290 instead.
6291 Deprecated functions will not be removed from the API, but the fact
6293 that they are deprecated indicates that there are problems with correct
6294 use of these functions.
6295 ln
6297 ln target linkname
6298 This command creates a hard link.
6300 ln-f
6302 ln-f target linkname
6303 This command creates a hard link, removing the link "linkname" if it
6305 exists already.
6306 ln-s
6308 ln-s target linkname
6309 This command creates a symbolic link using the "ln -s" command.
6311 ln-sf
6313 ln-sf target linkname
6314 This command creates a symbolic link using the "ln -sf" command, The -f
6316 option removes the link ("linkname") if it exists already.
6317 lremovexattr
6319 lremovexattr xattr path
6320 This is the same as "removexattr", but if "path" is a symbolic link,
6322 then it removes an extended attribute of the link itself.
6323 This command depends on the feature "linuxxattrs". See also "feature-
6325 available".
6326 ls
6328 ls directory
6329 List the files in directory (relative to the root directory, there is
6331 no cwd). The "." and ".." entries are not returned, but hidden files
6332 are shown.
6333 ls0
6335 ls0 dir (filenames|-)
6336 This specialized command is used to get a listing of the filenames in
6338 the directory "dir". The list of filenames is written to the local
6339 file filenames (on the host).
6340 In the output file, the filenames are separated by "\0" characters.
6342 "." and ".." are not returned. The filenames are not sorted.
6344 Use "-" instead of a filename to read/write from stdin/stdout.
6346 lsetxattr
6348 lsetxattr xattr val vallen path
6349 This is the same as "setxattr", but if "path" is a symbolic link, then
6351 it sets an extended attribute of the link itself.
6352 This command depends on the feature "linuxxattrs". See also "feature-
6354 available".
6355 lstat
6357 lstat path
6358 Returns file information for the given "path".
6360 This is the same as "stat" except that if "path" is a symbolic link,
6362 then the link is stat-ed, not the file it refers to.
6363 This is the same as the lstat(2) system call.
6365 This function is deprecated. In new code, use the "lstatns" call
6367 instead.
6368 Deprecated functions will not be removed from the API, but the fact
6370 that they are deprecated indicates that there are problems with correct
6371 use of these functions.
6372 lstatlist
6374 lstatlist path 'names ...'
6375 This call allows you to perform the "lstat" operation on multiple
6377 files, where all files are in the directory "path". "names" is the
6378 list of files from this directory.
6379 On return you get a list of stat structs, with a one-to-one
6381 correspondence to the "names" list. If any name did not exist or could
6382 not be lstat'd, then the "st_ino" field of that structure is set to
6383 "-1".
6384 This call is intended for programs that want to efficiently list a
6386 directory contents without making many round-trips. See also
6387 "lxattrlist" for a similarly efficient call for getting extended
6388 attributes.
6389 This function is deprecated. In new code, use the "lstatnslist" call
6391 instead.
6392 Deprecated functions will not be removed from the API, but the fact
6394 that they are deprecated indicates that there are problems with correct
6395 use of these functions.
6396 lstatns
6398 lstatns path
6399 Returns file information for the given "path".
6401 This is the same as "statns" except that if "path" is a symbolic link,
6403 then the link is stat-ed, not the file it refers to.
6404 This is the same as the lstat(2) system call.
6406 lstatnslist
6408 lstatnslist path 'names ...'
6409 This call allows you to perform the "lstatns" operation on multiple
6411 files, where all files are in the directory "path". "names" is the
6412 list of files from this directory.
6413 On return you get a list of stat structs, with a one-to-one
6415 correspondence to the "names" list. If any name did not exist or could
6416 not be lstat'd, then the "st_ino" field of that structure is set to
6417 "-1".
6418 This call is intended for programs that want to efficiently list a
6420 directory contents without making many round-trips. See also
6421 "lxattrlist" for a similarly efficient call for getting extended
6422 attributes.
6423 luks-add-key
6425 luks-add-key device keyslot
6426 This command adds a new key on LUKS device "device". "key" is any
6428 existing key, and is used to access the device. "newkey" is the new
6429 key to add. "keyslot" is the key slot that will be replaced.
6430 Note that if "keyslot" already contains a key, then this command will
6432 fail. You have to use "luks-kill-slot" first to remove that key.
6433 This command has one or more key or passphrase parameters. Guestfish
6435 will prompt for these separately.
6436 This command depends on the feature "luks". See also "feature-
6438 available".
6439 luks-close
6441 luks-close device
6442 This closes a LUKS device that was created earlier by "luks-open" or
6444 "luks-open-ro". The "device" parameter must be the name of the LUKS
6445 mapping device (ie. /dev/mapper/mapname) and not the name of the
6446 underlying block device.
6447 This function is deprecated. In new code, use the "cryptsetup-close"
6449 call instead.
6450 Deprecated functions will not be removed from the API, but the fact
6452 that they are deprecated indicates that there are problems with correct
6453 use of these functions.
6454 This command depends on the feature "luks". See also "feature-
6456 available".
6457 luks-format
6459 luks-format device keyslot
6460 This command erases existing data on "device" and formats the device as
6462 a LUKS encrypted device. "key" is the initial key, which is added to
6463 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
6464 This command has one or more key or passphrase parameters. Guestfish
6466 will prompt for these separately.
6467 This command depends on the feature "luks". See also "feature-
6469 available".
6470 luks-format-cipher
6472 luks-format-cipher device keyslot cipher
6473 This command is the same as "luks-format" but it also allows you to set
6475 the "cipher" used.
6476 This command has one or more key or passphrase parameters. Guestfish
6478 will prompt for these separately.
6479 This command depends on the feature "luks". See also "feature-
6481 available".
6482 luks-kill-slot
6484 luks-kill-slot device keyslot
6485 This command deletes the key in key slot "keyslot" from the encrypted
6487 LUKS device "device". "key" must be one of the other keys.
6488 This command has one or more key or passphrase parameters. Guestfish
6490 will prompt for these separately.
6491 This command depends on the feature "luks". See also "feature-
6493 available".
6494 luks-open
6496 luks-open device mapname
6497 This command opens a block device which has been encrypted according to
6499 the Linux Unified Key Setup (LUKS) standard.
6500 "device" is the encrypted block device or partition.
6502 The caller must supply one of the keys associated with the LUKS block
6504 device, in the "key" parameter.
6505 This creates a new block device called /dev/mapper/mapname. Reads and
6507 writes to this block device are decrypted from and encrypted to the
6508 underlying "device" respectively.
6509 If this block device contains LVM volume groups, then calling "lvm-
6511 scan" with the "activate" parameter "true" will make them visible.
6512 Use "list-dm-devices" to list all device mapper devices.
6514 This command has one or more key or passphrase parameters. Guestfish
6516 will prompt for these separately.
6517 This function is deprecated. In new code, use the "cryptsetup-open"
6519 call instead.
6520 Deprecated functions will not be removed from the API, but the fact
6522 that they are deprecated indicates that there are problems with correct
6523 use of these functions.
6524 This command depends on the feature "luks". See also "feature-
6526 available".
6527 luks-open-ro
6529 luks-open-ro device mapname
6530 This is the same as "luks-open" except that a read-only mapping is
6532 created.
6533 This command has one or more key or passphrase parameters. Guestfish
6535 will prompt for these separately.
6536 This function is deprecated. In new code, use the "cryptsetup-open"
6538 call instead.
6539 Deprecated functions will not be removed from the API, but the fact
6541 that they are deprecated indicates that there are problems with correct
6542 use of these functions.
6543 This command depends on the feature "luks". See also "feature-
6545 available".
6546 luks-uuid
6548 luks-uuid device
6549 This returns the UUID of the LUKS device "device".
6551 This command depends on the feature "luks". See also "feature-
6553 available".
6554 lvcreate
6556 lvcreate logvol volgroup mbytes
6557 This creates an LVM logical volume called "logvol" on the volume group
6559 "volgroup", with "size" megabytes.
6560 This command depends on the feature "lvm2". See also "feature-
6562 available".
6563 lvcreate-free
6565 lvcreate-free logvol volgroup percent
6566 Create an LVM logical volume called /dev/volgroup/logvol, using
6568 approximately "percent" % of the free space remaining in the volume
6569 group. Most usefully, when "percent" is 100 this will create the
6570 largest possible LV.
6571 This command depends on the feature "lvm2". See also "feature-
6573 available".
6574 lvm-canonical-lv-name
6576 lvm-canonical-lv-name lvname
6577 This converts alternative naming schemes for LVs that you might find to
6579 the canonical name. For example, /dev/mapper/VG-LV is converted to
6580 /dev/VG/LV.
6581 This command returns an error if the "lvname" parameter does not refer
6583 to a logical volume. In this case errno will be set to "EINVAL".
6584 See also "is-lv", "canonical-device-name".
6586 lvm-clear-filter
6588 lvm-clear-filter
6589 This undoes the effect of "lvm-set-filter". LVM will be able to see
6591 every block device.
6592 This command also clears the LVM cache and performs a volume group
6594 scan.
6595 lvm-remove-all
6597 lvm-remove-all
6598 This command removes all LVM logical volumes, volume groups and
6600 physical volumes.
6601 This command depends on the feature "lvm2". See also "feature-
6603 available".
6604 lvm-scan
6606 lvm-scan true|false
6607 This scans all block devices and rebuilds the list of LVM physical
6609 volumes, volume groups and logical volumes.
6610 If the "activate" parameter is "true" then newly found volume groups
6612 and logical volumes are activated, meaning the LV /dev/VG/LV devices
6613 become visible.
6614 When a libguestfs handle is launched it scans for existing devices, so
6616 you do not normally need to use this API. However it is useful when
6617 you have added a new device or deleted an existing device (such as when
6618 the "luks-open" API is used).
6619 lvm-set-filter
6621 lvm-set-filter 'devices ...'
6622 This sets the LVM device filter so that LVM will only be able to "see"
6624 the block devices in the list "devices", and will ignore all other
6625 attached block devices.
6626 Where disk image(s) contain duplicate PVs or VGs, this command is
6628 useful to get LVM to ignore the duplicates, otherwise LVM can get
6629 confused. Note also there are two types of duplication possible:
6630 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
6631 cloned but just happen to have the same name. In normal operation you
6632 cannot create this situation, but you can do it outside LVM, eg. by
6633 cloning disk images or by bit twiddling inside the LVM metadata.
6634 This command also clears the LVM cache and performs a volume group
6636 scan.
6637 You can filter whole block devices or individual partitions.
6639 You cannot use this if any VG is currently in use (eg. contains a
6641 mounted filesystem), even if you are not filtering out that VG.
6642 This command depends on the feature "lvm2". See also "feature-
6644 available".
6645 lvremove
6647 lvremove device
6648 Remove an LVM logical volume "device", where "device" is the path to
6650 the LV, such as /dev/VG/LV.
6651 You can also remove all LVs in a volume group by specifying the VG
6653 name, /dev/VG.
6654 This command depends on the feature "lvm2". See also "feature-
6656 available".
6657 lvrename
6659 lvrename logvol newlogvol
6660 Rename a logical volume "logvol" with the new name "newlogvol".
6662 lvresize
6664 lvresize device mbytes
6665 This resizes (expands or shrinks) an existing LVM logical volume to
6667 "mbytes". When reducing, data in the reduced part is lost.
6668 This command depends on the feature "lvm2". See also "feature-
6670 available".
6671 lvresize-free
6673 lvresize-free lv percent
6674 This expands an existing logical volume "lv" so that it fills "pc" % of
6676 the remaining free space in the volume group. Commonly you would call
6677 this with pc = 100 which expands the logical volume as much as
6678 possible, using all remaining free space in the volume group.
6679 This command depends on the feature "lvm2". See also "feature-
6681 available".
6682 lvs
6684 lvs
6685 List all the logical volumes detected. This is the equivalent of the
6687 lvs(8) command.
6688 This returns a list of the logical volume device names (eg.
6690 /dev/VolGroup00/LogVol00).
6691 See also "lvs-full", "list-filesystems".
6693 This command depends on the feature "lvm2". See also "feature-
6695 available".
6696 lvs-full
6698 lvs-full
6699 List all the logical volumes detected. This is the equivalent of the
6701 lvs(8) command. The "full" version includes all fields.
6702 This command depends on the feature "lvm2". See also "feature-
6704 available".
6705 lvuuid
6707 lvuuid device
6708 This command returns the UUID of the LVM LV "device".
6710 lxattrlist
6712 lxattrlist path 'names ...'
6713 This call allows you to get the extended attributes of multiple files,
6715 where all files are in the directory "path". "names" is the list of
6716 files from this directory.
6717 On return you get a flat list of xattr structs which must be
6719 interpreted sequentially. The first xattr struct always has a zero-
6720 length "attrname". "attrval" in this struct is zero-length to indicate
6721 there was an error doing "lgetxattr" for this file, or is a C string
6722 which is a decimal number (the number of following attributes for this
6723 file, which could be "0"). Then after the first xattr struct are the
6724 zero or more attributes for the first named file. This repeats for the
6725 second and subsequent files.
6726 This call is intended for programs that want to efficiently list a
6728 directory contents without making many round-trips. See also
6729 "lstatlist" for a similarly efficient call for getting standard stats.
6730 This command depends on the feature "linuxxattrs". See also "feature-
6732 available".
6733 max-disks
6735 max-disks
6736 Return the maximum number of disks that may be added to a handle (eg.
6738 by "add-drive-opts" and similar calls).
6739 This function was added in libguestfs 1.19.7. In previous versions of
6741 libguestfs the limit was 25.
6742 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
6744 on this topic.
6745 md-create
6747 md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
6748 Create a Linux md (RAID) device named "name" on the devices in the list
6750 "devices".
6751 The optional parameters are:
6753 "missingbitmap"
6755 A bitmap of missing devices. If a bit is set it means that a
6756 missing device is added to the array. The least significant bit
6757 corresponds to the first device in the array.
6758 As examples:
6760 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
6762 resulting array would be "[<missing>, "/dev/sda"]".
6763 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
6765 resulting array would be "["/dev/sda", <missing>]".
6766 This defaults to 0 (no missing devices).
6768 The length of "devices" + the number of bits set in "missingbitmap"
6770 must equal "nrdevices" + "spare".
6771 "nrdevices"
6773 The number of active RAID devices.
6774 If not set, this defaults to the length of "devices" plus the
6776 number of bits set in "missingbitmap".
6777 "spare"
6779 The number of spare devices.
6780 If not set, this defaults to 0.
6782 "chunk"
6784 The chunk size in bytes.
6785 "level"
6787 The RAID level, which can be one of: "linear", "raid0", 0,
6788 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
6789 "raid10", 10. Some of these are synonymous, and more levels may be
6790 added in future.
6791 If not set, this defaults to "raid1".
6793 This command has one or more optional arguments. See "OPTIONAL
6795 ARGUMENTS".
6796 This command depends on the feature "mdadm". See also "feature-
6798 available".
6799 md-detail
6801 md-detail md
6802 This command exposes the output of "mdadm -DY <md>". The following
6804 fields are usually present in the returned hash. Other fields may also
6805 be present.
6806 "level"
6808 The raid level of the MD device.
6809 "devices"
6811 The number of underlying devices in the MD device.
6812 "metadata"
6814 The metadata version used.
6815 "uuid"
6817 The UUID of the MD device.
6818 "name"
6820 The name of the MD device.
6821 This command depends on the feature "mdadm". See also "feature-
6823 available".
6824 md-stat
6826 md-stat md
6827 This call returns a list of the underlying devices which make up the
6829 single software RAID array device "md".
6830 To get a list of software RAID devices, call "list-md-devices".
6832 Each structure returned corresponds to one device along with additional
6834 status information:
6835 "mdstat_device"
6837 The name of the underlying device.
6838 "mdstat_index"
6840 The index of this device within the array.
6841 "mdstat_flags"
6843 Flags associated with this device. This is a string containing (in
6844 no specific order) zero or more of the following flags:
6845 "W" write-mostly
6847 "F" device is faulty
6849 "S" device is a RAID spare
6851 "R" replacement
6853 This command depends on the feature "mdadm". See also "feature-
6855 available".
6856 md-stop
6858 md-stop md
6859 This command deactivates the MD array named "md". The device is
6861 stopped, but it is not destroyed or zeroed.
6862 This command depends on the feature "mdadm". See also "feature-
6864 available".
6865 mkdir
6867 mkdir path
6868 Create a directory named "path".
6870 mkdir-mode
6872 mkdir-mode path mode
6873 This command creates a directory, setting the initial permissions of
6875 the directory to "mode".
6876 For common Linux filesystems, the actual mode which is set will be
6878 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
6879 the mode in other ways.
6880 See also "mkdir", "umask"
6882 mkdir-p
6884 mkdir-p path
6885 Create a directory named "path", creating any parent directories as
6887 necessary. This is like the "mkdir -p" shell command.
6888 mkdtemp
6890 mkdtemp tmpl
6891 This command creates a temporary directory. The "tmpl" parameter
6893 should be a full pathname for the temporary directory name with the
6894 final six characters being "XXXXXX".
6895 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
6897 one being suitable for Windows filesystems.
6898 The name of the temporary directory that was created is returned.
6900 The temporary directory is created with mode 0700 and is owned by root.
6902 The caller is responsible for deleting the temporary directory and its
6904 contents after use.
6905 See also: mkdtemp(3)
6907 mke2fs
6909 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]
6910 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
6912 "device".
6913 The optional "blockscount" is the size of the filesystem in blocks. If
6915 omitted it defaults to the size of "device". Note if the filesystem is
6916 too small to contain a journal, "mke2fs" will silently create an ext2
6917 filesystem instead.
6918 This command has one or more optional arguments. See "OPTIONAL
6920 ARGUMENTS".
6921 mke2fs-J
6923 mke2fs-J fstype blocksize device journal
6924 This creates an ext2/3/4 filesystem on "device" with an external
6926 journal on "journal". It is equivalent to the command:
6927 mke2fs -t fstype -b blocksize -J device=<journal> <device>
6929 See also "mke2journal".
6931 This function is deprecated. In new code, use the "mke2fs" call
6933 instead.
6934 Deprecated functions will not be removed from the API, but the fact
6936 that they are deprecated indicates that there are problems with correct
6937 use of these functions.
6938 mke2fs-JL
6940 mke2fs-JL fstype blocksize device label
6941 This creates an ext2/3/4 filesystem on "device" with an external
6943 journal on the journal labeled "label".
6944 See also "mke2journal-L".
6946 This function is deprecated. In new code, use the "mke2fs" call
6948 instead.
6949 Deprecated functions will not be removed from the API, but the fact
6951 that they are deprecated indicates that there are problems with correct
6952 use of these functions.
6953 mke2fs-JU
6955 mke2fs-JU fstype blocksize device uuid
6956 This creates an ext2/3/4 filesystem on "device" with an external
6958 journal on the journal with UUID "uuid".
6959 See also "mke2journal-U".
6961 This function is deprecated. In new code, use the "mke2fs" call
6963 instead.
6964 Deprecated functions will not be removed from the API, but the fact
6966 that they are deprecated indicates that there are problems with correct
6967 use of these functions.
6968 This command depends on the feature "linuxfsuuid". See also "feature-
6970 available".
6971 mke2journal
6973 mke2journal blocksize device
6974 This creates an ext2 external journal on "device". It is equivalent to
6976 the command:
6977 mke2fs -O journal_dev -b blocksize device
6979 This function is deprecated. In new code, use the "mke2fs" call
6981 instead.
6982 Deprecated functions will not be removed from the API, but the fact
6984 that they are deprecated indicates that there are problems with correct
6985 use of these functions.
6986 mke2journal-L
6988 mke2journal-L blocksize label device
6989 This creates an ext2 external journal on "device" with label "label".
6991 This function is deprecated. In new code, use the "mke2fs" call
6993 instead.
6994 Deprecated functions will not be removed from the API, but the fact
6996 that they are deprecated indicates that there are problems with correct
6997 use of these functions.
6998 mke2journal-U
7000 mke2journal-U blocksize uuid device
7001 This creates an ext2 external journal on "device" with UUID "uuid".
7003 This function is deprecated. In new code, use the "mke2fs" call
7005 instead.
7006 Deprecated functions will not be removed from the API, but the fact
7008 that they are deprecated indicates that there are problems with correct
7009 use of these functions.
7010 This command depends on the feature "linuxfsuuid". See also "feature-
7012 available".
7013 mkfifo
7015 mkfifo mode path
7016 This call creates a FIFO (named pipe) called "path" with mode "mode".
7018 It is just a convenient wrapper around "mknod".
7019 Unlike with "mknod", "mode" must contain only permissions bits.
7021 The mode actually set is affected by the umask.
7023 This command depends on the feature "mknod". See also "feature-
7025 available".
7026 mkfs
7028 mkfs-opts
7029 mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N] [label:..]
7030 This function creates a filesystem on "device". The filesystem type is
7032 "fstype", for example "ext3".
7033 The optional arguments are:
7035 "blocksize"
7037 The filesystem block size. Supported block sizes depend on the
7038 filesystem type, but typically they are 1024, 2048 or 4096 for
7039 Linux ext2/3 filesystems.
7040 For VFAT and NTFS the "blocksize" parameter is treated as the
7042 requested cluster size.
7043 For UFS block sizes, please see mkfs.ufs(8).
7045 "features"
7047 This passes the -O parameter to the external mkfs program.
7048 For certain filesystem types, this allows extra filesystem features
7050 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
7051 You cannot use this optional parameter with the "gfs" or "gfs2"
7053 filesystem type.
7054 "inode"
7056 This passes the -I parameter to the external mke2fs(8) program
7057 which sets the inode size (only for ext2/3/4 filesystems at
7058 present).
7059 "sectorsize"
7061 This passes the -S parameter to external mkfs.ufs(8) program, which
7062 sets sector size for ufs filesystem.
7063 This command has one or more optional arguments. See "OPTIONAL
7065 ARGUMENTS".
7066 mkfs-b
7068 mkfs-b fstype blocksize device
7069 This call is similar to "mkfs", but it allows you to control the block
7071 size of the resulting filesystem. Supported block sizes depend on the
7072 filesystem type, but typically they are 1024, 2048 or 4096 only.
7073 For VFAT and NTFS the "blocksize" parameter is treated as the requested
7075 cluster size.
7076 This function is deprecated. In new code, use the "mkfs" call instead.
7078 Deprecated functions will not be removed from the API, but the fact
7080 that they are deprecated indicates that there are problems with correct
7081 use of these functions.
7082 mkfs-btrfs
7084 mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]
7085 Create a btrfs filesystem, allowing all configurables to be set. For
7087 more information on the optional arguments, see mkfs.btrfs(8).
7088 Since btrfs filesystems can span multiple devices, this takes a non-
7090 empty list of devices.
7091 To create general filesystems, use "mkfs".
7093 This command has one or more optional arguments. See "OPTIONAL
7095 ARGUMENTS".
7096 This command depends on the feature "btrfs". See also "feature-
7098 available".
7099 mklost-and-found
7101 mklost-and-found mountpoint
7102 Make the "lost+found" directory, normally in the root directory of an
7104 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
7105 to create the "lost+found" directory.
7106 mkmountpoint
7108 mkmountpoint exemptpath
7109 "mkmountpoint" and "rmmountpoint" are specialized calls that can be
7111 used to create extra mountpoints before mounting the first filesystem.
7112 These calls are only necessary in some very limited circumstances,
7114 mainly the case where you want to mount a mix of unrelated and/or read-
7115 only filesystems together.
7116 For example, live CDs often contain a "Russian doll" nest of
7118 filesystems, an ISO outer layer, with a squashfs image inside, with an
7119 ext2/3 image inside that. You can unpack this as follows in guestfish:
7120 add-ro Fedora-11-i686-Live.iso
7122 run
7123 mkmountpoint /cd
7124 mkmountpoint /sqsh
7125 mkmountpoint /ext3fs
7126 mount /dev/sda /cd
7127 mount-loop /cd/LiveOS/squashfs.img /sqsh
7128 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
7129 The inner filesystem is now unpacked under the /ext3fs mountpoint.
7131 "mkmountpoint" is not compatible with "umount-all". You may get
7133 unexpected errors if you try to mix these calls. It is safest to
7134 manually unmount filesystems and remove mountpoints after use.
7135 "umount-all" unmounts filesystems by sorting the paths longest first,
7137 so for this to work for manual mountpoints, you must ensure that the
7138 innermost mountpoints have the longest pathnames, as in the example
7139 code above.
7140 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
7142 Autosync [see "set-autosync", this is set by default on handles] can
7144 cause "umount-all" to be called when the handle is closed which can
7145 also trigger these issues.
7146 mknod
7148 mknod mode devmajor devminor path
7149 This call creates block or character special devices, or named pipes
7151 (FIFOs).
7152 The "mode" parameter should be the mode, using the standard constants.
7154 "devmajor" and "devminor" are the device major and minor numbers, only
7155 used when creating block and character special devices.
7156 Note that, just like mknod(2), the mode must be bitwise OR'd with
7158 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
7159 a regular file). These constants are available in the standard Linux
7160 header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
7161 wrappers around this command which bitwise OR in the appropriate
7162 constant for you.
7163 The mode actually set is affected by the umask.
7165 This command depends on the feature "mknod". See also "feature-
7167 available".
7168 mknod-b
7170 mknod-b mode devmajor devminor path
7171 This call creates a block device node called "path" with mode "mode"
7173 and device major/minor "devmajor" and "devminor". It is just a
7174 convenient wrapper around "mknod".
7175 Unlike with "mknod", "mode" must contain only permissions bits.
7177 The mode actually set is affected by the umask.
7179 This command depends on the feature "mknod". See also "feature-
7181 available".
7182 mknod-c
7184 mknod-c mode devmajor devminor path
7185 This call creates a char device node called "path" with mode "mode" and
7187 device major/minor "devmajor" and "devminor". It is just a convenient
7188 wrapper around "mknod".
7189 Unlike with "mknod", "mode" must contain only permissions bits.
7191 The mode actually set is affected by the umask.
7193 This command depends on the feature "mknod". See also "feature-
7195 available".
7196 mksquashfs
7198 mksquashfs path (filename|-) [compress:..] [excludes:..]
7199 Create a squashfs filesystem for the specified "path".
7201 The optional "compress" flag controls compression. If not given, then
7203 the output compressed using "gzip". Otherwise one of the following
7204 strings may be given to select the compression type of the squashfs:
7205 "gzip", "lzma", "lzo", "lz4", "xz".
7206 The other optional arguments are:
7208 "excludes"
7210 A list of wildcards. Files are excluded if they match any of the
7211 wildcards.
7212 Please note that this API may fail when used to compress directories
7214 with large files, such as the resulting squashfs will be over 3GB big.
7215 Use "-" instead of a filename to read/write from stdin/stdout.
7217 This command has one or more optional arguments. See "OPTIONAL
7219 ARGUMENTS".
7220 This command depends on the feature "squashfs". See also "feature-
7222 available".
7223 mkswap
7225 mkswap-opts
7226 mkswap device [label:..] [uuid:..]
7227 Create a Linux swap partition on "device".
7229 The option arguments "label" and "uuid" allow you to set the label
7231 and/or UUID of the new swap partition.
7232 This command has one or more optional arguments. See "OPTIONAL
7234 ARGUMENTS".
7235 mkswap-L
7237 mkswap-L label device
7238 Create a swap partition on "device" with label "label".
7240 Note that you cannot attach a swap label to a block device (eg.
7242 /dev/sda), just to a partition. This appears to be a limitation of the
7243 kernel or swap tools.
7244 This function is deprecated. In new code, use the "mkswap" call
7246 instead.
7247 Deprecated functions will not be removed from the API, but the fact
7249 that they are deprecated indicates that there are problems with correct
7250 use of these functions.
7251 mkswap-U
7253 mkswap-U uuid device
7254 Create a swap partition on "device" with UUID "uuid".
7256 This function is deprecated. In new code, use the "mkswap" call
7258 instead.
7259 Deprecated functions will not be removed from the API, but the fact
7261 that they are deprecated indicates that there are problems with correct
7262 use of these functions.
7263 This command depends on the feature "linuxfsuuid". See also "feature-
7265 available".
7266 mkswap-file
7268 mkswap-file path
7269 Create a swap file.
7271 This command just writes a swap file signature to an existing file. To
7273 create the file itself, use something like "fallocate".
7274 mktemp
7276 mktemp tmpl [suffix:..]
7277 This command creates a temporary file. The "tmpl" parameter should be
7279 a full pathname for the temporary directory name with the final six
7280 characters being "XXXXXX".
7281 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
7283 one being suitable for Windows filesystems.
7284 The name of the temporary file that was created is returned.
7286 The temporary file is created with mode 0600 and is owned by root.
7288 The caller is responsible for deleting the temporary file after use.
7290 If the optional "suffix" parameter is given, then the suffix (eg.
7292 ".txt") is appended to the temporary name.
7293 See also: "mkdtemp".
7295 This command has one or more optional arguments. See "OPTIONAL
7297 ARGUMENTS".
7298 modprobe
7300 modprobe modulename
7301 This loads a kernel module in the appliance.
7303 This command depends on the feature "linuxmodules". See also
7305 "feature-available".
7306 mount
7308 mount mountable mountpoint
7309 Mount a guest disk at a position in the filesystem. Block devices are
7311 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
7312 If those block devices contain partitions, they will have the usual
7313 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
7314 ‘mountable’ strings returned by "list-filesystems" or "inspect-get-
7315 mountpoints".
7316 The rules are the same as for mount(2): A filesystem must first be
7318 mounted on / before others can be mounted. Other filesystems can only
7319 be mounted on directories which already exist.
7320 The mounted filesystem is writable, if we have sufficient permissions
7322 on the underlying device.
7323 Before libguestfs 1.13.16, this call implicitly added the options
7325 "sync" and "noatime". The "sync" option greatly slowed writes and
7326 caused many problems for users. If your program might need to work
7327 with older versions of libguestfs, use "mount-options" instead (using
7328 an empty string for the first parameter if you don't want any options).
7329 mount-9p
7331 mount-9p mounttag mountpoint [options:..]
7332 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
7334 "mountpoint".
7335 If required, "trans=virtio" will be automatically added to the options.
7337 Any other options required can be passed in the optional "options"
7338 parameter.
7339 This command has one or more optional arguments. See "OPTIONAL
7341 ARGUMENTS".
7342 mount-local
7344 mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
7345 This call exports the libguestfs-accessible filesystem to a local
7347 mountpoint (directory) called "localmountpoint". Ordinary reads and
7348 writes to files and directories under "localmountpoint" are redirected
7349 through libguestfs.
7350 If the optional "readonly" flag is set to true, then writes to the
7352 filesystem return error "EROFS".
7353 "options" is a comma-separated list of mount options. See
7355 guestmount(1) for some useful options.
7356 "cachetimeout" sets the timeout (in seconds) for cached directory
7358 entries. The default is 60 seconds. See guestmount(1) for further
7359 information.
7360 If "debugcalls" is set to true, then additional debugging information
7362 is generated for every FUSE call.
7363 When "mount-local" returns, the filesystem is ready, but is not
7365 processing requests (access to it will block). You have to call
7366 "mount-local-run" to run the main loop.
7367 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7369 This command has one or more optional arguments. See "OPTIONAL
7371 ARGUMENTS".
7372 mount-local-run
7374 mount-local-run
7375 Run the main loop which translates kernel calls to libguestfs calls.
7377 This should only be called after "mount-local" returns successfully.
7379 The call will not return until the filesystem is unmounted.
7380 Note you must not make concurrent libguestfs calls on the same handle
7382 from another thread.
7383 You may call this from a different thread than the one which called
7385 "mount-local", subject to the usual rules for threads and libguestfs
7386 (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
7387 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7389 mount-loop
7391 mount-loop file mountpoint
7392 This command lets you mount file (a filesystem image in a file) on a
7394 mount point. It is entirely equivalent to the command "mount -o loop
7395 file mountpoint".
7396 mount-options
7398 mount-options options mountable mountpoint
7399 This is the same as the "mount" command, but it allows you to set the
7401 mount options as for the mount(8) -o flag.
7402 If the "options" parameter is an empty string, then no options are
7404 passed (all options default to whatever the filesystem uses).
7405 mount-ro
7407 mount-ro mountable mountpoint
7408 This is the same as the "mount" command, but it mounts the filesystem
7410 with the read-only (-o ro) flag.
7411 mount-vfs
7413 mount-vfs options vfstype mountable mountpoint
7414 This is the same as the "mount" command, but it allows you to set both
7416 the mount options and the vfstype as for the mount(8) -o and -t flags.
7417 mountable-device
7419 mountable-device mountable
7420 Returns the device name of a mountable. In quite a lot of cases, the
7422 mountable is the device name.
7423 However this doesn't apply for btrfs subvolumes, where the mountable is
7425 a combination of both the device name and the subvolume path (see also
7426 "mountable-subvolume" to extract the subvolume path of the mountable if
7427 any).
7428 mountable-subvolume
7430 mountable-subvolume mountable
7431 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
7433 are a combination of both the device name and the subvolume path (see
7434 also "mountable-device" to extract the device of the mountable).
7435 If the mountable does not represent a btrfs subvolume, then this
7437 function fails and the "errno" is set to "EINVAL".
7438 mountpoints
7440 mountpoints
7441 This call is similar to "mounts". That call returns a list of devices.
7443 This one returns a hash table (map) of device name to directory where
7444 the device is mounted.
7445 mounts
7447 mounts
7448 This returns the list of currently mounted filesystems. It returns the
7450 list of devices (eg. /dev/sda1, /dev/VG/LV).
7451 Some internal mounts are not shown.
7453 See also: "mountpoints"
7455 mv
7457 mv src dest
7458 This moves a file from "src" to "dest" where "dest" is either a
7460 destination filename or destination directory.
7461 See also: "rename".
7463 nr-devices
7465 nr-devices
7466 This returns the number of whole block devices that were added. This
7468 is the same as the number of devices that would be returned if you
7469 called "list-devices".
7470 To find out the maximum number of devices that could be added, call
7472 "max-disks".
7473 ntfs-3g-probe
7475 ntfs-3g-probe true|false device
7476 This command runs the ntfs-3g.probe(8) command which probes an NTFS
7478 "device" for mountability. (Not all NTFS volumes can be mounted read-
7479 write, and some cannot be mounted at all).
7480 "rw" is a boolean flag. Set it to true if you want to test if the
7482 volume can be mounted read-write. Set it to false if you want to test
7483 if the volume can be mounted read-only.
7484 The return value is an integer which 0 if the operation would succeed,
7486 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
7487 This command depends on the feature "ntfs3g". See also "feature-
7489 available".
7490 ntfscat-i
7492 ntfscat-i device inode (filename|-)
7493 Download a file given its inode from a NTFS filesystem and save it as
7495 filename on the local machine.
7496 This allows to download some otherwise inaccessible files such as the
7498 ones within the $Extend folder.
7499 The filesystem from which to extract the file must be unmounted,
7501 otherwise the call will fail.
7502 Use "-" instead of a filename to read/write from stdin/stdout.
7504 ntfsclone-in
7506 ntfsclone-in (backupfile|-) device
7507 Restore the "backupfile" (from a previous call to "ntfsclone-out") to
7509 "device", overwriting any existing contents of this device.
7510 Use "-" instead of a filename to read/write from stdin/stdout.
7512 This command depends on the feature "ntfs3g". See also "feature-
7514 available".
7515 ntfsclone-out
7517 ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
7518 Stream the NTFS filesystem "device" to the local file "backupfile".
7520 The format used for the backup file is a special format used by the
7521 ntfsclone(8) tool.
7522 If the optional "metadataonly" flag is true, then only the metadata is
7524 saved, losing all the user data (this is useful for diagnosing some
7525 filesystem problems).
7526 The optional "rescue", "ignorefscheck", "preservetimestamps" and
7528 "force" flags have precise meanings detailed in the ntfsclone(8) man
7529 page.
7530 Use "ntfsclone-in" to restore the file back to a libguestfs device.
7532 Use "-" instead of a filename to read/write from stdin/stdout.
7534 This command has one or more optional arguments. See "OPTIONAL
7536 ARGUMENTS".
7537 This command depends on the feature "ntfs3g". See also "feature-
7539 available".
7540 ntfsfix
7542 ntfsfix device [clearbadsectors:true|false]
7543 This command repairs some fundamental NTFS inconsistencies, resets the
7545 NTFS journal file, and schedules an NTFS consistency check for the
7546 first boot into Windows.
7547 This is not an equivalent of Windows "chkdsk". It does not scan the
7549 filesystem for inconsistencies.
7550 The optional "clearbadsectors" flag clears the list of bad sectors.
7552 This is useful after cloning a disk with bad sectors to a new disk.
7553 This command has one or more optional arguments. See "OPTIONAL
7555 ARGUMENTS".
7556 This command depends on the feature "ntfs3g". See also "feature-
7558 available".
7559 ntfsresize
7561 ntfsresize-opts
7562 ntfsresize device [size:N] [force:true|false]
7563 This command resizes an NTFS filesystem, expanding or shrinking it to
7565 the size of the underlying device.
7566 The optional parameters are:
7568 "size"
7570 The new size (in bytes) of the filesystem. If omitted, the
7571 filesystem is resized to fit the container (eg. partition).
7572 "force"
7574 If this option is true, then force the resize of the filesystem
7575 even if the filesystem is marked as requiring a consistency check.
7576 After the resize operation, the filesystem is always marked as
7578 requiring a consistency check (for safety). You have to boot into
7579 Windows to perform this check and clear this condition. If you
7580 don't set the "force" option then it is not possible to call
7581 "ntfsresize" multiple times on a single filesystem without booting
7582 into Windows between each resize.
7583 See also ntfsresize(8).
7585 This command has one or more optional arguments. See "OPTIONAL
7587 ARGUMENTS".
7588 This command depends on the feature "ntfsprogs". See also "feature-
7590 available".
7591 ntfsresize-size
7593 ntfsresize-size device size
7594 This command is the same as "ntfsresize" except that it allows you to
7596 specify the new size (in bytes) explicitly.
7597 This function is deprecated. In new code, use the "ntfsresize" call
7599 instead.
7600 Deprecated functions will not be removed from the API, but the fact
7602 that they are deprecated indicates that there are problems with correct
7603 use of these functions.
7604 This command depends on the feature "ntfsprogs". See also "feature-
7606 available".
7607 parse-environment
7609 parse-environment
7610 Parse the program’s environment and set flags in the handle
7612 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
7613 flag is set in the handle.
7614 Most programs do not need to call this. It is done implicitly when you
7616 call "create".
7617 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
7619 variables that can affect libguestfs handles. See also
7620 "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
7621 parse-environment-list
7623 parse-environment-list 'environment ...'
7624 Parse the list of strings in the argument "environment" and set flags
7626 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
7627 string in the list, then the ‘verbose’ flag is set in the handle.
7628 This is the same as "parse-environment" except that it parses an
7630 explicit list of strings instead of the program's environment.
7631 part-add
7633 part-add device prlogex startsect endsect
7634 This command adds a partition to "device". If there is no partition
7636 table on the device, call "part-init" first.
7637 The "prlogex" parameter is the type of partition. Normally you should
7639 pass "p" or "primary" here, but MBR partition tables also support "l"
7640 (or "logical") and "e" (or "extended") partition types.
7641 "startsect" and "endsect" are the start and end of the partition in
7643 sectors. "endsect" may be negative, which means it counts backwards
7644 from the end of the disk ("-1" is the last sector).
7645 Creating a partition which covers the whole disk is not so easy. Use
7647 "part-disk" to do that.
7648 part-del
7650 part-del device partnum
7651 This command deletes the partition numbered "partnum" on "device".
7653 Note that in the case of MBR partitioning, deleting an extended
7655 partition also deletes any logical partitions it contains.
7656 part-disk
7658 part-disk device parttype
7659 This command is simply a combination of "part-init" followed by "part-
7661 add" to create a single primary partition covering the whole disk.
7662 "parttype" is the partition table type, usually "mbr" or "gpt", but
7664 other possible values are described in "part-init".
7665 part-expand-gpt
7667 part-expand-gpt device
7668 Move backup GPT data structures to the end of the disk. This is useful
7670 in case of in-place image expand since disk space after backup GPT
7671 header is not usable. This is equivalent to "sgdisk -e".
7672 See also sgdisk(8).
7674 This command depends on the feature "gdisk". See also "feature-
7676 available".
7677 part-get-bootable
7679 part-get-bootable device partnum
7680 This command returns true if the partition "partnum" on "device" has
7682 the bootable flag set.
7683 See also "part-set-bootable".
7685 part-get-disk-guid
7687 part-get-disk-guid device
7688 Return the disk identifier (GUID) of a GPT-partitioned "device".
7690 Behaviour is undefined for other partition types.
7691 This command depends on the feature "gdisk". See also "feature-
7693 available".
7694 part-get-gpt-attributes
7696 part-get-gpt-attributes device partnum
7697 Return the attribute flags of numbered GPT partition "partnum". An
7699 error is returned for MBR partitions.
7700 This command depends on the feature "gdisk". See also "feature-
7702 available".
7703 part-get-gpt-guid
7705 part-get-gpt-guid device partnum
7706 Return the GUID of numbered GPT partition "partnum".
7708 This command depends on the feature "gdisk". See also "feature-
7710 available".
7711 part-get-gpt-type
7713 part-get-gpt-type device partnum
7714 Return the type GUID of numbered GPT partition "partnum". For MBR
7716 partitions, return an appropriate GUID corresponding to the MBR type.
7717 Behaviour is undefined for other partition types.
7718 This command depends on the feature "gdisk". See also "feature-
7720 available".
7721 part-get-mbr-id
7723 part-get-mbr-id device partnum
7724 Returns the MBR type byte (also known as the ID byte) from the numbered
7726 partition "partnum".
7727 Note that only MBR (old DOS-style) partitions have type bytes. You
7729 will get undefined results for other partition table types (see "part-
7730 get-parttype").
7731 part-get-mbr-part-type
7733 part-get-mbr-part-type device partnum
7734 This returns the partition type of an MBR partition numbered "partnum"
7736 on device "device".
7737 It returns "primary", "logical", or "extended".
7739 part-get-name
7741 part-get-name device partnum
7742 This gets the partition name on partition numbered "partnum" on device
7744 "device". Note that partitions are numbered from 1.
7745 The partition name can only be read on certain types of partition
7747 table. This works on "gpt" but not on "mbr" partitions.
7748 part-get-parttype
7750 part-get-parttype device
7751 This command examines the partition table on "device" and returns the
7753 partition table type (format) being used.
7754 Common return values include: "msdos" (a DOS/Windows style MBR
7756 partition table), "gpt" (a GPT/EFI-style partition table). Other
7757 values are possible, although unusual. See "part-init" for a full
7758 list.
7759 part-init
7761 part-init device parttype
7762 This creates an empty partition table on "device" of one of the
7764 partition types listed below. Usually "parttype" should be either
7765 "msdos" or "gpt" (for large disks).
7766 Initially there are no partitions. Following this, you should call
7768 "part-add" for each partition required.
7769 Possible values for "parttype" are:
7771 "efi"
7773 "gpt"
7774 Intel EFI / GPT partition table.
7775 This is recommended for >= 2 TB partitions that will be accessed
7777 from Linux and Intel-based Mac OS X. It also has limited backwards
7778 compatibility with the "mbr" format.
7779 "mbr"
7781 "msdos"
7782 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
7783 and Windows. This partition type will only work for device sizes
7784 up to 2 TB. For large disks we recommend using "gpt".
7785 Other partition table types that may work but are not supported
7787 include:
7788 "aix"
7790 AIX disk labels.
7791 "amiga"
7793 "rdb"
7794 Amiga "Rigid Disk Block" format.
7795 "bsd"
7797 BSD disk labels.
7798 "dasd"
7800 DASD, used on IBM mainframes.
7801 "dvh"
7803 MIPS/SGI volumes.
7804 "mac"
7806 Old Mac partition format. Modern Macs use "gpt".
7807 "pc98"
7809 NEC PC-98 format, common in Japan apparently.
7810 "sun"
7812 Sun disk labels.
7813 part-list
7815 part-list device
7816 This command parses the partition table on "device" and returns the
7818 list of partitions found.
7819 The fields in the returned structure are:
7821 "part_num"
7823 Partition number, counting from 1.
7824 "part_start"
7826 Start of the partition in bytes. To get sectors you have to divide
7827 by the device’s sector size, see "blockdev-getss".
7828 "part_end"
7830 End of the partition in bytes.
7831 "part_size"
7833 Size of the partition in bytes.
7834 part-resize
7836 part-resize device partnum endsect
7837 This command resizes the partition numbered "partnum" on "device" by
7839 moving the end position.
7840 Note that this does not modify any filesystem present in the partition.
7842 If you wish to do this, you will need to use filesystem resizing
7843 commands like "resize2fs".
7844 When growing a partition you will want to grow the filesystem
7846 afterwards, but when shrinking, you need to shrink the filesystem
7847 before the partition.
7848 part-set-bootable
7850 part-set-bootable device partnum true|false
7851 This sets the bootable flag on partition numbered "partnum" on device
7853 "device". Note that partitions are numbered from 1.
7854 The bootable flag is used by some operating systems (notably Windows)
7856 to determine which partition to boot from. It is by no means
7857 universally recognized.
7858 part-set-disk-guid
7860 part-set-disk-guid device guid
7861 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
7863 Return an error if the partition table of "device" isn't GPT, or if
7864 "guid" is not a valid GUID.
7865 This command depends on the feature "gdisk". See also "feature-
7867 available".
7868 part-set-disk-guid-random
7870 part-set-disk-guid-random device
7871 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
7873 randomly generated value. Return an error if the partition table of
7874 "device" isn't GPT.
7875 This command depends on the feature "gdisk". See also "feature-
7877 available".
7878 part-set-gpt-attributes
7880 part-set-gpt-attributes device partnum attributes
7881 Set the attribute flags of numbered GPT partition "partnum" to
7883 "attributes". Return an error if the partition table of "device" isn't
7884 GPT.
7885 See
7887 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
7888 for a useful list of partition attributes.
7889 This command depends on the feature "gdisk". See also "feature-
7891 available".
7892 part-set-gpt-guid
7894 part-set-gpt-guid device partnum guid
7895 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
7897 error if the partition table of "device" isn't GPT, or if "guid" is not
7898 a valid GUID.
7899 This command depends on the feature "gdisk". See also "feature-
7901 available".
7902 part-set-gpt-type
7904 part-set-gpt-type device partnum guid
7905 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
7907 an error if the partition table of "device" isn't GPT, or if "guid" is
7908 not a valid GUID.
7909 See
7911 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
7912 for a useful list of type GUIDs.
7913 This command depends on the feature "gdisk". See also "feature-
7915 available".
7916 part-set-mbr-id
7918 part-set-mbr-id device partnum idbyte
7919 Sets the MBR type byte (also known as the ID byte) of the numbered
7921 partition "partnum" to "idbyte". Note that the type bytes quoted in
7922 most documentation are in fact hexadecimal numbers, but usually
7923 documented without any leading "0x" which might be confusing.
7924 Note that only MBR (old DOS-style) partitions have type bytes. You
7926 will get undefined results for other partition table types (see "part-
7927 get-parttype").
7928 part-set-name
7930 part-set-name device partnum name
7931 This sets the partition name on partition numbered "partnum" on device
7933 "device". Note that partitions are numbered from 1.
7934 The partition name can only be set on certain types of partition table.
7936 This works on "gpt" but not on "mbr" partitions.
7937 part-to-dev
7939 part-to-dev partition
7940 This function takes a partition name (eg. "/dev/sdb1") and removes the
7942 partition number, returning the device name (eg. "/dev/sdb").
7943 The named partition must exist, for example as a string returned from
7945 "list-partitions".
7946 See also "part-to-partnum", "device-index".
7948 part-to-partnum
7950 part-to-partnum partition
7951 This function takes a partition name (eg. "/dev/sdb1") and returns the
7953 partition number (eg. 1).
7954 The named partition must exist, for example as a string returned from
7956 "list-partitions".
7957 See also "part-to-dev".
7959 ping-daemon
7961 ping-daemon
7962 This is a test probe into the guestfs daemon running inside the
7964 libguestfs appliance. Calling this function checks that the daemon
7965 responds to the ping message, without affecting the daemon or attached
7966 block device(s) in any other way.
7967 pread
7969 pread path count offset
7970 This command lets you read part of a file. It reads "count" bytes of
7972 the file, starting at "offset", from file "path".
7973 This may read fewer bytes than requested. For further details see the
7975 pread(2) system call.
7976 See also "pwrite", "pread-device".
7978 Because of the message protocol, there is a transfer limit of somewhere
7980 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7981 pread-device
7983 pread-device device count offset
7984 This command lets you read part of a block device. It reads "count"
7986 bytes of "device", starting at "offset".
7987 This may read fewer bytes than requested. For further details see the
7989 pread(2) system call.
7990 See also "pread".
7992 Because of the message protocol, there is a transfer limit of somewhere
7994 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7995 pvchange-uuid
7997 pvchange-uuid device
7998 Generate a new random UUID for the physical volume "device".
8000 This command depends on the feature "lvm2". See also "feature-
8002 available".
8003 pvchange-uuid-all
8005 pvchange-uuid-all
8006 Generate new random UUIDs for all physical volumes.
8008 This command depends on the feature "lvm2". See also "feature-
8010 available".
8011 pvcreate
8013 pvcreate device
8014 This creates an LVM physical volume on the named "device", where
8016 "device" should usually be a partition name such as /dev/sda1.
8017 This command depends on the feature "lvm2". See also "feature-
8019 available".
8020 pvremove
8022 pvremove device
8023 This wipes a physical volume "device" so that LVM will no longer
8025 recognise it.
8026 The implementation uses the pvremove(8) command which refuses to wipe
8028 physical volumes that contain any volume groups, so you have to remove
8029 those first.
8030 This command depends on the feature "lvm2". See also "feature-
8032 available".
8033 pvresize
8035 pvresize device
8036 This resizes (expands or shrinks) an existing LVM physical volume to
8038 match the new size of the underlying device.
8039 This command depends on the feature "lvm2". See also "feature-
8041 available".
8042 pvresize-size
8044 pvresize-size device size
8045 This command is the same as "pvresize" except that it allows you to
8047 specify the new size (in bytes) explicitly.
8048 This command depends on the feature "lvm2". See also "feature-
8050 available".
8051 pvs
8053 pvs
8054 List all the physical volumes detected. This is the equivalent of the
8056 pvs(8) command.
8057 This returns a list of just the device names that contain PVs (eg.
8059 /dev/sda2).
8060 See also "pvs-full".
8062 This command depends on the feature "lvm2". See also "feature-
8064 available".
8065 pvs-full
8067 pvs-full
8068 List all the physical volumes detected. This is the equivalent of the
8070 pvs(8) command. The "full" version includes all fields.
8071 This command depends on the feature "lvm2". See also "feature-
8073 available".
8074 pvuuid
8076 pvuuid device
8077 This command returns the UUID of the LVM PV "device".
8079 pwrite
8081 pwrite path content offset
8082 This command writes to part of a file. It writes the data buffer
8084 "content" to the file "path" starting at offset "offset".
8085 This command implements the pwrite(2) system call, and like that system
8087 call it may not write the full data requested. The return value is the
8088 number of bytes that were actually written to the file. This could
8089 even be 0, although short writes are unlikely for regular files in
8090 ordinary circumstances.
8091 See also "pread", "pwrite-device".
8093 Because of the message protocol, there is a transfer limit of somewhere
8095 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8096 pwrite-device
8098 pwrite-device device content offset
8099 This command writes to part of a device. It writes the data buffer
8101 "content" to "device" starting at offset "offset".
8102 This command implements the pwrite(2) system call, and like that system
8104 call it may not write the full data requested (although short writes to
8105 disk devices and partitions are probably impossible with standard Linux
8106 kernels).
8107 See also "pwrite".
8109 Because of the message protocol, there is a transfer limit of somewhere
8111 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8112 read-file
8114 read-file path
8115 This calls returns the contents of the file "path" as a buffer.
8117 Unlike "cat", this function can correctly handle files that contain
8119 embedded ASCII NUL characters.
8120 read-lines
8122 read-lines path
8123 Return the contents of the file named "path".
8125 The file contents are returned as a list of lines. Trailing "LF" and
8127 "CRLF" character sequences are not returned.
8128 Note that this function cannot correctly handle binary files
8130 (specifically, files containing "\0" character which is treated as end
8131 of string). For those you need to use the "read-file" function and
8132 split the buffer into lines yourself.
8133 readdir
8135 readdir dir
8136 This returns the list of directory entries in directory "dir".
8138 All entries in the directory are returned, including "." and "..". The
8140 entries are not sorted, but returned in the same order as the
8141 underlying filesystem.
8142 Also this call returns basic file type information about each file.
8144 The "ftyp" field will contain one of the following characters:
8145 'b' Block special
8147 'c' Char special
8149 'd' Directory
8151 'f' FIFO (named pipe)
8153 'l' Symbolic link
8155 'r' Regular file
8157 's' Socket
8159 'u' Unknown file type
8161 '?' The readdir(3) call returned a "d_type" field with an unexpected
8163 value
8164 This function is primarily intended for use by programs. To get a
8166 simple list of names, use "ls". To get a printable directory for human
8167 consumption, use "ll".
8168 Because of the message protocol, there is a transfer limit of somewhere
8170 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8171 readlink
8173 readlink path
8174 This command reads the target of a symbolic link.
8176 readlinklist
8178 readlinklist path 'names ...'
8179 This call allows you to do a "readlink" operation on multiple files,
8181 where all files are in the directory "path". "names" is the list of
8182 files from this directory.
8183 On return you get a list of strings, with a one-to-one correspondence
8185 to the "names" list. Each string is the value of the symbolic link.
8186 If the readlink(2) operation fails on any name, then the corresponding
8188 result string is the empty string "". However the whole operation is
8189 completed even if there were readlink(2) errors, and so you can call
8190 this function with names where you don't know if they are symbolic
8191 links already (albeit slightly less efficient).
8192 This call is intended for programs that want to efficiently list a
8194 directory contents without making many round-trips.
8195 realpath
8197 realpath path
8198 Return the canonicalized absolute pathname of "path". The returned
8200 path has no ".", ".." or symbolic link path elements.
8201 remount
8203 remount mountpoint [rw:true|false]
8204 This call allows you to change the "rw" (readonly/read-write) flag on
8206 an already mounted filesystem at "mountpoint", converting a readonly
8207 filesystem to be read-write, or vice-versa.
8208 Note that at the moment you must supply the "optional" "rw" parameter.
8210 In future we may allow other flags to be adjusted.
8211 This command has one or more optional arguments. See "OPTIONAL
8213 ARGUMENTS".
8214 remove-drive
8216 remove-drive label
8217 This function is conceptually the opposite of "add-drive-opts". It
8219 removes the drive that was previously added with label "label".
8220 Note that in order to remove drives, you have to add them with labels
8222 (see the optional "label" argument to "add-drive-opts"). If you didn't
8223 use a label, then they cannot be removed.
8224 You can call this function before or after launching the handle. If
8226 called after launch, if the backend supports it, we try to hot unplug
8227 the drive: see "HOTPLUGGING" in guestfs(3). The disk must not be in
8228 use (eg. mounted) when you do this. We try to detect if the disk is in
8229 use and stop you from doing this.
8230 removexattr
8232 removexattr xattr path
8233 This call removes the extended attribute named "xattr" of the file
8235 "path".
8236 See also: "lremovexattr", attr(5).
8238 This command depends on the feature "linuxxattrs". See also "feature-
8240 available".
8241 rename
8243 rename oldpath newpath
8244 Rename a file to a new place on the same filesystem. This is the same
8246 as the Linux rename(2) system call. In most cases you are better to
8247 use "mv" instead.
8248 resize2fs
8250 resize2fs device
8251 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
8253 underlying device.
8254 See also "RESIZE2FS ERRORS" in guestfs(3).
8256 resize2fs-M
8258 resize2fs-M device
8259 This command is the same as "resize2fs", but the filesystem is resized
8261 to its minimum size. This works like the -M option to the resize2fs(8)
8262 command.
8263 To get the resulting size of the filesystem you should call "tune2fs-l"
8265 and read the "Block size" and "Block count" values. These two numbers,
8266 multiplied together, give the resulting size of the minimal filesystem
8267 in bytes.
8268 See also "RESIZE2FS ERRORS" in guestfs(3).
8270 resize2fs-size
8272 resize2fs-size device size
8273 This command is the same as "resize2fs" except that it allows you to
8275 specify the new size (in bytes) explicitly.
8276 See also "RESIZE2FS ERRORS" in guestfs(3).
8278 rm
8280 rm path
8281 Remove the single file "path".
8283 rm-f
8285 rm-f path
8286 Remove the file "path".
8288 If the file doesn't exist, that error is ignored. (Other errors, eg.
8290 I/O errors or bad paths, are not ignored)
8291 This call cannot remove directories. Use "rmdir" to remove an empty
8293 directory, or "rm-rf" to remove directories recursively.
8294 rm-rf
8296 rm-rf path
8297 Remove the file or directory "path", recursively removing the contents
8299 if its a directory. This is like the "rm -rf" shell command.
8300 rmdir
8302 rmdir path
8303 Remove the single directory "path".
8305 rmmountpoint
8307 rmmountpoint exemptpath
8308 This call removes a mountpoint that was previously created with
8310 "mkmountpoint". See "mkmountpoint" for full details.
8311 rsync
8313 rsync src dest [archive:true|false] [deletedest:true|false]
8314 This call may be used to copy or synchronize two directories under the
8316 same libguestfs handle. This uses the rsync(1) program which uses a
8317 fast algorithm that avoids copying files unnecessarily.
8318 "src" and "dest" are the source and destination directories. Files are
8320 copied from "src" to "dest".
8321 The optional arguments are:
8323 "archive"
8325 Turns on archive mode. This is the same as passing the --archive
8326 flag to "rsync".
8327 "deletedest"
8329 Delete files at the destination that do not exist at the source.
8330 This command has one or more optional arguments. See "OPTIONAL
8332 ARGUMENTS".
8333 This command depends on the feature "rsync". See also "feature-
8335 available".
8336 rsync-in
8338 rsync-in remote dest [archive:true|false] [deletedest:true|false]
8339 This call may be used to copy or synchronize the filesystem on the host
8341 or on a remote computer with the filesystem within libguestfs. This
8342 uses the rsync(1) program which uses a fast algorithm that avoids
8343 copying files unnecessarily.
8344 This call only works if the network is enabled. See "set-network" or
8346 the --network option to various tools like guestfish(1).
8347 Files are copied from the remote server and directory specified by
8349 "remote" to the destination directory "dest".
8350 The format of the remote server string is defined by rsync(1). Note
8352 that there is no way to supply a password or passphrase so the target
8353 must be set up not to require one.
8354 The optional arguments are the same as those of "rsync".
8356 This command has one or more optional arguments. See "OPTIONAL
8358 ARGUMENTS".
8359 This command depends on the feature "rsync". See also "feature-
8361 available".
8362 rsync-out
8364 rsync-out src remote [archive:true|false] [deletedest:true|false]
8365 This call may be used to copy or synchronize the filesystem within
8367 libguestfs with a filesystem on the host or on a remote computer. This
8368 uses the rsync(1) program which uses a fast algorithm that avoids
8369 copying files unnecessarily.
8370 This call only works if the network is enabled. See "set-network" or
8372 the --network option to various tools like guestfish(1).
8373 Files are copied from the source directory "src" to the remote server
8375 and directory specified by "remote".
8376 The format of the remote server string is defined by rsync(1). Note
8378 that there is no way to supply a password or passphrase so the target
8379 must be set up not to require one.
8380 The optional arguments are the same as those of "rsync".
8382 Globbing does not happen on the "src" parameter. In programs which use
8384 the API directly you have to expand wildcards yourself (see "glob-
8385 expand"). In guestfish you can use the "glob" command (see "glob"),
8386 for example:
8387 ><fs> glob rsync-out /* rsync://remote/
8389 This command has one or more optional arguments. See "OPTIONAL
8391 ARGUMENTS".
8392 This command depends on the feature "rsync". See also "feature-
8394 available".
8395 scrub-device
8397 scrub-device device
8398 This command writes patterns over "device" to make data retrieval more
8400 difficult.
8401 It is an interface to the scrub(1) program. See that manual page for
8403 more details.
8404 This command depends on the feature "scrub". See also "feature-
8406 available".
8407 scrub-file
8409 scrub-file file
8410 This command writes patterns over a file to make data retrieval more
8412 difficult.
8413 The file is removed after scrubbing.
8415 It is an interface to the scrub(1) program. See that manual page for
8417 more details.
8418 This command depends on the feature "scrub". See also "feature-
8420 available".
8421 scrub-freespace
8423 scrub-freespace dir
8424 This command creates the directory "dir" and then fills it with files
8426 until the filesystem is full, and scrubs the files as for "scrub-file",
8427 and deletes them. The intention is to scrub any free space on the
8428 partition containing "dir".
8429 It is an interface to the scrub(1) program. See that manual page for
8431 more details.
8432 This command depends on the feature "scrub". See also "feature-
8434 available".
8435 selinux-relabel
8437 selinux-relabel specfile path [force:true|false]
8438 SELinux relabel parts of the filesystem.
8440 The "specfile" parameter controls the policy spec file used. You have
8442 to parse "/etc/selinux/config" to find the correct SELinux policy and
8443 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
8444 "/contexts/files/file_contexts".
8445 The required "path" parameter is the top level directory where
8447 relabelling starts. Normally you should pass "path" as "/" to relabel
8448 the whole guest filesystem.
8449 The optional "force" boolean controls whether the context is reset for
8451 customizable files, and also whether the user, role and range parts of
8452 the file context is changed.
8453 This command has one or more optional arguments. See "OPTIONAL
8455 ARGUMENTS".
8456 This command depends on the feature "selinuxrelabel". See also
8458 "feature-available".
8459 set-append
8461 append
8462 set-append append
8463 This function is used to add additional options to the libguestfs
8465 appliance kernel command line.
8466 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
8468 environment variable.
8469 Setting "append" to "NULL" means no additional options are passed
8471 (libguestfs always adds a few of its own).
8472 set-attach-method
8474 attach-method
8475 set-attach-method backend
8476 Set the method that libguestfs uses to connect to the backend guestfsd
8478 daemon.
8479 See "BACKEND" in guestfs(3).
8481 This function is deprecated. In new code, use the "set-backend" call
8483 instead.
8484 Deprecated functions will not be removed from the API, but the fact
8486 that they are deprecated indicates that there are problems with correct
8487 use of these functions.
8488 set-autosync
8490 autosync
8491 set-autosync true|false
8492 If "autosync" is true, this enables autosync. Libguestfs will make a
8494 best effort attempt to make filesystems consistent and synchronized
8495 when the handle is closed (also if the program exits without closing
8496 handles).
8497 This is enabled by default (since libguestfs 1.5.24, previously it was
8499 disabled by default).
8500 set-backend
8502 backend
8503 set-backend backend
8504 Set the method that libguestfs uses to connect to the backend guestfsd
8506 daemon.
8507 This handle property was previously called the "attach method".
8509 See "BACKEND" in guestfs(3).
8511 set-backend-setting
8513 set-backend-setting name val
8514 Append "name=value" to the backend settings string list. However if a
8516 string already exists matching "name" or beginning with "name=", then
8517 that setting is replaced.
8518 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8520 set-backend-settings
8522 set-backend-settings 'settings ...'
8523 Set a list of zero or more settings which are passed through to the
8525 current backend. Each setting is a string which is interpreted in a
8526 backend-specific way, or ignored if not understood by the backend.
8527 The default value is an empty list, unless the environment variable
8529 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
8530 This environment variable contains a colon-separated list of settings.
8531 This call replaces all backend settings. If you want to replace a
8533 single backend setting, see "set-backend-setting". If you want to
8534 clear a single backend setting, see "clear-backend-setting".
8535 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8537 set-cachedir
8539 cachedir
8540 set-cachedir cachedir
8541 Set the directory used by the handle to store the appliance cache, when
8543 using a supermin appliance. The appliance is cached and shared between
8544 all handles which have the same effective user ID.
8545 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
8547 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
8548 default. Else if "TMPDIR" is set, then that is the default. Else
8549 /var/tmp is the default.
8550 set-direct
8552 direct
8553 set-direct true|false
8554 If the direct appliance mode flag is enabled, then stdin and stdout are
8556 passed directly through to the appliance once it is launched.
8557 One consequence of this is that log messages aren't caught by the
8559 library and handled by "set-log-message-callback", but go straight to
8560 stdout.
8561 You probably don't want to use this unless you know what you are doing.
8563 The default is disabled.
8565 This function is deprecated. In new code, use the "internal-get-
8567 console-socket" call instead.
8568 Deprecated functions will not be removed from the API, but the fact
8570 that they are deprecated indicates that there are problems with correct
8571 use of these functions.
8572 set-e2attrs
8574 set-e2attrs file attrs [clear:true|false]
8575 This sets or clears the file attributes "attrs" associated with the
8577 inode file.
8578 "attrs" is a string of characters representing file attributes. See
8580 "get-e2attrs" for a list of possible attributes. Not all attributes
8581 can be changed.
8582 If optional boolean "clear" is not present or false, then the "attrs"
8584 listed are set in the inode.
8585 If "clear" is true, then the "attrs" listed are cleared in the inode.
8587 In both cases, other attributes not present in the "attrs" string are
8589 left unchanged.
8590 These attributes are only present when the file is located on an
8592 ext2/3/4 filesystem. Using this call on other filesystem types will
8593 result in an error.
8594 This command has one or more optional arguments. See "OPTIONAL
8596 ARGUMENTS".
8597 set-e2generation
8599 set-e2generation file generation
8600 This sets the ext2 file generation of a file.
8602 See "get-e2generation".
8604 set-e2label
8606 set-e2label device label
8607 This sets the ext2/3/4 filesystem label of the filesystem on "device"
8609 to "label". Filesystem labels are limited to 16 characters.
8610 You can use either "tune2fs-l" or "get-e2label" to return the existing
8612 label on a filesystem.
8613 This function is deprecated. In new code, use the "set-label" call
8615 instead.
8616 Deprecated functions will not be removed from the API, but the fact
8618 that they are deprecated indicates that there are problems with correct
8619 use of these functions.
8620 set-e2uuid
8622 set-e2uuid device uuid
8623 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
8625 "uuid". The format of the UUID and alternatives such as "clear",
8626 "random" and "time" are described in the tune2fs(8) manpage.
8627 You can use "vfs-uuid" to return the existing UUID of a filesystem.
8629 This function is deprecated. In new code, use the "set-uuid" call
8631 instead.
8632 Deprecated functions will not be removed from the API, but the fact
8634 that they are deprecated indicates that there are problems with correct
8635 use of these functions.
8636 set-hv
8638 hv
8639 set-hv hv
8640 Set the hypervisor binary that we will use. The hypervisor depends on
8642 the backend, but is usually the location of the qemu/KVM hypervisor.
8643 For the uml backend, it is the location of the "linux" or "vmlinux"
8644 binary.
8645 The default is chosen when the library was compiled by the configure
8647 script.
8648 You can also override this by setting the "LIBGUESTFS_HV" environment
8650 variable.
8651 Note that you should call this function as early as possible after
8653 creating the handle. This is because some pre-launch operations depend
8654 on testing qemu features (by running "qemu -help"). If the qemu binary
8655 changes, we don't retest features, and so you might see inconsistent
8656 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8657 all since that picks the qemu binary at the same time as the handle is
8658 created.
8659 set-identifier
8661 identifier
8662 set-identifier identifier
8663 This is an informative string which the caller may optionally set in
8665 the handle. It is printed in various places, allowing the current
8666 handle to be identified in debugging output.
8667 One important place is when tracing is enabled. If the identifier
8669 string is not an empty string, then trace messages change from this:
8670 libguestfs: trace: get_tmpdir
8672 libguestfs: trace: get_tmpdir = "/tmp"
8673 to this:
8675 libguestfs: trace: ID: get_tmpdir
8677 libguestfs: trace: ID: get_tmpdir = "/tmp"
8678 where "ID" is the identifier string set by this call.
8680 The identifier must only contain alphanumeric ASCII characters,
8682 underscore and minus sign. The default is the empty string.
8683 See also "set-program", "set-trace", "get-identifier".
8685 set-label
8687 set-label mountable label
8688 Set the filesystem label on "mountable" to "label".
8690 Only some filesystem types support labels, and libguestfs supports
8692 setting labels on only a subset of these.
8693 ext2, ext3, ext4
8695 Labels are limited to 16 bytes.
8696 NTFS
8698 Labels are limited to 128 unicode characters.
8699 XFS The label is limited to 12 bytes. The filesystem must not be
8701 mounted when trying to set the label.
8702 btrfs
8704 The label is limited to 255 bytes and some characters are not
8705 allowed. Setting the label on a btrfs subvolume will set the label
8706 on its parent filesystem. The filesystem must not be mounted when
8707 trying to set the label.
8708 fat The label is limited to 11 bytes.
8710 swap
8712 The label is limited to 16 bytes.
8713 If there is no support for changing the label for the type of the
8715 specified filesystem, set_label will fail and set errno as ENOTSUP.
8716 To read the label on a filesystem, call "vfs-label".
8718 set-libvirt-requested-credential
8720 set-libvirt-requested-credential index cred
8721 After requesting the "index"'th credential from the user, call this
8723 function to pass the answer back to libvirt.
8724 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8726 example code.
8727 set-libvirt-supported-credentials
8729 set-libvirt-supported-credentials 'creds ...'
8730 Call this function before setting an event handler for
8732 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
8733 that the program knows how to process.
8734 The "creds" list must be a non-empty list of strings. Possible strings
8736 are:
8737 "username"
8739 "authname"
8740 "language"
8741 "cnonce"
8742 "passphrase"
8743 "echoprompt"
8744 "noechoprompt"
8745 "realm"
8746 "external"
8747 See libvirt documentation for the meaning of these credential types.
8749 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8751 example code.
8752 set-memsize
8754 memsize
8755 set-memsize memsize
8756 This sets the memory size in megabytes allocated to the hypervisor.
8758 This only has any effect if called before "launch".
8759 You can also change this by setting the environment variable
8761 "LIBGUESTFS_MEMSIZE" before the handle is created.
8762 For more information on the architecture of libguestfs, see guestfs(3).
8764 set-network
8766 network
8767 set-network true|false
8768 If "network" is true, then the network is enabled in the libguestfs
8770 appliance. The default is false.
8771 This affects whether commands are able to access the network (see
8773 "RUNNING COMMANDS" in guestfs(3)).
8774 You must call this before calling "launch", otherwise it has no effect.
8776 set-path
8778 path
8779 set-path searchpath
8780 Set the path that libguestfs searches for kernel and initrd.img.
8782 The default is "$libdir/guestfs" unless overridden by setting
8784 "LIBGUESTFS_PATH" environment variable.
8785 Setting "path" to "NULL" restores the default path.
8787 set-pgroup
8789 pgroup
8790 set-pgroup true|false
8791 If "pgroup" is true, child processes are placed into their own process
8793 group.
8794 The practical upshot of this is that signals like "SIGINT" (from users
8796 pressing "^C") won't be received by the child process.
8797 The default for this flag is false, because usually you want "^C" to
8799 kill the subprocess. Guestfish sets this flag to true when used
8800 interactively, so that "^C" can cancel long-running commands gracefully
8801 (see "user-cancel").
8802 set-program
8804 program
8805 set-program program
8806 Set the program name. This is an informative string which the main
8808 program may optionally set in the handle.
8809 When the handle is created, the program name in the handle is set to
8811 the basename from "argv[0]". The program name can never be "NULL".
8812 set-qemu
8814 qemu
8815 set-qemu hv
8816 Set the hypervisor binary (usually qemu) that we will use.
8818 The default is chosen when the library was compiled by the configure
8820 script.
8821 You can also override this by setting the "LIBGUESTFS_HV" environment
8823 variable.
8824 Setting "hv" to "NULL" restores the default qemu binary.
8826 Note that you should call this function as early as possible after
8828 creating the handle. This is because some pre-launch operations depend
8829 on testing qemu features (by running "qemu -help"). If the qemu binary
8830 changes, we don't retest features, and so you might see inconsistent
8831 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8832 all since that picks the qemu binary at the same time as the handle is
8833 created.
8834 This function is deprecated. In new code, use the "set-hv" call
8836 instead.
8837 Deprecated functions will not be removed from the API, but the fact
8839 that they are deprecated indicates that there are problems with correct
8840 use of these functions.
8841 set-recovery-proc
8843 recovery-proc
8844 set-recovery-proc true|false
8845 If this is called with the parameter "false" then "launch" does not
8847 create a recovery process. The purpose of the recovery process is to
8848 stop runaway hypervisor processes in the case where the main program
8849 aborts abruptly.
8850 This only has any effect if called before "launch", and the default is
8852 true.
8853 About the only time when you would want to disable this is if the main
8855 process will fork itself into the background ("daemonize" itself). In
8856 this case the recovery process thinks that the main program has
8857 disappeared and so kills the hypervisor, which is not very helpful.
8858 set-selinux
8860 selinux
8861 set-selinux true|false
8862 This sets the selinux flag that is passed to the appliance at boot
8864 time. The default is "selinux=0" (disabled).
8865 Note that if SELinux is enabled, it is always in Permissive mode
8867 ("enforcing=0").
8868 For more information on the architecture of libguestfs, see 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 set-smp
8879 smp
8880 set-smp smp
8881 Change the number of virtual CPUs assigned to the appliance. The
8883 default is 1. Increasing this may improve performance, though often it
8884 has no effect.
8885 This function must be called before "launch".
8887 set-tmpdir
8889 tmpdir
8890 set-tmpdir tmpdir
8891 Set the directory used by the handle to store temporary files.
8893 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
8895 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
8896 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
8897 default.
8898 set-trace
8900 trace
8901 set-trace true|false
8902 If the command trace flag is set to 1, then libguestfs calls,
8904 parameters and return values are traced.
8905 If you want to trace C API calls into libguestfs (and other libraries)
8907 then possibly a better way is to use the external ltrace(1) command.
8908 Command traces are disabled unless the environment variable
8910 "LIBGUESTFS_TRACE" is defined and set to 1.
8911 Trace messages are normally sent to "stderr", unless you register a
8913 callback to send them somewhere else (see "set-event-callback").
8914 set-uuid
8916 set-uuid device uuid
8917 Set the filesystem UUID on "device" to "uuid". If this fails and the
8919 errno is ENOTSUP, means that there is no support for changing the UUID
8920 for the type of the specified filesystem.
8921 Only some filesystem types support setting UUIDs.
8923 To read the UUID on a filesystem, call "vfs-uuid".
8925 set-uuid-random
8927 set-uuid-random device
8928 Set the filesystem UUID on "device" to a random UUID. If this fails
8930 and the errno is ENOTSUP, means that there is no support for changing
8931 the UUID for the type of the specified filesystem.
8932 Only some filesystem types support setting UUIDs.
8934 To read the UUID on a filesystem, call "vfs-uuid".
8936 set-verbose
8938 verbose
8939 set-verbose true|false
8940 If "verbose" is true, this turns on verbose messages.
8942 Verbose messages are disabled unless the environment variable
8944 "LIBGUESTFS_DEBUG" is defined and set to 1.
8945 Verbose messages are normally sent to "stderr", unless you register a
8947 callback to send them somewhere else (see "set-event-callback").
8948 setcon
8950 setcon context
8951 This sets the SELinux security context of the daemon to the string
8953 "context".
8954 See the documentation about SELINUX in guestfs(3).
8956 This function is deprecated. In new code, use the "selinux-relabel"
8958 call instead.
8959 Deprecated functions will not be removed from the API, but the fact
8961 that they are deprecated indicates that there are problems with correct
8962 use of these functions.
8963 This command depends on the feature "selinux". See also "feature-
8965 available".
8966 setxattr
8968 setxattr xattr val vallen path
8969 This call sets the extended attribute named "xattr" of the file "path"
8971 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
8972 data.
8973 See also: "lsetxattr", attr(5).
8975 This command depends on the feature "linuxxattrs". See also "feature-
8977 available".
8978 sfdisk
8980 sfdisk device cyls heads sectors 'lines ...'
8981 This is a direct interface to the sfdisk(8) program for creating
8983 partitions on block devices.
8984 "device" should be a block device, for example /dev/sda.
8986 "cyls", "heads" and "sectors" are the number of cylinders, heads and
8988 sectors on the device, which are passed directly to sfdisk(8) as the
8989 -C, -H and -S parameters. If you pass 0 for any of these, then the
8990 corresponding parameter is omitted. Usually for ‘large’ disks, you can
8991 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
8992 (or rather, the kernel) cannot work out the right geometry and you will
8993 need to tell it.
8994 "lines" is a list of lines that we feed to sfdisk(8). For more
8996 information refer to the sfdisk(8) manpage.
8997 To create a single partition occupying the whole disk, you would pass
8999 "lines" as a single element list, when the single element being the
9000 string "," (comma).
9001 See also: "sfdisk-l", "sfdisk-N", "part-init"
9003 This function is deprecated. In new code, use the "part-add" call
9005 instead.
9006 Deprecated functions will not be removed from the API, but the fact
9008 that they are deprecated indicates that there are problems with correct
9009 use of these functions.
9010 sfdiskM
9012 sfdiskM device 'lines ...'
9013 This is a simplified interface to the "sfdisk" command, where partition
9015 sizes are specified in megabytes only (rounded to the nearest cylinder)
9016 and you don't need to specify the cyls, heads and sectors parameters
9017 which were rarely if ever used anyway.
9018 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
9020 This function is deprecated. In new code, use the "part-add" call
9022 instead.
9023 Deprecated functions will not be removed from the API, but the fact
9025 that they are deprecated indicates that there are problems with correct
9026 use of these functions.
9027 sfdisk-N
9029 sfdisk-N device partnum cyls heads sectors line
9030 This runs sfdisk(8) option to modify just the single partition "n"
9032 (note: "n" counts from 1).
9033 For other parameters, see "sfdisk". You should usually pass 0 for the
9035 cyls/heads/sectors parameters.
9036 See also: "part-add"
9038 This function is deprecated. In new code, use the "part-add" call
9040 instead.
9041 Deprecated functions will not be removed from the API, but the fact
9043 that they are deprecated indicates that there are problems with correct
9044 use of these functions.
9045 sfdisk-disk-geometry
9047 sfdisk-disk-geometry device
9048 This displays the disk geometry of "device" read from the partition
9050 table. Especially in the case where the underlying block device has
9051 been resized, this can be different from the kernel’s idea of the
9052 geometry (see "sfdisk-kernel-geometry").
9053 The result is in human-readable format, and not designed to be parsed.
9055 sfdisk-kernel-geometry
9057 sfdisk-kernel-geometry device
9058 This displays the kernel’s idea of the geometry of "device".
9060 The result is in human-readable format, and not designed to be parsed.
9062 sfdisk-l
9064 sfdisk-l device
9065 This displays the partition table on "device", in the human-readable
9067 output of the sfdisk(8) command. It is not intended to be parsed.
9068 See also: "part-list"
9070 This function is deprecated. In new code, use the "part-list" call
9072 instead.
9073 Deprecated functions will not be removed from the API, but the fact
9075 that they are deprecated indicates that there are problems with correct
9076 use of these functions.
9077 sh
9079 sh command
9080 This call runs a command from the guest filesystem via the guest’s
9082 /bin/sh.
9083 This is like "command", but passes the command to:
9085 /bin/sh -c "command"
9087 Depending on the guest’s shell, this usually results in wildcards being
9089 expanded, shell expressions being interpolated and so on.
9090 All the provisos about "command" apply to this call.
9092 sh-lines
9094 sh-lines command
9095 This is the same as "sh", but splits the result into a list of lines.
9097 See also: "command-lines"
9099 shutdown
9101 shutdown
9102 This is the opposite of "launch". It performs an orderly shutdown of
9104 the backend process(es). If the autosync flag is set (which is the
9105 default) then the disk image is synchronized.
9106 If the subprocess exits with an error then this function will return an
9108 error, which should not be ignored (it may indicate that the disk image
9109 could not be written out properly).
9110 It is safe to call this multiple times. Extra calls are ignored.
9112 This call does not close or free up the handle. You still need to call
9114 "close" afterwards.
9115 "close" will call this if you don't do it explicitly, but note that any
9117 errors are ignored in that case.
9118 sleep
9120 sleep secs
9121 Sleep for "secs" seconds.
9123 stat
9125 stat path
9126 Returns file information for the given "path".
9128 This is the same as the stat(2) system call.
9130 This function is deprecated. In new code, use the "statns" call
9132 instead.
9133 Deprecated functions will not be removed from the API, but the fact
9135 that they are deprecated indicates that there are problems with correct
9136 use of these functions.
9137 statns
9139 statns path
9140 Returns file information for the given "path".
9142 This is the same as the stat(2) system call.
9144 statvfs
9146 statvfs path
9147 Returns file system statistics for any mounted file system. "path"
9149 should be a file or directory in the mounted file system (typically it
9150 is the mount point itself, but it doesn't need to be).
9151 This is the same as the statvfs(2) system call.
9153 strings
9155 strings path
9156 This runs the strings(1) command on a file and returns the list of
9158 printable strings found.
9159 The "strings" command has, in the past, had problems with parsing
9161 untrusted files. These are mitigated in the current version of
9162 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9163 Because of the message protocol, there is a transfer limit of somewhere
9165 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9166 strings-e
9168 strings-e encoding path
9169 This is like the "strings" command, but allows you to specify the
9171 encoding of strings that are looked for in the source file "path".
9172 Allowed encodings are:
9174 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
9176 parts of ISO-8859-X (this is what "strings" uses).
9177 S Single 8-bit-byte characters.
9179 b 16-bit big endian strings such as those encoded in UTF-16BE or
9181 UCS-2BE.
9182 l (lower case letter L)
9184 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
9185 for examining binaries in Windows guests.
9186 B 32-bit big endian such as UCS-4BE.
9188 L 32-bit little endian such as UCS-4LE.
9190 The returned strings are transcoded to UTF-8.
9192 The "strings" command has, in the past, had problems with parsing
9194 untrusted files. These are mitigated in the current version of
9195 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9196 Because of the message protocol, there is a transfer limit of somewhere
9198 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9199 swapoff-device
9201 swapoff-device device
9202 This command disables the libguestfs appliance swap device or partition
9204 named "device". See "swapon-device".
9205 swapoff-file
9207 swapoff-file file
9208 This command disables the libguestfs appliance swap on file.
9210 swapoff-label
9212 swapoff-label label
9213 This command disables the libguestfs appliance swap on labeled swap
9215 partition.
9216 swapoff-uuid
9218 swapoff-uuid uuid
9219 This command disables the libguestfs appliance swap partition with the
9221 given UUID.
9222 This command depends on the feature "linuxfsuuid". See also "feature-
9224 available".
9225 swapon-device
9227 swapon-device device
9228 This command enables the libguestfs appliance to use the swap device or
9230 partition named "device". The increased memory is made available for
9231 all commands, for example those run using "command" or "sh".
9232 Note that you should not swap to existing guest swap partitions unless
9234 you know what you are doing. They may contain hibernation information,
9235 or other information that the guest doesn't want you to trash. You
9236 also risk leaking information about the host to the guest this way.
9237 Instead, attach a new host device to the guest and swap on that.
9238 swapon-file
9240 swapon-file file
9241 This command enables swap to a file. See "swapon-device" for other
9243 notes.
9244 swapon-label
9246 swapon-label label
9247 This command enables swap to a labeled swap partition. See "swapon-
9249 device" for other notes.
9250 swapon-uuid
9252 swapon-uuid uuid
9253 This command enables swap to a swap partition with the given UUID. See
9255 "swapon-device" for other notes.
9256 This command depends on the feature "linuxfsuuid". See also "feature-
9258 available".
9259 sync
9261 sync
9262 This syncs the disk, so that any writes are flushed through to the
9264 underlying disk image.
9265 You should always call this if you have modified a disk image, before
9267 closing the handle.
9268 syslinux
9270 syslinux device [directory:..]
9271 Install the SYSLINUX bootloader on "device".
9273 The device parameter must be either a whole disk formatted as a FAT
9275 filesystem, or a partition formatted as a FAT filesystem. In the
9276 latter case, the partition should be marked as "active" ("part-set-
9277 bootable") and a Master Boot Record must be installed (eg. using
9278 "pwrite-device") on the first sector of the whole disk. The SYSLINUX
9279 package comes with some suitable Master Boot Records. See the
9280 syslinux(1) man page for further information.
9281 The optional arguments are:
9283 directory
9285 Install SYSLINUX in the named subdirectory, instead of in the root
9286 directory of the FAT filesystem.
9287 Additional configuration can be supplied to SYSLINUX by placing a file
9289 called syslinux.cfg on the FAT filesystem, either in the root
9290 directory, or under directory if that optional argument is being used.
9291 For further information about the contents of this file, see
9292 syslinux(1).
9293 See also "extlinux".
9295 This command has one or more optional arguments. See "OPTIONAL
9297 ARGUMENTS".
9298 This command depends on the feature "syslinux". See also "feature-
9300 available".
9301 tail
9303 tail path
9304 This command returns up to the last 10 lines of a file as a list of
9306 strings.
9307 Because of the message protocol, there is a transfer limit of somewhere
9309 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9310 tail-n
9312 tail-n nrlines path
9313 If the parameter "nrlines" is a positive number, this returns the last
9315 "nrlines" lines of the file "path".
9316 If the parameter "nrlines" is a negative number, this returns lines
9318 from the file "path", starting with the "-nrlines"'th line.
9319 If the parameter "nrlines" is zero, this returns an empty list.
9321 Because of the message protocol, there is a transfer limit of somewhere
9323 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9324 tar-in
9326 tar-in-opts
9327 tar-in (tarfile|-) directory [compress:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9328 This command uploads and unpacks local file "tarfile" into directory.
9330 The optional "compress" flag controls compression. If not given, then
9332 the input should be an uncompressed tar file. Otherwise one of the
9333 following strings may be given to select the compression type of the
9334 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9335 all builds of libguestfs will support all of these compression types).
9336 The other optional arguments are:
9338 "xattrs"
9340 If set to true, extended attributes are restored from the tar file.
9341 "selinux"
9343 If set to true, SELinux contexts are restored from the tar file.
9344 "acls"
9346 If set to true, POSIX ACLs are restored from the tar file.
9347 Use "-" instead of a filename to read/write from stdin/stdout.
9349 This command has one or more optional arguments. See "OPTIONAL
9351 ARGUMENTS".
9352 tar-out
9354 tar-out-opts
9355 tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9356 This command packs the contents of directory and downloads it to local
9358 file "tarfile".
9359 The optional "compress" flag controls compression. If not given, then
9361 the output will be an uncompressed tar file. Otherwise one of the
9362 following strings may be given to select the compression type of the
9363 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9364 all builds of libguestfs will support all of these compression types).
9365 The other optional arguments are:
9367 "excludes"
9369 A list of wildcards. Files are excluded if they match any of the
9370 wildcards.
9371 "numericowner"
9373 If set to true, the output tar file will contain UID/GID numbers
9374 instead of user/group names.
9375 "xattrs"
9377 If set to true, extended attributes are saved in the output tar.
9378 "selinux"
9380 If set to true, SELinux contexts are saved in the output tar.
9381 "acls"
9383 If set to true, POSIX ACLs are saved in the output tar.
9384 Use "-" instead of a filename to read/write from stdin/stdout.
9386 This command has one or more optional arguments. See "OPTIONAL
9388 ARGUMENTS".
9389 tgz-in
9391 tgz-in (tarball|-) directory
9392 This command uploads and unpacks local file "tarball" (a gzip
9394 compressed tar file) into directory.
9395 Use "-" instead of a filename to read/write from stdin/stdout.
9397 This function is deprecated. In new code, use the "tar-in" call
9399 instead.
9400 Deprecated functions will not be removed from the API, but the fact
9402 that they are deprecated indicates that there are problems with correct
9403 use of these functions.
9404 tgz-out
9406 tgz-out directory (tarball|-)
9407 This command packs the contents of directory and downloads it to local
9409 file "tarball".
9410 Use "-" instead of a filename to read/write from stdin/stdout.
9412 This function is deprecated. In new code, use the "tar-out" call
9414 instead.
9415 Deprecated functions will not be removed from the API, but the fact
9417 that they are deprecated indicates that there are problems with correct
9418 use of these functions.
9419 touch
9421 touch path
9422 Touch acts like the touch(1) command. It can be used to update the
9424 timestamps on a file, or, if the file does not exist, to create a new
9425 zero-length file.
9426 This command only works on regular files, and will fail on other file
9428 types such as directories, symbolic links, block special etc.
9429 truncate
9431 truncate path
9432 This command truncates "path" to a zero-length file. The file must
9434 exist already.
9435 truncate-size
9437 truncate-size path size
9438 This command truncates "path" to size "size" bytes. The file must
9440 exist already.
9441 If the current file size is less than "size" then the file is extended
9443 to the required size with zero bytes. This creates a sparse file (ie.
9444 disk blocks are not allocated for the file until you write to it). To
9445 create a non-sparse file of zeroes, use "fallocate64" instead.
9446 tune2fs
9448 tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
9449 This call allows you to adjust various filesystem parameters of an
9451 ext2/ext3/ext4 filesystem called "device".
9452 The optional parameters are:
9454 "force"
9456 Force tune2fs to complete the operation even in the face of errors.
9457 This is the same as the tune2fs(8) "-f" option.
9458 "maxmountcount"
9460 Set the number of mounts after which the filesystem is checked by
9461 e2fsck(8). If this is 0 then the number of mounts is disregarded.
9462 This is the same as the tune2fs(8) "-c" option.
9463 "mountcount"
9465 Set the number of times the filesystem has been mounted. This is
9466 the same as the tune2fs(8) "-C" option.
9467 "errorbehavior"
9469 Change the behavior of the kernel code when errors are detected.
9470 Possible values currently are: "continue", "remount-ro", "panic".
9471 In practice these options don't really make any difference,
9472 particularly for write errors.
9473 This is the same as the tune2fs(8) "-e" option.
9475 "group"
9477 Set the group which can use reserved filesystem blocks. This is
9478 the same as the tune2fs(8) "-g" option except that it can only be
9479 specified as a number.
9480 "intervalbetweenchecks"
9482 Adjust the maximal time between two filesystem checks (in seconds).
9483 If the option is passed as 0 then time-dependent checking is
9484 disabled.
9485 This is the same as the tune2fs(8) "-i" option.
9487 "reservedblockspercentage"
9489 Set the percentage of the filesystem which may only be allocated by
9490 privileged processes. This is the same as the tune2fs(8) "-m"
9491 option.
9492 "lastmounteddirectory"
9494 Set the last mounted directory. This is the same as the tune2fs(8)
9495 "-M" option.
9496 "reservedblockscount" Set the number of reserved filesystem blocks.
9498 This is the same as the tune2fs(8) "-r" option.
9499 "user"
9500 Set the user who can use the reserved filesystem blocks. This is
9501 the same as the tune2fs(8) "-u" option except that it can only be
9502 specified as a number.
9503 To get the current values of filesystem parameters, see "tune2fs-l".
9505 For precise details of how tune2fs works, see the tune2fs(8) man page.
9506 This command has one or more optional arguments. See "OPTIONAL
9508 ARGUMENTS".
9509 tune2fs-l
9511 tune2fs-l device
9512 This returns the contents of the ext2, ext3 or ext4 filesystem
9514 superblock on "device".
9515 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
9517 for more details. The list of fields returned isn't clearly defined,
9518 and depends on both the version of "tune2fs" that libguestfs was built
9519 against, and the filesystem itself.
9520 txz-in
9522 txz-in (tarball|-) directory
9523 This command uploads and unpacks local file "tarball" (an xz compressed
9525 tar file) into directory.
9526 Use "-" instead of a filename to read/write from stdin/stdout.
9528 This function is deprecated. In new code, use the "tar-in" call
9530 instead.
9531 Deprecated functions will not be removed from the API, but the fact
9533 that they are deprecated indicates that there are problems with correct
9534 use of these functions.
9535 This command depends on the feature "xz". See also "feature-
9537 available".
9538 txz-out
9540 txz-out directory (tarball|-)
9541 This command packs the contents of directory and downloads it to local
9543 file "tarball" (as an xz compressed tar archive).
9544 Use "-" instead of a filename to read/write from stdin/stdout.
9546 This function is deprecated. In new code, use the "tar-out" call
9548 instead.
9549 Deprecated functions will not be removed from the API, but the fact
9551 that they are deprecated indicates that there are problems with correct
9552 use of these functions.
9553 This command depends on the feature "xz". See also "feature-
9555 available".
9556 umask
9558 umask mask
9559 This function sets the mask used for creating new files and device
9561 nodes to "mask & 0777".
9562 Typical umask values would be 022 which creates new files with
9564 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
9565 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
9566 The default umask is 022. This is important because it means that
9568 directories and device nodes will be created with 0644 or 0755 mode
9569 even if you specify 0777.
9570 See also "get-umask", umask(2), "mknod", "mkdir".
9572 This call returns the previous umask.
9574 umount
9576 unmount
9577 umount-opts
9578 umount pathordevice [force:true|false] [lazyunmount:true|false]
9579 This unmounts the given filesystem. The filesystem may be specified
9581 either by its mountpoint (path) or the device which contains the
9582 filesystem.
9583 This command has one or more optional arguments. See "OPTIONAL
9585 ARGUMENTS".
9586 umount-all
9588 unmount-all
9589 umount-all
9590 This unmounts all mounted filesystems.
9592 Some internal mounts are not unmounted by this call.
9594 umount-local
9596 umount-local [retry:true|false]
9597 If libguestfs is exporting the filesystem on a local mountpoint, then
9599 this unmounts it.
9600 See "MOUNT LOCAL" in guestfs(3) for full documentation.
9602 This command has one or more optional arguments. See "OPTIONAL
9604 ARGUMENTS".
9605 upload
9607 upload (filename|-) remotefilename
9608 Upload local file filename to remotefilename on the filesystem.
9610 filename can also be a named pipe.
9612 See also "download".
9614 Use "-" instead of a filename to read/write from stdin/stdout.
9616 upload-offset
9618 upload-offset (filename|-) remotefilename offset
9619 Upload local file filename to remotefilename on the filesystem.
9621 remotefilename is overwritten starting at the byte "offset" specified.
9623 The intention is to overwrite parts of existing files or devices,
9624 although if a non-existent file is specified then it is created with a
9625 "hole" before "offset". The size of the data written is implicit in
9626 the size of the source filename.
9627 Note that there is no limit on the amount of data that can be uploaded
9629 with this call, unlike with "pwrite", and this call always writes the
9630 full amount unless an error occurs.
9631 See also "upload", "pwrite".
9633 Use "-" instead of a filename to read/write from stdin/stdout.
9635 user-cancel
9637 user-cancel
9638 This function cancels the current upload or download operation.
9640 Unlike most other libguestfs calls, this function is signal safe and
9642 thread safe. You can call it from a signal handler or from another
9643 thread, without needing to do any locking.
9644 The transfer that was in progress (if there is one) will stop shortly
9646 afterwards, and will return an error. The errno (see
9647 "guestfs_last_errno") is set to "EINTR", so you can test for this to
9648 find out if the operation was cancelled or failed because of another
9649 error.
9650 No cleanup is performed: for example, if a file was being uploaded then
9652 after cancellation there may be a partially uploaded file. It is the
9653 caller’s responsibility to clean up if necessary.
9654 There are two common places that you might call "user-cancel":
9656 In an interactive text-based program, you might call it from a "SIGINT"
9658 signal handler so that pressing "^C" cancels the current operation.
9659 (You also need to call "set-pgroup" so that child processes don't
9660 receive the "^C" signal).
9661 In a graphical program, when the main thread is displaying a progress
9663 bar with a cancel button, wire up the cancel button to call this
9664 function.
9665 utimens
9667 utimens path atsecs atnsecs mtsecs mtnsecs
9668 This command sets the timestamps of a file with nanosecond precision.
9670 "atsecs", "atnsecs" are the last access time (atime) in secs and
9672 nanoseconds from the epoch.
9673 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
9675 nanoseconds from the epoch.
9676 If the *nsecs field contains the special value "-1" then the
9678 corresponding timestamp is set to the current time. (The *secs field
9679 is ignored in this case).
9680 If the *nsecs field contains the special value "-2" then the
9682 corresponding timestamp is left unchanged. (The *secs field is ignored
9683 in this case).
9684 utsname
9686 utsname
9687 This returns the kernel version of the appliance, where this is
9689 available. This information is only useful for debugging. Nothing in
9690 the returned structure is defined by the API.
9691 version
9693 version
9694 Return the libguestfs version number that the program is linked
9696 against.
9697 Note that because of dynamic linking this is not necessarily the
9699 version of libguestfs that you compiled against. You can compile the
9700 program, and then at runtime dynamically link against a completely
9701 different libguestfs.so library.
9702 This call was added in version 1.0.58. In previous versions of
9704 libguestfs there was no way to get the version number. From C code you
9705 can use dynamic linker functions to find out if this symbol exists (if
9706 it doesn't, then it’s an earlier version).
9707 The call returns a structure with four elements. The first three
9709 ("major", "minor" and "release") are numbers and correspond to the
9710 usual version triplet. The fourth element ("extra") is a string and is
9711 normally empty, but may be used for distro-specific information.
9712 To construct the original version string:
9714 "$major.$minor.$release$extra"
9715 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
9717 Note: Don't use this call to test for availability of features. In
9719 enterprise distributions we backport features from later versions into
9720 earlier versions, making this an unreliable way to test for features.
9721 Use "available" or "feature-available" instead.
9722 vfs-label
9724 vfs-label mountable
9725 This returns the label of the filesystem on "mountable".
9727 If the filesystem is unlabeled, this returns the empty string.
9729 To find a filesystem from the label, use "findfs-label".
9731 vfs-minimum-size
9733 vfs-minimum-size mountable
9734 Get the minimum size of filesystem in bytes. This is the minimum
9736 possible size for filesystem shrinking.
9737 If getting minimum size of specified filesystem is not supported, this
9739 will fail and set errno as ENOTSUP.
9740 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
9742 vfs-type
9744 vfs-type mountable
9745 This command gets the filesystem type corresponding to the filesystem
9747 on "mountable".
9748 For most filesystems, the result is the name of the Linux VFS module
9750 which would be used to mount this filesystem if you mounted it without
9751 specifying the filesystem type. For example a string such as "ext3" or
9752 "ntfs".
9753 vfs-uuid
9755 get-uuid
9756 vfs-uuid mountable
9757 This returns the filesystem UUID of the filesystem on "mountable".
9759 If the filesystem does not have a UUID, this returns the empty string.
9761 To find a filesystem from the UUID, use "findfs-uuid".
9763 vg-activate
9765 vg-activate true|false 'volgroups ...'
9766 This command activates or (if "activate" is false) deactivates all
9768 logical volumes in the listed volume groups "volgroups".
9769 This command is the same as running "vgchange -a y|n volgroups..."
9771 Note that if "volgroups" is an empty list then all volume groups are
9773 activated or deactivated.
9774 This command depends on the feature "lvm2". See also "feature-
9776 available".
9777 vg-activate-all
9779 vg-activate-all true|false
9780 This command activates or (if "activate" is false) deactivates all
9782 logical volumes in all volume groups.
9783 This command is the same as running "vgchange -a y|n"
9785 This command depends on the feature "lvm2". See also "feature-
9787 available".
9788 vgchange-uuid
9790 vgchange-uuid vg
9791 Generate a new random UUID for the volume group "vg".
9793 This command depends on the feature "lvm2". See also "feature-
9795 available".
9796 vgchange-uuid-all
9798 vgchange-uuid-all
9799 Generate new random UUIDs for all volume groups.
9801 This command depends on the feature "lvm2". See also "feature-
9803 available".
9804 vgcreate
9806 vgcreate volgroup 'physvols ...'
9807 This creates an LVM volume group called "volgroup" from the non-empty
9809 list of physical volumes "physvols".
9810 This command depends on the feature "lvm2". See also "feature-
9812 available".
9813 vglvuuids
9815 vglvuuids vgname
9816 Given a VG called "vgname", this returns the UUIDs of all the logical
9818 volumes created in this volume group.
9819 You can use this along with "lvs" and "lvuuid" calls to associate
9821 logical volumes and volume groups.
9822 See also "vgpvuuids".
9824 vgmeta
9826 vgmeta vgname
9827 "vgname" is an LVM volume group. This command examines the volume
9829 group and returns its metadata.
9830 Note that the metadata is an internal structure used by LVM, subject to
9832 change at any time, and is provided for information only.
9833 This command depends on the feature "lvm2". See also "feature-
9835 available".
9836 vgpvuuids
9838 vgpvuuids vgname
9839 Given a VG called "vgname", this returns the UUIDs of all the physical
9841 volumes that this volume group resides on.
9842 You can use this along with "pvs" and "pvuuid" calls to associate
9844 physical volumes and volume groups.
9845 See also "vglvuuids".
9847 vgremove
9849 vgremove vgname
9850 Remove an LVM volume group "vgname", (for example "VG").
9852 This also forcibly removes all logical volumes in the volume group (if
9854 any).
9855 This command depends on the feature "lvm2". See also "feature-
9857 available".
9858 vgrename
9860 vgrename volgroup newvolgroup
9861 Rename a volume group "volgroup" with the new name "newvolgroup".
9863 vgs
9865 vgs
9866 List all the volumes groups detected. This is the equivalent of the
9868 vgs(8) command.
9869 This returns a list of just the volume group names that were detected
9871 (eg. "VolGroup00").
9872 See also "vgs-full".
9874 This command depends on the feature "lvm2". See also "feature-
9876 available".
9877 vgs-full
9879 vgs-full
9880 List all the volumes groups detected. This is the equivalent of the
9882 vgs(8) command. The "full" version includes all fields.
9883 This command depends on the feature "lvm2". See also "feature-
9885 available".
9886 vgscan
9888 vgscan
9889 This rescans all block devices and rebuilds the list of LVM physical
9891 volumes, volume groups and logical volumes.
9892 This function is deprecated. In new code, use the "lvm-scan" call
9894 instead.
9895 Deprecated functions will not be removed from the API, but the fact
9897 that they are deprecated indicates that there are problems with correct
9898 use of these functions.
9899 vguuid
9901 vguuid vgname
9902 This command returns the UUID of the LVM VG named "vgname".
9904 wc-c
9906 wc-c path
9907 This command counts the characters in a file, using the "wc -c"
9909 external command.
9910 wc-l
9912 wc-l path
9913 This command counts the lines in a file, using the "wc -l" external
9915 command.
9916 wc-w
9918 wc-w path
9919 This command counts the words in a file, using the "wc -w" external
9921 command.
9922 wipefs
9924 wipefs device
9925 This command erases filesystem or RAID signatures from the specified
9927 "device" to make the filesystem invisible to libblkid.
9928 This does not erase the filesystem itself nor any other data from the
9930 "device".
9931 Compare with "zero" which zeroes the first few blocks of a device.
9933 This command depends on the feature "wipefs". See also "feature-
9935 available".
9936 write
9938 write path content
9939 This call creates a file called "path". The content of the file is the
9941 string "content" (which can contain any 8 bit data).
9942 See also "write-append".
9944 write-append
9946 write-append path content
9947 This call appends "content" to the end of file "path". If "path" does
9949 not exist, then a new file is created.
9950 See also "write".
9952 write-file
9954 write-file path content size
9955 This call creates a file called "path". The contents of the file is
9957 the string "content" (which can contain any 8 bit data), with length
9958 "size".
9959 As a special case, if "size" is 0 then the length is calculated using
9961 "strlen" (so in this case the content cannot contain embedded ASCII
9962 NULs).
9963 NB. Owing to a bug, writing content containing ASCII NUL characters
9965 does not work, even if the length is specified.
9966 Because of the message protocol, there is a transfer limit of somewhere
9968 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9969 This function is deprecated. In new code, use the "write" call
9971 instead.
9972 Deprecated functions will not be removed from the API, but the fact
9974 that they are deprecated indicates that there are problems with correct
9975 use of these functions.
9976 xfs-admin
9978 xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
9979 Change the parameters of the XFS filesystem on "device".
9981 Devices that are mounted cannot be modified. Administrators must
9983 unmount filesystems before this call can modify parameters.
9984 Some of the parameters of a mounted filesystem can be examined and
9986 modified using the "xfs-info" and "xfs-growfs" calls.
9987 This command has one or more optional arguments. See "OPTIONAL
9989 ARGUMENTS".
9990 This command depends on the feature "xfs". See also "feature-
9992 available".
9993 xfs-growfs
9995 xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
9996 Grow the XFS filesystem mounted at "path".
9998 The returned struct contains geometry information. Missing fields are
10000 returned as "-1" (for numeric fields) or empty string.
10001 This command has one or more optional arguments. See "OPTIONAL
10003 ARGUMENTS".
10004 This command depends on the feature "xfs". See also "feature-
10006 available".
10007 xfs-info
10009 xfs-info pathordevice
10010 "pathordevice" is a mounted XFS filesystem or a device containing an
10012 XFS filesystem. This command returns the geometry of the filesystem.
10013 The returned struct contains geometry information. Missing fields are
10015 returned as "-1" (for numeric fields) or empty string.
10016 This command depends on the feature "xfs". See also "feature-
10018 available".
10019 xfs-repair
10021 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:..]
10022 Repair corrupt or damaged XFS filesystem on "device".
10024 The filesystem is specified using the "device" argument which should be
10026 the device name of the disk partition or volume containing the
10027 filesystem. If given the name of a block device, "xfs_repair" will
10028 attempt to find the raw device associated with the specified block
10029 device and will use the raw device instead.
10030 Regardless, the filesystem to be repaired must be unmounted, otherwise,
10032 the resulting filesystem may be inconsistent or corrupt.
10033 The returned status indicates whether filesystem corruption was
10035 detected (returns 1) or was not detected (returns 0).
10036 This command has one or more optional arguments. See "OPTIONAL
10038 ARGUMENTS".
10039 This command depends on the feature "xfs". See also "feature-
10041 available".
10042 yara-destroy
10044 yara-destroy
10045 Destroy previously loaded Yara rules in order to free libguestfs
10047 resources.
10048 This command depends on the feature "libyara". See also "feature-
10050 available".
10051 yara-load
10053 yara-load (filename|-)
10054 Upload a set of Yara rules from local file filename.
10056 Yara rules allow to categorize files based on textual or binary
10058 patterns within their content. See "yara-scan" to see how to scan
10059 files with the loaded rules.
10060 Rules can be in binary format, as when compiled with yarac command, or
10062 in source code format. In the latter case, the rules will be first
10063 compiled and then loaded.
10064 Rules in source code format cannot include external files. In such
10066 cases, it is recommended to compile them first.
10067 Previously loaded rules will be destroyed.
10069 Use "-" instead of a filename to read/write from stdin/stdout.
10071 This command depends on the feature "libyara". See also "feature-
10073 available".
10074 yara-scan
10076 yara-scan path
10077 Scan a file with the previously loaded Yara rules.
10079 For each matching rule, a "yara_detection" structure is returned.
10081 The "yara_detection" structure contains the following fields.
10083 "yara_name"
10085 Path of the file matching a Yara rule.
10086 "yara_rule"
10088 Identifier of the Yara rule which matched against the given file.
10089 This command depends on the feature "libyara". See also "feature-
10091 available".
10092 zegrep
10094 zegrep regex path
10095 This calls the external "zegrep" program and returns the matching
10097 lines.
10098 Because of the message protocol, there is a transfer limit of somewhere
10100 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10101 This function is deprecated. In new code, use the "grep" call instead.
10103 Deprecated functions will not be removed from the API, but the fact
10105 that they are deprecated indicates that there are problems with correct
10106 use of these functions.
10107 zegrepi
10109 zegrepi regex path
10110 This calls the external "zegrep -i" program and returns the matching
10112 lines.
10113 Because of the message protocol, there is a transfer limit of somewhere
10115 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10116 This function is deprecated. In new code, use the "grep" call instead.
10118 Deprecated functions will not be removed from the API, but the fact
10120 that they are deprecated indicates that there are problems with correct
10121 use of these functions.
10122 zero
10124 zero device
10125 This command writes zeroes over the first few blocks of "device".
10127 How many blocks are zeroed isn't specified (but it’s not enough to
10129 securely wipe the device). It should be sufficient to remove any
10130 partition tables, filesystem superblocks and so on.
10131 If blocks are already zero, then this command avoids writing zeroes.
10133 This prevents the underlying device from becoming non-sparse or growing
10134 unnecessarily.
10135 See also: "zero-device", "scrub-device", "is-zero-device"
10137 zero-device
10139 zero-device device
10140 This command writes zeroes over the entire "device". Compare with
10142 "zero" which just zeroes the first few blocks of a device.
10143 If blocks are already zero, then this command avoids writing zeroes.
10145 This prevents the underlying device from becoming non-sparse or growing
10146 unnecessarily.
10147 zero-free-space
10149 zero-free-space directory
10150 Zero the free space in the filesystem mounted on directory. The
10152 filesystem must be mounted read-write.
10153 The filesystem contents are not affected, but any free space in the
10155 filesystem is freed.
10156 Free space is not "trimmed". You may want to call "fstrim" either as
10158 an alternative to this, or after calling this, depending on your
10159 requirements.
10160 zerofree
10162 zerofree device
10163 This runs the zerofree program on "device". This program claims to
10165 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
10166 it possible to compress the filesystem more effectively.
10167 You should not run this program if the filesystem is mounted.
10169 It is possible that using this program can damage the filesystem or
10171 data on the filesystem.
10172 This command depends on the feature "zerofree". See also "feature-
10174 available".
10175 zfgrep
10177 zfgrep pattern path
10178 This calls the external "zfgrep" program and returns the matching
10180 lines.
10181 Because of the message protocol, there is a transfer limit of somewhere
10183 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10184 This function is deprecated. In new code, use the "grep" call instead.
10186 Deprecated functions will not be removed from the API, but the fact
10188 that they are deprecated indicates that there are problems with correct
10189 use of these functions.
10190 zfgrepi
10192 zfgrepi pattern path
10193 This calls the external "zfgrep -i" program and returns the matching
10195 lines.
10196 Because of the message protocol, there is a transfer limit of somewhere
10198 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10199 This function is deprecated. In new code, use the "grep" call instead.
10201 Deprecated functions will not be removed from the API, but the fact
10203 that they are deprecated indicates that there are problems with correct
10204 use of these functions.
10205 zfile
10207 zfile meth path
10208 This command runs file(1) after first decompressing "path" using
10210 "meth".
10211 "meth" must be one of "gzip", "compress" or "bzip2".
10213 Since 1.0.63, use "file" instead which can now process compressed
10215 files.
10216 This function is deprecated. In new code, use the "file" call instead.
10218 Deprecated functions will not be removed from the API, but the fact
10220 that they are deprecated indicates that there are problems with correct
10221 use of these functions.
10222 zgrep
10224 zgrep regex path
10225 This calls the external zgrep(1) program and returns the matching
10227 lines.
10228 Because of the message protocol, there is a transfer limit of somewhere
10230 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10231 This function is deprecated. In new code, use the "grep" call instead.
10233 Deprecated functions will not be removed from the API, but the fact
10235 that they are deprecated indicates that there are problems with correct
10236 use of these functions.
10237 zgrepi
10239 zgrepi regex path
10240 This calls the external "zgrep -i" program and returns the matching
10242 lines.
10243 Because of the message protocol, there is a transfer limit of somewhere
10245 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10246 This function is deprecated. In new code, use the "grep" call instead.
10248 Deprecated functions will not be removed from the API, but the fact
10250 that they are deprecated indicates that there are problems with correct
10251 use of these functions.
10252
10254 guestfish returns 0 if the commands completed without error, or 1 if
10255 there was an error.
10256
10258 EDITOR
10259 The "edit" command uses $EDITOR as the editor. If not set, it uses
10260 "vi".
10261 GUESTFISH_DISPLAY_IMAGE
10263 The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
10264 images. If not set, it uses display(1).
10265 GUESTFISH_INIT
10267 Printed when guestfish starts. See "PROMPT".
10268 GUESTFISH_OUTPUT
10270 Printed before guestfish output. See "PROMPT".
10271 GUESTFISH_PID
10273 Used with the --remote option to specify the remote guestfish
10274 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
10275 SOCKET".
10276 GUESTFISH_PS1
10278 Set the command prompt. See "PROMPT".
10279 GUESTFISH_RESTORE
10281 Printed before guestfish exits. See "PROMPT".
10282 HEXEDITOR
10284 The "hexedit" command uses $HEXEDITOR as the external hex editor.
10285 If not specified, the external hexedit(1) program is used.
10286 HOME
10288 If compiled with GNU readline support, various files in the home
10289 directory can be used. See "FILES".
10290 LIBGUESTFS_APPEND
10292 Pass additional options to the guest kernel.
10293 LIBGUESTFS_ATTACH_METHOD
10295 This is the old way to set "LIBGUESTFS_BACKEND".
10296 LIBGUESTFS_BACKEND
10298 Choose the default way to create the appliance. See
10299 "guestfs_set_backend" in guestfs(3).
10300 LIBGUESTFS_BACKEND_SETTINGS
10302 A colon-separated list of backend-specific settings. See "BACKEND"
10303 in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
10304 LIBGUESTFS_CACHEDIR
10306 The location where libguestfs will cache its appliance, when using
10307 a supermin appliance. The appliance is cached and shared between
10308 all handles which have the same effective user ID.
10309 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
10311 "TMPDIR" is not set, then /var/tmp is used.
10312 See also "LIBGUESTFS_TMPDIR", "set-cachedir".
10314 LIBGUESTFS_DEBUG
10316 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
10317 same effect as using the -v option.
10318 LIBGUESTFS_HV
10320 Set the default hypervisor (usually qemu) binary that libguestfs
10321 uses. If not set, then the qemu which was found at compile time by
10322 the configure script is used.
10323 LIBGUESTFS_MEMSIZE
10325 Set the memory allocated to the qemu process, in megabytes. For
10326 example:
10327 LIBGUESTFS_MEMSIZE=700
10329 LIBGUESTFS_PATH
10331 Set the path that guestfish uses to search for kernel and
10332 initrd.img. See the discussion of paths in guestfs(3).
10333 LIBGUESTFS_QEMU
10335 This is the old way to set "LIBGUESTFS_HV".
10336 LIBGUESTFS_TMPDIR
10338 The location where libguestfs will store temporary files used by
10339 each handle.
10340 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
10342 "TMPDIR" is not set, then /tmp is used.
10343 See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
10345 LIBGUESTFS_TRACE
10347 Set "LIBGUESTFS_TRACE=1" to enable command traces.
10348 PAGER
10350 The "more" command uses $PAGER as the pager. If not set, it uses
10351 "more".
10352 PATH
10354 Libguestfs and guestfish may run some external programs, and rely
10355 on $PATH being set to a reasonable value. If using the libvirt
10356 backend, libvirt will not work at all unless $PATH contains the
10357 path of qemu/KVM.
10358 SUPERMIN_KERNEL
10360 SUPERMIN_KERNEL_VERSION
10361 SUPERMIN_MODULES
10362 These three environment variables allow the kernel that libguestfs
10363 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
10364 set, then the most recent host kernel is chosen. For more
10365 information about kernel selection, see supermin(1).
10366 TMPDIR
10368 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
10369 XDG_RUNTIME_DIR
10371 This directory represents a user-specific directory for storing
10372 non-essential runtime files.
10373 If it is set, then is used to store temporary sockets. Otherwise,
10375 /tmp is used.
10376 See also "get-sockdir",
10378 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
10379
10381 $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
10382 $HOME/.libguestfs-tools.rc
10383 $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
10384 /etc/libguestfs-tools.conf
10385 This configuration file controls the default read-only or read-
10386 write mode (--ro or --rw).
10387 See libguestfs-tools.conf(5).
10389 $HOME/.guestfish
10391 If compiled with GNU readline support, then the command history is
10392 saved in this file.
10393 $HOME/.inputrc
10395 /etc/inputrc
10396 If compiled with GNU readline support, then these files can be used
10397 to configure readline. For further information, please see
10398 "INITIALIZATION FILE" in readline(3).
10399 To write rules which only apply to guestfish, use:
10401 $if guestfish
10403 ...
10404 $endif
10405 Variables that you can set in inputrc that change the behaviour of
10407 guestfish in useful ways include:
10408 completion-ignore-case (default: on)
10410 By default, guestfish will ignore case when tab-completing
10411 paths on the disk. Use:
10412 set completion-ignore-case off
10414 to make guestfish case sensitive.
10416 test1.img
10418 test2.img (etc)
10419 When using the -N or --new option, the prepared disk or filesystem
10420 will be created in the file test1.img in the current directory.
10421 The second use of -N will use test2.img and so on. Any existing
10422 file with the same name will be overwritten. You can use a
10423 different filename by using the "filename=" prefix.
10424
10426 guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
10427 virt-builder(1), virt-builder-repository(1), virt-cat(1),
10428 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
10429 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1),
10430 virt-list-filesystems(1), virt-list-partitions(1), virt-log(1),
10431 virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
10432 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
10433 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
10434 virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1),
10435 supermin(1).
10436
10438 Richard W.M. Jones ("rjones at redhat dot com")
10439
10441 Copyright (C) 2009-2020 Red Hat Inc.
10442
10444 This program is free software; you can redistribute it and/or modify it
10445 under the terms of the GNU General Public License as published by the
10446 Free Software Foundation; either version 2 of the License, or (at your
10447 option) any later version.
10448 This program is distributed in the hope that it will be useful, but
10450 WITHOUT ANY WARRANTY; without even the implied warranty of
10451 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10452 General Public License for more details.
10453 You should have received a copy of the GNU General Public License along
10455 with this program; if not, write to the Free Software Foundation, Inc.,
10456 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
10457
10459 To get a list of bugs against libguestfs, use this link:
10460 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
10461 To report a new bug against libguestfs, use this link:
10463 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
10464 When reporting a bug, please supply:
10466 • The version of libguestfs.
10468 • Where you got libguestfs (eg. which Linux distro, compiled from
10470 source, etc)
10471 • Describe the bug accurately and give a way to reproduce it.
10473 • Run libguestfs-test-tool(1) and paste the complete, unedited output
10475 into the bug report.
10476libguestfs-1.46.0 2021-09-23 guestfish(1)