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 -c URI
177 --connect URI
178 When used in conjunction with the -d option, this specifies the
179 libvirt URI to use. The default is to use the default libvirt
180 connection.
181 --csh
183 If using the --listen option and a csh-like shell, use this option.
184 See section "REMOTE CONTROL AND CSH" below.
185 -d LIBVIRT-DOMAIN
187 --domain LIBVIRT-DOMAIN
188 Add disks from the named libvirt domain. If the --ro option is
189 also used, then any libvirt domain can be used. However in write
190 mode, only libvirt domains which are shut down can be named here.
191 Domain UUIDs can be used instead of names.
193 Using this flag is mostly equivalent to using the "add-domain"
195 command, with "readonly:true" if the --ro flag was given, and with
196 "format:..." if the --format=... flag was given.
197 --echo-keys
199 When prompting for keys and passphrases, guestfish normally turns
200 echoing off so you cannot see what you are typing. If you are not
201 worried about Tempest attacks and there is no one else in the room
202 you can specify this flag to see what you are typing.
203 -f FILE
205 --file FILE
206 Read commands from "FILE". To write pure guestfish scripts, use:
207 #!/usr/bin/guestfish -f
209 --format=raw|qcow2|..
211 --format
212 The default for the -a option is to auto-detect the format of the
213 disk image. Using this forces the disk format for -a options which
214 follow on the command line. Using --format with no argument
215 switches back to auto-detection for subsequent -a options.
216 For example:
218 guestfish --format=raw -a disk.img
220 forces raw format (no auto-detection) for disk.img.
222 guestfish --format=raw -a disk.img --format -a another.img
224 forces raw format (no auto-detection) for disk.img and reverts to
226 auto-detection for another.img.
227 If you have untrusted raw-format guest disk images, you should use
229 this option to specify the disk format. This avoids a possible
230 security problem with malicious guests (CVE-2010-3851). See also
231 "add".
232 -i
234 --inspector
235 Using virt-inspector(1) code, inspect the disks looking for an
236 operating system and mount filesystems as they would be mounted on
237 the real virtual machine.
238 Typical usage is either:
240 guestfish -d myguest -i
242 (for an inactive libvirt domain called myguest), or:
244 guestfish --ro -d myguest -i
246 (for active domains, readonly), or specify the block device
248 directly:
249 guestfish --rw -a /dev/Guests/MyGuest -i
251 Note that the command line syntax changed slightly over older
253 versions of guestfish. You can still use the old syntax:
254 guestfish [--ro] -i disk.img
256 guestfish [--ro] -i libvirt-domain
258 Using this flag is mostly equivalent to using the "inspect-os"
260 command and then using other commands to mount the filesystems that
261 were found.
262 --key SELECTOR
264 Specify a key for LUKS, to automatically open a LUKS device when
265 using the inspection. "SELECTOR" can be in one of the following
266 formats:
267 --key "DEVICE":key:KEY_STRING
269 Use the specified "KEY_STRING" as passphrase.
270 --key "DEVICE":file:FILENAME
272 Read the passphrase from FILENAME.
273 --keys-from-stdin
275 Read key or passphrase parameters from stdin. The default is to
276 try to read passphrases from the user by opening /dev/tty.
277 --listen
279 Fork into the background and listen for remote commands. See
280 section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
281 --live
283 Connect to a live virtual machine. (Experimental, see "ATTACHING
284 TO RUNNING DAEMONS" in guestfs(3)).
285 -m dev[:mountpoint[:options[:fstype]]]
287 --mount dev[:mountpoint[:options[:fstype]]]
288 Mount the named partition or logical volume on the given
289 mountpoint.
290 If the mountpoint is omitted, it defaults to /.
292 You have to mount something on / before most commands will work.
294 If any -m or --mount options are given, the guest is automatically
296 launched.
297 If you don’t know what filesystems a disk image contains, you can
299 either run guestfish without this option, then list the partitions,
300 filesystems and LVs available (see "list-partitions", "list-
301 filesystems" and "lvs" commands), or you can use the
302 virt-filesystems(1) program.
303 The third (and rarely used) part of the mount parameter is the list
305 of mount options used to mount the underlying filesystem. If this
306 is not given, then the mount options are either the empty string or
307 "ro" (the latter if the --ro flag is used). By specifying the
308 mount options, you override this default choice. Probably the only
309 time you would use this is to enable ACLs and/or extended
310 attributes if the filesystem can support them:
311 -m /dev/sda1:/:acl,user_xattr
313 Using this flag is equivalent to using the "mount-options" command.
315 The fourth part of the parameter is the filesystem driver to use,
317 such as "ext3" or "ntfs". This is rarely needed, but can be useful
318 if multiple drivers are valid for a filesystem (eg: "ext2" and
319 "ext3"), or if libguestfs misidentifies a filesystem.
320 --network
322 Enable QEMU user networking in the guest.
323 -N [FILENAME=]TYPE
325 --new [FILENAME=]TYPE
326 -N help
327 Prepare a fresh disk image formatted as "TYPE". This is an
328 alternative to the -a option: whereas -a adds an existing disk, -N
329 creates a preformatted disk with a filesystem and adds it. See
330 "PREPARED DISK IMAGES" below.
331 -n
333 --no-sync
334 Disable autosync. This is enabled by default. See the discussion
335 of autosync in the guestfs(3) manpage.
336 --no-dest-paths
338 Don’t tab-complete paths on the guest filesystem. It is useful to
339 be able to hit the tab key to complete paths on the guest
340 filesystem, but this causes extra "hidden" guestfs calls to be
341 made, so this option is here to allow this feature to be disabled.
342 --pipe-error
344 If writes fail to pipe commands (see "PIPES" below), then the
345 command returns an error.
346 The default (also for historical reasons) is to ignore such errors
348 so that:
349 ><fs> command_with_lots_of_output | head
351 doesn't give an error.
353 --progress-bars
355 Enable progress bars, even when guestfish is used non-
356 interactively.
357 Progress bars are enabled by default when guestfish is used as an
359 interactive shell.
360 --no-progress-bars
362 Disable progress bars.
363 --remote
365 --remote=PID
366 Send remote commands to $GUESTFISH_PID or "pid". See section
367 "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
368 -r
370 --ro
371 This changes the -a, -d and -m options so that disks are added and
372 mounts are done read-only.
373 The option must always be used if the disk image or virtual machine
375 might be running, and is generally recommended in cases where you
376 don't need write access to the disk.
377 Note that prepared disk images created with -N are not affected by
379 this option. Also commands like "add" are not affected - you have
380 to specify the "readonly:true" option explicitly if you need it.
381 See also "OPENING DISKS FOR READ AND WRITE" below.
383 --selinux
385 This option is provided for backwards compatibility and does
386 nothing.
387 -v
389 --verbose
390 Enable very verbose messages. This is particularly useful if you
391 find a bug.
392 -V
394 --version
395 Display the guestfish / libguestfs version number and exit.
396 -w
398 --rw
399 This changes the -a, -d and -m options so that disks are added and
400 mounts are done read-write.
401 See "OPENING DISKS FOR READ AND WRITE" below.
403 -x Echo each command before executing it.
405
407 Any additional (non-option) arguments are treated as commands to
408 execute.
409 Commands to execute should be separated by a colon (":"), where the
411 colon is a separate parameter. Thus:
412 guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
414 If there are no additional arguments, then we enter a shell, either an
416 interactive shell with a prompt (if the input is a terminal) or a non-
417 interactive shell.
418 In either command line mode or non-interactive shell, the first command
420 that gives an error causes the whole shell to exit. In interactive
421 mode (with a prompt) if a command fails, you can continue to enter
422 commands.
423 Note that arguments of the commands will be considered as guestfish
425 options if they start with a dash ("-"): you can always separate the
426 guestfish options and the rest of the commands (with their arguments)
427 using a double dash ("--"). For example:
428 guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img
430
432 As with guestfs(3), you must first configure your guest by adding
433 disks, then launch it, then mount any disks you need, and finally issue
434 actions/commands. So the general order of the day is:
435 · add or -a/--add
437 · launch (aka run)
439 · mount or -m/--mount
441 · any other commands
443 "run" is a synonym for "launch". You must "launch" (or "run") your
445 guest before mounting or performing any other commands.
446 The only exception is that if any of the -i, -m, --mount, -N or --new
448 options were given then "run" is done automatically, simply because
449 guestfish can't perform the action you asked for without doing this.
450
452 The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
453 affect whether the other command line options -a, -c, -d, -i and -m
454 open disk images read-only or for writing.
455 In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
457 to opening disk images supplied on the command line for write. To open
458 a disk image read-only you have to do -a image --ro.
459 This matters: If you accidentally open a live VM disk image writable
461 then you will cause irreversible disk corruption.
462 In a future libguestfs we intend to change the default the other way.
464 Disk images will be opened read-only. You will have to either specify
465 guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
466 configuration file in order to get write access for disk images
467 specified by those other command line options.
468 This version of guestfish, guestmount and virt-rescue has a --rw option
470 which does nothing (it is already the default). However it is highly
471 recommended that you use this option to indicate that you need write
472 access, and prepare your scripts for the day when this option will be
473 required for write access.
474 Note: This does not affect commands like "add" and "mount", or any
476 other libguestfs program apart from guestfish and guestmount.
477
479 You can quote ordinary parameters using either single or double quotes.
480 For example:
481 add "file with a space.img"
483 rm '/file name'
485 rm '/"'
487 A few commands require a list of strings to be passed. For these, use
489 a whitespace-separated list, enclosed in quotes. Strings containing
490 whitespace to be passed through must be enclosed in single quotes. A
491 literal single quote must be escaped with a backslash.
492 vgcreate VG "/dev/sda1 /dev/sdb1"
494 command "/bin/echo 'foo bar'"
495 command "/bin/echo \'foo\'"
496 ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
498 In double-quoted arguments (only) use backslash to insert special
499 characters:
500 "\a"
502 Alert (bell) character.
503 "\b"
505 Backspace character.
506 "\f"
508 Form feed character.
509 "\n"
511 Newline character.
512 "\r"
514 Carriage return character.
515 "\t"
517 Horizontal tab character.
518 "\v"
520 Vertical tab character.
521 "\""
523 A literal double quote character.
524 "\ooo"
526 A character with octal value ooo. There must be precisely 3 octal
527 digits (unlike C).
528 "\xhh"
530 A character with hex value hh. There must be precisely 2 hex
531 digits.
532 In the current implementation "\000" and "\x00" cannot be used in
534 strings.
535 "\\"
537 A literal backslash character.
538
540 Some commands take optional arguments. These arguments appear in this
541 documentation as "[argname:..]". You can use them as in these
542 examples:
543 add filename
545 add filename readonly:true
547 add filename format:qcow2 readonly:false
549 Each optional argument can appear at most once. All optional arguments
551 must appear after the required ones.
552
554 This section applies to all commands which can take integers as
555 parameters.
556 SIZE SUFFIX
558 When the command takes a parameter measured in bytes, you can use one
559 of the following suffixes to specify kilobytes, megabytes and larger
560 sizes:
561 k or K or KiB
563 The size in kilobytes (multiplied by 1024).
564 KB The size in SI 1000 byte units.
566 M or MiB
568 The size in megabytes (multiplied by 1048576).
569 MB The size in SI 1000000 byte units.
571 G or GiB
573 The size in gigabytes (multiplied by 2**30).
574 GB The size in SI 10**9 byte units.
576 T or TiB
578 The size in terabytes (multiplied by 2**40).
579 TB The size in SI 10**12 byte units.
581 P or PiB
583 The size in petabytes (multiplied by 2**50).
584 PB The size in SI 10**15 byte units.
586 E or EiB
588 The size in exabytes (multiplied by 2**60).
589 EB The size in SI 10**18 byte units.
591 Z or ZiB
593 The size in zettabytes (multiplied by 2**70).
594 ZB The size in SI 10**21 byte units.
596 Y or YiB
598 The size in yottabytes (multiplied by 2**80).
599 YB The size in SI 10**24 byte units.
601 For example:
603 truncate-size /file 1G
605 would truncate the file to 1 gigabyte.
607 Be careful because a few commands take sizes in kilobytes or megabytes
609 (eg. the parameter to "memsize" is specified in megabytes already).
610 Adding a suffix will probably not do what you expect.
611 OCTAL AND HEXADECIMAL NUMBERS
613 For specifying the radix (base) use the C convention: 0 to prefix an
614 octal number or "0x" to prefix a hexadecimal number. For example:
615 1234 decimal number 1234
617 02322 octal number, equivalent to decimal 1234
618 0x4d2 hexadecimal number, equivalent to decimal 1234
619 When using the "chmod" command, you almost always want to specify an
621 octal number for the mode, and you must prefix it with 0 (unlike the
622 Unix chmod(1) program):
623 chmod 0777 /public # OK
625 chmod 777 /public # WRONG! This is mode 777 decimal = 01411 octal.
626 Commands that return numbers usually print them in decimal, but some
628 commands print numbers in other radices (eg. "umask" prints the mode in
629 octal, preceded by 0).
630
632 Neither guestfish nor the underlying guestfs API performs wildcard
633 expansion (globbing) by default. So for example the following will not
634 do what you expect:
635 rm-rf /home/*
637 Assuming you don’t have a directory called literally /home/* then the
639 above command will return an error.
640 To perform wildcard expansion, use the "glob" command.
642 glob rm-rf /home/*
644 runs "rm-rf" on each path that matches (ie. potentially running the
646 command many times), equivalent to:
647 rm-rf /home/jim
649 rm-rf /home/joe
650 rm-rf /home/mary
651 "glob" only works on simple guest paths and not on device names.
653 If you have several parameters, each containing a wildcard, then glob
655 will perform a Cartesian product.
656
658 Any line which starts with a # character is treated as a comment and
659 ignored. The # can optionally be preceded by whitespace, but not by a
660 command. For example:
661 # this is a comment
663 # this is a comment
664 foo # NOT a comment
665 Blank lines are also ignored.
667
669 Any line which starts with a ! character is treated as a command sent
670 to the local shell (/bin/sh or whatever system(3) uses). For example:
671 !mkdir local
673 tgz-out /remote local/remote-data.tar.gz
674 will create a directory "local" on the host, and then export the
676 contents of /remote on the mounted filesystem to
677 local/remote-data.tar.gz. (See "tgz-out").
678 To change the local directory, use the "lcd" command. "!cd" will have
680 no effect, due to the way that subprocesses work in Unix.
681 LOCAL COMMANDS WITH INLINE EXECUTION
683 If a line starts with <! then the shell command is executed (as for !),
684 but subsequently any output (stdout) of the shell command is parsed and
685 executed as guestfish commands.
686 Thus you can use shell script to construct arbitrary guestfish commands
688 which are then parsed by guestfish.
689 For example it is tedious to create a sequence of files (eg. /foo.1
691 through /foo.100) using guestfish commands alone. However this is
692 simple if we use a shell script to create the guestfish commands for
693 us:
694 <! for n in `seq 1 100`; do echo write /foo.$n $n; done
696 or with names like /foo.001:
698 <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
700 When using guestfish interactively it can be helpful to just run the
702 shell script first (ie. remove the initial "<" character so it is just
703 an ordinary ! local command), see what guestfish commands it would run,
704 and when you are happy with those prepend the "<" character to run the
705 guestfish commands for real.
706
708 Use "command <space> | command" to pipe the output of the first command
709 (a guestfish command) to the second command (any host command). For
710 example:
711 cat /etc/passwd | awk -F: '$3 == 0 { print }'
713 (where "cat" is the guestfish cat command, but "awk" is the host awk
715 program). The above command would list all accounts in the guest
716 filesystem which have UID 0, ie. root accounts including backdoors.
717 Other examples:
718 hexdump /bin/ls | head
720 list-devices | tail -1
721 tgz-out / - | tar ztf -
722 The space before the pipe symbol is required, any space after the pipe
724 symbol is optional. Everything after the pipe symbol is just passed
725 straight to the host shell, so it can contain redirections, globs and
726 anything else that makes sense on the host side.
727 To use a literal argument which begins with a pipe symbol, you have to
729 quote it, eg:
730 echo "|"
732
734 If a parameter starts with the character "~" then the tilde may be
735 expanded as a home directory path (either "~" for the current user's
736 home directory, or "~user" for another user).
737 Note that home directory expansion happens for users known on the host,
739 not in the guest filesystem.
740 To use a literal argument which begins with a tilde, you have to quote
742 it, eg:
743 echo "~"
745
747 Libguestfs has some support for Linux guests encrypted according to the
748 Linux Unified Key Setup (LUKS) standard, which includes nearly all
749 whole disk encryption systems used by modern Linux guests. Currently
750 only LVM-on-LUKS is supported.
751 Identify encrypted block devices and partitions using "vfs-type":
753 ><fs> vfs-type /dev/sda2
755 crypto_LUKS
756 Then open those devices using "luks-open". This creates a device-
758 mapper device called /dev/mapper/luksdev.
759 ><fs> luks-open /dev/sda2 luksdev
761 Enter key or passphrase ("key"): <enter the passphrase>
762 Finally you have to tell LVM to scan for volume groups on the newly
764 created mapper device:
765 vgscan
767 vg-activate-all true
768 The logical volume(s) can now be mounted in the usual way.
770 Before closing a LUKS device you must unmount any logical volumes on it
772 and deactivate the volume groups by calling "vg-activate false VG" on
773 each one. Then you can close the mapper device:
774 vg-activate false /dev/VG
776 luks-close /dev/mapper/luksdev
777
779 If a path is prefixed with "win:" then you can use Windows-style drive
780 letters and paths (with some limitations). The following commands are
781 equivalent:
782 file /WINDOWS/system32/config/system.LOG
784 file win:\windows\system32\config\system.log
786 file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
788 The parameter is rewritten "behind the scenes" by looking up the
790 position where the drive is mounted, prepending that to the path,
791 changing all backslash characters to forward slash, then resolving the
792 result using "case-sensitive-path". For example if the E: drive was
793 mounted on /e then the parameter might be rewritten like this:
794 win:e:\foo\bar => /e/FOO/bar
796 This only works in argument positions that expect a path.
798
800 For commands such as "upload", "download", "tar-in", "tar-out" and
801 others which upload from or download to a local file, you can use the
802 special filename "-" to mean "from stdin" or "to stdout". For example:
803 upload - /foo
805 reads stdin and creates from that a file /foo in the disk image, and:
807 tar-out /etc - | tar tf -
809 writes the tarball to stdout and then pipes that into the external
811 "tar" command (see "PIPES").
812 When using "-" to read from stdin, the input is read up to the end of
814 stdin. You can also use a special "heredoc"-like syntax to read up to
815 some arbitrary end marker:
816 upload -<<END /foo
818 input line 1
819 input line 2
820 input line 3
821 END
822 Any string of characters can be used instead of "END". The end marker
824 must appear on a line of its own, without any preceding or following
825 characters (not even spaces).
826 Note that the "-<<" syntax only applies to parameters used to upload
828 local files (so-called "FileIn" parameters in the generator).
829
831 By default, guestfish will ignore any errors when in interactive mode
832 (ie. taking commands from a human over a tty), and will exit on the
833 first error in non-interactive mode (scripts, commands given on the
834 command line).
835 If you prefix a command with a - character, then that command will not
837 cause guestfish to exit, even if that (one) command returns an error.
838
840 Guestfish can be remote-controlled over a socket. This is useful
841 particularly in shell scripts where you want to make several different
842 changes to a filesystem, but you don't want the overhead of starting up
843 a guestfish process each time.
844 Start a guestfish server process using:
846 eval "`guestfish --listen`"
848 and then send it commands by doing:
850 guestfish --remote cmd [...]
852 To cause the server to exit, send it the exit command:
854 guestfish --remote exit
856 Note that the server will normally exit if there is an error in a
858 command. You can change this in the usual way. See section "EXIT ON
859 ERROR BEHAVIOUR".
860 CONTROLLING MULTIPLE GUESTFISH PROCESSES
862 The "eval" statement sets the environment variable $GUESTFISH_PID,
863 which is how the --remote option knows where to send the commands. You
864 can have several guestfish listener processes running using:
865 eval "`guestfish --listen`"
867 pid1=$GUESTFISH_PID
868 eval "`guestfish --listen`"
869 pid2=$GUESTFISH_PID
870 ...
871 guestfish --remote=$pid1 cmd
872 guestfish --remote=$pid2 cmd
873 REMOTE CONTROL AND CSH
875 When using csh-like shells (csh, tcsh etc) you have to add the --csh
876 option:
877 eval "`guestfish --listen --csh`"
879 REMOTE CONTROL DETAILS
881 Remote control happens over a Unix domain socket called
882 /tmp/.guestfish-$UID/socket-$PID, where $UID is the effective user ID
883 of the process, and $PID is the process ID of the server.
884 Guestfish client and server versions must match exactly.
886 Older versions of guestfish were vulnerable to CVE-2013-4419 (see
888 "CVE-2013-4419" in guestfs(3)). This is fixed in the current version.
889 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
891 From Bash, you can use the following code which creates a guestfish
892 instance, correctly quotes the command line, handles failure to start,
893 and cleans up guestfish when the script exits:
894 #!/bin/bash -
896 set -e
898 guestfish[0]="guestfish"
900 guestfish[1]="--listen"
901 guestfish[2]="--ro"
902 guestfish[3]="-a"
903 guestfish[4]="disk.img"
904 GUESTFISH_PID=
906 eval $("${guestfish[@]}")
907 if [ -z "$GUESTFISH_PID" ]; then
908 echo "error: guestfish didn't start up, see error messages above"
909 exit 1
910 fi
911 cleanup_guestfish ()
913 {
914 guestfish --remote -- exit >/dev/null 2>&1 ||:
915 }
916 trap cleanup_guestfish EXIT ERR
917 guestfish --remote -- run
919 # ...
921 REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
923 Options such as -a, --add, -N, --new etc don’t interact properly with
924 remote support. They are processed locally, and not sent through to
925 the remote guestfish. In particular this won't do what you expect:
926 guestfish --remote --add disk.img
928 Don’t use these options. Use the equivalent commands instead, eg:
930 guestfish --remote add-drive disk.img
932 or:
934 guestfish --remote
936 ><fs> add disk.img
937 REMOTE CONTROL RUN COMMAND HANGING
939 Using the "run" (or "launch") command remotely in a command
940 substitution context hangs, ie. don't do (note the backquotes):
941 a=`guestfish --remote run`
943 Since the "run" command produces no output on stdout, this is not
945 useful anyway. For further information see
946 https://bugzilla.redhat.com/show_bug.cgi?id=592910.
947
949 Use the -N [filename=]type or --new [filename=]type parameter to select
950 one of a set of preformatted disk images that guestfish can make for
951 you to save typing. This is particularly useful for testing purposes.
952 This option is used instead of the -a option, and like -a can appear
953 multiple times (and can be mixed with -a).
954 The new disk is called test1.img for the first -N, test2.img for the
956 second and so on. Existing files in the current directory are
957 overwritten. You can use a different filename by specifying
958 "filename=" before the type (see examples below).
959 The type briefly describes how the disk should be sized, partitioned,
961 how filesystem(s) should be created, and how content should be added.
962 Optionally the type can be followed by extra parameters, separated by
963 ":" (colon) characters. For example, -N fs creates a default 1G,
964 sparsely-allocated disk, containing a single partition, with the
965 partition formatted as ext2. -N fs:ext4:2G is the same, but for an
966 ext4 filesystem on a 2GB disk instead.
967 Note that the prepared filesystem is not mounted. You would usually
969 have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
970 option.
971 If any -N or --new options are given, the libguestfs appliance is
973 automatically launched.
974 EXAMPLES
976 Create a 1G disk with an ext4-formatted partition, called test1.img in
977 the current directory:
978 guestfish -N fs:ext4
980 Create a 32MB disk with a VFAT-formatted partition, and mount it:
982 guestfish -N fs:vfat:32M -m /dev/sda1
984 Create a blank 200MB disk:
986 guestfish -N disk:200M
988 Create a blank 200MB disk called blankdisk.img (instead of test1.img):
990 guestfish -N blankdisk.img=disk:200M
992 -N disk - create a blank disk
994 "guestfish -N [filename=]disk[:size]"
995 Create a blank disk, size 1G (by default).
997 The default size can be changed by supplying an optional parameter.
999 The optional parameters are:
1001 Name Default value
1003 size 1G the size of the disk image
1004 -N part - create a partitioned disk
1006 "guestfish -N [filename=]part[:size[:partition]]"
1007 Create a disk with a single partition. By default the size of the disk
1009 is 1G (the available space in the partition will be a tiny bit smaller)
1010 and the partition table will be MBR (old DOS-style).
1011 These defaults can be changed by supplying optional parameters.
1013 The optional parameters are:
1015 Name Default value
1017 size 1G the size of the disk image
1018 partition mbr partition table type
1019 -N fs - create a filesystem
1021 "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"
1022 Create a disk with a single partition, with the partition containing an
1024 empty filesystem. This defaults to creating a 1G disk (the available
1025 space in the filesystem will be a tiny bit smaller) with an MBR (old
1026 DOS-style) partition table and an ext2 filesystem.
1027 These defaults can be changed by supplying optional parameters.
1029 The optional parameters are:
1031 Name Default value
1033 filesystem ext2 the type of filesystem to use
1034 size 1G the size of the disk image
1035 partition mbr partition table type
1036 -N lv - create a disk with logical volume
1038 "guestfish -N [filename=]lv[:name[:size[:partition]]]"
1039 Create a disk with a single partition, set up the partition as an LVM2
1041 physical volume, and place a volume group and logical volume on there.
1042 This defaults to creating a 1G disk with the VG and LV called
1043 "/dev/VG/LV". You can change the name of the VG and LV by supplying an
1044 alternate name as the first optional parameter.
1045 Note this does not create a filesystem. Use 'lvfs' to do that.
1047 The optional parameters are:
1049 Name Default value
1051 name /dev/VG/LV the name of the VG and LV to use
1052 size 1G the size of the disk image
1053 partition mbr partition table type
1054 -N lvfs - create a disk with logical volume and filesystem
1056 "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"
1057 Create a disk with a single partition, set up the partition as an LVM2
1059 physical volume, and place a volume group and logical volume on there.
1060 Then format the LV with a filesystem. This defaults to creating a 1G
1061 disk with the VG and LV called "/dev/VG/LV", with an ext2 filesystem.
1062 The optional parameters are:
1064 Name Default value
1066 name /dev/VG/LV the name of the VG and LV to use
1067 filesystem ext2 the type of filesystem to use
1068 size 1G the size of the disk image
1069 partition mbr partition table type
1070 -N bootroot - create a boot and root filesystem
1072 "guestfish -N
1073 [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"
1074 Create a disk with two partitions, for boot and root filesystem.
1076 Format the two filesystems independently. There are several optional
1077 parameters which control the exact layout and filesystem types.
1078 The optional parameters are:
1080 Name Default value
1082 bootfs ext2 the type of filesystem to use for boot
1083 rootfs ext2 the type of filesystem to use for root
1084 size 1G the size of the disk image
1085 bootsize 128M the size of the boot filesystem
1086 partition mbr partition table type
1087 -N bootrootlv - create a boot and root filesystem using LVM
1089 "guestfish -N
1090 [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"
1091 This is the same as "bootroot" but the root filesystem (only) is placed
1093 on a logical volume, named by default "/dev/VG/LV". There are several
1094 optional parameters which control the exact layout.
1095 The optional parameters are:
1097 Name Default value
1099 name /dev/VG/LV the name of the VG and LV for root
1100 bootfs ext2 the type of filesystem to use for boot
1101 rootfs ext2 the type of filesystem to use for root
1102 size 1G the size of the disk image
1103 bootsize 128M the size of the boot filesystem
1104 partition mbr partition table type
1105
1107 For API-level documentation on this topic, see "guestfs_add_drive_opts"
1108 in guestfs(3) and "REMOTE STORAGE" in guestfs(3).
1109 On the command line, you can use the -a option to add network block
1111 devices using a URI-style format, for example:
1112 guestfish -a ssh://root@example.com/disk.img
1114 URIs cannot be used with the "add" command. The equivalent command
1116 using the API directly is:
1117 ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root
1119 The possible -a URI formats are described below.
1121 -a disk.img
1123 -a file:///path/to/disk.img
1124 Add the local disk image (or device) called disk.img.
1125 -a ftp://[user@]example.com[:port]/disk.img
1127 -a ftps://[user@]example.com[:port]/disk.img
1128 -a http://[user@]example.com[:port]/disk.img
1129 -a https://[user@]example.com[:port]/disk.img
1130 -a tftp://[user@]example.com[:port]/disk.img
1131 Add a disk located on a remote FTP, HTTP or TFTP server.
1132 The equivalent API command would be:
1134 ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com
1136 -a gluster://example.com[:port]/volname/image
1138 Add a disk image located on GlusterFS storage.
1139 The server is the one running "glusterd", and may be "localhost".
1141 The equivalent API command would be:
1143 ><fs> add volname/image protocol:gluster server:tcp:example.com
1145 -a iscsi://example.com[:port]/target-iqn-name[/lun]
1147 Add a disk located on an iSCSI server.
1148 The equivalent API command would be:
1150 ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com
1152 -a nbd://example.com[:port]
1154 -a nbd://example.com[:port]/exportname
1155 -a nbd://?socket=/socket
1156 -a nbd:///exportname?socket=/socket
1157 Add a disk located on Network Block Device (nbd) storage.
1158 The /exportname part of the URI specifies an NBD export name, but is
1160 usually left empty.
1161 The optional ?socket parameter can be used to specify a Unix domain
1163 socket that we talk to the NBD server over. Note that you cannot mix
1164 server name (ie. TCP/IP) and socket path.
1165 The equivalent API command would be (no export name):
1167 ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]
1169 -a rbd:///pool/disk
1171 -a rbd://example.com[:port]/pool/disk
1172 Add a disk image located on a Ceph (RBD/librbd) storage volume.
1173 Although libguestfs and Ceph supports multiple servers, only a single
1175 server can be specified when using this URI syntax.
1176 The equivalent API command would be:
1178 ><fs> add pool/disk protocol:rbd server:tcp:example.com:port
1180 -a sheepdog://[example.com[:port]]/volume/image
1182 Add a disk image located on a Sheepdog volume.
1183 The server name is optional. Although libguestfs and Sheepdog supports
1185 multiple servers, only at most one server can be specified when using
1186 this URI syntax.
1187 The equivalent API command would be:
1189 ><fs> add volume protocol:sheepdog [server:tcp:example.com]
1191 -a ssh://[user@]example.com[:port]/disk.img
1193 Add a disk image located on a remote server, accessed using the Secure
1194 Shell (ssh) SFTP protocol. SFTP is supported out of the box by all
1195 major SSH servers.
1196 The equivalent API command would be:
1198 ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]
1200 Note that the URIs follow the syntax of RFC 3986: in particular, there
1202 are restrictions on the allowed characters for the various components
1203 of the URI. Characters such as ":", "@", and "/" must be percent-
1204 encoded:
1205 $ guestfish -a ssh://user:pass%40word@example.com/disk.img
1207 In this case, the password is "pass@word".
1209
1211 Some (not all) long-running commands send progress notification
1212 messages as they are running. Guestfish turns these messages into
1213 progress bars.
1214 When a command that supports progress bars takes longer than two
1216 seconds to run, and if progress bars are enabled, then you will see one
1217 appearing below the command:
1218 ><fs> copy-size /large-file /another-file 2048M
1220 / 10% [#####-----------------------------------------] 00:30
1221 The spinner on the left hand side moves round once for every progress
1223 notification received from the backend. This is a (reasonably) golden
1224 assurance that the command is "doing something" even if the progress
1225 bar is not moving, because the command is able to send the progress
1226 notifications. When the bar reaches 100% and the command finishes, the
1227 spinner disappears.
1228 Progress bars are enabled by default when guestfish is used
1230 interactively. You can enable them even for non-interactive modes
1231 using --progress-bars, and you can disable them completely using
1232 --no-progress-bars.
1233
1235 You can change or add colours to the default prompt ("><fs>") by
1236 setting the "GUESTFISH_PS1" environment variable. A second string
1237 ("GUESTFISH_OUTPUT") is printed after the command has been entered and
1238 before the output, allowing you to control the colour of the output. A
1239 third string ("GUESTFISH_INIT") is printed before the welcome message,
1240 allowing you to control the colour of that message. A fourth string
1241 ("GUESTFISH_RESTORE") is printed before guestfish exits.
1242 A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate
1244 string:
1245 $ GUESTFISH_PS1='(type a command) '
1247 $ export GUESTFISH_PS1
1248 $ guestfish
1249 [...]
1250 (type a command) ▂
1251 You can also use special escape sequences, as described in the table
1253 below:
1254 \\ A literal backslash character.
1256 \[
1258 \] (These should only be used in "GUESTFISH_PS1".)
1259 Place non-printing characters (eg. terminal control codes for
1261 colours) between "\[...\]". What this does it to tell the
1262 readline(3) library that it should treat this subsequence as zero-
1263 width, so that command-line redisplay, editing etc works.
1264 \a A bell character.
1266 \e An ASCII ESC (escape) character.
1268 \n A newline.
1270 \r A carriage return.
1272 \NNN
1274 The ASCII character whose code is the octal value NNN.
1275 \xNN
1277 The ASCII character whose code is the hex value NN.
1278 EXAMPLES OF PROMPTS
1280 Note that these examples require a terminal that supports ANSI escape
1281 codes.
1282 ·
1284 GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1287 A bold black version of the ordinary prompt.
1289 ·
1291 GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
1294 GUESTFISH_OUTPUT='\e[0m'
1295 GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
1296 GUESTFISH_INIT='\e[1;34m'
1297 Blue welcome text, green prompt, red commands, black command
1299 output.
1300
1302 Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1303 partitions. See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1304 guestfs(3).
1305
1307 The commands in this section are guestfish convenience commands, in
1308 other words, they are not part of the guestfs(3) API.
1309 help
1311 help
1312 help cmd
1313 help -l|--list
1314 Without any parameter, this provides general help.
1316 With a "cmd" parameter, this displays detailed help for that command.
1318 With -l or --list, this list all commands.
1320 exit
1322 quit
1323 This exits guestfish. You can also use "^D" key.
1324 alloc
1326 allocate
1327 alloc filename size
1328 This creates an empty (zeroed) file of the given size, and then adds so
1330 it can be further examined.
1331 For more advanced image creation, see "disk-create".
1333 Size can be specified using standard suffixes, eg. "1M".
1335 To create a sparse file, use "sparse" instead. To create a prepared
1337 disk image, see "PREPARED DISK IMAGES".
1338 copy-in
1340 copy-in local [local ...] /remotedir
1341 "copy-in" copies local files or directories recursively into the disk
1343 image, placing them in the directory called /remotedir (which must
1344 exist). This guestfish meta-command turns into a sequence of "tar-in"
1345 and other commands as necessary.
1346 Multiple local files and directories can be specified, but the last
1348 parameter must always be a remote directory. Wildcards cannot be used.
1349 copy-out
1351 copy-out remote [remote ...] localdir
1352 "copy-out" copies remote files or directories recursively out of the
1354 disk image, placing them on the host disk in a local directory called
1355 "localdir" (which must exist). This guestfish meta-command turns into
1356 a sequence of "download", "tar-out" and other commands as necessary.
1357 Multiple remote files and directories can be specified, but the last
1359 parameter must always be a local directory. To download to the current
1360 directory, use "." as in:
1361 copy-out /home .
1363 Wildcards cannot be used in the ordinary command, but you can use them
1365 with the help of "glob" like this:
1366 glob copy-out /home/* .
1368 delete-event
1370 delete-event name
1371 Delete the event handler which was previously registered as "name". If
1373 multiple event handlers were registered with the same name, they are
1374 all deleted.
1375 See also the guestfish commands "event" and "list-events".
1377 display
1379 display filename
1380 Use "display" (a graphical display program) to display an image file.
1382 It downloads the file, and runs "display" on it.
1383 To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1385 environment variable. For example to use the GNOME display program:
1386 export GUESTFISH_DISPLAY_IMAGE=eog
1388 See also display(1).
1390 echo
1392 echo [params ...]
1393 This echos the parameters to the terminal.
1395 edit
1397 vi
1398 emacs
1399 edit filename
1400 This is used to edit a file. It downloads the file, edits it locally
1402 using your editor, then uploads the result.
1403 The editor is $EDITOR. However if you use the alternate commands "vi"
1405 or "emacs" you will get those corresponding editors.
1406 event
1408 event name eventset "shell script ..."
1409 Register a shell script fragment which is executed when an event is
1411 raised. See "guestfs_set_event_callback" in guestfs(3) for a
1412 discussion of the event API in libguestfs.
1413 The "name" parameter is a name that you give to this event handler. It
1415 can be any string (even the empty string) and is simply there so you
1416 can delete the handler using the guestfish "delete-event" command.
1417 The "eventset" parameter is a comma-separated list of one or more
1419 events, for example "close" or "close,trace". The special value "*"
1420 means all events.
1421 The third and final parameter is the shell script fragment (or any
1423 external command) that is executed when any of the events in the
1424 eventset occurs. It is executed using "$SHELL -c", or if $SHELL is not
1425 set then /bin/sh -c.
1426 The shell script fragment receives callback parameters as arguments $1,
1428 $2 etc. The actual event that was called is available in the
1429 environment variable $EVENT.
1430 event "" close "echo closed"
1432 event messages appliance,library,trace "echo $@"
1433 event "" progress "echo progress: $3/$4"
1434 event "" * "echo $EVENT $@"
1435 See also the guestfish commands "delete-event" and "list-events".
1437 glob
1439 glob command args...
1440 Expand wildcards in any paths in the args list, and run "command"
1442 repeatedly on each matching path.
1443 See "WILDCARDS AND GLOBBING".
1445 hexedit
1447 hexedit <filename|device>
1448 hexedit <filename|device> <max>
1449 hexedit <filename|device> <start> <max>
1450 Use hexedit (a hex editor) to edit all or part of a binary file or
1452 block device.
1453 This command works by downloading potentially the whole file or device,
1455 editing it locally, then uploading it. If the file or device is large,
1456 you have to specify which part you wish to edit by using "max" and/or
1457 "start" "max" parameters. "start" and "max" are specified in bytes,
1458 with the usual modifiers allowed such as "1M" (1 megabyte).
1459 For example to edit the first few sectors of a disk you might do:
1461 hexedit /dev/sda 1M
1463 which would allow you to edit anywhere within the first megabyte of the
1465 disk.
1466 To edit the superblock of an ext2 filesystem on /dev/sda1, do:
1468 hexedit /dev/sda1 0x400 0x400
1470 (assuming the superblock is in the standard location).
1472 This command requires the external hexedit(1) program. You can specify
1474 another program to use by setting the "HEXEDITOR" environment variable.
1475 See also "hexdump".
1477 lcd
1479 lcd directory
1480 Change the local directory, ie. the current directory of guestfish
1482 itself.
1483 Note that "!cd" won't do what you might expect.
1485 list-events
1487 list-events
1488 List the event handlers registered using the guestfish "event" command.
1490 man
1492 manual
1493 man
1494 Opens the manual page for guestfish.
1496 more
1498 less
1499 more filename
1500 less filename
1502 This is used to view a file.
1504 The default viewer is $PAGER. However if you use the alternate command
1506 "less" you will get the "less" command specifically.
1507 reopen
1509 reopen
1510 Close and reopen the libguestfs handle. It is not necessary to use
1512 this normally, because the handle is closed properly when guestfish
1513 exits. However this is occasionally useful for testing.
1514 setenv
1516 setenv VAR value
1517 Set the environment variable "VAR" to the string "value".
1519 To print the value of an environment variable use a shell command such
1521 as:
1522 !echo $VAR
1524 sparse
1526 sparse filename size
1527 This creates an empty sparse file of the given size, and then adds so
1529 it can be further examined.
1530 In all respects it works the same as the "alloc" command, except that
1532 the image file is allocated sparsely, which means that disk blocks are
1533 not assigned to the file until they are needed. Sparse disk files only
1534 use space when written to, but they are slower and there is a danger
1535 you could run out of real disk space during a write operation.
1536 For more advanced image creation, see "disk-create".
1538 Size can be specified using standard suffixes, eg. "1M".
1540 See also the guestfish "scratch" command.
1542 supported
1544 supported
1545 This command returns a list of the optional groups known to the daemon,
1547 and indicates which ones are supported by this build of the libguestfs
1548 appliance.
1549 See also "AVAILABILITY" in guestfs(3).
1551 time
1553 time command args...
1554 Run the command as usual, but print the elapsed time afterwards. This
1556 can be useful for benchmarking operations.
1557 unsetenv
1559 unsetenv VAR
1560 Remove "VAR" from the environment.
1562
1564 acl-delete-def-file
1565 acl-delete-def-file dir
1566 This function deletes the default POSIX Access Control List (ACL)
1568 attached to directory "dir".
1569 This command depends on the feature "acl". See also "feature-
1571 available".
1572 acl-get-file
1574 acl-get-file path acltype
1575 This function returns the POSIX Access Control List (ACL) attached to
1577 "path". The ACL is returned in "long text form" (see acl(5)).
1578 The "acltype" parameter may be:
1580 "access"
1582 Return the ordinary (access) ACL for any file, directory or other
1583 filesystem object.
1584 "default"
1586 Return the default ACL. Normally this only makes sense if "path"
1587 is a directory.
1588 This command depends on the feature "acl". See also "feature-
1590 available".
1591 acl-set-file
1593 acl-set-file path acltype acl
1594 This function sets the POSIX Access Control List (ACL) attached to
1596 "path".
1597 The "acltype" parameter may be:
1599 "access"
1601 Set the ordinary (access) ACL for any file, directory or other
1602 filesystem object.
1603 "default"
1605 Set the default ACL. Normally this only makes sense if "path" is a
1606 directory.
1607 The "acl" parameter is the new ACL in either "long text form" or "short
1609 text form" (see acl(5)). The new ACL completely replaces any previous
1610 ACL on the file. The ACL must contain the full Unix permissions (eg.
1611 "u::rwx,g::rx,o::rx").
1612 If you are specifying individual users or groups, then the mask field
1614 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1615 "g:ID:..." field(s). A full ACL string might therefore look like this:
1616 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1618 \ Unix permissions / \mask/ \ ACL /
1619 You should use numeric UIDs and GIDs. To map usernames and groupnames
1621 to the correct numeric ID in the context of the guest, use the Augeas
1622 functions (see "aug-init").
1623 This command depends on the feature "acl". See also "feature-
1625 available".
1626 add-cdrom
1628 add-cdrom filename
1629 This function adds a virtual CD-ROM disk image to the guest.
1631 The image is added as read-only drive, so this function is equivalent
1633 of "add-drive-ro".
1634 This function is deprecated. In new code, use the "add-drive-ro" call
1636 instead.
1637 Deprecated functions will not be removed from the API, but the fact
1639 that they are deprecated indicates that there are problems with correct
1640 use of these functions.
1641 add-domain
1643 domain
1644 add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]
1645 This function adds the disk(s) attached to the named libvirt domain
1647 "dom". It works by connecting to libvirt, requesting the domain and
1648 domain XML from libvirt, parsing it for disks, and calling "add-drive-
1649 opts" on each one.
1650 The number of disks added is returned. This operation is atomic: if an
1652 error is returned, then no disks are added.
1653 This function does some minimal checks to make sure the libvirt domain
1655 is not running (unless "readonly" is true). In a future version we
1656 will try to acquire the libvirt lock on each disk.
1657 Disks must be accessible locally. This often means that adding disks
1659 from a remote libvirt connection (see http://libvirt.org/remote.html)
1660 will fail unless those disks are accessible via the same device path
1661 locally too.
1662 The optional "libvirturi" parameter sets the libvirt URI (see
1664 http://libvirt.org/uri.html). If this is not set then we connect to
1665 the default libvirt URI (or one set through an environment variable,
1666 see the libvirt documentation for full details).
1667 The optional "live" flag controls whether this call will try to connect
1669 to a running virtual machine "guestfsd" process if it sees a suitable
1670 <channel> element in the libvirt XML definition. The default (if the
1671 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1672 in guestfs(3) for more information.
1673 If the "allowuuid" flag is true (default is false) then a UUID may be
1675 passed instead of the domain name. The "dom" string is treated as a
1676 UUID first and looked up, and if that lookup fails then we treat "dom"
1677 as a name as usual.
1678 The optional "readonlydisk" parameter controls what we do for disks
1680 which are marked <readonly/> in the libvirt XML. Possible values are:
1681 readonlydisk = "error"
1683 If "readonly" is false:
1684 The whole call is aborted with an error if any disk with the
1686 <readonly/> flag is found.
1687 If "readonly" is true:
1689 Disks with the <readonly/> flag are added read-only.
1691 readonlydisk = "read"
1693 If "readonly" is false:
1694 Disks with the <readonly/> flag are added read-only. Other disks
1696 are added read/write.
1697 If "readonly" is true:
1699 Disks with the <readonly/> flag are added read-only.
1701 readonlydisk = "write" (default)
1703 If "readonly" is false:
1704 Disks with the <readonly/> flag are added read/write.
1706 If "readonly" is true:
1708 Disks with the <readonly/> flag are added read-only.
1710 readonlydisk = "ignore"
1712 If "readonly" is true or false:
1713 Disks with the <readonly/> flag are skipped.
1715 The other optional parameters are passed directly through to "add-
1717 drive-opts".
1718 This command has one or more optional arguments. See "OPTIONAL
1720 ARGUMENTS".
1721 add-drive
1723 add
1724 add-drive-opts
1725 add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false]
1726 This function adds a disk image called filename to the handle.
1728 filename may be a regular host file or a host device.
1729 When this function is called before "launch" (the usual case) then the
1731 first time you call this function, the disk appears in the API as
1732 /dev/sda, the second time as /dev/sdb, and so on.
1733 In libguestfs ≥ 1.20 you can also call this function after launch (with
1735 some restrictions). This is called "hotplugging". When hotplugging,
1736 you must specify a "label" so that the new disk gets a predictable
1737 name. For more information see "HOTPLUGGING" in guestfs(3).
1738 You don't necessarily need to be root when using libguestfs. However
1740 you obviously do need sufficient permissions to access the filename for
1741 whatever operations you want to perform (ie. read access if you just
1742 want to read the image or write access if you want to modify the
1743 image).
1744 This call checks that filename exists.
1746 filename may be the special string "/dev/null". See "NULL DISKS" in
1748 guestfs(3).
1749 The optional arguments are:
1751 "readonly"
1753 If true then the image is treated as read-only. Writes are still
1754 allowed, but they are stored in a temporary snapshot overlay which
1755 is discarded at the end. The disk that you add is not modified.
1756 "format"
1758 This forces the image format. If you omit this (or use "add-drive"
1759 or "add-drive-ro") then the format is automatically detected.
1760 Possible formats include "raw" and "qcow2".
1761 Automatic detection of the format opens you up to a potential
1763 security hole when dealing with untrusted raw-format images. See
1764 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
1765 security hole.
1766 "iface"
1768 This rarely-used option lets you emulate the behaviour of the
1769 deprecated "add-drive-with-if" call (q.v.)
1770 "name"
1772 The name the drive had in the original guest, e.g. /dev/sdb. This
1773 is used as a hint to the guest inspection process if it is
1774 available.
1775 "label"
1777 Give the disk a label. The label should be a unique, short string
1778 using only ASCII characters "[a-zA-Z]". As well as its usual name
1779 in the API (such as /dev/sda), the drive will also be named
1780 /dev/disk/guestfs/label.
1781 See "DISK LABELS" in guestfs(3).
1783 "protocol"
1785 The optional protocol argument can be used to select an alternate
1786 source protocol.
1787 See also: "REMOTE STORAGE" in guestfs(3).
1789 "protocol = "file""
1791 filename is interpreted as a local file or device. This is the
1792 default if the optional protocol parameter is omitted.
1793 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
1795 Connect to a remote FTP, HTTP or TFTP server. The "server"
1796 parameter must also be supplied - see below.
1797 See also: "FTP, HTTP AND TFTP" in guestfs(3)
1799 "protocol = "gluster""
1801 Connect to the GlusterFS server. The "server" parameter must
1802 also be supplied - see below.
1803 See also: "GLUSTER" in guestfs(3)
1805 "protocol = "iscsi""
1807 Connect to the iSCSI server. The "server" parameter must also
1808 be supplied - see below. The "username" parameter may be
1809 supplied. See below. The "secret" parameter may be supplied.
1810 See below.
1811 See also: "ISCSI" in guestfs(3).
1813 "protocol = "nbd""
1815 Connect to the Network Block Device server. The "server"
1816 parameter must also be supplied - see below.
1817 See also: "NETWORK BLOCK DEVICE" in guestfs(3).
1819 "protocol = "rbd""
1821 Connect to the Ceph (librbd/RBD) server. The "server"
1822 parameter must also be supplied - see below. The "username"
1823 parameter may be supplied. See below. The "secret" parameter
1824 may be supplied. See below.
1825 See also: "CEPH" in guestfs(3).
1827 "protocol = "sheepdog""
1829 Connect to the Sheepdog server. The "server" parameter may
1830 also be supplied - see below.
1831 See also: "SHEEPDOG" in guestfs(3).
1833 "protocol = "ssh""
1835 Connect to the Secure Shell (ssh) server.
1836 The "server" parameter must be supplied. The "username"
1838 parameter may be supplied. See below.
1839 See also: "SSH" in guestfs(3).
1841 "server"
1843 For protocols which require access to a remote server, this is a
1844 list of server(s).
1845 Protocol Number of servers required
1847 -------- --------------------------
1848 file List must be empty or param not used at all
1849 ftp|ftps|http|https|tftp Exactly one
1850 gluster Exactly one
1851 iscsi Exactly one
1852 nbd Exactly one
1853 rbd Zero or more
1854 sheepdog Zero or more
1855 ssh Exactly one
1856 Each list element is a string specifying a server. The string must
1858 be in one of the following formats:
1859 hostname
1861 hostname:port
1862 tcp:hostname
1863 tcp:hostname:port
1864 unix:/path/to/socket
1865 If the port number is omitted, then the standard port number for
1867 the protocol is used (see /etc/services).
1868 "username"
1870 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
1871 "tftp" protocols, this specifies the remote username.
1872 If not given, then the local username is used for "ssh", and no
1874 authentication is attempted for ceph. But note this sometimes may
1875 give unexpected results, for example if using the libvirt backend
1876 and if the libvirt backend is configured to start the qemu
1877 appliance as a special user such as "qemu.qemu". If in doubt,
1878 specify the remote username you want.
1879 "secret"
1881 For the "rbd" protocol only, this specifies the ‘secret’ to use
1882 when connecting to the remote device. It must be base64 encoded.
1883 If not given, then a secret matching the given username will be
1885 looked up in the default keychain locations, or if no username is
1886 given, then no authentication will be used.
1887 "cachemode"
1889 Choose whether or not libguestfs will obey sync operations (safe
1890 but slow) or not (unsafe but fast). The possible values for this
1891 string are:
1892 "cachemode = "writeback""
1894 This is the default.
1895 Write operations in the API do not return until a write(2) call
1897 has completed in the host [but note this does not imply that
1898 anything gets written to disk].
1899 Sync operations in the API, including implicit syncs caused by
1901 filesystem journalling, will not return until an fdatasync(2)
1902 call has completed in the host, indicating that data has been
1903 committed to disk.
1904 "cachemode = "unsafe""
1906 In this mode, there are no guarantees. Libguestfs may cache
1907 anything and ignore sync requests. This is suitable only for
1908 scratch or temporary disks.
1909 "discard"
1911 Enable or disable discard (a.k.a. trim or unmap) support on this
1912 drive. If enabled, operations such as "fstrim" will be able to
1913 discard / make thin / punch holes in the underlying host file or
1914 device.
1915 Possible discard settings are:
1917 "discard = "disable""
1919 Disable discard support. This is the default.
1920 "discard = "enable""
1922 Enable discard support. Fail if discard is not possible.
1923 "discard = "besteffort""
1925 Enable discard support if possible, but don't fail if it is not
1926 supported.
1927 Since not all backends and not all underlying systems support
1929 discard, this is a good choice if you want to use discard if
1930 possible, but don't mind if it doesn't work.
1931 "copyonread"
1933 The boolean parameter "copyonread" enables copy-on-read support.
1934 This only affects disk formats which have backing files, and causes
1935 reads to be stored in the overlay layer, speeding up multiple reads
1936 of the same area of disk.
1937 The default is false.
1939 This command has one or more optional arguments. See "OPTIONAL
1941 ARGUMENTS".
1942 add-drive-ro
1944 add-ro
1945 add-drive-ro filename
1946 This function is the equivalent of calling "add-drive-opts" with the
1948 optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1949 disk is added read-only, with the format being detected automatically.
1950 add-drive-ro-with-if
1952 add-drive-ro-with-if filename iface
1953 This is the same as "add-drive-ro" but it allows you to specify the
1955 QEMU interface emulation to use at run time.
1956 This function is deprecated. In new code, use the "add-drive" call
1958 instead.
1959 Deprecated functions will not be removed from the API, but the fact
1961 that they are deprecated indicates that there are problems with correct
1962 use of these functions.
1963 add-drive-scratch
1965 scratch
1966 add-drive-scratch size [name:..] [label:..]
1967 This command adds a temporary scratch drive to the handle. The "size"
1969 parameter is the virtual size (in bytes). The scratch drive is blank
1970 initially (all reads return zeroes until you start writing to it). The
1971 drive is deleted when the handle is closed.
1972 The optional arguments "name" and "label" are passed through to "add-
1974 drive".
1975 This command has one or more optional arguments. See "OPTIONAL
1977 ARGUMENTS".
1978 add-drive-with-if
1980 add-drive-with-if filename iface
1981 This is the same as "add-drive" but it allows you to specify the QEMU
1983 interface emulation to use at run time.
1984 This function is deprecated. In new code, use the "add-drive" call
1986 instead.
1987 Deprecated functions will not be removed from the API, but the fact
1989 that they are deprecated indicates that there are problems with correct
1990 use of these functions.
1991 aug-clear
1993 aug-clear augpath
1994 Set the value associated with "path" to "NULL". This is the same as
1996 the augtool(1) "clear" command.
1997 aug-close
1999 aug-close
2000 Close the current Augeas handle and free up any resources used by it.
2002 After calling this, you have to call "aug-init" again before you can
2003 use any other Augeas functions.
2004 aug-defnode
2006 aug-defnode name expr val
2007 Defines a variable "name" whose value is the result of evaluating
2009 "expr".
2010 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2012 to calling "aug-set" "expr", "value". "name" will be the nodeset
2013 containing that single node.
2014 On success this returns a pair containing the number of nodes in the
2016 nodeset, and a boolean flag if a node was created.
2017 aug-defvar
2019 aug-defvar name expr
2020 Defines an Augeas variable "name" whose value is the result of
2022 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2023 On success this returns the number of nodes in "expr", or 0 if "expr"
2025 evaluates to something which is not a nodeset.
2026 aug-get
2028 aug-get augpath
2029 Look up the value associated with "path". If "path" matches exactly
2031 one node, the "value" is returned.
2032 aug-init
2034 aug-init root flags
2035 Create a new Augeas handle for editing configuration files. If there
2037 was any previous Augeas handle associated with this guestfs session,
2038 then it is closed.
2039 You must call this before using any other "aug-*" commands.
2041 "root" is the filesystem root. "root" must not be NULL, use / instead.
2043 The flags are the same as the flags defined in <augeas.h>, the logical
2045 or of the following integers:
2046 "AUG_SAVE_BACKUP" = 1
2048 Keep the original file with a ".augsave" extension.
2049 "AUG_SAVE_NEWFILE" = 2
2051 Save changes into a file with extension ".augnew", and do not
2052 overwrite original. Overrides "AUG_SAVE_BACKUP".
2053 "AUG_TYPE_CHECK" = 4
2055 Typecheck lenses.
2056 This option is only useful when debugging Augeas lenses. Use of
2058 this option may require additional memory for the libguestfs
2059 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2060 environment variable or call "set-memsize".
2061 "AUG_NO_STDINC" = 8
2063 Do not use standard load path for modules.
2064 "AUG_SAVE_NOOP" = 16
2066 Make save a no-op, just record what would have been changed.
2067 "AUG_NO_LOAD" = 32
2069 Do not load the tree in "aug-init".
2070 To close the handle, you can call "aug-close".
2072 To find out more about Augeas, see http://augeas.net/.
2074 aug-insert
2076 aug-insert augpath label true|false
2077 Create a new sibling "label" for "path", inserting it into the tree
2079 before or after "path" (depending on the boolean flag "before").
2080 "path" must match exactly one existing node in the tree, and "label"
2082 must be a label, ie. not contain /, "*" or end with a bracketed index
2083 "[N]".
2084 aug-label
2086 aug-label augpath
2087 The label (name of the last element) of the Augeas path expression
2089 "augpath" is returned. "augpath" must match exactly one node, else
2090 this function returns an error.
2091 aug-load
2093 aug-load
2094 Load files into the tree.
2096 See "aug_load" in the Augeas documentation for the full gory details.
2098 aug-ls
2100 aug-ls augpath
2101 This is just a shortcut for listing "aug-match" "path/*" and sorting
2103 the resulting nodes into alphabetical order.
2104 aug-match
2106 aug-match augpath
2107 Returns a list of paths which match the path expression "path". The
2109 returned paths are sufficiently qualified so that they match exactly
2110 one node in the current tree.
2111 aug-mv
2113 aug-mv src dest
2114 Move the node "src" to "dest". "src" must match exactly one node.
2116 "dest" is overwritten if it exists.
2117 aug-rm
2119 aug-rm augpath
2120 Remove "path" and all of its children.
2122 On success this returns the number of entries which were removed.
2124 aug-save
2126 aug-save
2127 This writes all pending changes to disk.
2129 The flags which were passed to "aug-init" affect exactly how files are
2131 saved.
2132 aug-set
2134 aug-set augpath val
2135 Set the value associated with "path" to "val".
2137 In the Augeas API, it is possible to clear a node by setting the value
2139 to NULL. Due to an oversight in the libguestfs API you cannot do that
2140 with this call. Instead you must use the "aug-clear" call.
2141 aug-setm
2143 aug-setm base sub val
2144 Change multiple Augeas nodes in a single operation. "base" is an
2146 expression matching multiple nodes. "sub" is a path expression
2147 relative to "base". All nodes matching "base" are found, and then for
2148 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2149 which case the "base" nodes are modified.
2150 This returns the number of nodes modified.
2152 aug-transform
2154 aug-transform lens file [remove:true|false]
2155 Add an Augeas transformation for the specified "lens" so it can handle
2157 "file".
2158 If "remove" is true ("false" by default), then the transformation is
2160 removed.
2161 This command has one or more optional arguments. See "OPTIONAL
2163 ARGUMENTS".
2164 available
2166 available 'groups ...'
2167 This command is used to check the availability of some groups of
2169 functionality in the appliance, which not all builds of the libguestfs
2170 appliance will be able to provide.
2171 The libguestfs groups, and the functions that those groups correspond
2173 to, are listed in "AVAILABILITY" in guestfs(3). You can also fetch
2174 this list at runtime by calling "available-all-groups".
2175 The argument "groups" is a list of group names, eg: "["inotify",
2177 "augeas"]" would check for the availability of the Linux inotify
2178 functions and Augeas (configuration file editing) functions.
2179 The command returns no error if all requested groups are available.
2181 It fails with an error if one or more of the requested groups is
2183 unavailable in the appliance.
2184 If an unknown group name is included in the list of groups then an
2186 error is always returned.
2187 Notes:
2189 · "feature-available" is the same as this call, but with a slightly
2191 simpler to use API: that call returns a boolean true/false instead
2192 of throwing an error.
2193 · You must call "launch" before calling this function.
2195 The reason is because we don't know what groups are supported by
2197 the appliance/daemon until it is running and can be queried.
2198 · If a group of functions is available, this does not necessarily
2200 mean that they will work. You still have to check for errors when
2201 calling individual API functions even if they are available.
2202 · It is usually the job of distro packagers to build complete
2204 functionality into the libguestfs appliance. Upstream libguestfs,
2205 if built from source with all requirements satisfied, will support
2206 everything.
2207 · This call was added in version 1.0.80. In previous versions of
2209 libguestfs all you could do would be to speculatively execute a
2210 command to find out if the daemon implemented it. See also
2211 "version".
2212 See also "filesystem-available".
2214 available-all-groups
2216 available-all-groups
2217 This command returns a list of all optional groups that this daemon
2219 knows about. Note this returns both supported and unsupported groups.
2220 To find out which ones the daemon can actually support you have to call
2221 "available" / "feature-available" on each member of the returned list.
2222 See also "available", "feature-available" and "AVAILABILITY" in
2224 guestfs(3).
2225 base64-in
2227 base64-in (base64file|-) filename
2228 This command uploads base64-encoded data from "base64file" to filename.
2230 Use "-" instead of a filename to read/write from stdin/stdout.
2232 base64-out
2234 base64-out filename (base64file|-)
2235 This command downloads the contents of filename, writing it out to
2237 local file "base64file" encoded as base64.
2238 Use "-" instead of a filename to read/write from stdin/stdout.
2240 blkdiscard
2242 blkdiscard device
2243 This discards all blocks on the block device "device", giving the free
2245 space back to the host.
2246 This operation requires support in libguestfs, the host filesystem,
2248 qemu and the host kernel. If this support isn't present it may give an
2249 error or even appear to run but do nothing. You must also set the
2250 "discard" attribute on the underlying drive (see "add-drive-opts").
2251 This command depends on the feature "blkdiscard". See also "feature-
2253 available".
2254 blkdiscardzeroes
2256 blkdiscardzeroes device
2257 This call returns true if blocks on "device" that have been discarded
2259 by a call to "blkdiscard" are returned as blocks of zero bytes when
2260 read the next time.
2261 If it returns false, then it may be that discarded blocks are read as
2263 stale or random data.
2264 This command depends on the feature "blkdiscardzeroes". See also
2266 "feature-available".
2267 blkid
2269 blkid device
2270 This command returns block device attributes for "device". The
2272 following fields are usually present in the returned hash. Other fields
2273 may also be present.
2274 "UUID"
2276 The uuid of this device.
2277 "LABEL"
2279 The label of this device.
2280 "VERSION"
2282 The version of blkid command.
2283 "TYPE"
2285 The filesystem type or RAID of this device.
2286 "USAGE"
2288 The usage of this device, for example "filesystem" or "raid".
2289 blockdev-flushbufs
2291 blockdev-flushbufs device
2292 This tells the kernel to flush internal buffers associated with
2294 "device".
2295 This uses the blockdev(8) command.
2297 blockdev-getbsz
2299 blockdev-getbsz device
2300 This returns the block size of a device.
2302 Note: this is different from both size in blocks and filesystem block
2304 size. Also this setting is not really used by anything. You should
2305 probably not use it for anything. Filesystems have their own idea
2306 about what block size to choose.
2307 This uses the blockdev(8) command.
2309 blockdev-getro
2311 blockdev-getro device
2312 Returns a boolean indicating if the block device is read-only (true if
2314 read-only, false if not).
2315 This uses the blockdev(8) command.
2317 blockdev-getsize64
2319 blockdev-getsize64 device
2320 This returns the size of the device in bytes.
2322 See also "blockdev-getsz".
2324 This uses the blockdev(8) command.
2326 blockdev-getss
2328 blockdev-getss device
2329 This returns the size of sectors on a block device. Usually 512, but
2331 can be larger for modern devices.
2332 (Note, this is not the size in sectors, use "blockdev-getsz" for that).
2334 This uses the blockdev(8) command.
2336 blockdev-getsz
2338 blockdev-getsz device
2339 This returns the size of the device in units of 512-byte sectors (even
2341 if the sectorsize isn't 512 bytes ... weird).
2342 See also "blockdev-getss" for the real sector size of the device, and
2344 "blockdev-getsize64" for the more useful size in bytes.
2345 This uses the blockdev(8) command.
2347 blockdev-rereadpt
2349 blockdev-rereadpt device
2350 Reread the partition table on "device".
2352 This uses the blockdev(8) command.
2354 blockdev-setbsz
2356 blockdev-setbsz device blocksize
2357 This call does nothing and has never done anything because of a bug in
2359 blockdev. Do not use it.
2360 If you need to set the filesystem block size, use the "blocksize"
2362 option of "mkfs".
2363 This function is deprecated. There is no replacement. Consult the API
2365 documentation in guestfs(3) for further information.
2366 Deprecated functions will not be removed from the API, but the fact
2368 that they are deprecated indicates that there are problems with correct
2369 use of these functions.
2370 blockdev-setra
2372 blockdev-setra device sectors
2373 Set readahead (in 512-byte sectors) for the device.
2375 This uses the blockdev(8) command.
2377 blockdev-setro
2379 blockdev-setro device
2380 Sets the block device named "device" to read-only.
2382 This uses the blockdev(8) command.
2384 blockdev-setrw
2386 blockdev-setrw device
2387 Sets the block device named "device" to read-write.
2389 This uses the blockdev(8) command.
2391 btrfs-balance-cancel
2393 btrfs-balance-cancel path
2394 Cancel a running balance on a btrfs filesystem.
2396 This command depends on the feature "btrfs". See also "feature-
2398 available".
2399 btrfs-balance-pause
2401 btrfs-balance-pause path
2402 Pause a running balance on a btrfs filesystem.
2404 This command depends on the feature "btrfs". See also "feature-
2406 available".
2407 btrfs-balance-resume
2409 btrfs-balance-resume path
2410 Resume a paused balance on a btrfs filesystem.
2412 This command depends on the feature "btrfs". See also "feature-
2414 available".
2415 btrfs-balance-status
2417 btrfs-balance-status path
2418 Show the status of a running or paused balance on a btrfs filesystem.
2420 This command depends on the feature "btrfs". See also "feature-
2422 available".
2423 btrfs-device-add
2425 btrfs-device-add 'devices ...' fs
2426 Add the list of device(s) in "devices" to the btrfs filesystem mounted
2428 at "fs". If "devices" is an empty list, this does nothing.
2429 This command depends on the feature "btrfs". See also "feature-
2431 available".
2432 btrfs-device-delete
2434 btrfs-device-delete 'devices ...' fs
2435 Remove the "devices" from the btrfs filesystem mounted at "fs". If
2437 "devices" is an empty list, this does nothing.
2438 This command depends on the feature "btrfs". See also "feature-
2440 available".
2441 btrfs-filesystem-balance
2443 btrfs-balance
2444 btrfs-filesystem-balance fs
2445 Balance the chunks in the btrfs filesystem mounted at "fs" across the
2447 underlying devices.
2448 This command depends on the feature "btrfs". See also "feature-
2450 available".
2451 btrfs-filesystem-defragment
2453 btrfs-filesystem-defragment path [flush:true|false] [compress:..]
2454 Defragment a file or directory on a btrfs filesystem. compress is one
2456 of zlib or lzo.
2457 This command has one or more optional arguments. See "OPTIONAL
2459 ARGUMENTS".
2460 This command depends on the feature "btrfs". See also "feature-
2462 available".
2463 btrfs-filesystem-resize
2465 btrfs-filesystem-resize mountpoint [size:N]
2466 This command resizes a btrfs filesystem.
2468 Note that unlike other resize calls, the filesystem has to be mounted
2470 and the parameter is the mountpoint not the device (this is a
2471 requirement of btrfs itself).
2472 The optional parameters are:
2474 "size"
2476 The new size (in bytes) of the filesystem. If omitted, the
2477 filesystem is resized to the maximum size.
2478 See also btrfs(8).
2480 This command has one or more optional arguments. See "OPTIONAL
2482 ARGUMENTS".
2483 This command depends on the feature "btrfs". See also "feature-
2485 available".
2486 btrfs-filesystem-show
2488 btrfs-filesystem-show device
2489 Show all the devices where the filesystems in "device" is spanned over.
2491 If not all the devices for the filesystems are present, then this
2493 function fails and the "errno" is set to "ENODEV".
2494 This command depends on the feature "btrfs". See also "feature-
2496 available".
2497 btrfs-filesystem-sync
2499 btrfs-filesystem-sync fs
2500 Force sync on the btrfs filesystem mounted at "fs".
2502 This command depends on the feature "btrfs". See also "feature-
2504 available".
2505 btrfs-fsck
2507 btrfs-fsck device [superblock:N] [repair:true|false]
2508 Used to check a btrfs filesystem, "device" is the device file where the
2510 filesystem is stored.
2511 This command has one or more optional arguments. See "OPTIONAL
2513 ARGUMENTS".
2514 This command depends on the feature "btrfs". See also "feature-
2516 available".
2517 btrfs-image
2519 btrfs-image 'source ...' image [compresslevel:N]
2520 This is used to create an image of a btrfs filesystem. All data will
2522 be zeroed, but metadata and the like is preserved.
2523 This command has one or more optional arguments. See "OPTIONAL
2525 ARGUMENTS".
2526 This command depends on the feature "btrfs". See also "feature-
2528 available".
2529 btrfs-qgroup-assign
2531 btrfs-qgroup-assign src dst path
2532 Add qgroup "src" to parent qgroup "dst". This command can group several
2534 qgroups into a parent qgroup to share common limit.
2535 This command depends on the feature "btrfs". See also "feature-
2537 available".
2538 btrfs-qgroup-create
2540 btrfs-qgroup-create qgroupid subvolume
2541 Create a quota group (qgroup) for subvolume at "subvolume".
2543 This command depends on the feature "btrfs". See also "feature-
2545 available".
2546 btrfs-qgroup-destroy
2548 btrfs-qgroup-destroy qgroupid subvolume
2549 Destroy a quota group.
2551 This command depends on the feature "btrfs". See also "feature-
2553 available".
2554 btrfs-qgroup-limit
2556 btrfs-qgroup-limit subvolume size
2557 Limit the size of the subvolume with path "subvolume".
2559 This command depends on the feature "btrfs". See also "feature-
2561 available".
2562 btrfs-qgroup-remove
2564 btrfs-qgroup-remove src dst path
2565 Remove qgroup "src" from the parent qgroup "dst".
2567 This command depends on the feature "btrfs". See also "feature-
2569 available".
2570 btrfs-qgroup-show
2572 btrfs-qgroup-show path
2573 Show all subvolume quota groups in a btrfs filesystem, including their
2575 usages.
2576 This command depends on the feature "btrfs". See also "feature-
2578 available".
2579 btrfs-quota-enable
2581 btrfs-quota-enable fs true|false
2582 Enable or disable subvolume quota support for filesystem which contains
2584 "path".
2585 This command depends on the feature "btrfs". See also "feature-
2587 available".
2588 btrfs-quota-rescan
2590 btrfs-quota-rescan fs
2591 Trash all qgroup numbers and scan the metadata again with the current
2593 config.
2594 This command depends on the feature "btrfs". See also "feature-
2596 available".
2597 btrfs-replace
2599 btrfs-replace srcdev targetdev mntpoint
2600 Replace device of a btrfs filesystem. On a live filesystem, duplicate
2602 the data to the target device which is currently stored on the source
2603 device. After completion of the operation, the source device is wiped
2604 out and removed from the filesystem.
2605 The "targetdev" needs to be same size or larger than the "srcdev".
2607 Devices which are currently mounted are never allowed to be used as the
2608 "targetdev".
2609 This command depends on the feature "btrfs". See also "feature-
2611 available".
2612 btrfs-rescue-chunk-recover
2614 btrfs-rescue-chunk-recover device
2615 Recover the chunk tree of btrfs filesystem by scanning the devices one
2617 by one.
2618 This command depends on the feature "btrfs". See also "feature-
2620 available".
2621 btrfs-rescue-super-recover
2623 btrfs-rescue-super-recover device
2624 Recover bad superblocks from good copies.
2626 This command depends on the feature "btrfs". See also "feature-
2628 available".
2629 btrfs-scrub-cancel
2631 btrfs-scrub-cancel path
2632 Cancel a running scrub on a btrfs filesystem.
2634 This command depends on the feature "btrfs". See also "feature-
2636 available".
2637 btrfs-scrub-resume
2639 btrfs-scrub-resume path
2640 Resume a previously canceled or interrupted scrub on a btrfs
2642 filesystem.
2643 This command depends on the feature "btrfs". See also "feature-
2645 available".
2646 btrfs-scrub-start
2648 btrfs-scrub-start path
2649 Reads all the data and metadata on the filesystem, and uses checksums
2651 and the duplicate copies from RAID storage to identify and repair any
2652 corrupt data.
2653 This command depends on the feature "btrfs". See also "feature-
2655 available".
2656 btrfs-scrub-status
2658 btrfs-scrub-status path
2659 Show status of running or finished scrub on a btrfs filesystem.
2661 This command depends on the feature "btrfs". See also "feature-
2663 available".
2664 btrfs-set-seeding
2666 btrfs-set-seeding device true|false
2667 Enable or disable the seeding feature of a device that contains a btrfs
2669 filesystem.
2670 This command depends on the feature "btrfs". See also "feature-
2672 available".
2673 btrfs-subvolume-create
2675 btrfs-subvolume-create-opts
2676 btrfs-subvolume-create dest [qgroupid:..]
2677 Create a btrfs subvolume. The "dest" argument is the destination
2679 directory and the name of the subvolume, in the form
2680 /path/to/dest/name. The optional parameter "qgroupid" represents the
2681 qgroup which the newly created subvolume will be added to.
2682 This command has one or more optional arguments. See "OPTIONAL
2684 ARGUMENTS".
2685 This command depends on the feature "btrfs". See also "feature-
2687 available".
2688 btrfs-subvolume-delete
2690 btrfs-subvolume-delete subvolume
2691 Delete the named btrfs subvolume or snapshot.
2693 This command depends on the feature "btrfs". See also "feature-
2695 available".
2696 btrfs-subvolume-get-default
2698 btrfs-subvolume-get-default fs
2699 Get the default subvolume or snapshot of a filesystem mounted at
2701 "mountpoint".
2702 This command depends on the feature "btrfs". See also "feature-
2704 available".
2705 btrfs-subvolume-list
2707 btrfs-subvolume-list fs
2708 List the btrfs snapshots and subvolumes of the btrfs filesystem which
2710 is mounted at "fs".
2711 This command depends on the feature "btrfs". See also "feature-
2713 available".
2714 btrfs-subvolume-set-default
2716 btrfs-subvolume-set-default id fs
2717 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2719 default. See "btrfs-subvolume-list" to get a list of subvolumes.
2720 This command depends on the feature "btrfs". See also "feature-
2722 available".
2723 btrfs-subvolume-show
2725 btrfs-subvolume-show subvolume
2726 Return detailed information of the subvolume.
2728 This command depends on the feature "btrfs". See also "feature-
2730 available".
2731 btrfs-subvolume-snapshot
2733 btrfs-subvolume-snapshot-opts
2734 btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]
2735 Create a snapshot of the btrfs subvolume "source". The "dest" argument
2737 is the destination directory and the name of the snapshot, in the form
2738 /path/to/dest/name. By default the newly created snapshot is writable,
2739 if the value of optional parameter "ro" is true, then a readonly
2740 snapshot is created. The optional parameter "qgroupid" represents the
2741 qgroup which the newly created snapshot will be added to.
2742 This command has one or more optional arguments. See "OPTIONAL
2744 ARGUMENTS".
2745 This command depends on the feature "btrfs". See also "feature-
2747 available".
2748 btrfstune-enable-extended-inode-refs
2750 btrfstune-enable-extended-inode-refs device
2751 This will Enable extended inode refs.
2753 This command depends on the feature "btrfs". See also "feature-
2755 available".
2756 btrfstune-enable-skinny-metadata-extent-refs
2758 btrfstune-enable-skinny-metadata-extent-refs device
2759 This enable skinny metadata extent refs.
2761 This command depends on the feature "btrfs". See also "feature-
2763 available".
2764 btrfstune-seeding
2766 btrfstune-seeding device true|false
2767 Enable seeding of a btrfs device, this will force a fs readonly so that
2769 you can use it to build other filesystems.
2770 This command depends on the feature "btrfs". See also "feature-
2772 available".
2773 c-pointer
2775 c-pointer
2776 In non-C language bindings, this allows you to retrieve the underlying
2778 C pointer to the handle (ie. "h *"). The purpose of this is to allow
2779 other libraries to interwork with libguestfs.
2780 canonical-device-name
2782 canonical-device-name device
2783 This utility function is useful when displaying device names to the
2785 user. It takes a number of irregular device names and returns them in
2786 a consistent format:
2787 /dev/hdX
2789 /dev/vdX
2790 These are returned as /dev/sdX. Note this works for device names
2791 and partition names. This is approximately the reverse of the
2792 algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2793 /dev/mapper/VG-LV
2795 /dev/dm-N
2796 Converted to /dev/VG/LV form using "lvm-canonical-lv-name".
2797 Other strings are returned unmodified.
2799 cap-get-file
2801 cap-get-file path
2802 This function returns the Linux capabilities attached to "path". The
2804 capabilities set is returned in text form (see cap_to_text(3)).
2805 If no capabilities are attached to a file, an empty string is returned.
2807 This command depends on the feature "linuxcaps". See also "feature-
2809 available".
2810 cap-set-file
2812 cap-set-file path cap
2813 This function sets the Linux capabilities attached to "path". The
2815 capabilities set "cap" should be passed in text form (see
2816 cap_from_text(3)).
2817 This command depends on the feature "linuxcaps". See also "feature-
2819 available".
2820 case-sensitive-path
2822 case-sensitive-path path
2823 This can be used to resolve case insensitive paths on a filesystem
2825 which is case sensitive. The use case is to resolve paths which you
2826 have read from Windows configuration files or the Windows Registry, to
2827 the true path.
2828 The command handles a peculiarity of the Linux ntfs-3g filesystem
2830 driver (and probably others), which is that although the underlying
2831 filesystem is case-insensitive, the driver exports the filesystem to
2832 Linux as case-sensitive.
2833 One consequence of this is that special directories such as C:\windows
2835 may appear as /WINDOWS or /windows (or other things) depending on the
2836 precise details of how they were created. In Windows itself this would
2837 not be a problem.
2838 Bug or feature? You decide:
2840 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2841 "case-sensitive-path" attempts to resolve the true case of each element
2843 in the path. It will return a resolved path if either the full path or
2844 its parent directory exists. If the parent directory exists but the
2845 full path does not, the case of the parent directory will be correctly
2846 resolved, and the remainder appended unmodified. For example, if the
2847 file "/Windows/System32/netkvm.sys" exists:
2848 "case-sensitive-path" ("/windows/system32/netkvm.sys")
2850 "Windows/System32/netkvm.sys"
2851 "case-sensitive-path" ("/windows/system32/NoSuchFile")
2853 "Windows/System32/NoSuchFile"
2854 "case-sensitive-path" ("/windows/system33/netkvm.sys")
2856 ERROR
2857 Note: Because of the above behaviour, "case-sensitive-path" cannot be
2859 used to check for the existence of a file.
2860 Note: This function does not handle drive names, backslashes etc.
2862 See also "realpath".
2864 cat
2866 cat path
2867 Return the contents of the file named "path".
2869 Because, in C, this function returns a "char *", there is no way to
2871 differentiate between a "\0" character in a file and end of string. To
2872 handle binary files, use the "read-file" or "download" functions.
2873 checksum
2875 checksum csumtype path
2876 This call computes the MD5, SHAx or CRC checksum of the file named
2878 "path".
2879 The type of checksum to compute is given by the "csumtype" parameter
2881 which must have one of the following values:
2882 "crc"
2884 Compute the cyclic redundancy check (CRC) specified by POSIX for
2885 the "cksum" command.
2886 "md5"
2888 Compute the MD5 hash (using the "md5sum" program).
2889 "sha1"
2891 Compute the SHA1 hash (using the "sha1sum" program).
2892 "sha224"
2894 Compute the SHA224 hash (using the "sha224sum" program).
2895 "sha256"
2897 Compute the SHA256 hash (using the "sha256sum" program).
2898 "sha384"
2900 Compute the SHA384 hash (using the "sha384sum" program).
2901 "sha512"
2903 Compute the SHA512 hash (using the "sha512sum" program).
2904 The checksum is returned as a printable string.
2906 To get the checksum for a device, use "checksum-device".
2908 To get the checksums for many files, use "checksums-out".
2910 checksum-device
2912 checksum-device csumtype device
2913 This call computes the MD5, SHAx or CRC checksum of the contents of the
2915 device named "device". For the types of checksums supported see the
2916 "checksum" command.
2917 checksums-out
2919 checksums-out csumtype directory (sumsfile|-)
2920 This command computes the checksums of all regular files in directory
2922 and then emits a list of those checksums to the local output file
2923 "sumsfile".
2924 This can be used for verifying the integrity of a virtual machine.
2926 However to be properly secure you should pay attention to the output of
2927 the checksum command (it uses the ones from GNU coreutils). In
2928 particular when the filename is not printable, coreutils uses a special
2929 backslash syntax. For more information, see the GNU coreutils info
2930 file.
2931 Use "-" instead of a filename to read/write from stdin/stdout.
2933 chmod
2935 chmod mode path
2936 Change the mode (permissions) of "path" to "mode". Only numeric modes
2938 are supported.
2939 Note: When using this command from guestfish, "mode" by default would
2941 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2942 700.
2943 The mode actually set is affected by the umask.
2945 chown
2947 chown owner group path
2948 Change the file owner to "owner" and group to "group".
2950 Only numeric uid and gid are supported. If you want to use names, you
2952 will need to locate and parse the password file yourself (Augeas
2953 support makes this relatively easy).
2954 clear-backend-setting
2956 clear-backend-setting name
2957 If there is a backend setting string matching "name" or beginning with
2959 "name=", then that string is removed from the backend settings.
2960 This call returns the number of strings which were removed (which may
2962 be 0, 1 or greater than 1).
2963 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2965 command
2967 command 'arguments ...'
2968 This call runs a command from the guest filesystem. The filesystem
2970 must be mounted, and must contain a compatible operating system (ie.
2971 something Linux, with the same or compatible processor architecture).
2972 The single parameter is an argv-style list of arguments. The first
2974 element is the name of the program to run. Subsequent elements are
2975 parameters. The list must be non-empty (ie. must contain a program
2976 name). Note that the command runs directly, and is not invoked via the
2977 shell (see "sh").
2978 The return value is anything printed to stdout by the command.
2980 If the command returns a non-zero exit status, then this function
2982 returns an error message. The error message string is the content of
2983 stderr from the command.
2984 The $PATH environment variable will contain at least /usr/bin and /bin.
2986 If you require a program from another location, you should provide the
2987 full path in the first parameter.
2988 Shared libraries and data files required by the program must be
2990 available on filesystems which are mounted in the correct places. It
2991 is the caller’s responsibility to ensure all filesystems that are
2992 needed are mounted at the right locations.
2993 Because of the message protocol, there is a transfer limit of somewhere
2995 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
2996 command-lines
2998 command-lines 'arguments ...'
2999 This is the same as "command", but splits the result into a list of
3001 lines.
3002 See also: "sh-lines"
3004 Because of the message protocol, there is a transfer limit of somewhere
3006 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3007 compress-device-out
3009 compress-device-out ctype device (zdevice|-) [level:N]
3010 This command compresses "device" and writes it out to the local file
3012 "zdevice".
3013 The "ctype" and optional "level" parameters have the same meaning as in
3015 "compress-out".
3016 Use "-" instead of a filename to read/write from stdin/stdout.
3018 This command has one or more optional arguments. See "OPTIONAL
3020 ARGUMENTS".
3021 compress-out
3023 compress-out ctype file (zfile|-) [level:N]
3024 This command compresses file and writes it out to the local file zfile.
3026 The compression program used is controlled by the "ctype" parameter.
3028 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3029 Some compression types may not be supported by particular builds of
3030 libguestfs, in which case you will get an error containing the
3031 substring "not supported".
3032 The optional "level" parameter controls compression level. The meaning
3034 and default for this parameter depends on the compression program being
3035 used.
3036 Use "-" instead of a filename to read/write from stdin/stdout.
3038 This command has one or more optional arguments. See "OPTIONAL
3040 ARGUMENTS".
3041 config
3043 config hvparam hvvalue
3044 This can be used to add arbitrary hypervisor parameters of the form
3046 -param value. Actually it’s not quite arbitrary - we prevent you from
3047 setting some parameters which would interfere with parameters that we
3048 use.
3049 The first character of "hvparam" string must be a "-" (dash).
3051 "hvvalue" can be NULL.
3053 copy-attributes
3055 copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]
3056 Copy the attributes of a path (which can be a file or a directory) to
3058 another path.
3059 By default "no" attribute is copied, so make sure to specify any (or
3061 "all" to copy everything).
3062 The optional arguments specify which attributes can be copied:
3064 "mode"
3066 Copy part of the file mode from "source" to "destination". Only the
3067 UNIX permissions and the sticky/setuid/setgid bits can be copied.
3068 "xattributes"
3070 Copy the Linux extended attributes (xattrs) from "source" to
3071 "destination". This flag does nothing if the linuxxattrs feature
3072 is not available (see "feature-available").
3073 "ownership"
3075 Copy the owner uid and the group gid of "source" to "destination".
3076 "all"
3078 Copy all the attributes from "source" to "destination". Enabling it
3079 enables all the other flags, if they are not specified already.
3080 This command has one or more optional arguments. See "OPTIONAL
3082 ARGUMENTS".
3083 copy-device-to-device
3085 copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3086 The four calls "copy-device-to-device", "copy-device-to-file", "copy-
3088 file-to-device", and "copy-file-to-file" let you copy from a source
3089 (device|file) to a destination (device|file).
3090 Partial copies can be made since you can specify optionally the source
3092 offset, destination offset and size to copy. These values are all
3093 specified in bytes. If not given, the offsets both default to zero,
3094 and the size defaults to copying as much as possible until we hit the
3095 end of the source.
3096 The source and destination may be the same object. However overlapping
3098 regions may not be copied correctly.
3099 If the destination is a file, it is created if required. If the
3101 destination file is not large enough, it is extended.
3102 If the destination is a file and the "append" flag is not set, then the
3104 destination file is truncated. If the "append" flag is set, then the
3105 copy appends to the destination file. The "append" flag currently
3106 cannot be set for devices.
3107 If the "sparse" flag is true then the call avoids writing blocks that
3109 contain only zeroes, which can help in some situations where the
3110 backing disk is thin-provisioned. Note that unless the target is
3111 already zeroed, using this option will result in incorrect copying.
3112 This command has one or more optional arguments. See "OPTIONAL
3114 ARGUMENTS".
3115 copy-device-to-file
3117 copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3118 See "copy-device-to-device" for a general overview of this call.
3120 This command has one or more optional arguments. See "OPTIONAL
3122 ARGUMENTS".
3123 copy-file-to-device
3125 copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3126 See "copy-device-to-device" for a general overview of this call.
3128 This command has one or more optional arguments. See "OPTIONAL
3130 ARGUMENTS".
3131 copy-file-to-file
3133 copy-file-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 is not the function you want for copying files. This is for
3138 copying blocks within existing files. See "cp", "cp-a" and "mv" for
3139 general file copying and moving functions.
3140 This command has one or more optional arguments. See "OPTIONAL
3142 ARGUMENTS".
3143 copy-size
3145 copy-size src dest size
3146 This command copies exactly "size" bytes from one source device or file
3148 "src" to another destination device or file "dest".
3149 Note this will fail if the source is too short or if the destination is
3151 not large enough.
3152 This function is deprecated. In new code, use the "copy-device-to-
3154 device" call instead.
3155 Deprecated functions will not be removed from the API, but the fact
3157 that they are deprecated indicates that there are problems with correct
3158 use of these functions.
3159 cp
3161 cp src dest
3162 This copies a file from "src" to "dest" where "dest" is either a
3164 destination filename or destination directory.
3165 cp-a
3167 cp-a src dest
3168 This copies a file or directory from "src" to "dest" recursively using
3170 the "cp -a" command.
3171 cp-r
3173 cp-r src dest
3174 This copies a file or directory from "src" to "dest" recursively using
3176 the "cp -rP" command.
3177 Most users should use "cp-a" instead. This command is useful when you
3179 don't want to preserve permissions, because the target filesystem does
3180 not support it (primarily when writing to DOS FAT filesystems).
3181 cpio-out
3183 cpio-out directory (cpiofile|-) [format:..]
3184 This command packs the contents of directory and downloads it to local
3186 file "cpiofile".
3187 The optional "format" parameter can be used to select the format. Only
3189 the following formats are currently permitted:
3190 "newc"
3192 New (SVR4) portable format. This format happens to be compatible
3193 with the cpio-like format used by the Linux kernel for initramfs.
3194 This is the default format.
3196 "crc"
3198 New (SVR4) portable format with a checksum.
3199 Use "-" instead of a filename to read/write from stdin/stdout.
3201 This command has one or more optional arguments. See "OPTIONAL
3203 ARGUMENTS".
3204 dd
3206 dd src dest
3207 This command copies from one source device or file "src" to another
3209 destination device or file "dest". Normally you would use this to copy
3210 to or from a device or partition, for example to duplicate a
3211 filesystem.
3212 If the destination is a device, it must be as large or larger than the
3214 source file or device, otherwise the copy will fail. This command
3215 cannot do partial copies (see "copy-device-to-device").
3216 This function is deprecated. In new code, use the "copy-device-to-
3218 device" call instead.
3219 Deprecated functions will not be removed from the API, but the fact
3221 that they are deprecated indicates that there are problems with correct
3222 use of these functions.
3223 device-index
3225 device-index device
3226 This function takes a device name (eg. "/dev/sdb") and returns the
3228 index of the device in the list of devices.
3229 Index numbers start from 0. The named device must exist, for example
3231 as a string returned from "list-devices".
3232 See also "list-devices", "part-to-dev".
3234 df
3236 df
3237 This command runs the "df" command to report disk space used.
3239 This command is mostly useful for interactive sessions. It is not
3241 intended that you try to parse the output string. Use "statvfs" from
3242 programs.
3243 df-h
3245 df-h
3246 This command runs the "df -h" command to report disk space used in
3248 human-readable format.
3249 This command is mostly useful for interactive sessions. It is not
3251 intended that you try to parse the output string. Use "statvfs" from
3252 programs.
3253 disk-create
3255 disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]
3256 Create a blank disk image called filename (a host file) with format
3258 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
3259 If used with the optional "backingfile" parameter, then a snapshot is
3261 created on top of the backing file. In this case, "size" must be
3262 passed as "-1". The size of the snapshot is the same as the size of
3263 the backing file, which is discovered automatically. You are
3264 encouraged to also pass "backingformat" to describe the format of
3265 "backingfile".
3266 If filename refers to a block device, then the device is formatted.
3268 The "size" is ignored since block devices have an intrinsic size.
3269 The other optional parameters are:
3271 "preallocation"
3273 If format is "raw", then this can be either "off" (or "sparse") or
3274 "full" to create a sparse or fully allocated file respectively.
3275 The default is "off".
3276 If format is "qcow2", then this can be "off" (or "sparse"),
3278 "metadata" or "full". Preallocating metadata can be faster when
3279 doing lots of writes, but uses more space. The default is "off".
3280 "compat"
3282 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
3283 supported by qemu ≥ 1.1.
3284 "clustersize"
3286 "qcow2" only: Change the qcow2 cluster size. The default is 65536
3287 (bytes) and this setting may be any power of two between 512 and
3288 2097152.
3289 Note that this call does not add the new disk to the handle. You may
3291 need to call "add-drive-opts" separately.
3292 This command has one or more optional arguments. See "OPTIONAL
3294 ARGUMENTS".
3295 disk-format
3297 disk-format filename
3298 Detect and return the format of the disk image called filename.
3300 filename can also be a host device, etc. If the format of the image
3301 could not be detected, then "unknown" is returned.
3302 Note that detecting the disk format can be insecure under some
3304 circumstances. See "CVE-2010-3851" in guestfs(3).
3305 See also: "DISK IMAGE FORMATS" in guestfs(3)
3307 disk-has-backing-file
3309 disk-has-backing-file filename
3310 Detect and return whether the disk image filename has a backing file.
3312 Note that detecting disk features can be insecure under some
3314 circumstances. See "CVE-2010-3851" in guestfs(3).
3315 disk-virtual-size
3317 disk-virtual-size filename
3318 Detect and return the virtual size in bytes of the disk image called
3320 filename.
3321 Note that detecting disk features can be insecure under some
3323 circumstances. See "CVE-2010-3851" in guestfs(3).
3324 dmesg
3326 dmesg
3327 This returns the kernel messages ("dmesg" output) from the guest
3329 kernel. This is sometimes useful for extended debugging of problems.
3330 Another way to get the same information is to enable verbose messages
3332 with "set-verbose" or by setting the environment variable
3333 "LIBGUESTFS_DEBUG=1" before running the program.
3334 download
3336 download remotefilename (filename|-)
3337 Download file remotefilename and save it as filename on the local
3339 machine.
3340 filename can also be a named pipe.
3342 See also "upload", "cat".
3344 Use "-" instead of a filename to read/write from stdin/stdout.
3346 download-blocks
3348 download-blocks device start stop (filename|-) [unallocated:true|false]
3349 Download the data units from start address to stop from the disk
3351 partition (eg. /dev/sda1) and save them as filename on the local
3352 machine.
3353 The use of this API on sparse disk image formats such as QCOW, may
3355 result in large zero-filled files downloaded on the host.
3356 The size of a data unit varies across filesystem implementations. On
3358 NTFS filesystems data units are referred as clusters while on ExtX ones
3359 they are referred as fragments.
3360 If the optional "unallocated" flag is true (default is false), only the
3362 unallocated blocks will be extracted. This is useful to detect hidden
3363 data or to retrieve deleted files which data units have not been
3364 overwritten yet.
3365 Use "-" instead of a filename to read/write from stdin/stdout.
3367 This command has one or more optional arguments. See "OPTIONAL
3369 ARGUMENTS".
3370 This command depends on the feature "sleuthkit". See also "feature-
3372 available".
3373 download-inode
3375 download-inode device inode (filename|-)
3376 Download a file given its inode from the disk partition (eg. /dev/sda1)
3378 and save it as filename on the local machine.
3379 It is not required to mount the disk to run this command.
3381 The command is capable of downloading deleted or inaccessible files.
3383 Use "-" instead of a filename to read/write from stdin/stdout.
3385 This command depends on the feature "sleuthkit". See also "feature-
3387 available".
3388 download-offset
3390 download-offset remotefilename (filename|-) offset size
3391 Download file remotefilename and save it as filename on the local
3393 machine.
3394 remotefilename is read for "size" bytes starting at "offset" (this
3396 region must be within the file or device).
3397 Note that there is no limit on the amount of data that can be
3399 downloaded with this call, unlike with "pread", and this call always
3400 reads the full amount unless an error occurs.
3401 See also "download", "pread".
3403 Use "-" instead of a filename to read/write from stdin/stdout.
3405 drop-caches
3407 drop-caches whattodrop
3408 This instructs the guest kernel to drop its page cache, and/or dentries
3410 and inode caches. The parameter "whattodrop" tells the kernel what
3411 precisely to drop, see http://linux-mm.org/Drop_Caches
3412 Setting "whattodrop" to 3 should drop everything.
3414 This automatically calls sync(2) before the operation, so that the
3416 maximum guest memory is freed.
3417 du
3419 du path
3420 This command runs the "du -s" command to estimate file space usage for
3422 "path".
3423 "path" can be a file or a directory. If "path" is a directory then the
3425 estimate includes the contents of the directory and all subdirectories
3426 (recursively).
3427 The result is the estimated size in kilobytes (ie. units of 1024
3429 bytes).
3430 e2fsck
3432 e2fsck device [correct:true|false] [forceall:true|false]
3433 This runs the ext2/ext3 filesystem checker on "device". It can take
3435 the following optional arguments:
3436 "correct"
3438 Automatically repair the file system. This option will cause e2fsck
3439 to automatically fix any filesystem problems that can be safely
3440 fixed without human intervention.
3441 This option may not be specified at the same time as the "forceall"
3443 option.
3444 "forceall"
3446 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
3447 used non-interactively.
3448 This option may not be specified at the same time as the "correct"
3450 option.
3451 This command has one or more optional arguments. See "OPTIONAL
3453 ARGUMENTS".
3454 e2fsck-f
3456 e2fsck-f device
3457 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3459 checker on "device", noninteractively (-p), even if the filesystem
3460 appears to be clean (-f).
3461 This function is deprecated. In new code, use the "e2fsck" call
3463 instead.
3464 Deprecated functions will not be removed from the API, but the fact
3466 that they are deprecated indicates that there are problems with correct
3467 use of these functions.
3468 echo-daemon
3470 echo-daemon 'words ...'
3471 This command concatenates the list of "words" passed with single spaces
3473 between them and returns the resulting string.
3474 You can use this command to test the connection through to the daemon.
3476 See also "ping-daemon".
3478 egrep
3480 egrep regex path
3481 This calls the external "egrep" program and returns the matching lines.
3483 Because of the message protocol, there is a transfer limit of somewhere
3485 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3486 This function is deprecated. In new code, use the "grep" call instead.
3488 Deprecated functions will not be removed from the API, but the fact
3490 that they are deprecated indicates that there are problems with correct
3491 use of these functions.
3492 egrepi
3494 egrepi regex path
3495 This calls the external "egrep -i" program and returns the matching
3497 lines.
3498 Because of the message protocol, there is a transfer limit of somewhere
3500 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3501 This function is deprecated. In new code, use the "grep" call instead.
3503 Deprecated functions will not be removed from the API, but the fact
3505 that they are deprecated indicates that there are problems with correct
3506 use of these functions.
3507 equal
3509 equal file1 file2
3510 This compares the two files file1 and file2 and returns true if their
3512 content is exactly equal, or false otherwise.
3513 The external cmp(1) program is used for the comparison.
3515 exists
3517 exists path
3518 This returns "true" if and only if there is a file, directory (or
3520 anything) with the given "path" name.
3521 See also "is-file", "is-dir", "stat".
3523 extlinux
3525 extlinux directory
3526 Install the SYSLINUX bootloader on the device mounted at directory.
3528 Unlike "syslinux" which requires a FAT filesystem, this can be used on
3529 an ext2/3/4 or btrfs filesystem.
3530 The directory parameter can be either a mountpoint, or a directory
3532 within the mountpoint.
3533 You also have to mark the partition as "active" ("part-set-bootable")
3535 and a Master Boot Record must be installed (eg. using "pwrite-device")
3536 on the first sector of the whole disk. The SYSLINUX package comes with
3537 some suitable Master Boot Records. See the extlinux(1) man page for
3538 further information.
3539 Additional configuration can be supplied to SYSLINUX by placing a file
3541 called extlinux.conf on the filesystem under directory. For further
3542 information about the contents of this file, see extlinux(1).
3543 See also "syslinux".
3545 This command depends on the feature "extlinux". See also "feature-
3547 available".
3548 f2fs-expand
3550 f2fs-expand device
3551 This expands a f2fs filesystem to match the size of the underlying
3553 device.
3554 This command depends on the feature "f2fs". See also "feature-
3556 available".
3557 fallocate
3559 fallocate path len
3560 This command preallocates a file (containing zero bytes) named "path"
3562 of size "len" bytes. If the file exists already, it is overwritten.
3563 Do not confuse this with the guestfish-specific "alloc" command which
3565 allocates a file in the host and attaches it as a device.
3566 This function is deprecated. In new code, use the "fallocate64" call
3568 instead.
3569 Deprecated functions will not be removed from the API, but the fact
3571 that they are deprecated indicates that there are problems with correct
3572 use of these functions.
3573 fallocate64
3575 fallocate64 path len
3576 This command preallocates a file (containing zero bytes) named "path"
3578 of size "len" bytes. If the file exists already, it is overwritten.
3579 Note that this call allocates disk blocks for the file. To create a
3581 sparse file use "truncate-size" instead.
3582 The deprecated call "fallocate" does the same, but owing to an
3584 oversight it only allowed 30 bit lengths to be specified, effectively
3585 limiting the maximum size of files created through that call to 1GB.
3586 Do not confuse this with the guestfish-specific "alloc" and "sparse"
3588 commands which create a file in the host and attach it as a device.
3589 feature-available
3591 feature-available 'groups ...'
3592 This is the same as "available", but unlike that call it returns a
3594 simple true/false boolean result, instead of throwing an exception if a
3595 feature is not found. For other documentation see "available".
3596 fgrep
3598 fgrep pattern path
3599 This calls the external "fgrep" program and returns the matching lines.
3601 Because of the message protocol, there is a transfer limit of somewhere
3603 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3604 This function is deprecated. In new code, use the "grep" call instead.
3606 Deprecated functions will not be removed from the API, but the fact
3608 that they are deprecated indicates that there are problems with correct
3609 use of these functions.
3610 fgrepi
3612 fgrepi pattern path
3613 This calls the external "fgrep -i" program and returns the matching
3615 lines.
3616 Because of the message protocol, there is a transfer limit of somewhere
3618 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
3619 This function is deprecated. In new code, use the "grep" call instead.
3621 Deprecated functions will not be removed from the API, but the fact
3623 that they are deprecated indicates that there are problems with correct
3624 use of these functions.
3625 file
3627 file path
3628 This call uses the standard file(1) command to determine the type or
3630 contents of the file.
3631 This call will also transparently look inside various types of
3633 compressed file.
3634 The exact command which runs is "file -zb path". Note in particular
3636 that the filename is not prepended to the output (the -b option).
3637 The output depends on the output of the underlying file(1) command and
3639 it can change in future in ways beyond our control. In other words,
3640 the output is not guaranteed by the ABI.
3641 See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
3643 "is-zero".
3644 file-architecture
3646 file-architecture filename
3647 This detects the architecture of the binary filename, and returns it if
3649 known.
3650 Currently defined architectures are:
3652 "aarch64"
3654 64 bit ARM.
3655 "arm"
3657 32 bit ARM.
3658 "i386"
3660 This string is returned for all 32 bit i386, i486, i586, i686
3661 binaries irrespective of the precise processor requirements of the
3662 binary.
3663 "ia64"
3665 Intel Itanium.
3666 "ppc"
3668 32 bit Power PC.
3669 "ppc64"
3671 64 bit Power PC (big endian).
3672 "ppc64le"
3674 64 bit Power PC (little endian).
3675 "riscv32"
3677 "riscv64"
3678 "riscv128"
3679 RISC-V 32-, 64- or 128-bit variants.
3680 "s390"
3682 31 bit IBM S/390.
3683 "s390x"
3685 64 bit IBM S/390.
3686 "sparc"
3688 32 bit SPARC.
3689 "sparc64"
3691 64 bit SPARC V9 and above.
3692 "x86_64"
3694 64 bit x86-64.
3695 Libguestfs may return other architecture strings in future.
3697 The function works on at least the following types of files:
3699 · many types of Un*x and Linux binary
3701 · many types of Un*x and Linux shared library
3703 · Windows Win32 and Win64 binaries
3705 · Windows Win32 and Win64 DLLs
3707 Win32 binaries and DLLs return "i386".
3709 Win64 binaries and DLLs return "x86_64".
3711 · Linux kernel modules
3713 · Linux new-style initrd images
3715 · some non-x86 Linux vmlinuz kernels
3717 What it can't do currently:
3719 · static libraries (libfoo.a)
3721 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
3723 · x86 Linux vmlinuz kernels
3725 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
3727 and compressed code, and are horribly hard to unpack. If you want
3728 to find the architecture of a kernel, use the architecture of the
3729 associated initrd or kernel module(s) instead.
3730 filesize
3732 filesize file
3733 This command returns the size of file in bytes.
3735 To get other stats about a file, use "stat", "lstat", "is-dir", "is-
3737 file" etc. To get the size of block devices, use "blockdev-getsize64".
3738 filesystem-available
3740 filesystem-available filesystem
3741 Check whether libguestfs supports the named filesystem. The argument
3743 "filesystem" is a filesystem name, such as "ext3".
3744 You must call "launch" before using this command.
3746 This is mainly useful as a negative test. If this returns true, it
3748 doesn't mean that a particular filesystem can be created or mounted,
3749 since filesystems can fail for other reasons such as it being a later
3750 version of the filesystem, or having incompatible features, or lacking
3751 the right mkfs.<fs> tool.
3752 See also "available", "feature-available", "AVAILABILITY" in
3754 guestfs(3).
3755 filesystem-walk
3757 filesystem-walk device
3758 Walk through the internal structures of a disk partition (eg.
3760 /dev/sda1) in order to return a list of all the files and directories
3761 stored within.
3762 It is not necessary to mount the disk partition to run this command.
3764 All entries in the filesystem are returned. This function can list
3766 deleted or unaccessible files. The entries are not sorted.
3767 The "tsk_dirent" structure contains the following fields.
3769 "tsk_inode"
3771 Filesystem reference number of the node. It might be 0 if the node
3772 has been deleted.
3773 "tsk_type"
3775 Basic file type information. See below for a detailed list of
3776 values.
3777 "tsk_size"
3779 File size in bytes. It might be "-1" if the node has been deleted.
3780 "tsk_name"
3782 The file path relative to its directory.
3783 "tsk_flags"
3785 Bitfield containing extra information regarding the entry. It
3786 contains the logical OR of the following values:
3787 0x0001
3789 If set to 1, the file is allocated and visible within the
3790 filesystem. Otherwise, the file has been deleted. Under
3791 certain circumstances, the function "download_inode" can be
3792 used to recover deleted files.
3793 0x0002
3795 Filesystem such as NTFS and Ext2 or greater, separate the file
3796 name from the metadata structure. The bit is set to 1 when the
3797 file name is in an unallocated state and the metadata structure
3798 is in an allocated one. This generally implies the metadata
3799 has been reallocated to a new file. Therefore, information
3800 such as file type, file size, timestamps, number of links and
3801 symlink target might not correspond with the ones of the
3802 original deleted entry.
3803 0x0004
3805 The bit is set to 1 when the file is compressed using
3806 filesystem native compression support (NTFS). The API is not
3807 able to detect application level compression.
3808 "tsk_atime_sec"
3810 "tsk_atime_nsec"
3811 "tsk_mtime_sec"
3812 "tsk_mtime_nsec"
3813 "tsk_ctime_sec"
3814 "tsk_ctime_nsec"
3815 "tsk_crtime_sec"
3816 "tsk_crtime_nsec"
3817 Respectively, access, modification, last status change and creation
3818 time in Unix format in seconds and nanoseconds.
3819 "tsk_nlink"
3821 Number of file names pointing to this entry.
3822 "tsk_link"
3824 If the entry is a symbolic link, this field will contain the path
3825 to the target file.
3826 The "tsk_type" field will contain one of the following characters:
3828 'b' Block special
3830 'c' Char special
3832 'd' Directory
3834 'f' FIFO (named pipe)
3836 'l' Symbolic link
3838 'r' Regular file
3840 's' Socket
3842 'h' Shadow inode (Solaris)
3844 'w' Whiteout inode (BSD)
3846 'u' Unknown file type
3848 This command depends on the feature "libtsk". See also "feature-
3850 available".
3851 fill
3853 fill c len path
3854 This command creates a new file called "path". The initial content of
3856 the file is "len" octets of "c", where "c" must be a number in the
3857 range "[0..255]".
3858 To fill a file with zero bytes (sparsely), it is much more efficient to
3860 use "truncate-size". To create a file with a pattern of repeating
3861 bytes use "fill-pattern".
3862 fill-dir
3864 fill-dir dir nr
3865 This function, useful for testing filesystems, creates "nr" empty files
3867 in the directory "dir" with names 00000000 through "nr-1" (ie. each
3868 file name is 8 digits long padded with zeroes).
3869 fill-pattern
3871 fill-pattern pattern len path
3872 This function is like "fill" except that it creates a new file of
3874 length "len" containing the repeating pattern of bytes in "pattern".
3875 The pattern is truncated if necessary to ensure the length of the file
3876 is exactly "len" bytes.
3877 find
3879 find directory
3880 This command lists out all files and directories, recursively, starting
3882 at directory. It is essentially equivalent to running the shell
3883 command "find directory -print" but some post-processing happens on the
3884 output, described below.
3885 This returns a list of strings without any prefix. Thus if the
3887 directory structure was:
3888 /tmp/a
3890 /tmp/b
3891 /tmp/c/d
3892 then the returned list from "find" /tmp would be 4 elements:
3894 a
3896 b
3897 c
3898 c/d
3899 If directory is not a directory, then this command returns an error.
3901 The returned list is sorted.
3903 find0
3905 find0 directory (files|-)
3906 This command lists out all files and directories, recursively, starting
3908 at directory, placing the resulting list in the external file called
3909 files.
3910 This command works the same way as "find" with the following
3912 exceptions:
3913 · The resulting list is written to an external file.
3915 · Items (filenames) in the result are separated by "\0" characters.
3917 See find(1) option -print0.
3918 · The result list is not sorted.
3920 Use "-" instead of a filename to read/write from stdin/stdout.
3922 find-inode
3924 find-inode device inode
3925 Searches all the entries associated with the given inode.
3927 For each entry, a "tsk_dirent" structure is returned. See
3929 "filesystem_walk" for more information about "tsk_dirent" structures.
3930 This command depends on the feature "libtsk". See also "feature-
3932 available".
3933 findfs-label
3935 findfs-label label
3936 This command searches the filesystems and returns the one which has the
3938 given label. An error is returned if no such filesystem can be found.
3939 To find the label of a filesystem, use "vfs-label".
3941 findfs-uuid
3943 findfs-uuid uuid
3944 This command searches the filesystems and returns the one which has the
3946 given UUID. An error is returned if no such filesystem can be found.
3947 To find the UUID of a filesystem, use "vfs-uuid".
3949 fsck
3951 fsck fstype device
3952 This runs the filesystem checker (fsck) on "device" which should have
3954 filesystem type "fstype".
3955 The returned integer is the status. See fsck(8) for the list of status
3957 codes from "fsck".
3958 Notes:
3960 · Multiple status codes can be summed together.
3962 · A non-zero return code can mean "success", for example if errors
3964 have been corrected on the filesystem.
3965 · Checking or repairing NTFS volumes is not supported (by linux-
3967 ntfs).
3968 This command is entirely equivalent to running "fsck -a -t fstype
3970 device".
3971 fstrim
3973 fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]
3974 Trim the free space in the filesystem mounted on "mountpoint". The
3976 filesystem must be mounted read-write.
3977 The filesystem contents are not affected, but any free space in the
3979 filesystem is "trimmed", that is, given back to the host device, thus
3980 making disk images more sparse, allowing unused space in qcow2 files to
3981 be reused, etc.
3982 This operation requires support in libguestfs, the mounted filesystem,
3984 the host filesystem, qemu and the host kernel. If this support isn't
3985 present it may give an error or even appear to run but do nothing.
3986 In the case where the kernel vfs driver does not support trimming, this
3988 call will fail with errno set to "ENOTSUP". Currently this happens
3989 when trying to trim FAT filesystems.
3990 See also "zero-free-space". That is a slightly different operation
3992 that turns free space in the filesystem into zeroes. It is valid to
3993 call "fstrim" either instead of, or after calling "zero-free-space".
3994 This command has one or more optional arguments. See "OPTIONAL
3996 ARGUMENTS".
3997 This command depends on the feature "fstrim". See also "feature-
3999 available".
4000 get-append
4002 get-append
4003 Return the additional kernel options which are added to the libguestfs
4005 appliance kernel command line.
4006 If "NULL" then no options are added.
4008 get-attach-method
4010 get-attach-method
4011 Return the current backend.
4013 See "set-backend" and "BACKEND" in guestfs(3).
4015 This function is deprecated. In new code, use the "get-backend" call
4017 instead.
4018 Deprecated functions will not be removed from the API, but the fact
4020 that they are deprecated indicates that there are problems with correct
4021 use of these functions.
4022 get-autosync
4024 get-autosync
4025 Get the autosync flag.
4027 get-backend
4029 get-backend
4030 Return the current backend.
4032 This handle property was previously called the "attach method".
4034 See "set-backend" and "BACKEND" in guestfs(3).
4036 get-backend-setting
4038 get-backend-setting name
4039 Find a backend setting string which is either "name" or begins with
4041 "name=". If "name", this returns the string "1". If "name=", this
4042 returns the part after the equals sign (which may be an empty string).
4043 If no such setting is found, this function throws an error. The errno
4045 (see "last-errno") will be "ESRCH" in this case.
4046 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4048 get-backend-settings
4050 get-backend-settings
4051 Return the current backend settings.
4053 This call returns all backend settings strings. If you want to find a
4055 single backend setting, see "get-backend-setting".
4056 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4058 get-cachedir
4060 get-cachedir
4061 Get the directory used by the handle to store the appliance cache.
4063 get-direct
4065 get-direct
4066 Return the direct appliance mode flag.
4068 This function is deprecated. In new code, use the "internal-get-
4070 console-socket" call instead.
4071 Deprecated functions will not be removed from the API, but the fact
4073 that they are deprecated indicates that there are problems with correct
4074 use of these functions.
4075 get-e2attrs
4077 get-e2attrs file
4078 This returns the file attributes associated with file.
4080 The attributes are a set of bits associated with each inode which
4082 affect the behaviour of the file. The attributes are returned as a
4083 string of letters (described below). The string may be empty,
4084 indicating that no file attributes are set for this file.
4085 These attributes are only present when the file is located on an
4087 ext2/3/4 filesystem. Using this call on other filesystem types will
4088 result in an error.
4089 The characters (file attributes) in the returned string are currently:
4091 'A' When the file is accessed, its atime is not modified.
4093 'a' The file is append-only.
4095 'c' The file is compressed on-disk.
4097 'D' (Directories only.) Changes to this directory are written
4099 synchronously to disk.
4100 'd' The file is not a candidate for backup (see dump(8)).
4102 'E' The file has compression errors.
4104 'e' The file is using extents.
4106 'h' The file is storing its blocks in units of the filesystem blocksize
4108 instead of sectors.
4109 'I' (Directories only.) The directory is using hashed trees.
4111 'i' The file is immutable. It cannot be modified, deleted or renamed.
4113 No link can be created to this file.
4114 'j' The file is data-journaled.
4116 's' When the file is deleted, all its blocks will be zeroed.
4118 'S' Changes to this file are written synchronously to disk.
4120 'T' (Directories only.) This is a hint to the block allocator that
4122 subdirectories contained in this directory should be spread across
4123 blocks. If not present, the block allocator will try to group
4124 subdirectories together.
4125 't' For a file, this disables tail-merging. (Not used by upstream
4127 implementations of ext2.)
4128 'u' When the file is deleted, its blocks will be saved, allowing the
4130 file to be undeleted.
4131 'X' The raw contents of the compressed file may be accessed.
4133 'Z' The compressed file is dirty.
4135 More file attributes may be added to this list later. Not all file
4137 attributes may be set for all kinds of files. For detailed
4138 information, consult the chattr(1) man page.
4139 See also "set-e2attrs".
4141 Don't confuse these attributes with extended attributes (see
4143 "getxattr").
4144 get-e2generation
4146 get-e2generation file
4147 This returns the ext2 file generation of a file. The generation (which
4149 used to be called the "version") is a number associated with an inode.
4150 This is most commonly used by NFS servers.
4151 The generation is only present when the file is located on an ext2/3/4
4153 filesystem. Using this call on other filesystem types will result in
4154 an error.
4155 See "set-e2generation".
4157 get-e2label
4159 get-e2label device
4160 This returns the ext2/3/4 filesystem label of the filesystem on
4162 "device".
4163 This function is deprecated. In new code, use the "vfs-label" call
4165 instead.
4166 Deprecated functions will not be removed from the API, but the fact
4168 that they are deprecated indicates that there are problems with correct
4169 use of these functions.
4170 get-e2uuid
4172 get-e2uuid device
4173 This returns the ext2/3/4 filesystem UUID of the filesystem on
4175 "device".
4176 This function is deprecated. In new code, use the "vfs-uuid" call
4178 instead.
4179 Deprecated functions will not be removed from the API, but the fact
4181 that they are deprecated indicates that there are problems with correct
4182 use of these functions.
4183 get-hv
4185 get-hv
4186 Return the current hypervisor binary.
4188 This is always non-NULL. If it wasn't set already, then this will
4190 return the default qemu binary name.
4191 get-identifier
4193 get-identifier
4194 Get the handle identifier. See "set-identifier".
4196 get-libvirt-requested-credential-challenge
4198 get-libvirt-requested-credential-challenge index
4199 Get the challenge (provided by libvirt) for the "index"'th requested
4201 credential. If libvirt did not provide a challenge, this returns the
4202 empty string "".
4203 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4205 example code.
4206 get-libvirt-requested-credential-defresult
4208 get-libvirt-requested-credential-defresult index
4209 Get the default result (provided by libvirt) for the "index"'th
4211 requested credential. If libvirt did not provide a default result,
4212 this returns the empty string "".
4213 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4215 example code.
4216 get-libvirt-requested-credential-prompt
4218 get-libvirt-requested-credential-prompt index
4219 Get the prompt (provided by libvirt) for the "index"'th requested
4221 credential. If libvirt did not provide a prompt, this returns the
4222 empty string "".
4223 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4225 example code.
4226 get-libvirt-requested-credentials
4228 get-libvirt-requested-credentials
4229 This should only be called during the event callback for events of type
4231 "GUESTFS_EVENT_LIBVIRT_AUTH".
4232 Return the list of credentials requested by libvirt. Possible values
4234 are a subset of the strings provided when you called "set-libvirt-
4235 supported-credentials".
4236 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4238 example code.
4239 get-memsize
4241 get-memsize
4242 This gets the memory size in megabytes allocated to the hypervisor.
4244 If "set-memsize" was not called on this handle, and if
4246 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4247 default value for memsize.
4248 For more information on the architecture of libguestfs, see guestfs(3).
4250 get-network
4252 get-network
4253 This returns the enable network flag.
4255 get-path
4257 get-path
4258 Return the current search path.
4260 This is always non-NULL. If it wasn't set already, then this will
4262 return the default path.
4263 get-pgroup
4265 get-pgroup
4266 This returns the process group flag.
4268 get-pid
4270 pid
4271 get-pid
4272 Return the process ID of the hypervisor. If there is no hypervisor
4274 running, then this will return an error.
4275 This is an internal call used for debugging and testing.
4277 get-program
4279 get-program
4280 Get the program name. See "set-program".
4282 get-qemu
4284 get-qemu
4285 Return the current hypervisor binary (usually qemu).
4287 This is always non-NULL. If it wasn't set already, then this will
4289 return the default qemu binary name.
4290 This function is deprecated. In new code, use the "get-hv" call
4292 instead.
4293 Deprecated functions will not be removed from the API, but the fact
4295 that they are deprecated indicates that there are problems with correct
4296 use of these functions.
4297 get-recovery-proc
4299 get-recovery-proc
4300 Return the recovery process enabled flag.
4302 get-selinux
4304 get-selinux
4305 This returns the current setting of the selinux flag which is passed to
4307 the appliance at boot time. See "set-selinux".
4308 For more information on the architecture of libguestfs, see guestfs(3).
4310 This function is deprecated. In new code, use the "selinux-relabel"
4312 call instead.
4313 Deprecated functions will not be removed from the API, but the fact
4315 that they are deprecated indicates that there are problems with correct
4316 use of these functions.
4317 get-smp
4319 get-smp
4320 This returns the number of virtual CPUs assigned to the appliance.
4322 get-sockdir
4324 get-sockdir
4325 Get the directory used by the handle to store temporary socket files.
4327 This is different from "tmpdir", as we need shorter paths for sockets
4329 (due to the limited buffers of filenames for UNIX sockets), and
4330 "tmpdir" may be too long for them.
4331 The environment variable "XDG_RUNTIME_DIR" controls the default value:
4333 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
4334 the default.
4335 get-tmpdir
4337 get-tmpdir
4338 Get the directory used by the handle to store temporary files.
4340 get-trace
4342 get-trace
4343 Return the command trace flag.
4345 get-umask
4347 get-umask
4348 Return the current umask. By default the umask is 022 unless it has
4350 been set by calling "umask".
4351 get-verbose
4353 get-verbose
4354 This returns the verbose messages flag.
4356 getcon
4358 getcon
4359 This gets the SELinux security context of the daemon.
4361 See the documentation about SELINUX in guestfs(3), and "setcon"
4363 This function is deprecated. In new code, use the "selinux-relabel"
4365 call instead.
4366 Deprecated functions will not be removed from the API, but the fact
4368 that they are deprecated indicates that there are problems with correct
4369 use of these functions.
4370 This command depends on the feature "selinux". See also "feature-
4372 available".
4373 getxattr
4375 getxattr path name
4376 Get a single extended attribute from file "path" named "name". This
4378 call follows symlinks. If you want to lookup an extended attribute for
4379 the symlink itself, use "lgetxattr".
4380 Normally it is better to get all extended attributes from a file in one
4382 go by calling "getxattrs". However some Linux filesystem
4383 implementations are buggy and do not provide a way to list out
4384 attributes. For these filesystems (notably ntfs-3g) you have to know
4385 the names of the extended attributes you want in advance and call this
4386 function.
4387 Extended attribute values are blobs of binary data. If there is no
4389 extended attribute named "name", this returns an error.
4390 See also: "getxattrs", "lgetxattr", attr(5).
4392 This command depends on the feature "linuxxattrs". See also "feature-
4394 available".
4395 getxattrs
4397 getxattrs path
4398 This call lists the extended attributes of the file or directory
4400 "path".
4401 At the system call level, this is a combination of the listxattr(2) and
4403 getxattr(2) calls.
4404 See also: "lgetxattrs", attr(5).
4406 This command depends on the feature "linuxxattrs". See also "feature-
4408 available".
4409 glob-expand
4411 glob-expand-opts
4412 glob-expand pattern [directoryslash:true|false]
4413 This command searches for all the pathnames matching "pattern"
4415 according to the wildcard expansion rules used by the shell.
4416 If no paths match, then this returns an empty list (note: not an
4418 error).
4419 It is just a wrapper around the C glob(3) function with flags
4421 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
4422 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
4424 and it defaults to true. It can be explicitly set as off to return no
4425 trailing slashes in filenames of directories.
4426 Notice that there is no equivalent command for expanding a device name
4428 (eg. /dev/sd*). Use "list-devices", "list-partitions" etc functions
4429 instead.
4430 This command has one or more optional arguments. See "OPTIONAL
4432 ARGUMENTS".
4433 grep
4435 grep-opts
4436 grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
4437 This calls the external "grep" program and returns the matching lines.
4439 The optional flags are:
4441 "extended"
4443 Use extended regular expressions. This is the same as using the -E
4444 flag.
4445 "fixed"
4447 Match fixed (don't use regular expressions). This is the same as
4448 using the -F flag.
4449 "insensitive"
4451 Match case-insensitive. This is the same as using the -i flag.
4452 "compressed"
4454 Use "zgrep" instead of "grep". This allows the input to be
4455 compress- or gzip-compressed.
4456 This command has one or more optional arguments. See "OPTIONAL
4458 ARGUMENTS".
4459 Because of the message protocol, there is a transfer limit of somewhere
4461 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4462 grepi
4464 grepi regex path
4465 This calls the external "grep -i" program and returns the matching
4467 lines.
4468 Because of the message protocol, there is a transfer limit of somewhere
4470 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4471 This function is deprecated. In new code, use the "grep" call instead.
4473 Deprecated functions will not be removed from the API, but the fact
4475 that they are deprecated indicates that there are problems with correct
4476 use of these functions.
4477 grub-install
4479 grub-install root device
4480 This command installs GRUB 1 (the Grand Unified Bootloader) on
4482 "device", with the root directory being "root".
4483 Notes:
4485 · There is currently no way in the API to install grub2, which is
4487 used by most modern Linux guests. It is possible to run the grub2
4488 command from the guest, although see the caveats in "RUNNING
4489 COMMANDS" in guestfs(3).
4490 · This uses "grub-install" from the host. Unfortunately grub is not
4492 always compatible with itself, so this only works in rather narrow
4493 circumstances. Careful testing with each guest version is
4494 advisable.
4495 · If grub-install reports the error "No suitable drive was found in
4497 the generated device map." it may be that you need to create a
4498 /boot/grub/device.map file first that contains the mapping between
4499 grub device names and Linux device names. It is usually sufficient
4500 to create a file containing:
4501 (hd0) /dev/vda
4503 replacing /dev/vda with the name of the installation device.
4505 This command depends on the feature "grub". See also "feature-
4507 available".
4508 head
4510 head path
4511 This command returns up to the first 10 lines of a file as a list of
4513 strings.
4514 Because of the message protocol, there is a transfer limit of somewhere
4516 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4517 head-n
4519 head-n nrlines path
4520 If the parameter "nrlines" is a positive number, this returns the first
4522 "nrlines" lines of the file "path".
4523 If the parameter "nrlines" is a negative number, this returns lines
4525 from the file "path", excluding the last "nrlines" lines.
4526 If the parameter "nrlines" is zero, this returns an empty list.
4528 Because of the message protocol, there is a transfer limit of somewhere
4530 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4531 hexdump
4533 hexdump path
4534 This runs "hexdump -C" on the given "path". The result is the human-
4536 readable, canonical hex dump of the file.
4537 Because of the message protocol, there is a transfer limit of somewhere
4539 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4540 hivex-close
4542 hivex-close
4543 Close the current hivex handle.
4545 This is a wrapper around the hivex(3) call of the same name.
4547 This command depends on the feature "hivex". See also "feature-
4549 available".
4550 hivex-commit
4552 hivex-commit filename
4553 Commit (write) changes to the hive.
4555 If the optional filename parameter is null, then the changes are
4557 written back to the same hive that was opened. If this is not null
4558 then they are written to the alternate filename given and the original
4559 hive is left untouched.
4560 This is a wrapper around the hivex(3) call of the same name.
4562 This command depends on the feature "hivex". See also "feature-
4564 available".
4565 hivex-node-add-child
4567 hivex-node-add-child parent name
4568 Add a child node to "parent" named "name".
4570 This is a wrapper around the hivex(3) call of the same name.
4572 This command depends on the feature "hivex". See also "feature-
4574 available".
4575 hivex-node-children
4577 hivex-node-children nodeh
4578 Return the list of nodes which are subkeys of "nodeh".
4580 This is a wrapper around the hivex(3) call of the same name.
4582 This command depends on the feature "hivex". See also "feature-
4584 available".
4585 hivex-node-delete-child
4587 hivex-node-delete-child nodeh
4588 Delete "nodeh", recursively if necessary.
4590 This is a wrapper around the hivex(3) call of the same name.
4592 This command depends on the feature "hivex". See also "feature-
4594 available".
4595 hivex-node-get-child
4597 hivex-node-get-child nodeh name
4598 Return the child of "nodeh" with the name "name", if it exists. This
4600 can return 0 meaning the name was not found.
4601 This is a wrapper around the hivex(3) call of the same name.
4603 This command depends on the feature "hivex". See also "feature-
4605 available".
4606 hivex-node-get-value
4608 hivex-node-get-value nodeh key
4609 Return the value attached to "nodeh" which has the name "key", if it
4611 exists. This can return 0 meaning the key was not found.
4612 This is a wrapper around the hivex(3) call of the same name.
4614 This command depends on the feature "hivex". See also "feature-
4616 available".
4617 hivex-node-name
4619 hivex-node-name nodeh
4620 Return the name of "nodeh".
4622 This is a wrapper around the hivex(3) call of the same name.
4624 This command depends on the feature "hivex". See also "feature-
4626 available".
4627 hivex-node-parent
4629 hivex-node-parent nodeh
4630 Return the parent node of "nodeh".
4632 This is a wrapper around the hivex(3) call of the same name.
4634 This command depends on the feature "hivex". See also "feature-
4636 available".
4637 hivex-node-set-value
4639 hivex-node-set-value nodeh key t val
4640 Set or replace a single value under the node "nodeh". The "key" is the
4642 name, "t" is the type, and "val" is the data.
4643 This is a wrapper around the hivex(3) call of the same name.
4645 This command depends on the feature "hivex". See also "feature-
4647 available".
4648 hivex-node-values
4650 hivex-node-values nodeh
4651 Return the array of (key, datatype, data) tuples attached to "nodeh".
4653 This is a wrapper around the hivex(3) call of the same name.
4655 This command depends on the feature "hivex". See also "feature-
4657 available".
4658 hivex-open
4660 hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]
4661 Open the Windows Registry hive file named filename. If there was any
4663 previous hivex handle associated with this guestfs session, then it is
4664 closed.
4665 This is a wrapper around the hivex(3) call of the same name.
4667 This command has one or more optional arguments. See "OPTIONAL
4669 ARGUMENTS".
4670 This command depends on the feature "hivex". See also "feature-
4672 available".
4673 hivex-root
4675 hivex-root
4676 Return the root node of the hive.
4678 This is a wrapper around the hivex(3) call of the same name.
4680 This command depends on the feature "hivex". See also "feature-
4682 available".
4683 hivex-value-key
4685 hivex-value-key valueh
4686 Return the key (name) field of a (key, datatype, data) tuple.
4688 This is a wrapper around the hivex(3) call of the same name.
4690 This command depends on the feature "hivex". See also "feature-
4692 available".
4693 hivex-value-string
4695 hivex-value-string valueh
4696 This calls "hivex-value-value" (which returns the data field from a
4698 hivex value tuple). It then assumes that the field is a UTF-16LE
4699 string and converts the result to UTF-8 (or if this is not possible, it
4700 returns an error).
4701 This is useful for reading strings out of the Windows registry.
4703 However it is not foolproof because the registry is not strongly-typed
4704 and fields can contain arbitrary or unexpected data.
4705 This command depends on the feature "hivex". See also "feature-
4707 available".
4708 hivex-value-type
4710 hivex-value-type valueh
4711 Return the data type field from a (key, datatype, data) tuple.
4713 This is a wrapper around the hivex(3) call of the same name.
4715 This command depends on the feature "hivex". See also "feature-
4717 available".
4718 hivex-value-utf8
4720 hivex-value-utf8 valueh
4721 This calls "hivex-value-value" (which returns the data field from a
4723 hivex value tuple). It then assumes that the field is a UTF-16LE
4724 string and converts the result to UTF-8 (or if this is not possible, it
4725 returns an error).
4726 This is useful for reading strings out of the Windows registry.
4728 However it is not foolproof because the registry is not strongly-typed
4729 and fields can contain arbitrary or unexpected data.
4730 This function is deprecated. In new code, use the "hivex-value-string"
4732 call instead.
4733 Deprecated functions will not be removed from the API, but the fact
4735 that they are deprecated indicates that there are problems with correct
4736 use of these functions.
4737 This command depends on the feature "hivex". See also "feature-
4739 available".
4740 hivex-value-value
4742 hivex-value-value valueh
4743 Return the data field of a (key, datatype, data) tuple.
4745 This is a wrapper around the hivex(3) call of the same name.
4747 See also: "hivex-value-utf8".
4749 This command depends on the feature "hivex". See also "feature-
4751 available".
4752 initrd-cat
4754 initrd-cat initrdpath filename
4755 This command unpacks the file filename from the initrd file called
4757 initrdpath. The filename must be given without the initial /
4758 character.
4759 For example, in guestfish you could use the following command to
4761 examine the boot script (usually called /init) contained in a Linux
4762 initrd or initramfs image:
4763 initrd-cat /boot/initrd-<version>.img init
4765 See also "initrd-list".
4767 Because of the message protocol, there is a transfer limit of somewhere
4769 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
4770 initrd-list
4772 initrd-list path
4773 This command lists out files contained in an initrd.
4775 The files are listed without any initial / character. The files are
4777 listed in the order they appear (not necessarily alphabetical).
4778 Directory names are listed as separate items.
4779 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
4781 as initrd. We only support the newer initramfs format (compressed cpio
4782 files).
4783 inotify-add-watch
4785 inotify-add-watch path mask
4786 Watch "path" for the events listed in "mask".
4788 Note that if "path" is a directory then events within that directory
4790 are watched, but this does not happen recursively (in subdirectories).
4791 Note for non-C or non-Linux callers: the inotify events are defined by
4793 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
4794 This command depends on the feature "inotify". See also "feature-
4796 available".
4797 inotify-close
4799 inotify-close
4800 This closes the inotify handle which was previously opened by
4802 inotify_init. It removes all watches, throws away any pending events,
4803 and deallocates all resources.
4804 This command depends on the feature "inotify". See also "feature-
4806 available".
4807 inotify-files
4809 inotify-files
4810 This function is a helpful wrapper around "inotify-read" which just
4812 returns a list of pathnames of objects that were touched. The returned
4813 pathnames are sorted and deduplicated.
4814 This command depends on the feature "inotify". See also "feature-
4816 available".
4817 inotify-init
4819 inotify-init maxevents
4820 This command creates a new inotify handle. The inotify subsystem can
4822 be used to notify events which happen to objects in the guest
4823 filesystem.
4824 "maxevents" is the maximum number of events which will be queued up
4826 between calls to "inotify-read" or "inotify-files". If this is passed
4827 as 0, then the kernel (or previously set) default is used. For Linux
4828 2.6.29 the default was 16384 events. Beyond this limit, the kernel
4829 throws away events, but records the fact that it threw them away by
4830 setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
4831 "inotify-read").
4832 Before any events are generated, you have to add some watches to the
4834 internal watch list. See: "inotify-add-watch" and "inotify-rm-watch".
4835 Queued up events should be read periodically by calling "inotify-read"
4837 (or "inotify-files" which is just a helpful wrapper around "inotify-
4838 read"). If you don't read the events out often enough then you risk
4839 the internal queue overflowing.
4840 The handle should be closed after use by calling "inotify-close". This
4842 also removes any watches automatically.
4843 See also inotify(7) for an overview of the inotify interface as exposed
4845 by the Linux kernel, which is roughly what we expose via libguestfs.
4846 Note that there is one global inotify handle per libguestfs instance.
4847 This command depends on the feature "inotify". See also "feature-
4849 available".
4850 inotify-read
4852 inotify-read
4853 Return the complete queue of events that have happened since the
4855 previous read call.
4856 If no events have happened, this returns an empty list.
4858 Note: In order to make sure that all events have been read, you must
4860 call this function repeatedly until it returns an empty list. The
4861 reason is that the call will read events up to the maximum appliance-
4862 to-host message size and leave remaining events in the queue.
4863 This command depends on the feature "inotify". See also "feature-
4865 available".
4866 inotify-rm-watch
4868 inotify-rm-watch wd
4869 Remove a previously defined inotify watch. See "inotify-add-watch".
4871 This command depends on the feature "inotify". See also "feature-
4873 available".
4874 inspect-get-arch
4876 inspect-get-arch root
4877 This returns the architecture of the inspected operating system. The
4879 possible return values are listed under "file-architecture".
4880 If the architecture could not be determined, then the string "unknown"
4882 is returned.
4883 Please read "INSPECTION" in guestfs(3) for more details.
4885 inspect-get-distro
4887 inspect-get-distro root
4888 This returns the distro (distribution) of the inspected operating
4890 system.
4891 Currently defined distros are:
4893 "alpinelinux"
4895 Alpine Linux.
4896 "altlinux"
4898 ALT Linux.
4899 "archlinux"
4901 Arch Linux.
4902 "buildroot"
4904 Buildroot-derived distro, but not one we specifically recognize.
4905 "centos"
4907 CentOS.
4908 "cirros"
4910 Cirros.
4911 "coreos"
4913 CoreOS.
4914 "debian"
4916 Debian.
4917 "fedora"
4919 Fedora.
4920 "freebsd"
4922 FreeBSD.
4923 "freedos"
4925 FreeDOS.
4926 "frugalware"
4928 Frugalware.
4929 "gentoo"
4931 Gentoo.
4932 "kalilinux"
4934 Kali Linux.
4935 "linuxmint"
4937 Linux Mint.
4938 "mageia"
4940 Mageia.
4941 "mandriva"
4943 Mandriva.
4944 "meego"
4946 MeeGo.
4947 "msdos"
4949 Microsoft DOS.
4950 "neokylin"
4952 NeoKylin.
4953 "netbsd"
4955 NetBSD.
4956 "openbsd"
4958 OpenBSD.
4959 "opensuse"
4961 OpenSUSE.
4962 "oraclelinux"
4964 Oracle Linux.
4965 "pardus"
4967 Pardus.
4968 "pldlinux"
4970 PLD Linux.
4971 "redhat-based"
4973 Some Red Hat-derived distro.
4974 "rhel"
4976 Red Hat Enterprise Linux.
4977 "scientificlinux"
4979 Scientific Linux.
4980 "slackware"
4982 Slackware.
4983 "sles"
4985 SuSE Linux Enterprise Server or Desktop.
4986 "suse-based"
4988 Some openSuSE-derived distro.
4989 "ttylinux"
4991 ttylinux.
4992 "ubuntu"
4994 Ubuntu.
4995 "unknown"
4997 The distro could not be determined.
4998 "voidlinux"
5000 Void Linux.
5001 "windows"
5003 Windows does not have distributions. This string is returned if
5004 the OS type is Windows.
5005 Future versions of libguestfs may return other strings here. The
5007 caller should be prepared to handle any string.
5008 Please read "INSPECTION" in guestfs(3) for more details.
5010 inspect-get-drive-mappings
5012 inspect-get-drive-mappings root
5013 This call is useful for Windows which uses a primitive system of
5015 assigning drive letters (like C:\) to partitions. This inspection API
5016 examines the Windows Registry to find out how disks/partitions are
5017 mapped to drive letters, and returns a hash table as in the example
5018 below:
5019 C => /dev/vda2
5021 E => /dev/vdb1
5022 F => /dev/vdc1
5023 Note that keys are drive letters. For Windows, the key is case
5025 insensitive and just contains the drive letter, without the customary
5026 colon separator character.
5027 In future we may support other operating systems that also used drive
5029 letters, but the keys for those might not be case insensitive and might
5030 be longer than 1 character. For example in OS-9, hard drives were
5031 named "h0", "h1" etc.
5032 For Windows guests, currently only hard drive mappings are returned.
5034 Removable disks (eg. DVD-ROMs) are ignored.
5035 For guests that do not use drive mappings, or if the drive mappings
5037 could not be determined, this returns an empty hash table.
5038 Please read "INSPECTION" in guestfs(3) for more details. See also
5040 "inspect-get-mountpoints", "inspect-get-filesystems".
5041 inspect-get-filesystems
5043 inspect-get-filesystems root
5044 This returns a list of all the filesystems that we think are associated
5046 with this operating system. This includes the root filesystem, other
5047 ordinary filesystems, and non-mounted devices like swap partitions.
5048 In the case of a multi-boot virtual machine, it is possible for a
5050 filesystem to be shared between operating systems.
5051 Please read "INSPECTION" in guestfs(3) for more details. See also
5053 "inspect-get-mountpoints".
5054 inspect-get-format
5056 inspect-get-format root
5057 Before libguestfs 1.38, there was some unreliable support for detecting
5059 installer CDs. This API would return:
5060 "installed"
5062 This is an installed operating system.
5063 "installer"
5065 The disk image being inspected is not an installed operating
5066 system, but a bootable install disk, live CD, or similar.
5067 "unknown"
5069 The format of this disk image is not known.
5070 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
5072 directly to detect installer CDs.
5073 Please read "INSPECTION" in guestfs(3) for more details.
5075 This function is deprecated. There is no replacement. Consult the API
5077 documentation in guestfs(3) for further information.
5078 Deprecated functions will not be removed from the API, but the fact
5080 that they are deprecated indicates that there are problems with correct
5081 use of these functions.
5082 inspect-get-hostname
5084 inspect-get-hostname root
5085 This function returns the hostname of the operating system as found by
5087 inspection of the guest’s configuration files.
5088 If the hostname could not be determined, then the string "unknown" is
5090 returned.
5091 Please read "INSPECTION" in guestfs(3) for more details.
5093 inspect-get-icon
5095 inspect-get-icon root [favicon:true|false] [highquality:true|false]
5096 This function returns an icon corresponding to the inspected operating
5098 system. The icon is returned as a buffer containing a PNG image (re-
5099 encoded to PNG if necessary).
5100 If it was not possible to get an icon this function returns a zero-
5102 length (non-NULL) buffer. Callers must check for this case.
5103 Libguestfs will start by looking for a file called /etc/favicon.png or
5105 C:\etc\favicon.png and if it has the correct format, the contents of
5106 this file will be returned. You can disable favicons by passing the
5107 optional "favicon" boolean as false (default is true).
5108 If finding the favicon fails, then we look in other places in the guest
5110 for a suitable icon.
5111 If the optional "highquality" boolean is true then only high quality
5113 icons are returned, which means only icons of high resolution with an
5114 alpha channel. The default (false) is to return any icon we can, even
5115 if it is of substandard quality.
5116 Notes:
5118 · Unlike most other inspection API calls, the guest’s disks must be
5120 mounted up before you call this, since it needs to read information
5121 from the guest filesystem during the call.
5122 · Security: The icon data comes from the untrusted guest, and should
5124 be treated with caution. PNG files have been known to contain
5125 exploits. Ensure that libpng (or other relevant libraries) are
5126 fully up to date before trying to process or display the icon.
5127 · The PNG image returned can be any size. It might not be square.
5129 Libguestfs tries to return the largest, highest quality icon
5130 available. The application must scale the icon to the required
5131 size.
5132 · Extracting icons from Windows guests requires the external
5134 "wrestool" program from the "icoutils" package, and several
5135 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
5136 package. These must be installed separately.
5137 · Operating system icons are usually trademarks. Seek legal advice
5139 before using trademarks in applications.
5140 This command has one or more optional arguments. See "OPTIONAL
5142 ARGUMENTS".
5143 inspect-get-major-version
5145 inspect-get-major-version root
5146 This returns the major version number of the inspected operating
5148 system.
5149 Windows uses a consistent versioning scheme which is not reflected in
5151 the popular public names used by the operating system. Notably the
5152 operating system known as "Windows 7" is really version 6.1 (ie. major
5153 = 6, minor = 1). You can find out the real versions corresponding to
5154 releases of Windows by consulting Wikipedia or MSDN.
5155 If the version could not be determined, then 0 is returned.
5157 Please read "INSPECTION" in guestfs(3) for more details.
5159 inspect-get-minor-version
5161 inspect-get-minor-version root
5162 This returns the minor version number of the inspected operating
5164 system.
5165 If the version could not be determined, then 0 is returned.
5167 Please read "INSPECTION" in guestfs(3) for more details. See also
5169 "inspect-get-major-version".
5170 inspect-get-mountpoints
5172 inspect-get-mountpoints root
5173 This returns a hash of where we think the filesystems associated with
5175 this operating system should be mounted. Callers should note that this
5176 is at best an educated guess made by reading configuration files such
5177 as /etc/fstab. In particular note that this may return filesystems
5178 which are non-existent or not mountable and callers should be prepared
5179 to handle or ignore failures if they try to mount them.
5180 Each element in the returned hashtable has a key which is the path of
5182 the mountpoint (eg. /boot) and a value which is the filesystem that
5183 would be mounted there (eg. /dev/sda1).
5184 Non-mounted devices such as swap devices are not returned in this list.
5186 For operating systems like Windows which still use drive letters, this
5188 call will only return an entry for the first drive "mounted on" /. For
5189 information about the mapping of drive letters to partitions, see
5190 "inspect-get-drive-mappings".
5191 Please read "INSPECTION" in guestfs(3) for more details. See also
5193 "inspect-get-filesystems".
5194 inspect-get-osinfo
5196 inspect-get-osinfo root
5197 This function returns a possible short ID for libosinfo corresponding
5199 to the guest.
5200 Note: The returned ID is only a guess by libguestfs, and nothing
5202 ensures that it actually exists in osinfo-db.
5203 If no ID could not be determined, then the string "unknown" is
5205 returned.
5206 inspect-get-package-format
5208 inspect-get-package-format root
5209 This function and "inspect-get-package-management" return the package
5211 format and package management tool used by the inspected operating
5212 system. For example for Fedora these functions would return "rpm"
5213 (package format), and "yum" or "dnf" (package management).
5214 This returns the string "unknown" if we could not determine the package
5216 format or if the operating system does not have a real packaging system
5217 (eg. Windows).
5218 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5220 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
5221 other strings.
5222 Please read "INSPECTION" in guestfs(3) for more details.
5224 inspect-get-package-management
5226 inspect-get-package-management root
5227 "inspect-get-package-format" and this function return the package
5229 format and package management tool used by the inspected operating
5230 system. For example for Fedora these functions would return "rpm"
5231 (package format), and "yum" or "dnf" (package management).
5232 This returns the string "unknown" if we could not determine the package
5234 management tool or if the operating system does not have a real
5235 packaging system (eg. Windows).
5236 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
5238 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
5239 "apk", "xbps". Future versions of libguestfs may return other strings.
5240 Please read "INSPECTION" in guestfs(3) for more details.
5242 inspect-get-product-name
5244 inspect-get-product-name root
5245 This returns the product name of the inspected operating system. The
5247 product name is generally some freeform string which can be displayed
5248 to the user, but should not be parsed by programs.
5249 If the product name could not be determined, then the string "unknown"
5251 is returned.
5252 Please read "INSPECTION" in guestfs(3) for more details.
5254 inspect-get-product-variant
5256 inspect-get-product-variant root
5257 This returns the product variant of the inspected operating system.
5259 For Windows guests, this returns the contents of the Registry key
5261 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
5262 which is usually a string such as "Client" or "Server" (other values
5263 are possible). This can be used to distinguish consumer and enterprise
5264 versions of Windows that have the same version number (for example,
5265 Windows 7 and Windows 2008 Server are both version 6.1, but the former
5266 is "Client" and the latter is "Server").
5267 For enterprise Linux guests, in future we intend this to return the
5269 product variant such as "Desktop", "Server" and so on. But this is not
5270 implemented at present.
5271 If the product variant could not be determined, then the string
5273 "unknown" is returned.
5274 Please read "INSPECTION" in guestfs(3) for more details. See also
5276 "inspect-get-product-name", "inspect-get-major-version".
5277 inspect-get-roots
5279 inspect-get-roots
5280 This function is a convenient way to get the list of root devices, as
5282 returned from a previous call to "inspect-os", but without redoing the
5283 whole inspection process.
5284 This returns an empty list if either no root devices were found or the
5286 caller has not called "inspect-os".
5287 Please read "INSPECTION" in guestfs(3) for more details.
5289 inspect-get-type
5291 inspect-get-type root
5292 This returns the type of the inspected operating system. Currently
5294 defined types are:
5295 "linux"
5297 Any Linux-based operating system.
5298 "windows"
5300 Any Microsoft Windows operating system.
5301 "freebsd"
5303 FreeBSD.
5304 "netbsd"
5306 NetBSD.
5307 "openbsd"
5309 OpenBSD.
5310 "hurd"
5312 GNU/Hurd.
5313 "dos"
5315 MS-DOS, FreeDOS and others.
5316 "minix"
5318 MINIX.
5319 "unknown"
5321 The operating system type could not be determined.
5322 Future versions of libguestfs may return other strings here. The
5324 caller should be prepared to handle any string.
5325 Please read "INSPECTION" in guestfs(3) for more details.
5327 inspect-get-windows-current-control-set
5329 inspect-get-windows-current-control-set root
5330 This returns the Windows CurrentControlSet of the inspected guest. The
5332 CurrentControlSet is a registry key name such as "ControlSet001".
5333 This call assumes that the guest is Windows and that the Registry could
5335 be examined by inspection. If this is not the case then an error is
5336 returned.
5337 Please read "INSPECTION" in guestfs(3) for more details.
5339 inspect-get-windows-software-hive
5341 inspect-get-windows-software-hive root
5342 This returns the path to the hive (binary Windows Registry file)
5344 corresponding to HKLM\SOFTWARE.
5345 This call assumes that the guest is Windows and that the guest has a
5347 software hive file with the right name. If this is not the case then
5348 an error is returned. This call does not check that the hive is a
5349 valid Windows Registry hive.
5350 You can use "hivex-open" to read or write to the hive.
5352 Please read "INSPECTION" in guestfs(3) for more details.
5354 inspect-get-windows-system-hive
5356 inspect-get-windows-system-hive root
5357 This returns the path to the hive (binary Windows Registry file)
5359 corresponding to HKLM\SYSTEM.
5360 This call assumes that the guest is Windows and that the guest has a
5362 system hive file with the right name. If this is not the case then an
5363 error is returned. This call does not check that the hive is a valid
5364 Windows Registry hive.
5365 You can use "hivex-open" to read or write to the hive.
5367 Please read "INSPECTION" in guestfs(3) for more details.
5369 inspect-get-windows-systemroot
5371 inspect-get-windows-systemroot root
5372 This returns the Windows systemroot of the inspected guest. The
5374 systemroot is a directory path such as /WINDOWS.
5375 This call assumes that the guest is Windows and that the systemroot
5377 could be determined by inspection. If this is not the case then an
5378 error is returned.
5379 Please read "INSPECTION" in guestfs(3) for more details.
5381 inspect-is-live
5383 inspect-is-live root
5384 This is deprecated and always returns "false".
5386 Please read "INSPECTION" in guestfs(3) for more details.
5388 This function is deprecated. There is no replacement. Consult the API
5390 documentation in guestfs(3) for further information.
5391 Deprecated functions will not be removed from the API, but the fact
5393 that they are deprecated indicates that there are problems with correct
5394 use of these functions.
5395 inspect-is-multipart
5397 inspect-is-multipart root
5398 This is deprecated and always returns "false".
5400 Please read "INSPECTION" in guestfs(3) for more details.
5402 This function is deprecated. There is no replacement. Consult the API
5404 documentation in guestfs(3) for further information.
5405 Deprecated functions will not be removed from the API, but the fact
5407 that they are deprecated indicates that there are problems with correct
5408 use of these functions.
5409 inspect-is-netinst
5411 inspect-is-netinst root
5412 This is deprecated and always returns "false".
5414 Please read "INSPECTION" in guestfs(3) for more details.
5416 This function is deprecated. There is no replacement. Consult the API
5418 documentation in guestfs(3) for further information.
5419 Deprecated functions will not be removed from the API, but the fact
5421 that they are deprecated indicates that there are problems with correct
5422 use of these functions.
5423 inspect-list-applications
5425 inspect-list-applications root
5426 Return the list of applications installed in the operating system.
5428 Note: This call works differently from other parts of the inspection
5430 API. You have to call "inspect-os", then "inspect-get-mountpoints",
5431 then mount up the disks, before calling this. Listing applications is
5432 a significantly more difficult operation which requires access to the
5433 full filesystem. Also note that unlike the other "inspect-get-*" calls
5434 which are just returning data cached in the libguestfs handle, this
5435 call actually reads parts of the mounted filesystems during the call.
5436 This returns an empty list if the inspection code was not able to
5438 determine the list of applications.
5439 The application structure contains the following fields:
5441 "app_name"
5443 The name of the application. For Red Hat-derived and Debian-
5444 derived Linux guests, this is the package name.
5445 "app_display_name"
5447 The display name of the application, sometimes localized to the
5448 install language of the guest operating system.
5449 If unavailable this is returned as an empty string "". Callers
5451 needing to display something can use "app_name" instead.
5452 "app_epoch"
5454 For package managers which use epochs, this contains the epoch of
5455 the package (an integer). If unavailable, this is returned as 0.
5456 "app_version"
5458 The version string of the application or package. If unavailable
5459 this is returned as an empty string "".
5460 "app_release"
5462 The release string of the application or package, for package
5463 managers that use this. If unavailable this is returned as an
5464 empty string "".
5465 "app_install_path"
5467 The installation path of the application (on operating systems such
5468 as Windows which use installation paths). This path is in the
5469 format used by the guest operating system, it is not a libguestfs
5470 path.
5471 If unavailable this is returned as an empty string "".
5473 "app_trans_path"
5475 The install path translated into a libguestfs path. If unavailable
5476 this is returned as an empty string "".
5477 "app_publisher"
5479 The name of the publisher of the application, for package managers
5480 that use this. If unavailable this is returned as an empty string
5481 "".
5482 "app_url"
5484 The URL (eg. upstream URL) of the application. If unavailable this
5485 is returned as an empty string "".
5486 "app_source_package"
5488 For packaging systems which support this, the name of the source
5489 package. If unavailable this is returned as an empty string "".
5490 "app_summary"
5492 A short (usually one line) description of the application or
5493 package. If unavailable this is returned as an empty string "".
5494 "app_description"
5496 A longer description of the application or package. If unavailable
5497 this is returned as an empty string "".
5498 Please read "INSPECTION" in guestfs(3) for more details.
5500 This function is deprecated. In new code, use the
5502 "inspect-list-applications2" call instead.
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-applications2
5509 inspect-list-applications2 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 "app2_name"
5527 The name of the application. For Red Hat-derived and Debian-
5528 derived Linux guests, this is the package name.
5529 "app2_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 "app2_name" instead.
5536 "app2_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 "app2_version"
5542 The version string of the application or package. If unavailable
5543 this is returned as an empty string "".
5544 "app2_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 "app2_arch"
5551 The architecture string of the application or package, for package
5552 managers that use this. If unavailable this is returned as an
5553 empty string "".
5554 "app2_install_path"
5556 The installation path of the application (on operating systems such
5557 as Windows which use installation paths). This path is in the
5558 format used by the guest operating system, it is not a libguestfs
5559 path.
5560 If unavailable this is returned as an empty string "".
5562 "app2_trans_path"
5564 The install path translated into a libguestfs path. If unavailable
5565 this is returned as an empty string "".
5566 "app2_publisher"
5568 The name of the publisher of the application, for package managers
5569 that use this. If unavailable this is returned as an empty string
5570 "".
5571 "app2_url"
5573 The URL (eg. upstream URL) of the application. If unavailable this
5574 is returned as an empty string "".
5575 "app2_source_package"
5577 For packaging systems which support this, the name of the source
5578 package. If unavailable this is returned as an empty string "".
5579 "app2_summary"
5581 A short (usually one line) description of the application or
5582 package. If unavailable this is returned as an empty string "".
5583 "app2_description"
5585 A longer description of the application or package. If unavailable
5586 this is returned as an empty string "".
5587 Please read "INSPECTION" in guestfs(3) for more details.
5589 inspect-os
5591 inspect-os
5592 This function uses other libguestfs functions and certain heuristics to
5594 inspect the disk(s) (usually disks belonging to a virtual machine),
5595 looking for operating systems.
5596 The list returned is empty if no operating systems were found.
5598 If one operating system was found, then this returns a list with a
5600 single element, which is the name of the root filesystem of this
5601 operating system. It is also possible for this function to return a
5602 list containing more than one element, indicating a dual-boot or multi-
5603 boot virtual machine, with each element being the root filesystem of
5604 one of the operating systems.
5605 You can pass the root string(s) returned to other "inspect-get-*"
5607 functions in order to query further information about each operating
5608 system, such as the name and version.
5609 This function uses other libguestfs features such as "mount-ro" and
5611 "umount-all" in order to mount and unmount filesystems and look at the
5612 contents. This should be called with no disks currently mounted. The
5613 function may also use Augeas, so any existing Augeas handle will be
5614 closed.
5615 This function cannot decrypt encrypted disks. The caller must do that
5617 first (supplying the necessary keys) if the disk is encrypted.
5618 Please read "INSPECTION" in guestfs(3) for more details.
5620 See also "list-filesystems".
5622 is-blockdev
5624 is-blockdev-opts
5625 is-blockdev path [followsymlinks:true|false]
5626 This returns "true" if and only if there is a block device with the
5628 given "path" name.
5629 If the optional flag "followsymlinks" is true, then a symlink (or chain
5631 of symlinks) that ends with a block device also causes the function to
5632 return true.
5633 This call only looks at files within the guest filesystem. Libguestfs
5635 partitions and block devices (eg. /dev/sda) cannot be used as the
5636 "path" parameter of this call.
5637 See also "stat".
5639 This command has one or more optional arguments. See "OPTIONAL
5641 ARGUMENTS".
5642 is-chardev
5644 is-chardev-opts
5645 is-chardev path [followsymlinks:true|false]
5646 This returns "true" if and only if there is a character device with the
5648 given "path" name.
5649 If the optional flag "followsymlinks" is true, then a symlink (or chain
5651 of symlinks) that ends with a chardev also causes the function to
5652 return true.
5653 See also "stat".
5655 This command has one or more optional arguments. See "OPTIONAL
5657 ARGUMENTS".
5658 is-config
5660 is-config
5661 This returns true iff this handle is being configured (in the "CONFIG"
5663 state).
5664 For more information on states, see guestfs(3).
5666 is-dir
5668 is-dir-opts
5669 is-dir path [followsymlinks:true|false]
5670 This returns "true" if and only if there is a directory with the given
5672 "path" name. Note that it returns false for other objects like files.
5673 If the optional flag "followsymlinks" is true, then a symlink (or chain
5675 of symlinks) that ends with a directory also causes the function to
5676 return true.
5677 See also "stat".
5679 This command has one or more optional arguments. See "OPTIONAL
5681 ARGUMENTS".
5682 is-fifo
5684 is-fifo-opts
5685 is-fifo path [followsymlinks:true|false]
5686 This returns "true" if and only if there is a FIFO (named pipe) with
5688 the given "path" name.
5689 If the optional flag "followsymlinks" is true, then a symlink (or chain
5691 of symlinks) that ends with a FIFO also causes the function to return
5692 true.
5693 See also "stat".
5695 This command has one or more optional arguments. See "OPTIONAL
5697 ARGUMENTS".
5698 is-file
5700 is-file-opts
5701 is-file path [followsymlinks:true|false]
5702 This returns "true" if and only if there is a regular file with the
5704 given "path" name. Note that it returns false for other objects like
5705 directories.
5706 If the optional flag "followsymlinks" is true, then a symlink (or chain
5708 of symlinks) that ends with a file also causes the function to return
5709 true.
5710 See also "stat".
5712 This command has one or more optional arguments. See "OPTIONAL
5714 ARGUMENTS".
5715 is-lv
5717 is-lv mountable
5718 This command tests whether "mountable" is a logical volume, and returns
5720 true iff this is the case.
5721 is-socket
5723 is-socket-opts
5724 is-socket path [followsymlinks:true|false]
5725 This returns "true" if and only if there is a Unix domain socket with
5727 the given "path" name.
5728 If the optional flag "followsymlinks" is true, then a symlink (or chain
5730 of symlinks) that ends with a socket also causes the function to return
5731 true.
5732 See also "stat".
5734 This command has one or more optional arguments. See "OPTIONAL
5736 ARGUMENTS".
5737 is-symlink
5739 is-symlink path
5740 This returns "true" if and only if there is a symbolic link with the
5742 given "path" name.
5743 See also "stat".
5745 is-whole-device
5747 is-whole-device device
5748 This returns "true" if and only if "device" refers to a whole block
5750 device. That is, not a partition or a logical device.
5751 is-zero
5753 is-zero path
5754 This returns true iff the file exists and the file is empty or it
5756 contains all zero bytes.
5757 is-zero-device
5759 is-zero-device device
5760 This returns true iff the device exists and contains all zero bytes.
5762 Note that for large devices this can take a long time to run.
5764 isoinfo
5766 isoinfo isofile
5767 This is the same as "isoinfo-device" except that it works for an ISO
5769 file located inside some other mounted filesystem. Note that in the
5770 common case where you have added an ISO file as a libguestfs device,
5771 you would not call this. Instead you would call "isoinfo-device".
5772 isoinfo-device
5774 isoinfo-device device
5775 "device" is an ISO device. This returns a struct of information read
5777 from the primary volume descriptor (the ISO equivalent of the
5778 superblock) of the device.
5779 Usually it is more efficient to use the isoinfo(1) command with the -d
5781 option on the host to analyze ISO files, instead of going through
5782 libguestfs.
5783 For information on the primary volume descriptor fields, see
5785 http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
5786 journal-close
5788 journal-close
5789 Close the journal handle.
5791 This command depends on the feature "journal". See also "feature-
5793 available".
5794 journal-get
5796 journal-get
5797 Read the current journal entry. This returns all the fields in the
5799 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
5800 field name (a string).
5801 The "attrval" is the field value (a binary blob, often but not always a
5803 string). Please note that "attrval" is a byte array, not a
5804 \0-terminated C string.
5805 The length of data may be truncated to the data threshold (see:
5807 "journal-set-data-threshold", "journal-get-data-threshold").
5808 If you set the data threshold to unlimited (0) then this call can read
5810 a journal entry of any size, ie. it is not limited by the libguestfs
5811 protocol.
5812 This command depends on the feature "journal". See also "feature-
5814 available".
5815 journal-get-data-threshold
5817 journal-get-data-threshold
5818 Get the current data threshold for reading journal entries. This is a
5820 hint to the journal that it may truncate data fields to this size when
5821 reading them (note also that it may not truncate them). If this
5822 returns 0, then the threshold is unlimited.
5823 See also "journal-set-data-threshold".
5825 This command depends on the feature "journal". See also "feature-
5827 available".
5828 journal-get-realtime-usec
5830 journal-get-realtime-usec
5831 Get the realtime (wallclock) timestamp of the current journal entry.
5833 This command depends on the feature "journal". See also "feature-
5835 available".
5836 journal-next
5838 journal-next
5839 Move to the next journal entry. You have to call this at least once
5841 after opening the handle before you are able to read data.
5842 The returned boolean tells you if there are any more journal records to
5844 read. "true" means you can read the next record (eg. using "journal-
5845 get"), and "false" means you have reached the end of the journal.
5846 This command depends on the feature "journal". See also "feature-
5848 available".
5849 journal-open
5851 journal-open directory
5852 Open the systemd journal located in directory. Any previously opened
5854 journal handle is closed.
5855 The contents of the journal can be read using "journal-next" and
5857 "journal-get".
5858 After you have finished using the journal, you should close the handle
5860 by calling "journal-close".
5861 This command depends on the feature "journal". See also "feature-
5863 available".
5864 journal-set-data-threshold
5866 journal-set-data-threshold threshold
5867 Set the data threshold for reading journal entries. This is a hint to
5869 the journal that it may truncate data fields to this size when reading
5870 them (note also that it may not truncate them). If you set this to 0,
5871 then the threshold is unlimited.
5872 See also "journal-get-data-threshold".
5874 This command depends on the feature "journal". See also "feature-
5876 available".
5877 journal-skip
5879 journal-skip skip
5880 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
5882 The number of entries actually skipped is returned (note "rskip ≥ 0").
5884 If this is not the same as the absolute value of the skip parameter
5885 ("|skip|") you passed in then it means you have reached the end or the
5886 start of the journal.
5887 This command depends on the feature "journal". See also "feature-
5889 available".
5890 kill-subprocess
5892 kill-subprocess
5893 This kills the hypervisor.
5895 Do not call this. See: "shutdown" instead.
5897 This function is deprecated. In new code, use the "shutdown" call
5899 instead.
5900 Deprecated functions will not be removed from the API, but the fact
5902 that they are deprecated indicates that there are problems with correct
5903 use of these functions.
5904 launch
5906 run
5907 launch
5908 You should call this after configuring the handle (eg. adding drives)
5910 but before performing any actions.
5911 Do not call "launch" twice on the same handle. Although it will not
5913 give an error (for historical reasons), the precise behaviour when you
5914 do this is not well defined. Handles are very cheap to create, so
5915 create a new one for each launch.
5916 lchown
5918 lchown owner group path
5919 Change the file owner to "owner" and group to "group". This is like
5921 "chown" but if "path" is a symlink then the link itself is changed, not
5922 the target.
5923 Only numeric uid and gid are supported. If you want to use names, you
5925 will need to locate and parse the password file yourself (Augeas
5926 support makes this relatively easy).
5927 ldmtool-create-all
5929 ldmtool-create-all
5930 This function scans all block devices looking for Windows dynamic disk
5932 volumes and partitions, and creates devices for any that were found.
5933 Call "list-ldm-volumes" and "list-ldm-partitions" to return all
5935 devices.
5936 Note that you don't normally need to call this explicitly, since it is
5938 done automatically at "launch" time. However you might want to call
5939 this function if you have hotplugged disks or have just created a
5940 Windows dynamic disk.
5941 This command depends on the feature "ldm". See also "feature-
5943 available".
5944 ldmtool-diskgroup-disks
5946 ldmtool-diskgroup-disks diskgroup
5947 Return the disks in a Windows dynamic disk group. The "diskgroup"
5949 parameter should be the GUID of a disk group, one element from the list
5950 returned by "ldmtool-scan".
5951 This command depends on the feature "ldm". See also "feature-
5953 available".
5954 ldmtool-diskgroup-name
5956 ldmtool-diskgroup-name diskgroup
5957 Return the name of a Windows dynamic disk group. The "diskgroup"
5959 parameter should be the GUID of a disk group, one element from the list
5960 returned by "ldmtool-scan".
5961 This command depends on the feature "ldm". See also "feature-
5963 available".
5964 ldmtool-diskgroup-volumes
5966 ldmtool-diskgroup-volumes diskgroup
5967 Return the volumes in a Windows dynamic disk group. The "diskgroup"
5969 parameter should be the GUID of a disk group, one element from the list
5970 returned by "ldmtool-scan".
5971 This command depends on the feature "ldm". See also "feature-
5973 available".
5974 ldmtool-remove-all
5976 ldmtool-remove-all
5977 This is essentially the opposite of "ldmtool-create-all". It removes
5979 the device mapper mappings for all Windows dynamic disk volumes
5980 This command depends on the feature "ldm". See also "feature-
5982 available".
5983 ldmtool-scan
5985 ldmtool-scan
5986 This function scans for Windows dynamic disks. It returns a list of
5988 identifiers (GUIDs) for all disk groups that were found. These
5989 identifiers can be passed to other "ldmtool-*" functions.
5990 This function scans all block devices. To scan a subset of block
5992 devices, call "ldmtool-scan-devices" instead.
5993 This command depends on the feature "ldm". See also "feature-
5995 available".
5996 ldmtool-scan-devices
5998 ldmtool-scan-devices 'devices ...'
5999 This function scans for Windows dynamic disks. It returns a list of
6001 identifiers (GUIDs) for all disk groups that were found. These
6002 identifiers can be passed to other "ldmtool-*" functions.
6003 The parameter "devices" is a list of block devices which are scanned.
6005 If this list is empty, all block devices are scanned.
6006 This command depends on the feature "ldm". See also "feature-
6008 available".
6009 ldmtool-volume-hint
6011 ldmtool-volume-hint diskgroup volume
6012 Return the hint field of the volume named "volume" in the disk group
6014 with GUID "diskgroup". This may not be defined, in which case the
6015 empty string is returned. The hint field is often, though not always,
6016 the name of a Windows drive, eg. "E:".
6017 This command depends on the feature "ldm". See also "feature-
6019 available".
6020 ldmtool-volume-partitions
6022 ldmtool-volume-partitions diskgroup volume
6023 Return the list of partitions in the volume named "volume" in the disk
6025 group with GUID "diskgroup".
6026 This command depends on the feature "ldm". See also "feature-
6028 available".
6029 ldmtool-volume-type
6031 ldmtool-volume-type diskgroup volume
6032 Return the type of the volume named "volume" in the disk group with
6034 GUID "diskgroup".
6035 Possible volume types that can be returned here include: "simple",
6037 "spanned", "striped", "mirrored", "raid5". Other types may also be
6038 returned.
6039 This command depends on the feature "ldm". See also "feature-
6041 available".
6042 lgetxattr
6044 lgetxattr path name
6045 Get a single extended attribute from file "path" named "name". If
6047 "path" is a symlink, then this call returns an extended attribute from
6048 the symlink.
6049 Normally it is better to get all extended attributes from a file in one
6051 go by calling "getxattrs". However some Linux filesystem
6052 implementations are buggy and do not provide a way to list out
6053 attributes. For these filesystems (notably ntfs-3g) you have to know
6054 the names of the extended attributes you want in advance and call this
6055 function.
6056 Extended attribute values are blobs of binary data. If there is no
6058 extended attribute named "name", this returns an error.
6059 See also: "lgetxattrs", "getxattr", attr(5).
6061 This command depends on the feature "linuxxattrs". See also "feature-
6063 available".
6064 lgetxattrs
6066 lgetxattrs path
6067 This is the same as "getxattrs", but if "path" is a symbolic link, then
6069 it returns the extended attributes of the link itself.
6070 This command depends on the feature "linuxxattrs". See also "feature-
6072 available".
6073 list-9p
6075 list-9p
6076 List all 9p filesystems attached to the guest. A list of mount tags is
6078 returned.
6079 list-devices
6081 list-devices
6082 List all the block devices.
6084 The full block device names are returned, eg. /dev/sda.
6086 See also "list-filesystems".
6088 list-disk-labels
6090 list-disk-labels
6091 If you add drives using the optional "label" parameter of "add-drive-
6093 opts", you can use this call to map between disk labels, and raw block
6094 device and partition names (like /dev/sda and /dev/sda1).
6095 This returns a hashtable, where keys are the disk labels (without the
6097 /dev/disk/guestfs prefix), and the values are the full raw block device
6098 and partition names (eg. /dev/sda and /dev/sda1).
6099 list-dm-devices
6101 list-dm-devices
6102 List all device mapper devices.
6104 The returned list contains /dev/mapper/* devices, eg. ones created by a
6106 previous call to "luks-open".
6107 Device mapper devices which correspond to logical volumes are not
6109 returned in this list. Call "lvs" if you want to list logical volumes.
6110 list-filesystems
6112 list-filesystems
6113 This inspection command looks for filesystems on partitions, block
6115 devices and logical volumes, returning a list of "mountables"
6116 containing filesystems and their type.
6117 The return value is a hash, where the keys are the devices containing
6119 filesystems, and the values are the filesystem types. For example:
6120 "/dev/sda1" => "ntfs"
6122 "/dev/sda2" => "ext2"
6123 "/dev/vg_guest/lv_root" => "ext4"
6124 "/dev/vg_guest/lv_swap" => "swap"
6125 The key is not necessarily a block device. It may also be an opaque
6127 ‘mountable’ string which can be passed to "mount".
6128 The value can have the special value "unknown", meaning the content of
6130 the device is undetermined or empty. "swap" means a Linux swap
6131 partition.
6132 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
6134 might have included "mount" and "umount", and therefore you had to use
6135 this soon after launch and only when nothing else was mounted. This
6136 restriction is removed in libguestfs ≥ 1.38.
6137 Not all of the filesystems returned will be mountable. In particular,
6139 swap partitions are returned in the list. Also this command does not
6140 check that each filesystem found is valid and mountable, and some
6141 filesystems might be mountable but require special options.
6142 Filesystems may not all belong to a single logical operating system
6143 (use "inspect-os" to look for OSes).
6144 list-ldm-partitions
6146 list-ldm-partitions
6147 This function returns all Windows dynamic disk partitions that were
6149 found at launch time. It returns a list of device names.
6150 This command depends on the feature "ldm". See also "feature-
6152 available".
6153 list-ldm-volumes
6155 list-ldm-volumes
6156 This function returns all Windows dynamic disk volumes that were found
6158 at launch time. It returns a list of device names.
6159 This command depends on the feature "ldm". See also "feature-
6161 available".
6162 list-md-devices
6164 list-md-devices
6165 List all Linux md devices.
6167 list-partitions
6169 list-partitions
6170 List all the partitions detected on all block devices.
6172 The full partition device names are returned, eg. /dev/sda1
6174 This does not return logical volumes. For that you will need to call
6176 "lvs".
6177 See also "list-filesystems".
6179 ll
6181 ll directory
6182 List the files in directory (relative to the root directory, there is
6184 no cwd) in the format of 'ls -la'.
6185 This command is mostly useful for interactive sessions. It is not
6187 intended that you try to parse the output string.
6188 llz
6190 llz directory
6191 List the files in directory in the format of 'ls -laZ'.
6193 This command is mostly useful for interactive sessions. It is not
6195 intended that you try to parse the output string.
6196 This function is deprecated. In new code, use the "lgetxattrs" call
6198 instead.
6199 Deprecated functions will not be removed from the API, but the fact
6201 that they are deprecated indicates that there are problems with correct
6202 use of these functions.
6203 ln
6205 ln target linkname
6206 This command creates a hard link using the "ln" command.
6208 ln-f
6210 ln-f target linkname
6211 This command creates a hard link using the "ln -f" command. The -f
6213 option removes the link ("linkname") if it exists already.
6214 ln-s
6216 ln-s target linkname
6217 This command creates a symbolic link using the "ln -s" command.
6219 ln-sf
6221 ln-sf target linkname
6222 This command creates a symbolic link using the "ln -sf" command, The -f
6224 option removes the link ("linkname") if it exists already.
6225 lremovexattr
6227 lremovexattr xattr path
6228 This is the same as "removexattr", but if "path" is a symbolic link,
6230 then it removes an extended attribute of the link itself.
6231 This command depends on the feature "linuxxattrs". See also "feature-
6233 available".
6234 ls
6236 ls directory
6237 List the files in directory (relative to the root directory, there is
6239 no cwd). The '.' and '..' entries are not returned, but hidden files
6240 are shown.
6241 ls0
6243 ls0 dir (filenames|-)
6244 This specialized command is used to get a listing of the filenames in
6246 the directory "dir". The list of filenames is written to the local
6247 file filenames (on the host).
6248 In the output file, the filenames are separated by "\0" characters.
6250 "." and ".." are not returned. The filenames are not sorted.
6252 Use "-" instead of a filename to read/write from stdin/stdout.
6254 lsetxattr
6256 lsetxattr xattr val vallen path
6257 This is the same as "setxattr", but if "path" is a symbolic link, then
6259 it sets an extended attribute of the link itself.
6260 This command depends on the feature "linuxxattrs". See also "feature-
6262 available".
6263 lstat
6265 lstat path
6266 Returns file information for the given "path".
6268 This is the same as "stat" except that if "path" is a symbolic link,
6270 then the link is stat-ed, not the file it refers to.
6271 This is the same as the lstat(2) system call.
6273 This function is deprecated. In new code, use the "lstatns" call
6275 instead.
6276 Deprecated functions will not be removed from the API, but the fact
6278 that they are deprecated indicates that there are problems with correct
6279 use of these functions.
6280 lstatlist
6282 lstatlist path 'names ...'
6283 This call allows you to perform the "lstat" operation on multiple
6285 files, where all files are in the directory "path". "names" is the
6286 list of files from this directory.
6287 On return you get a list of stat structs, with a one-to-one
6289 correspondence to the "names" list. If any name did not exist or could
6290 not be lstat'd, then the "st_ino" field of that structure is set to
6291 "-1".
6292 This call is intended for programs that want to efficiently list a
6294 directory contents without making many round-trips. See also
6295 "lxattrlist" for a similarly efficient call for getting extended
6296 attributes.
6297 This function is deprecated. In new code, use the "lstatnslist" call
6299 instead.
6300 Deprecated functions will not be removed from the API, but the fact
6302 that they are deprecated indicates that there are problems with correct
6303 use of these functions.
6304 lstatns
6306 lstatns path
6307 Returns file information for the given "path".
6309 This is the same as "statns" except that if "path" is a symbolic link,
6311 then the link is stat-ed, not the file it refers to.
6312 This is the same as the lstat(2) system call.
6314 lstatnslist
6316 lstatnslist path 'names ...'
6317 This call allows you to perform the "lstatns" operation on multiple
6319 files, where all files are in the directory "path". "names" is the
6320 list of files from this directory.
6321 On return you get a list of stat structs, with a one-to-one
6323 correspondence to the "names" list. If any name did not exist or could
6324 not be lstat'd, then the "st_ino" field of that structure is set to
6325 "-1".
6326 This call is intended for programs that want to efficiently list a
6328 directory contents without making many round-trips. See also
6329 "lxattrlist" for a similarly efficient call for getting extended
6330 attributes.
6331 luks-add-key
6333 luks-add-key device keyslot
6334 This command adds a new key on LUKS device "device". "key" is any
6336 existing key, and is used to access the device. "newkey" is the new
6337 key to add. "keyslot" is the key slot that will be replaced.
6338 Note that if "keyslot" already contains a key, then this command will
6340 fail. You have to use "luks-kill-slot" first to remove that key.
6341 This command has one or more key or passphrase parameters. Guestfish
6343 will prompt for these separately.
6344 This command depends on the feature "luks". See also "feature-
6346 available".
6347 luks-close
6349 luks-close device
6350 This closes a LUKS device that was created earlier by "luks-open" or
6352 "luks-open-ro". The "device" parameter must be the name of the LUKS
6353 mapping device (ie. /dev/mapper/mapname) and not the name of the
6354 underlying block device.
6355 This command depends on the feature "luks". See also "feature-
6357 available".
6358 luks-format
6360 luks-format device keyslot
6361 This command erases existing data on "device" and formats the device as
6363 a LUKS encrypted device. "key" is the initial key, which is added to
6364 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
6365 This command has one or more key or passphrase parameters. Guestfish
6367 will prompt for these separately.
6368 This command depends on the feature "luks". See also "feature-
6370 available".
6371 luks-format-cipher
6373 luks-format-cipher device keyslot cipher
6374 This command is the same as "luks-format" but it also allows you to set
6376 the "cipher" used.
6377 This command has one or more key or passphrase parameters. Guestfish
6379 will prompt for these separately.
6380 This command depends on the feature "luks". See also "feature-
6382 available".
6383 luks-kill-slot
6385 luks-kill-slot device keyslot
6386 This command deletes the key in key slot "keyslot" from the encrypted
6388 LUKS device "device". "key" must be one of the other keys.
6389 This command has one or more key or passphrase parameters. Guestfish
6391 will prompt for these separately.
6392 This command depends on the feature "luks". See also "feature-
6394 available".
6395 luks-open
6397 luks-open device mapname
6398 This command opens a block device which has been encrypted according to
6400 the Linux Unified Key Setup (LUKS) standard.
6401 "device" is the encrypted block device or partition.
6403 The caller must supply one of the keys associated with the LUKS block
6405 device, in the "key" parameter.
6406 This creates a new block device called /dev/mapper/mapname. Reads and
6408 writes to this block device are decrypted from and encrypted to the
6409 underlying "device" respectively.
6410 If this block device contains LVM volume groups, then calling "lvm-
6412 scan" with the "activate" parameter "true" will make them visible.
6413 Use "list-dm-devices" to list all device mapper devices.
6415 This command has one or more key or passphrase parameters. Guestfish
6417 will prompt for these separately.
6418 This command depends on the feature "luks". See also "feature-
6420 available".
6421 luks-open-ro
6423 luks-open-ro device mapname
6424 This is the same as "luks-open" except that a read-only mapping is
6426 created.
6427 This command has one or more key or passphrase parameters. Guestfish
6429 will prompt for these separately.
6430 This command depends on the feature "luks". See also "feature-
6432 available".
6433 lvcreate
6435 lvcreate logvol volgroup mbytes
6436 This creates an LVM logical volume called "logvol" on the volume group
6438 "volgroup", with "size" megabytes.
6439 This command depends on the feature "lvm2". See also "feature-
6441 available".
6442 lvcreate-free
6444 lvcreate-free logvol volgroup percent
6445 Create an LVM logical volume called /dev/volgroup/logvol, using
6447 approximately "percent" % of the free space remaining in the volume
6448 group. Most usefully, when "percent" is 100 this will create the
6449 largest possible LV.
6450 This command depends on the feature "lvm2". See also "feature-
6452 available".
6453 lvm-canonical-lv-name
6455 lvm-canonical-lv-name lvname
6456 This converts alternative naming schemes for LVs that you might find to
6458 the canonical name. For example, /dev/mapper/VG-LV is converted to
6459 /dev/VG/LV.
6460 This command returns an error if the "lvname" parameter does not refer
6462 to a logical volume.
6463 See also "is-lv", "canonical-device-name".
6465 lvm-clear-filter
6467 lvm-clear-filter
6468 This undoes the effect of "lvm-set-filter". LVM will be able to see
6470 every block device.
6471 This command also clears the LVM cache and performs a volume group
6473 scan.
6474 lvm-remove-all
6476 lvm-remove-all
6477 This command removes all LVM logical volumes, volume groups and
6479 physical volumes.
6480 This command depends on the feature "lvm2". See also "feature-
6482 available".
6483 lvm-scan
6485 lvm-scan true|false
6486 This scans all block devices and rebuilds the list of LVM physical
6488 volumes, volume groups and logical volumes.
6489 If the "activate" parameter is "true" then newly found volume groups
6491 and logical volumes are activated, meaning the LV /dev/VG/LV devices
6492 become visible.
6493 When a libguestfs handle is launched it scans for existing devices, so
6495 you do not normally need to use this API. However it is useful when
6496 you have added a new device or deleted an existing device (such as when
6497 the "luks-open" API is used).
6498 lvm-set-filter
6500 lvm-set-filter 'devices ...'
6501 This sets the LVM device filter so that LVM will only be able to "see"
6503 the block devices in the list "devices", and will ignore all other
6504 attached block devices.
6505 Where disk image(s) contain duplicate PVs or VGs, this command is
6507 useful to get LVM to ignore the duplicates, otherwise LVM can get
6508 confused. Note also there are two types of duplication possible:
6509 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
6510 cloned but just happen to have the same name. In normal operation you
6511 cannot create this situation, but you can do it outside LVM, eg. by
6512 cloning disk images or by bit twiddling inside the LVM metadata.
6513 This command also clears the LVM cache and performs a volume group
6515 scan.
6516 You can filter whole block devices or individual partitions.
6518 You cannot use this if any VG is currently in use (eg. contains a
6520 mounted filesystem), even if you are not filtering out that VG.
6521 This command depends on the feature "lvm2". See also "feature-
6523 available".
6524 lvremove
6526 lvremove device
6527 Remove an LVM logical volume "device", where "device" is the path to
6529 the LV, such as /dev/VG/LV.
6530 You can also remove all LVs in a volume group by specifying the VG
6532 name, /dev/VG.
6533 This command depends on the feature "lvm2". See also "feature-
6535 available".
6536 lvrename
6538 lvrename logvol newlogvol
6539 Rename a logical volume "logvol" with the new name "newlogvol".
6541 lvresize
6543 lvresize device mbytes
6544 This resizes (expands or shrinks) an existing LVM logical volume to
6546 "mbytes". When reducing, data in the reduced part is lost.
6547 This command depends on the feature "lvm2". See also "feature-
6549 available".
6550 lvresize-free
6552 lvresize-free lv percent
6553 This expands an existing logical volume "lv" so that it fills "pc"% of
6555 the remaining free space in the volume group. Commonly you would call
6556 this with pc = 100 which expands the logical volume as much as
6557 possible, using all remaining free space in the volume group.
6558 This command depends on the feature "lvm2". See also "feature-
6560 available".
6561 lvs
6563 lvs
6564 List all the logical volumes detected. This is the equivalent of the
6566 lvs(8) command.
6567 This returns a list of the logical volume device names (eg.
6569 /dev/VolGroup00/LogVol00).
6570 See also "lvs-full", "list-filesystems".
6572 This command depends on the feature "lvm2". See also "feature-
6574 available".
6575 lvs-full
6577 lvs-full
6578 List all the logical volumes detected. This is the equivalent of the
6580 lvs(8) command. The "full" version includes all fields.
6581 This command depends on the feature "lvm2". See also "feature-
6583 available".
6584 lvuuid
6586 lvuuid device
6587 This command returns the UUID of the LVM LV "device".
6589 lxattrlist
6591 lxattrlist path 'names ...'
6592 This call allows you to get the extended attributes of multiple files,
6594 where all files are in the directory "path". "names" is the list of
6595 files from this directory.
6596 On return you get a flat list of xattr structs which must be
6598 interpreted sequentially. The first xattr struct always has a zero-
6599 length "attrname". "attrval" in this struct is zero-length to indicate
6600 there was an error doing "lgetxattr" for this file, or is a C string
6601 which is a decimal number (the number of following attributes for this
6602 file, which could be "0"). Then after the first xattr struct are the
6603 zero or more attributes for the first named file. This repeats for the
6604 second and subsequent files.
6605 This call is intended for programs that want to efficiently list a
6607 directory contents without making many round-trips. See also
6608 "lstatlist" for a similarly efficient call for getting standard stats.
6609 This command depends on the feature "linuxxattrs". See also "feature-
6611 available".
6612 max-disks
6614 max-disks
6615 Return the maximum number of disks that may be added to a handle (eg.
6617 by "add-drive-opts" and similar calls).
6618 This function was added in libguestfs 1.19.7. In previous versions of
6620 libguestfs the limit was 25.
6621 See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
6623 on this topic.
6624 md-create
6626 md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
6627 Create a Linux md (RAID) device named "name" on the devices in the list
6629 "devices".
6630 The optional parameters are:
6632 "missingbitmap"
6634 A bitmap of missing devices. If a bit is set it means that a
6635 missing device is added to the array. The least significant bit
6636 corresponds to the first device in the array.
6637 As examples:
6639 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
6641 resulting array would be "[<missing>, "/dev/sda"]".
6642 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
6644 resulting array would be "["/dev/sda", <missing>]".
6645 This defaults to 0 (no missing devices).
6647 The length of "devices" + the number of bits set in "missingbitmap"
6649 must equal "nrdevices" + "spare".
6650 "nrdevices"
6652 The number of active RAID devices.
6653 If not set, this defaults to the length of "devices" plus the
6655 number of bits set in "missingbitmap".
6656 "spare"
6658 The number of spare devices.
6659 If not set, this defaults to 0.
6661 "chunk"
6663 The chunk size in bytes.
6664 "level"
6666 The RAID level, which can be one of: linear, raid0, 0, stripe,
6667 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some
6668 of these are synonymous, and more levels may be added in future.
6669 If not set, this defaults to "raid1".
6671 This command has one or more optional arguments. See "OPTIONAL
6673 ARGUMENTS".
6674 This command depends on the feature "mdadm". See also "feature-
6676 available".
6677 md-detail
6679 md-detail md
6680 This command exposes the output of 'mdadm -DY <md>'. The following
6682 fields are usually present in the returned hash. Other fields may also
6683 be present.
6684 "level"
6686 The raid level of the MD device.
6687 "devices"
6689 The number of underlying devices in the MD device.
6690 "metadata"
6692 The metadata version used.
6693 "uuid"
6695 The UUID of the MD device.
6696 "name"
6698 The name of the MD device.
6699 This command depends on the feature "mdadm". See also "feature-
6701 available".
6702 md-stat
6704 md-stat md
6705 This call returns a list of the underlying devices which make up the
6707 single software RAID array device "md".
6708 To get a list of software RAID devices, call "list-md-devices".
6710 Each structure returned corresponds to one device along with additional
6712 status information:
6713 "mdstat_device"
6715 The name of the underlying device.
6716 "mdstat_index"
6718 The index of this device within the array.
6719 "mdstat_flags"
6721 Flags associated with this device. This is a string containing (in
6722 no specific order) zero or more of the following flags:
6723 "W" write-mostly
6725 "F" device is faulty
6727 "S" device is a RAID spare
6729 "R" replacement
6731 This command depends on the feature "mdadm". See also "feature-
6733 available".
6734 md-stop
6736 md-stop md
6737 This command deactivates the MD array named "md". The device is
6739 stopped, but it is not destroyed or zeroed.
6740 This command depends on the feature "mdadm". See also "feature-
6742 available".
6743 mkdir
6745 mkdir path
6746 Create a directory named "path".
6748 mkdir-mode
6750 mkdir-mode path mode
6751 This command creates a directory, setting the initial permissions of
6753 the directory to "mode".
6754 For common Linux filesystems, the actual mode which is set will be
6756 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
6757 the mode in other ways.
6758 See also "mkdir", "umask"
6760 mkdir-p
6762 mkdir-p path
6763 Create a directory named "path", creating any parent directories as
6765 necessary. This is like the "mkdir -p" shell command.
6766 mkdtemp
6768 mkdtemp tmpl
6769 This command creates a temporary directory. The "tmpl" parameter
6771 should be a full pathname for the temporary directory name with the
6772 final six characters being "XXXXXX".
6773 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
6775 one being suitable for Windows filesystems.
6776 The name of the temporary directory that was created is returned.
6778 The temporary directory is created with mode 0700 and is owned by root.
6780 The caller is responsible for deleting the temporary directory and its
6782 contents after use.
6783 See also: mkdtemp(3)
6785 mke2fs
6787 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]
6788 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
6790 "device".
6791 The optional "blockscount" is the size of the filesystem in blocks. If
6793 omitted it defaults to the size of "device". Note if the filesystem is
6794 too small to contain a journal, "mke2fs" will silently create an ext2
6795 filesystem instead.
6796 This command has one or more optional arguments. See "OPTIONAL
6798 ARGUMENTS".
6799 mke2fs-J
6801 mke2fs-J fstype blocksize device journal
6802 This creates an ext2/3/4 filesystem on "device" with an external
6804 journal on "journal". It is equivalent to the command:
6805 mke2fs -t fstype -b blocksize -J device=<journal> <device>
6807 See also "mke2journal".
6809 This function is deprecated. In new code, use the "mke2fs" call
6811 instead.
6812 Deprecated functions will not be removed from the API, but the fact
6814 that they are deprecated indicates that there are problems with correct
6815 use of these functions.
6816 mke2fs-JL
6818 mke2fs-JL fstype blocksize device label
6819 This creates an ext2/3/4 filesystem on "device" with an external
6821 journal on the journal labeled "label".
6822 See also "mke2journal-L".
6824 This function is deprecated. In new code, use the "mke2fs" call
6826 instead.
6827 Deprecated functions will not be removed from the API, but the fact
6829 that they are deprecated indicates that there are problems with correct
6830 use of these functions.
6831 mke2fs-JU
6833 mke2fs-JU fstype blocksize device uuid
6834 This creates an ext2/3/4 filesystem on "device" with an external
6836 journal on the journal with UUID "uuid".
6837 See also "mke2journal-U".
6839 This function is deprecated. In new code, use the "mke2fs" call
6841 instead.
6842 Deprecated functions will not be removed from the API, but the fact
6844 that they are deprecated indicates that there are problems with correct
6845 use of these functions.
6846 This command depends on the feature "linuxfsuuid". See also "feature-
6848 available".
6849 mke2journal
6851 mke2journal blocksize device
6852 This creates an ext2 external journal on "device". It is equivalent to
6854 the command:
6855 mke2fs -O journal_dev -b blocksize device
6857 This function is deprecated. In new code, use the "mke2fs" call
6859 instead.
6860 Deprecated functions will not be removed from the API, but the fact
6862 that they are deprecated indicates that there are problems with correct
6863 use of these functions.
6864 mke2journal-L
6866 mke2journal-L blocksize label device
6867 This creates an ext2 external journal on "device" with label "label".
6869 This function is deprecated. In new code, use the "mke2fs" call
6871 instead.
6872 Deprecated functions will not be removed from the API, but the fact
6874 that they are deprecated indicates that there are problems with correct
6875 use of these functions.
6876 mke2journal-U
6878 mke2journal-U blocksize uuid device
6879 This creates an ext2 external journal on "device" with UUID "uuid".
6881 This function is deprecated. In new code, use the "mke2fs" call
6883 instead.
6884 Deprecated functions will not be removed from the API, but the fact
6886 that they are deprecated indicates that there are problems with correct
6887 use of these functions.
6888 This command depends on the feature "linuxfsuuid". See also "feature-
6890 available".
6891 mkfifo
6893 mkfifo mode path
6894 This call creates a FIFO (named pipe) called "path" with mode "mode".
6896 It is just a convenient wrapper around "mknod".
6897 Unlike with "mknod", "mode" must contain only permissions bits.
6899 The mode actually set is affected by the umask.
6901 This command depends on the feature "mknod". See also "feature-
6903 available".
6904 mkfs
6906 mkfs-opts
6907 mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N] [label:..]
6908 This function creates a filesystem on "device". The filesystem type is
6910 "fstype", for example "ext3".
6911 The optional arguments are:
6913 "blocksize"
6915 The filesystem block size. Supported block sizes depend on the
6916 filesystem type, but typically they are 1024, 2048 or 4096 for
6917 Linux ext2/3 filesystems.
6918 For VFAT and NTFS the "blocksize" parameter is treated as the
6920 requested cluster size.
6921 For UFS block sizes, please see mkfs.ufs(8).
6923 "features"
6925 This passes the -O parameter to the external mkfs program.
6926 For certain filesystem types, this allows extra filesystem features
6928 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
6929 You cannot use this optional parameter with the "gfs" or "gfs2"
6931 filesystem type.
6932 "inode"
6934 This passes the -I parameter to the external mke2fs(8) program
6935 which sets the inode size (only for ext2/3/4 filesystems at
6936 present).
6937 "sectorsize"
6939 This passes the -S parameter to external mkfs.ufs(8) program, which
6940 sets sector size for ufs filesystem.
6941 This command has one or more optional arguments. See "OPTIONAL
6943 ARGUMENTS".
6944 mkfs-b
6946 mkfs-b fstype blocksize device
6947 This call is similar to "mkfs", but it allows you to control the block
6949 size of the resulting filesystem. Supported block sizes depend on the
6950 filesystem type, but typically they are 1024, 2048 or 4096 only.
6951 For VFAT and NTFS the "blocksize" parameter is treated as the requested
6953 cluster size.
6954 This function is deprecated. In new code, use the "mkfs" call instead.
6956 Deprecated functions will not be removed from the API, but the fact
6958 that they are deprecated indicates that there are problems with correct
6959 use of these functions.
6960 mkfs-btrfs
6962 mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]
6963 Create a btrfs filesystem, allowing all configurables to be set. For
6965 more information on the optional arguments, see mkfs.btrfs(8).
6966 Since btrfs filesystems can span multiple devices, this takes a non-
6968 empty list of devices.
6969 To create general filesystems, use "mkfs".
6971 This command has one or more optional arguments. See "OPTIONAL
6973 ARGUMENTS".
6974 This command depends on the feature "btrfs". See also "feature-
6976 available".
6977 mklost-and-found
6979 mklost-and-found mountpoint
6980 Make the "lost+found" directory, normally in the root directory of an
6982 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
6983 to create the "lost+found" directory.
6984 mkmountpoint
6986 mkmountpoint exemptpath
6987 "mkmountpoint" and "rmmountpoint" are specialized calls that can be
6989 used to create extra mountpoints before mounting the first filesystem.
6990 These calls are only necessary in some very limited circumstances,
6992 mainly the case where you want to mount a mix of unrelated and/or read-
6993 only filesystems together.
6994 For example, live CDs often contain a "Russian doll" nest of
6996 filesystems, an ISO outer layer, with a squashfs image inside, with an
6997 ext2/3 image inside that. You can unpack this as follows in guestfish:
6998 add-ro Fedora-11-i686-Live.iso
7000 run
7001 mkmountpoint /cd
7002 mkmountpoint /sqsh
7003 mkmountpoint /ext3fs
7004 mount /dev/sda /cd
7005 mount-loop /cd/LiveOS/squashfs.img /sqsh
7006 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
7007 The inner filesystem is now unpacked under the /ext3fs mountpoint.
7009 "mkmountpoint" is not compatible with "umount-all". You may get
7011 unexpected errors if you try to mix these calls. It is safest to
7012 manually unmount filesystems and remove mountpoints after use.
7013 "umount-all" unmounts filesystems by sorting the paths longest first,
7015 so for this to work for manual mountpoints, you must ensure that the
7016 innermost mountpoints have the longest pathnames, as in the example
7017 code above.
7018 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
7020 Autosync [see "set-autosync", this is set by default on handles] can
7022 cause "umount-all" to be called when the handle is closed which can
7023 also trigger these issues.
7024 mknod
7026 mknod mode devmajor devminor path
7027 This call creates block or character special devices, or named pipes
7029 (FIFOs).
7030 The "mode" parameter should be the mode, using the standard constants.
7032 "devmajor" and "devminor" are the device major and minor numbers, only
7033 used when creating block and character special devices.
7034 Note that, just like mknod(2), the mode must be bitwise OR'd with
7036 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
7037 a regular file). These constants are available in the standard Linux
7038 header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
7039 wrappers around this command which bitwise OR in the appropriate
7040 constant for you.
7041 The mode actually set is affected by the umask.
7043 This command depends on the feature "mknod". See also "feature-
7045 available".
7046 mknod-b
7048 mknod-b mode devmajor devminor path
7049 This call creates a block device node called "path" with mode "mode"
7051 and device major/minor "devmajor" and "devminor". It is just a
7052 convenient wrapper around "mknod".
7053 Unlike with "mknod", "mode" must contain only permissions bits.
7055 The mode actually set is affected by the umask.
7057 This command depends on the feature "mknod". See also "feature-
7059 available".
7060 mknod-c
7062 mknod-c mode devmajor devminor path
7063 This call creates a char device node called "path" with mode "mode" and
7065 device major/minor "devmajor" and "devminor". It is just a convenient
7066 wrapper around "mknod".
7067 Unlike with "mknod", "mode" must contain only permissions bits.
7069 The mode actually set is affected by the umask.
7071 This command depends on the feature "mknod". See also "feature-
7073 available".
7074 mksquashfs
7076 mksquashfs path (filename|-) [compress:..] [excludes:..]
7077 Create a squashfs filesystem for the specified "path".
7079 The optional "compress" flag controls compression. If not given, then
7081 the output compressed using "gzip". Otherwise one of the following
7082 strings may be given to select the compression type of the squashfs:
7083 "gzip", "lzma", "lzo", "lz4", "xz".
7084 The other optional arguments are:
7086 "excludes"
7088 A list of wildcards. Files are excluded if they match any of the
7089 wildcards.
7090 Please note that this API may fail when used to compress directories
7092 with large files, such as the resulting squashfs will be over 3GB big.
7093 Use "-" instead of a filename to read/write from stdin/stdout.
7095 This command has one or more optional arguments. See "OPTIONAL
7097 ARGUMENTS".
7098 This command depends on the feature "squashfs". See also "feature-
7100 available".
7101 mkswap
7103 mkswap-opts
7104 mkswap device [label:..] [uuid:..]
7105 Create a Linux swap partition on "device".
7107 The option arguments "label" and "uuid" allow you to set the label
7109 and/or UUID of the new swap partition.
7110 This command has one or more optional arguments. See "OPTIONAL
7112 ARGUMENTS".
7113 mkswap-L
7115 mkswap-L label device
7116 Create a swap partition on "device" with label "label".
7118 Note that you cannot attach a swap label to a block device (eg.
7120 /dev/sda), just to a partition. This appears to be a limitation of the
7121 kernel or swap tools.
7122 This function is deprecated. In new code, use the "mkswap" call
7124 instead.
7125 Deprecated functions will not be removed from the API, but the fact
7127 that they are deprecated indicates that there are problems with correct
7128 use of these functions.
7129 mkswap-U
7131 mkswap-U uuid device
7132 Create a swap partition on "device" with UUID "uuid".
7134 This function is deprecated. In new code, use the "mkswap" call
7136 instead.
7137 Deprecated functions will not be removed from the API, but the fact
7139 that they are deprecated indicates that there are problems with correct
7140 use of these functions.
7141 This command depends on the feature "linuxfsuuid". See also "feature-
7143 available".
7144 mkswap-file
7146 mkswap-file path
7147 Create a swap file.
7149 This command just writes a swap file signature to an existing file. To
7151 create the file itself, use something like "fallocate".
7152 mktemp
7154 mktemp tmpl [suffix:..]
7155 This command creates a temporary file. The "tmpl" parameter should be
7157 a full pathname for the temporary directory name with the final six
7158 characters being "XXXXXX".
7159 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
7161 one being suitable for Windows filesystems.
7162 The name of the temporary file that was created is returned.
7164 The temporary file is created with mode 0600 and is owned by root.
7166 The caller is responsible for deleting the temporary file after use.
7168 If the optional "suffix" parameter is given, then the suffix (eg.
7170 ".txt") is appended to the temporary name.
7171 See also: "mkdtemp".
7173 This command has one or more optional arguments. See "OPTIONAL
7175 ARGUMENTS".
7176 modprobe
7178 modprobe modulename
7179 This loads a kernel module in the appliance.
7181 This command depends on the feature "linuxmodules". See also
7183 "feature-available".
7184 mount
7186 mount mountable mountpoint
7187 Mount a guest disk at a position in the filesystem. Block devices are
7189 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
7190 If those block devices contain partitions, they will have the usual
7191 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
7192 ‘mountable’ strings returned by "list-filesystems" or "inspect-get-
7193 mountpoints".
7194 The rules are the same as for mount(2): A filesystem must first be
7196 mounted on / before others can be mounted. Other filesystems can only
7197 be mounted on directories which already exist.
7198 The mounted filesystem is writable, if we have sufficient permissions
7200 on the underlying device.
7201 Before libguestfs 1.13.16, this call implicitly added the options
7203 "sync" and "noatime". The "sync" option greatly slowed writes and
7204 caused many problems for users. If your program might need to work
7205 with older versions of libguestfs, use "mount-options" instead (using
7206 an empty string for the first parameter if you don't want any options).
7207 mount-9p
7209 mount-9p mounttag mountpoint [options:..]
7210 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
7212 "mountpoint".
7213 If required, "trans=virtio" will be automatically added to the options.
7215 Any other options required can be passed in the optional "options"
7216 parameter.
7217 This command has one or more optional arguments. See "OPTIONAL
7219 ARGUMENTS".
7220 mount-local
7222 mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
7223 This call exports the libguestfs-accessible filesystem to a local
7225 mountpoint (directory) called "localmountpoint". Ordinary reads and
7226 writes to files and directories under "localmountpoint" are redirected
7227 through libguestfs.
7228 If the optional "readonly" flag is set to true, then writes to the
7230 filesystem return error "EROFS".
7231 "options" is a comma-separated list of mount options. See
7233 guestmount(1) for some useful options.
7234 "cachetimeout" sets the timeout (in seconds) for cached directory
7236 entries. The default is 60 seconds. See guestmount(1) for further
7237 information.
7238 If "debugcalls" is set to true, then additional debugging information
7240 is generated for every FUSE call.
7241 When "mount-local" returns, the filesystem is ready, but is not
7243 processing requests (access to it will block). You have to call
7244 "mount-local-run" to run the main loop.
7245 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7247 This command has one or more optional arguments. See "OPTIONAL
7249 ARGUMENTS".
7250 mount-local-run
7252 mount-local-run
7253 Run the main loop which translates kernel calls to libguestfs calls.
7255 This should only be called after "mount-local" returns successfully.
7257 The call will not return until the filesystem is unmounted.
7258 Note you must not make concurrent libguestfs calls on the same handle
7260 from another thread.
7261 You may call this from a different thread than the one which called
7263 "mount-local", subject to the usual rules for threads and libguestfs
7264 (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
7265 See "MOUNT LOCAL" in guestfs(3) for full documentation.
7267 mount-loop
7269 mount-loop file mountpoint
7270 This command lets you mount file (a filesystem image in a file) on a
7272 mount point. It is entirely equivalent to the command "mount -o loop
7273 file mountpoint".
7274 mount-options
7276 mount-options options mountable mountpoint
7277 This is the same as the "mount" command, but it allows you to set the
7279 mount options as for the mount(8) -o flag.
7280 If the "options" parameter is an empty string, then no options are
7282 passed (all options default to whatever the filesystem uses).
7283 mount-ro
7285 mount-ro mountable mountpoint
7286 This is the same as the "mount" command, but it mounts the filesystem
7288 with the read-only (-o ro) flag.
7289 mount-vfs
7291 mount-vfs options vfstype mountable mountpoint
7292 This is the same as the "mount" command, but it allows you to set both
7294 the mount options and the vfstype as for the mount(8) -o and -t flags.
7295 mountable-device
7297 mountable-device mountable
7298 Returns the device name of a mountable. In quite a lot of cases, the
7300 mountable is the device name.
7301 However this doesn't apply for btrfs subvolumes, where the mountable is
7303 a combination of both the device name and the subvolume path (see also
7304 "mountable-subvolume" to extract the subvolume path of the mountable if
7305 any).
7306 mountable-subvolume
7308 mountable-subvolume mountable
7309 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
7311 are a combination of both the device name and the subvolume path (see
7312 also "mountable-device" to extract the device of the mountable).
7313 If the mountable does not represent a btrfs subvolume, then this
7315 function fails and the "errno" is set to "EINVAL".
7316 mountpoints
7318 mountpoints
7319 This call is similar to "mounts". That call returns a list of devices.
7321 This one returns a hash table (map) of device name to directory where
7322 the device is mounted.
7323 mounts
7325 mounts
7326 This returns the list of currently mounted filesystems. It returns the
7328 list of devices (eg. /dev/sda1, /dev/VG/LV).
7329 Some internal mounts are not shown.
7331 See also: "mountpoints"
7333 mv
7335 mv src dest
7336 This moves a file from "src" to "dest" where "dest" is either a
7338 destination filename or destination directory.
7339 See also: "rename".
7341 nr-devices
7343 nr-devices
7344 This returns the number of whole block devices that were added. This
7346 is the same as the number of devices that would be returned if you
7347 called "list-devices".
7348 To find out the maximum number of devices that could be added, call
7350 "max-disks".
7351 ntfs-3g-probe
7353 ntfs-3g-probe true|false device
7354 This command runs the ntfs-3g.probe(8) command which probes an NTFS
7356 "device" for mountability. (Not all NTFS volumes can be mounted read-
7357 write, and some cannot be mounted at all).
7358 "rw" is a boolean flag. Set it to true if you want to test if the
7360 volume can be mounted read-write. Set it to false if you want to test
7361 if the volume can be mounted read-only.
7362 The return value is an integer which 0 if the operation would succeed,
7364 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
7365 This command depends on the feature "ntfs3g". See also "feature-
7367 available".
7368 ntfscat-i
7370 ntfscat-i device inode (filename|-)
7371 Download a file given its inode from a NTFS filesystem and save it as
7373 filename on the local machine.
7374 This allows to download some otherwise inaccessible files such as the
7376 ones within the $Extend folder.
7377 The filesystem from which to extract the file must be unmounted,
7379 otherwise the call will fail.
7380 Use "-" instead of a filename to read/write from stdin/stdout.
7382 ntfsclone-in
7384 ntfsclone-in (backupfile|-) device
7385 Restore the "backupfile" (from a previous call to "ntfsclone-out") to
7387 "device", overwriting any existing contents of this device.
7388 Use "-" instead of a filename to read/write from stdin/stdout.
7390 This command depends on the feature "ntfs3g". See also "feature-
7392 available".
7393 ntfsclone-out
7395 ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
7396 Stream the NTFS filesystem "device" to the local file "backupfile".
7398 The format used for the backup file is a special format used by the
7399 ntfsclone(8) tool.
7400 If the optional "metadataonly" flag is true, then only the metadata is
7402 saved, losing all the user data (this is useful for diagnosing some
7403 filesystem problems).
7404 The optional "rescue", "ignorefscheck", "preservetimestamps" and
7406 "force" flags have precise meanings detailed in the ntfsclone(8) man
7407 page.
7408 Use "ntfsclone-in" to restore the file back to a libguestfs device.
7410 Use "-" instead of a filename to read/write from stdin/stdout.
7412 This command has one or more optional arguments. See "OPTIONAL
7414 ARGUMENTS".
7415 This command depends on the feature "ntfs3g". See also "feature-
7417 available".
7418 ntfsfix
7420 ntfsfix device [clearbadsectors:true|false]
7421 This command repairs some fundamental NTFS inconsistencies, resets the
7423 NTFS journal file, and schedules an NTFS consistency check for the
7424 first boot into Windows.
7425 This is not an equivalent of Windows "chkdsk". It does not scan the
7427 filesystem for inconsistencies.
7428 The optional "clearbadsectors" flag clears the list of bad sectors.
7430 This is useful after cloning a disk with bad sectors to a new disk.
7431 This command has one or more optional arguments. See "OPTIONAL
7433 ARGUMENTS".
7434 This command depends on the feature "ntfs3g". See also "feature-
7436 available".
7437 ntfsresize
7439 ntfsresize-opts
7440 ntfsresize device [size:N] [force:true|false]
7441 This command resizes an NTFS filesystem, expanding or shrinking it to
7443 the size of the underlying device.
7444 The optional parameters are:
7446 "size"
7448 The new size (in bytes) of the filesystem. If omitted, the
7449 filesystem is resized to fit the container (eg. partition).
7450 "force"
7452 If this option is true, then force the resize of the filesystem
7453 even if the filesystem is marked as requiring a consistency check.
7454 After the resize operation, the filesystem is always marked as
7456 requiring a consistency check (for safety). You have to boot into
7457 Windows to perform this check and clear this condition. If you
7458 don't set the "force" option then it is not possible to call
7459 "ntfsresize" multiple times on a single filesystem without booting
7460 into Windows between each resize.
7461 See also ntfsresize(8).
7463 This command has one or more optional arguments. See "OPTIONAL
7465 ARGUMENTS".
7466 This command depends on the feature "ntfsprogs". See also "feature-
7468 available".
7469 ntfsresize-size
7471 ntfsresize-size device size
7472 This command is the same as "ntfsresize" except that it allows you to
7474 specify the new size (in bytes) explicitly.
7475 This function is deprecated. In new code, use the "ntfsresize" call
7477 instead.
7478 Deprecated functions will not be removed from the API, but the fact
7480 that they are deprecated indicates that there are problems with correct
7481 use of these functions.
7482 This command depends on the feature "ntfsprogs". See also "feature-
7484 available".
7485 parse-environment
7487 parse-environment
7488 Parse the program’s environment and set flags in the handle
7490 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
7491 flag is set in the handle.
7492 Most programs do not need to call this. It is done implicitly when you
7494 call "create".
7495 See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
7497 variables that can affect libguestfs handles. See also
7498 "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
7499 parse-environment-list
7501 parse-environment-list 'environment ...'
7502 Parse the list of strings in the argument "environment" and set flags
7504 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
7505 string in the list, then the ‘verbose’ flag is set in the handle.
7506 This is the same as "parse-environment" except that it parses an
7508 explicit list of strings instead of the program's environment.
7509 part-add
7511 part-add device prlogex startsect endsect
7512 This command adds a partition to "device". If there is no partition
7514 table on the device, call "part-init" first.
7515 The "prlogex" parameter is the type of partition. Normally you should
7517 pass "p" or "primary" here, but MBR partition tables also support "l"
7518 (or "logical") and "e" (or "extended") partition types.
7519 "startsect" and "endsect" are the start and end of the partition in
7521 sectors. "endsect" may be negative, which means it counts backwards
7522 from the end of the disk ("-1" is the last sector).
7523 Creating a partition which covers the whole disk is not so easy. Use
7525 "part-disk" to do that.
7526 part-del
7528 part-del device partnum
7529 This command deletes the partition numbered "partnum" on "device".
7531 Note that in the case of MBR partitioning, deleting an extended
7533 partition also deletes any logical partitions it contains.
7534 part-disk
7536 part-disk device parttype
7537 This command is simply a combination of "part-init" followed by "part-
7539 add" to create a single primary partition covering the whole disk.
7540 "parttype" is the partition table type, usually "mbr" or "gpt", but
7542 other possible values are described in "part-init".
7543 part-expand-gpt
7545 part-expand-gpt device
7546 Move backup GPT data structures to the end of the disk. This is useful
7548 in case of in-place image expand since disk space after backup GPT
7549 header is not usable. This is equivalent to "sgdisk -e".
7550 See also sgdisk(8).
7552 This command depends on the feature "gdisk". See also "feature-
7554 available".
7555 part-get-bootable
7557 part-get-bootable device partnum
7558 This command returns true if the partition "partnum" on "device" has
7560 the bootable flag set.
7561 See also "part-set-bootable".
7563 part-get-disk-guid
7565 part-get-disk-guid device
7566 Return the disk identifier (GUID) of a GPT-partitioned "device".
7568 Behaviour is undefined for other partition types.
7569 This command depends on the feature "gdisk". See also "feature-
7571 available".
7572 part-get-gpt-attributes
7574 part-get-gpt-attributes device partnum
7575 Return the attribute flags of numbered GPT partition "partnum". An
7577 error is returned for MBR partitions.
7578 This command depends on the feature "gdisk". See also "feature-
7580 available".
7581 part-get-gpt-guid
7583 part-get-gpt-guid device partnum
7584 Return the GUID of numbered GPT partition "partnum".
7586 This command depends on the feature "gdisk". See also "feature-
7588 available".
7589 part-get-gpt-type
7591 part-get-gpt-type device partnum
7592 Return the type GUID of numbered GPT partition "partnum". For MBR
7594 partitions, return an appropriate GUID corresponding to the MBR type.
7595 Behaviour is undefined for other partition types.
7596 This command depends on the feature "gdisk". See also "feature-
7598 available".
7599 part-get-mbr-id
7601 part-get-mbr-id device partnum
7602 Returns the MBR type byte (also known as the ID byte) from the numbered
7604 partition "partnum".
7605 Note that only MBR (old DOS-style) partitions have type bytes. You
7607 will get undefined results for other partition table types (see "part-
7608 get-parttype").
7609 part-get-mbr-part-type
7611 part-get-mbr-part-type device partnum
7612 This returns the partition type of an MBR partition numbered "partnum"
7614 on device "device".
7615 It returns "primary", "logical", or "extended".
7617 part-get-name
7619 part-get-name device partnum
7620 This gets the partition name on partition numbered "partnum" on device
7622 "device". Note that partitions are numbered from 1.
7623 The partition name can only be read on certain types of partition
7625 table. This works on "gpt" but not on "mbr" partitions.
7626 part-get-parttype
7628 part-get-parttype device
7629 This command examines the partition table on "device" and returns the
7631 partition table type (format) being used.
7632 Common return values include: "msdos" (a DOS/Windows style MBR
7634 partition table), "gpt" (a GPT/EFI-style partition table). Other
7635 values are possible, although unusual. See "part-init" for a full
7636 list.
7637 part-init
7639 part-init device parttype
7640 This creates an empty partition table on "device" of one of the
7642 partition types listed below. Usually "parttype" should be either
7643 "msdos" or "gpt" (for large disks).
7644 Initially there are no partitions. Following this, you should call
7646 "part-add" for each partition required.
7647 Possible values for "parttype" are:
7649 efi
7651 gpt Intel EFI / GPT partition table.
7652 This is recommended for >= 2 TB partitions that will be accessed
7654 from Linux and Intel-based Mac OS X. It also has limited backwards
7655 compatibility with the "mbr" format.
7656 mbr
7658 msdos
7659 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
7660 and Windows. This partition type will only work for device sizes
7661 up to 2 TB. For large disks we recommend using "gpt".
7662 Other partition table types that may work but are not supported
7664 include:
7665 aix AIX disk labels.
7667 amiga
7669 rdb Amiga "Rigid Disk Block" format.
7670 bsd BSD disk labels.
7672 dasd
7674 DASD, used on IBM mainframes.
7675 dvh MIPS/SGI volumes.
7677 mac Old Mac partition format. Modern Macs use "gpt".
7679 pc98
7681 NEC PC-98 format, common in Japan apparently.
7682 sun Sun disk labels.
7684 part-list
7686 part-list device
7687 This command parses the partition table on "device" and returns the
7689 list of partitions found.
7690 The fields in the returned structure are:
7692 part_num
7694 Partition number, counting from 1.
7695 part_start
7697 Start of the partition in bytes. To get sectors you have to divide
7698 by the device’s sector size, see "blockdev-getss".
7699 part_end
7701 End of the partition in bytes.
7702 part_size
7704 Size of the partition in bytes.
7705 part-resize
7707 part-resize device partnum endsect
7708 This command resizes the partition numbered "partnum" on "device" by
7710 moving the end position.
7711 Note that this does not modify any filesystem present in the partition.
7713 If you wish to do this, you will need to use filesystem resizing
7714 commands like "resize2fs".
7715 When growing a partition you will want to grow the filesystem
7717 afterwards, but when shrinking, you need to shrink the filesystem
7718 before the partition.
7719 part-set-bootable
7721 part-set-bootable device partnum true|false
7722 This sets the bootable flag on partition numbered "partnum" on device
7724 "device". Note that partitions are numbered from 1.
7725 The bootable flag is used by some operating systems (notably Windows)
7727 to determine which partition to boot from. It is by no means
7728 universally recognized.
7729 part-set-disk-guid
7731 part-set-disk-guid device guid
7732 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
7734 Return an error if the partition table of "device" isn't GPT, or if
7735 "guid" is not a valid GUID.
7736 This command depends on the feature "gdisk". See also "feature-
7738 available".
7739 part-set-disk-guid-random
7741 part-set-disk-guid-random device
7742 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
7744 randomly generated value. Return an error if the partition table of
7745 "device" isn't GPT.
7746 This command depends on the feature "gdisk". See also "feature-
7748 available".
7749 part-set-gpt-attributes
7751 part-set-gpt-attributes device partnum attributes
7752 Set the attribute flags of numbered GPT partition "partnum" to
7754 "attributes". Return an error if the partition table of "device" isn't
7755 GPT.
7756 See
7758 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
7759 for a useful list of partition attributes.
7760 This command depends on the feature "gdisk". See also "feature-
7762 available".
7763 part-set-gpt-guid
7765 part-set-gpt-guid device partnum guid
7766 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
7768 error if the partition table of "device" isn't GPT, or if "guid" is not
7769 a valid GUID.
7770 This command depends on the feature "gdisk". See also "feature-
7772 available".
7773 part-set-gpt-type
7775 part-set-gpt-type device partnum guid
7776 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
7778 an error if the partition table of "device" isn't GPT, or if "guid" is
7779 not a valid GUID.
7780 See
7782 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
7783 for a useful list of type GUIDs.
7784 This command depends on the feature "gdisk". See also "feature-
7786 available".
7787 part-set-mbr-id
7789 part-set-mbr-id device partnum idbyte
7790 Sets the MBR type byte (also known as the ID byte) of the numbered
7792 partition "partnum" to "idbyte". Note that the type bytes quoted in
7793 most documentation are in fact hexadecimal numbers, but usually
7794 documented without any leading "0x" which might be confusing.
7795 Note that only MBR (old DOS-style) partitions have type bytes. You
7797 will get undefined results for other partition table types (see "part-
7798 get-parttype").
7799 part-set-name
7801 part-set-name device partnum name
7802 This sets the partition name on partition numbered "partnum" on device
7804 "device". Note that partitions are numbered from 1.
7805 The partition name can only be set on certain types of partition table.
7807 This works on "gpt" but not on "mbr" partitions.
7808 part-to-dev
7810 part-to-dev partition
7811 This function takes a partition name (eg. "/dev/sdb1") and removes the
7813 partition number, returning the device name (eg. "/dev/sdb").
7814 The named partition must exist, for example as a string returned from
7816 "list-partitions".
7817 See also "part-to-partnum", "device-index".
7819 part-to-partnum
7821 part-to-partnum partition
7822 This function takes a partition name (eg. "/dev/sdb1") and returns the
7824 partition number (eg. 1).
7825 The named partition must exist, for example as a string returned from
7827 "list-partitions".
7828 See also "part-to-dev".
7830 ping-daemon
7832 ping-daemon
7833 This is a test probe into the guestfs daemon running inside the
7835 libguestfs appliance. Calling this function checks that the daemon
7836 responds to the ping message, without affecting the daemon or attached
7837 block device(s) in any other way.
7838 pread
7840 pread path count offset
7841 This command lets you read part of a file. It reads "count" bytes of
7843 the file, starting at "offset", from file "path".
7844 This may read fewer bytes than requested. For further details see the
7846 pread(2) system call.
7847 See also "pwrite", "pread-device".
7849 Because of the message protocol, there is a transfer limit of somewhere
7851 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7852 pread-device
7854 pread-device device count offset
7855 This command lets you read part of a block device. It reads "count"
7857 bytes of "device", starting at "offset".
7858 This may read fewer bytes than requested. For further details see the
7860 pread(2) system call.
7861 See also "pread".
7863 Because of the message protocol, there is a transfer limit of somewhere
7865 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7866 pvchange-uuid
7868 pvchange-uuid device
7869 Generate a new random UUID for the physical volume "device".
7871 This command depends on the feature "lvm2". See also "feature-
7873 available".
7874 pvchange-uuid-all
7876 pvchange-uuid-all
7877 Generate new random UUIDs for all physical volumes.
7879 This command depends on the feature "lvm2". See also "feature-
7881 available".
7882 pvcreate
7884 pvcreate device
7885 This creates an LVM physical volume on the named "device", where
7887 "device" should usually be a partition name such as /dev/sda1.
7888 This command depends on the feature "lvm2". See also "feature-
7890 available".
7891 pvremove
7893 pvremove device
7894 This wipes a physical volume "device" so that LVM will no longer
7896 recognise it.
7897 The implementation uses the "pvremove" command which refuses to wipe
7899 physical volumes that contain any volume groups, so you have to remove
7900 those first.
7901 This command depends on the feature "lvm2". See also "feature-
7903 available".
7904 pvresize
7906 pvresize device
7907 This resizes (expands or shrinks) an existing LVM physical volume to
7909 match the new size of the underlying device.
7910 This command depends on the feature "lvm2". See also "feature-
7912 available".
7913 pvresize-size
7915 pvresize-size device size
7916 This command is the same as "pvresize" except that it allows you to
7918 specify the new size (in bytes) explicitly.
7919 This command depends on the feature "lvm2". See also "feature-
7921 available".
7922 pvs
7924 pvs
7925 List all the physical volumes detected. This is the equivalent of the
7927 pvs(8) command.
7928 This returns a list of just the device names that contain PVs (eg.
7930 /dev/sda2).
7931 See also "pvs-full".
7933 This command depends on the feature "lvm2". See also "feature-
7935 available".
7936 pvs-full
7938 pvs-full
7939 List all the physical volumes detected. This is the equivalent of the
7941 pvs(8) command. The "full" version includes all fields.
7942 This command depends on the feature "lvm2". See also "feature-
7944 available".
7945 pvuuid
7947 pvuuid device
7948 This command returns the UUID of the LVM PV "device".
7950 pwrite
7952 pwrite path content offset
7953 This command writes to part of a file. It writes the data buffer
7955 "content" to the file "path" starting at offset "offset".
7956 This command implements the pwrite(2) system call, and like that system
7958 call it may not write the full data requested. The return value is the
7959 number of bytes that were actually written to the file. This could
7960 even be 0, although short writes are unlikely for regular files in
7961 ordinary circumstances.
7962 See also "pread", "pwrite-device".
7964 Because of the message protocol, there is a transfer limit of somewhere
7966 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
7967 pwrite-device
7969 pwrite-device device content offset
7970 This command writes to part of a device. It writes the data buffer
7972 "content" to "device" starting at offset "offset".
7973 This command implements the pwrite(2) system call, and like that system
7975 call it may not write the full data requested (although short writes to
7976 disk devices and partitions are probably impossible with standard Linux
7977 kernels).
7978 See also "pwrite".
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 read-file
7985 read-file path
7986 This calls returns the contents of the file "path" as a buffer.
7988 Unlike "cat", this function can correctly handle files that contain
7990 embedded ASCII NUL characters.
7991 read-lines
7993 read-lines path
7994 Return the contents of the file named "path".
7996 The file contents are returned as a list of lines. Trailing "LF" and
7998 "CRLF" character sequences are not returned.
7999 Note that this function cannot correctly handle binary files
8001 (specifically, files containing "\0" character which is treated as end
8002 of string). For those you need to use the "read-file" function and
8003 split the buffer into lines yourself.
8004 readdir
8006 readdir dir
8007 This returns the list of directory entries in directory "dir".
8009 All entries in the directory are returned, including "." and "..". The
8011 entries are not sorted, but returned in the same order as the
8012 underlying filesystem.
8013 Also this call returns basic file type information about each file.
8015 The "ftyp" field will contain one of the following characters:
8016 'b' Block special
8018 'c' Char special
8020 'd' Directory
8022 'f' FIFO (named pipe)
8024 'l' Symbolic link
8026 'r' Regular file
8028 's' Socket
8030 'u' Unknown file type
8032 '?' The readdir(3) call returned a "d_type" field with an unexpected
8034 value
8035 This function is primarily intended for use by programs. To get a
8037 simple list of names, use "ls". To get a printable directory for human
8038 consumption, use "ll".
8039 Because of the message protocol, there is a transfer limit of somewhere
8041 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
8042 readlink
8044 readlink path
8045 This command reads the target of a symbolic link.
8047 readlinklist
8049 readlinklist path 'names ...'
8050 This call allows you to do a "readlink" operation on multiple files,
8052 where all files are in the directory "path". "names" is the list of
8053 files from this directory.
8054 On return you get a list of strings, with a one-to-one correspondence
8056 to the "names" list. Each string is the value of the symbolic link.
8057 If the readlink(2) operation fails on any name, then the corresponding
8059 result string is the empty string "". However the whole operation is
8060 completed even if there were readlink(2) errors, and so you can call
8061 this function with names where you don't know if they are symbolic
8062 links already (albeit slightly less efficient).
8063 This call is intended for programs that want to efficiently list a
8065 directory contents without making many round-trips.
8066 realpath
8068 realpath path
8069 Return the canonicalized absolute pathname of "path". The returned
8071 path has no ".", ".." or symbolic link path elements.
8072 remount
8074 remount mountpoint [rw:true|false]
8075 This call allows you to change the "rw" (readonly/read-write) flag on
8077 an already mounted filesystem at "mountpoint", converting a readonly
8078 filesystem to be read-write, or vice-versa.
8079 Note that at the moment you must supply the "optional" "rw" parameter.
8081 In future we may allow other flags to be adjusted.
8082 This command has one or more optional arguments. See "OPTIONAL
8084 ARGUMENTS".
8085 remove-drive
8087 remove-drive label
8088 This function is conceptually the opposite of "add-drive-opts". It
8090 removes the drive that was previously added with label "label".
8091 Note that in order to remove drives, you have to add them with labels
8093 (see the optional "label" argument to "add-drive-opts"). If you didn't
8094 use a label, then they cannot be removed.
8095 You can call this function before or after launching the handle. If
8097 called after launch, if the backend supports it, we try to hot unplug
8098 the drive: see "HOTPLUGGING" in guestfs(3). The disk must not be in
8099 use (eg. mounted) when you do this. We try to detect if the disk is in
8100 use and stop you from doing this.
8101 removexattr
8103 removexattr xattr path
8104 This call removes the extended attribute named "xattr" of the file
8106 "path".
8107 See also: "lremovexattr", attr(5).
8109 This command depends on the feature "linuxxattrs". See also "feature-
8111 available".
8112 rename
8114 rename oldpath newpath
8115 Rename a file to a new place on the same filesystem. This is the same
8117 as the Linux rename(2) system call. In most cases you are better to
8118 use "mv" instead.
8119 resize2fs
8121 resize2fs device
8122 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
8124 underlying device.
8125 See also "RESIZE2FS ERRORS" in guestfs(3).
8127 resize2fs-M
8129 resize2fs-M device
8130 This command is the same as "resize2fs", but the filesystem is resized
8132 to its minimum size. This works like the -M option to the "resize2fs"
8133 command.
8134 To get the resulting size of the filesystem you should call "tune2fs-l"
8136 and read the "Block size" and "Block count" values. These two numbers,
8137 multiplied together, give the resulting size of the minimal filesystem
8138 in bytes.
8139 See also "RESIZE2FS ERRORS" in guestfs(3).
8141 resize2fs-size
8143 resize2fs-size device size
8144 This command is the same as "resize2fs" except that it allows you to
8146 specify the new size (in bytes) explicitly.
8147 See also "RESIZE2FS ERRORS" in guestfs(3).
8149 rm
8151 rm path
8152 Remove the single file "path".
8154 rm-f
8156 rm-f path
8157 Remove the file "path".
8159 If the file doesn't exist, that error is ignored. (Other errors, eg.
8161 I/O errors or bad paths, are not ignored)
8162 This call cannot remove directories. Use "rmdir" to remove an empty
8164 directory, or "rm-rf" to remove directories recursively.
8165 rm-rf
8167 rm-rf path
8168 Remove the file or directory "path", recursively removing the contents
8170 if its a directory. This is like the "rm -rf" shell command.
8171 rmdir
8173 rmdir path
8174 Remove the single directory "path".
8176 rmmountpoint
8178 rmmountpoint exemptpath
8179 This call removes a mountpoint that was previously created with
8181 "mkmountpoint". See "mkmountpoint" for full details.
8182 rsync
8184 rsync src dest [archive:true|false] [deletedest:true|false]
8185 This call may be used to copy or synchronize two directories under the
8187 same libguestfs handle. This uses the rsync(1) program which uses a
8188 fast algorithm that avoids copying files unnecessarily.
8189 "src" and "dest" are the source and destination directories. Files are
8191 copied from "src" to "dest".
8192 The optional arguments are:
8194 "archive"
8196 Turns on archive mode. This is the same as passing the --archive
8197 flag to "rsync".
8198 "deletedest"
8200 Delete files at the destination that do not exist at the source.
8201 This command has one or more optional arguments. See "OPTIONAL
8203 ARGUMENTS".
8204 This command depends on the feature "rsync". See also "feature-
8206 available".
8207 rsync-in
8209 rsync-in remote dest [archive:true|false] [deletedest:true|false]
8210 This call may be used to copy or synchronize the filesystem on the host
8212 or on a remote computer with the filesystem within libguestfs. This
8213 uses the rsync(1) program which uses a fast algorithm that avoids
8214 copying files unnecessarily.
8215 This call only works if the network is enabled. See "set-network" or
8217 the --network option to various tools like guestfish(1).
8218 Files are copied from the remote server and directory specified by
8220 "remote" to the destination directory "dest".
8221 The format of the remote server string is defined by rsync(1). Note
8223 that there is no way to supply a password or passphrase so the target
8224 must be set up not to require one.
8225 The optional arguments are the same as those of "rsync".
8227 This command has one or more optional arguments. See "OPTIONAL
8229 ARGUMENTS".
8230 This command depends on the feature "rsync". See also "feature-
8232 available".
8233 rsync-out
8235 rsync-out src remote [archive:true|false] [deletedest:true|false]
8236 This call may be used to copy or synchronize the filesystem within
8238 libguestfs with a filesystem on the host or on a remote computer. This
8239 uses the rsync(1) program which uses a fast algorithm that avoids
8240 copying files unnecessarily.
8241 This call only works if the network is enabled. See "set-network" or
8243 the --network option to various tools like guestfish(1).
8244 Files are copied from the source directory "src" to the remote server
8246 and directory specified by "remote".
8247 The format of the remote server string is defined by rsync(1). Note
8249 that there is no way to supply a password or passphrase so the target
8250 must be set up not to require one.
8251 The optional arguments are the same as those of "rsync".
8253 Globbing does not happen on the "src" parameter. In programs which use
8255 the API directly you have to expand wildcards yourself (see "glob-
8256 expand"). In guestfish you can use the "glob" command (see "glob"),
8257 for example:
8258 ><fs> glob rsync-out /* rsync://remote/
8260 This command has one or more optional arguments. See "OPTIONAL
8262 ARGUMENTS".
8263 This command depends on the feature "rsync". See also "feature-
8265 available".
8266 scrub-device
8268 scrub-device device
8269 This command writes patterns over "device" to make data retrieval more
8271 difficult.
8272 It is an interface to the scrub(1) program. See that manual page for
8274 more details.
8275 This command depends on the feature "scrub". See also "feature-
8277 available".
8278 scrub-file
8280 scrub-file file
8281 This command writes patterns over a file to make data retrieval more
8283 difficult.
8284 The file is removed after scrubbing.
8286 It is an interface to the scrub(1) program. See that manual page for
8288 more details.
8289 This command depends on the feature "scrub". See also "feature-
8291 available".
8292 scrub-freespace
8294 scrub-freespace dir
8295 This command creates the directory "dir" and then fills it with files
8297 until the filesystem is full, and scrubs the files as for "scrub-file",
8298 and deletes them. The intention is to scrub any free space on the
8299 partition containing "dir".
8300 It is an interface to the scrub(1) program. See that manual page for
8302 more details.
8303 This command depends on the feature "scrub". See also "feature-
8305 available".
8306 selinux-relabel
8308 selinux-relabel specfile path [force:true|false]
8309 SELinux relabel parts of the filesystem.
8311 The "specfile" parameter controls the policy spec file used. You have
8313 to parse "/etc/selinux/config" to find the correct SELinux policy and
8314 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
8315 "/contexts/files/file_contexts".
8316 The required "path" parameter is the top level directory where
8318 relabelling starts. Normally you should pass "path" as "/" to relabel
8319 the whole guest filesystem.
8320 The optional "force" boolean controls whether the context is reset for
8322 customizable files, and also whether the user, role and range parts of
8323 the file context is changed.
8324 This command has one or more optional arguments. See "OPTIONAL
8326 ARGUMENTS".
8327 This command depends on the feature "selinuxrelabel". See also
8329 "feature-available".
8330 set-append
8332 append
8333 set-append append
8334 This function is used to add additional options to the libguestfs
8336 appliance kernel command line.
8337 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
8339 environment variable.
8340 Setting "append" to "NULL" means no additional options are passed
8342 (libguestfs always adds a few of its own).
8343 set-attach-method
8345 attach-method
8346 set-attach-method backend
8347 Set the method that libguestfs uses to connect to the backend guestfsd
8349 daemon.
8350 See "BACKEND" in guestfs(3).
8352 This function is deprecated. In new code, use the "set-backend" call
8354 instead.
8355 Deprecated functions will not be removed from the API, but the fact
8357 that they are deprecated indicates that there are problems with correct
8358 use of these functions.
8359 set-autosync
8361 autosync
8362 set-autosync true|false
8363 If "autosync" is true, this enables autosync. Libguestfs will make a
8365 best effort attempt to make filesystems consistent and synchronized
8366 when the handle is closed (also if the program exits without closing
8367 handles).
8368 This is enabled by default (since libguestfs 1.5.24, previously it was
8370 disabled by default).
8371 set-backend
8373 backend
8374 set-backend backend
8375 Set the method that libguestfs uses to connect to the backend guestfsd
8377 daemon.
8378 This handle property was previously called the "attach method".
8380 See "BACKEND" in guestfs(3).
8382 set-backend-setting
8384 set-backend-setting name val
8385 Append "name=value" to the backend settings string list. However if a
8387 string already exists matching "name" or beginning with "name=", then
8388 that setting is replaced.
8389 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8391 set-backend-settings
8393 set-backend-settings 'settings ...'
8394 Set a list of zero or more settings which are passed through to the
8396 current backend. Each setting is a string which is interpreted in a
8397 backend-specific way, or ignored if not understood by the backend.
8398 The default value is an empty list, unless the environment variable
8400 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
8401 This environment variable contains a colon-separated list of settings.
8402 This call replaces all backend settings. If you want to replace a
8404 single backend setting, see "set-backend-setting". If you want to
8405 clear a single backend setting, see "clear-backend-setting".
8406 See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8408 set-cachedir
8410 cachedir
8411 set-cachedir cachedir
8412 Set the directory used by the handle to store the appliance cache, when
8414 using a supermin appliance. The appliance is cached and shared between
8415 all handles which have the same effective user ID.
8416 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
8418 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
8419 default. Else if "TMPDIR" is set, then that is the default. Else
8420 /var/tmp is the default.
8421 set-direct
8423 direct
8424 set-direct true|false
8425 If the direct appliance mode flag is enabled, then stdin and stdout are
8427 passed directly through to the appliance once it is launched.
8428 One consequence of this is that log messages aren't caught by the
8430 library and handled by "set-log-message-callback", but go straight to
8431 stdout.
8432 You probably don't want to use this unless you know what you are doing.
8434 The default is disabled.
8436 This function is deprecated. In new code, use the "internal-get-
8438 console-socket" call instead.
8439 Deprecated functions will not be removed from the API, but the fact
8441 that they are deprecated indicates that there are problems with correct
8442 use of these functions.
8443 set-e2attrs
8445 set-e2attrs file attrs [clear:true|false]
8446 This sets or clears the file attributes "attrs" associated with the
8448 inode file.
8449 "attrs" is a string of characters representing file attributes. See
8451 "get-e2attrs" for a list of possible attributes. Not all attributes
8452 can be changed.
8453 If optional boolean "clear" is not present or false, then the "attrs"
8455 listed are set in the inode.
8456 If "clear" is true, then the "attrs" listed are cleared in the inode.
8458 In both cases, other attributes not present in the "attrs" string are
8460 left unchanged.
8461 These attributes are only present when the file is located on an
8463 ext2/3/4 filesystem. Using this call on other filesystem types will
8464 result in an error.
8465 This command has one or more optional arguments. See "OPTIONAL
8467 ARGUMENTS".
8468 set-e2generation
8470 set-e2generation file generation
8471 This sets the ext2 file generation of a file.
8473 See "get-e2generation".
8475 set-e2label
8477 set-e2label device label
8478 This sets the ext2/3/4 filesystem label of the filesystem on "device"
8480 to "label". Filesystem labels are limited to 16 characters.
8481 You can use either "tune2fs-l" or "get-e2label" to return the existing
8483 label on a filesystem.
8484 This function is deprecated. In new code, use the "set-label" call
8486 instead.
8487 Deprecated functions will not be removed from the API, but the fact
8489 that they are deprecated indicates that there are problems with correct
8490 use of these functions.
8491 set-e2uuid
8493 set-e2uuid device uuid
8494 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
8496 "uuid". The format of the UUID and alternatives such as "clear",
8497 "random" and "time" are described in the tune2fs(8) manpage.
8498 You can use "vfs-uuid" to return the existing UUID of a filesystem.
8500 This function is deprecated. In new code, use the "set-uuid" call
8502 instead.
8503 Deprecated functions will not be removed from the API, but the fact
8505 that they are deprecated indicates that there are problems with correct
8506 use of these functions.
8507 set-hv
8509 hv
8510 set-hv hv
8511 Set the hypervisor binary that we will use. The hypervisor depends on
8513 the backend, but is usually the location of the qemu/KVM hypervisor.
8514 For the uml backend, it is the location of the "linux" or "vmlinux"
8515 binary.
8516 The default is chosen when the library was compiled by the configure
8518 script.
8519 You can also override this by setting the "LIBGUESTFS_HV" environment
8521 variable.
8522 Note that you should call this function as early as possible after
8524 creating the handle. This is because some pre-launch operations depend
8525 on testing qemu features (by running "qemu -help"). If the qemu binary
8526 changes, we don't retest features, and so you might see inconsistent
8527 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8528 all since that picks the qemu binary at the same time as the handle is
8529 created.
8530 set-identifier
8532 identifier
8533 set-identifier identifier
8534 This is an informative string which the caller may optionally set in
8536 the handle. It is printed in various places, allowing the current
8537 handle to be identified in debugging output.
8538 One important place is when tracing is enabled. If the identifier
8540 string is not an empty string, then trace messages change from this:
8541 libguestfs: trace: get_tmpdir
8543 libguestfs: trace: get_tmpdir = "/tmp"
8544 to this:
8546 libguestfs: trace: ID: get_tmpdir
8548 libguestfs: trace: ID: get_tmpdir = "/tmp"
8549 where "ID" is the identifier string set by this call.
8551 The identifier must only contain alphanumeric ASCII characters,
8553 underscore and minus sign. The default is the empty string.
8554 See also "set-program", "set-trace", "get-identifier".
8556 set-label
8558 set-label mountable label
8559 Set the filesystem label on "mountable" to "label".
8561 Only some filesystem types support labels, and libguestfs supports
8563 setting labels on only a subset of these.
8564 ext2, ext3, ext4
8566 Labels are limited to 16 bytes.
8567 NTFS
8569 Labels are limited to 128 unicode characters.
8570 XFS The label is limited to 12 bytes. The filesystem must not be
8572 mounted when trying to set the label.
8573 btrfs
8575 The label is limited to 255 bytes and some characters are not
8576 allowed. Setting the label on a btrfs subvolume will set the label
8577 on its parent filesystem. The filesystem must not be mounted when
8578 trying to set the label.
8579 fat The label is limited to 11 bytes.
8581 swap
8583 The label is limited to 16 bytes.
8584 If there is no support for changing the label for the type of the
8586 specified filesystem, set_label will fail and set errno as ENOTSUP.
8587 To read the label on a filesystem, call "vfs-label".
8589 set-libvirt-requested-credential
8591 set-libvirt-requested-credential index cred
8592 After requesting the "index"'th credential from the user, call this
8594 function to pass the answer back to libvirt.
8595 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8597 example code.
8598 set-libvirt-supported-credentials
8600 set-libvirt-supported-credentials 'creds ...'
8601 Call this function before setting an event handler for
8603 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
8604 that the program knows how to process.
8605 The "creds" list must be a non-empty list of strings. Possible strings
8607 are:
8608 "username"
8610 "authname"
8611 "language"
8612 "cnonce"
8613 "passphrase"
8614 "echoprompt"
8615 "noechoprompt"
8616 "realm"
8617 "external"
8618 See libvirt documentation for the meaning of these credential types.
8620 See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8622 example code.
8623 set-memsize
8625 memsize
8626 set-memsize memsize
8627 This sets the memory size in megabytes allocated to the hypervisor.
8629 This only has any effect if called before "launch".
8630 You can also change this by setting the environment variable
8632 "LIBGUESTFS_MEMSIZE" before the handle is created.
8633 For more information on the architecture of libguestfs, see guestfs(3).
8635 set-network
8637 network
8638 set-network true|false
8639 If "network" is true, then the network is enabled in the libguestfs
8641 appliance. The default is false.
8642 This affects whether commands are able to access the network (see
8644 "RUNNING COMMANDS" in guestfs(3)).
8645 You must call this before calling "launch", otherwise it has no effect.
8647 set-path
8649 path
8650 set-path searchpath
8651 Set the path that libguestfs searches for kernel and initrd.img.
8653 The default is "$libdir/guestfs" unless overridden by setting
8655 "LIBGUESTFS_PATH" environment variable.
8656 Setting "path" to "NULL" restores the default path.
8658 set-pgroup
8660 pgroup
8661 set-pgroup true|false
8662 If "pgroup" is true, child processes are placed into their own process
8664 group.
8665 The practical upshot of this is that signals like "SIGINT" (from users
8667 pressing "^C") won't be received by the child process.
8668 The default for this flag is false, because usually you want "^C" to
8670 kill the subprocess. Guestfish sets this flag to true when used
8671 interactively, so that "^C" can cancel long-running commands gracefully
8672 (see "user-cancel").
8673 set-program
8675 program
8676 set-program program
8677 Set the program name. This is an informative string which the main
8679 program may optionally set in the handle.
8680 When the handle is created, the program name in the handle is set to
8682 the basename from "argv[0]". The program name can never be "NULL".
8683 set-qemu
8685 qemu
8686 set-qemu hv
8687 Set the hypervisor binary (usually qemu) that we will use.
8689 The default is chosen when the library was compiled by the configure
8691 script.
8692 You can also override this by setting the "LIBGUESTFS_HV" environment
8694 variable.
8695 Setting "hv" to "NULL" restores the default qemu binary.
8697 Note that you should call this function as early as possible after
8699 creating the handle. This is because some pre-launch operations depend
8700 on testing qemu features (by running "qemu -help"). If the qemu binary
8701 changes, we don't retest features, and so you might see inconsistent
8702 results. Using the environment variable "LIBGUESTFS_HV" is safest of
8703 all since that picks the qemu binary at the same time as the handle is
8704 created.
8705 This function is deprecated. In new code, use the "set-hv" call
8707 instead.
8708 Deprecated functions will not be removed from the API, but the fact
8710 that they are deprecated indicates that there are problems with correct
8711 use of these functions.
8712 set-recovery-proc
8714 recovery-proc
8715 set-recovery-proc true|false
8716 If this is called with the parameter "false" then "launch" does not
8718 create a recovery process. The purpose of the recovery process is to
8719 stop runaway hypervisor processes in the case where the main program
8720 aborts abruptly.
8721 This only has any effect if called before "launch", and the default is
8723 true.
8724 About the only time when you would want to disable this is if the main
8726 process will fork itself into the background ("daemonize" itself). In
8727 this case the recovery process thinks that the main program has
8728 disappeared and so kills the hypervisor, which is not very helpful.
8729 set-selinux
8731 selinux
8732 set-selinux true|false
8733 This sets the selinux flag that is passed to the appliance at boot
8735 time. The default is "selinux=0" (disabled).
8736 Note that if SELinux is enabled, it is always in Permissive mode
8738 ("enforcing=0").
8739 For more information on the architecture of libguestfs, see guestfs(3).
8741 This function is deprecated. In new code, use the "selinux-relabel"
8743 call instead.
8744 Deprecated functions will not be removed from the API, but the fact
8746 that they are deprecated indicates that there are problems with correct
8747 use of these functions.
8748 set-smp
8750 smp
8751 set-smp smp
8752 Change the number of virtual CPUs assigned to the appliance. The
8754 default is 1. Increasing this may improve performance, though often it
8755 has no effect.
8756 This function must be called before "launch".
8758 set-tmpdir
8760 tmpdir
8761 set-tmpdir tmpdir
8762 Set the directory used by the handle to store temporary files.
8764 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
8766 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
8767 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
8768 default.
8769 set-trace
8771 trace
8772 set-trace true|false
8773 If the command trace flag is set to 1, then libguestfs calls,
8775 parameters and return values are traced.
8776 If you want to trace C API calls into libguestfs (and other libraries)
8778 then possibly a better way is to use the external ltrace(1) command.
8779 Command traces are disabled unless the environment variable
8781 "LIBGUESTFS_TRACE" is defined and set to 1.
8782 Trace messages are normally sent to "stderr", unless you register a
8784 callback to send them somewhere else (see "set-event-callback").
8785 set-uuid
8787 set-uuid device uuid
8788 Set the filesystem UUID on "device" to "uuid". If this fails and the
8790 errno is ENOTSUP, means that there is no support for changing the UUID
8791 for the type of the specified filesystem.
8792 Only some filesystem types support setting UUIDs.
8794 To read the UUID on a filesystem, call "vfs-uuid".
8796 set-uuid-random
8798 set-uuid-random device
8799 Set the filesystem UUID on "device" to a random UUID. If this fails
8801 and the errno is ENOTSUP, means that there is no support for changing
8802 the UUID for the type of the specified filesystem.
8803 Only some filesystem types support setting UUIDs.
8805 To read the UUID on a filesystem, call "vfs-uuid".
8807 set-verbose
8809 verbose
8810 set-verbose true|false
8811 If "verbose" is true, this turns on verbose messages.
8813 Verbose messages are disabled unless the environment variable
8815 "LIBGUESTFS_DEBUG" is defined and set to 1.
8816 Verbose messages are normally sent to "stderr", unless you register a
8818 callback to send them somewhere else (see "set-event-callback").
8819 setcon
8821 setcon context
8822 This sets the SELinux security context of the daemon to the string
8824 "context".
8825 See the documentation about SELINUX in guestfs(3).
8827 This function is deprecated. In new code, use the "selinux-relabel"
8829 call instead.
8830 Deprecated functions will not be removed from the API, but the fact
8832 that they are deprecated indicates that there are problems with correct
8833 use of these functions.
8834 This command depends on the feature "selinux". See also "feature-
8836 available".
8837 setxattr
8839 setxattr xattr val vallen path
8840 This call sets the extended attribute named "xattr" of the file "path"
8842 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
8843 data.
8844 See also: "lsetxattr", attr(5).
8846 This command depends on the feature "linuxxattrs". See also "feature-
8848 available".
8849 sfdisk
8851 sfdisk device cyls heads sectors 'lines ...'
8852 This is a direct interface to the sfdisk(8) program for creating
8854 partitions on block devices.
8855 "device" should be a block device, for example /dev/sda.
8857 "cyls", "heads" and "sectors" are the number of cylinders, heads and
8859 sectors on the device, which are passed directly to sfdisk as the -C,
8860 -H and -S parameters. If you pass 0 for any of these, then the
8861 corresponding parameter is omitted. Usually for ‘large’ disks, you can
8862 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
8863 rather, the kernel) cannot work out the right geometry and you will
8864 need to tell it.
8865 "lines" is a list of lines that we feed to "sfdisk". For more
8867 information refer to the sfdisk(8) manpage.
8868 To create a single partition occupying the whole disk, you would pass
8870 "lines" as a single element list, when the single element being the
8871 string "," (comma).
8872 See also: "sfdisk-l", "sfdisk-N", "part-init"
8874 This function is deprecated. In new code, use the "part-add" call
8876 instead.
8877 Deprecated functions will not be removed from the API, but the fact
8879 that they are deprecated indicates that there are problems with correct
8880 use of these functions.
8881 sfdiskM
8883 sfdiskM device 'lines ...'
8884 This is a simplified interface to the "sfdisk" command, where partition
8886 sizes are specified in megabytes only (rounded to the nearest cylinder)
8887 and you don't need to specify the cyls, heads and sectors parameters
8888 which were rarely if ever used anyway.
8889 See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
8891 This function is deprecated. In new code, use the "part-add" call
8893 instead.
8894 Deprecated functions will not be removed from the API, but the fact
8896 that they are deprecated indicates that there are problems with correct
8897 use of these functions.
8898 sfdisk-N
8900 sfdisk-N device partnum cyls heads sectors line
8901 This runs sfdisk(8) option to modify just the single partition "n"
8903 (note: "n" counts from 1).
8904 For other parameters, see "sfdisk". You should usually pass 0 for the
8906 cyls/heads/sectors parameters.
8907 See also: "part-add"
8909 This function is deprecated. In new code, use the "part-add" call
8911 instead.
8912 Deprecated functions will not be removed from the API, but the fact
8914 that they are deprecated indicates that there are problems with correct
8915 use of these functions.
8916 sfdisk-disk-geometry
8918 sfdisk-disk-geometry device
8919 This displays the disk geometry of "device" read from the partition
8921 table. Especially in the case where the underlying block device has
8922 been resized, this can be different from the kernel’s idea of the
8923 geometry (see "sfdisk-kernel-geometry").
8924 The result is in human-readable format, and not designed to be parsed.
8926 sfdisk-kernel-geometry
8928 sfdisk-kernel-geometry device
8929 This displays the kernel’s idea of the geometry of "device".
8931 The result is in human-readable format, and not designed to be parsed.
8933 sfdisk-l
8935 sfdisk-l device
8936 This displays the partition table on "device", in the human-readable
8938 output of the sfdisk(8) command. It is not intended to be parsed.
8939 See also: "part-list"
8941 This function is deprecated. In new code, use the "part-list" call
8943 instead.
8944 Deprecated functions will not be removed from the API, but the fact
8946 that they are deprecated indicates that there are problems with correct
8947 use of these functions.
8948 sh
8950 sh command
8951 This call runs a command from the guest filesystem via the guest’s
8953 /bin/sh.
8954 This is like "command", but passes the command to:
8956 /bin/sh -c "command"
8958 Depending on the guest’s shell, this usually results in wildcards being
8960 expanded, shell expressions being interpolated and so on.
8961 All the provisos about "command" apply to this call.
8963 sh-lines
8965 sh-lines command
8966 This is the same as "sh", but splits the result into a list of lines.
8968 See also: "command-lines"
8970 shutdown
8972 shutdown
8973 This is the opposite of "launch". It performs an orderly shutdown of
8975 the backend process(es). If the autosync flag is set (which is the
8976 default) then the disk image is synchronized.
8977 If the subprocess exits with an error then this function will return an
8979 error, which should not be ignored (it may indicate that the disk image
8980 could not be written out properly).
8981 It is safe to call this multiple times. Extra calls are ignored.
8983 This call does not close or free up the handle. You still need to call
8985 "close" afterwards.
8986 "close" will call this if you don't do it explicitly, but note that any
8988 errors are ignored in that case.
8989 sleep
8991 sleep secs
8992 Sleep for "secs" seconds.
8994 stat
8996 stat path
8997 Returns file information for the given "path".
8999 This is the same as the stat(2) system call.
9001 This function is deprecated. In new code, use the "statns" call
9003 instead.
9004 Deprecated functions will not be removed from the API, but the fact
9006 that they are deprecated indicates that there are problems with correct
9007 use of these functions.
9008 statns
9010 statns path
9011 Returns file information for the given "path".
9013 This is the same as the stat(2) system call.
9015 statvfs
9017 statvfs path
9018 Returns file system statistics for any mounted file system. "path"
9020 should be a file or directory in the mounted file system (typically it
9021 is the mount point itself, but it doesn't need to be).
9022 This is the same as the statvfs(2) system call.
9024 strings
9026 strings path
9027 This runs the strings(1) command on a file and returns the list of
9029 printable strings found.
9030 The "strings" command has, in the past, had problems with parsing
9032 untrusted files. These are mitigated in the current version of
9033 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9034 Because of the message protocol, there is a transfer limit of somewhere
9036 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9037 strings-e
9039 strings-e encoding path
9040 This is like the "strings" command, but allows you to specify the
9042 encoding of strings that are looked for in the source file "path".
9043 Allowed encodings are:
9045 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
9047 parts of ISO-8859-X (this is what "strings" uses).
9048 S Single 8-bit-byte characters.
9050 b 16-bit big endian strings such as those encoded in UTF-16BE or
9052 UCS-2BE.
9053 l (lower case letter L)
9055 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
9056 for examining binaries in Windows guests.
9057 B 32-bit big endian such as UCS-4BE.
9059 L 32-bit little endian such as UCS-4LE.
9061 The returned strings are transcoded to UTF-8.
9063 The "strings" command has, in the past, had problems with parsing
9065 untrusted files. These are mitigated in the current version of
9066 libguestfs, but see "CVE-2014-8484" in guestfs(3).
9067 Because of the message protocol, there is a transfer limit of somewhere
9069 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9070 swapoff-device
9072 swapoff-device device
9073 This command disables the libguestfs appliance swap device or partition
9075 named "device". See "swapon-device".
9076 swapoff-file
9078 swapoff-file file
9079 This command disables the libguestfs appliance swap on file.
9081 swapoff-label
9083 swapoff-label label
9084 This command disables the libguestfs appliance swap on labeled swap
9086 partition.
9087 swapoff-uuid
9089 swapoff-uuid uuid
9090 This command disables the libguestfs appliance swap partition with the
9092 given UUID.
9093 This command depends on the feature "linuxfsuuid". See also "feature-
9095 available".
9096 swapon-device
9098 swapon-device device
9099 This command enables the libguestfs appliance to use the swap device or
9101 partition named "device". The increased memory is made available for
9102 all commands, for example those run using "command" or "sh".
9103 Note that you should not swap to existing guest swap partitions unless
9105 you know what you are doing. They may contain hibernation information,
9106 or other information that the guest doesn't want you to trash. You
9107 also risk leaking information about the host to the guest this way.
9108 Instead, attach a new host device to the guest and swap on that.
9109 swapon-file
9111 swapon-file file
9112 This command enables swap to a file. See "swapon-device" for other
9114 notes.
9115 swapon-label
9117 swapon-label label
9118 This command enables swap to a labeled swap partition. See "swapon-
9120 device" for other notes.
9121 swapon-uuid
9123 swapon-uuid uuid
9124 This command enables swap to a swap partition with the given UUID. See
9126 "swapon-device" for other notes.
9127 This command depends on the feature "linuxfsuuid". See also "feature-
9129 available".
9130 sync
9132 sync
9133 This syncs the disk, so that any writes are flushed through to the
9135 underlying disk image.
9136 You should always call this if you have modified a disk image, before
9138 closing the handle.
9139 syslinux
9141 syslinux device [directory:..]
9142 Install the SYSLINUX bootloader on "device".
9144 The device parameter must be either a whole disk formatted as a FAT
9146 filesystem, or a partition formatted as a FAT filesystem. In the
9147 latter case, the partition should be marked as "active" ("part-set-
9148 bootable") and a Master Boot Record must be installed (eg. using
9149 "pwrite-device") on the first sector of the whole disk. The SYSLINUX
9150 package comes with some suitable Master Boot Records. See the
9151 syslinux(1) man page for further information.
9152 The optional arguments are:
9154 directory
9156 Install SYSLINUX in the named subdirectory, instead of in the root
9157 directory of the FAT filesystem.
9158 Additional configuration can be supplied to SYSLINUX by placing a file
9160 called syslinux.cfg on the FAT filesystem, either in the root
9161 directory, or under directory if that optional argument is being used.
9162 For further information about the contents of this file, see
9163 syslinux(1).
9164 See also "extlinux".
9166 This command has one or more optional arguments. See "OPTIONAL
9168 ARGUMENTS".
9169 This command depends on the feature "syslinux". See also "feature-
9171 available".
9172 tail
9174 tail path
9175 This command returns up to the last 10 lines of a file as a list of
9177 strings.
9178 Because of the message protocol, there is a transfer limit of somewhere
9180 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9181 tail-n
9183 tail-n nrlines path
9184 If the parameter "nrlines" is a positive number, this returns the last
9186 "nrlines" lines of the file "path".
9187 If the parameter "nrlines" is a negative number, this returns lines
9189 from the file "path", starting with the "-nrlines"th line.
9190 If the parameter "nrlines" is zero, this returns an empty list.
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 tar-in
9197 tar-in-opts
9198 tar-in (tarfile|-) directory [compress:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9199 This command uploads and unpacks local file "tarfile" into directory.
9201 The optional "compress" flag controls compression. If not given, then
9203 the input should be an uncompressed tar file. Otherwise one of the
9204 following strings may be given to select the compression type of the
9205 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9206 all builds of libguestfs will support all of these compression types).
9207 The other optional arguments are:
9209 "xattrs"
9211 If set to true, extended attributes are restored from the tar file.
9212 "selinux"
9214 If set to true, SELinux contexts are restored from the tar file.
9215 "acls"
9217 If set to true, POSIX ACLs are restored from the tar file.
9218 Use "-" instead of a filename to read/write from stdin/stdout.
9220 This command has one or more optional arguments. See "OPTIONAL
9222 ARGUMENTS".
9223 tar-out
9225 tar-out-opts
9226 tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9227 This command packs the contents of directory and downloads it to local
9229 file "tarfile".
9230 The optional "compress" flag controls compression. If not given, then
9232 the output will be an uncompressed tar file. Otherwise one of the
9233 following strings may be given to select the compression type of the
9234 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
9235 all builds of libguestfs will support all of these compression types).
9236 The other optional arguments are:
9238 "excludes"
9240 A list of wildcards. Files are excluded if they match any of the
9241 wildcards.
9242 "numericowner"
9244 If set to true, the output tar file will contain UID/GID numbers
9245 instead of user/group names.
9246 "xattrs"
9248 If set to true, extended attributes are saved in the output tar.
9249 "selinux"
9251 If set to true, SELinux contexts are saved in the output tar.
9252 "acls"
9254 If set to true, POSIX ACLs are saved in the output tar.
9255 Use "-" instead of a filename to read/write from stdin/stdout.
9257 This command has one or more optional arguments. See "OPTIONAL
9259 ARGUMENTS".
9260 tgz-in
9262 tgz-in (tarball|-) directory
9263 This command uploads and unpacks local file "tarball" (a gzip
9265 compressed tar file) into directory.
9266 Use "-" instead of a filename to read/write from stdin/stdout.
9268 This function is deprecated. In new code, use the "tar-in" call
9270 instead.
9271 Deprecated functions will not be removed from the API, but the fact
9273 that they are deprecated indicates that there are problems with correct
9274 use of these functions.
9275 tgz-out
9277 tgz-out directory (tarball|-)
9278 This command packs the contents of directory and downloads it to local
9280 file "tarball".
9281 Use "-" instead of a filename to read/write from stdin/stdout.
9283 This function is deprecated. In new code, use the "tar-out" call
9285 instead.
9286 Deprecated functions will not be removed from the API, but the fact
9288 that they are deprecated indicates that there are problems with correct
9289 use of these functions.
9290 touch
9292 touch path
9293 Touch acts like the touch(1) command. It can be used to update the
9295 timestamps on a file, or, if the file does not exist, to create a new
9296 zero-length file.
9297 This command only works on regular files, and will fail on other file
9299 types such as directories, symbolic links, block special etc.
9300 truncate
9302 truncate path
9303 This command truncates "path" to a zero-length file. The file must
9305 exist already.
9306 truncate-size
9308 truncate-size path size
9309 This command truncates "path" to size "size" bytes. The file must
9311 exist already.
9312 If the current file size is less than "size" then the file is extended
9314 to the required size with zero bytes. This creates a sparse file (ie.
9315 disk blocks are not allocated for the file until you write to it). To
9316 create a non-sparse file of zeroes, use "fallocate64" instead.
9317 tune2fs
9319 tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
9320 This call allows you to adjust various filesystem parameters of an
9322 ext2/ext3/ext4 filesystem called "device".
9323 The optional parameters are:
9325 "force"
9327 Force tune2fs to complete the operation even in the face of errors.
9328 This is the same as the tune2fs "-f" option.
9329 "maxmountcount"
9331 Set the number of mounts after which the filesystem is checked by
9332 e2fsck(8). If this is 0 then the number of mounts is disregarded.
9333 This is the same as the tune2fs "-c" option.
9334 "mountcount"
9336 Set the number of times the filesystem has been mounted. This is
9337 the same as the tune2fs "-C" option.
9338 "errorbehavior"
9340 Change the behavior of the kernel code when errors are detected.
9341 Possible values currently are: "continue", "remount-ro", "panic".
9342 In practice these options don't really make any difference,
9343 particularly for write errors.
9344 This is the same as the tune2fs "-e" option.
9346 "group"
9348 Set the group which can use reserved filesystem blocks. This is
9349 the same as the tune2fs "-g" option except that it can only be
9350 specified as a number.
9351 "intervalbetweenchecks"
9353 Adjust the maximal time between two filesystem checks (in seconds).
9354 If the option is passed as 0 then time-dependent checking is
9355 disabled.
9356 This is the same as the tune2fs "-i" option.
9358 "reservedblockspercentage"
9360 Set the percentage of the filesystem which may only be allocated by
9361 privileged processes. This is the same as the tune2fs "-m" option.
9362 "lastmounteddirectory"
9364 Set the last mounted directory. This is the same as the tune2fs
9365 "-M" option.
9366 "reservedblockscount" Set the number of reserved filesystem blocks.
9368 This is the same as the tune2fs "-r" option.
9369 "user"
9370 Set the user who can use the reserved filesystem blocks. This is
9371 the same as the tune2fs "-u" option except that it can only be
9372 specified as a number.
9373 To get the current values of filesystem parameters, see "tune2fs-l".
9375 For precise details of how tune2fs works, see the tune2fs(8) man page.
9376 This command has one or more optional arguments. See "OPTIONAL
9378 ARGUMENTS".
9379 tune2fs-l
9381 tune2fs-l device
9382 This returns the contents of the ext2, ext3 or ext4 filesystem
9384 superblock on "device".
9385 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
9387 for more details. The list of fields returned isn't clearly defined,
9388 and depends on both the version of "tune2fs" that libguestfs was built
9389 against, and the filesystem itself.
9390 txz-in
9392 txz-in (tarball|-) directory
9393 This command uploads and unpacks local file "tarball" (an xz compressed
9395 tar file) into directory.
9396 Use "-" instead of a filename to read/write from stdin/stdout.
9398 This function is deprecated. In new code, use the "tar-in" call
9400 instead.
9401 Deprecated functions will not be removed from the API, but the fact
9403 that they are deprecated indicates that there are problems with correct
9404 use of these functions.
9405 This command depends on the feature "xz". See also "feature-
9407 available".
9408 txz-out
9410 txz-out directory (tarball|-)
9411 This command packs the contents of directory and downloads it to local
9413 file "tarball" (as an xz compressed tar archive).
9414 Use "-" instead of a filename to read/write from stdin/stdout.
9416 This function is deprecated. In new code, use the "tar-out" call
9418 instead.
9419 Deprecated functions will not be removed from the API, but the fact
9421 that they are deprecated indicates that there are problems with correct
9422 use of these functions.
9423 This command depends on the feature "xz". See also "feature-
9425 available".
9426 umask
9428 umask mask
9429 This function sets the mask used for creating new files and device
9431 nodes to "mask & 0777".
9432 Typical umask values would be 022 which creates new files with
9434 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
9435 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
9436 The default umask is 022. This is important because it means that
9438 directories and device nodes will be created with 0644 or 0755 mode
9439 even if you specify 0777.
9440 See also "get-umask", umask(2), "mknod", "mkdir".
9442 This call returns the previous umask.
9444 umount
9446 unmount
9447 umount-opts
9448 umount pathordevice [force:true|false] [lazyunmount:true|false]
9449 This unmounts the given filesystem. The filesystem may be specified
9451 either by its mountpoint (path) or the device which contains the
9452 filesystem.
9453 This command has one or more optional arguments. See "OPTIONAL
9455 ARGUMENTS".
9456 umount-all
9458 unmount-all
9459 umount-all
9460 This unmounts all mounted filesystems.
9462 Some internal mounts are not unmounted by this call.
9464 umount-local
9466 umount-local [retry:true|false]
9467 If libguestfs is exporting the filesystem on a local mountpoint, then
9469 this unmounts it.
9470 See "MOUNT LOCAL" in guestfs(3) for full documentation.
9472 This command has one or more optional arguments. See "OPTIONAL
9474 ARGUMENTS".
9475 upload
9477 upload (filename|-) remotefilename
9478 Upload local file filename to remotefilename on the filesystem.
9480 filename can also be a named pipe.
9482 See also "download".
9484 Use "-" instead of a filename to read/write from stdin/stdout.
9486 upload-offset
9488 upload-offset (filename|-) remotefilename offset
9489 Upload local file filename to remotefilename on the filesystem.
9491 remotefilename is overwritten starting at the byte "offset" specified.
9493 The intention is to overwrite parts of existing files or devices,
9494 although if a non-existent file is specified then it is created with a
9495 "hole" before "offset". The size of the data written is implicit in
9496 the size of the source filename.
9497 Note that there is no limit on the amount of data that can be uploaded
9499 with this call, unlike with "pwrite", and this call always writes the
9500 full amount unless an error occurs.
9501 See also "upload", "pwrite".
9503 Use "-" instead of a filename to read/write from stdin/stdout.
9505 user-cancel
9507 user-cancel
9508 This function cancels the current upload or download operation.
9510 Unlike most other libguestfs calls, this function is signal safe and
9512 thread safe. You can call it from a signal handler or from another
9513 thread, without needing to do any locking.
9514 The transfer that was in progress (if there is one) will stop shortly
9516 afterwards, and will return an error. The errno (see
9517 "guestfs_last_errno") is set to "EINTR", so you can test for this to
9518 find out if the operation was cancelled or failed because of another
9519 error.
9520 No cleanup is performed: for example, if a file was being uploaded then
9522 after cancellation there may be a partially uploaded file. It is the
9523 caller’s responsibility to clean up if necessary.
9524 There are two common places that you might call "user-cancel":
9526 In an interactive text-based program, you might call it from a "SIGINT"
9528 signal handler so that pressing "^C" cancels the current operation.
9529 (You also need to call "guestfs_set_pgroup" so that child processes
9530 don't receive the "^C" signal).
9531 In a graphical program, when the main thread is displaying a progress
9533 bar with a cancel button, wire up the cancel button to call this
9534 function.
9535 utimens
9537 utimens path atsecs atnsecs mtsecs mtnsecs
9538 This command sets the timestamps of a file with nanosecond precision.
9540 "atsecs, atnsecs" are the last access time (atime) in secs and
9542 nanoseconds from the epoch.
9543 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
9545 nanoseconds from the epoch.
9546 If the *nsecs field contains the special value "-1" then the
9548 corresponding timestamp is set to the current time. (The *secs field
9549 is ignored in this case).
9550 If the *nsecs field contains the special value "-2" then the
9552 corresponding timestamp is left unchanged. (The *secs field is ignored
9553 in this case).
9554 utsname
9556 utsname
9557 This returns the kernel version of the appliance, where this is
9559 available. This information is only useful for debugging. Nothing in
9560 the returned structure is defined by the API.
9561 version
9563 version
9564 Return the libguestfs version number that the program is linked
9566 against.
9567 Note that because of dynamic linking this is not necessarily the
9569 version of libguestfs that you compiled against. You can compile the
9570 program, and then at runtime dynamically link against a completely
9571 different libguestfs.so library.
9572 This call was added in version 1.0.58. In previous versions of
9574 libguestfs there was no way to get the version number. From C code you
9575 can use dynamic linker functions to find out if this symbol exists (if
9576 it doesn't, then it’s an earlier version).
9577 The call returns a structure with four elements. The first three
9579 ("major", "minor" and "release") are numbers and correspond to the
9580 usual version triplet. The fourth element ("extra") is a string and is
9581 normally empty, but may be used for distro-specific information.
9582 To construct the original version string:
9584 "$major.$minor.$release$extra"
9585 See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
9587 Note: Don't use this call to test for availability of features. In
9589 enterprise distributions we backport features from later versions into
9590 earlier versions, making this an unreliable way to test for features.
9591 Use "available" or "feature-available" instead.
9592 vfs-label
9594 vfs-label mountable
9595 This returns the label of the filesystem on "mountable".
9597 If the filesystem is unlabeled, this returns the empty string.
9599 To find a filesystem from the label, use "findfs-label".
9601 vfs-minimum-size
9603 vfs-minimum-size mountable
9604 Get the minimum size of filesystem in bytes. This is the minimum
9606 possible size for filesystem shrinking.
9607 If getting minimum size of specified filesystem is not supported, this
9609 will fail and set errno as ENOTSUP.
9610 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
9612 vfs-type
9614 vfs-type mountable
9615 This command gets the filesystem type corresponding to the filesystem
9617 on "mountable".
9618 For most filesystems, the result is the name of the Linux VFS module
9620 which would be used to mount this filesystem if you mounted it without
9621 specifying the filesystem type. For example a string such as "ext3" or
9622 "ntfs".
9623 vfs-uuid
9625 get-uuid
9626 vfs-uuid mountable
9627 This returns the filesystem UUID of the filesystem on "mountable".
9629 If the filesystem does not have a UUID, this returns the empty string.
9631 To find a filesystem from the UUID, use "findfs-uuid".
9633 vg-activate
9635 vg-activate true|false 'volgroups ...'
9636 This command activates or (if "activate" is false) deactivates all
9638 logical volumes in the listed volume groups "volgroups".
9639 This command is the same as running "vgchange -a y|n volgroups..."
9641 Note that if "volgroups" is an empty list then all volume groups are
9643 activated or deactivated.
9644 This command depends on the feature "lvm2". See also "feature-
9646 available".
9647 vg-activate-all
9649 vg-activate-all true|false
9650 This command activates or (if "activate" is false) deactivates all
9652 logical volumes in all volume groups.
9653 This command is the same as running "vgchange -a y|n"
9655 This command depends on the feature "lvm2". See also "feature-
9657 available".
9658 vgchange-uuid
9660 vgchange-uuid vg
9661 Generate a new random UUID for the volume group "vg".
9663 This command depends on the feature "lvm2". See also "feature-
9665 available".
9666 vgchange-uuid-all
9668 vgchange-uuid-all
9669 Generate new random UUIDs for all volume groups.
9671 This command depends on the feature "lvm2". See also "feature-
9673 available".
9674 vgcreate
9676 vgcreate volgroup 'physvols ...'
9677 This creates an LVM volume group called "volgroup" from the non-empty
9679 list of physical volumes "physvols".
9680 This command depends on the feature "lvm2". See also "feature-
9682 available".
9683 vglvuuids
9685 vglvuuids vgname
9686 Given a VG called "vgname", this returns the UUIDs of all the logical
9688 volumes created in this volume group.
9689 You can use this along with "lvs" and "lvuuid" calls to associate
9691 logical volumes and volume groups.
9692 See also "vgpvuuids".
9694 vgmeta
9696 vgmeta vgname
9697 "vgname" is an LVM volume group. This command examines the volume
9699 group and returns its metadata.
9700 Note that the metadata is an internal structure used by LVM, subject to
9702 change at any time, and is provided for information only.
9703 This command depends on the feature "lvm2". See also "feature-
9705 available".
9706 vgpvuuids
9708 vgpvuuids vgname
9709 Given a VG called "vgname", this returns the UUIDs of all the physical
9711 volumes that this volume group resides on.
9712 You can use this along with "pvs" and "pvuuid" calls to associate
9714 physical volumes and volume groups.
9715 See also "vglvuuids".
9717 vgremove
9719 vgremove vgname
9720 Remove an LVM volume group "vgname", (for example "VG").
9722 This also forcibly removes all logical volumes in the volume group (if
9724 any).
9725 This command depends on the feature "lvm2". See also "feature-
9727 available".
9728 vgrename
9730 vgrename volgroup newvolgroup
9731 Rename a volume group "volgroup" with the new name "newvolgroup".
9733 vgs
9735 vgs
9736 List all the volumes groups detected. This is the equivalent of the
9738 vgs(8) command.
9739 This returns a list of just the volume group names that were detected
9741 (eg. "VolGroup00").
9742 See also "vgs-full".
9744 This command depends on the feature "lvm2". See also "feature-
9746 available".
9747 vgs-full
9749 vgs-full
9750 List all the volumes groups detected. This is the equivalent of the
9752 vgs(8) command. The "full" version includes all fields.
9753 This command depends on the feature "lvm2". See also "feature-
9755 available".
9756 vgscan
9758 vgscan
9759 This rescans all block devices and rebuilds the list of LVM physical
9761 volumes, volume groups and logical volumes.
9762 This function is deprecated. In new code, use the "lvm-scan" call
9764 instead.
9765 Deprecated functions will not be removed from the API, but the fact
9767 that they are deprecated indicates that there are problems with correct
9768 use of these functions.
9769 vguuid
9771 vguuid vgname
9772 This command returns the UUID of the LVM VG named "vgname".
9774 wc-c
9776 wc-c path
9777 This command counts the characters in a file, using the "wc -c"
9779 external command.
9780 wc-l
9782 wc-l path
9783 This command counts the lines in a file, using the "wc -l" external
9785 command.
9786 wc-w
9788 wc-w path
9789 This command counts the words in a file, using the "wc -w" external
9791 command.
9792 wipefs
9794 wipefs device
9795 This command erases filesystem or RAID signatures from the specified
9797 "device" to make the filesystem invisible to libblkid.
9798 This does not erase the filesystem itself nor any other data from the
9800 "device".
9801 Compare with "zero" which zeroes the first few blocks of a device.
9803 This command depends on the feature "wipefs". See also "feature-
9805 available".
9806 write
9808 write path content
9809 This call creates a file called "path". The content of the file is the
9811 string "content" (which can contain any 8 bit data).
9812 See also "write-append".
9814 write-append
9816 write-append path content
9817 This call appends "content" to the end of file "path". If "path" does
9819 not exist, then a new file is created.
9820 See also "write".
9822 write-file
9824 write-file path content size
9825 This call creates a file called "path". The contents of the file is
9827 the string "content" (which can contain any 8 bit data), with length
9828 "size".
9829 As a special case, if "size" is 0 then the length is calculated using
9831 "strlen" (so in this case the content cannot contain embedded ASCII
9832 NULs).
9833 NB. Owing to a bug, writing content containing ASCII NUL characters
9835 does not work, even if the length is specified.
9836 Because of the message protocol, there is a transfer limit of somewhere
9838 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9839 This function is deprecated. In new code, use the "write" call
9841 instead.
9842 Deprecated functions will not be removed from the API, but the fact
9844 that they are deprecated indicates that there are problems with correct
9845 use of these functions.
9846 xfs-admin
9848 xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
9849 Change the parameters of the XFS filesystem on "device".
9851 Devices that are mounted cannot be modified. Administrators must
9853 unmount filesystems before this call can modify parameters.
9854 Some of the parameters of a mounted filesystem can be examined and
9856 modified using the "xfs-info" and "xfs-growfs" calls.
9857 This command has one or more optional arguments. See "OPTIONAL
9859 ARGUMENTS".
9860 This command depends on the feature "xfs". See also "feature-
9862 available".
9863 xfs-growfs
9865 xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
9866 Grow the XFS filesystem mounted at "path".
9868 The returned struct contains geometry information. Missing fields are
9870 returned as "-1" (for numeric fields) or empty string.
9871 This command has one or more optional arguments. See "OPTIONAL
9873 ARGUMENTS".
9874 This command depends on the feature "xfs". See also "feature-
9876 available".
9877 xfs-info
9879 xfs-info pathordevice
9880 "pathordevice" is a mounted XFS filesystem or a device containing an
9882 XFS filesystem. This command returns the geometry of the filesystem.
9883 The returned struct contains geometry information. Missing fields are
9885 returned as "-1" (for numeric fields) or empty string.
9886 This command depends on the feature "xfs". See also "feature-
9888 available".
9889 xfs-repair
9891 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:..]
9892 Repair corrupt or damaged XFS filesystem on "device".
9894 The filesystem is specified using the "device" argument which should be
9896 the device name of the disk partition or volume containing the
9897 filesystem. If given the name of a block device, "xfs_repair" will
9898 attempt to find the raw device associated with the specified block
9899 device and will use the raw device instead.
9900 Regardless, the filesystem to be repaired must be unmounted, otherwise,
9902 the resulting filesystem may be inconsistent or corrupt.
9903 The returned status indicates whether filesystem corruption was
9905 detected (returns 1) or was not detected (returns 0).
9906 This command has one or more optional arguments. See "OPTIONAL
9908 ARGUMENTS".
9909 This command depends on the feature "xfs". See also "feature-
9911 available".
9912 yara-destroy
9914 yara-destroy
9915 Destroy previously loaded Yara rules in order to free libguestfs
9917 resources.
9918 This command depends on the feature "libyara". See also "feature-
9920 available".
9921 yara-load
9923 yara-load (filename|-)
9924 Upload a set of Yara rules from local file filename.
9926 Yara rules allow to categorize files based on textual or binary
9928 patterns within their content. See "yara-scan" to see how to scan
9929 files with the loaded rules.
9930 Rules can be in binary format, as when compiled with yarac command, or
9932 in source code format. In the latter case, the rules will be first
9933 compiled and then loaded.
9934 Rules in source code format cannot include external files. In such
9936 cases, it is recommended to compile them first.
9937 Previously loaded rules will be destroyed.
9939 Use "-" instead of a filename to read/write from stdin/stdout.
9941 This command depends on the feature "libyara". See also "feature-
9943 available".
9944 yara-scan
9946 yara-scan path
9947 Scan a file with the previously loaded Yara rules.
9949 For each matching rule, a "yara_detection" structure is returned.
9951 The "yara_detection" structure contains the following fields.
9953 "yara_name"
9955 Path of the file matching a Yara rule.
9956 "yara_rule"
9958 Identifier of the Yara rule which matched against the given file.
9959 This command depends on the feature "libyara". See also "feature-
9961 available".
9962 zegrep
9964 zegrep regex path
9965 This calls the external "zegrep" program and returns the matching
9967 lines.
9968 Because of the message protocol, there is a transfer limit of somewhere
9970 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9971 This function is deprecated. In new code, use the "grep" call instead.
9973 Deprecated functions will not be removed from the API, but the fact
9975 that they are deprecated indicates that there are problems with correct
9976 use of these functions.
9977 zegrepi
9979 zegrepi regex path
9980 This calls the external "zegrep -i" program and returns the matching
9982 lines.
9983 Because of the message protocol, there is a transfer limit of somewhere
9985 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
9986 This function is deprecated. In new code, use the "grep" call instead.
9988 Deprecated functions will not be removed from the API, but the fact
9990 that they are deprecated indicates that there are problems with correct
9991 use of these functions.
9992 zero
9994 zero device
9995 This command writes zeroes over the first few blocks of "device".
9997 How many blocks are zeroed isn't specified (but it’s not enough to
9999 securely wipe the device). It should be sufficient to remove any
10000 partition tables, filesystem superblocks and so on.
10001 If blocks are already zero, then this command avoids writing zeroes.
10003 This prevents the underlying device from becoming non-sparse or growing
10004 unnecessarily.
10005 See also: "zero-device", "scrub-device", "is-zero-device"
10007 zero-device
10009 zero-device device
10010 This command writes zeroes over the entire "device". Compare with
10012 "zero" which just zeroes the first few blocks of a device.
10013 If blocks are already zero, then this command avoids writing zeroes.
10015 This prevents the underlying device from becoming non-sparse or growing
10016 unnecessarily.
10017 zero-free-space
10019 zero-free-space directory
10020 Zero the free space in the filesystem mounted on directory. The
10022 filesystem must be mounted read-write.
10023 The filesystem contents are not affected, but any free space in the
10025 filesystem is freed.
10026 Free space is not "trimmed". You may want to call "fstrim" either as
10028 an alternative to this, or after calling this, depending on your
10029 requirements.
10030 zerofree
10032 zerofree device
10033 This runs the zerofree program on "device". This program claims to
10035 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
10036 it possible to compress the filesystem more effectively.
10037 You should not run this program if the filesystem is mounted.
10039 It is possible that using this program can damage the filesystem or
10041 data on the filesystem.
10042 This command depends on the feature "zerofree". See also "feature-
10044 available".
10045 zfgrep
10047 zfgrep pattern path
10048 This calls the external "zfgrep" program and returns the matching
10050 lines.
10051 Because of the message protocol, there is a transfer limit of somewhere
10053 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10054 This function is deprecated. In new code, use the "grep" call instead.
10056 Deprecated functions will not be removed from the API, but the fact
10058 that they are deprecated indicates that there are problems with correct
10059 use of these functions.
10060 zfgrepi
10062 zfgrepi pattern path
10063 This calls the external "zfgrep -i" program and returns the matching
10065 lines.
10066 Because of the message protocol, there is a transfer limit of somewhere
10068 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10069 This function is deprecated. In new code, use the "grep" call instead.
10071 Deprecated functions will not be removed from the API, but the fact
10073 that they are deprecated indicates that there are problems with correct
10074 use of these functions.
10075 zfile
10077 zfile meth path
10078 This command runs file after first decompressing "path" using "method".
10080 "method" must be one of "gzip", "compress" or "bzip2".
10082 Since 1.0.63, use "file" instead which can now process compressed
10084 files.
10085 This function is deprecated. In new code, use the "file" call instead.
10087 Deprecated functions will not be removed from the API, but the fact
10089 that they are deprecated indicates that there are problems with correct
10090 use of these functions.
10091 zgrep
10093 zgrep regex path
10094 This calls the external "zgrep" program and returns the matching lines.
10096 Because of the message protocol, there is a transfer limit of somewhere
10098 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10099 This function is deprecated. In new code, use the "grep" call instead.
10101 Deprecated functions will not be removed from the API, but the fact
10103 that they are deprecated indicates that there are problems with correct
10104 use of these functions.
10105 zgrepi
10107 zgrepi regex path
10108 This calls the external "zgrep -i" program and returns the matching
10110 lines.
10111 Because of the message protocol, there is a transfer limit of somewhere
10113 between 2MB and 4MB. See "PROTOCOL LIMITS" in guestfs(3).
10114 This function is deprecated. In new code, use the "grep" call instead.
10116 Deprecated functions will not be removed from the API, but the fact
10118 that they are deprecated indicates that there are problems with correct
10119 use of these functions.
10120
10122 guestfish returns 0 if the commands completed without error, or 1 if
10123 there was an error.
10124
10126 EDITOR
10127 The "edit" command uses $EDITOR as the editor. If not set, it uses
10128 "vi".
10129 GUESTFISH_DISPLAY_IMAGE
10131 The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
10132 images. If not set, it uses display(1).
10133 GUESTFISH_INIT
10135 Printed when guestfish starts. See "PROMPT".
10136 GUESTFISH_OUTPUT
10138 Printed before guestfish output. See "PROMPT".
10139 GUESTFISH_PID
10141 Used with the --remote option to specify the remote guestfish
10142 process to control. See section "REMOTE CONTROL GUESTFISH OVER A
10143 SOCKET".
10144 GUESTFISH_PS1
10146 Set the command prompt. See "PROMPT".
10147 GUESTFISH_RESTORE
10149 Printed before guestfish exits. See "PROMPT".
10150 HEXEDITOR
10152 The "hexedit" command uses $HEXEDITOR as the external hex editor.
10153 If not specified, the external hexedit(1) program is used.
10154 HOME
10156 If compiled with GNU readline support, various files in the home
10157 directory can be used. See "FILES".
10158 LIBGUESTFS_APPEND
10160 Pass additional options to the guest kernel.
10161 LIBGUESTFS_ATTACH_METHOD
10163 This is the old way to set "LIBGUESTFS_BACKEND".
10164 LIBGUESTFS_BACKEND
10166 Choose the default way to create the appliance. See
10167 "guestfs_set_backend" in guestfs(3).
10168 LIBGUESTFS_BACKEND_SETTINGS
10170 A colon-separated list of backend-specific settings. See "BACKEND"
10171 in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
10172 LIBGUESTFS_CACHEDIR
10174 The location where libguestfs will cache its appliance, when using
10175 a supermin appliance. The appliance is cached and shared between
10176 all handles which have the same effective user ID.
10177 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
10179 "TMPDIR" is not set, then /var/tmp is used.
10180 See also "LIBGUESTFS_TMPDIR", "set-cachedir".
10182 LIBGUESTFS_DEBUG
10184 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
10185 same effect as using the -v option.
10186 LIBGUESTFS_HV
10188 Set the default hypervisor (usually qemu) binary that libguestfs
10189 uses. If not set, then the qemu which was found at compile time by
10190 the configure script is used.
10191 LIBGUESTFS_MEMSIZE
10193 Set the memory allocated to the qemu process, in megabytes. For
10194 example:
10195 LIBGUESTFS_MEMSIZE=700
10197 LIBGUESTFS_PATH
10199 Set the path that guestfish uses to search for kernel and
10200 initrd.img. See the discussion of paths in guestfs(3).
10201 LIBGUESTFS_QEMU
10203 This is the old way to set "LIBGUESTFS_HV".
10204 LIBGUESTFS_TMPDIR
10206 The location where libguestfs will store temporary files used by
10207 each handle.
10208 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
10210 "TMPDIR" is not set, then /tmp is used.
10211 See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
10213 LIBGUESTFS_TRACE
10215 Set "LIBGUESTFS_TRACE=1" to enable command traces.
10216 PAGER
10218 The "more" command uses $PAGER as the pager. If not set, it uses
10219 "more".
10220 PATH
10222 Libguestfs and guestfish may run some external programs, and rely
10223 on $PATH being set to a reasonable value. If using the libvirt
10224 backend, libvirt will not work at all unless $PATH contains the
10225 path of qemu/KVM.
10226 SUPERMIN_KERNEL
10228 SUPERMIN_KERNEL_VERSION
10229 SUPERMIN_MODULES
10230 These three environment variables allow the kernel that libguestfs
10231 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
10232 set, then the most recent host kernel is chosen. For more
10233 information about kernel selection, see supermin(1).
10234 TMPDIR
10236 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
10237 XDG_RUNTIME_DIR
10239 This directory represents a user-specific directory for storing
10240 non-essential runtime files.
10241 If it is set, then is used to store temporary sockets. Otherwise,
10243 /tmp is used.
10244 See also "get-sockdir",
10246 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
10247
10249 $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
10250 $HOME/.libguestfs-tools.rc
10251 $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
10252 /etc/libguestfs-tools.conf
10253 This configuration file controls the default read-only or read-
10254 write mode (--ro or --rw).
10255 See libguestfs-tools.conf(5).
10257 $HOME/.guestfish
10259 If compiled with GNU readline support, then the command history is
10260 saved in this file.
10261 $HOME/.inputrc
10263 /etc/inputrc
10264 If compiled with GNU readline support, then these files can be used
10265 to configure readline. For further information, please see
10266 "INITIALIZATION FILE" in readline(3).
10267 To write rules which only apply to guestfish, use:
10269 $if guestfish
10271 ...
10272 $endif
10273 Variables that you can set in inputrc that change the behaviour of
10275 guestfish in useful ways include:
10276 completion-ignore-case (default: on)
10278 By default, guestfish will ignore case when tab-completing
10279 paths on the disk. Use:
10280 set completion-ignore-case off
10282 to make guestfish case sensitive.
10284 test1.img
10286 test2.img (etc)
10287 When using the -N or --new option, the prepared disk or filesystem
10288 will be created in the file test1.img in the current directory.
10289 The second use of -N will use test2.img and so on. Any existing
10290 file with the same name will be overwritten. You can use a
10291 different filename by using the "filename=" prefix.
10292
10294 guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
10295 virt-builder(1), virt-builder-repository(1), virt-cat(1),
10296 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
10297 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1),
10298 virt-list-filesystems(1), virt-list-partitions(1), virt-log(1),
10299 virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
10300 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
10301 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
10302 virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1),
10303 supermin(1).
10304
10306 Richard W.M. Jones ("rjones at redhat dot com")
10307
10309 Copyright (C) 2009-2019 Red Hat Inc.
10310
10312 This program is free software; you can redistribute it and/or modify it
10313 under the terms of the GNU General Public License as published by the
10314 Free Software Foundation; either version 2 of the License, or (at your
10315 option) any later version.
10316 This program is distributed in the hope that it will be useful, but
10318 WITHOUT ANY WARRANTY; without even the implied warranty of
10319 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10320 General Public License for more details.
10321 You should have received a copy of the GNU General Public License along
10323 with this program; if not, write to the Free Software Foundation, Inc.,
10324 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
10325
10327 To get a list of bugs against libguestfs, use this link:
10328 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
10329 To report a new bug against libguestfs, use this link:
10331 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
10332 When reporting a bug, please supply:
10334 · The version of libguestfs.
10336 · Where you got libguestfs (eg. which Linux distro, compiled from
10338 source, etc)
10339 · Describe the bug accurately and give a way to reproduce it.
10341 · Run libguestfs-test-tool(1) and paste the complete, unedited output
10343 into the bug report.
10344libguestfs-1.40.2 2019-02-07 guestfish(1)