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 -m dev[:mountpoint[:options[:fstype]]]
295 --mount dev[:mountpoint[:options[:fstype]]]
296 Mount the named partition or logical volume on the given
297 mountpoint.
298 If the mountpoint is omitted, it defaults to /.
300 You have to mount something on / before most commands will work.
302 If any -m or --mount options are given, the guest is automatically
304 launched.
305 If you don’t know what filesystems a disk image contains, you can
307 either run guestfish without this option, then list the partitions,
308 filesystems and LVs available (see "list-partitions", "list-
309 filesystems" and "lvs" commands), or you can use the
310 virt-filesystems(1) program.
311 The third (and rarely used) part of the mount parameter is the list
313 of mount options used to mount the underlying filesystem. If this
314 is not given, then the mount options are either the empty string or
315 "ro" (the latter if the --ro flag is used). By specifying the
316 mount options, you override this default choice. Probably the only
317 time you would use this is to enable ACLs and/or extended
318 attributes if the filesystem can support them:
319 -m /dev/sda1:/:acl,user_xattr
321 Using this flag is equivalent to using the "mount-options" command.
323 The fourth part of the parameter is the filesystem driver to use,
325 such as "ext3" or "ntfs". This is rarely needed, but can be useful
326 if multiple drivers are valid for a filesystem (eg: "ext2" and
327 "ext3"), or if libguestfs misidentifies a filesystem.
328 --network
330 Enable QEMU user networking in the guest.
331 -N [FILENAME=]TYPE
333 --new [FILENAME=]TYPE
334 -N help
335 Prepare a fresh disk image formatted as "TYPE". This is an
336 alternative to the -a option: whereas -a adds an existing disk, -N
337 creates a preformatted disk with a filesystem and adds it. See
338 "PREPARED DISK IMAGES" below.
339 -n
341 --no-sync
342 Disable autosync. This is enabled by default. See the discussion
343 of autosync in the guestfs(3) manpage.
344 --no-dest-paths
346 Don’t tab-complete paths on the guest filesystem. It is useful to
347 be able to hit the tab key to complete paths on the guest
348 filesystem, but this causes extra "hidden" guestfs calls to be
349 made, so this option is here to allow this feature to be disabled.
350 --pipe-error
352 If writes fail to pipe commands (see "PIPES" below), then the
353 command returns an error.
354 The default (also for historical reasons) is to ignore such errors
356 so that:
357 ><fs> command_with_lots_of_output | head
359 doesn't give an error.
361 --progress-bars
363 Enable progress bars, even when guestfish is used non-
364 interactively.
365 Progress bars are enabled by default when guestfish is used as an
367 interactive shell.
368 --no-progress-bars
370 Disable progress bars.
371 --remote
373 --remote=PID
374 Send remote commands to $GUESTFISH_PID or "pid". See section
375 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
376 -r
378 --ro
379 This changes the -a, -d and -m options so that disks are added and
380 mounts are done read-only.
381 The option must always be used if the disk image or virtual machine
383 might be running, and is generally recommended in cases where you
384 don't need write access to the disk.
385 Note that prepared disk images created with -N are not affected by
387 this option. Also commands like "add" are not affected - you have
388 to specify the "readonly:true" option explicitly if you need it.
389 See also "OPENING DISKS FOR READ AND WRITE" below.
391 --selinux
393 This option is provided for backwards compatibility and does
394 nothing.
395 -v
397 --verbose
398 Enable very verbose messages. This is particularly useful if you
399 find a bug.
400 -V
402 --version
403 Display the guestfish / libguestfs version number and exit.
404 -w
406 --rw
407 This changes the -a, -d and -m options so that disks are added and
408 mounts are done read-write.
409 See "OPENING DISKS FOR READ AND WRITE" below.
411 -x Echo each command before executing it.
413
415 Any additional (non-option) arguments are treated as commands to
416 execute.
417 Commands to execute should be separated by a colon (":"), where the
419 colon is a separate parameter. Thus:
420 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
422 If there are no additional arguments, then we enter a shell, either an
424 interactive shell with a prompt (if the input is a terminal) or a non-
425 interactive shell.
426 In either command line mode or non-interactive shell, the first command
428 that gives an error causes the whole shell to exit. In interactive
429 mode (with a prompt) if a command fails, you can continue to enter
430 commands.
431 Note that arguments of the commands will be considered as guestfish
433 options if they start with a dash ("-"): you can always separate the
434 guestfish options and the rest of the commands (with their arguments)
435 using a double dash ("--"). For example:
436 guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img
438
440 As with guestfs(3), you must first configure your guest by adding
441 disks, then launch it, then mount any disks you need, and finally issue
442 actions/commands. So the general order of the day is:
443 • add or -a/--add
445 • launch (aka run)
447 • mount or -m/--mount
449 • any other commands
451 "run" is a synonym for "launch". You must "launch" (or "run") your
453 guest before mounting or performing any other commands.
454 The only exception is that if any of the -i, -m, --mount, -N or --new
456 options were given then "run" is done automatically, simply because
457 guestfish can't perform the action you asked for without doing this.
458
460 The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
461 affect whether the other command line options -a, -c, -d, -i and -m
462 open disk images read-only or for writing.
463 In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
465 to opening disk images supplied on the command line for write. To open
466 a disk image read-only you have to do -a image --ro.
467 This matters: If you accidentally open a live VM disk image writable
469 then you will cause irreversible disk corruption.
470 In a future libguestfs we intend to change the default the other way.
472 Disk images will be opened read-only. You will have to either specify
473 guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
474 configuration file in order to get write access for disk images
475 specified by those other command line options.
476 This version of guestfish, guestmount and virt-rescue has a --rw option
478 which does nothing (it is already the default). However it is highly
479 recommended that you use this option to indicate that you need write
480 access, and prepare your scripts for the day when this option will be
481 required for write access.
482 Note: This does not affect commands like "add" and "mount", or any
484 other libguestfs program apart from guestfish and guestmount.
485
487 You can quote ordinary parameters using either single or double quotes.
488 For example:
489 add "file with a space.img"
491 rm '/file name'
493 rm '/"'
495 A few commands require a list of strings to be passed. For these, use
497 a whitespace-separated list, enclosed in quotes. Strings containing
498 whitespace to be passed through must be enclosed in single quotes. A
499 literal single quote must be escaped with a backslash.
500 vgcreate VG "/dev/sda1 /dev/sdb1"
502 command "/bin/echo 'foo bar'"
503 command "/bin/echo \'foo\'"
504 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
506 In double-quoted arguments (only) use backslash to insert special
507 characters:
508 "\a"
510 Alert (bell) character.
511 "\b"
513 Backspace character.
514 "\f"
516 Form feed character.
517 "\n"
519 Newline character.
520 "\r"
522 Carriage return character.
523 "\t"
525 Horizontal tab character.
526 "\v"
528 Vertical tab character.
529 "\""
531 A literal double quote character.
532 "\ooo"
534 A character with octal value ooo. There must be precisely 3 octal
535 digits (unlike C).
536 "\xhh"
538 A character with hex value hh. There must be precisely 2 hex
539 digits.
540 In the current implementation "\000" and "\x00" cannot be used in
542 strings.
543 "\\"
545 A literal backslash character.
546
548 Some commands take optional arguments. These arguments appear in this
549 documentation as "[argname:..]". You can use them as in these
550 examples:
551 add filename
553 add filename readonly:true
555 add filename format:qcow2 readonly:false
557 Each optional argument can appear at most once. All optional arguments
559 must appear after the required ones.
560
562 This section applies to all commands which can take integers as
563 parameters.
564 SIZE SUFFIX
566 When the command takes a parameter measured in bytes, you can use one
567 of the following suffixes to specify kilobytes, megabytes and larger
568 sizes:
569 k or K or KiB
571 The size in kilobytes (multiplied by 1024).
572 KB The size in SI 1000 byte units.
574 M or MiB
576 The size in megabytes (multiplied by 1048576).
577 MB The size in SI 1000000 byte units.
579 G or GiB
581 The size in gigabytes (multiplied by 2**30).
582 GB The size in SI 10**9 byte units.
584 T or TiB
586 The size in terabytes (multiplied by 2**40).
587 TB The size in SI 10**12 byte units.
589 P or PiB
591 The size in petabytes (multiplied by 2**50).
592 PB The size in SI 10**15 byte units.
594 E or EiB
596 The size in exabytes (multiplied by 2**60).
597 EB The size in SI 10**18 byte units.
599 Z or ZiB
601 The size in zettabytes (multiplied by 2**70).
602 ZB The size in SI 10**21 byte units.
604 Y or YiB
606 The size in yottabytes (multiplied by 2**80).
607 YB The size in SI 10**24 byte units.
609 For example:
611 truncate-size /file 1G
613 would truncate the file to 1 gigabyte.
615 Be careful because a few commands take sizes in kilobytes or megabytes
617 (eg. the parameter to "memsize" is specified in megabytes already).
618 Adding a suffix will probably not do what you expect.
619 OCTAL AND HEXADECIMAL NUMBERS
621 For specifying the radix (base) use the C convention: 0 to prefix an
622 octal number or "0x" to prefix a hexadecimal number. For example:
623 1234 decimal number 1234
625 02322 octal number, equivalent to decimal 1234
626 0x4d2 hexadecimal number, equivalent to decimal 1234
627 When using the "chmod" command, you almost always want to specify an
629 octal number for the mode, and you must prefix it with 0 (unlike the
630 Unix chmod(1) program):
631 chmod 0777 /public # OK
633 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
634 Commands that return numbers usually print them in decimal, but some
636 commands print numbers in other radices (eg. "umask" prints the mode in
637 octal, preceded by 0).
638
640 Neither guestfish nor the underlying guestfs API performs wildcard
641 expansion (globbing) by default. So for example the following will not
642 do what you expect:
643 rm-rf /home/*
645 Assuming you don’t have a directory called literally /home/* then the
647 above command will return an error.
648 To perform wildcard expansion, use the "glob" command.
650 glob rm-rf /home/*
652 runs "rm-rf" on each path that matches (ie. potentially running the
654 command many times), equivalent to:
655 rm-rf /home/jim
657 rm-rf /home/joe
658 rm-rf /home/mary
659 "glob" only works on simple guest paths and not on device names.
661 If you have several parameters, each containing a wildcard, then glob
663 will perform a Cartesian product.
664
666 Any line which starts with a # character is treated as a comment and
667 ignored. The # can optionally be preceded by whitespace, but not by a
668 command. For example:
669 # this is a comment
671 # this is a comment
672 foo # NOT a comment
673 Blank lines are also ignored.
675
677 Any line which starts with a ! character is treated as a command sent
678 to the local shell (/bin/sh or whatever system(3) uses). For example:
679 !mkdir local
681 tgz-out /remote local/remote-data.tar.gz
682 will create a directory "local" on the host, and then export the
684 contents of /remote on the mounted filesystem to
685 local/remote-data.tar.gz. (See "tgz-out").
686 To change the local directory, use the "lcd" command. "!cd" will have
688 no effect, due to the way that subprocesses work in Unix.
689 LOCAL COMMANDS WITH INLINE EXECUTION
691 If a line starts with <! then the shell command is executed (as for !),
692 but subsequently any output (stdout) of the shell command is parsed and
693 executed as guestfish commands.
694 Thus you can use shell script to construct arbitrary guestfish commands
696 which are then parsed by guestfish.
697 For example it is tedious to create a sequence of files (eg. /foo.1
699 through /foo.100) using guestfish commands alone. However this is
700 simple if we use a shell script to create the guestfish commands for
701 us:
702 <! for n in `seq 1 100`; do echo write /foo.$n $n; done
704 or with names like /foo.001:
706 <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
708 When using guestfish interactively it can be helpful to just run the
710 shell script first (ie. remove the initial "<" character so it is just
711 an ordinary ! local command), see what guestfish commands it would run,
712 and when you are happy with those prepend the "<" character to run the
713 guestfish commands for real.
714
716 Use "command <space> | command" to pipe the output of the first command
717 (a guestfish command) to the second command (any host command). For
718 example:
719 cat /etc/passwd | awk -F: '$3 == 0 { print }'
721 (where "cat" is the guestfish cat command, but "awk" is the host awk
723 program). The above command would list all accounts in the guest
724 filesystem which have UID 0, ie. root accounts including backdoors.
725 Other examples:
726 hexdump /bin/ls | head
728 list-devices | tail -1
729 tgz-out / - | tar ztf -
730 The space before the pipe symbol is required, any space after the pipe
732 symbol is optional. Everything after the pipe symbol is just passed
733 straight to the host shell, so it can contain redirections, globs and
734 anything else that makes sense on the host side.
735 To use a literal argument which begins with a pipe symbol, you have to
737 quote it, eg:
738 echo "|"
740
742 If a parameter starts with the character "~" then the tilde may be
743 expanded as a home directory path (either "~" for the current user's
744 home directory, or "~user" for another user).
745 Note that home directory expansion happens for users known on the host,
747 not in the guest filesystem.
748 To use a literal argument which begins with a tilde, you have to quote
750 it, eg:
751 echo "~"
753
755 Libguestfs has some support for Linux guests encrypted according to the
756 Linux Unified Key Setup (LUKS) standard, which includes nearly all
757 whole disk encryption systems used by modern Linux guests, and Windows
758 BitLocker.
759 Identify encrypted block devices and partitions using "vfs-type":
761 ><fs> vfs-type /dev/sda2
763 crypto_LUKS
764 or:
766 ><fs> vfs-type /dev/sda2
768 BitLocker
769 Then open those devices using "cryptsetup-open". This creates a
771 device-mapper device called /dev/mapper/name.
772 ><fs> cryptsetup-open /dev/sda2 name
774 Enter key or passphrase ("key"): <enter the passphrase>
775 For Linux guests you have to tell LVM to scan for volume groups on the
777 newly created mapper device:
778 vgscan
780 vg-activate-all true
781 The filesystems or logical volumes can now be mounted in the usual way.
783 Before closing an encrypted device you must unmount any logical volumes
785 on it and deactivate the volume groups by calling "vg-activate false
786 VG" on each one. Then you can close the mapper device:
787 vg-activate false /dev/VG
789 cryptsetup-close /dev/mapper/name
790
792 If a path is prefixed with "win:" then you can use Windows-style drive
793 letters and paths (with some limitations). The following commands are
794 equivalent:
795 file /WINDOWS/system32/config/system.LOG
797 file win:\windows\system32\config\system.log
799 file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
801 The parameter is rewritten "behind the scenes" by looking up the
803 position where the drive is mounted, prepending that to the path,
804 changing all backslash characters to forward slash, then resolving the
805 result using "case-sensitive-path". For example if the E: drive was
806 mounted on /e then the parameter might be rewritten like this:
807 win:e:\foo\bar => /e/FOO/bar
809 This only works in argument positions that expect a path.
811
813 For commands such as "upload", "download", "tar-in", "tar-out" and
814 others which upload from or download to a local file, you can use the
815 special filename "-" to mean "from stdin" or "to stdout". For example:
816 upload - /foo
818 reads stdin and creates from that a file /foo in the disk image, and:
820 tar-out /etc - | tar tf -
822 writes the tarball to stdout and then pipes that into the external
824 "tar" command (see "PIPES").
825 When using "-" to read from stdin, the input is read up to the end of
827 stdin. You can also use a special "heredoc"-like syntax to read up to
828 some arbitrary end marker:
829 upload -<<END /foo
831 input line 1
832 input line 2
833 input line 3
834 END
835 Any string of characters can be used instead of "END". The end marker
837 must appear on a line of its own, without any preceding or following
838 characters (not even spaces).
839 Note that the "-<<" syntax only applies to parameters used to upload
841 local files (so-called "FileIn" parameters in the generator).
842
844 By default, guestfish will ignore any errors when in interactive mode
845 (ie. taking commands from a human over a tty), and will exit on the
846 first error in non-interactive mode (scripts, commands given on the
847 command line).
848 If you prefix a command with a - character, then that command will not
850 cause guestfish to exit, even if that (one) command returns an error.
851
853 Guestfish can be remote-controlled over a socket. This is useful
854 particularly in shell scripts where you want to make several different
855 changes to a filesystem, but you don't want the overhead of starting up
856 a guestfish process each time.
857 Start a guestfish server process using:
859 eval "`guestfish --listen`"
861 and then send it commands by doing:
863 guestfish --remote cmd [...]
865 To cause the server to exit, send it the exit command:
867 guestfish --remote exit
869 Note that the server will normally exit if there is an error in a
871 command. You can change this in the usual way. See section "EXIT ON
872 ERROR BEHAVIOUR".
873 CONTROLLING MULTIPLE GUESTFISH PROCESSES
875 The "eval" statement sets the environment variable $GUESTFISH_PID,
876 which is how the --remote option knows where to send the commands. You
877 can have several guestfish listener processes running using:
878 eval "`guestfish --listen`"
880 pid1=$GUESTFISH_PID
881 eval "`guestfish --listen`"
882 pid2=$GUESTFISH_PID
883 ...
884 guestfish --remote=$pid1 cmd
885 guestfish --remote=$pid2 cmd
886 REMOTE CONTROL AND CSH
888 When using csh-like shells (csh, tcsh etc) you have to add the --csh
889 option:
890 eval "`guestfish --listen --csh`"
892 REMOTE CONTROL DETAILS
894 Remote control happens over a Unix domain socket called
895 /tmp/.guestfish-$UID/socket-$PID, where $UID is the effective user ID
896 of the process, and $PID is the process ID of the server.
897 Guestfish client and server versions must match exactly.
899 Older versions of guestfish were vulnerable to CVE-2013-4419 (see
901 "CVE-2013-4419" in guestfs(3)). This is fixed in the current version.
902 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
904 From Bash, you can use the following code which creates a guestfish
905 instance, correctly quotes the command line, handles failure to start,
906 and cleans up guestfish when the script exits:
907 #!/bin/bash -
909 set -e
911 guestfish[0]="guestfish"
913 guestfish[1]="--listen"
914 guestfish[2]="--ro"
915 guestfish[3]="-a"
916 guestfish[4]="disk.img"
917 GUESTFISH_PID=
919 eval $("${guestfish[@]}")
920 if [ -z "$GUESTFISH_PID" ]; then
921 echo "error: guestfish didn't start up, see error messages above"
922 exit 1
923 fi
924 cleanup_guestfish ()
926 {
927 guestfish --remote -- exit >/dev/null 2>&1 ||:
928 }
929 trap cleanup_guestfish EXIT ERR
930 guestfish --remote -- run
932 # ...
934 REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
936 Options such as -a, --add, -N, --new etc don’t interact properly with
937 remote support. They are processed locally, and not sent through to
938 the remote guestfish. In particular this won't do what you expect:
939 guestfish --remote --add disk.img
941 Don’t use these options. Use the equivalent commands instead, eg:
943 guestfish --remote add-drive disk.img
945 or:
947 guestfish --remote
949 ><fs> add disk.img
950 REMOTE CONTROL RUN COMMAND HANGING
952 Using the "run" (or "launch") command remotely in a command
953 substitution context hangs, ie. don't do (note the backquotes):
954 a=`guestfish --remote run`
956 Since the "run" command produces no output on stdout, this is not
958 useful anyway. For further information see
959 https://bugzilla.redhat.com/show_bug.cgi?id=592910.
960
962 Use the -N [filename=]type or --new [filename=]type parameter to select
963 one of a set of preformatted disk images that guestfish can make for
964 you to save typing. This is particularly useful for testing purposes.
965 This option is used instead of the -a option, and like -a can appear
966 multiple times (and can be mixed with -a).
967 The new disk is called test1.img for the first -N, test2.img for the
969 second and so on. Existing files in the current directory are
970 overwritten. You can use a different filename by specifying
971 "filename=" before the type (see examples below).
972 The type briefly describes how the disk should be sized, partitioned,
974 how filesystem(s) should be created, and how content should be added.
975 Optionally the type can be followed by extra parameters, separated by
976 ":" (colon) characters. For example, -N fs creates a default 1G,
977 sparsely-allocated disk, containing a single partition, with the
978 partition formatted as ext2. -N fs:ext4:2G is the same, but for an
979 ext4 filesystem on a 2GB disk instead.
980 Note that the prepared filesystem is not mounted. You would usually
982 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
983 option.
984 If any -N or --new options are given, the libguestfs appliance is
986 automatically launched.
987 EXAMPLES
989 Create a 1G disk with an ext4-formatted partition, called test1.img in
990 the current directory:
991 guestfish -N fs:ext4
993 Create a 32MB disk with a VFAT-formatted partition, and mount it:
995 guestfish -N fs:vfat:32M -m /dev/sda1
997 Create a blank 200MB disk:
999 guestfish -N disk:200M
1001 Create a blank 200MB disk called blankdisk.img (instead of test1.img):
1003 guestfish -N blankdisk.img=disk:200M
1005 -N disk - create a blank disk
1007 "guestfish -N [filename=]disk[:size]"
1008 Create a blank disk, size 1G (by default).
1010 The default size can be changed by supplying an optional parameter.
1012 The optional parameters are:
1014 Name Default value
1016 size 1G the size of the disk image
1017 -N part - create a partitioned disk
1019 "guestfish -N [filename=]part[:size[:partition]]"
1020 Create a disk with a single partition. By default the size of the disk
1022 is 1G (the available space in the partition will be a tiny bit smaller)
1023 and the partition table will be MBR (old DOS-style).
1024 These defaults can be changed by supplying optional parameters.
1026 The optional parameters are:
1028 Name Default value
1030 size 1G the size of the disk image
1031 partition mbr partition table type
1032 -N fs - create a filesystem
1034 "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"
1035 Create a disk with a single partition, with the partition containing an
1037 empty filesystem. This defaults to creating a 1G disk (the available
1038 space in the filesystem will be a tiny bit smaller) with an MBR (old
1039 DOS-style) partition table and an ext2 filesystem.
1040 These defaults can be changed by supplying optional parameters.
1042 The optional parameters are:
1044 Name Default value
1046 filesystem ext2 the type of filesystem to use
1047 size 1G the size of the disk image
1048 partition mbr partition table type
1049 -N lv - create a disk with logical volume
1051 "guestfish -N [filename=]lv[:name[:size[:partition]]]"
1052 Create a disk with a single partition, set up the partition as an LVM2
1054 physical volume, and place a volume group and logical volume on there.
1055 This defaults to creating a 1G disk with the VG and LV called
1056 "/dev/VG/LV". You can change the name of the VG and LV by supplying an
1057 alternate name as the first optional parameter.
1058 Note this does not create a filesystem. Use 'lvfs' to do that.
1060 The optional parameters are:
1062 Name Default value
1064 name /dev/VG/LV the name of the VG and LV to use
1065 size 1G the size of the disk image
1066 partition mbr partition table type
1067 -N lvfs - create a disk with logical volume and filesystem
1069 "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"
1070 Create a disk with a single partition, set up the partition as an LVM2
1072 physical volume, and place a volume group and logical volume on there.
1073 Then format the LV with a filesystem. This defaults to creating a 1G
1074 disk with the VG and LV called "/dev/VG/LV", with an ext2 filesystem.
1075 The optional parameters are:
1077 Name Default value
1079 name /dev/VG/LV the name of the VG and LV to use
1080 filesystem ext2 the type of filesystem to use
1081 size 1G the size of the disk image
1082 partition mbr partition table type
1083 -N bootroot - create a boot and root filesystem
1085 "guestfish -N
1086 [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"
1087 Create a disk with two partitions, for boot and root filesystem.
1089 Format the two filesystems independently. There are several optional
1090 parameters which control the exact layout and filesystem types.
1091 The optional parameters are:
1093 Name Default value
1095 bootfs ext2 the type of filesystem to use for boot
1096 rootfs ext2 the type of filesystem to use for root
1097 size 1G the size of the disk image
1098 bootsize 128M the size of the boot filesystem
1099 partition mbr partition table type
1100 -N bootrootlv - create a boot and root filesystem using LVM
1102 "guestfish -N
1103 [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"
1104 This is the same as "bootroot" but the root filesystem (only) is placed
1106 on a logical volume, named by default "/dev/VG/LV". There are several
1107 optional parameters which control the exact layout.
1108 The optional parameters are:
1110 Name Default value
1112 name /dev/VG/LV the name of the VG and LV for root
1113 bootfs ext2 the type of filesystem to use for boot
1114 rootfs ext2 the type of filesystem to use for root
1115 size 1G the size of the disk image
1116 bootsize 128M the size of the boot filesystem
1117 partition mbr partition table type
1118
1120 For API-level documentation on this topic, see "guestfs_add_drive_opts"
1121 in guestfs(3) and "REMOTE STORAGE" in guestfs(3).
1122 On the command line, you can use the -a option to add network block
1124 devices using a URI-style format, for example:
1125 guestfish -a ssh://root@example.com/disk.img
1127 URIs cannot be used with the "add" command. The equivalent command
1129 using the API directly is:
1130 ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root
1132 The possible -a URI formats are described below.
1134 -a disk.img
1136 -a file:///path/to/disk.img
1137 Add the local disk image (or device) called disk.img.
1138 -a ftp://[user@]example.com[:port]/disk.img
1140 -a ftps://[user@]example.com[:port]/disk.img
1141 -a http://[user@]example.com[:port]/disk.img
1142 -a https://[user@]example.com[:port]/disk.img
1143 -a tftp://[user@]example.com[:port]/disk.img
1144 Add a disk located on a remote FTP, HTTP or TFTP server.
1145 The equivalent API command would be:
1147 ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com
1149 -a gluster://example.com[:port]/volname/image
1151 Add a disk image located on GlusterFS storage.
1152 The server is the one running "glusterd", and may be "localhost".
1154 The equivalent API command would be:
1156 ><fs> add volname/image protocol:gluster server:tcp:example.com
1158 -a iscsi://example.com[:port]/target-iqn-name[/lun]
1160 Add a disk located on an iSCSI server.
1161 The equivalent API command would be:
1163 ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com
1165 -a nbd://example.com[:port]
1167 -a nbd://example.com[:port]/exportname
1168 -a nbd://?socket=/socket
1169 -a nbd:///exportname?socket=/socket
1170 Add a disk located on Network Block Device (nbd) storage.
1171 The exportname part of the URI specifies an NBD export name, but is
1173 usually left empty.
1174 The optional ?socket parameter can be used to specify a Unix domain
1176 socket that we talk to the NBD server over. Note that you cannot mix
1177 server name (ie. TCP/IP) and socket path.
1178 The equivalent API command would be (no export name):
1180 ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]
1182 -a rbd:///pool/disk
1184 -a rbd://example.com[:port]/pool/disk
1185 Add a disk image located on a Ceph (RBD/librbd) storage volume.
1186 Although libguestfs and Ceph supports multiple servers, only a single
1188 server can be specified when using this URI syntax.
1189 The equivalent API command would be:
1191 ><fs> add pool/disk protocol:rbd server:tcp:example.com:port
1193 -a sheepdog://[example.com[:port]]/volume/image
1195 Add a disk image located on a Sheepdog volume.
1196 The server name is optional. Although libguestfs and Sheepdog supports
1198 multiple servers, only at most one server can be specified when using
1199 this URI syntax.
1200 The equivalent API command would be:
1202 ><fs> add volume protocol:sheepdog [server:tcp:example.com]
1204 -a ssh://[user@]example.com[:port]/disk.img
1206 Add a disk image located on a remote server, accessed using the Secure
1207 Shell (ssh) SFTP protocol. SFTP is supported out of the box by all
1208 major SSH servers.
1209 The equivalent API command would be:
1211 ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]
1213 Note that the URIs follow the syntax of RFC 3986: in particular, there
1215 are restrictions on the allowed characters for the various components
1216 of the URI. Characters such as ":", "@", and "/" must be percent-
1217 encoded:
1218 $ guestfish -a ssh://user:pass%40word@example.com/disk.img
1220 In this case, the password is "pass@word".
1222
1224 Some (not all) long-running commands send progress notification
1225 messages as they are running. Guestfish turns these messages into
1226 progress bars.
1227 When a command that supports progress bars takes longer than two
1229 seconds to run, and if progress bars are enabled, then you will see one
1230 appearing below the command:
1231 ><fs> copy-size /large-file /another-file 2048M
1233 / 10% [#####-----------------------------------------] 00:30
1234 The spinner on the left hand side moves round once for every progress
1236 notification received from the backend. This is a (reasonably) golden
1237 assurance that the command is "doing something" even if the progress
1238 bar is not moving, because the command is able to send the progress
1239 notifications. When the bar reaches 100% and the command finishes, the
1240 spinner disappears.
1241 Progress bars are enabled by default when guestfish is used
1243 interactively. You can enable them even for non-interactive modes
1244 using --progress-bars, and you can disable them completely using
1245 --no-progress-bars.
1246
1248 You can change or add colours to the default prompt ("><fs>") by
1249 setting the "GUESTFISH_PS1" environment variable. A second string
1250 ("GUESTFISH_OUTPUT") is printed after the command has been entered and
1251 before the output, allowing you to control the colour of the output. A
1252 third string ("GUESTFISH_INIT") is printed before the welcome message,
1253 allowing you to control the colour of that message. A fourth string
1254 ("GUESTFISH_RESTORE") is printed before guestfish exits.
1255 A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate
1257 string:
1258 $ GUESTFISH_PS1='(type a command) '
1260 $ export GUESTFISH_PS1
1261 $ guestfish
1262 [...]
1263 (type a command) ▂
1264 You can also use special escape sequences, as described in the table
1266 below:
1267 \\ A literal backslash character.
1269 \[
1271 \] (These should only be used in "GUESTFISH_PS1".)
1272 Place non-printing characters (eg. terminal control codes for
1274 colours) between "\[...\]". What this does it to tell the
1275 readline(3) library that it should treat this subsequence as zero-
1276 width, so that command-line redisplay, editing etc works.
1277 \a A bell character.
1279 \e An ASCII ESC (escape) character.
1281 \n A newline.
1283 \r A carriage return.
1285 \NNN
1287 The ASCII character whose code is the octal value NNN.
1288 \xNN
1290 The ASCII character whose code is the hex value NN.
1291 EXAMPLES OF PROMPTS
1293 Note that these examples require a terminal that supports ANSI escape
1294 codes.
1295 •
1297 GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1300 A bold black version of the ordinary prompt.
1302 •
1304 GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
1307 GUESTFISH_OUTPUT='\e[0m'
1308 GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
1309 GUESTFISH_INIT='\e[1;34m'
1310 Blue welcome text, green prompt, red commands, black command
1312 output.
1313
1315 Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1316 partitions. See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1317 guestfs(3).
1318
1320 The commands in this section are guestfish convenience commands, in
1321 other words, they are not part of the guestfs(3) API.
1322 help
1324 help
1325 help cmd
1326 help -l|--list
1327 Without any parameter, this provides general help.
1329 With a "cmd" parameter, this displays detailed help for that command.
1331 With -l or --list, this list all commands.
1333 exit
1335 quit
1336 This exits guestfish. You can also use "^D" key.
1337 alloc
1339 allocate
1340 alloc filename size
1341 This creates an empty (zeroed) file of the given size, and then adds so
1343 it can be further examined.
1344 For more advanced image creation, see "disk-create".
1346 Size can be specified using standard suffixes, eg. "1M".
1348 To create a sparse file, use "sparse" instead. To create a prepared
1350 disk image, see "PREPARED DISK IMAGES".
1351 copy-in
1353 copy-in local [local ...] /remotedir
1354 "copy-in" copies local files or directories recursively into the disk
1356 image, placing them in the directory called /remotedir (which must
1357 exist). This guestfish meta-command turns into a sequence of "tar-in"
1358 and other commands as necessary.
1359 Multiple local files and directories can be specified, but the last
1361 parameter must always be a remote directory. Wildcards cannot be used.
1362 copy-out
1364 copy-out remote [remote ...] localdir
1365 "copy-out" copies remote files or directories recursively out of the
1367 disk image, placing them on the host disk in a local directory called
1368 "localdir" (which must exist). This guestfish meta-command turns into
1369 a sequence of "download", "tar-out" and other commands as necessary.
1370 Multiple remote files and directories can be specified, but the last
1372 parameter must always be a local directory. To download to the current
1373 directory, use "." as in:
1374 copy-out /home .
1376 Wildcards cannot be used in the ordinary command, but you can use them
1378 with the help of "glob" like this:
1379 glob copy-out /home/* .
1381 delete-event
1383 delete-event name
1384 Delete the event handler which was previously registered as "name". If
1386 multiple event handlers were registered with the same name, they are
1387 all deleted.
1388 See also the guestfish commands "event" and "list-events".
1390 display
1392 display filename
1393 Use "display" (a graphical display program) to display an image file.
1395 It downloads the file, and runs "display" on it.
1396 To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1398 environment variable. For example to use the GNOME display program:
1399 export GUESTFISH_DISPLAY_IMAGE=eog
1401 See also display(1).
1403 echo
1405 echo [params ...]
1406 This echos the parameters to the terminal.
1408 edit
1410 vi
1411 emacs
1412 edit filename
1413 This is used to edit a file. It downloads the file, edits it locally
1415 using your editor, then uploads the result.
1416 The editor is $EDITOR. However if you use the alternate commands "vi"
1418 or "emacs" you will get those corresponding editors.
1419 event
1421 event name eventset "shell script ..."
1422 Register a shell script fragment which is executed when an event is
1424 raised. See "guestfs_set_event_callback" in guestfs(3) for a
1425 discussion of the event API in libguestfs.
1426 The "name" parameter is a name that you give to this event handler. It
1428 can be any string (even the empty string) and is simply there so you
1429 can delete the handler using the guestfish "delete-event" command.
1430 The "eventset" parameter is a comma-separated list of one or more
1432 events, for example "close" or "close,trace". The special value "*"
1433 means all events.
1434 The third and final parameter is the shell script fragment (or any
1436 external command) that is executed when any of the events in the
1437 eventset occurs. It is executed using "$SHELL -c", or if $SHELL is not
1438 set then /bin/sh -c.
1439 The shell script fragment receives callback parameters as arguments $1,
1441 $2 etc. The actual event that was called is available in the
1442 environment variable $EVENT.
1443 event "" close "echo closed"
1445 event messages appliance,library,trace "echo $@"
1446 event "" progress "echo progress: $3/$4"
1447 event "" * "echo $EVENT $@"
1448 See also the guestfish commands "delete-event" and "list-events".
1450 glob
1452 glob command args...
1453 Expand wildcards in any paths in the args list, and run "command"
1455 repeatedly on each matching path.
1456 See "WILDCARDS AND GLOBBING".
1458 hexedit
1460 hexedit <filename|device>
1461 hexedit <filename|device> <max>
1462 hexedit <filename|device> <start> <max>
1463 Use hexedit (a hex editor) to edit all or part of a binary file or
1465 block device.
1466 This command works by downloading potentially the whole file or device,
1468 editing it locally, then uploading it. If the file or device is large,
1469 you have to specify which part you wish to edit by using "max" and/or
1470 "start" "max" parameters. "start" and "max" are specified in bytes,
1471 with the usual modifiers allowed such as "1M" (1 megabyte).
1472 For example to edit the first few sectors of a disk you might do:
1474 hexedit /dev/sda 1M
1476 which would allow you to edit anywhere within the first megabyte of the
1478 disk.
1479 To edit the superblock of an ext2 filesystem on /dev/sda1, do:
1481 hexedit /dev/sda1 0x400 0x400
1483 (assuming the superblock is in the standard location).
1485 This command requires the external hexedit(1) program. You can specify
1487 another program to use by setting the "HEXEDITOR" environment variable.
1488 See also "hexdump".
1490 lcd
1492 lcd directory
1493 Change the local directory, ie. the current directory of guestfish
1495 itself.
1496 Note that "!cd" won't do what you might expect.
1498 list-events
1500 list-events
1501 List the event handlers registered using the guestfish "event" command.
1503 man
1505 manual
1506 man
1507 Opens the manual page for guestfish.
1509 more
1511 less
1512 more filename
1513 less filename
1515 This is used to view a file.
1517 The default viewer is $PAGER. However if you use the alternate command
1519 "less" you will get the "less" command specifically.
1520 reopen
1522 reopen
1523 Close and reopen the libguestfs handle. It is not necessary to use
1525 this normally, because the handle is closed properly when guestfish
1526 exits. However this is occasionally useful for testing.
1527 setenv
1529 setenv VAR value
1530 Set the environment variable "VAR" to the string "value".
1532 To print the value of an environment variable use a shell command such
1534 as:
1535 !echo $VAR
1537 sparse
1539 sparse filename size
1540 This creates an empty sparse file of the given size, and then adds so
1542 it can be further examined.
1543 In all respects it works the same as the "alloc" command, except that
1545 the image file is allocated sparsely, which means that disk blocks are
1546 not assigned to the file until they are needed. Sparse disk files only
1547 use space when written to, but they are slower and there is a danger
1548 you could run out of real disk space during a write operation.
1549 For more advanced image creation, see "disk-create".
1551 Size can be specified using standard suffixes, eg. "1M".
1553 See also the guestfish "scratch" command.
1555 supported
1557 supported
1558 This command returns a list of the optional groups known to the daemon,
1560 and indicates which ones are supported by this build of the libguestfs
1561 appliance.
1562 See also "AVAILABILITY" in guestfs(3).
1564 time
1566 time command args...
1567 Run the command as usual, but print the elapsed time afterwards. This
1569 can be useful for benchmarking operations.
1570 unsetenv
1572 unsetenv VAR
1573 Remove "VAR" from the environment.
1575
1577 acl-delete-def-file
1578 acl-delete-def-file dir
1579 This function deletes the default POSIX Access Control List (ACL)
1581 attached to directory "dir".
1582 This command depends on the feature "acl". See also "feature-
1584 available".
1585 acl-get-file
1587 acl-get-file path acltype
1588 This function returns the POSIX Access Control List (ACL) attached to
1590 "path". The ACL is returned in "long text form" (see acl(5)).
1591 The "acltype" parameter may be:
1593 "access"
1595 Return the ordinary (access) ACL for any file, directory or other
1596 filesystem object.
1597 "default"
1599 Return the default ACL. Normally this only makes sense if "path"
1600 is a directory.
1601 This command depends on the feature "acl". See also "feature-
1603 available".
1604 acl-set-file
1606 acl-set-file path acltype acl
1607 This function sets the POSIX Access Control List (ACL) attached to
1609 "path".
1610 The "acltype" parameter may be:
1612 "access"
1614 Set the ordinary (access) ACL for any file, directory or other
1615 filesystem object.
1616 "default"
1618 Set the default ACL. Normally this only makes sense if "path" is a
1619 directory.
1620 The "acl" parameter is the new ACL in either "long text form" or "short
1622 text form" (see acl(5)). The new ACL completely replaces any previous
1623 ACL on the file. The ACL must contain the full Unix permissions (eg.
1624 "u::rwx,g::rx,o::rx").
1625 If you are specifying individual users or groups, then the mask field
1627 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1628 "g:ID:..." field(s). A full ACL string might therefore look like this:
1629 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1631 \ Unix permissions / \mask/ \ ACL /
1632 You should use numeric UIDs and GIDs. To map usernames and groupnames
1634 to the correct numeric ID in the context of the guest, use the Augeas
1635 functions (see "aug-init").
1636 This command depends on the feature "acl". See also "feature-
1638 available".
1639 add-cdrom
1641 add-cdrom filename
1642 This function adds a virtual CD-ROM disk image to the guest.
1644 The image is added as read-only drive, so this function is equivalent
1646 of "add-drive-ro".
1647 This function is deprecated. In new code, use the "add-drive-ro" call
1649 instead.
1650 Deprecated functions will not be removed from the API, but the fact
1652 that they are deprecated indicates that there are problems with correct
1653 use of these functions.
1654 add-domain
1656 domain
1657 add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]
1658 This function adds the disk(s) attached to the named libvirt domain
1660 "dom". It works by connecting to libvirt, requesting the domain and
1661 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1662 opts" on each one.
1663 The number of disks added is returned. This operation is atomic: if an
1665 error is returned, then no disks are added.
1666 This function does some minimal checks to make sure the libvirt domain
1668 is not running (unless "readonly" is true). In a future version we
1669 will try to acquire the libvirt lock on each disk.
1670 Disks must be accessible locally. This often means that adding disks
1672 from a remote libvirt connection (see https://libvirt.org/remote.html)
1673 will fail unless those disks are accessible via the same device path
1674 locally too.
1675 The optional "libvirturi" parameter sets the libvirt URI (see
1677 https://libvirt.org/uri.html). If this is not set then we connect to
1678 the default libvirt URI (or one set through an environment variable,
1679 see the libvirt documentation for full details).
1680 The optional "live" flag is ignored in libguestfs ≥ 1.48.
1682 If the "allowuuid" flag is true (default is false) then a UUID may be
1684 passed instead of the domain name. The "dom" string is treated as a
1685 UUID first and looked up, and if that lookup fails then we treat "dom"
1686 as a name as usual.
1687 The optional "readonlydisk" parameter controls what we do for disks
1689 which are marked <readonly/> in the libvirt XML. Possible values are:
1690 readonlydisk = "error"
1692 If "readonly" is false:
1693 The whole call is aborted with an error if any disk with the
1695 <readonly/> flag is found.
1696 If "readonly" is true:
1698 Disks with the <readonly/> flag are added read-only.
1700 readonlydisk = "read"
1702 If "readonly" is false:
1703 Disks with the <readonly/> flag are added read-only. Other disks
1705 are added read/write.
1706 If "readonly" is true:
1708 Disks with the <readonly/> flag are added read-only.
1710 readonlydisk = "write" (default)
1712 If "readonly" is false:
1713 Disks with the <readonly/> flag are added read/write.
1715 If "readonly" is true:
1717 Disks with the <readonly/> flag are added read-only.
1719 readonlydisk = "ignore"
1721 If "readonly" is true or false:
1722 Disks with the <readonly/> flag are skipped.
1724 If present, the value of "logical_block_size" attribute of <blockio/>
1726 tag in libvirt XML will be passed as "blocksize" parameter to "add-
1727 drive-opts".
1728 The other optional parameters are passed directly through to "add-
1730 drive-opts".
1731 This command has one or more optional arguments. See "OPTIONAL
1733 ARGUMENTS".
1734 add-drive
1736 add
1737 add-drive-opts
1738 add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]
1739 This function adds a disk image called filename to the handle.
1741 filename may be a regular host file or a host device.
1742 When this function is called before "launch" (the usual case) then the
1744 first time you call this function, the disk appears in the API as
1745 /dev/sda, the second time as /dev/sdb, and so on.
1746 You don't necessarily need to be root when using libguestfs. However
1748 you obviously do need sufficient permissions to access the filename for
1749 whatever operations you want to perform (ie. read access if you just
1750 want to read the image or write access if you want to modify the
1751 image).
1752 This call checks that filename exists.
1754 filename may be the special string "/dev/null". See "NULL DISKS" in
1756 guestfs(3).
1757 The optional arguments are:
1759 "readonly"
1761 If true then the image is treated as read-only. Writes are still
1762 allowed, but they are stored in a temporary snapshot overlay which
1763 is discarded at the end. The disk that you add is not modified.
1764 "format"
1766 This forces the image format. If you omit this (or use "add-drive"
1767 or "add-drive-ro") then the format is automatically detected.
1768 Possible formats include "raw" and "qcow2".
1769 Automatic detection of the format opens you up to a potential
1771 security hole when dealing with untrusted raw-format images. See
1772 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1773 security hole.
1774 "iface"
1776 This rarely-used option lets you emulate the behaviour of the
1777 deprecated "add-drive-with-if" call (q.v.)
1778 "name"
1780 This field used to be passed as a hint for guest inspection, but it
1781 is no longer used.
1782 "label"
1784 Give the disk a label. The label should be a unique, short string
1785 using only ASCII characters "[a-zA-Z]". As well as its usual name
1786 in the API (such as /dev/sda), the drive will also be named
1787 /dev/disk/guestfs/label.
1788 See "DISK LABELS" in guestfs(3).
1790 "protocol"
1792 The optional protocol argument can be used to select an alternate
1793 source protocol.
1794 See also: "REMOTE STORAGE" in guestfs(3).
1796 "protocol = "file""
1798 filename is interpreted as a local file or device. This is the
1799 default if the optional protocol parameter is omitted.
1800 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
1802 Connect to a remote FTP, HTTP or TFTP server. The "server"
1803 parameter must also be supplied - see below.
1804 See also: "FTP, HTTP AND TFTP" in guestfs(3)
1806 "protocol = "gluster""
1808 Connect to the GlusterFS server. The "server" parameter must
1809 also be supplied - see below.
1810 See also: "GLUSTER" in guestfs(3)
1812 "protocol = "iscsi""
1814 Connect to the iSCSI server. The "server" parameter must also
1815 be supplied - see below. The "username" parameter may be
1816 supplied. See below. The "secret" parameter may be supplied.
1817 See below.
1818 See also: "ISCSI" in guestfs(3).
1820 "protocol = "nbd""
1822 Connect to the Network Block Device server. The "server"
1823 parameter must also be supplied - see below.
1824 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
1826 "protocol = "rbd""
1828 Connect to the Ceph (librbd/RBD) server. The "server"
1829 parameter must also be supplied - see below. The "username"
1830 parameter may be supplied. See below. The "secret" parameter
1831 may be supplied. See below.
1832 See also: "CEPH" in guestfs(3).
1834 "protocol = "sheepdog""
1836 Connect to the Sheepdog server. The "server" parameter may
1837 also be supplied - see below.
1838 See also: "SHEEPDOG" in guestfs(3).
1840 "protocol = "ssh""
1842 Connect to the Secure Shell (ssh) server.
1843 The "server" parameter must be supplied. The "username"
1845 parameter may be supplied. See below.
1846 See also: "SSH" in guestfs(3).
1848 "server"
1850 For protocols which require access to a remote server, this is a
1851 list of server(s).
1852 Protocol Number of servers required
1854 -------- --------------------------
1855 file List must be empty or param not used at all
1856 ftp|ftps|http|https|tftp Exactly one
1857 gluster Exactly one
1858 iscsi Exactly one
1859 nbd Exactly one
1860 rbd Zero or more
1861 sheepdog Zero or more
1862 ssh Exactly one
1863 Each list element is a string specifying a server. The string must
1865 be in one of the following formats:
1866 hostname
1868 hostname:port
1869 tcp:hostname
1870 tcp:hostname:port
1871 unix:/path/to/socket
1872 If the port number is omitted, then the standard port number for
1874 the protocol is used (see /etc/services).
1875 "username"
1877 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
1878 "tftp" protocols, this specifies the remote username.
1879 If not given, then the local username is used for "ssh", and no
1881 authentication is attempted for ceph. But note this sometimes may
1882 give unexpected results, for example if using the libvirt backend
1883 and if the libvirt backend is configured to start the qemu
1884 appliance as a special user such as "qemu.qemu". If in doubt,
1885 specify the remote username you want.
1886 "secret"
1888 For the "rbd" protocol only, this specifies the ‘secret’ to use
1889 when connecting to the remote device. It must be base64 encoded.
1890 If not given, then a secret matching the given username will be
1892 looked up in the default keychain locations, or if no username is
1893 given, then no authentication will be used.
1894 "cachemode"
1896 Choose whether or not libguestfs will obey sync operations (safe
1897 but slow) or not (unsafe but fast). The possible values for this
1898 string are:
1899 "cachemode = "writeback""
1901 This is the default.
1902 Write operations in the API do not return until a write(2) call
1904 has completed in the host [but note this does not imply that
1905 anything gets written to disk].
1906 Sync operations in the API, including implicit syncs caused by
1908 filesystem journalling, will not return until an fdatasync(2)
1909 call has completed in the host, indicating that data has been
1910 committed to disk.
1911 "cachemode = "unsafe""
1913 In this mode, there are no guarantees. Libguestfs may cache
1914 anything and ignore sync requests. This is suitable only for
1915 scratch or temporary disks.
1916 "discard"
1918 Enable or disable discard (a.k.a. trim or unmap) support on this
1919 drive. If enabled, operations such as "fstrim" will be able to
1920 discard / make thin / punch holes in the underlying host file or
1921 device.
1922 Possible discard settings are:
1924 "discard = "disable""
1926 Disable discard support. This is the default.
1927 "discard = "enable""
1929 Enable discard support. Fail if discard is not possible.
1930 "discard = "besteffort""
1932 Enable discard support if possible, but don't fail if it is not
1933 supported.
1934 Since not all backends and not all underlying systems support
1936 discard, this is a good choice if you want to use discard if
1937 possible, but don't mind if it doesn't work.
1938 "copyonread"
1940 The boolean parameter "copyonread" enables copy-on-read support.
1941 This only affects disk formats which have backing files, and causes
1942 reads to be stored in the overlay layer, speeding up multiple reads
1943 of the same area of disk.
1944 The default is false.
1946 "blocksize"
1948 This parameter sets the sector size of the disk. Possible values
1949 are 512 (the default if the parameter is omitted) or 4096. Use
1950 4096 when handling an "Advanced Format" disk that uses 4K sector
1951 size (https://en.wikipedia.org/wiki/Advanced_Format).
1952 Only a subset of the backends support this parameter (currently
1954 only the libvirt and direct backends do).
1955 This command has one or more optional arguments. See "OPTIONAL
1957 ARGUMENTS".
1958 add-drive-ro
1960 add-ro
1961 add-drive-ro filename
1962 This function is the equivalent of calling "add-drive-opts" with the
1964 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1965 disk is added read-only, with the format being detected automatically.
1966 add-drive-ro-with-if
1968 add-drive-ro-with-if filename iface
1969 This is the same as "add-drive-ro" but it allows you to specify the
1971 QEMU interface emulation to use at run time.
1972 This function is deprecated. In new code, use the "add-drive" call
1974 instead.
1975 Deprecated functions will not be removed from the API, but the fact
1977 that they are deprecated indicates that there are problems with correct
1978 use of these functions.
1979 add-drive-scratch
1981 scratch
1982 add-drive-scratch size [name:..] [label:..] [blocksize:N]
1983 This command adds a temporary scratch drive to the handle. The "size"
1985 parameter is the virtual size (in bytes). The scratch drive is blank
1986 initially (all reads return zeroes until you start writing to it). The
1987 drive is deleted when the handle is closed.
1988 The optional arguments "name", "label" and "blocksize" are passed
1990 through to "add-drive-opts".
1991 This command has one or more optional arguments. See "OPTIONAL
1993 ARGUMENTS".
1994 add-drive-with-if
1996 add-drive-with-if filename iface
1997 This is the same as "add-drive" but it allows you to specify the QEMU
1999 interface emulation to use at run time.
2000 This function is deprecated. In new code, use the "add-drive" call
2002 instead.
2003 Deprecated functions will not be removed from the API, but the fact
2005 that they are deprecated indicates that there are problems with correct
2006 use of these functions.
2007 aug-clear
2009 aug-clear augpath
2010 Set the value associated with "path" to "NULL". This is the same as
2012 the augtool(1) "clear" command.
2013 aug-close
2015 aug-close
2016 Close the current Augeas handle and free up any resources used by it.
2018 After calling this, you have to call "aug-init" again before you can
2019 use any other Augeas functions.
2020 aug-defnode
2022 aug-defnode name expr val
2023 Defines a variable "name" whose value is the result of evaluating
2025 "expr".
2026 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2028 to calling "aug-set" "expr", "val". "name" will be the nodeset
2029 containing that single node.
2030 On success this returns a pair containing the number of nodes in the
2032 nodeset, and a boolean flag if a node was created.
2033 aug-defvar
2035 aug-defvar name expr
2036 Defines an Augeas variable "name" whose value is the result of
2038 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2039 On success this returns the number of nodes in "expr", or 0 if "expr"
2041 evaluates to something which is not a nodeset.
2042 aug-get
2044 aug-get augpath
2045 Look up the value associated with "path". If "path" matches exactly
2047 one node, the "value" is returned.
2048 aug-init
2050 aug-init root flags
2051 Create a new Augeas handle for editing configuration files. If there
2053 was any previous Augeas handle associated with this guestfs session,
2054 then it is closed.
2055 You must call this before using any other "aug-*" commands.
2057 "root" is the filesystem root. "root" must not be NULL, use / instead.
2059 The flags are the same as the flags defined in <augeas.h>, the logical
2061 or of the following integers:
2062 "AUG_SAVE_BACKUP" = 1
2064 Keep the original file with a ".augsave" extension.
2065 "AUG_SAVE_NEWFILE" = 2
2067 Save changes into a file with extension ".augnew", and do not
2068 overwrite original. Overrides "AUG_SAVE_BACKUP".
2069 "AUG_TYPE_CHECK" = 4
2071 Typecheck lenses.
2072 This option is only useful when debugging Augeas lenses. Use of
2074 this option may require additional memory for the libguestfs
2075 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2076 environment variable or call "set-memsize".
2077 "AUG_NO_STDINC" = 8
2079 Do not use standard load path for modules.
2080 "AUG_SAVE_NOOP" = 16
2082 Make save a no-op, just record what would have been changed.
2083 "AUG_NO_LOAD" = 32
2085 Do not load the tree in "aug-init".
2086 To close the handle, you can call "aug-close".
2088 To find out more about Augeas, see http://augeas.net/.
2090 aug-insert
2092 aug-insert augpath label true|false
2093 Create a new sibling "label" for "path", inserting it into the tree
2095 before or after "path" (depending on the boolean flag "before").
2096 "path" must match exactly one existing node in the tree, and "label"
2098 must be a label, ie. not contain /, "*" or end with a bracketed index
2099 "[N]".
2100 aug-label
2102 aug-label augpath
2103 The label (name of the last element) of the Augeas path expression
2105 "augpath" is returned. "augpath" must match exactly one node, else
2106 this function returns an error.
2107 aug-load
2109 aug-load
2110 Load files into the tree.
2112 See "aug_load" in the Augeas documentation for the full gory details.
2114 aug-ls
2116 aug-ls augpath
2117 This is just a shortcut for listing "aug-match" "path/*" and sorting
2119 the resulting nodes into alphabetical order.
2120 aug-match
2122 aug-match augpath
2123 Returns a list of paths which match the path expression "path". The
2125 returned paths are sufficiently qualified so that they match exactly
2126 one node in the current tree.
2127 aug-mv
2129 aug-mv src dest
2130 Move the node "src" to "dest". "src" must match exactly one node.
2132 "dest" is overwritten if it exists.
2133 aug-rm
2135 aug-rm augpath
2136 Remove "path" and all of its children.
2138 On success this returns the number of entries which were removed.
2140 aug-save
2142 aug-save
2143 This writes all pending changes to disk.
2145 The flags which were passed to "aug-init" affect exactly how files are
2147 saved.
2148 aug-set
2150 aug-set augpath val
2151 Set the value associated with "augpath" to "val".
2153 In the Augeas API, it is possible to clear a node by setting the value
2155 to NULL. Due to an oversight in the libguestfs API you cannot do that
2156 with this call. Instead you must use the "aug-clear" call.
2157 aug-setm
2159 aug-setm base sub val
2160 Change multiple Augeas nodes in a single operation. "base" is an
2162 expression matching multiple nodes. "sub" is a path expression
2163 relative to "base". All nodes matching "base" are found, and then for
2164 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2165 which case the "base" nodes are modified.
2166 This returns the number of nodes modified.
2168 aug-transform
2170 aug-transform lens file [remove:true|false]
2171 Add an Augeas transformation for the specified "lens" so it can handle
2173 "file".
2174 If "remove" is true ("false" by default), then the transformation is
2176 removed.
2177 This command has one or more optional arguments. See "OPTIONAL
2179 ARGUMENTS".
2180 available
2182 available 'groups ...'
2183 This command is used to check the availability of some groups of
2185 functionality in the appliance, which not all builds of the libguestfs
2186 appliance will be able to provide.
2187 The libguestfs groups, and the functions that those groups correspond
2189 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
2190 this list at runtime by calling "available-all-groups".
2191 The argument "groups" is a list of group names, eg: "["inotify",
2193 "augeas"]" would check for the availability of the Linux inotify
2194 functions and Augeas (configuration file editing) functions.
2195 The command returns no error if all requested groups are available.
2197 It fails with an error if one or more of the requested groups is
2199 unavailable in the appliance.
2200 If an unknown group name is included in the list of groups then an
2202 error is always returned.
2203 Notes:
2205 • "feature-available" is the same as this call, but with a slightly
2207 simpler to use API: that call returns a boolean true/false instead
2208 of throwing an error.
2209 • You must call "launch" before calling this function.
2211 The reason is because we don't know what groups are supported by
2213 the appliance/daemon until it is running and can be queried.
2214 • If a group of functions is available, this does not necessarily
2216 mean that they will work. You still have to check for errors when
2217 calling individual API functions even if they are available.
2218 • It is usually the job of distro packagers to build complete
2220 functionality into the libguestfs appliance. Upstream libguestfs,
2221 if built from source with all requirements satisfied, will support
2222 everything.
2223 • This call was added in version 1.0.80. In previous versions of
2225 libguestfs all you could do would be to speculatively execute a
2226 command to find out if the daemon implemented it. See also
2227 "version".
2228 See also "filesystem-available".
2230 available-all-groups
2232 available-all-groups
2233 This command returns a list of all optional groups that this daemon
2235 knows about. Note this returns both supported and unsupported groups.
2236 To find out which ones the daemon can actually support you have to call
2237 "available" / "feature-available" on each member of the returned list.
2238 See also "available", "feature-available" and "AVAILABILITY" in
2240 guestfs(3).
2241 base64-in
2243 base64-in (base64file|-) filename
2244 This command uploads base64-encoded data from "base64file" to filename.
2246 Use "-" instead of a filename to read/write from stdin/stdout.
2248 base64-out
2250 base64-out filename (base64file|-)
2251 This command downloads the contents of filename, writing it out to
2253 local file "base64file" encoded as base64.
2254 Use "-" instead of a filename to read/write from stdin/stdout.
2256 blkdiscard
2258 blkdiscard device
2259 This discards all blocks on the block device "device", giving the free
2261 space back to the host.
2262 This operation requires support in libguestfs, the host filesystem,
2264 qemu and the host kernel. If this support isn't present it may give an
2265 error or even appear to run but do nothing. You must also set the
2266 "discard" attribute on the underlying drive (see "add-drive-opts").
2267 This command depends on the feature "blkdiscard". See also "feature-
2269 available".
2270 blkdiscardzeroes
2272 blkdiscardzeroes device
2273 This call returns true if blocks on "device" that have been discarded
2275 by a call to "blkdiscard" are returned as blocks of zero bytes when
2276 read the next time.
2277 If it returns false, then it may be that discarded blocks are read as
2279 stale or random data.
2280 This command depends on the feature "blkdiscardzeroes". See also
2282 "feature-available".
2283 blkid
2285 blkid device
2286 This command returns block device attributes for "device". The
2288 following fields are usually present in the returned hash. Other fields
2289 may also be present.
2290 "UUID"
2292 The uuid of this device.
2293 "LABEL"
2295 The label of this device.
2296 "VERSION"
2298 The version of blkid command.
2299 "TYPE"
2301 The filesystem type or RAID of this device.
2302 "USAGE"
2304 The usage of this device, for example "filesystem" or "raid".
2305 blockdev-flushbufs
2307 blockdev-flushbufs device
2308 This tells the kernel to flush internal buffers associated with
2310 "device".
2311 This uses the blockdev(8) command.
2313 blockdev-getbsz
2315 blockdev-getbsz device
2316 This returns the block size of a device.
2318 Note: this is different from both size in blocks and filesystem block
2320 size. Also this setting is not really used by anything. You should
2321 probably not use it for anything. Filesystems have their own idea
2322 about what block size to choose.
2323 This uses the blockdev(8) command.
2325 blockdev-getro
2327 blockdev-getro device
2328 Returns a boolean indicating if the block device is read-only (true if
2330 read-only, false if not).
2331 This uses the blockdev(8) command.
2333 blockdev-getsize64
2335 blockdev-getsize64 device
2336 This returns the size of the device in bytes.
2338 See also "blockdev-getsz".
2340 This uses the blockdev(8) command.
2342 blockdev-getss
2344 blockdev-getss device
2345 This returns the size of sectors on a block device. Usually 512, but
2347 can be larger for modern devices.
2348 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
2350 This uses the blockdev(8) command.
2352 blockdev-getsz
2354 blockdev-getsz device
2355 This returns the size of the device in units of 512-byte sectors (even
2357 if the sectorsize isn't 512 bytes ... weird).
2358 See also "blockdev-getss" for the real sector size of the device, and
2360 "blockdev-getsize64" for the more useful size in bytes.
2361 This uses the blockdev(8) command.
2363 blockdev-rereadpt
2365 blockdev-rereadpt device
2366 Reread the partition table on "device".
2368 This uses the blockdev(8) command.
2370 blockdev-setbsz
2372 blockdev-setbsz device blocksize
2373 This call does nothing and has never done anything because of a bug in
2375 blockdev. Do not use it.
2376 If you need to set the filesystem block size, use the "blocksize"
2378 option of "mkfs".
2379 This function is deprecated. There is no replacement. Consult the API
2381 documentation in guestfs(3) for further information.
2382 Deprecated functions will not be removed from the API, but the fact
2384 that they are deprecated indicates that there are problems with correct
2385 use of these functions.
2386 blockdev-setra
2388 blockdev-setra device sectors
2389 Set readahead (in 512-byte sectors) for the device.
2391 This uses the blockdev(8) command.
2393 blockdev-setro
2395 blockdev-setro device
2396 Sets the block device named "device" to read-only.
2398 This uses the blockdev(8) command.
2400 blockdev-setrw
2402 blockdev-setrw device
2403 Sets the block device named "device" to read-write.
2405 This uses the blockdev(8) command.
2407 btrfs-balance-cancel
2409 btrfs-balance-cancel path
2410 Cancel a running balance on a btrfs filesystem.
2412 This command depends on the feature "btrfs". See also "feature-
2414 available".
2415 btrfs-balance-pause
2417 btrfs-balance-pause path
2418 Pause a running balance on a btrfs filesystem.
2420 This command depends on the feature "btrfs". See also "feature-
2422 available".
2423 btrfs-balance-resume
2425 btrfs-balance-resume path
2426 Resume a paused balance on a btrfs filesystem.
2428 This command depends on the feature "btrfs". See also "feature-
2430 available".
2431 btrfs-balance-status
2433 btrfs-balance-status path
2434 Show the status of a running or paused balance on a btrfs filesystem.
2436 This command depends on the feature "btrfs". See also "feature-
2438 available".
2439 btrfs-device-add
2441 btrfs-device-add 'devices ...' fs
2442 Add the list of device(s) in "devices" to the btrfs filesystem mounted
2444 at "fs". If "devices" is an empty list, this does nothing.
2445 This command depends on the feature "btrfs". See also "feature-
2447 available".
2448 btrfs-device-delete
2450 btrfs-device-delete 'devices ...' fs
2451 Remove the "devices" from the btrfs filesystem mounted at "fs". If
2453 "devices" is an empty list, this does nothing.
2454 This command depends on the feature "btrfs". See also "feature-
2456 available".
2457 btrfs-filesystem-balance
2459 btrfs-balance
2460 btrfs-filesystem-balance fs
2461 Balance the chunks in the btrfs filesystem mounted at "fs" across the
2463 underlying devices.
2464 This command depends on the feature "btrfs". See also "feature-
2466 available".
2467 btrfs-filesystem-defragment
2469 btrfs-filesystem-defragment path [flush:true|false] [compress:..]
2470 Defragment a file or directory on a btrfs filesystem. compress is one
2472 of zlib or lzo.
2473 This command has one or more optional arguments. See "OPTIONAL
2475 ARGUMENTS".
2476 This command depends on the feature "btrfs". See also "feature-
2478 available".
2479 btrfs-filesystem-resize
2481 btrfs-filesystem-resize mountpoint [size:N]
2482 This command resizes a btrfs filesystem.
2484 Note that unlike other resize calls, the filesystem has to be mounted
2486 and the parameter is the mountpoint not the device (this is a
2487 requirement of btrfs itself).
2488 The optional parameters are:
2490 "size"
2492 The new size (in bytes) of the filesystem. If omitted, the
2493 filesystem is resized to the maximum size.
2494 See also btrfs(8).
2496 This command has one or more optional arguments. See "OPTIONAL
2498 ARGUMENTS".
2499 This command depends on the feature "btrfs". See also "feature-
2501 available".
2502 btrfs-filesystem-show
2504 btrfs-filesystem-show device
2505 Show all the devices where the filesystems in "device" is spanned over.
2507 If not all the devices for the filesystems are present, then this
2509 function fails and the "errno" is set to "ENODEV".
2510 This command depends on the feature "btrfs". See also "feature-
2512 available".
2513 btrfs-filesystem-sync
2515 btrfs-filesystem-sync fs
2516 Force sync on the btrfs filesystem mounted at "fs".
2518 This command depends on the feature "btrfs". See also "feature-
2520 available".
2521 btrfs-fsck
2523 btrfs-fsck device [superblock:N] [repair:true|false]
2524 Used to check a btrfs filesystem, "device" is the device file where the
2526 filesystem is stored.
2527 This command has one or more optional arguments. See "OPTIONAL
2529 ARGUMENTS".
2530 This command depends on the feature "btrfs". See also "feature-
2532 available".
2533 btrfs-image
2535 btrfs-image 'source ...' image [compresslevel:N]
2536 This is used to create an image of a btrfs filesystem. All data will
2538 be zeroed, but metadata and the like is preserved.
2539 This command has one or more optional arguments. See "OPTIONAL
2541 ARGUMENTS".
2542 This command depends on the feature "btrfs". See also "feature-
2544 available".
2545 btrfs-qgroup-assign
2547 btrfs-qgroup-assign src dst path
2548 Add qgroup "src" to parent qgroup "dst". This command can group several
2550 qgroups into a parent qgroup to share common limit.
2551 This command depends on the feature "btrfs". See also "feature-
2553 available".
2554 btrfs-qgroup-create
2556 btrfs-qgroup-create qgroupid subvolume
2557 Create a quota group (qgroup) for subvolume at "subvolume".
2559 This command depends on the feature "btrfs". See also "feature-
2561 available".
2562 btrfs-qgroup-destroy
2564 btrfs-qgroup-destroy qgroupid subvolume
2565 Destroy a quota group.
2567 This command depends on the feature "btrfs". See also "feature-
2569 available".
2570 btrfs-qgroup-limit
2572 btrfs-qgroup-limit subvolume size
2573 Limit the size of the subvolume with path "subvolume".
2575 This command depends on the feature "btrfs". See also "feature-
2577 available".
2578 btrfs-qgroup-remove
2580 btrfs-qgroup-remove src dst path
2581 Remove qgroup "src" from the parent qgroup "dst".
2583 This command depends on the feature "btrfs". See also "feature-
2585 available".
2586 btrfs-qgroup-show
2588 btrfs-qgroup-show path
2589 Show all subvolume quota groups in a btrfs filesystem, including their
2591 usages.
2592 This command depends on the feature "btrfs". See also "feature-
2594 available".
2595 btrfs-quota-enable
2597 btrfs-quota-enable fs true|false
2598 Enable or disable subvolume quota support for filesystem which contains
2600 "path".
2601 This command depends on the feature "btrfs". See also "feature-
2603 available".
2604 btrfs-quota-rescan
2606 btrfs-quota-rescan fs
2607 Trash all qgroup numbers and scan the metadata again with the current
2609 config.
2610 This command depends on the feature "btrfs". See also "feature-
2612 available".
2613 btrfs-replace
2615 btrfs-replace srcdev targetdev mntpoint
2616 Replace device of a btrfs filesystem. On a live filesystem, duplicate
2618 the data to the target device which is currently stored on the source
2619 device. After completion of the operation, the source device is wiped
2620 out and removed from the filesystem.
2621 The "targetdev" needs to be same size or larger than the "srcdev".
2623 Devices which are currently mounted are never allowed to be used as the
2624 "targetdev".
2625 This command depends on the feature "btrfs". See also "feature-
2627 available".
2628 btrfs-rescue-chunk-recover
2630 btrfs-rescue-chunk-recover device
2631 Recover the chunk tree of btrfs filesystem by scanning the devices one
2633 by one.
2634 This command depends on the feature "btrfs". See also "feature-
2636 available".
2637 btrfs-rescue-super-recover
2639 btrfs-rescue-super-recover device
2640 Recover bad superblocks from good copies.
2642 This command depends on the feature "btrfs". See also "feature-
2644 available".
2645 btrfs-scrub-cancel
2647 btrfs-scrub-cancel path
2648 Cancel a running scrub on a btrfs filesystem.
2650 This command depends on the feature "btrfs". See also "feature-
2652 available".
2653 btrfs-scrub-resume
2655 btrfs-scrub-resume path
2656 Resume a previously canceled or interrupted scrub on a btrfs
2658 filesystem.
2659 This command depends on the feature "btrfs". See also "feature-
2661 available".
2662 btrfs-scrub-start
2664 btrfs-scrub-start path
2665 Reads all the data and metadata on the filesystem, and uses checksums
2667 and the duplicate copies from RAID storage to identify and repair any
2668 corrupt data.
2669 This command depends on the feature "btrfs". See also "feature-
2671 available".
2672 btrfs-scrub-status
2674 btrfs-scrub-status path
2675 Show status of running or finished scrub on a btrfs filesystem.
2677 This command depends on the feature "btrfs". See also "feature-
2679 available".
2680 btrfs-set-seeding
2682 btrfs-set-seeding device true|false
2683 Enable or disable the seeding feature of a device that contains a btrfs
2685 filesystem.
2686 This command depends on the feature "btrfs". See also "feature-
2688 available".
2689 btrfs-subvolume-create
2691 btrfs-subvolume-create-opts
2692 btrfs-subvolume-create dest [qgroupid:..]
2693 Create a btrfs subvolume. The "dest" argument is the destination
2695 directory and the name of the subvolume, in the form
2696 /path/to/dest/name. The optional parameter "qgroupid" represents the
2697 qgroup which the newly created subvolume will be added to.
2698 This command has one or more optional arguments. See "OPTIONAL
2700 ARGUMENTS".
2701 This command depends on the feature "btrfs". See also "feature-
2703 available".
2704 btrfs-subvolume-delete
2706 btrfs-subvolume-delete subvolume
2707 Delete the named btrfs subvolume or snapshot.
2709 This command depends on the feature "btrfs". See also "feature-
2711 available".
2712 btrfs-subvolume-get-default
2714 btrfs-subvolume-get-default fs
2715 Get the default subvolume or snapshot of a filesystem mounted at
2717 "mountpoint".
2718 This command depends on the feature "btrfs". See also "feature-
2720 available".
2721 btrfs-subvolume-list
2723 btrfs-subvolume-list fs
2724 List the btrfs snapshots and subvolumes of the btrfs filesystem which
2726 is mounted at "fs".
2727 This command depends on the feature "btrfs". See also "feature-
2729 available".
2730 btrfs-subvolume-set-default
2732 btrfs-subvolume-set-default id fs
2733 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2735 default. See "btrfs-subvolume-list" to get a list of subvolumes.
2736 This command depends on the feature "btrfs". See also "feature-
2738 available".
2739 btrfs-subvolume-show
2741 btrfs-subvolume-show subvolume
2742 Return detailed information of the subvolume.
2744 This command depends on the feature "btrfs". See also "feature-
2746 available".
2747 btrfs-subvolume-snapshot
2749 btrfs-subvolume-snapshot-opts
2750 btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]
2751 Create a snapshot of the btrfs subvolume "source". The "dest" argument
2753 is the destination directory and the name of the snapshot, in the form
2754 /path/to/dest/name. By default the newly created snapshot is writable,
2755 if the value of optional parameter "ro" is true, then a readonly
2756 snapshot is created. The optional parameter "qgroupid" represents the
2757 qgroup which the newly created snapshot will be added to.
2758 This command has one or more optional arguments. See "OPTIONAL
2760 ARGUMENTS".
2761 This command depends on the feature "btrfs". See also "feature-
2763 available".
2764 btrfstune-enable-extended-inode-refs
2766 btrfstune-enable-extended-inode-refs device
2767 This will Enable extended inode refs.
2769 This command depends on the feature "btrfs". See also "feature-
2771 available".
2772 btrfstune-enable-skinny-metadata-extent-refs
2774 btrfstune-enable-skinny-metadata-extent-refs device
2775 This enable skinny metadata extent refs.
2777 This command depends on the feature "btrfs". See also "feature-
2779 available".
2780 btrfstune-seeding
2782 btrfstune-seeding device true|false
2783 Enable seeding of a btrfs device, this will force a fs readonly so that
2785 you can use it to build other filesystems.
2786 This command depends on the feature "btrfs". See also "feature-
2788 available".
2789 c-pointer
2791 c-pointer
2792 In non-C language bindings, this allows you to retrieve the underlying
2794 C pointer to the handle (ie. "h *"). The purpose of this is to allow
2795 other libraries to interwork with libguestfs.
2796 canonical-device-name
2798 canonical-device-name device
2799 This utility function is useful when displaying device names to the
2801 user. It takes a number of irregular device names and returns them in
2802 a consistent format:
2803 /dev/hdX
2805 /dev/vdX
2806 These are returned as /dev/sdX. Note this works for device names
2807 and partition names. This is approximately the reverse of the
2808 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2809 /dev/mapper/VG-LV
2811 /dev/dm-N
2812 Converted to /dev/VG/LV form using "lvm-canonical-lv-name".
2813 Other strings are returned unmodified.
2815 cap-get-file
2817 cap-get-file path
2818 This function returns the Linux capabilities attached to "path". The
2820 capabilities set is returned in text form (see cap_to_text(3)).
2821 If no capabilities are attached to a file, an empty string is returned.
2823 This command depends on the feature "linuxcaps". See also "feature-
2825 available".
2826 cap-set-file
2828 cap-set-file path cap
2829 This function sets the Linux capabilities attached to "path". The
2831 capabilities set "cap" should be passed in text form (see
2832 cap_from_text(3)).
2833 This command depends on the feature "linuxcaps". See also "feature-
2835 available".
2836 case-sensitive-path
2838 case-sensitive-path path
2839 This can be used to resolve case insensitive paths on a filesystem
2841 which is case sensitive. The use case is to resolve paths which you
2842 have read from Windows configuration files or the Windows Registry, to
2843 the true path.
2844 The command handles a peculiarity of the Linux ntfs-3g filesystem
2846 driver (and probably others), which is that although the underlying
2847 filesystem is case-insensitive, the driver exports the filesystem to
2848 Linux as case-sensitive.
2849 One consequence of this is that special directories such as C:\windows
2851 may appear as /WINDOWS or /windows (or other things) depending on the
2852 precise details of how they were created. In Windows itself this would
2853 not be a problem.
2854 Bug or feature? You decide:
2856 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2857 "case-sensitive-path" attempts to resolve the true case of each element
2859 in the path. It will return a resolved path if either the full path or
2860 its parent directory exists. If the parent directory exists but the
2861 full path does not, the case of the parent directory will be correctly
2862 resolved, and the remainder appended unmodified. For example, if the
2863 file "/Windows/System32/netkvm.sys" exists:
2864 "case-sensitive-path" ("/windows/system32/netkvm.sys")
2866 "Windows/System32/netkvm.sys"
2867 "case-sensitive-path" ("/windows/system32/NoSuchFile")
2869 "Windows/System32/NoSuchFile"
2870 "case-sensitive-path" ("/windows/system33/netkvm.sys")
2872 ERROR
2873 Note: Because of the above behaviour, "case-sensitive-path" cannot be
2875 used to check for the existence of a file.
2876 Note: This function does not handle drive names, backslashes etc.
2878 See also "realpath".
2880 cat
2882 cat path
2883 Return the contents of the file named "path".
2885 Because, in C, this function returns a "char *", there is no way to
2887 differentiate between a "\0" character in a file and end of string. To
2888 handle binary files, use the "read-file" or "download" functions.
2889 checksum
2891 checksum csumtype path
2892 This call computes the MD5, SHAx or CRC checksum of the file named
2894 "path".
2895 The type of checksum to compute is given by the "csumtype" parameter
2897 which must have one of the following values:
2898 "crc"
2900 Compute the cyclic redundancy check (CRC) specified by POSIX for
2901 the "cksum" command.
2902 "md5"
2904 Compute the MD5 hash (using the md5sum(1) program).
2905 "sha1"
2907 Compute the SHA1 hash (using the sha1sum(1) program).
2908 "sha224"
2910 Compute the SHA224 hash (using the sha224sum(1) program).
2911 "sha256"
2913 Compute the SHA256 hash (using the sha256sum(1) program).
2914 "sha384"
2916 Compute the SHA384 hash (using the sha384sum(1) program).
2917 "sha512"
2919 Compute the SHA512 hash (using the sha512sum(1) program).
2920 The checksum is returned as a printable string.
2922 To get the checksum for a device, use "checksum-device".
2924 To get the checksums for many files, use "checksums-out".
2926 checksum-device
2928 checksum-device csumtype device
2929 This call computes the MD5, SHAx or CRC checksum of the contents of the
2931 device named "device". For the types of checksums supported see the
2932 "checksum" command.
2933 checksums-out
2935 checksums-out csumtype directory (sumsfile|-)
2936 This command computes the checksums of all regular files in directory
2938 and then emits a list of those checksums to the local output file
2939 "sumsfile".
2940 This can be used for verifying the integrity of a virtual machine.
2942 However to be properly secure you should pay attention to the output of
2943 the checksum command (it uses the ones from GNU coreutils). In
2944 particular when the filename is not printable, coreutils uses a special
2945 backslash syntax. For more information, see the GNU coreutils info
2946 file.
2947 Use "-" instead of a filename to read/write from stdin/stdout.
2949 chmod
2951 chmod mode path
2952 Change the mode (permissions) of "path" to "mode". Only numeric modes
2954 are supported.
2955 Note: When using this command from guestfish, "mode" by default would
2957 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2958 700.
2959 The mode actually set is affected by the umask.
2961 chown
2963 chown owner group path
2964 Change the file owner to "owner" and group to "group".
2966 Only numeric uid and gid are supported. If you want to use names, you
2968 will need to locate and parse the password file yourself (Augeas
2969 support makes this relatively easy).
2970 clear-backend-setting
2972 clear-backend-setting name
2973 If there is a backend setting string matching "name" or beginning with
2975 "name=", then that string is removed from the backend settings.
2976 This call returns the number of strings which were removed (which may
2978 be 0, 1 or greater than 1).
2979 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2981 command
2983 command 'arguments ...'
2984 This call runs a command from the guest filesystem. The filesystem
2986 must be mounted, and must contain a compatible operating system (ie.
2987 something Linux, with the same or compatible processor architecture).
2988 The single parameter is an argv-style list of arguments. The first
2990 element is the name of the program to run. Subsequent elements are
2991 parameters. The list must be non-empty (ie. must contain a program
2992 name). Note that the command runs directly, and is not invoked via the
2993 shell (see "sh").
2994 The return value is anything printed to stdout by the command.
2996 If the command returns a non-zero exit status, then this function
2998 returns an error message. The error message string is the content of
2999 stderr from the command.
3000 The $PATH environment variable will contain at least /usr/bin and /bin.
3002 If you require a program from another location, you should provide the
3003 full path in the first parameter.
3004 Shared libraries and data files required by the program must be
3006 available on filesystems which are mounted in the correct places. It
3007 is the caller’s responsibility to ensure all filesystems that are
3008 needed are mounted at the right locations.
3009 Because of the message protocol, there is a transfer limit of somewhere
3011 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3012 command-lines
3014 command-lines 'arguments ...'
3015 This is the same as "command", but splits the result into a list of
3017 lines.
3018 See also: "sh-lines"
3020 Because of the message protocol, there is a transfer limit of somewhere
3022 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3023 compress-device-out
3025 compress-device-out ctype device (zdevice|-) [level:N]
3026 This command compresses "device" and writes it out to the local file
3028 "zdevice".
3029 The "ctype" and optional "level" parameters have the same meaning as in
3031 "compress-out".
3032 Use "-" instead of a filename to read/write from stdin/stdout.
3034 This command has one or more optional arguments. See "OPTIONAL
3036 ARGUMENTS".
3037 compress-out
3039 compress-out ctype file (zfile|-) [level:N]
3040 This command compresses file and writes it out to the local file zfile.
3042 The compression program used is controlled by the "ctype" parameter.
3044 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3045 Some compression types may not be supported by particular builds of
3046 libguestfs, in which case you will get an error containing the
3047 substring "not supported".
3048 The optional "level" parameter controls compression level. The meaning
3050 and default for this parameter depends on the compression program being
3051 used.
3052 Use "-" instead of a filename to read/write from stdin/stdout.
3054 This command has one or more optional arguments. See "OPTIONAL
3056 ARGUMENTS".
3057 config
3059 config hvparam hvvalue
3060 This can be used to add arbitrary hypervisor parameters of the form
3062 -param value. Actually it’s not quite arbitrary - we prevent you from
3063 setting some parameters which would interfere with parameters that we
3064 use.
3065 The first character of "hvparam" string must be a "-" (dash).
3067 "hvvalue" can be NULL.
3069 copy-attributes
3071 copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]
3072 Copy the attributes of a path (which can be a file or a directory) to
3074 another path.
3075 By default no attribute is copied, so make sure to specify any (or
3077 "all" to copy everything).
3078 The optional arguments specify which attributes can be copied:
3080 "mode"
3082 Copy part of the file mode from "source" to "destination". Only the
3083 UNIX permissions and the sticky/setuid/setgid bits can be copied.
3084 "xattributes"
3086 Copy the Linux extended attributes (xattrs) from "source" to
3087 "destination". This flag does nothing if the linuxxattrs feature
3088 is not available (see "feature-available").
3089 "ownership"
3091 Copy the owner uid and the group gid of "source" to "destination".
3092 "all"
3094 Copy all the attributes from "source" to "destination". Enabling it
3095 enables all the other flags, if they are not specified already.
3096 This command has one or more optional arguments. See "OPTIONAL
3098 ARGUMENTS".
3099 copy-device-to-device
3101 copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3102 The four calls "copy-device-to-device", "copy-device-to-file", "copy-
3104 file-to-device", and "copy-file-to-file" let you copy from a source
3105 (device|file) to a destination (device|file).
3106 Partial copies can be made since you can specify optionally the source
3108 offset, destination offset and size to copy. These values are all
3109 specified in bytes. If not given, the offsets both default to zero,
3110 and the size defaults to copying as much as possible until we hit the
3111 end of the source.
3112 The source and destination may be the same object. However overlapping
3114 regions may not be copied correctly.
3115 If the destination is a file, it is created if required. If the
3117 destination file is not large enough, it is extended.
3118 If the destination is a file and the "append" flag is not set, then the
3120 destination file is truncated. If the "append" flag is set, then the
3121 copy appends to the destination file. The "append" flag currently
3122 cannot be set for devices.
3123 If the "sparse" flag is true then the call avoids writing blocks that
3125 contain only zeroes, which can help in some situations where the
3126 backing disk is thin-provisioned. Note that unless the target is
3127 already zeroed, using this option will result in incorrect copying.
3128 This command has one or more optional arguments. See "OPTIONAL
3130 ARGUMENTS".
3131 copy-device-to-file
3133 copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3134 See "copy-device-to-device" for a general overview of this call.
3136 This command has one or more optional arguments. See "OPTIONAL
3138 ARGUMENTS".
3139 copy-file-to-device
3141 copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3142 See "copy-device-to-device" for a general overview of this call.
3144 This command has one or more optional arguments. See "OPTIONAL
3146 ARGUMENTS".
3147 copy-file-to-file
3149 copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3150 See "copy-device-to-device" for a general overview of this call.
3152 This is not the function you want for copying files. This is for
3154 copying blocks within existing files. See "cp", "cp-a" and "mv" for
3155 general file copying and moving functions.
3156 This command has one or more optional arguments. See "OPTIONAL
3158 ARGUMENTS".
3159 copy-size
3161 copy-size src dest size
3162 This command copies exactly "size" bytes from one source device or file
3164 "src" to another destination device or file "dest".
3165 Note this will fail if the source is too short or if the destination is
3167 not large enough.
3168 This function is deprecated. In new code, use the "copy-device-to-
3170 device" call instead.
3171 Deprecated functions will not be removed from the API, but the fact
3173 that they are deprecated indicates that there are problems with correct
3174 use of these functions.
3175 cp
3177 cp src dest
3178 This copies a file from "src" to "dest" where "dest" is either a
3180 destination filename or destination directory.
3181 cp-a
3183 cp-a src dest
3184 This copies a file or directory from "src" to "dest" recursively using
3186 the "cp -a" command.
3187 cp-r
3189 cp-r src dest
3190 This copies a file or directory from "src" to "dest" recursively using
3192 the "cp -rP" command.
3193 Most users should use "cp-a" instead. This command is useful when you
3195 don't want to preserve permissions, because the target filesystem does
3196 not support it (primarily when writing to DOS FAT filesystems).
3197 cpio-out
3199 cpio-out directory (cpiofile|-) [format:..]
3200 This command packs the contents of directory and downloads it to local
3202 file "cpiofile".
3203 The optional "format" parameter can be used to select the format. Only
3205 the following formats are currently permitted:
3206 "newc"
3208 New (SVR4) portable format. This format happens to be compatible
3209 with the cpio-like format used by the Linux kernel for initramfs.
3210 This is the default format.
3212 "crc"
3214 New (SVR4) portable format with a checksum.
3215 Use "-" instead of a filename to read/write from stdin/stdout.
3217 This command has one or more optional arguments. See "OPTIONAL
3219 ARGUMENTS".
3220 cryptsetup-close
3222 cryptsetup-close device
3223 This closes an encrypted device that was created earlier by
3225 "cryptsetup-open". The "device" parameter must be the name of the
3226 mapping device (ie. /dev/mapper/mapname) and not the name of the
3227 underlying block device.
3228 This command depends on the feature "luks". See also "feature-
3230 available".
3231 cryptsetup-open
3233 cryptsetup-open device mapname [readonly:true|false] [crypttype:..]
3234 This command opens a block device which has been encrypted according to
3236 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
3237 other types.
3238 "device" is the encrypted block device or partition.
3240 The caller must supply one of the keys associated with the encrypted
3242 block device, in the "key" parameter.
3243 This creates a new block device called /dev/mapper/mapname. Reads and
3245 writes to this block device are decrypted from and encrypted to the
3246 underlying "device" respectively.
3247 "mapname" cannot be "control" because that name is reserved by device-
3249 mapper.
3250 If the optional "crypttype" parameter is not present then libguestfs
3252 tries to guess the correct type (for example LUKS or BitLocker).
3253 However you can override this by specifying one of the following types:
3254 "luks"
3256 A Linux LUKS device.
3257 "bitlk"
3259 A Windows BitLocker device.
3260 The optional "readonly" flag, if set to true, creates a read-only
3262 mapping.
3263 If this block device contains LVM volume groups, then calling "lvm-
3265 scan" with the "activate" parameter "true" will make them visible.
3266 Use "list-dm-devices" to list all device mapper devices.
3268 This command has one or more key or passphrase parameters. Guestfish
3270 will prompt for these separately.
3271 This command has one or more optional arguments. See "OPTIONAL
3273 ARGUMENTS".
3274 This command depends on the feature "luks". See also "feature-
3276 available".
3277 dd
3279 dd src dest
3280 This command copies from one source device or file "src" to another
3282 destination device or file "dest". Normally you would use this to copy
3283 to or from a device or partition, for example to duplicate a
3284 filesystem.
3285 If the destination is a device, it must be as large or larger than the
3287 source file or device, otherwise the copy will fail. This command
3288 cannot do partial copies (see "copy-device-to-device").
3289 This function is deprecated. In new code, use the "copy-device-to-
3291 device" call instead.
3292 Deprecated functions will not be removed from the API, but the fact
3294 that they are deprecated indicates that there are problems with correct
3295 use of these functions.
3296 device-index
3298 device-index device
3299 This function takes a device name (eg. "/dev/sdb") and returns the
3301 index of the device in the list of devices.
3302 Index numbers start from 0. The named device must exist, for example
3304 as a string returned from "list-devices".
3305 See also "list-devices", "part-to-dev".
3307 df
3309 df
3310 This command runs the df(1) command to report disk space used.
3312 This command is mostly useful for interactive sessions. It is not
3314 intended that you try to parse the output string. Use "statvfs" from
3315 programs.
3316 df-h
3318 df-h
3319 This command runs the "df -h" command to report disk space used in
3321 human-readable format.
3322 This command is mostly useful for interactive sessions. It is not
3324 intended that you try to parse the output string. Use "statvfs" from
3325 programs.
3326 disk-create
3328 disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]
3329 Create a blank disk image called filename (a host file) with format
3331 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
3332 If used with the optional "backingfile" parameter, then a snapshot is
3334 created on top of the backing file. In this case, "size" must be
3335 passed as "-1". The size of the snapshot is the same as the size of
3336 the backing file, which is discovered automatically. You are
3337 encouraged to also pass "backingformat" to describe the format of
3338 "backingfile".
3339 If filename refers to a block device, then the device is formatted.
3341 The "size" is ignored since block devices have an intrinsic size.
3342 The other optional parameters are:
3344 "preallocation"
3346 If format is "raw", then this can be either "off" (or "sparse") or
3347 "full" to create a sparse or fully allocated file respectively.
3348 The default is "off".
3349 If format is "qcow2", then this can be "off" (or "sparse"),
3351 "metadata" or "full". Preallocating metadata can be faster when
3352 doing lots of writes, but uses more space. The default is "off".
3353 "compat"
3355 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
3356 supported by qemu ≥ 1.1.
3357 "clustersize"
3359 "qcow2" only: Change the qcow2 cluster size. The default is 65536
3360 (bytes) and this setting may be any power of two between 512 and
3361 2097152.
3362 Note that this call does not add the new disk to the handle. You may
3364 need to call "add-drive-opts" separately.
3365 This command has one or more optional arguments. See "OPTIONAL
3367 ARGUMENTS".
3368 disk-format
3370 disk-format filename
3371 Detect and return the format of the disk image called filename.
3373 filename can also be a host device, etc. If the format of the image
3374 could not be detected, then "unknown" is returned.
3375 Note that detecting the disk format can be insecure under some
3377 circumstances. See "CVE-2010-3851" in guestfs(3).
3378 See also: "DISK IMAGE FORMATS" in guestfs(3)
3380 disk-has-backing-file
3382 disk-has-backing-file filename
3383 Detect and return whether the disk image filename has a backing file.
3385 Note that detecting disk features can be insecure under some
3387 circumstances. See "CVE-2010-3851" in guestfs(3).
3388 disk-virtual-size
3390 disk-virtual-size filename
3391 Detect and return the virtual size in bytes of the disk image called
3393 filename.
3394 Note that detecting disk features can be insecure under some
3396 circumstances. See "CVE-2010-3851" in guestfs(3).
3397 dmesg
3399 dmesg
3400 This returns the kernel messages (dmesg(1) output) from the guest
3402 kernel. This is sometimes useful for extended debugging of problems.
3403 Another way to get the same information is to enable verbose messages
3405 with "set-verbose" or by setting the environment variable
3406 "LIBGUESTFS_DEBUG=1" before running the program.
3407 download
3409 download remotefilename (filename|-)
3410 Download file remotefilename and save it as filename on the local
3412 machine.
3413 filename can also be a named pipe.
3415 See also "upload", "cat".
3417 Use "-" instead of a filename to read/write from stdin/stdout.
3419 download-blocks
3421 download-blocks device start stop (filename|-) [unallocated:true|false]
3422 Download the data units from start address to stop from the disk
3424 partition (eg. /dev/sda1) and save them as filename on the local
3425 machine.
3426 The use of this API on sparse disk image formats such as QCOW, may
3428 result in large zero-filled files downloaded on the host.
3429 The size of a data unit varies across filesystem implementations. On
3431 NTFS filesystems data units are referred as clusters while on ExtX ones
3432 they are referred as fragments.
3433 If the optional "unallocated" flag is true (default is false), only the
3435 unallocated blocks will be extracted. This is useful to detect hidden
3436 data or to retrieve deleted files which data units have not been
3437 overwritten yet.
3438 Use "-" instead of a filename to read/write from stdin/stdout.
3440 This command has one or more optional arguments. See "OPTIONAL
3442 ARGUMENTS".
3443 This command depends on the feature "sleuthkit". See also "feature-
3445 available".
3446 download-inode
3448 download-inode device inode (filename|-)
3449 Download a file given its inode from the disk partition (eg. /dev/sda1)
3451 and save it as filename on the local machine.
3452 It is not required to mount the disk to run this command.
3454 The command is capable of downloading deleted or inaccessible files.
3456 Use "-" instead of a filename to read/write from stdin/stdout.
3458 This command depends on the feature "sleuthkit". See also "feature-
3460 available".
3461 download-offset
3463 download-offset remotefilename (filename|-) offset size
3464 Download file remotefilename and save it as filename on the local
3466 machine.
3467 remotefilename is read for "size" bytes starting at "offset" (this
3469 region must be within the file or device).
3470 Note that there is no limit on the amount of data that can be
3472 downloaded with this call, unlike with "pread", and this call always
3473 reads the full amount unless an error occurs.
3474 See also "download", "pread".
3476 Use "-" instead of a filename to read/write from stdin/stdout.
3478 drop-caches
3480 drop-caches whattodrop
3481 This instructs the guest kernel to drop its page cache, and/or dentries
3483 and inode caches. The parameter "whattodrop" tells the kernel what
3484 precisely to drop, see https://linux-mm.org/Drop_Caches
3485 Setting "whattodrop" to 3 should drop everything.
3487 This automatically calls sync(2) before the operation, so that the
3489 maximum guest memory is freed.
3490 du
3492 du path
3493 This command runs the "du -s" command to estimate file space usage for
3495 "path".
3496 "path" can be a file or a directory. If "path" is a directory then the
3498 estimate includes the contents of the directory and all subdirectories
3499 (recursively).
3500 The result is the estimated size in kilobytes (ie. units of 1024
3502 bytes).
3503 e2fsck
3505 e2fsck device [correct:true|false] [forceall:true|false]
3506 This runs the ext2/ext3 filesystem checker on "device". It can take
3508 the following optional arguments:
3509 "correct"
3511 Automatically repair the file system. This option will cause e2fsck
3512 to automatically fix any filesystem problems that can be safely
3513 fixed without human intervention.
3514 This option may not be specified at the same time as the "forceall"
3516 option.
3517 "forceall"
3519 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
3520 used non-interactively.
3521 This option may not be specified at the same time as the "correct"
3523 option.
3524 This command has one or more optional arguments. See "OPTIONAL
3526 ARGUMENTS".
3527 e2fsck-f
3529 e2fsck-f device
3530 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3532 checker on "device", noninteractively (-p), even if the filesystem
3533 appears to be clean (-f).
3534 This function is deprecated. In new code, use the "e2fsck" call
3536 instead.
3537 Deprecated functions will not be removed from the API, but the fact
3539 that they are deprecated indicates that there are problems with correct
3540 use of these functions.
3541 echo-daemon
3543 echo-daemon 'words ...'
3544 This command concatenates the list of "words" passed with single spaces
3546 between them and returns the resulting string.
3547 You can use this command to test the connection through to the daemon.
3549 See also "ping-daemon".
3551 egrep
3553 egrep regex path
3554 This calls the external egrep(1) program and returns the matching
3556 lines.
3557 Because of the message protocol, there is a transfer limit of somewhere
3559 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3560 This function is deprecated. In new code, use the "grep" call instead.
3562 Deprecated functions will not be removed from the API, but the fact
3564 that they are deprecated indicates that there are problems with correct
3565 use of these functions.
3566 egrepi
3568 egrepi regex path
3569 This calls the external "egrep -i" program and returns the matching
3571 lines.
3572 Because of the message protocol, there is a transfer limit of somewhere
3574 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3575 This function is deprecated. In new code, use the "grep" call instead.
3577 Deprecated functions will not be removed from the API, but the fact
3579 that they are deprecated indicates that there are problems with correct
3580 use of these functions.
3581 equal
3583 equal file1 file2
3584 This compares the two files file1 and file2 and returns true if their
3586 content is exactly equal, or false otherwise.
3587 The external cmp(1) program is used for the comparison.
3589 exists
3591 exists path
3592 This returns "true" if and only if there is a file, directory (or
3594 anything) with the given "path" name.
3595 See also "is-file", "is-dir", "stat".
3597 extlinux
3599 extlinux directory
3600 Install the SYSLINUX bootloader on the device mounted at directory.
3602 Unlike "syslinux" which requires a FAT filesystem, this can be used on
3603 an ext2/3/4 or btrfs filesystem.
3604 The directory parameter can be either a mountpoint, or a directory
3606 within the mountpoint.
3607 You also have to mark the partition as "active" ("part-set-bootable")
3609 and a Master Boot Record must be installed (eg. using "pwrite-device")
3610 on the first sector of the whole disk. The SYSLINUX package comes with
3611 some suitable Master Boot Records. See the extlinux(1) man page for
3612 further information.
3613 Additional configuration can be supplied to SYSLINUX by placing a file
3615 called extlinux.conf on the filesystem under directory. For further
3616 information about the contents of this file, see extlinux(1).
3617 See also "syslinux".
3619 This command depends on the feature "extlinux". See also "feature-
3621 available".
3622 f2fs-expand
3624 f2fs-expand device
3625 This expands a f2fs filesystem to match the size of the underlying
3627 device.
3628 This command depends on the feature "f2fs". See also "feature-
3630 available".
3631 fallocate
3633 fallocate path len
3634 This command preallocates a file (containing zero bytes) named "path"
3636 of size "len" bytes. If the file exists already, it is overwritten.
3637 Do not confuse this with the guestfish-specific "alloc" command which
3639 allocates a file in the host and attaches it as a device.
3640 This function is deprecated. In new code, use the "fallocate64" call
3642 instead.
3643 Deprecated functions will not be removed from the API, but the fact
3645 that they are deprecated indicates that there are problems with correct
3646 use of these functions.
3647 fallocate64
3649 fallocate64 path len
3650 This command preallocates a file (containing zero bytes) named "path"
3652 of size "len" bytes. If the file exists already, it is overwritten.
3653 Note that this call allocates disk blocks for the file. To create a
3655 sparse file use "truncate-size" instead.
3656 The deprecated call "fallocate" does the same, but owing to an
3658 oversight it only allowed 30 bit lengths to be specified, effectively
3659 limiting the maximum size of files created through that call to 1GB.
3660 Do not confuse this with the guestfish-specific "alloc" and "sparse"
3662 commands which create a file in the host and attach it as a device.
3663 feature-available
3665 feature-available 'groups ...'
3666 This is the same as "available", but unlike that call it returns a
3668 simple true/false boolean result, instead of throwing an exception if a
3669 feature is not found. For other documentation see "available".
3670 fgrep
3672 fgrep pattern path
3673 This calls the external fgrep(1) program and returns the matching
3675 lines.
3676 Because of the message protocol, there is a transfer limit of somewhere
3678 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3679 This function is deprecated. In new code, use the "grep" call instead.
3681 Deprecated functions will not be removed from the API, but the fact
3683 that they are deprecated indicates that there are problems with correct
3684 use of these functions.
3685 fgrepi
3687 fgrepi pattern path
3688 This calls the external "fgrep -i" program and returns the matching
3690 lines.
3691 Because of the message protocol, there is a transfer limit of somewhere
3693 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3694 This function is deprecated. In new code, use the "grep" call instead.
3696 Deprecated functions will not be removed from the API, but the fact
3698 that they are deprecated indicates that there are problems with correct
3699 use of these functions.
3700 file
3702 file path
3703 This call uses the standard file(1) command to determine the type or
3705 contents of the file.
3706 This call will also transparently look inside various types of
3708 compressed file.
3709 The exact command which runs is "file -zb path". Note in particular
3711 that the filename is not prepended to the output (the -b option).
3712 The output depends on the output of the underlying file(1) command and
3714 it can change in future in ways beyond our control. In other words,
3715 the output is not guaranteed by the ABI.
3716 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
3718 "is-zero".
3719 file-architecture
3721 file-architecture filename
3722 This detects the architecture of the binary filename, and returns it if
3724 known.
3725 Currently defined architectures are:
3727 "aarch64"
3729 64 bit ARM.
3730 "arm"
3732 32 bit ARM.
3733 "i386"
3735 This string is returned for all 32 bit i386, i486, i586, i686
3736 binaries irrespective of the precise processor requirements of the
3737 binary.
3738 "ia64"
3740 Intel Itanium.
3741 "ppc"
3743 32 bit Power PC.
3744 "ppc64"
3746 64 bit Power PC (big endian).
3747 "ppc64le"
3749 64 bit Power PC (little endian).
3750 "riscv32"
3752 "riscv64"
3753 "riscv128"
3754 RISC-V 32-, 64- or 128-bit variants.
3755 "s390"
3757 31 bit IBM S/390.
3758 "s390x"
3760 64 bit IBM S/390.
3761 "sparc"
3763 32 bit SPARC.
3764 "sparc64"
3766 64 bit SPARC V9 and above.
3767 "x86_64"
3769 64 bit x86-64.
3770 Libguestfs may return other architecture strings in future.
3772 The function works on at least the following types of files:
3774 • many types of Un*x and Linux binary
3776 • many types of Un*x and Linux shared library
3778 • Windows Win32 and Win64 binaries
3780 • Windows Win32 and Win64 DLLs
3782 Win32 binaries and DLLs return "i386".
3784 Win64 binaries and DLLs return "x86_64".
3786 • Linux kernel modules
3788 • Linux new-style initrd images
3790 • some non-x86 Linux vmlinuz kernels
3792 What it can't do currently:
3794 • static libraries (libfoo.a)
3796 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
3798 • x86 Linux vmlinuz kernels
3800 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
3802 and compressed code, and are horribly hard to unpack. If you want
3803 to find the architecture of a kernel, use the architecture of the
3804 associated initrd or kernel module(s) instead.
3805 filesize
3807 filesize file
3808 This command returns the size of file in bytes.
3810 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
3812 file" etc. To get the size of block devices, use "blockdev-getsize64".
3813 filesystem-available
3815 filesystem-available filesystem
3816 Check whether libguestfs supports the named filesystem. The argument
3818 "filesystem" is a filesystem name, such as "ext3".
3819 You must call "launch" before using this command.
3821 This is mainly useful as a negative test. If this returns true, it
3823 doesn't mean that a particular filesystem can be created or mounted,
3824 since filesystems can fail for other reasons such as it being a later
3825 version of the filesystem, or having incompatible features, or lacking
3826 the right mkfs.<fs> tool.
3827 See also "available", "feature-available", "AVAILABILITY" in
3829 guestfs(3).
3830 filesystem-walk
3832 filesystem-walk device
3833 Walk through the internal structures of a disk partition (eg.
3835 /dev/sda1) in order to return a list of all the files and directories
3836 stored within.
3837 It is not necessary to mount the disk partition to run this command.
3839 All entries in the filesystem are returned. This function can list
3841 deleted or unaccessible files. The entries are not sorted.
3842 The "tsk_dirent" structure contains the following fields.
3844 "tsk_inode"
3846 Filesystem reference number of the node. It might be 0 if the node
3847 has been deleted.
3848 "tsk_type"
3850 Basic file type information. See below for a detailed list of
3851 values.
3852 "tsk_size"
3854 File size in bytes. It might be "-1" if the node has been deleted.
3855 "tsk_name"
3857 The file path relative to its directory.
3858 "tsk_flags"
3860 Bitfield containing extra information regarding the entry. It
3861 contains the logical OR of the following values:
3862 0x0001
3864 If set to 1, the file is allocated and visible within the
3865 filesystem. Otherwise, the file has been deleted. Under
3866 certain circumstances, the function "download_inode" can be
3867 used to recover deleted files.
3868 0x0002
3870 Filesystem such as NTFS and Ext2 or greater, separate the file
3871 name from the metadata structure. The bit is set to 1 when the
3872 file name is in an unallocated state and the metadata structure
3873 is in an allocated one. This generally implies the metadata
3874 has been reallocated to a new file. Therefore, information
3875 such as file type, file size, timestamps, number of links and
3876 symlink target might not correspond with the ones of the
3877 original deleted entry.
3878 0x0004
3880 The bit is set to 1 when the file is compressed using
3881 filesystem native compression support (NTFS). The API is not
3882 able to detect application level compression.
3883 "tsk_atime_sec"
3885 "tsk_atime_nsec"
3886 "tsk_mtime_sec"
3887 "tsk_mtime_nsec"
3888 "tsk_ctime_sec"
3889 "tsk_ctime_nsec"
3890 "tsk_crtime_sec"
3891 "tsk_crtime_nsec"
3892 Respectively, access, modification, last status change and creation
3893 time in Unix format in seconds and nanoseconds.
3894 "tsk_nlink"
3896 Number of file names pointing to this entry.
3897 "tsk_link"
3899 If the entry is a symbolic link, this field will contain the path
3900 to the target file.
3901 The "tsk_type" field will contain one of the following characters:
3903 'b' Block special
3905 'c' Char special
3907 'd' Directory
3909 'f' FIFO (named pipe)
3911 'l' Symbolic link
3913 'r' Regular file
3915 's' Socket
3917 'h' Shadow inode (Solaris)
3919 'w' Whiteout inode (BSD)
3921 'u' Unknown file type
3923 This command depends on the feature "libtsk". See also "feature-
3925 available".
3926 fill
3928 fill c len path
3929 This command creates a new file called "path". The initial content of
3931 the file is "len" octets of "c", where "c" must be a number in the
3932 range "[0..255]".
3933 To fill a file with zero bytes (sparsely), it is much more efficient to
3935 use "truncate-size". To create a file with a pattern of repeating
3936 bytes use "fill-pattern".
3937 fill-dir
3939 fill-dir dir nr
3940 This function, useful for testing filesystems, creates "nr" empty files
3942 in the directory "dir" with names 00000000 through "nr-1" (ie. each
3943 file name is 8 digits long padded with zeroes).
3944 fill-pattern
3946 fill-pattern pattern len path
3947 This function is like "fill" except that it creates a new file of
3949 length "len" containing the repeating pattern of bytes in "pattern".
3950 The pattern is truncated if necessary to ensure the length of the file
3951 is exactly "len" bytes.
3952 find
3954 find directory
3955 This command lists out all files and directories, recursively, starting
3957 at directory. It is essentially equivalent to running the shell
3958 command "find directory -print" but some post-processing happens on the
3959 output, described below.
3960 This returns a list of strings without any prefix. Thus if the
3962 directory structure was:
3963 /tmp/a
3965 /tmp/b
3966 /tmp/c/d
3967 then the returned list from "find" /tmp would be 4 elements:
3969 a
3971 b
3972 c
3973 c/d
3974 If directory is not a directory, then this command returns an error.
3976 The returned list is sorted.
3978 find0
3980 find0 directory (files|-)
3981 This command lists out all files and directories, recursively, starting
3983 at directory, placing the resulting list in the external file called
3984 files.
3985 This command works the same way as "find" with the following
3987 exceptions:
3988 • The resulting list is written to an external file.
3990 • Items (filenames) in the result are separated by "\0" characters.
3992 See find(1) option -print0.
3993 • The result list is not sorted.
3995 Use "-" instead of a filename to read/write from stdin/stdout.
3997 find-inode
3999 find-inode device inode
4000 Searches all the entries associated with the given inode.
4002 For each entry, a "tsk_dirent" structure is returned. See
4004 "filesystem_walk" for more information about "tsk_dirent" structures.
4005 This command depends on the feature "libtsk". See also "feature-
4007 available".
4008 findfs-label
4010 findfs-label label
4011 This command searches the filesystems and returns the one which has the
4013 given label. An error is returned if no such filesystem can be found.
4014 To find the label of a filesystem, use "vfs-label".
4016 findfs-uuid
4018 findfs-uuid uuid
4019 This command searches the filesystems and returns the one which has the
4021 given UUID. An error is returned if no such filesystem can be found.
4022 To find the UUID of a filesystem, use "vfs-uuid".
4024 fsck
4026 fsck fstype device
4027 This runs the filesystem checker (fsck) on "device" which should have
4029 filesystem type "fstype".
4030 The returned integer is the status. See fsck(8) for the list of status
4032 codes from "fsck".
4033 Notes:
4035 • Multiple status codes can be summed together.
4037 • A non-zero return code can mean "success", for example if errors
4039 have been corrected on the filesystem.
4040 • Checking or repairing NTFS volumes is not supported (by linux-
4042 ntfs).
4043 This command is entirely equivalent to running "fsck -a -t fstype
4045 device".
4046 fstrim
4048 fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]
4049 Trim the free space in the filesystem mounted on "mountpoint". The
4051 filesystem must be mounted read-write.
4052 The filesystem contents are not affected, but any free space in the
4054 filesystem is "trimmed", that is, given back to the host device, thus
4055 making disk images more sparse, allowing unused space in qcow2 files to
4056 be reused, etc.
4057 This operation requires support in libguestfs, the mounted filesystem,
4059 the host filesystem, qemu and the host kernel. If this support isn't
4060 present it may give an error or even appear to run but do nothing.
4061 In the case where the kernel vfs driver does not support trimming, this
4063 call will fail with errno set to "ENOTSUP". Currently this happens
4064 when trying to trim FAT filesystems.
4065 See also "zero-free-space". That is a slightly different operation
4067 that turns free space in the filesystem into zeroes. It is valid to
4068 call "fstrim" either instead of, or after calling "zero-free-space".
4069 This command has one or more optional arguments. See "OPTIONAL
4071 ARGUMENTS".
4072 This command depends on the feature "fstrim". See also "feature-
4074 available".
4075 get-append
4077 get-append
4078 Return the additional kernel options which are added to the libguestfs
4080 appliance kernel command line.
4081 If "NULL" then no options are added.
4083 get-attach-method
4085 get-attach-method
4086 Return the current backend.
4088 See "set-backend" and "BACKEND" in guestfs(3).
4090 This function is deprecated. In new code, use the "get-backend" call
4092 instead.
4093 Deprecated functions will not be removed from the API, but the fact
4095 that they are deprecated indicates that there are problems with correct
4096 use of these functions.
4097 get-autosync
4099 get-autosync
4100 Get the autosync flag.
4102 get-backend
4104 get-backend
4105 Return the current backend.
4107 This handle property was previously called the "attach method".
4109 See "set-backend" and "BACKEND" in guestfs(3).
4111 get-backend-setting
4113 get-backend-setting name
4114 Find a backend setting string which is either "name" or begins with
4116 "name=". If "name", this returns the string "1". If "name=", this
4117 returns the part after the equals sign (which may be an empty string).
4118 If no such setting is found, this function throws an error. The errno
4120 (see "last-errno") will be "ESRCH" in this case.
4121 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4123 get-backend-settings
4125 get-backend-settings
4126 Return the current backend settings.
4128 This call returns all backend settings strings. If you want to find a
4130 single backend setting, see "get-backend-setting".
4131 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4133 get-cachedir
4135 get-cachedir
4136 Get the directory used by the handle to store the appliance cache.
4138 get-direct
4140 get-direct
4141 Return the direct appliance mode flag.
4143 This function is deprecated. In new code, use the "internal-get-
4145 console-socket" call instead.
4146 Deprecated functions will not be removed from the API, but the fact
4148 that they are deprecated indicates that there are problems with correct
4149 use of these functions.
4150 get-e2attrs
4152 get-e2attrs file
4153 This returns the file attributes associated with file.
4155 The attributes are a set of bits associated with each inode which
4157 affect the behaviour of the file. The attributes are returned as a
4158 string of letters (described below). The string may be empty,
4159 indicating that no file attributes are set for this file.
4160 These attributes are only present when the file is located on an
4162 ext2/3/4 filesystem. Using this call on other filesystem types will
4163 result in an error.
4164 The characters (file attributes) in the returned string are currently:
4166 'A' When the file is accessed, its atime is not modified.
4168 'a' The file is append-only.
4170 'c' The file is compressed on-disk.
4172 'D' (Directories only.) Changes to this directory are written
4174 synchronously to disk.
4175 'd' The file is not a candidate for backup (see dump(8)).
4177 'E' The file has compression errors.
4179 'e' The file is using extents.
4181 'h' The file is storing its blocks in units of the filesystem blocksize
4183 instead of sectors.
4184 'I' (Directories only.) The directory is using hashed trees.
4186 'i' The file is immutable. It cannot be modified, deleted or renamed.
4188 No link can be created to this file.
4189 'j' The file is data-journaled.
4191 's' When the file is deleted, all its blocks will be zeroed.
4193 'S' Changes to this file are written synchronously to disk.
4195 'T' (Directories only.) This is a hint to the block allocator that
4197 subdirectories contained in this directory should be spread across
4198 blocks. If not present, the block allocator will try to group
4199 subdirectories together.
4200 't' For a file, this disables tail-merging. (Not used by upstream
4202 implementations of ext2.)
4203 'u' When the file is deleted, its blocks will be saved, allowing the
4205 file to be undeleted.
4206 'X' The raw contents of the compressed file may be accessed.
4208 'Z' The compressed file is dirty.
4210 More file attributes may be added to this list later. Not all file
4212 attributes may be set for all kinds of files. For detailed
4213 information, consult the chattr(1) man page.
4214 See also "set-e2attrs".
4216 Don't confuse these attributes with extended attributes (see
4218 "getxattr").
4219 get-e2generation
4221 get-e2generation file
4222 This returns the ext2 file generation of a file. The generation (which
4224 used to be called the "version") is a number associated with an inode.
4225 This is most commonly used by NFS servers.
4226 The generation is only present when the file is located on an ext2/3/4
4228 filesystem. Using this call on other filesystem types will result in
4229 an error.
4230 See "set-e2generation".
4232 get-e2label
4234 get-e2label device
4235 This returns the ext2/3/4 filesystem label of the filesystem on
4237 "device".
4238 This function is deprecated. In new code, use the "vfs-label" call
4240 instead.
4241 Deprecated functions will not be removed from the API, but the fact
4243 that they are deprecated indicates that there are problems with correct
4244 use of these functions.
4245 get-e2uuid
4247 get-e2uuid device
4248 This returns the ext2/3/4 filesystem UUID of the filesystem on
4250 "device".
4251 This function is deprecated. In new code, use the "vfs-uuid" call
4253 instead.
4254 Deprecated functions will not be removed from the API, but the fact
4256 that they are deprecated indicates that there are problems with correct
4257 use of these functions.
4258 get-hv
4260 get-hv
4261 Return the current hypervisor binary.
4263 This is always non-NULL. If it wasn't set already, then this will
4265 return the default qemu binary name.
4266 get-identifier
4268 get-identifier
4269 Get the handle identifier. See "set-identifier".
4271 get-libvirt-requested-credential-challenge
4273 get-libvirt-requested-credential-challenge index
4274 Get the challenge (provided by libvirt) for the "index"'th requested
4276 credential. If libvirt did not provide a challenge, this returns the
4277 empty string "".
4278 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4280 example code.
4281 get-libvirt-requested-credential-defresult
4283 get-libvirt-requested-credential-defresult index
4284 Get the default result (provided by libvirt) for the "index"'th
4286 requested credential. If libvirt did not provide a default result,
4287 this returns the empty string "".
4288 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4290 example code.
4291 get-libvirt-requested-credential-prompt
4293 get-libvirt-requested-credential-prompt index
4294 Get the prompt (provided by libvirt) for the "index"'th requested
4296 credential. If libvirt did not provide a prompt, this returns the
4297 empty string "".
4298 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4300 example code.
4301 get-libvirt-requested-credentials
4303 get-libvirt-requested-credentials
4304 This should only be called during the event callback for events of type
4306 "GUESTFS_EVENT_LIBVIRT_AUTH".
4307 Return the list of credentials requested by libvirt. Possible values
4309 are a subset of the strings provided when you called "set-libvirt-
4310 supported-credentials".
4311 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4313 example code.
4314 get-memsize
4316 get-memsize
4317 This gets the memory size in megabytes allocated to the hypervisor.
4319 If "set-memsize" was not called on this handle, and if
4321 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4322 default value for memsize.
4323 For more information on the architecture of libguestfs, see guestfs(3).
4325 get-network
4327 get-network
4328 This returns the enable network flag.
4330 get-path
4332 get-path
4333 Return the current search path.
4335 This is always non-NULL. If it wasn't set already, then this will
4337 return the default path.
4338 get-pgroup
4340 get-pgroup
4341 This returns the process group flag.
4343 get-pid
4345 pid
4346 get-pid
4347 Return the process ID of the hypervisor. If there is no hypervisor
4349 running, then this will return an error.
4350 This is an internal call used for debugging and testing.
4352 get-program
4354 get-program
4355 Get the program name. See "set-program".
4357 get-qemu
4359 get-qemu
4360 Return the current hypervisor binary (usually qemu).
4362 This is always non-NULL. If it wasn't set already, then this will
4364 return the default qemu binary name.
4365 This function is deprecated. In new code, use the "get-hv" call
4367 instead.
4368 Deprecated functions will not be removed from the API, but the fact
4370 that they are deprecated indicates that there are problems with correct
4371 use of these functions.
4372 get-recovery-proc
4374 get-recovery-proc
4375 Return the recovery process enabled flag.
4377 get-selinux
4379 get-selinux
4380 This returns the current setting of the selinux flag which is passed to
4382 the appliance at boot time. See "set-selinux".
4383 For more information on the architecture of libguestfs, see guestfs(3).
4385 This function is deprecated. In new code, use the "selinux-relabel"
4387 call instead.
4388 Deprecated functions will not be removed from the API, but the fact
4390 that they are deprecated indicates that there are problems with correct
4391 use of these functions.
4392 get-smp
4394 get-smp
4395 This returns the number of virtual CPUs assigned to the appliance.
4397 get-sockdir
4399 get-sockdir
4400 Get the directory used by the handle to store temporary socket files.
4402 This is different from "get-tmpdir", as we need shorter paths for
4404 sockets (due to the limited buffers of filenames for UNIX sockets), and
4405 "get-tmpdir" may be too long for them.
4406 The environment variable "XDG_RUNTIME_DIR" controls the default value:
4408 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
4409 the default.
4410 get-tmpdir
4412 get-tmpdir
4413 Get the directory used by the handle to store temporary files.
4415 get-trace
4417 get-trace
4418 Return the command trace flag.
4420 get-umask
4422 get-umask
4423 Return the current umask. By default the umask is 022 unless it has
4425 been set by calling "umask".
4426 get-verbose
4428 get-verbose
4429 This returns the verbose messages flag.
4431 getcon
4433 getcon
4434 This gets the SELinux security context of the daemon.
4436 See the documentation about SELINUX in guestfs(3), and "setcon"
4438 This function is deprecated. In new code, use the "selinux-relabel"
4440 call instead.
4441 Deprecated functions will not be removed from the API, but the fact
4443 that they are deprecated indicates that there are problems with correct
4444 use of these functions.
4445 This command depends on the feature "selinux". See also "feature-
4447 available".
4448 getxattr
4450 getxattr path name
4451 Get a single extended attribute from file "path" named "name". This
4453 call follows symlinks. If you want to lookup an extended attribute for
4454 the symlink itself, use "lgetxattr".
4455 Normally it is better to get all extended attributes from a file in one
4457 go by calling "getxattrs". However some Linux filesystem
4458 implementations are buggy and do not provide a way to list out
4459 attributes. For these filesystems (notably ntfs-3g) you have to know
4460 the names of the extended attributes you want in advance and call this
4461 function.
4462 Extended attribute values are blobs of binary data. If there is no
4464 extended attribute named "name", this returns an error.
4465 See also: "getxattrs", "lgetxattr", attr(5).
4467 This command depends on the feature "linuxxattrs". See also "feature-
4469 available".
4470 getxattrs
4472 getxattrs path
4473 This call lists the extended attributes of the file or directory
4475 "path".
4476 At the system call level, this is a combination of the listxattr(2) and
4478 getxattr(2) calls.
4479 See also: "lgetxattrs", attr(5).
4481 This command depends on the feature "linuxxattrs". See also "feature-
4483 available".
4484 glob-expand
4486 glob-expand-opts
4487 glob-expand pattern [directoryslash:true|false]
4488 This command searches for all the pathnames matching "pattern"
4490 according to the wildcard expansion rules used by the shell.
4491 If no paths match, then this returns an empty list (note: not an
4493 error).
4494 It is just a wrapper around the C glob(3) function with flags
4496 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
4497 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
4499 and it defaults to true. It can be explicitly set as off to return no
4500 trailing slashes in filenames of directories.
4501 Notice that there is no equivalent command for expanding a device name
4503 (eg. /dev/sd*). Use "list-devices", "list-partitions" etc functions
4504 instead.
4505 This command has one or more optional arguments. See "OPTIONAL
4507 ARGUMENTS".
4508 grep
4510 grep-opts
4511 grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
4512 This calls the external grep(1) program and returns the matching lines.
4514 The optional flags are:
4516 "extended"
4518 Use extended regular expressions. This is the same as using the -E
4519 flag.
4520 "fixed"
4522 Match fixed (don't use regular expressions). This is the same as
4523 using the -F flag.
4524 "insensitive"
4526 Match case-insensitive. This is the same as using the -i flag.
4527 "compressed"
4529 Use zgrep(1) instead of grep(1). This allows the input to be
4530 compress- or gzip-compressed.
4531 This command has one or more optional arguments. See "OPTIONAL
4533 ARGUMENTS".
4534 Because of the message protocol, there is a transfer limit of somewhere
4536 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4537 grepi
4539 grepi regex path
4540 This calls the external "grep -i" program and returns the matching
4542 lines.
4543 Because of the message protocol, there is a transfer limit of somewhere
4545 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4546 This function is deprecated. In new code, use the "grep" call instead.
4548 Deprecated functions will not be removed from the API, but the fact
4550 that they are deprecated indicates that there are problems with correct
4551 use of these functions.
4552 grub-install
4554 grub-install root device
4555 This command installs GRUB 1 (the Grand Unified Bootloader) on
4557 "device", with the root directory being "root".
4558 Notes:
4560 • There is currently no way in the API to install grub2, which is
4562 used by most modern Linux guests. It is possible to run the grub2
4563 command from the guest, although see the caveats in "RUNNING
4564 COMMANDS" in guestfs(3).
4565 • This uses grub-install(8) from the host. Unfortunately grub is not
4567 always compatible with itself, so this only works in rather narrow
4568 circumstances. Careful testing with each guest version is
4569 advisable.
4570 • If grub-install reports the error "No suitable drive was found in
4572 the generated device map." it may be that you need to create a
4573 /boot/grub/device.map file first that contains the mapping between
4574 grub device names and Linux device names. It is usually sufficient
4575 to create a file containing:
4576 (hd0) /dev/vda
4578 replacing /dev/vda with the name of the installation device.
4580 This command depends on the feature "grub". See also "feature-
4582 available".
4583 head
4585 head path
4586 This command returns up to the first 10 lines of a file as a list of
4588 strings.
4589 Because of the message protocol, there is a transfer limit of somewhere
4591 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4592 head-n
4594 head-n nrlines path
4595 If the parameter "nrlines" is a positive number, this returns the first
4597 "nrlines" lines of the file "path".
4598 If the parameter "nrlines" is a negative number, this returns lines
4600 from the file "path", excluding the last "nrlines" lines.
4601 If the parameter "nrlines" is zero, this returns an empty list.
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 hexdump
4608 hexdump path
4609 This runs "hexdump -C" on the given "path". The result is the human-
4611 readable, canonical hex dump of the file.
4612 Because of the message protocol, there is a transfer limit of somewhere
4614 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4615 hivex-close
4617 hivex-close
4618 Close the current hivex handle.
4620 This is a wrapper around the hivex(3) call of the same name.
4622 This command depends on the feature "hivex". See also "feature-
4624 available".
4625 hivex-commit
4627 hivex-commit filename
4628 Commit (write) changes to the hive.
4630 If the optional filename parameter is null, then the changes are
4632 written back to the same hive that was opened. If this is not null
4633 then they are written to the alternate filename given and the original
4634 hive is left untouched.
4635 This is a wrapper around the hivex(3) call of the same name.
4637 This command depends on the feature "hivex". See also "feature-
4639 available".
4640 hivex-node-add-child
4642 hivex-node-add-child parent name
4643 Add a child node to "parent" named "name".
4645 This is a wrapper around the hivex(3) call of the same name.
4647 This command depends on the feature "hivex". See also "feature-
4649 available".
4650 hivex-node-children
4652 hivex-node-children nodeh
4653 Return the list of nodes which are subkeys of "nodeh".
4655 This is a wrapper around the hivex(3) call of the same name.
4657 This command depends on the feature "hivex". See also "feature-
4659 available".
4660 hivex-node-delete-child
4662 hivex-node-delete-child nodeh
4663 Delete "nodeh", recursively if necessary.
4665 This is a wrapper around the hivex(3) call of the same name.
4667 This command depends on the feature "hivex". See also "feature-
4669 available".
4670 hivex-node-get-child
4672 hivex-node-get-child nodeh name
4673 Return the child of "nodeh" with the name "name", if it exists. This
4675 can return 0 meaning the name was not found.
4676 This is a wrapper around the hivex(3) call of the same name.
4678 This command depends on the feature "hivex". See also "feature-
4680 available".
4681 hivex-node-get-value
4683 hivex-node-get-value nodeh key
4684 Return the value attached to "nodeh" which has the name "key", if it
4686 exists. This can return 0 meaning the key was not found.
4687 This is a wrapper around the hivex(3) call of the same name.
4689 This command depends on the feature "hivex". See also "feature-
4691 available".
4692 hivex-node-name
4694 hivex-node-name nodeh
4695 Return the name of "nodeh".
4697 This is a wrapper around the hivex(3) call of the same name.
4699 This command depends on the feature "hivex". See also "feature-
4701 available".
4702 hivex-node-parent
4704 hivex-node-parent nodeh
4705 Return the parent node of "nodeh".
4707 This is a wrapper around the hivex(3) call of the same name.
4709 This command depends on the feature "hivex". See also "feature-
4711 available".
4712 hivex-node-set-value
4714 hivex-node-set-value nodeh key t val
4715 Set or replace a single value under the node "nodeh". The "key" is the
4717 name, "t" is the type, and "val" is the data.
4718 This is a wrapper around the hivex(3) call of the same name.
4720 This command depends on the feature "hivex". See also "feature-
4722 available".
4723 hivex-node-values
4725 hivex-node-values nodeh
4726 Return the array of (key, datatype, data) tuples attached to "nodeh".
4728 This is a wrapper around the hivex(3) call of the same name.
4730 This command depends on the feature "hivex". See also "feature-
4732 available".
4733 hivex-open
4735 hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]
4736 Open the Windows Registry hive file named filename. If there was any
4738 previous hivex handle associated with this guestfs session, then it is
4739 closed.
4740 This is a wrapper around the hivex(3) call of the same name.
4742 This command has one or more optional arguments. See "OPTIONAL
4744 ARGUMENTS".
4745 This command depends on the feature "hivex". See also "feature-
4747 available".
4748 hivex-root
4750 hivex-root
4751 Return the root node of the hive.
4753 This is a wrapper around the hivex(3) call of the same name.
4755 This command depends on the feature "hivex". See also "feature-
4757 available".
4758 hivex-value-key
4760 hivex-value-key valueh
4761 Return the key (name) field of a (key, datatype, data) tuple.
4763 This is a wrapper around the hivex(3) call of the same name.
4765 This command depends on the feature "hivex". See also "feature-
4767 available".
4768 hivex-value-string
4770 hivex-value-string valueh
4771 This calls "hivex-value-value" (which returns the data field from a
4773 hivex value tuple). It then assumes that the field is a UTF-16LE
4774 string and converts the result to UTF-8 (or if this is not possible, it
4775 returns an error).
4776 This is useful for reading strings out of the Windows registry.
4778 However it is not foolproof because the registry is not strongly-typed
4779 and fields can contain arbitrary or unexpected data.
4780 This command depends on the feature "hivex". See also "feature-
4782 available".
4783 hivex-value-type
4785 hivex-value-type valueh
4786 Return the data type field from a (key, datatype, data) tuple.
4788 This is a wrapper around the hivex(3) call of the same name.
4790 This command depends on the feature "hivex". See also "feature-
4792 available".
4793 hivex-value-utf8
4795 hivex-value-utf8 valueh
4796 This calls "hivex-value-value" (which returns the data field from a
4798 hivex value tuple). It then assumes that the field is a UTF-16LE
4799 string and converts the result to UTF-8 (or if this is not possible, it
4800 returns an error).
4801 This is useful for reading strings out of the Windows registry.
4803 However it is not foolproof because the registry is not strongly-typed
4804 and fields can contain arbitrary or unexpected data.
4805 This function is deprecated. In new code, use the "hivex-value-string"
4807 call instead.
4808 Deprecated functions will not be removed from the API, but the fact
4810 that they are deprecated indicates that there are problems with correct
4811 use of these functions.
4812 This command depends on the feature "hivex". See also "feature-
4814 available".
4815 hivex-value-value
4817 hivex-value-value valueh
4818 Return the data field of a (key, datatype, data) tuple.
4820 This is a wrapper around the hivex(3) call of the same name.
4822 See also: "hivex-value-utf8".
4824 This command depends on the feature "hivex". See also "feature-
4826 available".
4827 initrd-cat
4829 initrd-cat initrdpath filename
4830 This command unpacks the file filename from the initrd file called
4832 initrdpath. The filename must be given without the initial /
4833 character.
4834 For example, in guestfish you could use the following command to
4836 examine the boot script (usually called /init) contained in a Linux
4837 initrd or initramfs image:
4838 initrd-cat /boot/initrd-<version>.img init
4840 See also "initrd-list".
4842 Because of the message protocol, there is a transfer limit of somewhere
4844 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4845 initrd-list
4847 initrd-list path
4848 This command lists out files contained in an initrd.
4850 The files are listed without any initial / character. The files are
4852 listed in the order they appear (not necessarily alphabetical).
4853 Directory names are listed as separate items.
4854 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
4856 as initrd. We only support the newer initramfs format (compressed cpio
4857 files).
4858 inotify-add-watch
4860 inotify-add-watch path mask
4861 Watch "path" for the events listed in "mask".
4863 Note that if "path" is a directory then events within that directory
4865 are watched, but this does not happen recursively (in subdirectories).
4866 Note for non-C or non-Linux callers: the inotify events are defined by
4868 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
4869 This command depends on the feature "inotify". See also "feature-
4871 available".
4872 inotify-close
4874 inotify-close
4875 This closes the inotify handle which was previously opened by
4877 inotify_init. It removes all watches, throws away any pending events,
4878 and deallocates all resources.
4879 This command depends on the feature "inotify". See also "feature-
4881 available".
4882 inotify-files
4884 inotify-files
4885 This function is a helpful wrapper around "inotify-read" which just
4887 returns a list of pathnames of objects that were touched. The returned
4888 pathnames are sorted and deduplicated.
4889 This command depends on the feature "inotify". See also "feature-
4891 available".
4892 inotify-init
4894 inotify-init maxevents
4895 This command creates a new inotify handle. The inotify subsystem can
4897 be used to notify events which happen to objects in the guest
4898 filesystem.
4899 "maxevents" is the maximum number of events which will be queued up
4901 between calls to "inotify-read" or "inotify-files". If this is passed
4902 as 0, then the kernel (or previously set) default is used. For Linux
4903 2.6.29 the default was 16384 events. Beyond this limit, the kernel
4904 throws away events, but records the fact that it threw them away by
4905 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
4906 "inotify-read").
4907 Before any events are generated, you have to add some watches to the
4909 internal watch list. See: "inotify-add-watch" and "inotify-rm-watch".
4910 Queued up events should be read periodically by calling "inotify-read"
4912 (or "inotify-files" which is just a helpful wrapper around "inotify-
4913 read"). If you don't read the events out often enough then you risk
4914 the internal queue overflowing.
4915 The handle should be closed after use by calling "inotify-close". This
4917 also removes any watches automatically.
4918 See also inotify(7) for an overview of the inotify interface as exposed
4920 by the Linux kernel, which is roughly what we expose via libguestfs.
4921 Note that there is one global inotify handle per libguestfs instance.
4922 This command depends on the feature "inotify". See also "feature-
4924 available".
4925 inotify-read
4927 inotify-read
4928 Return the complete queue of events that have happened since the
4930 previous read call.
4931 If no events have happened, this returns an empty list.
4933 Note: In order to make sure that all events have been read, you must
4935 call this function repeatedly until it returns an empty list. The
4936 reason is that the call will read events up to the maximum appliance-
4937 to-host message size and leave remaining events in the queue.
4938 This command depends on the feature "inotify". See also "feature-
4940 available".
4941 inotify-rm-watch
4943 inotify-rm-watch wd
4944 Remove a previously defined inotify watch. See "inotify-add-watch".
4946 This command depends on the feature "inotify". See also "feature-
4948 available".
4949 inspect-get-arch
4951 inspect-get-arch root
4952 This returns the architecture of the inspected operating system. The
4954 possible return values are listed under "file-architecture".
4955 If the architecture could not be determined, then the string "unknown"
4957 is returned.
4958 Please read "INSPECTION" in guestfs(3) for more details.
4960 inspect-get-distro
4962 inspect-get-distro root
4963 This returns the distro (distribution) of the inspected operating
4965 system.
4966 Currently defined distros are:
4968 "alpinelinux"
4970 Alpine Linux.
4971 "altlinux"
4973 ALT Linux.
4974 "archlinux"
4976 Arch Linux.
4977 "buildroot"
4979 Buildroot-derived distro, but not one we specifically recognize.
4980 "centos"
4982 CentOS.
4983 "cirros"
4985 Cirros.
4986 "coreos"
4988 CoreOS.
4989 "debian"
4991 Debian.
4992 "fedora"
4994 Fedora.
4995 "freebsd"
4997 FreeBSD.
4998 "freedos"
5000 FreeDOS.
5001 "frugalware"
5003 Frugalware.
5004 "gentoo"
5006 Gentoo.
5007 "kalilinux"
5009 Kali Linux.
5010 "kylin"
5012 Kylin.
5013 "linuxmint"
5015 Linux Mint.
5016 "mageia"
5018 Mageia.
5019 "mandriva"
5021 Mandriva.
5022 "meego"
5024 MeeGo.
5025 "msdos"
5027 Microsoft DOS.
5028 "neokylin"
5030 NeoKylin.
5031 "netbsd"
5033 NetBSD.
5034 "openbsd"
5036 OpenBSD.
5037 "openmandriva"
5039 OpenMandriva Lx.
5040 "opensuse"
5042 OpenSUSE.
5043 "oraclelinux"
5045 Oracle Linux.
5046 "pardus"
5048 Pardus.
5049 "pldlinux"
5051 PLD Linux.
5052 "redhat-based"
5054 Some Red Hat-derived distro.
5055 "rhel"
5057 Red Hat Enterprise Linux.
5058 "rocky"
5060 Rocky Linux.
5061 "scientificlinux"
5063 Scientific Linux.
5064 "slackware"
5066 Slackware.
5067 "sles"
5069 SuSE Linux Enterprise Server or Desktop.
5070 "suse-based"
5072 Some openSuSE-derived distro.
5073 "ttylinux"
5075 ttylinux.
5076 "ubuntu"
5078 Ubuntu.
5079 "unknown"
5081 The distro could not be determined.
5082 "voidlinux"
5084 Void Linux.
5085 "windows"
5087 Windows does not have distributions. This string is returned if
5088 the OS type is Windows.
5089 Future versions of libguestfs may return other strings here. The
5091 caller should be prepared to handle any string.
5092 Please read "INSPECTION" in guestfs(3) for more details.
5094 inspect-get-drive-mappings
5096 inspect-get-drive-mappings root
5097 This call is useful for Windows which uses a primitive system of
5099 assigning drive letters (like C:\) to partitions. This inspection API
5100 examines the Windows Registry to find out how disks/partitions are
5101 mapped to drive letters, and returns a hash table as in the example
5102 below:
5103 C => /dev/vda2
5105 E => /dev/vdb1
5106 F => /dev/vdc1
5107 Note that keys are drive letters. For Windows, the key is case
5109 insensitive and just contains the drive letter, without the customary
5110 colon separator character.
5111 In future we may support other operating systems that also used drive
5113 letters, but the keys for those might not be case insensitive and might
5114 be longer than 1 character. For example in OS-9, hard drives were
5115 named "h0", "h1" etc.
5116 For Windows guests, currently only hard drive mappings are returned.
5118 Removable disks (eg. DVD-ROMs) are ignored.
5119 For guests that do not use drive mappings, or if the drive mappings
5121 could not be determined, this returns an empty hash table.
5122 Please read "INSPECTION" in guestfs(3) for more details. See also
5124 "inspect-get-mountpoints", "inspect-get-filesystems".
5125 inspect-get-filesystems
5127 inspect-get-filesystems root
5128 This returns a list of all the filesystems that we think are associated
5130 with this operating system. This includes the root filesystem, other
5131 ordinary filesystems, and non-mounted devices like swap partitions.
5132 In the case of a multi-boot virtual machine, it is possible for a
5134 filesystem to be shared between operating systems.
5135 Please read "INSPECTION" in guestfs(3) for more details. See also
5137 "inspect-get-mountpoints".
5138 inspect-get-format
5140 inspect-get-format root
5141 Before libguestfs 1.38, there was some unreliable support for detecting
5143 installer CDs. This API would return:
5144 "installed"
5146 This is an installed operating system.
5147 "installer"
5149 The disk image being inspected is not an installed operating
5150 system, but a bootable install disk, live CD, or similar.
5151 "unknown"
5153 The format of this disk image is not known.
5154 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
5156 directly to detect installer CDs.
5157 Please read "INSPECTION" in guestfs(3) for more details.
5159 This function is deprecated. There is no replacement. Consult the API
5161 documentation in guestfs(3) for further information.
5162 Deprecated functions will not be removed from the API, but the fact
5164 that they are deprecated indicates that there are problems with correct
5165 use of these functions.
5166 inspect-get-hostname
5168 inspect-get-hostname root
5169 This function returns the hostname of the operating system as found by
5171 inspection of the guest’s configuration files.
5172 If the hostname could not be determined, then the string "unknown" is
5174 returned.
5175 Please read "INSPECTION" in guestfs(3) for more details.
5177 inspect-get-icon
5179 inspect-get-icon root [favicon:true|false] [highquality:true|false]
5180 This function returns an icon corresponding to the inspected operating
5182 system. The icon is returned as a buffer containing a PNG image (re-
5183 encoded to PNG if necessary).
5184 If it was not possible to get an icon this function returns a zero-
5186 length (non-NULL) buffer. Callers must check for this case.
5187 Libguestfs will start by looking for a file called /etc/favicon.png or
5189 C:\etc\favicon.png and if it has the correct format, the contents of
5190 this file will be returned. You can disable favicons by passing the
5191 optional "favicon" boolean as false (default is true).
5192 If finding the favicon fails, then we look in other places in the guest
5194 for a suitable icon.
5195 If the optional "highquality" boolean is true then only high quality
5197 icons are returned, which means only icons of high resolution with an
5198 alpha channel. The default (false) is to return any icon we can, even
5199 if it is of substandard quality.
5200 Notes:
5202 • Unlike most other inspection API calls, the guest’s disks must be
5204 mounted up before you call this, since it needs to read information
5205 from the guest filesystem during the call.
5206 • Security: The icon data comes from the untrusted guest, and should
5208 be treated with caution. PNG files have been known to contain
5209 exploits. Ensure that libpng (or other relevant libraries) are
5210 fully up to date before trying to process or display the icon.
5211 • The PNG image returned can be any size. It might not be square.
5213 Libguestfs tries to return the largest, highest quality icon
5214 available. The application must scale the icon to the required
5215 size.
5216 • Extracting icons from Windows guests requires the external
5218 wrestool(1) program from the "icoutils" package, and several
5219 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
5220 package. These must be installed separately.
5221 • Operating system icons are usually trademarks. Seek legal advice
5223 before using trademarks in applications.
5224 This command has one or more optional arguments. See "OPTIONAL
5226 ARGUMENTS".
5227 inspect-get-major-version
5229 inspect-get-major-version root
5230 This returns the major version number of the inspected operating
5232 system.
5233 Windows uses a consistent versioning scheme which is not reflected in
5235 the popular public names used by the operating system. Notably the
5236 operating system known as "Windows 7" is really version 6.1 (ie. major
5237 = 6, minor = 1). You can find out the real versions corresponding to
5238 releases of Windows by consulting Wikipedia or MSDN.
5239 If the version could not be determined, then 0 is returned.
5241 Please read "INSPECTION" in guestfs(3) for more details.
5243 inspect-get-minor-version
5245 inspect-get-minor-version root
5246 This returns the minor version number of the inspected operating
5248 system.
5249 If the version could not be determined, then 0 is returned.
5251 Please read "INSPECTION" in guestfs(3) for more details. See also
5253 "inspect-get-major-version".
5254 inspect-get-mountpoints
5256 inspect-get-mountpoints root
5257 This returns a hash of where we think the filesystems associated with
5259 this operating system should be mounted. Callers should note that this
5260 is at best an educated guess made by reading configuration files such
5261 as /etc/fstab. In particular note that this may return filesystems
5262 which are non-existent or not mountable and callers should be prepared
5263 to handle or ignore failures if they try to mount them.
5264 Each element in the returned hashtable has a key which is the path of
5266 the mountpoint (eg. /boot) and a value which is the filesystem that
5267 would be mounted there (eg. /dev/sda1).
5268 Non-mounted devices such as swap devices are not returned in this list.
5270 For operating systems like Windows which still use drive letters, this
5272 call will only return an entry for the first drive "mounted on" /. For
5273 information about the mapping of drive letters to partitions, see
5274 "inspect-get-drive-mappings".
5275 Please read "INSPECTION" in guestfs(3) for more details. See also
5277 "inspect-get-filesystems".
5278 inspect-get-osinfo
5280 inspect-get-osinfo root
5281 This function returns a possible short ID for libosinfo corresponding
5283 to the guest.
5284 Note: The returned ID is only a guess by libguestfs, and nothing
5286 ensures that it actually exists in osinfo-db.
5287 If no ID could not be determined, then the string "unknown" is
5289 returned.
5290 inspect-get-package-format
5292 inspect-get-package-format root
5293 This function and "inspect-get-package-management" return the package
5295 format and package management tool used by the inspected operating
5296 system. For example for Fedora these functions would return "rpm"
5297 (package format), and "yum" or "dnf" (package management).
5298 This returns the string "unknown" if we could not determine the package
5300 format or if the operating system does not have a real packaging system
5301 (eg. Windows).
5302 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5304 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
5305 other strings.
5306 Please read "INSPECTION" in guestfs(3) for more details.
5308 inspect-get-package-management
5310 inspect-get-package-management root
5311 "inspect-get-package-format" and this function return the package
5313 format and package management tool used by the inspected operating
5314 system. For example for Fedora these functions would return "rpm"
5315 (package format), and "yum" or "dnf" (package management).
5316 This returns the string "unknown" if we could not determine the package
5318 management tool or if the operating system does not have a real
5319 packaging system (eg. Windows).
5320 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
5322 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
5323 "apk", "xbps". Future versions of libguestfs may return other strings.
5324 Please read "INSPECTION" in guestfs(3) for more details.
5326 inspect-get-product-name
5328 inspect-get-product-name root
5329 This returns the product name of the inspected operating system. The
5331 product name is generally some freeform string which can be displayed
5332 to the user, but should not be parsed by programs.
5333 If the product name could not be determined, then the string "unknown"
5335 is returned.
5336 Please read "INSPECTION" in guestfs(3) for more details.
5338 inspect-get-product-variant
5340 inspect-get-product-variant root
5341 This returns the product variant of the inspected operating system.
5343 For Windows guests, this returns the contents of the Registry key
5345 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
5346 which is usually a string such as "Client" or "Server" (other values
5347 are possible). This can be used to distinguish consumer and enterprise
5348 versions of Windows that have the same version number (for example,
5349 Windows 7 and Windows 2008 Server are both version 6.1, but the former
5350 is "Client" and the latter is "Server").
5351 For enterprise Linux guests, in future we intend this to return the
5353 product variant such as "Desktop", "Server" and so on. But this is not
5354 implemented at present.
5355 If the product variant could not be determined, then the string
5357 "unknown" is returned.
5358 Please read "INSPECTION" in guestfs(3) for more details. See also
5360 "inspect-get-product-name", "inspect-get-major-version".
5361 inspect-get-roots
5363 inspect-get-roots
5364 This function is a convenient way to get the list of root devices, as
5366 returned from a previous call to "inspect-os", but without redoing the
5367 whole inspection process.
5368 This returns an empty list if either no root devices were found or the
5370 caller has not called "inspect-os".
5371 Please read "INSPECTION" in guestfs(3) for more details.
5373 inspect-get-type
5375 inspect-get-type root
5376 This returns the type of the inspected operating system. Currently
5378 defined types are:
5379 "linux"
5381 Any Linux-based operating system.
5382 "windows"
5384 Any Microsoft Windows operating system.
5385 "freebsd"
5387 FreeBSD.
5388 "netbsd"
5390 NetBSD.
5391 "openbsd"
5393 OpenBSD.
5394 "hurd"
5396 GNU/Hurd.
5397 "dos"
5399 MS-DOS, FreeDOS and others.
5400 "minix"
5402 MINIX.
5403 "unknown"
5405 The operating system type could not be determined.
5406 Future versions of libguestfs may return other strings here. The
5408 caller should be prepared to handle any string.
5409 Please read "INSPECTION" in guestfs(3) for more details.
5411 inspect-get-windows-current-control-set
5413 inspect-get-windows-current-control-set root
5414 This returns the Windows CurrentControlSet of the inspected guest. The
5416 CurrentControlSet is a registry key name such as "ControlSet001".
5417 This call assumes that the guest is Windows and that the Registry could
5419 be examined by inspection. If this is not the case then an error is
5420 returned.
5421 Please read "INSPECTION" in guestfs(3) for more details.
5423 inspect-get-windows-software-hive
5425 inspect-get-windows-software-hive root
5426 This returns the path to the hive (binary Windows Registry file)
5428 corresponding to HKLM\SOFTWARE.
5429 This call assumes that the guest is Windows and that the guest has a
5431 software hive file with the right name. If this is not the case then
5432 an error is returned. This call does not check that the hive is a
5433 valid Windows Registry hive.
5434 You can use "hivex-open" to read or write to the hive.
5436 Please read "INSPECTION" in guestfs(3) for more details.
5438 inspect-get-windows-system-hive
5440 inspect-get-windows-system-hive root
5441 This returns the path to the hive (binary Windows Registry file)
5443 corresponding to HKLM\SYSTEM.
5444 This call assumes that the guest is Windows and that the guest has a
5446 system hive file with the right name. If this is not the case then an
5447 error is returned. This call does not check that the hive is a valid
5448 Windows Registry hive.
5449 You can use "hivex-open" to read or write to the hive.
5451 Please read "INSPECTION" in guestfs(3) for more details.
5453 inspect-get-windows-systemroot
5455 inspect-get-windows-systemroot root
5456 This returns the Windows systemroot of the inspected guest. The
5458 systemroot is a directory path such as /WINDOWS.
5459 This call assumes that the guest is Windows and that the systemroot
5461 could be determined by inspection. If this is not the case then an
5462 error is returned.
5463 Please read "INSPECTION" in guestfs(3) for more details.
5465 inspect-is-live
5467 inspect-is-live root
5468 This is deprecated and always returns "false".
5470 Please read "INSPECTION" in guestfs(3) for more details.
5472 This function is deprecated. There is no replacement. Consult the API
5474 documentation in guestfs(3) for further information.
5475 Deprecated functions will not be removed from the API, but the fact
5477 that they are deprecated indicates that there are problems with correct
5478 use of these functions.
5479 inspect-is-multipart
5481 inspect-is-multipart root
5482 This is deprecated and always returns "false".
5484 Please read "INSPECTION" in guestfs(3) for more details.
5486 This function is deprecated. There is no replacement. Consult the API
5488 documentation in guestfs(3) for further information.
5489 Deprecated functions will not be removed from the API, but the fact
5491 that they are deprecated indicates that there are problems with correct
5492 use of these functions.
5493 inspect-is-netinst
5495 inspect-is-netinst root
5496 This is deprecated and always returns "false".
5498 Please read "INSPECTION" in guestfs(3) for more details.
5500 This function is deprecated. There is no replacement. Consult the API
5502 documentation in guestfs(3) for further information.
5503 Deprecated functions will not be removed from the API, but the fact
5505 that they are deprecated indicates that there are problems with correct
5506 use of these functions.
5507 inspect-list-applications
5509 inspect-list-applications root
5510 Return the list of applications installed in the operating system.
5512 Note: This call works differently from other parts of the inspection
5514 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5515 then mount up the disks, before calling this. Listing applications is
5516 a significantly more difficult operation which requires access to the
5517 full filesystem. Also note that unlike the other "inspect-get-*" calls
5518 which are just returning data cached in the libguestfs handle, this
5519 call actually reads parts of the mounted filesystems during the call.
5520 This returns an empty list if the inspection code was not able to
5522 determine the list of applications.
5523 The application structure contains the following fields:
5525 "app_name"
5527 The name of the application. For Linux guests, this is the package
5528 name.
5529 "app_display_name"
5531 The display name of the application, sometimes localized to the
5532 install language of the guest operating system.
5533 If unavailable this is returned as an empty string "". Callers
5535 needing to display something can use "app_name" instead.
5536 "app_epoch"
5538 For package managers which use epochs, this contains the epoch of
5539 the package (an integer). If unavailable, this is returned as 0.
5540 "app_version"
5542 The version string of the application or package. If unavailable
5543 this is returned as an empty string "".
5544 "app_release"
5546 The release string of the application or package, for package
5547 managers that use this. If unavailable this is returned as an
5548 empty string "".
5549 "app_install_path"
5551 The installation path of the application (on operating systems such
5552 as Windows which use installation paths). This path is in the
5553 format used by the guest operating system, it is not a libguestfs
5554 path.
5555 If unavailable this is returned as an empty string "".
5557 "app_trans_path"
5559 The install path translated into a libguestfs path. If unavailable
5560 this is returned as an empty string "".
5561 "app_publisher"
5563 The name of the publisher of the application, for package managers
5564 that use this. If unavailable this is returned as an empty string
5565 "".
5566 "app_url"
5568 The URL (eg. upstream URL) of the application. If unavailable this
5569 is returned as an empty string "".
5570 "app_source_package"
5572 For packaging systems which support this, the name of the source
5573 package. If unavailable this is returned as an empty string "".
5574 "app_summary"
5576 A short (usually one line) description of the application or
5577 package. If unavailable this is returned as an empty string "".
5578 "app_description"
5580 A longer description of the application or package. If unavailable
5581 this is returned as an empty string "".
5582 Please read "INSPECTION" in guestfs(3) for more details.
5584 This function is deprecated. In new code, use the
5586 "inspect-list-applications2" call instead.
5587 Deprecated functions will not be removed from the API, but the fact
5589 that they are deprecated indicates that there are problems with correct
5590 use of these functions.
5591 inspect-list-applications2
5593 inspect-list-applications2 root
5594 Return the list of applications installed in the operating system.
5596 Note: This call works differently from other parts of the inspection
5598 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5599 then mount up the disks, before calling this. Listing applications is
5600 a significantly more difficult operation which requires access to the
5601 full filesystem. Also note that unlike the other "inspect-get-*" calls
5602 which are just returning data cached in the libguestfs handle, this
5603 call actually reads parts of the mounted filesystems during the call.
5604 This returns an empty list if the inspection code was not able to
5606 determine the list of applications.
5607 The application structure contains the following fields:
5609 "app2_name"
5611 The name of the application. For Linux guests, this is the package
5612 name.
5613 "app2_display_name"
5615 The display name of the application, sometimes localized to the
5616 install language of the guest operating system.
5617 If unavailable this is returned as an empty string "". Callers
5619 needing to display something can use "app2_name" instead.
5620 "app2_epoch"
5622 For package managers which use epochs, this contains the epoch of
5623 the package (an integer). If unavailable, this is returned as 0.
5624 "app2_version"
5626 The version string of the application or package. If unavailable
5627 this is returned as an empty string "".
5628 "app2_release"
5630 The release string of the application or package, for package
5631 managers that use this. If unavailable this is returned as an
5632 empty string "".
5633 "app2_arch"
5635 The architecture string of the application or package, for package
5636 managers that use this. If unavailable this is returned as an
5637 empty string "".
5638 "app2_install_path"
5640 The installation path of the application (on operating systems such
5641 as Windows which use installation paths). This path is in the
5642 format used by the guest operating system, it is not a libguestfs
5643 path.
5644 If unavailable this is returned as an empty string "".
5646 "app2_trans_path"
5648 The install path translated into a libguestfs path. If unavailable
5649 this is returned as an empty string "".
5650 "app2_publisher"
5652 The name of the publisher of the application, for package managers
5653 that use this. If unavailable this is returned as an empty string
5654 "".
5655 "app2_url"
5657 The URL (eg. upstream URL) of the application. If unavailable this
5658 is returned as an empty string "".
5659 "app2_source_package"
5661 For packaging systems which support this, the name of the source
5662 package. If unavailable this is returned as an empty string "".
5663 "app2_summary"
5665 A short (usually one line) description of the application or
5666 package. If unavailable this is returned as an empty string "".
5667 "app2_description"
5669 A longer description of the application or package. If unavailable
5670 this is returned as an empty string "".
5671 Please read "INSPECTION" in guestfs(3) for more details.
5673 inspect-os
5675 inspect-os
5676 This function uses other libguestfs functions and certain heuristics to
5678 inspect the disk(s) (usually disks belonging to a virtual machine),
5679 looking for operating systems.
5680 The list returned is empty if no operating systems were found.
5682 If one operating system was found, then this returns a list with a
5684 single element, which is the name of the root filesystem of this
5685 operating system. It is also possible for this function to return a
5686 list containing more than one element, indicating a dual-boot or multi-
5687 boot virtual machine, with each element being the root filesystem of
5688 one of the operating systems.
5689 You can pass the root string(s) returned to other "inspect-get-*"
5691 functions in order to query further information about each operating
5692 system, such as the name and version.
5693 This function uses other libguestfs features such as "mount-ro" and
5695 "umount-all" in order to mount and unmount filesystems and look at the
5696 contents. This should be called with no disks currently mounted. The
5697 function may also use Augeas, so any existing Augeas handle will be
5698 closed.
5699 This function cannot decrypt encrypted disks. The caller must do that
5701 first (supplying the necessary keys) if the disk is encrypted.
5702 Please read "INSPECTION" in guestfs(3) for more details.
5704 See also "list-filesystems".
5706 is-blockdev
5708 is-blockdev-opts
5709 is-blockdev path [followsymlinks:true|false]
5710 This returns "true" if and only if there is a block device with the
5712 given "path" name.
5713 If the optional flag "followsymlinks" is true, then a symlink (or chain
5715 of symlinks) that ends with a block device also causes the function to
5716 return true.
5717 This call only looks at files within the guest filesystem. Libguestfs
5719 partitions and block devices (eg. /dev/sda) cannot be used as the
5720 "path" parameter of this call.
5721 See also "stat".
5723 This command has one or more optional arguments. See "OPTIONAL
5725 ARGUMENTS".
5726 is-chardev
5728 is-chardev-opts
5729 is-chardev path [followsymlinks:true|false]
5730 This returns "true" if and only if there is a character device with the
5732 given "path" name.
5733 If the optional flag "followsymlinks" is true, then a symlink (or chain
5735 of symlinks) that ends with a chardev also causes the function to
5736 return true.
5737 See also "stat".
5739 This command has one or more optional arguments. See "OPTIONAL
5741 ARGUMENTS".
5742 is-config
5744 is-config
5745 This returns true iff this handle is being configured (in the "CONFIG"
5747 state).
5748 For more information on states, see guestfs(3).
5750 is-dir
5752 is-dir-opts
5753 is-dir path [followsymlinks:true|false]
5754 This returns "true" if and only if there is a directory with the given
5756 "path" name. Note that it returns false for other objects like files.
5757 If the optional flag "followsymlinks" is true, then a symlink (or chain
5759 of symlinks) that ends with a directory also causes the function to
5760 return true.
5761 See also "stat".
5763 This command has one or more optional arguments. See "OPTIONAL
5765 ARGUMENTS".
5766 is-fifo
5768 is-fifo-opts
5769 is-fifo path [followsymlinks:true|false]
5770 This returns "true" if and only if there is a FIFO (named pipe) with
5772 the given "path" name.
5773 If the optional flag "followsymlinks" is true, then a symlink (or chain
5775 of symlinks) that ends with a FIFO also causes the function to return
5776 true.
5777 See also "stat".
5779 This command has one or more optional arguments. See "OPTIONAL
5781 ARGUMENTS".
5782 is-file
5784 is-file-opts
5785 is-file path [followsymlinks:true|false]
5786 This returns "true" if and only if there is a regular file with the
5788 given "path" name. Note that it returns false for other objects like
5789 directories.
5790 If the optional flag "followsymlinks" is true, then a symlink (or chain
5792 of symlinks) that ends with a file also causes the function to return
5793 true.
5794 See also "stat".
5796 This command has one or more optional arguments. See "OPTIONAL
5798 ARGUMENTS".
5799 is-lv
5801 is-lv mountable
5802 This command tests whether "mountable" is a logical volume, and returns
5804 true iff this is the case.
5805 is-socket
5807 is-socket-opts
5808 is-socket path [followsymlinks:true|false]
5809 This returns "true" if and only if there is a Unix domain socket with
5811 the given "path" name.
5812 If the optional flag "followsymlinks" is true, then a symlink (or chain
5814 of symlinks) that ends with a socket also causes the function to return
5815 true.
5816 See also "stat".
5818 This command has one or more optional arguments. See "OPTIONAL
5820 ARGUMENTS".
5821 is-symlink
5823 is-symlink path
5824 This returns "true" if and only if there is a symbolic link with the
5826 given "path" name.
5827 See also "stat".
5829 is-whole-device
5831 is-whole-device device
5832 This returns "true" if and only if "device" refers to a whole block
5834 device. That is, not a partition or a logical device.
5835 is-zero
5837 is-zero path
5838 This returns true iff the file exists and the file is empty or it
5840 contains all zero bytes.
5841 is-zero-device
5843 is-zero-device device
5844 This returns true iff the device exists and contains all zero bytes.
5846 Note that for large devices this can take a long time to run.
5848 isoinfo
5850 isoinfo isofile
5851 This is the same as "isoinfo-device" except that it works for an ISO
5853 file located inside some other mounted filesystem. Note that in the
5854 common case where you have added an ISO file as a libguestfs device,
5855 you would not call this. Instead you would call "isoinfo-device".
5856 isoinfo-device
5858 isoinfo-device device
5859 "device" is an ISO device. This returns a struct of information read
5861 from the primary volume descriptor (the ISO equivalent of the
5862 superblock) of the device.
5863 Usually it is more efficient to use the isoinfo(1) command with the -d
5865 option on the host to analyze ISO files, instead of going through
5866 libguestfs.
5867 For information on the primary volume descriptor fields, see
5869 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
5870 journal-close
5872 journal-close
5873 Close the journal handle.
5875 This command depends on the feature "journal". See also "feature-
5877 available".
5878 journal-get
5880 journal-get
5881 Read the current journal entry. This returns all the fields in the
5883 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
5884 field name (a string).
5885 The "attrval" is the field value (a binary blob, often but not always a
5887 string). Please note that "attrval" is a byte array, not a
5888 \0-terminated C string.
5889 The length of data may be truncated to the data threshold (see:
5891 "journal-set-data-threshold", "journal-get-data-threshold").
5892 If you set the data threshold to unlimited (0) then this call can read
5894 a journal entry of any size, ie. it is not limited by the libguestfs
5895 protocol.
5896 This command depends on the feature "journal". See also "feature-
5898 available".
5899 journal-get-data-threshold
5901 journal-get-data-threshold
5902 Get the current data threshold for reading journal entries. This is a
5904 hint to the journal that it may truncate data fields to this size when
5905 reading them (note also that it may not truncate them). If this
5906 returns 0, then the threshold is unlimited.
5907 See also "journal-set-data-threshold".
5909 This command depends on the feature "journal". See also "feature-
5911 available".
5912 journal-get-realtime-usec
5914 journal-get-realtime-usec
5915 Get the realtime (wallclock) timestamp of the current journal entry.
5917 This command depends on the feature "journal". See also "feature-
5919 available".
5920 journal-next
5922 journal-next
5923 Move to the next journal entry. You have to call this at least once
5925 after opening the handle before you are able to read data.
5926 The returned boolean tells you if there are any more journal records to
5928 read. "true" means you can read the next record (eg. using "journal-
5929 get"), and "false" means you have reached the end of the journal.
5930 This command depends on the feature "journal". See also "feature-
5932 available".
5933 journal-open
5935 journal-open directory
5936 Open the systemd journal located in directory. Any previously opened
5938 journal handle is closed.
5939 The contents of the journal can be read using "journal-next" and
5941 "journal-get".
5942 After you have finished using the journal, you should close the handle
5944 by calling "journal-close".
5945 This command depends on the feature "journal". See also "feature-
5947 available".
5948 journal-set-data-threshold
5950 journal-set-data-threshold threshold
5951 Set the data threshold for reading journal entries. This is a hint to
5953 the journal that it may truncate data fields to this size when reading
5954 them (note also that it may not truncate them). If you set this to 0,
5955 then the threshold is unlimited.
5956 See also "journal-get-data-threshold".
5958 This command depends on the feature "journal". See also "feature-
5960 available".
5961 journal-skip
5963 journal-skip skip
5964 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
5966 The number of entries actually skipped is returned (note "rskip ≥ 0").
5968 If this is not the same as the absolute value of the skip parameter
5969 ("|skip|") you passed in then it means you have reached the end or the
5970 start of the journal.
5971 This command depends on the feature "journal". See also "feature-
5973 available".
5974 kill-subprocess
5976 kill-subprocess
5977 This kills the hypervisor.
5979 Do not call this. See: "shutdown" instead.
5981 This function is deprecated. In new code, use the "shutdown" call
5983 instead.
5984 Deprecated functions will not be removed from the API, but the fact
5986 that they are deprecated indicates that there are problems with correct
5987 use of these functions.
5988 launch
5990 run
5991 launch
5992 You should call this after configuring the handle (eg. adding drives)
5994 but before performing any actions.
5995 Do not call "launch" twice on the same handle. Although it will not
5997 give an error (for historical reasons), the precise behaviour when you
5998 do this is not well defined. Handles are very cheap to create, so
5999 create a new one for each launch.
6000 lchown
6002 lchown owner group path
6003 Change the file owner to "owner" and group to "group". This is like
6005 "chown" but if "path" is a symlink then the link itself is changed, not
6006 the target.
6007 Only numeric uid and gid are supported. If you want to use names, you
6009 will need to locate and parse the password file yourself (Augeas
6010 support makes this relatively easy).
6011 ldmtool-create-all
6013 ldmtool-create-all
6014 This function scans all block devices looking for Windows dynamic disk
6016 volumes and partitions, and creates devices for any that were found.
6017 Call "list-ldm-volumes" and "list-ldm-partitions" to return all
6019 devices.
6020 Note that you don't normally need to call this explicitly, since it is
6022 done automatically at "launch" time.
6023 This command depends on the feature "ldm". See also "feature-
6025 available".
6026 ldmtool-diskgroup-disks
6028 ldmtool-diskgroup-disks diskgroup
6029 Return the disks in a Windows dynamic disk group. The "diskgroup"
6031 parameter should be the GUID of a disk group, one element from the list
6032 returned by "ldmtool-scan".
6033 This command depends on the feature "ldm". See also "feature-
6035 available".
6036 ldmtool-diskgroup-name
6038 ldmtool-diskgroup-name diskgroup
6039 Return the name of 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-volumes
6048 ldmtool-diskgroup-volumes diskgroup
6049 Return the volumes in 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-remove-all
6058 ldmtool-remove-all
6059 This is essentially the opposite of "ldmtool-create-all". It removes
6061 the device mapper mappings for all Windows dynamic disk volumes
6062 This command depends on the feature "ldm". See also "feature-
6064 available".
6065 ldmtool-scan
6067 ldmtool-scan
6068 This function scans for Windows dynamic disks. It returns a list of
6070 identifiers (GUIDs) for all disk groups that were found. These
6071 identifiers can be passed to other "ldmtool-*" functions.
6072 This function scans all block devices. To scan a subset of block
6074 devices, call "ldmtool-scan-devices" instead.
6075 This command depends on the feature "ldm". See also "feature-
6077 available".
6078 ldmtool-scan-devices
6080 ldmtool-scan-devices 'devices ...'
6081 This function scans for Windows dynamic disks. It returns a list of
6083 identifiers (GUIDs) for all disk groups that were found. These
6084 identifiers can be passed to other "ldmtool-*" functions.
6085 The parameter "devices" is a list of block devices which are scanned.
6087 If this list is empty, all block devices are scanned.
6088 This command depends on the feature "ldm". See also "feature-
6090 available".
6091 ldmtool-volume-hint
6093 ldmtool-volume-hint diskgroup volume
6094 Return the hint field of the volume named "volume" in the disk group
6096 with GUID "diskgroup". This may not be defined, in which case the
6097 empty string is returned. The hint field is often, though not always,
6098 the name of a Windows drive, eg. "E:".
6099 This command depends on the feature "ldm". See also "feature-
6101 available".
6102 ldmtool-volume-partitions
6104 ldmtool-volume-partitions diskgroup volume
6105 Return the list of partitions in the volume named "volume" in the disk
6107 group with GUID "diskgroup".
6108 This command depends on the feature "ldm". See also "feature-
6110 available".
6111 ldmtool-volume-type
6113 ldmtool-volume-type diskgroup volume
6114 Return the type of the volume named "volume" in the disk group with
6116 GUID "diskgroup".
6117 Possible volume types that can be returned here include: "simple",
6119 "spanned", "striped", "mirrored", "raid5". Other types may also be
6120 returned.
6121 This command depends on the feature "ldm". See also "feature-
6123 available".
6124 lgetxattr
6126 lgetxattr path name
6127 Get a single extended attribute from file "path" named "name". If
6129 "path" is a symlink, then this call returns an extended attribute from
6130 the symlink.
6131 Normally it is better to get all extended attributes from a file in one
6133 go by calling "getxattrs". However some Linux filesystem
6134 implementations are buggy and do not provide a way to list out
6135 attributes. For these filesystems (notably ntfs-3g) you have to know
6136 the names of the extended attributes you want in advance and call this
6137 function.
6138 Extended attribute values are blobs of binary data. If there is no
6140 extended attribute named "name", this returns an error.
6141 See also: "lgetxattrs", "getxattr", attr(5).
6143 This command depends on the feature "linuxxattrs". See also "feature-
6145 available".
6146 lgetxattrs
6148 lgetxattrs path
6149 This is the same as "getxattrs", but if "path" is a symbolic link, then
6151 it returns the extended attributes of the link itself.
6152 This command depends on the feature "linuxxattrs". See also "feature-
6154 available".
6155 list-9p
6157 list-9p
6158 This call does nothing and returns an error.
6160 This function is deprecated. There is no replacement. Consult the API
6162 documentation in guestfs(3) for further information.
6163 Deprecated functions will not be removed from the API, but the fact
6165 that they are deprecated indicates that there are problems with correct
6166 use of these functions.
6167 list-devices
6169 list-devices
6170 List all the block devices.
6172 The full block device names are returned, eg. /dev/sda.
6174 See also "list-filesystems".
6176 list-disk-labels
6178 list-disk-labels
6179 If you add drives using the optional "label" parameter of "add-drive-
6181 opts", you can use this call to map between disk labels, and raw block
6182 device and partition names (like /dev/sda and /dev/sda1).
6183 This returns a hashtable, where keys are the disk labels (without the
6185 /dev/disk/guestfs prefix), and the values are the full raw block device
6186 and partition names (eg. /dev/sda and /dev/sda1).
6187 list-dm-devices
6189 list-dm-devices
6190 List all device mapper devices.
6192 The returned list contains /dev/mapper/* devices, eg. ones created by a
6194 previous call to "luks-open".
6195 Device mapper devices which correspond to logical volumes are not
6197 returned in this list. Call "lvs" if you want to list logical volumes.
6198 list-filesystems
6200 list-filesystems
6201 This inspection command looks for filesystems on partitions, block
6203 devices and logical volumes, returning a list of "mountables"
6204 containing filesystems and their type.
6205 The return value is a hash, where the keys are the devices containing
6207 filesystems, and the values are the filesystem types. For example:
6208 "/dev/sda1" => "ntfs"
6210 "/dev/sda2" => "ext2"
6211 "/dev/vg_guest/lv_root" => "ext4"
6212 "/dev/vg_guest/lv_swap" => "swap"
6213 The key is not necessarily a block device. It may also be an opaque
6215 ‘mountable’ string which can be passed to "mount".
6216 The value can have the special value "unknown", meaning the content of
6218 the device is undetermined or empty. "swap" means a Linux swap
6219 partition.
6220 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
6222 might have included "mount" and "umount", and therefore you had to use
6223 this soon after launch and only when nothing else was mounted. This
6224 restriction is removed in libguestfs ≥ 1.38.
6225 Not all of the filesystems returned will be mountable. In particular,
6227 swap partitions are returned in the list. Also this command does not
6228 check that each filesystem found is valid and mountable, and some
6229 filesystems might be mountable but require special options.
6230 Filesystems may not all belong to a single logical operating system
6231 (use "inspect-os" to look for OSes).
6232 list-ldm-partitions
6234 list-ldm-partitions
6235 This function returns all Windows dynamic disk partitions that were
6237 found at launch time. It returns a list of device names.
6238 This command depends on the feature "ldm". See also "feature-
6240 available".
6241 list-ldm-volumes
6243 list-ldm-volumes
6244 This function returns all Windows dynamic disk volumes that were found
6246 at launch time. It returns a list of device names.
6247 This command depends on the feature "ldm". See also "feature-
6249 available".
6250 list-md-devices
6252 list-md-devices
6253 List all Linux md devices.
6255 list-partitions
6257 list-partitions
6258 List all the partitions detected on all block devices.
6260 The full partition device names are returned, eg. /dev/sda1
6262 This does not return logical volumes. For that you will need to call
6264 "lvs".
6265 See also "list-filesystems".
6267 ll
6269 ll directory
6270 List the files in directory (relative to the root directory, there is
6272 no cwd) in the format of "ls -la".
6273 This command is mostly useful for interactive sessions. It is not
6275 intended that you try to parse the output string.
6276 llz
6278 llz directory
6279 List the files in directory in the format of "ls -laZ".
6281 This command is mostly useful for interactive sessions. It is not
6283 intended that you try to parse the output string.
6284 This function is deprecated. In new code, use the "lgetxattrs" call
6286 instead.
6287 Deprecated functions will not be removed from the API, but the fact
6289 that they are deprecated indicates that there are problems with correct
6290 use of these functions.
6291 ln
6293 ln target linkname
6294 This command creates a hard link.
6296 ln-f
6298 ln-f target linkname
6299 This command creates a hard link, removing the link "linkname" if it
6301 exists already.
6302 ln-s
6304 ln-s target linkname
6305 This command creates a symbolic link using the "ln -s" command.
6307 ln-sf
6309 ln-sf target linkname
6310 This command creates a symbolic link using the "ln -sf" command, The -f
6312 option removes the link ("linkname") if it exists already.
6313 lremovexattr
6315 lremovexattr xattr path
6316 This is the same as "removexattr", but if "path" is a symbolic link,
6318 then it removes an extended attribute of the link itself.
6319 This command depends on the feature "linuxxattrs". See also "feature-
6321 available".
6322 ls
6324 ls directory
6325 List the files in directory (relative to the root directory, there is
6327 no cwd). The "." and ".." entries are not returned, but hidden files
6328 are shown.
6329 ls0
6331 ls0 dir (filenames|-)
6332 This specialized command is used to get a listing of the filenames in
6334 the directory "dir". The list of filenames is written to the local
6335 file filenames (on the host).
6336 In the output file, the filenames are separated by "\0" characters.
6338 "." and ".." are not returned. The filenames are not sorted.
6340 Use "-" instead of a filename to read/write from stdin/stdout.
6342 lsetxattr
6344 lsetxattr xattr val vallen path
6345 This is the same as "setxattr", but if "path" is a symbolic link, then
6347 it sets an extended attribute of the link itself.
6348 This command depends on the feature "linuxxattrs". See also "feature-
6350 available".
6351 lstat
6353 lstat path
6354 Returns file information for the given "path".
6356 This is the same as "stat" except that if "path" is a symbolic link,
6358 then the link is stat-ed, not the file it refers to.
6359 This is the same as the lstat(2) system call.
6361 This function is deprecated. In new code, use the "lstatns" call
6363 instead.
6364 Deprecated functions will not be removed from the API, but the fact
6366 that they are deprecated indicates that there are problems with correct
6367 use of these functions.
6368 lstatlist
6370 lstatlist path 'names ...'
6371 This call allows you to perform the "lstat" operation on multiple
6373 files, where all files are in the directory "path". "names" is the
6374 list of files from this directory.
6375 On return you get a list of stat structs, with a one-to-one
6377 correspondence to the "names" list. If any name did not exist or could
6378 not be lstat'd, then the "st_ino" field of that structure is set to
6379 "-1".
6380 This call is intended for programs that want to efficiently list a
6382 directory contents without making many round-trips. See also
6383 "lxattrlist" for a similarly efficient call for getting extended
6384 attributes.
6385 This function is deprecated. In new code, use the "lstatnslist" call
6387 instead.
6388 Deprecated functions will not be removed from the API, but the fact
6390 that they are deprecated indicates that there are problems with correct
6391 use of these functions.
6392 lstatns
6394 lstatns path
6395 Returns file information for the given "path".
6397 This is the same as "statns" except that if "path" is a symbolic link,
6399 then the link is stat-ed, not the file it refers to.
6400 This is the same as the lstat(2) system call.
6402 lstatnslist
6404 lstatnslist path 'names ...'
6405 This call allows you to perform the "lstatns" operation on multiple
6407 files, where all files are in the directory "path". "names" is the
6408 list of files from this directory.
6409 On return you get a list of stat structs, with a one-to-one
6411 correspondence to the "names" list. If any name did not exist or could
6412 not be lstat'd, then the "st_ino" field of that structure is set to
6413 "-1".
6414 This call is intended for programs that want to efficiently list a
6416 directory contents without making many round-trips. See also
6417 "lxattrlist" for a similarly efficient call for getting extended
6418 attributes.
6419 luks-add-key
6421 luks-add-key device keyslot
6422 This command adds a new key on LUKS device "device". "key" is any
6424 existing key, and is used to access the device. "newkey" is the new
6425 key to add. "keyslot" is the key slot that will be replaced.
6426 Note that if "keyslot" already contains a key, then this command will
6428 fail. You have to use "luks-kill-slot" first to remove that key.
6429 This command has one or more key or passphrase parameters. Guestfish
6431 will prompt for these separately.
6432 This command depends on the feature "luks". See also "feature-
6434 available".
6435 luks-close
6437 luks-close device
6438 This closes a LUKS device that was created earlier by "luks-open" or
6440 "luks-open-ro". The "device" parameter must be the name of the LUKS
6441 mapping device (ie. /dev/mapper/mapname) and not the name of the
6442 underlying block device.
6443 This function is deprecated. In new code, use the "cryptsetup-close"
6445 call instead.
6446 Deprecated functions will not be removed from the API, but the fact
6448 that they are deprecated indicates that there are problems with correct
6449 use of these functions.
6450 This command depends on the feature "luks". See also "feature-
6452 available".
6453 luks-format
6455 luks-format device keyslot
6456 This command erases existing data on "device" and formats the device as
6458 a LUKS encrypted device. "key" is the initial key, which is added to
6459 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
6460 This command has one or more key or passphrase parameters. Guestfish
6462 will prompt for these separately.
6463 This command depends on the feature "luks". See also "feature-
6465 available".
6466 luks-format-cipher
6468 luks-format-cipher device keyslot cipher
6469 This command is the same as "luks-format" but it also allows you to set
6471 the "cipher" used.
6472 This command has one or more key or passphrase parameters. Guestfish
6474 will prompt for these separately.
6475 This command depends on the feature "luks". See also "feature-
6477 available".
6478 luks-kill-slot
6480 luks-kill-slot device keyslot
6481 This command deletes the key in key slot "keyslot" from the encrypted
6483 LUKS device "device". "key" must be one of the other keys.
6484 This command has one or more key or passphrase parameters. Guestfish
6486 will prompt for these separately.
6487 This command depends on the feature "luks". See also "feature-
6489 available".
6490 luks-open
6492 luks-open device mapname
6493 This command opens a block device which has been encrypted according to
6495 the Linux Unified Key Setup (LUKS) standard.
6496 "device" is the encrypted block device or partition.
6498 The caller must supply one of the keys associated with the LUKS block
6500 device, in the "key" parameter.
6501 This creates a new block device called /dev/mapper/mapname. Reads and
6503 writes to this block device are decrypted from and encrypted to the
6504 underlying "device" respectively.
6505 If this block device contains LVM volume groups, then calling "lvm-
6507 scan" with the "activate" parameter "true" will make them visible.
6508 Use "list-dm-devices" to list all device mapper devices.
6510 This command has one or more key or passphrase parameters. Guestfish
6512 will prompt for these separately.
6513 This function is deprecated. In new code, use the "cryptsetup-open"
6515 call instead.
6516 Deprecated functions will not be removed from the API, but the fact
6518 that they are deprecated indicates that there are problems with correct
6519 use of these functions.
6520 This command depends on the feature "luks". See also "feature-
6522 available".
6523 luks-open-ro
6525 luks-open-ro device mapname
6526 This is the same as "luks-open" except that a read-only mapping is
6528 created.
6529 This command has one or more key or passphrase parameters. Guestfish
6531 will prompt for these separately.
6532 This function is deprecated. In new code, use the "cryptsetup-open"
6534 call instead.
6535 Deprecated functions will not be removed from the API, but the fact
6537 that they are deprecated indicates that there are problems with correct
6538 use of these functions.
6539 This command depends on the feature "luks". See also "feature-
6541 available".
6542 luks-uuid
6544 luks-uuid device
6545 This returns the UUID of the LUKS device "device".
6547 This command depends on the feature "luks". See also "feature-
6549 available".
6550 lvcreate
6552 lvcreate logvol volgroup mbytes
6553 This creates an LVM logical volume called "logvol" on the volume group
6555 "volgroup", with "size" megabytes.
6556 This command depends on the feature "lvm2". See also "feature-
6558 available".
6559 lvcreate-free
6561 lvcreate-free logvol volgroup percent
6562 Create an LVM logical volume called /dev/volgroup/logvol, using
6564 approximately "percent" % of the free space remaining in the volume
6565 group. Most usefully, when "percent" is 100 this will create the
6566 largest possible LV.
6567 This command depends on the feature "lvm2". See also "feature-
6569 available".
6570 lvm-canonical-lv-name
6572 lvm-canonical-lv-name lvname
6573 This converts alternative naming schemes for LVs that you might find to
6575 the canonical name. For example, /dev/mapper/VG-LV is converted to
6576 /dev/VG/LV.
6577 This command returns an error if the "lvname" parameter does not refer
6579 to a logical volume. In this case errno will be set to "EINVAL".
6580 See also "is-lv", "canonical-device-name".
6582 lvm-clear-filter
6584 lvm-clear-filter
6585 This undoes the effect of "lvm-set-filter". LVM will be able to see
6587 every block device.
6588 This command also clears the LVM cache and performs a volume group
6590 scan.
6591 lvm-remove-all
6593 lvm-remove-all
6594 This command removes all LVM logical volumes, volume groups and
6596 physical volumes.
6597 This command depends on the feature "lvm2". See also "feature-
6599 available".
6600 lvm-scan
6602 lvm-scan true|false
6603 This scans all block devices and rebuilds the list of LVM physical
6605 volumes, volume groups and logical volumes.
6606 If the "activate" parameter is "true" then newly found volume groups
6608 and logical volumes are activated, meaning the LV /dev/VG/LV devices
6609 become visible.
6610 When a libguestfs handle is launched it scans for existing devices, so
6612 you do not normally need to use this API. However it is useful when
6613 you have added a new device or deleted an existing device (such as when
6614 the "luks-open" API is used).
6615 lvm-set-filter
6617 lvm-set-filter 'devices ...'
6618 This sets the LVM device filter so that LVM will only be able to "see"
6620 the block devices in the list "devices", and will ignore all other
6621 attached block devices.
6622 Where disk image(s) contain duplicate PVs or VGs, this command is
6624 useful to get LVM to ignore the duplicates, otherwise LVM can get
6625 confused. Note also there are two types of duplication possible:
6626 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
6627 cloned but just happen to have the same name. In normal operation you
6628 cannot create this situation, but you can do it outside LVM, eg. by
6629 cloning disk images or by bit twiddling inside the LVM metadata.
6630 This command also clears the LVM cache and performs a volume group
6632 scan.
6633 You can filter whole block devices or individual partitions.
6635 You cannot use this if any VG is currently in use (eg. contains a
6637 mounted filesystem), even if you are not filtering out that VG.
6638 This command depends on the feature "lvm2". See also "feature-
6640 available".
6641 lvremove
6643 lvremove device
6644 Remove an LVM logical volume "device", where "device" is the path to
6646 the LV, such as /dev/VG/LV.
6647 You can also remove all LVs in a volume group by specifying the VG
6649 name, /dev/VG.
6650 This command depends on the feature "lvm2". See also "feature-
6652 available".
6653 lvrename
6655 lvrename logvol newlogvol
6656 Rename a logical volume "logvol" with the new name "newlogvol".
6658 lvresize
6660 lvresize device mbytes
6661 This resizes (expands or shrinks) an existing LVM logical volume to
6663 "mbytes". When reducing, data in the reduced part is lost.
6664 This command depends on the feature "lvm2". See also "feature-
6666 available".
6667 lvresize-free
6669 lvresize-free lv percent
6670 This expands an existing logical volume "lv" so that it fills "pc" % of
6672 the remaining free space in the volume group. Commonly you would call
6673 this with pc = 100 which expands the logical volume as much as
6674 possible, using all remaining free space in the volume group.
6675 This command depends on the feature "lvm2". See also "feature-
6677 available".
6678 lvs
6680 lvs
6681 List all the logical volumes detected. This is the equivalent of the
6683 lvs(8) command.
6684 This returns a list of the logical volume device names (eg.
6686 /dev/VolGroup00/LogVol00).
6687 See also "lvs-full", "list-filesystems".
6689 This command depends on the feature "lvm2". See also "feature-
6691 available".
6692 lvs-full
6694 lvs-full
6695 List all the logical volumes detected. This is the equivalent of the
6697 lvs(8) command. The "full" version includes all fields.
6698 This command depends on the feature "lvm2". See also "feature-
6700 available".
6701 lvuuid
6703 lvuuid device
6704 This command returns the UUID of the LVM LV "device".
6706 lxattrlist
6708 lxattrlist path 'names ...'
6709 This call allows you to get the extended attributes of multiple files,
6711 where all files are in the directory "path". "names" is the list of
6712 files from this directory.
6713 On return you get a flat list of xattr structs which must be
6715 interpreted sequentially. The first xattr struct always has a zero-
6716 length "attrname". "attrval" in this struct is zero-length to indicate
6717 there was an error doing "lgetxattr" for this file, or is a C string
6718 which is a decimal number (the number of following attributes for this
6719 file, which could be "0"). Then after the first xattr struct are the
6720 zero or more attributes for the first named file. This repeats for the
6721 second and subsequent files.
6722 This call is intended for programs that want to efficiently list a
6724 directory contents without making many round-trips. See also
6725 "lstatlist" for a similarly efficient call for getting standard stats.
6726 This command depends on the feature "linuxxattrs". See also "feature-
6728 available".
6729 max-disks
6731 max-disks
6732 Return the maximum number of disks that may be added to a handle (eg.
6734 by "add-drive-opts" and similar calls).
6735 This function was added in libguestfs 1.19.7. In previous versions of
6737 libguestfs the limit was 25.
6738 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
6740 on this topic.
6741 md-create
6743 md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
6744 Create a Linux md (RAID) device named "name" on the devices in the list
6746 "devices".
6747 The optional parameters are:
6749 "missingbitmap"
6751 A bitmap of missing devices. If a bit is set it means that a
6752 missing device is added to the array. The least significant bit
6753 corresponds to the first device in the array.
6754 As examples:
6756 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
6758 resulting array would be "[<missing>, "/dev/sda"]".
6759 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
6761 resulting array would be "["/dev/sda", <missing>]".
6762 This defaults to 0 (no missing devices).
6764 The length of "devices" + the number of bits set in "missingbitmap"
6766 must equal "nrdevices" + "spare".
6767 "nrdevices"
6769 The number of active RAID devices.
6770 If not set, this defaults to the length of "devices" plus the
6772 number of bits set in "missingbitmap".
6773 "spare"
6775 The number of spare devices.
6776 If not set, this defaults to 0.
6778 "chunk"
6780 The chunk size in bytes.
6781 The "chunk" parameter does not make sense, and should not be
6783 specified, when "level" is "raid1" (which is the default; see
6784 below).
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 This call does nothing and returns an error.
7334 This command has one or more optional arguments. See "OPTIONAL
7336 ARGUMENTS".
7337 This function is deprecated. There is no replacement. Consult the API
7339 documentation in guestfs(3) for further information.
7340 Deprecated functions will not be removed from the API, but the fact
7342 that they are deprecated indicates that there are problems with correct
7343 use of these functions.
7344 mount-local
7346 mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
7347 This call exports the libguestfs-accessible filesystem to a local
7349 mountpoint (directory) called "localmountpoint". Ordinary reads and
7350 writes to files and directories under "localmountpoint" are redirected
7351 through libguestfs.
7352 If the optional "readonly" flag is set to true, then writes to the
7354 filesystem return error "EROFS".
7355 "options" is a comma-separated list of mount options. See
7357 guestmount(1) for some useful options.
7358 "cachetimeout" sets the timeout (in seconds) for cached directory
7360 entries. The default is 60 seconds. See guestmount(1) for further
7361 information.
7362 If "debugcalls" is set to true, then additional debugging information
7364 is generated for every FUSE call.
7365 When "mount-local" returns, the filesystem is ready, but is not
7367 processing requests (access to it will block). You have to call
7368 "mount-local-run" to run the main loop.
7369 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7371 This command has one or more optional arguments. See "OPTIONAL
7373 ARGUMENTS".
7374 mount-local-run
7376 mount-local-run
7377 Run the main loop which translates kernel calls to libguestfs calls.
7379 This should only be called after "mount-local" returns successfully.
7381 The call will not return until the filesystem is unmounted.
7382 Note you must not make concurrent libguestfs calls on the same handle
7384 from another thread.
7385 You may call this from a different thread than the one which called
7387 "mount-local", subject to the usual rules for threads and libguestfs
7388 (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
7389 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7391 mount-loop
7393 mount-loop file mountpoint
7394 This command lets you mount file (a filesystem image in a file) on a
7396 mount point. It is entirely equivalent to the command "mount -o loop
7397 file mountpoint".
7398 mount-options
7400 mount-options options mountable mountpoint
7401 This is the same as the "mount" command, but it allows you to set the
7403 mount options as for the mount(8) -o flag.
7404 If the "options" parameter is an empty string, then no options are
7406 passed (all options default to whatever the filesystem uses).
7407 mount-ro
7409 mount-ro mountable mountpoint
7410 This is the same as the "mount" command, but it mounts the filesystem
7412 with the read-only (-o ro) flag.
7413 mount-vfs
7415 mount-vfs options vfstype mountable mountpoint
7416 This is the same as the "mount" command, but it allows you to set both
7418 the mount options and the vfstype as for the mount(8) -o and -t flags.
7419 mountable-device
7421 mountable-device mountable
7422 Returns the device name of a mountable. In quite a lot of cases, the
7424 mountable is the device name.
7425 However this doesn't apply for btrfs subvolumes, where the mountable is
7427 a combination of both the device name and the subvolume path (see also
7428 "mountable-subvolume" to extract the subvolume path of the mountable if
7429 any).
7430 mountable-subvolume
7432 mountable-subvolume mountable
7433 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
7435 are a combination of both the device name and the subvolume path (see
7436 also "mountable-device" to extract the device of the mountable).
7437 If the mountable does not represent a btrfs subvolume, then this
7439 function fails and the "errno" is set to "EINVAL".
7440 mountpoints
7442 mountpoints
7443 This call is similar to "mounts". That call returns a list of devices.
7445 This one returns a hash table (map) of device name to directory where
7446 the device is mounted.
7447 mounts
7449 mounts
7450 This returns the list of currently mounted filesystems. It returns the
7452 list of devices (eg. /dev/sda1, /dev/VG/LV).
7453 Some internal mounts are not shown.
7455 See also: "mountpoints"
7457 mv
7459 mv src dest
7460 This moves a file from "src" to "dest" where "dest" is either a
7462 destination filename or destination directory.
7463 See also: "rename".
7465 nr-devices
7467 nr-devices
7468 This returns the number of whole block devices that were added. This
7470 is the same as the number of devices that would be returned if you
7471 called "list-devices".
7472 To find out the maximum number of devices that could be added, call
7474 "max-disks".
7475 ntfs-3g-probe
7477 ntfs-3g-probe true|false device
7478 This command runs the ntfs-3g.probe(8) command which probes an NTFS
7480 "device" for mountability. (Not all NTFS volumes can be mounted read-
7481 write, and some cannot be mounted at all).
7482 "rw" is a boolean flag. Set it to true if you want to test if the
7484 volume can be mounted read-write. Set it to false if you want to test
7485 if the volume can be mounted read-only.
7486 The return value is an integer which 0 if the operation would succeed,
7488 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
7489 This command depends on the feature "ntfs3g". See also "feature-
7491 available".
7492 ntfscat-i
7494 ntfscat-i device inode (filename|-)
7495 Download a file given its inode from a NTFS filesystem and save it as
7497 filename on the local machine.
7498 This allows to download some otherwise inaccessible files such as the
7500 ones within the $Extend folder.
7501 The filesystem from which to extract the file must be unmounted,
7503 otherwise the call will fail.
7504 Use "-" instead of a filename to read/write from stdin/stdout.
7506 ntfsclone-in
7508 ntfsclone-in (backupfile|-) device
7509 Restore the "backupfile" (from a previous call to "ntfsclone-out") to
7511 "device", overwriting any existing contents of this device.
7512 Use "-" instead of a filename to read/write from stdin/stdout.
7514 This command depends on the feature "ntfs3g". See also "feature-
7516 available".
7517 ntfsclone-out
7519 ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
7520 Stream the NTFS filesystem "device" to the local file "backupfile".
7522 The format used for the backup file is a special format used by the
7523 ntfsclone(8) tool.
7524 If the optional "metadataonly" flag is true, then only the metadata is
7526 saved, losing all the user data (this is useful for diagnosing some
7527 filesystem problems).
7528 The optional "rescue", "ignorefscheck", "preservetimestamps" and
7530 "force" flags have precise meanings detailed in the ntfsclone(8) man
7531 page.
7532 Use "ntfsclone-in" to restore the file back to a libguestfs device.
7534 Use "-" instead of a filename to read/write from stdin/stdout.
7536 This command has one or more optional arguments. See "OPTIONAL
7538 ARGUMENTS".
7539 This command depends on the feature "ntfs3g". See also "feature-
7541 available".
7542 ntfsfix
7544 ntfsfix device [clearbadsectors:true|false]
7545 This command repairs some fundamental NTFS inconsistencies, resets the
7547 NTFS journal file, and schedules an NTFS consistency check for the
7548 first boot into Windows.
7549 This is not an equivalent of Windows "chkdsk". It does not scan the
7551 filesystem for inconsistencies.
7552 The optional "clearbadsectors" flag clears the list of bad sectors.
7554 This is useful after cloning a disk with bad sectors to a new disk.
7555 This command has one or more optional arguments. See "OPTIONAL
7557 ARGUMENTS".
7558 This command depends on the feature "ntfs3g". See also "feature-
7560 available".
7561 ntfsresize
7563 ntfsresize-opts
7564 ntfsresize device [size:N] [force:true|false]
7565 This command resizes an NTFS filesystem, expanding or shrinking it to
7567 the size of the underlying device.
7568 The optional parameters are:
7570 "size"
7572 The new size (in bytes) of the filesystem. If omitted, the
7573 filesystem is resized to fit the container (eg. partition).
7574 "force"
7576 If this option is true, then force the resize of the filesystem
7577 even if the filesystem is marked as requiring a consistency check.
7578 After the resize operation, the filesystem is always marked as
7580 requiring a consistency check (for safety). You have to boot into
7581 Windows to perform this check and clear this condition. If you
7582 don't set the "force" option then it is not possible to call
7583 "ntfsresize" multiple times on a single filesystem without booting
7584 into Windows between each resize.
7585 See also ntfsresize(8).
7587 This command has one or more optional arguments. See "OPTIONAL
7589 ARGUMENTS".
7590 This command depends on the feature "ntfsprogs". See also "feature-
7592 available".
7593 ntfsresize-size
7595 ntfsresize-size device size
7596 This command is the same as "ntfsresize" except that it allows you to
7598 specify the new size (in bytes) explicitly.
7599 This function is deprecated. In new code, use the "ntfsresize" call
7601 instead.
7602 Deprecated functions will not be removed from the API, but the fact
7604 that they are deprecated indicates that there are problems with correct
7605 use of these functions.
7606 This command depends on the feature "ntfsprogs". See also "feature-
7608 available".
7609 parse-environment
7611 parse-environment
7612 Parse the program’s environment and set flags in the handle
7614 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
7615 flag is set in the handle.
7616 Most programs do not need to call this. It is done implicitly when you
7618 call "create".
7619 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
7621 variables that can affect libguestfs handles. See also
7622 "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
7623 parse-environment-list
7625 parse-environment-list 'environment ...'
7626 Parse the list of strings in the argument "environment" and set flags
7628 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
7629 string in the list, then the ‘verbose’ flag is set in the handle.
7630 This is the same as "parse-environment" except that it parses an
7632 explicit list of strings instead of the program's environment.
7633 part-add
7635 part-add device prlogex startsect endsect
7636 This command adds a partition to "device". If there is no partition
7638 table on the device, call "part-init" first.
7639 The "prlogex" parameter is the type of partition. Normally you should
7641 pass "p" or "primary" here, but MBR partition tables also support "l"
7642 (or "logical") and "e" (or "extended") partition types.
7643 "startsect" and "endsect" are the start and end of the partition in
7645 sectors. "endsect" may be negative, which means it counts backwards
7646 from the end of the disk ("-1" is the last sector).
7647 Creating a partition which covers the whole disk is not so easy. Use
7649 "part-disk" to do that.
7650 part-del
7652 part-del device partnum
7653 This command deletes the partition numbered "partnum" on "device".
7655 Note that in the case of MBR partitioning, deleting an extended
7657 partition also deletes any logical partitions it contains.
7658 part-disk
7660 part-disk device parttype
7661 This command is simply a combination of "part-init" followed by "part-
7663 add" to create a single primary partition covering the whole disk.
7664 "parttype" is the partition table type, usually "mbr" or "gpt", but
7666 other possible values are described in "part-init".
7667 part-expand-gpt
7669 part-expand-gpt device
7670 Move backup GPT data structures to the end of the disk. This is useful
7672 in case of in-place image expand since disk space after backup GPT
7673 header is not usable. This is equivalent to "sgdisk -e".
7674 See also sgdisk(8).
7676 This command depends on the feature "gdisk". See also "feature-
7678 available".
7679 part-get-bootable
7681 part-get-bootable device partnum
7682 This command returns true if the partition "partnum" on "device" has
7684 the bootable flag set.
7685 See also "part-set-bootable".
7687 part-get-disk-guid
7689 part-get-disk-guid device
7690 Return the disk identifier (GUID) of a GPT-partitioned "device".
7692 Behaviour is undefined for other partition types.
7693 This command depends on the feature "gdisk". See also "feature-
7695 available".
7696 part-get-gpt-attributes
7698 part-get-gpt-attributes device partnum
7699 Return the attribute flags of numbered GPT partition "partnum". An
7701 error is returned for MBR partitions.
7702 This command depends on the feature "gdisk". See also "feature-
7704 available".
7705 part-get-gpt-guid
7707 part-get-gpt-guid device partnum
7708 Return the GUID of numbered GPT partition "partnum".
7710 This command depends on the feature "gdisk". See also "feature-
7712 available".
7713 part-get-gpt-type
7715 part-get-gpt-type device partnum
7716 Return the type GUID of numbered GPT partition "partnum". For MBR
7718 partitions, return an appropriate GUID corresponding to the MBR type.
7719 Behaviour is undefined for other partition types.
7720 This command depends on the feature "gdisk". See also "feature-
7722 available".
7723 part-get-mbr-id
7725 part-get-mbr-id device partnum
7726 Returns the MBR type byte (also known as the ID byte) from the numbered
7728 partition "partnum".
7729 Note that only MBR (old DOS-style) partitions have type bytes. You
7731 will get undefined results for other partition table types (see "part-
7732 get-parttype").
7733 part-get-mbr-part-type
7735 part-get-mbr-part-type device partnum
7736 This returns the partition type of an MBR partition numbered "partnum"
7738 on device "device".
7739 It returns "primary", "logical", or "extended".
7741 part-get-name
7743 part-get-name device partnum
7744 This gets the partition name on partition numbered "partnum" on device
7746 "device". Note that partitions are numbered from 1.
7747 The partition name can only be read on certain types of partition
7749 table. This works on "gpt" but not on "mbr" partitions.
7750 part-get-parttype
7752 part-get-parttype device
7753 This command examines the partition table on "device" and returns the
7755 partition table type (format) being used.
7756 Common return values include: "msdos" (a DOS/Windows style MBR
7758 partition table), "gpt" (a GPT/EFI-style partition table). Other
7759 values are possible, although unusual. See "part-init" for a full
7760 list.
7761 part-init
7763 part-init device parttype
7764 This creates an empty partition table on "device" of one of the
7766 partition types listed below. Usually "parttype" should be either
7767 "msdos" or "gpt" (for large disks).
7768 Initially there are no partitions. Following this, you should call
7770 "part-add" for each partition required.
7771 Possible values for "parttype" are:
7773 "efi"
7775 "gpt"
7776 Intel EFI / GPT partition table.
7777 This is recommended for >= 2 TB partitions that will be accessed
7779 from Linux and Intel-based Mac OS X. It also has limited backwards
7780 compatibility with the "mbr" format.
7781 "mbr"
7783 "msdos"
7784 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
7785 and Windows. This partition type will only work for device sizes
7786 up to 2 TB. For large disks we recommend using "gpt".
7787 Other partition table types that may work but are not supported
7789 include:
7790 "aix"
7792 AIX disk labels.
7793 "amiga"
7795 "rdb"
7796 Amiga "Rigid Disk Block" format.
7797 "bsd"
7799 BSD disk labels.
7800 "dasd"
7802 DASD, used on IBM mainframes.
7803 "dvh"
7805 MIPS/SGI volumes.
7806 "mac"
7808 Old Mac partition format. Modern Macs use "gpt".
7809 "pc98"
7811 NEC PC-98 format, common in Japan apparently.
7812 "sun"
7814 Sun disk labels.
7815 part-list
7817 part-list device
7818 This command parses the partition table on "device" and returns the
7820 list of partitions found.
7821 The fields in the returned structure are:
7823 "part_num"
7825 Partition number, counting from 1.
7826 "part_start"
7828 Start of the partition in bytes. To get sectors you have to divide
7829 by the device’s sector size, see "blockdev-getss".
7830 "part_end"
7832 End of the partition in bytes.
7833 "part_size"
7835 Size of the partition in bytes.
7836 part-resize
7838 part-resize device partnum endsect
7839 This command resizes the partition numbered "partnum" on "device" by
7841 moving the end position.
7842 Note that this does not modify any filesystem present in the partition.
7844 If you wish to do this, you will need to use filesystem resizing
7845 commands like "resize2fs".
7846 When growing a partition you will want to grow the filesystem
7848 afterwards, but when shrinking, you need to shrink the filesystem
7849 before the partition.
7850 part-set-bootable
7852 part-set-bootable device partnum true|false
7853 This sets the bootable flag on partition numbered "partnum" on device
7855 "device". Note that partitions are numbered from 1.
7856 The bootable flag is used by some operating systems (notably Windows)
7858 to determine which partition to boot from. It is by no means
7859 universally recognized.
7860 part-set-disk-guid
7862 part-set-disk-guid device guid
7863 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
7865 Return an error if the partition table of "device" isn't GPT, or if
7866 "guid" is not a valid GUID.
7867 This command depends on the feature "gdisk". See also "feature-
7869 available".
7870 part-set-disk-guid-random
7872 part-set-disk-guid-random device
7873 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
7875 randomly generated value. Return an error if the partition table of
7876 "device" isn't GPT.
7877 This command depends on the feature "gdisk". See also "feature-
7879 available".
7880 part-set-gpt-attributes
7882 part-set-gpt-attributes device partnum attributes
7883 Set the attribute flags of numbered GPT partition "partnum" to
7885 "attributes". Return an error if the partition table of "device" isn't
7886 GPT.
7887 See
7889 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
7890 for a useful list of partition attributes.
7891 This command depends on the feature "gdisk". See also "feature-
7893 available".
7894 part-set-gpt-guid
7896 part-set-gpt-guid device partnum guid
7897 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
7899 error if the partition table of "device" isn't GPT, or if "guid" is not
7900 a valid GUID.
7901 This command depends on the feature "gdisk". See also "feature-
7903 available".
7904 part-set-gpt-type
7906 part-set-gpt-type device partnum guid
7907 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
7909 an error if the partition table of "device" isn't GPT, or if "guid" is
7910 not a valid GUID.
7911 See
7913 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
7914 for a useful list of type GUIDs.
7915 This command depends on the feature "gdisk". See also "feature-
7917 available".
7918 part-set-mbr-id
7920 part-set-mbr-id device partnum idbyte
7921 Sets the MBR type byte (also known as the ID byte) of the numbered
7923 partition "partnum" to "idbyte". Note that the type bytes quoted in
7924 most documentation are in fact hexadecimal numbers, but usually
7925 documented without any leading "0x" which might be confusing.
7926 Note that only MBR (old DOS-style) partitions have type bytes. You
7928 will get undefined results for other partition table types (see "part-
7929 get-parttype").
7930 part-set-name
7932 part-set-name device partnum name
7933 This sets the partition name on partition numbered "partnum" on device
7935 "device". Note that partitions are numbered from 1.
7936 The partition name can only be set on certain types of partition table.
7938 This works on "gpt" but not on "mbr" partitions.
7939 part-to-dev
7941 part-to-dev partition
7942 This function takes a partition name (eg. "/dev/sdb1") and removes the
7944 partition number, returning the device name (eg. "/dev/sdb").
7945 The named partition must exist, for example as a string returned from
7947 "list-partitions".
7948 See also "part-to-partnum", "device-index".
7950 part-to-partnum
7952 part-to-partnum partition
7953 This function takes a partition name (eg. "/dev/sdb1") and returns the
7955 partition number (eg. 1).
7956 The named partition must exist, for example as a string returned from
7958 "list-partitions".
7959 See also "part-to-dev".
7961 ping-daemon
7963 ping-daemon
7964 This is a test probe into the guestfs daemon running inside the
7966 libguestfs appliance. Calling this function checks that the daemon
7967 responds to the ping message, without affecting the daemon or attached
7968 block device(s) in any other way.
7969 pread
7971 pread path count offset
7972 This command lets you read part of a file. It reads "count" bytes of
7974 the file, starting at "offset", from file "path".
7975 This may read fewer bytes than requested. For further details see the
7977 pread(2) system call.
7978 See also "pwrite", "pread-device".
7980 Because of the message protocol, there is a transfer limit of somewhere
7982 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7983 pread-device
7985 pread-device device count offset
7986 This command lets you read part of a block device. It reads "count"
7988 bytes of "device", starting at "offset".
7989 This may read fewer bytes than requested. For further details see the
7991 pread(2) system call.
7992 See also "pread".
7994 Because of the message protocol, there is a transfer limit of somewhere
7996 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7997 pvchange-uuid
7999 pvchange-uuid device
8000 Generate a new random UUID for the physical volume "device".
8002 This command depends on the feature "lvm2". See also "feature-
8004 available".
8005 pvchange-uuid-all
8007 pvchange-uuid-all
8008 Generate new random UUIDs for all physical volumes.
8010 This command depends on the feature "lvm2". See also "feature-
8012 available".
8013 pvcreate
8015 pvcreate device
8016 This creates an LVM physical volume on the named "device", where
8018 "device" should usually be a partition name such as /dev/sda1.
8019 This command depends on the feature "lvm2". See also "feature-
8021 available".
8022 pvremove
8024 pvremove device
8025 This wipes a physical volume "device" so that LVM will no longer
8027 recognise it.
8028 The implementation uses the pvremove(8) command which refuses to wipe
8030 physical volumes that contain any volume groups, so you have to remove
8031 those first.
8032 This command depends on the feature "lvm2". See also "feature-
8034 available".
8035 pvresize
8037 pvresize device
8038 This resizes (expands or shrinks) an existing LVM physical volume to
8040 match the new size of the underlying device.
8041 This command depends on the feature "lvm2". See also "feature-
8043 available".
8044 pvresize-size
8046 pvresize-size device size
8047 This command is the same as "pvresize" except that it allows you to
8049 specify the new size (in bytes) explicitly.
8050 This command depends on the feature "lvm2". See also "feature-
8052 available".
8053 pvs
8055 pvs
8056 List all the physical volumes detected. This is the equivalent of the
8058 pvs(8) command.
8059 This returns a list of just the device names that contain PVs (eg.
8061 /dev/sda2).
8062 See also "pvs-full".
8064 This command depends on the feature "lvm2". See also "feature-
8066 available".
8067 pvs-full
8069 pvs-full
8070 List all the physical volumes detected. This is the equivalent of the
8072 pvs(8) command. The "full" version includes all fields.
8073 This command depends on the feature "lvm2". See also "feature-
8075 available".
8076 pvuuid
8078 pvuuid device
8079 This command returns the UUID of the LVM PV "device".
8081 pwrite
8083 pwrite path content offset
8084 This command writes to part of a file. It writes the data buffer
8086 "content" to the file "path" starting at offset "offset".
8087 This command implements the pwrite(2) system call, and like that system
8089 call it may not write the full data requested. The return value is the
8090 number of bytes that were actually written to the file. This could
8091 even be 0, although short writes are unlikely for regular files in
8092 ordinary circumstances.
8093 See also "pread", "pwrite-device".
8095 Because of the message protocol, there is a transfer limit of somewhere
8097 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8098 pwrite-device
8100 pwrite-device device content offset
8101 This command writes to part of a device. It writes the data buffer
8103 "content" to "device" starting at offset "offset".
8104 This command implements the pwrite(2) system call, and like that system
8106 call it may not write the full data requested (although short writes to
8107 disk devices and partitions are probably impossible with standard Linux
8108 kernels).
8109 See also "pwrite".
8111 Because of the message protocol, there is a transfer limit of somewhere
8113 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8114 read-file
8116 read-file path
8117 This calls returns the contents of the file "path" as a buffer.
8119 Unlike "cat", this function can correctly handle files that contain
8121 embedded ASCII NUL characters.
8122 read-lines
8124 read-lines path
8125 Return the contents of the file named "path".
8127 The file contents are returned as a list of lines. Trailing "LF" and
8129 "CRLF" character sequences are not returned.
8130 Note that this function cannot correctly handle binary files
8132 (specifically, files containing "\0" character which is treated as end
8133 of string). For those you need to use the "read-file" function and
8134 split the buffer into lines yourself.
8135 readdir
8137 readdir dir
8138 This returns the list of directory entries in directory "dir".
8140 All entries in the directory are returned, including "." and "..". The
8142 entries are not sorted, but returned in the same order as the
8143 underlying filesystem.
8144 Also this call returns basic file type information about each file.
8146 The "ftyp" field will contain one of the following characters:
8147 'b' Block special
8149 'c' Char special
8151 'd' Directory
8153 'f' FIFO (named pipe)
8155 'l' Symbolic link
8157 'r' Regular file
8159 's' Socket
8161 'u' Unknown file type
8163 '?' The readdir(3) call returned a "d_type" field with an unexpected
8165 value
8166 This function is primarily intended for use by programs. To get a
8168 simple list of names, use "ls". To get a printable directory for human
8169 consumption, use "ll".
8170 Because of the message protocol, there is a transfer limit of somewhere
8172 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8173 readlink
8175 readlink path
8176 This command reads the target of a symbolic link.
8178 readlinklist
8180 readlinklist path 'names ...'
8181 This call allows you to do a "readlink" operation on multiple files,
8183 where all files are in the directory "path". "names" is the list of
8184 files from this directory.
8185 On return you get a list of strings, with a one-to-one correspondence
8187 to the "names" list. Each string is the value of the symbolic link.
8188 If the readlink(2) operation fails on any name, then the corresponding
8190 result string is the empty string "". However the whole operation is
8191 completed even if there were readlink(2) errors, and so you can call
8192 this function with names where you don't know if they are symbolic
8193 links already (albeit slightly less efficient).
8194 This call is intended for programs that want to efficiently list a
8196 directory contents without making many round-trips.
8197 realpath
8199 realpath path
8200 Return the canonicalized absolute pathname of "path". The returned
8202 path has no ".", ".." or symbolic link path elements.
8203 remount
8205 remount mountpoint [rw:true|false]
8206 This call allows you to change the "rw" (readonly/read-write) flag on
8208 an already mounted filesystem at "mountpoint", converting a readonly
8209 filesystem to be read-write, or vice-versa.
8210 Note that at the moment you must supply the "optional" "rw" parameter.
8212 In future we may allow other flags to be adjusted.
8213 This command has one or more optional arguments. See "OPTIONAL
8215 ARGUMENTS".
8216 remove-drive
8218 remove-drive label
8219 This call does nothing and returns an error.
8221 This function is deprecated. There is no replacement. Consult the API
8223 documentation in guestfs(3) for further information.
8224 Deprecated functions will not be removed from the API, but the fact
8226 that they are deprecated indicates that there are problems with correct
8227 use of these functions.
8228 removexattr
8230 removexattr xattr path
8231 This call removes the extended attribute named "xattr" of the file
8233 "path".
8234 See also: "lremovexattr", attr(5).
8236 This command depends on the feature "linuxxattrs". See also "feature-
8238 available".
8239 rename
8241 rename oldpath newpath
8242 Rename a file to a new place on the same filesystem. This is the same
8244 as the Linux rename(2) system call. In most cases you are better to
8245 use "mv" instead.
8246 resize2fs
8248 resize2fs device
8249 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
8251 underlying device.
8252 See also "RESIZE2FS ERRORS" in guestfs(3).
8254 resize2fs-M
8256 resize2fs-M device
8257 This command is the same as "resize2fs", but the filesystem is resized
8259 to its minimum size. This works like the -M option to the resize2fs(8)
8260 command.
8261 To get the resulting size of the filesystem you should call "tune2fs-l"
8263 and read the "Block size" and "Block count" values. These two numbers,
8264 multiplied together, give the resulting size of the minimal filesystem
8265 in bytes.
8266 See also "RESIZE2FS ERRORS" in guestfs(3).
8268 resize2fs-size
8270 resize2fs-size device size
8271 This command is the same as "resize2fs" except that it allows you to
8273 specify the new size (in bytes) explicitly.
8274 See also "RESIZE2FS ERRORS" in guestfs(3).
8276 rm
8278 rm path
8279 Remove the single file "path".
8281 rm-f
8283 rm-f path
8284 Remove the file "path".
8286 If the file doesn't exist, that error is ignored. (Other errors, eg.
8288 I/O errors or bad paths, are not ignored)
8289 This call cannot remove directories. Use "rmdir" to remove an empty
8291 directory, or "rm-rf" to remove directories recursively.
8292 rm-rf
8294 rm-rf path
8295 Remove the file or directory "path", recursively removing the contents
8297 if its a directory. This is like the "rm -rf" shell command.
8298 rmdir
8300 rmdir path
8301 Remove the single directory "path".
8303 rmmountpoint
8305 rmmountpoint exemptpath
8306 This call removes a mountpoint that was previously created with
8308 "mkmountpoint". See "mkmountpoint" for full details.
8309 rsync
8311 rsync src dest [archive:true|false] [deletedest:true|false]
8312 This call may be used to copy or synchronize two directories under the
8314 same libguestfs handle. This uses the rsync(1) program which uses a
8315 fast algorithm that avoids copying files unnecessarily.
8316 "src" and "dest" are the source and destination directories. Files are
8318 copied from "src" to "dest".
8319 The optional arguments are:
8321 "archive"
8323 Turns on archive mode. This is the same as passing the --archive
8324 flag to "rsync".
8325 "deletedest"
8327 Delete files at the destination that do not exist at the source.
8328 This command has one or more optional arguments. See "OPTIONAL
8330 ARGUMENTS".
8331 This command depends on the feature "rsync". See also "feature-
8333 available".
8334 rsync-in
8336 rsync-in remote dest [archive:true|false] [deletedest:true|false]
8337 This call may be used to copy or synchronize the filesystem on the host
8339 or on a remote computer with the filesystem within libguestfs. This
8340 uses the rsync(1) program which uses a fast algorithm that avoids
8341 copying files unnecessarily.
8342 This call only works if the network is enabled. See "set-network" or
8344 the --network option to various tools like guestfish(1).
8345 Files are copied from the remote server and directory specified by
8347 "remote" to the destination directory "dest".
8348 The format of the remote server string is defined by rsync(1). Note
8350 that there is no way to supply a password or passphrase so the target
8351 must be set up not to require one.
8352 The optional arguments are the same as those of "rsync".
8354 This command has one or more optional arguments. See "OPTIONAL
8356 ARGUMENTS".
8357 This command depends on the feature "rsync". See also "feature-
8359 available".
8360 rsync-out
8362 rsync-out src remote [archive:true|false] [deletedest:true|false]
8363 This call may be used to copy or synchronize the filesystem within
8365 libguestfs with a filesystem on the host or on a remote computer. This
8366 uses the rsync(1) program which uses a fast algorithm that avoids
8367 copying files unnecessarily.
8368 This call only works if the network is enabled. See "set-network" or
8370 the --network option to various tools like guestfish(1).
8371 Files are copied from the source directory "src" to the remote server
8373 and directory specified by "remote".
8374 The format of the remote server string is defined by rsync(1). Note
8376 that there is no way to supply a password or passphrase so the target
8377 must be set up not to require one.
8378 The optional arguments are the same as those of "rsync".
8380 Globbing does not happen on the "src" parameter. In programs which use
8382 the API directly you have to expand wildcards yourself (see "glob-
8383 expand"). In guestfish you can use the "glob" command (see "glob"),
8384 for example:
8385 ><fs> glob rsync-out /* rsync://remote/
8387 This command has one or more optional arguments. See "OPTIONAL
8389 ARGUMENTS".
8390 This command depends on the feature "rsync". See also "feature-
8392 available".
8393 scrub-device
8395 scrub-device device
8396 This command writes patterns over "device" to make data retrieval more
8398 difficult.
8399 It is an interface to the scrub(1) program. See that manual page for
8401 more details.
8402 This command depends on the feature "scrub". See also "feature-
8404 available".
8405 scrub-file
8407 scrub-file file
8408 This command writes patterns over a file to make data retrieval more
8410 difficult.
8411 The file is removed after scrubbing.
8413 It is an interface to the scrub(1) program. See that manual page for
8415 more details.
8416 This command depends on the feature "scrub". See also "feature-
8418 available".
8419 scrub-freespace
8421 scrub-freespace dir
8422 This command creates the directory "dir" and then fills it with files
8424 until the filesystem is full, and scrubs the files as for "scrub-file",
8425 and deletes them. The intention is to scrub any free space on the
8426 partition containing "dir".
8427 It is an interface to the scrub(1) program. See that manual page for
8429 more details.
8430 This command depends on the feature "scrub". See also "feature-
8432 available".
8433 selinux-relabel
8435 selinux-relabel specfile path [force:true|false]
8436 SELinux relabel parts of the filesystem.
8438 The "specfile" parameter controls the policy spec file used. You have
8440 to parse "/etc/selinux/config" to find the correct SELinux policy and
8441 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
8442 "/contexts/files/file_contexts".
8443 The required "path" parameter is the top level directory where
8445 relabelling starts. Normally you should pass "path" as "/" to relabel
8446 the whole guest filesystem.
8447 The optional "force" boolean controls whether the context is reset for
8449 customizable files, and also whether the user, role and range parts of
8450 the file context is changed.
8451 This command has one or more optional arguments. See "OPTIONAL
8453 ARGUMENTS".
8454 This command depends on the feature "selinuxrelabel". See also
8456 "feature-available".
8457 set-append
8459 append
8460 set-append append
8461 This function is used to add additional options to the libguestfs
8463 appliance kernel command line.
8464 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
8466 environment variable.
8467 Setting "append" to "NULL" means no additional options are passed
8469 (libguestfs always adds a few of its own).
8470 set-attach-method
8472 attach-method
8473 set-attach-method backend
8474 Set the method that libguestfs uses to connect to the backend guestfsd
8476 daemon.
8477 See "BACKEND" in guestfs(3).
8479 This function is deprecated. In new code, use the "set-backend" call
8481 instead.
8482 Deprecated functions will not be removed from the API, but the fact
8484 that they are deprecated indicates that there are problems with correct
8485 use of these functions.
8486 set-autosync
8488 autosync
8489 set-autosync true|false
8490 If "autosync" is true, this enables autosync. Libguestfs will make a
8492 best effort attempt to make filesystems consistent and synchronized
8493 when the handle is closed (also if the program exits without closing
8494 handles).
8495 This is enabled by default (since libguestfs 1.5.24, previously it was
8497 disabled by default).
8498 set-backend
8500 backend
8501 set-backend backend
8502 Set the method that libguestfs uses to connect to the backend guestfsd
8504 daemon.
8505 This handle property was previously called the "attach method".
8507 See "BACKEND" in guestfs(3).
8509 set-backend-setting
8511 set-backend-setting name val
8512 Append "name=value" to the backend settings string list. However if a
8514 string already exists matching "name" or beginning with "name=", then
8515 that setting is replaced.
8516 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8518 set-backend-settings
8520 set-backend-settings 'settings ...'
8521 Set a list of zero or more settings which are passed through to the
8523 current backend. Each setting is a string which is interpreted in a
8524 backend-specific way, or ignored if not understood by the backend.
8525 The default value is an empty list, unless the environment variable
8527 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
8528 This environment variable contains a colon-separated list of settings.
8529 This call replaces all backend settings. If you want to replace a
8531 single backend setting, see "set-backend-setting". If you want to
8532 clear a single backend setting, see "clear-backend-setting".
8533 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8535 set-cachedir
8537 cachedir
8538 set-cachedir cachedir
8539 Set the directory used by the handle to store the appliance cache, when
8541 using a supermin appliance. The appliance is cached and shared between
8542 all handles which have the same effective user ID.
8543 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
8545 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
8546 default. Else if "TMPDIR" is set, then that is the default. Else
8547 /var/tmp is the default.
8548 set-direct
8550 direct
8551 set-direct true|false
8552 If the direct appliance mode flag is enabled, then stdin and stdout are
8554 passed directly through to the appliance once it is launched.
8555 One consequence of this is that log messages aren't caught by the
8557 library and handled by "set-log-message-callback", but go straight to
8558 stdout.
8559 You probably don't want to use this unless you know what you are doing.
8561 The default is disabled.
8563 This function is deprecated. In new code, use the "internal-get-
8565 console-socket" call instead.
8566 Deprecated functions will not be removed from the API, but the fact
8568 that they are deprecated indicates that there are problems with correct
8569 use of these functions.
8570 set-e2attrs
8572 set-e2attrs file attrs [clear:true|false]
8573 This sets or clears the file attributes "attrs" associated with the
8575 inode file.
8576 "attrs" is a string of characters representing file attributes. See
8578 "get-e2attrs" for a list of possible attributes. Not all attributes
8579 can be changed.
8580 If optional boolean "clear" is not present or false, then the "attrs"
8582 listed are set in the inode.
8583 If "clear" is true, then the "attrs" listed are cleared in the inode.
8585 In both cases, other attributes not present in the "attrs" string are
8587 left unchanged.
8588 These attributes are only present when the file is located on an
8590 ext2/3/4 filesystem. Using this call on other filesystem types will
8591 result in an error.
8592 This command has one or more optional arguments. See "OPTIONAL
8594 ARGUMENTS".
8595 set-e2generation
8597 set-e2generation file generation
8598 This sets the ext2 file generation of a file.
8600 See "get-e2generation".
8602 set-e2label
8604 set-e2label device label
8605 This sets the ext2/3/4 filesystem label of the filesystem on "device"
8607 to "label". Filesystem labels are limited to 16 characters.
8608 You can use either "tune2fs-l" or "get-e2label" to return the existing
8610 label on a filesystem.
8611 This function is deprecated. In new code, use the "set-label" call
8613 instead.
8614 Deprecated functions will not be removed from the API, but the fact
8616 that they are deprecated indicates that there are problems with correct
8617 use of these functions.
8618 set-e2uuid
8620 set-e2uuid device uuid
8621 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
8623 "uuid". The format of the UUID and alternatives such as "clear",
8624 "random" and "time" are described in the tune2fs(8) manpage.
8625 You can use "vfs-uuid" to return the existing UUID of a filesystem.
8627 This function is deprecated. In new code, use the "set-uuid" call
8629 instead.
8630 Deprecated functions will not be removed from the API, but the fact
8632 that they are deprecated indicates that there are problems with correct
8633 use of these functions.
8634 set-hv
8636 hv
8637 set-hv hv
8638 Set the hypervisor binary that we will use. The hypervisor depends on
8640 the backend, but is usually the location of the qemu/KVM hypervisor.
8641 The default is chosen when the library was compiled by the configure
8643 script.
8644 You can also override this by setting the "LIBGUESTFS_HV" environment
8646 variable.
8647 Note that you should call this function as early as possible after
8649 creating the handle. This is because some pre-launch operations depend
8650 on testing qemu features (by running "qemu -help"). If the qemu binary
8651 changes, we don't retest features, and so you might see inconsistent
8652 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8653 all since that picks the qemu binary at the same time as the handle is
8654 created.
8655 set-identifier
8657 identifier
8658 set-identifier identifier
8659 This is an informative string which the caller may optionally set in
8661 the handle. It is printed in various places, allowing the current
8662 handle to be identified in debugging output.
8663 One important place is when tracing is enabled. If the identifier
8665 string is not an empty string, then trace messages change from this:
8666 libguestfs: trace: get_tmpdir
8668 libguestfs: trace: get_tmpdir = "/tmp"
8669 to this:
8671 libguestfs: trace: ID: get_tmpdir
8673 libguestfs: trace: ID: get_tmpdir = "/tmp"
8674 where "ID" is the identifier string set by this call.
8676 The identifier must only contain alphanumeric ASCII characters,
8678 underscore and minus sign. The default is the empty string.
8679 See also "set-program", "set-trace", "get-identifier".
8681 set-label
8683 set-label mountable label
8684 Set the filesystem label on "mountable" to "label".
8686 Only some filesystem types support labels, and libguestfs supports
8688 setting labels on only a subset of these.
8689 ext2, ext3, ext4
8691 Labels are limited to 16 bytes.
8692 NTFS
8694 Labels are limited to 128 unicode characters.
8695 XFS The label is limited to 12 bytes. The filesystem must not be
8697 mounted when trying to set the label.
8698 btrfs
8700 The label is limited to 255 bytes and some characters are not
8701 allowed. Setting the label on a btrfs subvolume will set the label
8702 on its parent filesystem. The filesystem must not be mounted when
8703 trying to set the label.
8704 fat The label is limited to 11 bytes.
8706 swap
8708 The label is limited to 16 bytes.
8709 If there is no support for changing the label for the type of the
8711 specified filesystem, set_label will fail and set errno as ENOTSUP.
8712 To read the label on a filesystem, call "vfs-label".
8714 set-libvirt-requested-credential
8716 set-libvirt-requested-credential index cred
8717 After requesting the "index"'th credential from the user, call this
8719 function to pass the answer back to libvirt.
8720 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8722 example code.
8723 set-libvirt-supported-credentials
8725 set-libvirt-supported-credentials 'creds ...'
8726 Call this function before setting an event handler for
8728 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
8729 that the program knows how to process.
8730 The "creds" list must be a non-empty list of strings. Possible strings
8732 are:
8733 "username"
8735 "authname"
8736 "language"
8737 "cnonce"
8738 "passphrase"
8739 "echoprompt"
8740 "noechoprompt"
8741 "realm"
8742 "external"
8743 See libvirt documentation for the meaning of these credential types.
8745 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8747 example code.
8748 set-memsize
8750 memsize
8751 set-memsize memsize
8752 This sets the memory size in megabytes allocated to the hypervisor.
8754 This only has any effect if called before "launch".
8755 You can also change this by setting the environment variable
8757 "LIBGUESTFS_MEMSIZE" before the handle is created.
8758 For more information on the architecture of libguestfs, see guestfs(3).
8760 set-network
8762 network
8763 set-network true|false
8764 If "network" is true, then the network is enabled in the libguestfs
8766 appliance. The default is false.
8767 This affects whether commands are able to access the network (see
8769 "RUNNING COMMANDS" in guestfs(3)).
8770 You must call this before calling "launch", otherwise it has no effect.
8772 set-path
8774 path
8775 set-path searchpath
8776 Set the path that libguestfs searches for kernel and initrd.img.
8778 The default is "$libdir/guestfs" unless overridden by setting
8780 "LIBGUESTFS_PATH" environment variable.
8781 Setting "path" to "NULL" restores the default path.
8783 set-pgroup
8785 pgroup
8786 set-pgroup true|false
8787 If "pgroup" is true, child processes are placed into their own process
8789 group.
8790 The practical upshot of this is that signals like "SIGINT" (from users
8792 pressing "^C") won't be received by the child process.
8793 The default for this flag is false, because usually you want "^C" to
8795 kill the subprocess. Guestfish sets this flag to true when used
8796 interactively, so that "^C" can cancel long-running commands gracefully
8797 (see "user-cancel").
8798 set-program
8800 program
8801 set-program program
8802 Set the program name. This is an informative string which the main
8804 program may optionally set in the handle.
8805 When the handle is created, the program name in the handle is set to
8807 the basename from "argv[0]". The program name can never be "NULL".
8808 set-qemu
8810 qemu
8811 set-qemu hv
8812 Set the hypervisor binary (usually qemu) that we will use.
8814 The default is chosen when the library was compiled by the configure
8816 script.
8817 You can also override this by setting the "LIBGUESTFS_HV" environment
8819 variable.
8820 Setting "hv" to "NULL" restores the default qemu binary.
8822 Note that you should call this function as early as possible after
8824 creating the handle. This is because some pre-launch operations depend
8825 on testing qemu features (by running "qemu -help"). If the qemu binary
8826 changes, we don't retest features, and so you might see inconsistent
8827 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8828 all since that picks the qemu binary at the same time as the handle is
8829 created.
8830 This function is deprecated. In new code, use the "set-hv" call
8832 instead.
8833 Deprecated functions will not be removed from the API, but the fact
8835 that they are deprecated indicates that there are problems with correct
8836 use of these functions.
8837 set-recovery-proc
8839 recovery-proc
8840 set-recovery-proc true|false
8841 If this is called with the parameter "false" then "launch" does not
8843 create a recovery process. The purpose of the recovery process is to
8844 stop runaway hypervisor processes in the case where the main program
8845 aborts abruptly.
8846 This only has any effect if called before "launch", and the default is
8848 true.
8849 About the only time when you would want to disable this is if the main
8851 process will fork itself into the background ("daemonize" itself). In
8852 this case the recovery process thinks that the main program has
8853 disappeared and so kills the hypervisor, which is not very helpful.
8854 set-selinux
8856 selinux
8857 set-selinux true|false
8858 This sets the selinux flag that is passed to the appliance at boot
8860 time. The default is "selinux=0" (disabled).
8861 Note that if SELinux is enabled, it is always in Permissive mode
8863 ("enforcing=0").
8864 For more information on the architecture of libguestfs, see guestfs(3).
8866 This function is deprecated. In new code, use the "selinux-relabel"
8868 call instead.
8869 Deprecated functions will not be removed from the API, but the fact
8871 that they are deprecated indicates that there are problems with correct
8872 use of these functions.
8873 set-smp
8875 smp
8876 set-smp smp
8877 Change the number of virtual CPUs assigned to the appliance. The
8879 default is 1. Increasing this may improve performance, though often it
8880 has no effect.
8881 This function must be called before "launch".
8883 set-tmpdir
8885 tmpdir
8886 set-tmpdir tmpdir
8887 Set the directory used by the handle to store temporary files.
8889 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
8891 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
8892 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
8893 default.
8894 set-trace
8896 trace
8897 set-trace true|false
8898 If the command trace flag is set to 1, then libguestfs calls,
8900 parameters and return values are traced.
8901 If you want to trace C API calls into libguestfs (and other libraries)
8903 then possibly a better way is to use the external ltrace(1) command.
8904 Command traces are disabled unless the environment variable
8906 "LIBGUESTFS_TRACE" is defined and set to 1.
8907 Trace messages are normally sent to "stderr", unless you register a
8909 callback to send them somewhere else (see "set-event-callback").
8910 set-uuid
8912 set-uuid device uuid
8913 Set the filesystem UUID on "device" to "uuid". If this fails and the
8915 errno is ENOTSUP, means that there is no support for changing the UUID
8916 for the type of the specified filesystem.
8917 Only some filesystem types support setting UUIDs.
8919 To read the UUID on a filesystem, call "vfs-uuid".
8921 set-uuid-random
8923 set-uuid-random device
8924 Set the filesystem UUID on "device" to a random UUID. If this fails
8926 and the errno is ENOTSUP, means that there is no support for changing
8927 the UUID for the type of the specified filesystem.
8928 Only some filesystem types support setting UUIDs.
8930 To read the UUID on a filesystem, call "vfs-uuid".
8932 set-verbose
8934 verbose
8935 set-verbose true|false
8936 If "verbose" is true, this turns on verbose messages.
8938 Verbose messages are disabled unless the environment variable
8940 "LIBGUESTFS_DEBUG" is defined and set to 1.
8941 Verbose messages are normally sent to "stderr", unless you register a
8943 callback to send them somewhere else (see "set-event-callback").
8944 setcon
8946 setcon context
8947 This sets the SELinux security context of the daemon to the string
8949 "context".
8950 See the documentation about SELINUX in guestfs(3).
8952 This function is deprecated. In new code, use the "selinux-relabel"
8954 call instead.
8955 Deprecated functions will not be removed from the API, but the fact
8957 that they are deprecated indicates that there are problems with correct
8958 use of these functions.
8959 This command depends on the feature "selinux". See also "feature-
8961 available".
8962 setxattr
8964 setxattr xattr val vallen path
8965 This call sets the extended attribute named "xattr" of the file "path"
8967 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
8968 data.
8969 See also: "lsetxattr", attr(5).
8971 This command depends on the feature "linuxxattrs". See also "feature-
8973 available".
8974 sfdisk
8976 sfdisk device cyls heads sectors 'lines ...'
8977 This is a direct interface to the sfdisk(8) program for creating
8979 partitions on block devices.
8980 "device" should be a block device, for example /dev/sda.
8982 "cyls", "heads" and "sectors" are the number of cylinders, heads and
8984 sectors on the device, which are passed directly to sfdisk(8) as the
8985 -C, -H and -S parameters. If you pass 0 for any of these, then the
8986 corresponding parameter is omitted. Usually for ‘large’ disks, you can
8987 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
8988 (or rather, the kernel) cannot work out the right geometry and you will
8989 need to tell it.
8990 "lines" is a list of lines that we feed to sfdisk(8). For more
8992 information refer to the sfdisk(8) manpage.
8993 To create a single partition occupying the whole disk, you would pass
8995 "lines" as a single element list, when the single element being the
8996 string "," (comma).
8997 See also: "sfdisk-l", "sfdisk-N", "part-init"
8999 This function is deprecated. In new code, use the "part-add" call
9001 instead.
9002 Deprecated functions will not be removed from the API, but the fact
9004 that they are deprecated indicates that there are problems with correct
9005 use of these functions.
9006 sfdiskM
9008 sfdiskM device 'lines ...'
9009 This is a simplified interface to the "sfdisk" command, where partition
9011 sizes are specified in megabytes only (rounded to the nearest cylinder)
9012 and you don't need to specify the cyls, heads and sectors parameters
9013 which were rarely if ever used anyway.
9014 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
9016 This function is deprecated. In new code, use the "part-add" call
9018 instead.
9019 Deprecated functions will not be removed from the API, but the fact
9021 that they are deprecated indicates that there are problems with correct
9022 use of these functions.
9023 sfdisk-N
9025 sfdisk-N device partnum cyls heads sectors line
9026 This runs sfdisk(8) option to modify just the single partition "n"
9028 (note: "n" counts from 1).
9029 For other parameters, see "sfdisk". You should usually pass 0 for the
9031 cyls/heads/sectors parameters.
9032 See also: "part-add"
9034 This function is deprecated. In new code, use the "part-add" call
9036 instead.
9037 Deprecated functions will not be removed from the API, but the fact
9039 that they are deprecated indicates that there are problems with correct
9040 use of these functions.
9041 sfdisk-disk-geometry
9043 sfdisk-disk-geometry device
9044 This displays the disk geometry of "device" read from the partition
9046 table. Especially in the case where the underlying block device has
9047 been resized, this can be different from the kernel’s idea of the
9048 geometry (see "sfdisk-kernel-geometry").
9049 The result is in human-readable format, and not designed to be parsed.
9051 sfdisk-kernel-geometry
9053 sfdisk-kernel-geometry device
9054 This displays the kernel’s idea of the geometry of "device".
9056 The result is in human-readable format, and not designed to be parsed.
9058 sfdisk-l
9060 sfdisk-l device
9061 This displays the partition table on "device", in the human-readable
9063 output of the sfdisk(8) command. It is not intended to be parsed.
9064 See also: "part-list"
9066 This function is deprecated. In new code, use the "part-list" call
9068 instead.
9069 Deprecated functions will not be removed from the API, but the fact
9071 that they are deprecated indicates that there are problems with correct
9072 use of these functions.
9073 sh
9075 sh command
9076 This call runs a command from the guest filesystem via the guest’s
9078 /bin/sh.
9079 This is like "command", but passes the command to:
9081 /bin/sh -c "command"
9083 Depending on the guest’s shell, this usually results in wildcards being
9085 expanded, shell expressions being interpolated and so on.
9086 All the provisos about "command" apply to this call.
9088 sh-lines
9090 sh-lines command
9091 This is the same as "sh", but splits the result into a list of lines.
9093 See also: "command-lines"
9095 shutdown
9097 shutdown
9098 This is the opposite of "launch". It performs an orderly shutdown of
9100 the backend process(es). If the autosync flag is set (which is the
9101 default) then the disk image is synchronized.
9102 If the subprocess exits with an error then this function will return an
9104 error, which should not be ignored (it may indicate that the disk image
9105 could not be written out properly).
9106 It is safe to call this multiple times. Extra calls are ignored.
9108 This call does not close or free up the handle. You still need to call
9110 "close" afterwards.
9111 "close" will call this if you don't do it explicitly, but note that any
9113 errors are ignored in that case.
9114 sleep
9116 sleep secs
9117 Sleep for "secs" seconds.
9119 stat
9121 stat path
9122 Returns file information for the given "path".
9124 This is the same as the stat(2) system call.
9126 This function is deprecated. In new code, use the "statns" call
9128 instead.
9129 Deprecated functions will not be removed from the API, but the fact
9131 that they are deprecated indicates that there are problems with correct
9132 use of these functions.
9133 statns
9135 statns path
9136 Returns file information for the given "path".
9138 This is the same as the stat(2) system call.
9140 statvfs
9142 statvfs path
9143 Returns file system statistics for any mounted file system. "path"
9145 should be a file or directory in the mounted file system (typically it
9146 is the mount point itself, but it doesn't need to be).
9147 This is the same as the statvfs(2) system call.
9149 strings
9151 strings path
9152 This runs the strings(1) command on a file and returns the list of
9154 printable strings found.
9155 The "strings" command has, in the past, had problems with parsing
9157 untrusted files. These are mitigated in the current version of
9158 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9159 Because of the message protocol, there is a transfer limit of somewhere
9161 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9162 strings-e
9164 strings-e encoding path
9165 This is like the "strings" command, but allows you to specify the
9167 encoding of strings that are looked for in the source file "path".
9168 Allowed encodings are:
9170 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
9172 parts of ISO-8859-X (this is what "strings" uses).
9173 S Single 8-bit-byte characters.
9175 b 16-bit big endian strings such as those encoded in UTF-16BE or
9177 UCS-2BE.
9178 l (lower case letter L)
9180 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
9181 for examining binaries in Windows guests.
9182 B 32-bit big endian such as UCS-4BE.
9184 L 32-bit little endian such as UCS-4LE.
9186 The returned strings are transcoded to UTF-8.
9188 The "strings" command has, in the past, had problems with parsing
9190 untrusted files. These are mitigated in the current version of
9191 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9192 Because of the message protocol, there is a transfer limit of somewhere
9194 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9195 swapoff-device
9197 swapoff-device device
9198 This command disables the libguestfs appliance swap device or partition
9200 named "device". See "swapon-device".
9201 swapoff-file
9203 swapoff-file file
9204 This command disables the libguestfs appliance swap on file.
9206 swapoff-label
9208 swapoff-label label
9209 This command disables the libguestfs appliance swap on labeled swap
9211 partition.
9212 swapoff-uuid
9214 swapoff-uuid uuid
9215 This command disables the libguestfs appliance swap partition with the
9217 given UUID.
9218 This command depends on the feature "linuxfsuuid". See also "feature-
9220 available".
9221 swapon-device
9223 swapon-device device
9224 This command enables the libguestfs appliance to use the swap device or
9226 partition named "device". The increased memory is made available for
9227 all commands, for example those run using "command" or "sh".
9228 Note that you should not swap to existing guest swap partitions unless
9230 you know what you are doing. They may contain hibernation information,
9231 or other information that the guest doesn't want you to trash. You
9232 also risk leaking information about the host to the guest this way.
9233 Instead, attach a new host device to the guest and swap on that.
9234 swapon-file
9236 swapon-file file
9237 This command enables swap to a file. See "swapon-device" for other
9239 notes.
9240 swapon-label
9242 swapon-label label
9243 This command enables swap to a labeled swap partition. See "swapon-
9245 device" for other notes.
9246 swapon-uuid
9248 swapon-uuid uuid
9249 This command enables swap to a swap partition with the given UUID. See
9251 "swapon-device" for other notes.
9252 This command depends on the feature "linuxfsuuid". See also "feature-
9254 available".
9255 sync
9257 sync
9258 This syncs the disk, so that any writes are flushed through to the
9260 underlying disk image.
9261 You should always call this if you have modified a disk image, before
9263 closing the handle.
9264 syslinux
9266 syslinux device [directory:..]
9267 Install the SYSLINUX bootloader on "device".
9269 The device parameter must be either a whole disk formatted as a FAT
9271 filesystem, or a partition formatted as a FAT filesystem. In the
9272 latter case, the partition should be marked as "active" ("part-set-
9273 bootable") and a Master Boot Record must be installed (eg. using
9274 "pwrite-device") on the first sector of the whole disk. The SYSLINUX
9275 package comes with some suitable Master Boot Records. See the
9276 syslinux(1) man page for further information.
9277 The optional arguments are:
9279 directory
9281 Install SYSLINUX in the named subdirectory, instead of in the root
9282 directory of the FAT filesystem.
9283 Additional configuration can be supplied to SYSLINUX by placing a file
9285 called syslinux.cfg on the FAT filesystem, either in the root
9286 directory, or under directory if that optional argument is being used.
9287 For further information about the contents of this file, see
9288 syslinux(1).
9289 See also "extlinux".
9291 This command has one or more optional arguments. See "OPTIONAL
9293 ARGUMENTS".
9294 This command depends on the feature "syslinux". See also "feature-
9296 available".
9297 tail
9299 tail path
9300 This command returns up to the last 10 lines of a file as a list of
9302 strings.
9303 Because of the message protocol, there is a transfer limit of somewhere
9305 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9306 tail-n
9308 tail-n nrlines path
9309 If the parameter "nrlines" is a positive number, this returns the last
9311 "nrlines" lines of the file "path".
9312 If the parameter "nrlines" is a negative number, this returns lines
9314 from the file "path", starting with the "-nrlines"'th line.
9315 If the parameter "nrlines" is zero, this returns an empty list.
9317 Because of the message protocol, there is a transfer limit of somewhere
9319 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9320 tar-in
9322 tar-in-opts
9323 tar-in (tarfile|-) directory [compress:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9324 This command uploads and unpacks local file "tarfile" into directory.
9326 The optional "compress" flag controls compression. If not given, then
9328 the input should be an uncompressed tar file. Otherwise one of the
9329 following strings may be given to select the compression type of the
9330 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9331 all builds of libguestfs will support all of these compression types).
9332 The other optional arguments are:
9334 "xattrs"
9336 If set to true, extended attributes are restored from the tar file.
9337 "selinux"
9339 If set to true, SELinux contexts are restored from the tar file.
9340 "acls"
9342 If set to true, POSIX ACLs are restored from the tar file.
9343 Use "-" instead of a filename to read/write from stdin/stdout.
9345 This command has one or more optional arguments. See "OPTIONAL
9347 ARGUMENTS".
9348 tar-out
9350 tar-out-opts
9351 tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9352 This command packs the contents of directory and downloads it to local
9354 file "tarfile".
9355 The optional "compress" flag controls compression. If not given, then
9357 the output will be an uncompressed tar file. Otherwise one of the
9358 following strings may be given to select the compression type of the
9359 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9360 all builds of libguestfs will support all of these compression types).
9361 The other optional arguments are:
9363 "excludes"
9365 A list of wildcards. Files are excluded if they match any of the
9366 wildcards.
9367 "numericowner"
9369 If set to true, the output tar file will contain UID/GID numbers
9370 instead of user/group names.
9371 "xattrs"
9373 If set to true, extended attributes are saved in the output tar.
9374 "selinux"
9376 If set to true, SELinux contexts are saved in the output tar.
9377 "acls"
9379 If set to true, POSIX ACLs are saved in the output tar.
9380 Use "-" instead of a filename to read/write from stdin/stdout.
9382 This command has one or more optional arguments. See "OPTIONAL
9384 ARGUMENTS".
9385 tgz-in
9387 tgz-in (tarball|-) directory
9388 This command uploads and unpacks local file "tarball" (a gzip
9390 compressed tar file) into directory.
9391 Use "-" instead of a filename to read/write from stdin/stdout.
9393 This function is deprecated. In new code, use the "tar-in" call
9395 instead.
9396 Deprecated functions will not be removed from the API, but the fact
9398 that they are deprecated indicates that there are problems with correct
9399 use of these functions.
9400 tgz-out
9402 tgz-out directory (tarball|-)
9403 This command packs the contents of directory and downloads it to local
9405 file "tarball".
9406 Use "-" instead of a filename to read/write from stdin/stdout.
9408 This function is deprecated. In new code, use the "tar-out" call
9410 instead.
9411 Deprecated functions will not be removed from the API, but the fact
9413 that they are deprecated indicates that there are problems with correct
9414 use of these functions.
9415 touch
9417 touch path
9418 Touch acts like the touch(1) command. It can be used to update the
9420 timestamps on a file, or, if the file does not exist, to create a new
9421 zero-length file.
9422 This command only works on regular files, and will fail on other file
9424 types such as directories, symbolic links, block special etc.
9425 truncate
9427 truncate path
9428 This command truncates "path" to a zero-length file. The file must
9430 exist already.
9431 truncate-size
9433 truncate-size path size
9434 This command truncates "path" to size "size" bytes. The file must
9436 exist already.
9437 If the current file size is less than "size" then the file is extended
9439 to the required size with zero bytes. This creates a sparse file (ie.
9440 disk blocks are not allocated for the file until you write to it). To
9441 create a non-sparse file of zeroes, use "fallocate64" instead.
9442 tune2fs
9444 tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
9445 This call allows you to adjust various filesystem parameters of an
9447 ext2/ext3/ext4 filesystem called "device".
9448 The optional parameters are:
9450 "force"
9452 Force tune2fs to complete the operation even in the face of errors.
9453 This is the same as the tune2fs(8) "-f" option.
9454 "maxmountcount"
9456 Set the number of mounts after which the filesystem is checked by
9457 e2fsck(8). If this is 0 then the number of mounts is disregarded.
9458 This is the same as the tune2fs(8) "-c" option.
9459 "mountcount"
9461 Set the number of times the filesystem has been mounted. This is
9462 the same as the tune2fs(8) "-C" option.
9463 "errorbehavior"
9465 Change the behavior of the kernel code when errors are detected.
9466 Possible values currently are: "continue", "remount-ro", "panic".
9467 In practice these options don't really make any difference,
9468 particularly for write errors.
9469 This is the same as the tune2fs(8) "-e" option.
9471 "group"
9473 Set the group which can use reserved filesystem blocks. This is
9474 the same as the tune2fs(8) "-g" option except that it can only be
9475 specified as a number.
9476 "intervalbetweenchecks"
9478 Adjust the maximal time between two filesystem checks (in seconds).
9479 If the option is passed as 0 then time-dependent checking is
9480 disabled.
9481 This is the same as the tune2fs(8) "-i" option.
9483 "reservedblockspercentage"
9485 Set the percentage of the filesystem which may only be allocated by
9486 privileged processes. This is the same as the tune2fs(8) "-m"
9487 option.
9488 "lastmounteddirectory"
9490 Set the last mounted directory. This is the same as the tune2fs(8)
9491 "-M" option.
9492 "reservedblockscount" Set the number of reserved filesystem blocks.
9494 This is the same as the tune2fs(8) "-r" option.
9495 "user"
9496 Set the user who can use the reserved filesystem blocks. This is
9497 the same as the tune2fs(8) "-u" option except that it can only be
9498 specified as a number.
9499 To get the current values of filesystem parameters, see "tune2fs-l".
9501 For precise details of how tune2fs works, see the tune2fs(8) man page.
9502 This command has one or more optional arguments. See "OPTIONAL
9504 ARGUMENTS".
9505 tune2fs-l
9507 tune2fs-l device
9508 This returns the contents of the ext2, ext3 or ext4 filesystem
9510 superblock on "device".
9511 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
9513 for more details. The list of fields returned isn't clearly defined,
9514 and depends on both the version of "tune2fs" that libguestfs was built
9515 against, and the filesystem itself.
9516 txz-in
9518 txz-in (tarball|-) directory
9519 This command uploads and unpacks local file "tarball" (an xz compressed
9521 tar file) into directory.
9522 Use "-" instead of a filename to read/write from stdin/stdout.
9524 This function is deprecated. In new code, use the "tar-in" call
9526 instead.
9527 Deprecated functions will not be removed from the API, but the fact
9529 that they are deprecated indicates that there are problems with correct
9530 use of these functions.
9531 This command depends on the feature "xz". See also "feature-
9533 available".
9534 txz-out
9536 txz-out directory (tarball|-)
9537 This command packs the contents of directory and downloads it to local
9539 file "tarball" (as an xz compressed tar archive).
9540 Use "-" instead of a filename to read/write from stdin/stdout.
9542 This function is deprecated. In new code, use the "tar-out" call
9544 instead.
9545 Deprecated functions will not be removed from the API, but the fact
9547 that they are deprecated indicates that there are problems with correct
9548 use of these functions.
9549 This command depends on the feature "xz". See also "feature-
9551 available".
9552 umask
9554 umask mask
9555 This function sets the mask used for creating new files and device
9557 nodes to "mask & 0777".
9558 Typical umask values would be 022 which creates new files with
9560 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
9561 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
9562 The default umask is 022. This is important because it means that
9564 directories and device nodes will be created with 0644 or 0755 mode
9565 even if you specify 0777.
9566 See also "get-umask", umask(2), "mknod", "mkdir".
9568 This call returns the previous umask.
9570 umount
9572 unmount
9573 umount-opts
9574 umount pathordevice [force:true|false] [lazyunmount:true|false]
9575 This unmounts the given filesystem. The filesystem may be specified
9577 either by its mountpoint (path) or the device which contains the
9578 filesystem.
9579 This command has one or more optional arguments. See "OPTIONAL
9581 ARGUMENTS".
9582 umount-all
9584 unmount-all
9585 umount-all
9586 This unmounts all mounted filesystems.
9588 Some internal mounts are not unmounted by this call.
9590 umount-local
9592 umount-local [retry:true|false]
9593 If libguestfs is exporting the filesystem on a local mountpoint, then
9595 this unmounts it.
9596 See "MOUNT LOCAL" in guestfs(3) for full documentation.
9598 This command has one or more optional arguments. See "OPTIONAL
9600 ARGUMENTS".
9601 upload
9603 upload (filename|-) remotefilename
9604 Upload local file filename to remotefilename on the filesystem.
9606 filename can also be a named pipe.
9608 See also "download".
9610 Use "-" instead of a filename to read/write from stdin/stdout.
9612 upload-offset
9614 upload-offset (filename|-) remotefilename offset
9615 Upload local file filename to remotefilename on the filesystem.
9617 remotefilename is overwritten starting at the byte "offset" specified.
9619 The intention is to overwrite parts of existing files or devices,
9620 although if a non-existent file is specified then it is created with a
9621 "hole" before "offset". The size of the data written is implicit in
9622 the size of the source filename.
9623 Note that there is no limit on the amount of data that can be uploaded
9625 with this call, unlike with "pwrite", and this call always writes the
9626 full amount unless an error occurs.
9627 See also "upload", "pwrite".
9629 Use "-" instead of a filename to read/write from stdin/stdout.
9631 user-cancel
9633 user-cancel
9634 This function cancels the current upload or download operation.
9636 Unlike most other libguestfs calls, this function is signal safe and
9638 thread safe. You can call it from a signal handler or from another
9639 thread, without needing to do any locking.
9640 The transfer that was in progress (if there is one) will stop shortly
9642 afterwards, and will return an error. The errno (see
9643 "guestfs_last_errno") is set to "EINTR", so you can test for this to
9644 find out if the operation was cancelled or failed because of another
9645 error.
9646 No cleanup is performed: for example, if a file was being uploaded then
9648 after cancellation there may be a partially uploaded file. It is the
9649 caller’s responsibility to clean up if necessary.
9650 There are two common places that you might call "user-cancel":
9652 In an interactive text-based program, you might call it from a "SIGINT"
9654 signal handler so that pressing "^C" cancels the current operation.
9655 (You also need to call "set-pgroup" so that child processes don't
9656 receive the "^C" signal).
9657 In a graphical program, when the main thread is displaying a progress
9659 bar with a cancel button, wire up the cancel button to call this
9660 function.
9661 utimens
9663 utimens path atsecs atnsecs mtsecs mtnsecs
9664 This command sets the timestamps of a file with nanosecond precision.
9666 "atsecs", "atnsecs" are the last access time (atime) in secs and
9668 nanoseconds from the epoch.
9669 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
9671 nanoseconds from the epoch.
9672 If the *nsecs field contains the special value "-1" then the
9674 corresponding timestamp is set to the current time. (The *secs field
9675 is ignored in this case).
9676 If the *nsecs field contains the special value "-2" then the
9678 corresponding timestamp is left unchanged. (The *secs field is ignored
9679 in this case).
9680 utsname
9682 utsname
9683 This returns the kernel version of the appliance, where this is
9685 available. This information is only useful for debugging. Nothing in
9686 the returned structure is defined by the API.
9687 version
9689 version
9690 Return the libguestfs version number that the program is linked
9692 against.
9693 Note that because of dynamic linking this is not necessarily the
9695 version of libguestfs that you compiled against. You can compile the
9696 program, and then at runtime dynamically link against a completely
9697 different libguestfs.so library.
9698 This call was added in version 1.0.58. In previous versions of
9700 libguestfs there was no way to get the version number. From C code you
9701 can use dynamic linker functions to find out if this symbol exists (if
9702 it doesn't, then it’s an earlier version).
9703 The call returns a structure with four elements. The first three
9705 ("major", "minor" and "release") are numbers and correspond to the
9706 usual version triplet. The fourth element ("extra") is a string and is
9707 normally empty, but may be used for distro-specific information.
9708 To construct the original version string:
9710 "$major.$minor.$release$extra"
9711 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
9713 Note: Don't use this call to test for availability of features. In
9715 enterprise distributions we backport features from later versions into
9716 earlier versions, making this an unreliable way to test for features.
9717 Use "available" or "feature-available" instead.
9718 vfs-label
9720 vfs-label mountable
9721 This returns the label of the filesystem on "mountable".
9723 If the filesystem is unlabeled, this returns the empty string.
9725 To find a filesystem from the label, use "findfs-label".
9727 vfs-minimum-size
9729 vfs-minimum-size mountable
9730 Get the minimum size of filesystem in bytes. This is the minimum
9732 possible size for filesystem shrinking.
9733 If getting minimum size of specified filesystem is not supported, this
9735 will fail and set errno as ENOTSUP.
9736 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
9738 vfs-type
9740 vfs-type mountable
9741 This command gets the filesystem type corresponding to the filesystem
9743 on "mountable".
9744 For most filesystems, the result is the name of the Linux VFS module
9746 which would be used to mount this filesystem if you mounted it without
9747 specifying the filesystem type. For example a string such as "ext3" or
9748 "ntfs".
9749 vfs-uuid
9751 get-uuid
9752 vfs-uuid mountable
9753 This returns the filesystem UUID of the filesystem on "mountable".
9755 If the filesystem does not have a UUID, this returns the empty string.
9757 To find a filesystem from the UUID, use "findfs-uuid".
9759 vg-activate
9761 vg-activate true|false 'volgroups ...'
9762 This command activates or (if "activate" is false) deactivates all
9764 logical volumes in the listed volume groups "volgroups".
9765 This command is the same as running "vgchange -a y|n volgroups..."
9767 Note that if "volgroups" is an empty list then all volume groups are
9769 activated or deactivated.
9770 This command depends on the feature "lvm2". See also "feature-
9772 available".
9773 vg-activate-all
9775 vg-activate-all true|false
9776 This command activates or (if "activate" is false) deactivates all
9778 logical volumes in all volume groups.
9779 This command is the same as running "vgchange -a y|n"
9781 This command depends on the feature "lvm2". See also "feature-
9783 available".
9784 vgchange-uuid
9786 vgchange-uuid vg
9787 Generate a new random UUID for the volume group "vg".
9789 This command depends on the feature "lvm2". See also "feature-
9791 available".
9792 vgchange-uuid-all
9794 vgchange-uuid-all
9795 Generate new random UUIDs for all volume groups.
9797 This command depends on the feature "lvm2". See also "feature-
9799 available".
9800 vgcreate
9802 vgcreate volgroup 'physvols ...'
9803 This creates an LVM volume group called "volgroup" from the non-empty
9805 list of physical volumes "physvols".
9806 This command depends on the feature "lvm2". See also "feature-
9808 available".
9809 vglvuuids
9811 vglvuuids vgname
9812 Given a VG called "vgname", this returns the UUIDs of all the logical
9814 volumes created in this volume group.
9815 You can use this along with "lvs" and "lvuuid" calls to associate
9817 logical volumes and volume groups.
9818 See also "vgpvuuids".
9820 vgmeta
9822 vgmeta vgname
9823 "vgname" is an LVM volume group. This command examines the volume
9825 group and returns its metadata.
9826 Note that the metadata is an internal structure used by LVM, subject to
9828 change at any time, and is provided for information only.
9829 This command depends on the feature "lvm2". See also "feature-
9831 available".
9832 vgpvuuids
9834 vgpvuuids vgname
9835 Given a VG called "vgname", this returns the UUIDs of all the physical
9837 volumes that this volume group resides on.
9838 You can use this along with "pvs" and "pvuuid" calls to associate
9840 physical volumes and volume groups.
9841 See also "vglvuuids".
9843 vgremove
9845 vgremove vgname
9846 Remove an LVM volume group "vgname", (for example "VG").
9848 This also forcibly removes all logical volumes in the volume group (if
9850 any).
9851 This command depends on the feature "lvm2". See also "feature-
9853 available".
9854 vgrename
9856 vgrename volgroup newvolgroup
9857 Rename a volume group "volgroup" with the new name "newvolgroup".
9859 vgs
9861 vgs
9862 List all the volumes groups detected. This is the equivalent of the
9864 vgs(8) command.
9865 This returns a list of just the volume group names that were detected
9867 (eg. "VolGroup00").
9868 See also "vgs-full".
9870 This command depends on the feature "lvm2". See also "feature-
9872 available".
9873 vgs-full
9875 vgs-full
9876 List all the volumes groups detected. This is the equivalent of the
9878 vgs(8) command. The "full" version includes all fields.
9879 This command depends on the feature "lvm2". See also "feature-
9881 available".
9882 vgscan
9884 vgscan
9885 This rescans all block devices and rebuilds the list of LVM physical
9887 volumes, volume groups and logical volumes.
9888 This function is deprecated. In new code, use the "lvm-scan" call
9890 instead.
9891 Deprecated functions will not be removed from the API, but the fact
9893 that they are deprecated indicates that there are problems with correct
9894 use of these functions.
9895 vguuid
9897 vguuid vgname
9898 This command returns the UUID of the LVM VG named "vgname".
9900 wc-c
9902 wc-c path
9903 This command counts the characters in a file, using the "wc -c"
9905 external command.
9906 wc-l
9908 wc-l path
9909 This command counts the lines in a file, using the "wc -l" external
9911 command.
9912 wc-w
9914 wc-w path
9915 This command counts the words in a file, using the "wc -w" external
9917 command.
9918 wipefs
9920 wipefs device
9921 This command erases filesystem or RAID signatures from the specified
9923 "device" to make the filesystem invisible to libblkid.
9924 This does not erase the filesystem itself nor any other data from the
9926 "device".
9927 Compare with "zero" which zeroes the first few blocks of a device.
9929 This command depends on the feature "wipefs". See also "feature-
9931 available".
9932 write
9934 write path content
9935 This call creates a file called "path". The content of the file is the
9937 string "content" (which can contain any 8 bit data).
9938 See also "write-append".
9940 write-append
9942 write-append path content
9943 This call appends "content" to the end of file "path". If "path" does
9945 not exist, then a new file is created.
9946 See also "write".
9948 write-file
9950 write-file path content size
9951 This call creates a file called "path". The contents of the file is
9953 the string "content" (which can contain any 8 bit data), with length
9954 "size".
9955 As a special case, if "size" is 0 then the length is calculated using
9957 "strlen" (so in this case the content cannot contain embedded ASCII
9958 NULs).
9959 NB. Owing to a bug, writing content containing ASCII NUL characters
9961 does not work, even if the length is specified.
9962 Because of the message protocol, there is a transfer limit of somewhere
9964 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9965 This function is deprecated. In new code, use the "write" call
9967 instead.
9968 Deprecated functions will not be removed from the API, but the fact
9970 that they are deprecated indicates that there are problems with correct
9971 use of these functions.
9972 xfs-admin
9974 xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
9975 Change the parameters of the XFS filesystem on "device".
9977 Devices that are mounted cannot be modified. Administrators must
9979 unmount filesystems before this call can modify parameters.
9980 Some of the parameters of a mounted filesystem can be examined and
9982 modified using the "xfs-info" and "xfs-growfs" calls.
9983 Beginning with XFS version 5, it is no longer possible to modify the
9985 lazy-counters setting (ie. "lazycounter" parameter has no effect).
9986 This command has one or more optional arguments. See "OPTIONAL
9988 ARGUMENTS".
9989 This command depends on the feature "xfs". See also "feature-
9991 available".
9992 xfs-growfs
9994 xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
9995 Grow the XFS filesystem mounted at "path".
9997 The returned struct contains geometry information. Missing fields are
9999 returned as "-1" (for numeric fields) or empty string.
10000 This command has one or more optional arguments. See "OPTIONAL
10002 ARGUMENTS".
10003 This command depends on the feature "xfs". See also "feature-
10005 available".
10006 xfs-info
10008 xfs-info pathordevice
10009 "pathordevice" is a mounted XFS filesystem or a device containing an
10011 XFS filesystem. This command returns the geometry of the filesystem.
10012 The returned struct contains geometry information. Missing fields are
10014 returned as "-1" (for numeric fields) or empty string.
10015 This command depends on the feature "xfs". See also "feature-
10017 available".
10018 xfs-repair
10020 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:..]
10021 Repair corrupt or damaged XFS filesystem on "device".
10023 The filesystem is specified using the "device" argument which should be
10025 the device name of the disk partition or volume containing the
10026 filesystem. If given the name of a block device, "xfs_repair" will
10027 attempt to find the raw device associated with the specified block
10028 device and will use the raw device instead.
10029 Regardless, the filesystem to be repaired must be unmounted, otherwise,
10031 the resulting filesystem may be inconsistent or corrupt.
10032 The returned status indicates whether filesystem corruption was
10034 detected (returns 1) or was not detected (returns 0).
10035 This command has one or more optional arguments. See "OPTIONAL
10037 ARGUMENTS".
10038 This command depends on the feature "xfs". See also "feature-
10040 available".
10041 yara-destroy
10043 yara-destroy
10044 Destroy previously loaded Yara rules in order to free libguestfs
10046 resources.
10047 This command depends on the feature "libyara". See also "feature-
10049 available".
10050 yara-load
10052 yara-load (filename|-)
10053 Upload a set of Yara rules from local file filename.
10055 Yara rules allow to categorize files based on textual or binary
10057 patterns within their content. See "yara-scan" to see how to scan
10058 files with the loaded rules.
10059 Rules can be in binary format, as when compiled with yarac command, or
10061 in source code format. In the latter case, the rules will be first
10062 compiled and then loaded.
10063 Rules in source code format cannot include external files. In such
10065 cases, it is recommended to compile them first.
10066 Previously loaded rules will be destroyed.
10068 Use "-" instead of a filename to read/write from stdin/stdout.
10070 This command depends on the feature "libyara". See also "feature-
10072 available".
10073 yara-scan
10075 yara-scan path
10076 Scan a file with the previously loaded Yara rules.
10078 For each matching rule, a "yara_detection" structure is returned.
10080 The "yara_detection" structure contains the following fields.
10082 "yara_name"
10084 Path of the file matching a Yara rule.
10085 "yara_rule"
10087 Identifier of the Yara rule which matched against the given file.
10088 This command depends on the feature "libyara". See also "feature-
10090 available".
10091 zegrep
10093 zegrep regex path
10094 This calls the external "zegrep" program and returns the matching
10096 lines.
10097 Because of the message protocol, there is a transfer limit of somewhere
10099 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10100 This function is deprecated. In new code, use the "grep" call instead.
10102 Deprecated functions will not be removed from the API, but the fact
10104 that they are deprecated indicates that there are problems with correct
10105 use of these functions.
10106 zegrepi
10108 zegrepi regex path
10109 This calls the external "zegrep -i" program and returns the matching
10111 lines.
10112 Because of the message protocol, there is a transfer limit of somewhere
10114 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10115 This function is deprecated. In new code, use the "grep" call instead.
10117 Deprecated functions will not be removed from the API, but the fact
10119 that they are deprecated indicates that there are problems with correct
10120 use of these functions.
10121 zero
10123 zero device
10124 This command writes zeroes over the first few blocks of "device".
10126 How many blocks are zeroed isn't specified (but it’s not enough to
10128 securely wipe the device). It should be sufficient to remove any
10129 partition tables, filesystem superblocks and so on.
10130 If blocks are already zero, then this command avoids writing zeroes.
10132 This prevents the underlying device from becoming non-sparse or growing
10133 unnecessarily.
10134 See also: "zero-device", "scrub-device", "is-zero-device"
10136 zero-device
10138 zero-device device
10139 This command writes zeroes over the entire "device". Compare with
10141 "zero" which just zeroes the first few blocks of a device.
10142 If blocks are already zero, then this command avoids writing zeroes.
10144 This prevents the underlying device from becoming non-sparse or growing
10145 unnecessarily.
10146 zero-free-space
10148 zero-free-space directory
10149 Zero the free space in the filesystem mounted on directory. The
10151 filesystem must be mounted read-write.
10152 The filesystem contents are not affected, but any free space in the
10154 filesystem is freed.
10155 Free space is not "trimmed". You may want to call "fstrim" either as
10157 an alternative to this, or after calling this, depending on your
10158 requirements.
10159 zerofree
10161 zerofree device
10162 This runs the zerofree program on "device". This program claims to
10164 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
10165 it possible to compress the filesystem more effectively.
10166 You should not run this program if the filesystem is mounted.
10168 It is possible that using this program can damage the filesystem or
10170 data on the filesystem.
10171 This command depends on the feature "zerofree". See also "feature-
10173 available".
10174 zfgrep
10176 zfgrep pattern path
10177 This calls the external "zfgrep" program and returns the matching
10179 lines.
10180 Because of the message protocol, there is a transfer limit of somewhere
10182 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10183 This function is deprecated. In new code, use the "grep" call instead.
10185 Deprecated functions will not be removed from the API, but the fact
10187 that they are deprecated indicates that there are problems with correct
10188 use of these functions.
10189 zfgrepi
10191 zfgrepi pattern path
10192 This calls the external "zfgrep -i" program and returns the matching
10194 lines.
10195 Because of the message protocol, there is a transfer limit of somewhere
10197 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10198 This function is deprecated. In new code, use the "grep" call instead.
10200 Deprecated functions will not be removed from the API, but the fact
10202 that they are deprecated indicates that there are problems with correct
10203 use of these functions.
10204 zfile
10206 zfile meth path
10207 This command runs file(1) after first decompressing "path" using
10209 "meth".
10210 "meth" must be one of "gzip", "compress" or "bzip2".
10212 Since 1.0.63, use "file" instead which can now process compressed
10214 files.
10215 This function is deprecated. In new code, use the "file" call instead.
10217 Deprecated functions will not be removed from the API, but the fact
10219 that they are deprecated indicates that there are problems with correct
10220 use of these functions.
10221 zgrep
10223 zgrep regex path
10224 This calls the external zgrep(1) program and returns the matching
10226 lines.
10227 Because of the message protocol, there is a transfer limit of somewhere
10229 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10230 This function is deprecated. In new code, use the "grep" call instead.
10232 Deprecated functions will not be removed from the API, but the fact
10234 that they are deprecated indicates that there are problems with correct
10235 use of these functions.
10236 zgrepi
10238 zgrepi regex path
10239 This calls the external "zgrep -i" program and returns the matching
10241 lines.
10242 Because of the message protocol, there is a transfer limit of somewhere
10244 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10245 This function is deprecated. In new code, use the "grep" call instead.
10247 Deprecated functions will not be removed from the API, but the fact
10249 that they are deprecated indicates that there are problems with correct
10250 use of these functions.
10251
10253 guestfish returns 0 if the commands completed without error, or 1 if
10254 there was an error.
10255
10257 EDITOR
10258 The "edit" command uses $EDITOR as the editor. If not set, it uses
10259 "vi".
10260 GUESTFISH_DISPLAY_IMAGE
10262 The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
10263 images. If not set, it uses display(1).
10264 GUESTFISH_INIT
10266 Printed when guestfish starts. See "PROMPT".
10267 GUESTFISH_OUTPUT
10269 Printed before guestfish output. See "PROMPT".
10270 GUESTFISH_PID
10272 Used with the --remote option to specify the remote guestfish
10273 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
10274 SOCKET".
10275 GUESTFISH_PS1
10277 Set the command prompt. See "PROMPT".
10278 GUESTFISH_RESTORE
10280 Printed before guestfish exits. See "PROMPT".
10281 HEXEDITOR
10283 The "hexedit" command uses $HEXEDITOR as the external hex editor.
10284 If not specified, the external hexedit(1) program is used.
10285 HOME
10287 If compiled with GNU readline support, various files in the home
10288 directory can be used. See "FILES".
10289 LIBGUESTFS_APPEND
10291 Pass additional options to the guest kernel.
10292 LIBGUESTFS_ATTACH_METHOD
10294 This is the old way to set "LIBGUESTFS_BACKEND".
10295 LIBGUESTFS_BACKEND
10297 Choose the default way to create the appliance. See
10298 "guestfs_set_backend" in guestfs(3).
10299 LIBGUESTFS_BACKEND_SETTINGS
10301 A colon-separated list of backend-specific settings. See "BACKEND"
10302 in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
10303 LIBGUESTFS_CACHEDIR
10305 The location where libguestfs will cache its appliance, when using
10306 a supermin appliance. The appliance is cached and shared between
10307 all handles which have the same effective user ID.
10308 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
10310 "TMPDIR" is not set, then /var/tmp is used.
10311 See also "LIBGUESTFS_TMPDIR", "set-cachedir".
10313 LIBGUESTFS_DEBUG
10315 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
10316 same effect as using the -v option.
10317 LIBGUESTFS_HV
10319 Set the default hypervisor (usually qemu) binary that libguestfs
10320 uses. If not set, then the qemu which was found at compile time by
10321 the configure script is used.
10322 LIBGUESTFS_MEMSIZE
10324 Set the memory allocated to the qemu process, in megabytes. For
10325 example:
10326 LIBGUESTFS_MEMSIZE=700
10328 LIBGUESTFS_PATH
10330 Set the path that guestfish uses to search for kernel and
10331 initrd.img. See the discussion of paths in guestfs(3).
10332 LIBGUESTFS_QEMU
10334 This is the old way to set "LIBGUESTFS_HV".
10335 LIBGUESTFS_TMPDIR
10337 The location where libguestfs will store temporary files used by
10338 each handle.
10339 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
10341 "TMPDIR" is not set, then /tmp is used.
10342 See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
10344 LIBGUESTFS_TRACE
10346 Set "LIBGUESTFS_TRACE=1" to enable command traces.
10347 PAGER
10349 The "more" command uses $PAGER as the pager. If not set, it uses
10350 "more".
10351 PATH
10353 Libguestfs and guestfish may run some external programs, and rely
10354 on $PATH being set to a reasonable value. If using the libvirt
10355 backend, libvirt will not work at all unless $PATH contains the
10356 path of qemu/KVM.
10357 SUPERMIN_KERNEL
10359 SUPERMIN_KERNEL_VERSION
10360 SUPERMIN_MODULES
10361 These three environment variables allow the kernel that libguestfs
10362 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
10363 set, then the most recent host kernel is chosen. For more
10364 information about kernel selection, see supermin(1).
10365 TMPDIR
10367 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
10368 XDG_RUNTIME_DIR
10370 This directory represents a user-specific directory for storing
10371 non-essential runtime files.
10372 If it is set, then is used to store temporary sockets. Otherwise,
10374 /tmp is used.
10375 See also "get-sockdir",
10377 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
10378
10380 $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
10381 $HOME/.libguestfs-tools.rc
10382 $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
10383 /etc/libguestfs-tools.conf
10384 This configuration file controls the default read-only or read-
10385 write mode (--ro or --rw).
10386 See libguestfs-tools.conf(5).
10388 $HOME/.guestfish
10390 If compiled with GNU readline support, then the command history is
10391 saved in this file.
10392 $HOME/.inputrc
10394 /etc/inputrc
10395 If compiled with GNU readline support, then these files can be used
10396 to configure readline. For further information, please see
10397 "INITIALIZATION FILE" in readline(3).
10398 To write rules which only apply to guestfish, use:
10400 $if guestfish
10402 ...
10403 $endif
10404 Variables that you can set in inputrc that change the behaviour of
10406 guestfish in useful ways include:
10407 completion-ignore-case (default: on)
10409 By default, guestfish will ignore case when tab-completing
10410 paths on the disk. Use:
10411 set completion-ignore-case off
10413 to make guestfish case sensitive.
10415 test1.img
10417 test2.img (etc)
10418 When using the -N or --new option, the prepared disk or filesystem
10419 will be created in the file test1.img in the current directory.
10420 The second use of -N will use test2.img and so on. Any existing
10421 file with the same name will be overwritten. You can use a
10422 different filename by using the "filename=" prefix.
10423
10425 guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
10426 virt-builder(1), virt-builder-repository(1), virt-cat(1),
10427 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
10428 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1),
10429 virt-list-filesystems(1), virt-list-partitions(1), virt-log(1),
10430 virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
10431 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
10432 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
10433 virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1),
10434 supermin(1).
10435
10437 Richard W.M. Jones ("rjones at redhat dot com")
10438
10440 Copyright (C) 2009-2020 Red Hat Inc.
10441
10443 This program is free software; you can redistribute it and/or modify it
10444 under the terms of the GNU General Public License as published by the
10445 Free Software Foundation; either version 2 of the License, or (at your
10446 option) any later version.
10447 This program is distributed in the hope that it will be useful, but
10449 WITHOUT ANY WARRANTY; without even the implied warranty of
10450 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10451 General Public License for more details.
10452 You should have received a copy of the GNU General Public License along
10454 with this program; if not, write to the Free Software Foundation, Inc.,
10455 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
10456
10458 To get a list of bugs against libguestfs, use this link:
10459 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
10460 To report a new bug against libguestfs, use this link:
10462 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
10463 When reporting a bug, please supply:
10465 • The version of libguestfs.
10467 • Where you got libguestfs (eg. which Linux distro, compiled from
10469 source, etc)
10470 • Describe the bug accurately and give a way to reproduce it.
10472 • Run libguestfs-test-tool(1) and paste the complete, unedited output
10474 into the bug report.
10475libguestfs-1.48.3 2022-05-26 guestfish(1)