1guestfish(1)                Virtualization Support                guestfish(1)
2
3
4

NAME

6       guestfish - the guest filesystem shell
7

SYNOPSIS

9        guestfish [--options] [commands]
10
11        guestfish
12
13        guestfish [--ro|--rw] -a disk.img
14
15        guestfish [--ro|--rw] -a disk.img -m dev[:mountpoint]
16
17        guestfish -d libvirt-domain
18
19        guestfish [--ro|--rw] -a disk.img -i
20
21        guestfish -d libvirt-domain -i
22

WARNING

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
30       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

DESCRIPTION

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
40       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

EXAMPLES

46   As an interactive shell
47        $ guestfish
48
49        Welcome to guestfish, the guest filesystem shell for
50        editing virtual machine filesystems.
51
52        Type: 'help' for a list of commands
53              'man' to read the manual
54              'quit' to quit the shell
55
56        ><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
69   From shell scripts
70       Create a new /etc/motd file in a guest or disk image:
71
72        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
79       List the LVM logical volumes in a disk image:
80
81        guestfish -a disk.img --ro <<_EOF_
82        run
83        lvs
84        _EOF_
85
86       List all the filesystems in a disk image:
87
88        guestfish -a disk.img --ro <<_EOF_
89        run
90        list-filesystems
91        _EOF_
92
93   On one command line
94       Update /etc/resolv.conf in a guest:
95
96        guestfish \
97          add disk.img : run : mount /dev/vg_guest/lv_root / : \
98          write /etc/resolv.conf "nameserver 1.2.3.4"
99
100       Edit /boot/grub/grub.conf interactively:
101
102        guestfish --rw --add disk.img \
103          --mount /dev/vg_guest/lv_root \
104          --mount /dev/sda1:/boot \
105          edit /boot/grub/grub.conf
106
107   Mount disks automatically
108       Use the -i option to automatically mount the disks from a virtual
109       machine:
110
111        guestfish --ro -a disk.img -i cat /etc/group
112
113        guestfish --ro -d libvirt-domain -i cat /etc/group
114
115       Another way to edit /boot/grub/grub.conf interactively is:
116
117        guestfish --rw -a disk.img -i edit /boot/grub/grub.conf
118
119   As a script interpreter
120       Create a 100MB disk containing an ext2-formatted partition:
121
122        #!/usr/bin/guestfish -f
123        sparse test1.img 100M
124        run
125        part-disk /dev/sda mbr
126        mkfs ext2 /dev/sda1
127
128   Start with a prepared disk
129       Create a 1G disk called test1.img containing a single ext2-formatted
130       partition:
131
132        guestfish -N fs
133
134       To list what is available do:
135
136        guestfish -N help | less
137
138   Remote drives
139       Access a remote disk using ssh:
140
141        guestfish -a ssh://example.com/path/to/disk.img
142
143   Remote control
144        eval "`guestfish --listen`"
145        guestfish --remote add-ro disk.img
146        guestfish --remote run
147        guestfish --remote lvs
148

OPTIONS

150       --help
151           Displays general help on options.
152
153       -h
154       --cmd-help
155           Lists all available guestfish commands.
156
157       -h CMD
158       --cmd-help CMD
159           Displays detailed help on a single command "cmd".
160
161       -a IMAGE
162       --add IMAGE
163           Add a block device or virtual machine image to the shell.
164
165           The format of the disk image is auto-detected.  To override this
166           and force a particular format use the --format=.. option.
167
168           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
172       -a URI
173       --add URI
174           Add a remote disk.  See "ADDING REMOTE STORAGE".
175
176       --blocksize=512
177       --blocksize=4096
178       --blocksize
179           This parameter sets the sector size of the disk image.  It affects
180           all explicitly added subsequent disks after this parameter.  Using
181           --blocksize with no argument switches the disk sector size to the
182           default value which is usually 512 bytes.  See also
183           "guestfs_add_drive_opts" in guestfs(3).
184
185       -c URI
186       --connect URI
187           When used in conjunction with the -d option, this specifies the
188           libvirt URI to use.  The default is to use the default libvirt
189           connection.
190
191       --csh
192           If using the --listen option and a csh-like shell, use this option.
193           See section "REMOTE CONTROL AND CSH" below.
194
195       -d LIBVIRT-DOMAIN
196       --domain LIBVIRT-DOMAIN
197           Add disks from the named libvirt domain.  If the --ro option is
198           also used, then any libvirt domain can be used.  However in write
199           mode, only libvirt domains which are shut down can be named here.
200
201           Domain UUIDs can be used instead of names.
202
203           Using this flag is mostly equivalent to using the "add-domain"
204           command, with "readonly:true" if the --ro flag was given, and with
205           "format:..." if the --format=... flag was given.
206
207       --echo-keys
208           When prompting for keys and passphrases, guestfish normally turns
209           echoing off so you cannot see what you are typing.  If you are not
210           worried about Tempest attacks and there is no one else in the room
211           you can specify this flag to see what you are typing.
212
213       -f FILE
214       --file FILE
215           Read commands from "FILE".  To write pure guestfish scripts, use:
216
217            #!/usr/bin/guestfish -f
218
219       --format=raw|qcow2|..
220       --format
221           The default for the -a option is to auto-detect the format of the
222           disk image.  Using this forces the disk format for -a options which
223           follow on the command line.  Using --format with no argument
224           switches back to auto-detection for subsequent -a options.
225
226           For example:
227
228            guestfish --format=raw -a disk.img
229
230           forces raw format (no auto-detection) for disk.img.
231
232            guestfish --format=raw -a disk.img --format -a another.img
233
234           forces raw format (no auto-detection) for disk.img and reverts to
235           auto-detection for another.img.
236
237           If you have untrusted raw-format guest disk images, you should use
238           this option to specify the disk format.  This avoids a possible
239           security problem with malicious guests (CVE-2010-3851).  See also
240           "add".
241
242       -i
243       --inspector
244           Using virt-inspector(1) code, inspect the disks looking for an
245           operating system and mount filesystems as they would be mounted on
246           the real virtual machine.
247
248           Typical usage is either:
249
250            guestfish -d myguest -i
251
252           (for an inactive libvirt domain called myguest), or:
253
254            guestfish --ro -d myguest -i
255
256           (for active domains, readonly), or specify the block device
257           directly:
258
259            guestfish --rw -a /dev/Guests/MyGuest -i
260
261           Note that the command line syntax changed slightly over older
262           versions of guestfish.  You can still use the old syntax:
263
264            guestfish [--ro] -i disk.img
265
266            guestfish [--ro] -i libvirt-domain
267
268           Using this flag is mostly equivalent to using the "inspect-os"
269           command and then using other commands to mount the filesystems that
270           were found.
271
272       --key SELECTOR
273           Specify a key for LUKS, to automatically open a LUKS device when
274           using the inspection.  "ID" can be either the libguestfs device
275           name, or the UUID of the LUKS device.
276
277           --key "ID":key:KEY_STRING
278               Use the specified "KEY_STRING" as passphrase.
279
280           --key "ID":file:FILENAME
281               Read the passphrase from FILENAME.
282
283       --keys-from-stdin
284           Read key or passphrase parameters from stdin.  The default is to
285           try to read passphrases from the user by opening /dev/tty.
286
287       --listen
288           Fork into the background and listen for remote commands.  See
289           section "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
290
291       --live
292           Connect to a live virtual machine.  (Experimental, see "ATTACHING
293           TO RUNNING DAEMONS" in guestfs(3)).
294
295       -m dev[:mountpoint[:options[:fstype]]]
296       --mount dev[:mountpoint[:options[:fstype]]]
297           Mount the named partition or logical volume on the given
298           mountpoint.
299
300           If the mountpoint is omitted, it defaults to /.
301
302           You have to mount something on / before most commands will work.
303
304           If any -m or --mount options are given, the guest is automatically
305           launched.
306
307           If you don’t know what filesystems a disk image contains, you can
308           either run guestfish without this option, then list the partitions,
309           filesystems and LVs available (see "list-partitions", "list-
310           filesystems" and "lvs" commands), or you can use the
311           virt-filesystems(1) program.
312
313           The third (and rarely used) part of the mount parameter is the list
314           of mount options used to mount the underlying filesystem.  If this
315           is not given, then the mount options are either the empty string or
316           "ro" (the latter if the --ro flag is used).  By specifying the
317           mount options, you override this default choice.  Probably the only
318           time you would use this is to enable ACLs and/or extended
319           attributes if the filesystem can support them:
320
321            -m /dev/sda1:/:acl,user_xattr
322
323           Using this flag is equivalent to using the "mount-options" command.
324
325           The fourth part of the parameter is the filesystem driver to use,
326           such as "ext3" or "ntfs". This is rarely needed, but can be useful
327           if multiple drivers are valid for a filesystem (eg: "ext2" and
328           "ext3"), or if libguestfs misidentifies a filesystem.
329
330       --network
331           Enable QEMU user networking in the guest.
332
333       -N [FILENAME=]TYPE
334       --new [FILENAME=]TYPE
335       -N help
336           Prepare a fresh disk image formatted as "TYPE".  This is an
337           alternative to the -a option: whereas -a adds an existing disk, -N
338           creates a preformatted disk with a filesystem and adds it.  See
339           "PREPARED DISK IMAGES" below.
340
341       -n
342       --no-sync
343           Disable autosync.  This is enabled by default.  See the discussion
344           of autosync in the guestfs(3) manpage.
345
346       --no-dest-paths
347           Don’t tab-complete paths on the guest filesystem.  It is useful to
348           be able to hit the tab key to complete paths on the guest
349           filesystem, but this causes extra "hidden" guestfs calls to be
350           made, so this option is here to allow this feature to be disabled.
351
352       --pipe-error
353           If writes fail to pipe commands (see "PIPES" below), then the
354           command returns an error.
355
356           The default (also for historical reasons) is to ignore such errors
357           so that:
358
359            ><fs> command_with_lots_of_output | head
360
361           doesn't give an error.
362
363       --progress-bars
364           Enable progress bars, even when guestfish is used non-
365           interactively.
366
367           Progress bars are enabled by default when guestfish is used as an
368           interactive shell.
369
370       --no-progress-bars
371           Disable progress bars.
372
373       --remote
374       --remote=PID
375           Send remote commands to $GUESTFISH_PID or "pid".  See section
376           "REMOTE CONTROL GUESTFISH OVER A SOCKET" below.
377
378       -r
379       --ro
380           This changes the -a, -d and -m options so that disks are added and
381           mounts are done read-only.
382
383           The option must always be used if the disk image or virtual machine
384           might be running, and is generally recommended in cases where you
385           don't need write access to the disk.
386
387           Note that prepared disk images created with -N are not affected by
388           this option.  Also commands like "add" are not affected - you have
389           to specify the "readonly:true" option explicitly if you need it.
390
391           See also "OPENING DISKS FOR READ AND WRITE" below.
392
393       --selinux
394           This option is provided for backwards compatibility and does
395           nothing.
396
397       -v
398       --verbose
399           Enable very verbose messages.  This is particularly useful if you
400           find a bug.
401
402       -V
403       --version
404           Display the guestfish / libguestfs version number and exit.
405
406       -w
407       --rw
408           This changes the -a, -d and -m options so that disks are added and
409           mounts are done read-write.
410
411           See "OPENING DISKS FOR READ AND WRITE" below.
412
413       -x  Echo each command before executing it.
414

COMMANDS ON COMMAND LINE

416       Any additional (non-option) arguments are treated as commands to
417       execute.
418
419       Commands to execute should be separated by a colon (":"), where the
420       colon is a separate parameter.  Thus:
421
422        guestfish cmd [args...] : cmd [args...] : cmd [args...] ...
423
424       If there are no additional arguments, then we enter a shell, either an
425       interactive shell with a prompt (if the input is a terminal) or a non-
426       interactive shell.
427
428       In either command line mode or non-interactive shell, the first command
429       that gives an error causes the whole shell to exit.  In interactive
430       mode (with a prompt) if a command fails, you can continue to enter
431       commands.
432
433       Note that arguments of the commands will be considered as guestfish
434       options if they start with a dash ("-"): you can always separate the
435       guestfish options and the rest of the commands (with their arguments)
436       using a double dash ("--").  For example:
437
438        guestfish -- disk_create overlay.qcow2 qcow2 -1 backingfile:image.img
439

USING launch (OR run)

441       As with guestfs(3), you must first configure your guest by adding
442       disks, then launch it, then mount any disks you need, and finally issue
443       actions/commands.  So the general order of the day is:
444
445       ·   add or -a/--add
446
447       ·   launch (aka run)
448
449       ·   mount or -m/--mount
450
451       ·   any other commands
452
453       "run" is a synonym for "launch".  You must "launch" (or "run") your
454       guest before mounting or performing any other commands.
455
456       The only exception is that if any of the -i, -m, --mount, -N or --new
457       options were given then "run" is done automatically, simply because
458       guestfish can't perform the action you asked for without doing this.
459

OPENING DISKS FOR READ AND WRITE

461       The guestfish, guestmount(1) and virt-rescue(1) options --ro and --rw
462       affect whether the other command line options -a, -c, -d, -i and -m
463       open disk images read-only or for writing.
464
465       In libguestfs ≤ 1.10, guestfish, guestmount and virt-rescue defaulted
466       to opening disk images supplied on the command line for write.  To open
467       a disk image read-only you have to do -a image --ro.
468
469       This matters: If you accidentally open a live VM disk image writable
470       then you will cause irreversible disk corruption.
471
472       In a future libguestfs we intend to change the default the other way.
473       Disk images will be opened read-only.  You will have to either specify
474       guestfish --rw, guestmount --rw, virt-rescue --rw, or change the
475       configuration file in order to get write access for disk images
476       specified by those other command line options.
477
478       This version of guestfish, guestmount and virt-rescue has a --rw option
479       which does nothing (it is already the default).  However it is highly
480       recommended that you use this option to indicate that you need write
481       access, and prepare your scripts for the day when this option will be
482       required for write access.
483
484       Note: This does not affect commands like "add" and "mount", or any
485       other libguestfs program apart from guestfish and guestmount.
486

QUOTING

488       You can quote ordinary parameters using either single or double quotes.
489       For example:
490
491        add "file with a space.img"
492
493        rm '/file name'
494
495        rm '/"'
496
497       A few commands require a list of strings to be passed.  For these, use
498       a whitespace-separated list, enclosed in quotes.  Strings containing
499       whitespace to be passed through must be enclosed in single quotes.  A
500       literal single quote must be escaped with a backslash.
501
502        vgcreate VG "/dev/sda1 /dev/sdb1"
503        command "/bin/echo 'foo      bar'"
504        command "/bin/echo \'foo\'"
505
506   ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS
507       In double-quoted arguments (only) use backslash to insert special
508       characters:
509
510       "\a"
511           Alert (bell) character.
512
513       "\b"
514           Backspace character.
515
516       "\f"
517           Form feed character.
518
519       "\n"
520           Newline character.
521
522       "\r"
523           Carriage return character.
524
525       "\t"
526           Horizontal tab character.
527
528       "\v"
529           Vertical tab character.
530
531       "\""
532           A literal double quote character.
533
534       "\ooo"
535           A character with octal value ooo.  There must be precisely 3 octal
536           digits (unlike C).
537
538       "\xhh"
539           A character with hex value hh.  There must be precisely 2 hex
540           digits.
541
542           In the current implementation "\000" and "\x00" cannot be used in
543           strings.
544
545       "\\"
546           A literal backslash character.
547

OPTIONAL ARGUMENTS

549       Some commands take optional arguments.  These arguments appear in this
550       documentation as "[argname:..]".  You can use them as in these
551       examples:
552
553        add filename
554
555        add filename readonly:true
556
557        add filename format:qcow2 readonly:false
558
559       Each optional argument can appear at most once.  All optional arguments
560       must appear after the required ones.
561

NUMBERS

563       This section applies to all commands which can take integers as
564       parameters.
565
566   SIZE SUFFIX
567       When the command takes a parameter measured in bytes, you can use one
568       of the following suffixes to specify kilobytes, megabytes and larger
569       sizes:
570
571       k or K or KiB
572           The size in kilobytes (multiplied by 1024).
573
574       KB  The size in SI 1000 byte units.
575
576       M or MiB
577           The size in megabytes (multiplied by 1048576).
578
579       MB  The size in SI 1000000 byte units.
580
581       G or GiB
582           The size in gigabytes (multiplied by 2**30).
583
584       GB  The size in SI 10**9 byte units.
585
586       T or TiB
587           The size in terabytes (multiplied by 2**40).
588
589       TB  The size in SI 10**12 byte units.
590
591       P or PiB
592           The size in petabytes (multiplied by 2**50).
593
594       PB  The size in SI 10**15 byte units.
595
596       E or EiB
597           The size in exabytes (multiplied by 2**60).
598
599       EB  The size in SI 10**18 byte units.
600
601       Z or ZiB
602           The size in zettabytes (multiplied by 2**70).
603
604       ZB  The size in SI 10**21 byte units.
605
606       Y or YiB
607           The size in yottabytes (multiplied by 2**80).
608
609       YB  The size in SI 10**24 byte units.
610
611       For example:
612
613        truncate-size /file 1G
614
615       would truncate the file to 1 gigabyte.
616
617       Be careful because a few commands take sizes in kilobytes or megabytes
618       (eg. the parameter to "memsize" is specified in megabytes already).
619       Adding a suffix will probably not do what you expect.
620
621   OCTAL AND HEXADECIMAL NUMBERS
622       For specifying the radix (base) use the C convention: 0 to prefix an
623       octal number or "0x" to prefix a hexadecimal number.  For example:
624
625        1234      decimal number 1234
626        02322     octal number, equivalent to decimal 1234
627        0x4d2     hexadecimal number, equivalent to decimal 1234
628
629       When using the "chmod" command, you almost always want to specify an
630       octal number for the mode, and you must prefix it with 0 (unlike the
631       Unix chmod(1) program):
632
633        chmod 0777 /public  # OK
634        chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.
635
636       Commands that return numbers usually print them in decimal, but some
637       commands print numbers in other radices (eg. "umask" prints the mode in
638       octal, preceded by 0).
639

WILDCARDS AND GLOBBING

641       Neither guestfish nor the underlying guestfs API performs wildcard
642       expansion (globbing) by default.  So for example the following will not
643       do what you expect:
644
645        rm-rf /home/*
646
647       Assuming you don’t have a directory called literally /home/* then the
648       above command will return an error.
649
650       To perform wildcard expansion, use the "glob" command.
651
652        glob rm-rf /home/*
653
654       runs "rm-rf" on each path that matches (ie. potentially running the
655       command many times), equivalent to:
656
657        rm-rf /home/jim
658        rm-rf /home/joe
659        rm-rf /home/mary
660
661       "glob" only works on simple guest paths and not on device names.
662
663       If you have several parameters, each containing a wildcard, then glob
664       will perform a Cartesian product.
665

COMMENTS

667       Any line which starts with a # character is treated as a comment and
668       ignored.  The # can optionally be preceded by whitespace, but not by a
669       command.  For example:
670
671        # this is a comment
672                # this is a comment
673        foo # NOT a comment
674
675       Blank lines are also ignored.
676

RUNNING COMMANDS LOCALLY

678       Any line which starts with a ! character is treated as a command sent
679       to the local shell (/bin/sh or whatever system(3) uses).  For example:
680
681        !mkdir local
682        tgz-out /remote local/remote-data.tar.gz
683
684       will create a directory "local" on the host, and then export the
685       contents of /remote on the mounted filesystem to
686       local/remote-data.tar.gz.  (See "tgz-out").
687
688       To change the local directory, use the "lcd" command.  "!cd" will have
689       no effect, due to the way that subprocesses work in Unix.
690
691   LOCAL COMMANDS WITH INLINE EXECUTION
692       If a line starts with <! then the shell command is executed (as for !),
693       but subsequently any output (stdout) of the shell command is parsed and
694       executed as guestfish commands.
695
696       Thus you can use shell script to construct arbitrary guestfish commands
697       which are then parsed by guestfish.
698
699       For example it is tedious to create a sequence of files (eg. /foo.1
700       through /foo.100) using guestfish commands alone.  However this is
701       simple if we use a shell script to create the guestfish commands for
702       us:
703
704        <! for n in `seq 1 100`; do echo write /foo.$n $n; done
705
706       or with names like /foo.001:
707
708        <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
709
710       When using guestfish interactively it can be helpful to just run the
711       shell script first (ie. remove the initial "<" character so it is just
712       an ordinary ! local command), see what guestfish commands it would run,
713       and when you are happy with those prepend the "<" character to run the
714       guestfish commands for real.
715

PIPES

717       Use "command <space> | command" to pipe the output of the first command
718       (a guestfish command) to the second command (any host command).  For
719       example:
720
721        cat /etc/passwd | awk -F: '$3 == 0 { print }'
722
723       (where "cat" is the guestfish cat command, but "awk" is the host awk
724       program).  The above command would list all accounts in the guest
725       filesystem which have UID 0, ie. root accounts including backdoors.
726       Other examples:
727
728        hexdump /bin/ls | head
729        list-devices | tail -1
730        tgz-out / - | tar ztf -
731
732       The space before the pipe symbol is required, any space after the pipe
733       symbol is optional.  Everything after the pipe symbol is just passed
734       straight to the host shell, so it can contain redirections, globs and
735       anything else that makes sense on the host side.
736
737       To use a literal argument which begins with a pipe symbol, you have to
738       quote it, eg:
739
740        echo "|"
741

HOME DIRECTORIES

743       If a parameter starts with the character "~" then the tilde may be
744       expanded as a home directory path (either "~" for the current user's
745       home directory, or "~user" for another user).
746
747       Note that home directory expansion happens for users known on the host,
748       not in the guest filesystem.
749
750       To use a literal argument which begins with a tilde, you have to quote
751       it, eg:
752
753        echo "~"
754

ENCRYPTED DISKS

756       Libguestfs has some support for Linux guests encrypted according to the
757       Linux Unified Key Setup (LUKS) standard, which includes nearly all
758       whole disk encryption systems used by modern Linux guests.  Currently
759       only LVM-on-LUKS is supported.
760
761       Identify encrypted block devices and partitions using "vfs-type":
762
763        ><fs> vfs-type /dev/sda2
764        crypto_LUKS
765
766       Then open those devices using "luks-open".  This creates a device-
767       mapper device called /dev/mapper/luksdev.
768
769        ><fs> luks-open /dev/sda2 luksdev
770        Enter key or passphrase ("key"): <enter the passphrase>
771
772       Finally you have to tell LVM to scan for volume groups on the newly
773       created mapper device:
774
775        vgscan
776        vg-activate-all true
777
778       The logical volume(s) can now be mounted in the usual way.
779
780       Before closing a LUKS device you must unmount any logical volumes on it
781       and deactivate the volume groups by calling "vg-activate false VG" on
782       each one.  Then you can close the mapper device:
783
784        vg-activate false /dev/VG
785        luks-close /dev/mapper/luksdev
786

WINDOWS PATHS

788       If a path is prefixed with "win:" then you can use Windows-style drive
789       letters and paths (with some limitations).  The following commands are
790       equivalent:
791
792        file /WINDOWS/system32/config/system.LOG
793
794        file win:\windows\system32\config\system.log
795
796        file WIN:C:\Windows\SYSTEM32\CONFIG\SYSTEM.LOG
797
798       The parameter is rewritten "behind the scenes" by looking up the
799       position where the drive is mounted, prepending that to the path,
800       changing all backslash characters to forward slash, then resolving the
801       result using "case-sensitive-path".  For example if the E: drive was
802       mounted on /e then the parameter might be rewritten like this:
803
804        win:e:\foo\bar => /e/FOO/bar
805
806       This only works in argument positions that expect a path.
807

UPLOADING AND DOWNLOADING FILES

809       For commands such as "upload", "download", "tar-in", "tar-out" and
810       others which upload from or download to a local file, you can use the
811       special filename "-" to mean "from stdin" or "to stdout".  For example:
812
813        upload - /foo
814
815       reads stdin and creates from that a file /foo in the disk image, and:
816
817        tar-out /etc - | tar tf -
818
819       writes the tarball to stdout and then pipes that into the external
820       "tar" command (see "PIPES").
821
822       When using "-" to read from stdin, the input is read up to the end of
823       stdin.  You can also use a special "heredoc"-like syntax to read up to
824       some arbitrary end marker:
825
826        upload -<<END /foo
827        input line 1
828        input line 2
829        input line 3
830        END
831
832       Any string of characters can be used instead of "END".  The end marker
833       must appear on a line of its own, without any preceding or following
834       characters (not even spaces).
835
836       Note that the "-<<" syntax only applies to parameters used to upload
837       local files (so-called "FileIn" parameters in the generator).
838

EXIT ON ERROR BEHAVIOUR

840       By default, guestfish will ignore any errors when in interactive mode
841       (ie. taking commands from a human over a tty), and will exit on the
842       first error in non-interactive mode (scripts, commands given on the
843       command line).
844
845       If you prefix a command with a - character, then that command will not
846       cause guestfish to exit, even if that (one) command returns an error.
847

REMOTE CONTROL GUESTFISH OVER A SOCKET

849       Guestfish can be remote-controlled over a socket.  This is useful
850       particularly in shell scripts where you want to make several different
851       changes to a filesystem, but you don't want the overhead of starting up
852       a guestfish process each time.
853
854       Start a guestfish server process using:
855
856        eval "`guestfish --listen`"
857
858       and then send it commands by doing:
859
860        guestfish --remote cmd [...]
861
862       To cause the server to exit, send it the exit command:
863
864        guestfish --remote exit
865
866       Note that the server will normally exit if there is an error in a
867       command.  You can change this in the usual way.  See section "EXIT ON
868       ERROR BEHAVIOUR".
869
870   CONTROLLING MULTIPLE GUESTFISH PROCESSES
871       The "eval" statement sets the environment variable $GUESTFISH_PID,
872       which is how the --remote option knows where to send the commands.  You
873       can have several guestfish listener processes running using:
874
875        eval "`guestfish --listen`"
876        pid1=$GUESTFISH_PID
877        eval "`guestfish --listen`"
878        pid2=$GUESTFISH_PID
879        ...
880        guestfish --remote=$pid1 cmd
881        guestfish --remote=$pid2 cmd
882
883   REMOTE CONTROL AND CSH
884       When using csh-like shells (csh, tcsh etc) you have to add the --csh
885       option:
886
887        eval "`guestfish --listen --csh`"
888
889   REMOTE CONTROL DETAILS
890       Remote control happens over a Unix domain socket called
891       /tmp/.guestfish-$UID/socket-$PID, where $UID is the effective user ID
892       of the process, and $PID is the process ID of the server.
893
894       Guestfish client and server versions must match exactly.
895
896       Older versions of guestfish were vulnerable to CVE-2013-4419 (see
897       "CVE-2013-4419" in guestfs(3)).  This is fixed in the current version.
898
899   USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
900       From Bash, you can use the following code which creates a guestfish
901       instance, correctly quotes the command line, handles failure to start,
902       and cleans up guestfish when the script exits:
903
904        #!/bin/bash -
905
906        set -e
907
908        guestfish[0]="guestfish"
909        guestfish[1]="--listen"
910        guestfish[2]="--ro"
911        guestfish[3]="-a"
912        guestfish[4]="disk.img"
913
914        GUESTFISH_PID=
915        eval $("${guestfish[@]}")
916        if [ -z "$GUESTFISH_PID" ]; then
917            echo "error: guestfish didn't start up, see error messages above"
918            exit 1
919        fi
920
921        cleanup_guestfish ()
922        {
923            guestfish --remote -- exit >/dev/null 2>&1 ||:
924        }
925        trap cleanup_guestfish EXIT ERR
926
927        guestfish --remote -- run
928
929        # ...
930
931   REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS
932       Options such as -a, --add, -N, --new etc don’t interact properly with
933       remote support.  They are processed locally, and not sent through to
934       the remote guestfish.  In particular this won't do what you expect:
935
936        guestfish --remote --add disk.img
937
938       Don’t use these options.  Use the equivalent commands instead, eg:
939
940        guestfish --remote add-drive disk.img
941
942       or:
943
944        guestfish --remote
945        ><fs> add disk.img
946
947   REMOTE CONTROL RUN COMMAND HANGING
948       Using the "run" (or "launch") command remotely in a command
949       substitution context hangs, ie. don't do (note the backquotes):
950
951        a=`guestfish --remote run`
952
953       Since the "run" command produces no output on stdout, this is not
954       useful anyway.  For further information see
955       https://bugzilla.redhat.com/show_bug.cgi?id=592910.
956

PREPARED DISK IMAGES

958       Use the -N [filename=]type or --new [filename=]type parameter to select
959       one of a set of preformatted disk images that guestfish can make for
960       you to save typing.  This is particularly useful for testing purposes.
961       This option is used instead of the -a option, and like -a can appear
962       multiple times (and can be mixed with -a).
963
964       The new disk is called test1.img for the first -N, test2.img for the
965       second and so on.  Existing files in the current directory are
966       overwritten.  You can use a different filename by specifying
967       "filename=" before the type (see examples below).
968
969       The type briefly describes how the disk should be sized, partitioned,
970       how filesystem(s) should be created, and how content should be added.
971       Optionally the type can be followed by extra parameters, separated by
972       ":" (colon) characters.  For example, -N fs creates a default 1G,
973       sparsely-allocated disk, containing a single partition, with the
974       partition formatted as ext2.  -N fs:ext4:2G is the same, but for an
975       ext4 filesystem on a 2GB disk instead.
976
977       Note that the prepared filesystem is not mounted.  You would usually
978       have to use the "mount /dev/sda1 /" command or add the -m /dev/sda1
979       option.
980
981       If any -N or --new options are given, the libguestfs appliance is
982       automatically launched.
983
984   EXAMPLES
985       Create a 1G disk with an ext4-formatted partition, called test1.img in
986       the current directory:
987
988        guestfish -N fs:ext4
989
990       Create a 32MB disk with a VFAT-formatted partition, and mount it:
991
992        guestfish -N fs:vfat:32M -m /dev/sda1
993
994       Create a blank 200MB disk:
995
996        guestfish -N disk:200M
997
998       Create a blank 200MB disk called blankdisk.img (instead of test1.img):
999
1000        guestfish -N blankdisk.img=disk:200M
1001
1002   -N disk - create a blank disk
1003       "guestfish -N [filename=]disk[:size]"
1004
1005       Create a blank disk, size 1G (by default).
1006
1007       The default size can be changed by supplying an optional parameter.
1008
1009       The optional parameters are:
1010
1011        Name          Default value
1012        size          1G            the size of the disk image
1013
1014   -N part - create a partitioned disk
1015       "guestfish -N [filename=]part[:size[:partition]]"
1016
1017       Create a disk with a single partition.  By default the size of the disk
1018       is 1G (the available space in the partition will be a tiny bit smaller)
1019       and the partition table will be MBR (old DOS-style).
1020
1021       These defaults can be changed by supplying optional parameters.
1022
1023       The optional parameters are:
1024
1025        Name          Default value
1026        size          1G            the size of the disk image
1027        partition     mbr           partition table type
1028
1029   -N fs - create a filesystem
1030       "guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"
1031
1032       Create a disk with a single partition, with the partition containing an
1033       empty filesystem.  This defaults to creating a 1G disk (the available
1034       space in the filesystem will be a tiny bit smaller) with an MBR (old
1035       DOS-style) partition table and an ext2 filesystem.
1036
1037       These defaults can be changed by supplying optional parameters.
1038
1039       The optional parameters are:
1040
1041        Name          Default value
1042        filesystem    ext2          the type of filesystem to use
1043        size          1G            the size of the disk image
1044        partition     mbr           partition table type
1045
1046   -N lv - create a disk with logical volume
1047       "guestfish -N [filename=]lv[:name[:size[:partition]]]"
1048
1049       Create a disk with a single partition, set up the partition as an LVM2
1050       physical volume, and place a volume group and logical volume on there.
1051       This defaults to creating a 1G disk with the VG and LV called
1052       "/dev/VG/LV".  You can change the name of the VG and LV by supplying an
1053       alternate name as the first optional parameter.
1054
1055       Note this does not create a filesystem.  Use 'lvfs' to do that.
1056
1057       The optional parameters are:
1058
1059        Name          Default value
1060        name          /dev/VG/LV    the name of the VG and LV to use
1061        size          1G            the size of the disk image
1062        partition     mbr           partition table type
1063
1064   -N lvfs - create a disk with logical volume and filesystem
1065       "guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"
1066
1067       Create a disk with a single partition, set up the partition as an LVM2
1068       physical volume, and place a volume group and logical volume on there.
1069       Then format the LV with a filesystem.  This defaults to creating a 1G
1070       disk with the VG and LV called "/dev/VG/LV", with an ext2 filesystem.
1071
1072       The optional parameters are:
1073
1074        Name          Default value
1075        name          /dev/VG/LV    the name of the VG and LV to use
1076        filesystem    ext2          the type of filesystem to use
1077        size          1G            the size of the disk image
1078        partition     mbr           partition table type
1079
1080   -N bootroot - create a boot and root filesystem
1081       "guestfish -N
1082       [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"
1083
1084       Create a disk with two partitions, for boot and root filesystem.
1085       Format the two filesystems independently.  There are several optional
1086       parameters which control the exact layout and filesystem types.
1087
1088       The optional parameters are:
1089
1090        Name          Default value
1091        bootfs        ext2          the type of filesystem to use for boot
1092        rootfs        ext2          the type of filesystem to use for root
1093        size          1G            the size of the disk image
1094        bootsize      128M          the size of the boot filesystem
1095        partition     mbr           partition table type
1096
1097   -N bootrootlv - create a boot and root filesystem using LVM
1098       "guestfish -N
1099       [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"
1100
1101       This is the same as "bootroot" but the root filesystem (only) is placed
1102       on a logical volume, named by default "/dev/VG/LV".  There are several
1103       optional parameters which control the exact layout.
1104
1105       The optional parameters are:
1106
1107        Name          Default value
1108        name          /dev/VG/LV    the name of the VG and LV for root
1109        bootfs        ext2          the type of filesystem to use for boot
1110        rootfs        ext2          the type of filesystem to use for root
1111        size          1G            the size of the disk image
1112        bootsize      128M          the size of the boot filesystem
1113        partition     mbr           partition table type
1114

ADDING REMOTE STORAGE

1116       For API-level documentation on this topic, see "guestfs_add_drive_opts"
1117       in guestfs(3) and "REMOTE STORAGE" in guestfs(3).
1118
1119       On the command line, you can use the -a option to add network block
1120       devices using a URI-style format, for example:
1121
1122        guestfish -a ssh://root@example.com/disk.img
1123
1124       URIs cannot be used with the "add" command.  The equivalent command
1125       using the API directly is:
1126
1127        ><fs> add /disk.img protocol:ssh server:tcp:example.com username:root
1128
1129       The possible -a URI formats are described below.
1130
1131   -a disk.img
1132   -a file:///path/to/disk.img
1133       Add the local disk image (or device) called disk.img.
1134
1135   -a ftp://[user@]example.com[:port]/disk.img
1136   -a ftps://[user@]example.com[:port]/disk.img
1137   -a http://[user@]example.com[:port]/disk.img
1138   -a https://[user@]example.com[:port]/disk.img
1139   -a tftp://[user@]example.com[:port]/disk.img
1140       Add a disk located on a remote FTP, HTTP or TFTP server.
1141
1142       The equivalent API command would be:
1143
1144        ><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com
1145
1146   -a gluster://example.com[:port]/volname/image
1147       Add a disk image located on GlusterFS storage.
1148
1149       The server is the one running "glusterd", and may be "localhost".
1150
1151       The equivalent API command would be:
1152
1153        ><fs> add volname/image protocol:gluster server:tcp:example.com
1154
1155   -a iscsi://example.com[:port]/target-iqn-name[/lun]
1156       Add a disk located on an iSCSI server.
1157
1158       The equivalent API command would be:
1159
1160        ><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com
1161
1162   -a nbd://example.com[:port]
1163   -a nbd://example.com[:port]/exportname
1164   -a nbd://?socket=/socket
1165   -a nbd:///exportname?socket=/socket
1166       Add a disk located on Network Block Device (nbd) storage.
1167
1168       The /exportname part of the URI specifies an NBD export name, but is
1169       usually left empty.
1170
1171       The optional ?socket parameter can be used to specify a Unix domain
1172       socket that we talk to the NBD server over.  Note that you cannot mix
1173       server name (ie. TCP/IP) and socket path.
1174
1175       The equivalent API command would be (no export name):
1176
1177        ><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]
1178
1179   -a rbd:///pool/disk
1180   -a rbd://example.com[:port]/pool/disk
1181       Add a disk image located on a Ceph (RBD/librbd) storage volume.
1182
1183       Although libguestfs and Ceph supports multiple servers, only a single
1184       server can be specified when using this URI syntax.
1185
1186       The equivalent API command would be:
1187
1188        ><fs> add pool/disk protocol:rbd server:tcp:example.com:port
1189
1190   -a sheepdog://[example.com[:port]]/volume/image
1191       Add a disk image located on a Sheepdog volume.
1192
1193       The server name is optional.  Although libguestfs and Sheepdog supports
1194       multiple servers, only at most one server can be specified when using
1195       this URI syntax.
1196
1197       The equivalent API command would be:
1198
1199        ><fs> add volume protocol:sheepdog [server:tcp:example.com]
1200
1201   -a ssh://[user@]example.com[:port]/disk.img
1202       Add a disk image located on a remote server, accessed using the Secure
1203       Shell (ssh) SFTP protocol.  SFTP is supported out of the box by all
1204       major SSH servers.
1205
1206       The equivalent API command would be:
1207
1208        ><fs> add /disk protocol:ssh server:tcp:example.com [username:user]
1209
1210       Note that the URIs follow the syntax of RFC 3986: in particular, there
1211       are restrictions on the allowed characters for the various components
1212       of the URI.  Characters such as ":", "@", and "/" must be percent-
1213       encoded:
1214
1215        $ guestfish -a ssh://user:pass%40word@example.com/disk.img
1216
1217       In this case, the password is "pass@word".
1218

PROGRESS BARS

1220       Some (not all) long-running commands send progress notification
1221       messages as they are running.  Guestfish turns these messages into
1222       progress bars.
1223
1224       When a command that supports progress bars takes longer than two
1225       seconds to run, and if progress bars are enabled, then you will see one
1226       appearing below the command:
1227
1228        ><fs> copy-size /large-file /another-file 2048M
1229        / 10% [#####-----------------------------------------] 00:30
1230
1231       The spinner on the left hand side moves round once for every progress
1232       notification received from the backend.  This is a (reasonably) golden
1233       assurance that the command is "doing something" even if the progress
1234       bar is not moving, because the command is able to send the progress
1235       notifications.  When the bar reaches 100% and the command finishes, the
1236       spinner disappears.
1237
1238       Progress bars are enabled by default when guestfish is used
1239       interactively.  You can enable them even for non-interactive modes
1240       using --progress-bars, and you can disable them completely using
1241       --no-progress-bars.
1242

PROMPT

1244       You can change or add colours to the default prompt ("><fs>") by
1245       setting the "GUESTFISH_PS1" environment variable.  A second string
1246       ("GUESTFISH_OUTPUT") is printed after the command has been entered and
1247       before the output, allowing you to control the colour of the output.  A
1248       third string ("GUESTFISH_INIT") is printed before the welcome message,
1249       allowing you to control the colour of that message.  A fourth string
1250       ("GUESTFISH_RESTORE") is printed before guestfish exits.
1251
1252       A simple prompt can be set by setting "GUESTFISH_PS1" to an alternate
1253       string:
1254
1255        $ GUESTFISH_PS1='(type a command) '
1256        $ export GUESTFISH_PS1
1257        $ guestfish
1258        [...]
1259        (type a command) ▂
1260
1261       You can also use special escape sequences, as described in the table
1262       below:
1263
1264       \\  A literal backslash character.
1265
1266       \[
1267       \]  (These should only be used in "GUESTFISH_PS1".)
1268
1269           Place non-printing characters (eg. terminal control codes for
1270           colours) between "\[...\]".  What this does it to tell the
1271           readline(3) library that it should treat this subsequence as zero-
1272           width, so that command-line redisplay, editing etc works.
1273
1274       \a  A bell character.
1275
1276       \e  An ASCII ESC (escape) character.
1277
1278       \n  A newline.
1279
1280       \r  A carriage return.
1281
1282       \NNN
1283           The ASCII character whose code is the octal value NNN.
1284
1285       \xNN
1286           The ASCII character whose code is the hex value NN.
1287
1288   EXAMPLES OF PROMPTS
1289       Note that these examples require a terminal that supports ANSI escape
1290       codes.
1291
1292       ·
1293
1294
1295            GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '
1296
1297           A bold black version of the ordinary prompt.
1298
1299       ·
1300
1301
1302            GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
1303            GUESTFISH_OUTPUT='\e[0m'
1304            GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
1305            GUESTFISH_INIT='\e[1;34m'
1306
1307           Blue welcome text, green prompt, red commands, black command
1308           output.
1309

WINDOWS 8

1311       Windows 8 "fast startup" can prevent guestfish from mounting NTFS
1312       partitions.  See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in
1313       guestfs(3).
1314

GUESTFISH COMMANDS

1316       The commands in this section are guestfish convenience commands, in
1317       other words, they are not part of the guestfs(3) API.
1318
1319   help
1320        help
1321        help cmd
1322        help -l|--list
1323
1324       Without any parameter, this provides general help.
1325
1326       With a "cmd" parameter, this displays detailed help for that command.
1327
1328       With -l or --list, this list all commands.
1329
1330   exit
1331   quit
1332       This exits guestfish.  You can also use "^D" key.
1333
1334   alloc
1335   allocate
1336        alloc filename size
1337
1338       This creates an empty (zeroed) file of the given size, and then adds so
1339       it can be further examined.
1340
1341       For more advanced image creation, see "disk-create".
1342
1343       Size can be specified using standard suffixes, eg. "1M".
1344
1345       To create a sparse file, use "sparse" instead.  To create a prepared
1346       disk image, see "PREPARED DISK IMAGES".
1347
1348   copy-in
1349        copy-in local [local ...] /remotedir
1350
1351       "copy-in" copies local files or directories recursively into the disk
1352       image, placing them in the directory called /remotedir (which must
1353       exist).  This guestfish meta-command turns into a sequence of "tar-in"
1354       and other commands as necessary.
1355
1356       Multiple local files and directories can be specified, but the last
1357       parameter must always be a remote directory.  Wildcards cannot be used.
1358
1359   copy-out
1360        copy-out remote [remote ...] localdir
1361
1362       "copy-out" copies remote files or directories recursively out of the
1363       disk image, placing them on the host disk in a local directory called
1364       "localdir" (which must exist).  This guestfish meta-command turns into
1365       a sequence of "download", "tar-out" and other commands as necessary.
1366
1367       Multiple remote files and directories can be specified, but the last
1368       parameter must always be a local directory.  To download to the current
1369       directory, use "." as in:
1370
1371        copy-out /home .
1372
1373       Wildcards cannot be used in the ordinary command, but you can use them
1374       with the help of "glob" like this:
1375
1376        glob copy-out /home/* .
1377
1378   delete-event
1379        delete-event name
1380
1381       Delete the event handler which was previously registered as "name".  If
1382       multiple event handlers were registered with the same name, they are
1383       all deleted.
1384
1385       See also the guestfish commands "event" and "list-events".
1386
1387   display
1388        display filename
1389
1390       Use "display" (a graphical display program) to display an image file.
1391       It downloads the file, and runs "display" on it.
1392
1393       To use an alternative program, set the "GUESTFISH_DISPLAY_IMAGE"
1394       environment variable.  For example to use the GNOME display program:
1395
1396        export GUESTFISH_DISPLAY_IMAGE=eog
1397
1398       See also display(1).
1399
1400   echo
1401        echo [params ...]
1402
1403       This echos the parameters to the terminal.
1404
1405   edit
1406   vi
1407   emacs
1408        edit filename
1409
1410       This is used to edit a file.  It downloads the file, edits it locally
1411       using your editor, then uploads the result.
1412
1413       The editor is $EDITOR.  However if you use the alternate commands "vi"
1414       or "emacs" you will get those corresponding editors.
1415
1416   event
1417        event name eventset "shell script ..."
1418
1419       Register a shell script fragment which is executed when an event is
1420       raised.  See "guestfs_set_event_callback" in guestfs(3) for a
1421       discussion of the event API in libguestfs.
1422
1423       The "name" parameter is a name that you give to this event handler.  It
1424       can be any string (even the empty string) and is simply there so you
1425       can delete the handler using the guestfish "delete-event" command.
1426
1427       The "eventset" parameter is a comma-separated list of one or more
1428       events, for example "close" or "close,trace".  The special value "*"
1429       means all events.
1430
1431       The third and final parameter is the shell script fragment (or any
1432       external command) that is executed when any of the events in the
1433       eventset occurs.  It is executed using "$SHELL -c", or if $SHELL is not
1434       set then /bin/sh -c.
1435
1436       The shell script fragment receives callback parameters as arguments $1,
1437       $2 etc.  The actual event that was called is available in the
1438       environment variable $EVENT.
1439
1440        event "" close "echo closed"
1441        event messages appliance,library,trace "echo $@"
1442        event "" progress "echo progress: $3/$4"
1443        event "" * "echo $EVENT $@"
1444
1445       See also the guestfish commands "delete-event" and "list-events".
1446
1447   glob
1448        glob command args...
1449
1450       Expand wildcards in any paths in the args list, and run "command"
1451       repeatedly on each matching path.
1452
1453       See "WILDCARDS AND GLOBBING".
1454
1455   hexedit
1456        hexedit <filename|device>
1457        hexedit <filename|device> <max>
1458        hexedit <filename|device> <start> <max>
1459
1460       Use hexedit (a hex editor) to edit all or part of a binary file or
1461       block device.
1462
1463       This command works by downloading potentially the whole file or device,
1464       editing it locally, then uploading it.  If the file or device is large,
1465       you have to specify which part you wish to edit by using "max" and/or
1466       "start" "max" parameters.  "start" and "max" are specified in bytes,
1467       with the usual modifiers allowed such as "1M" (1 megabyte).
1468
1469       For example to edit the first few sectors of a disk you might do:
1470
1471        hexedit /dev/sda 1M
1472
1473       which would allow you to edit anywhere within the first megabyte of the
1474       disk.
1475
1476       To edit the superblock of an ext2 filesystem on /dev/sda1, do:
1477
1478        hexedit /dev/sda1 0x400 0x400
1479
1480       (assuming the superblock is in the standard location).
1481
1482       This command requires the external hexedit(1) program.  You can specify
1483       another program to use by setting the "HEXEDITOR" environment variable.
1484
1485       See also "hexdump".
1486
1487   lcd
1488        lcd directory
1489
1490       Change the local directory, ie. the current directory of guestfish
1491       itself.
1492
1493       Note that "!cd" won't do what you might expect.
1494
1495   list-events
1496        list-events
1497
1498       List the event handlers registered using the guestfish "event" command.
1499
1500   man
1501   manual
1502         man
1503
1504       Opens the manual page for guestfish.
1505
1506   more
1507   less
1508        more filename
1509
1510        less filename
1511
1512       This is used to view a file.
1513
1514       The default viewer is $PAGER.  However if you use the alternate command
1515       "less" you will get the "less" command specifically.
1516
1517   reopen
1518         reopen
1519
1520       Close and reopen the libguestfs handle.  It is not necessary to use
1521       this normally, because the handle is closed properly when guestfish
1522       exits.  However this is occasionally useful for testing.
1523
1524   setenv
1525         setenv VAR value
1526
1527       Set the environment variable "VAR" to the string "value".
1528
1529       To print the value of an environment variable use a shell command such
1530       as:
1531
1532        !echo $VAR
1533
1534   sparse
1535        sparse filename size
1536
1537       This creates an empty sparse file of the given size, and then adds so
1538       it can be further examined.
1539
1540       In all respects it works the same as the "alloc" command, except that
1541       the image file is allocated sparsely, which means that disk blocks are
1542       not assigned to the file until they are needed.  Sparse disk files only
1543       use space when written to, but they are slower and there is a danger
1544       you could run out of real disk space during a write operation.
1545
1546       For more advanced image creation, see "disk-create".
1547
1548       Size can be specified using standard suffixes, eg. "1M".
1549
1550       See also the guestfish "scratch" command.
1551
1552   supported
1553        supported
1554
1555       This command returns a list of the optional groups known to the daemon,
1556       and indicates which ones are supported by this build of the libguestfs
1557       appliance.
1558
1559       See also "AVAILABILITY" in guestfs(3).
1560
1561   time
1562        time command args...
1563
1564       Run the command as usual, but print the elapsed time afterwards.  This
1565       can be useful for benchmarking operations.
1566
1567   unsetenv
1568         unsetenv VAR
1569
1570       Remove "VAR" from the environment.
1571

COMMANDS

1573   acl-delete-def-file
1574        acl-delete-def-file dir
1575
1576       This function deletes the default POSIX Access Control List (ACL)
1577       attached to directory "dir".
1578
1579       This command depends on the feature "acl".   See also "feature-
1580       available".
1581
1582   acl-get-file
1583        acl-get-file path acltype
1584
1585       This function returns the POSIX Access Control List (ACL) attached to
1586       "path".  The ACL is returned in "long text form" (see acl(5)).
1587
1588       The "acltype" parameter may be:
1589
1590       "access"
1591           Return the ordinary (access) ACL for any file, directory or other
1592           filesystem object.
1593
1594       "default"
1595           Return the default ACL.  Normally this only makes sense if "path"
1596           is a directory.
1597
1598       This command depends on the feature "acl".   See also "feature-
1599       available".
1600
1601   acl-set-file
1602        acl-set-file path acltype acl
1603
1604       This function sets the POSIX Access Control List (ACL) attached to
1605       "path".
1606
1607       The "acltype" parameter may be:
1608
1609       "access"
1610           Set the ordinary (access) ACL for any file, directory or other
1611           filesystem object.
1612
1613       "default"
1614           Set the default ACL.  Normally this only makes sense if "path" is a
1615           directory.
1616
1617       The "acl" parameter is the new ACL in either "long text form" or "short
1618       text form" (see acl(5)).  The new ACL completely replaces any previous
1619       ACL on the file.  The ACL must contain the full Unix permissions (eg.
1620       "u::rwx,g::rx,o::rx").
1621
1622       If you are specifying individual users or groups, then the mask field
1623       is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1624       "g:ID:..." field(s).  A full ACL string might therefore look like this:
1625
1626        u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1627        \ Unix permissions / \mask/ \      ACL        /
1628
1629       You should use numeric UIDs and GIDs.  To map usernames and groupnames
1630       to the correct numeric ID in the context of the guest, use the Augeas
1631       functions (see "aug-init").
1632
1633       This command depends on the feature "acl".   See also "feature-
1634       available".
1635
1636   add-cdrom
1637        add-cdrom filename
1638
1639       This function adds a virtual CD-ROM disk image to the guest.
1640
1641       The image is added as read-only drive, so this function is equivalent
1642       of "add-drive-ro".
1643
1644       This function is deprecated.  In new code, use the "add-drive-ro" call
1645       instead.
1646
1647       Deprecated functions will not be removed from the API, but the fact
1648       that they are deprecated indicates that there are problems with correct
1649       use of these functions.
1650
1651   add-domain
1652   domain
1653        add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]
1654
1655       This function adds the disk(s) attached to the named libvirt domain
1656       "dom".  It works by connecting to libvirt, requesting the domain and
1657       domain XML from libvirt, parsing it for disks, and calling "add-drive-
1658       opts" on each one.
1659
1660       The number of disks added is returned.  This operation is atomic: if an
1661       error is returned, then no disks are added.
1662
1663       This function does some minimal checks to make sure the libvirt domain
1664       is not running (unless "readonly" is true).  In a future version we
1665       will try to acquire the libvirt lock on each disk.
1666
1667       Disks must be accessible locally.  This often means that adding disks
1668       from a remote libvirt connection (see https://libvirt.org/remote.html)
1669       will fail unless those disks are accessible via the same device path
1670       locally too.
1671
1672       The optional "libvirturi" parameter sets the libvirt URI (see
1673       https://libvirt.org/uri.html).  If this is not set then we connect to
1674       the default libvirt URI (or one set through an environment variable,
1675       see the libvirt documentation for full details).
1676
1677       The optional "live" flag controls whether this call will try to connect
1678       to a running virtual machine "guestfsd" process if it sees a suitable
1679       <channel> element in the libvirt XML definition.  The default (if the
1680       flag is omitted) is never to try.  See "ATTACHING TO RUNNING DAEMONS"
1681       in guestfs(3) for more information.
1682
1683       If the "allowuuid" flag is true (default is false) then a UUID may be
1684       passed instead of the domain name.  The "dom" string is treated as a
1685       UUID first and looked up, and if that lookup fails then we treat "dom"
1686       as a name as usual.
1687
1688       The optional "readonlydisk" parameter controls what we do for disks
1689       which are marked <readonly/> in the libvirt XML.  Possible values are:
1690
1691       readonlydisk = "error"
1692           If "readonly" is false:
1693
1694           The whole call is aborted with an error if any disk with the
1695           <readonly/> flag is found.
1696
1697           If "readonly" is true:
1698
1699           Disks with the <readonly/> flag are added read-only.
1700
1701       readonlydisk = "read"
1702           If "readonly" is false:
1703
1704           Disks with the <readonly/> flag are added read-only.  Other disks
1705           are added read/write.
1706
1707           If "readonly" is true:
1708
1709           Disks with the <readonly/> flag are added read-only.
1710
1711       readonlydisk = "write" (default)
1712           If "readonly" is false:
1713
1714           Disks with the <readonly/> flag are added read/write.
1715
1716           If "readonly" is true:
1717
1718           Disks with the <readonly/> flag are added read-only.
1719
1720       readonlydisk = "ignore"
1721           If "readonly" is true or false:
1722
1723           Disks with the <readonly/> flag are skipped.
1724
1725       If present, the value of "logical_block_size" attribute of <blockio/>
1726       tag in libvirt XML will be passed as "blocksize" parameter to "add-
1727       drive-opts".
1728
1729       The other optional parameters are passed directly through to "add-
1730       drive-opts".
1731
1732       This command has one or more optional arguments.  See "OPTIONAL
1733       ARGUMENTS".
1734
1735   add-drive
1736   add
1737   add-drive-opts
1738        add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]
1739
1740       This function adds a disk image called filename to the handle.
1741       filename may be a regular host file or a host device.
1742
1743       When this function is called before "launch" (the usual case) then the
1744       first time you call this function, the disk appears in the API as
1745       /dev/sda, the second time as /dev/sdb, and so on.
1746
1747       In libguestfs ≥ 1.20 you can also call this function after launch (with
1748       some restrictions).  This is called "hotplugging".  When hotplugging,
1749       you must specify a "label" so that the new disk gets a predictable
1750       name.  For more information see "HOTPLUGGING" in guestfs(3).
1751
1752       You don't necessarily need to be root when using libguestfs.  However
1753       you obviously do need sufficient permissions to access the filename for
1754       whatever operations you want to perform (ie. read access if you just
1755       want to read the image or write access if you want to modify the
1756       image).
1757
1758       This call checks that filename exists.
1759
1760       filename may be the special string "/dev/null".  See "NULL DISKS" in
1761       guestfs(3).
1762
1763       The optional arguments are:
1764
1765       "readonly"
1766           If true then the image is treated as read-only.  Writes are still
1767           allowed, but they are stored in a temporary snapshot overlay which
1768           is discarded at the end.  The disk that you add is not modified.
1769
1770       "format"
1771           This forces the image format.  If you omit this (or use "add-drive"
1772           or "add-drive-ro") then the format is automatically detected.
1773           Possible formats include "raw" and "qcow2".
1774
1775           Automatic detection of the format opens you up to a potential
1776           security hole when dealing with untrusted raw-format images.  See
1777           CVE-2010-3851 and RHBZ#642934.  Specifying the format closes this
1778           security hole.
1779
1780       "iface"
1781           This rarely-used option lets you emulate the behaviour of the
1782           deprecated "add-drive-with-if" call (q.v.)
1783
1784       "name"
1785           The name the drive had in the original guest, e.g. /dev/sdb.  This
1786           is used as a hint to the guest inspection process if it is
1787           available.
1788
1789       "label"
1790           Give the disk a label.  The label should be a unique, short string
1791           using only ASCII characters "[a-zA-Z]".  As well as its usual name
1792           in the API (such as /dev/sda), the drive will also be named
1793           /dev/disk/guestfs/label.
1794
1795           See "DISK LABELS" in guestfs(3).
1796
1797       "protocol"
1798           The optional protocol argument can be used to select an alternate
1799           source protocol.
1800
1801           See also: "REMOTE STORAGE" in guestfs(3).
1802
1803           "protocol = "file""
1804               filename is interpreted as a local file or device.  This is the
1805               default if the optional protocol parameter is omitted.
1806
1807           "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
1808               Connect to a remote FTP, HTTP or TFTP server.  The "server"
1809               parameter must also be supplied - see below.
1810
1811               See also: "FTP, HTTP AND TFTP" in guestfs(3)
1812
1813           "protocol = "gluster""
1814               Connect to the GlusterFS server.  The "server" parameter must
1815               also be supplied - see below.
1816
1817               See also: "GLUSTER" in guestfs(3)
1818
1819           "protocol = "iscsi""
1820               Connect to the iSCSI server.  The "server" parameter must also
1821               be supplied - see below.  The "username" parameter may be
1822               supplied.  See below.  The "secret" parameter may be supplied.
1823               See below.
1824
1825               See also: "ISCSI" in guestfs(3).
1826
1827           "protocol = "nbd""
1828               Connect to the Network Block Device server.  The "server"
1829               parameter must also be supplied - see below.
1830
1831               See also: "NETWORK BLOCK DEVICE" in guestfs(3).
1832
1833           "protocol = "rbd""
1834               Connect to the Ceph (librbd/RBD) server.  The "server"
1835               parameter must also be supplied - see below.  The "username"
1836               parameter may be supplied.  See below.  The "secret" parameter
1837               may be supplied.  See below.
1838
1839               See also: "CEPH" in guestfs(3).
1840
1841           "protocol = "sheepdog""
1842               Connect to the Sheepdog server.  The "server" parameter may
1843               also be supplied - see below.
1844
1845               See also: "SHEEPDOG" in guestfs(3).
1846
1847           "protocol = "ssh""
1848               Connect to the Secure Shell (ssh) server.
1849
1850               The "server" parameter must be supplied.  The "username"
1851               parameter may be supplied.  See below.
1852
1853               See also: "SSH" in guestfs(3).
1854
1855       "server"
1856           For protocols which require access to a remote server, this is a
1857           list of server(s).
1858
1859            Protocol       Number of servers required
1860            --------       --------------------------
1861            file           List must be empty or param not used at all
1862            ftp|ftps|http|https|tftp  Exactly one
1863            gluster        Exactly one
1864            iscsi          Exactly one
1865            nbd            Exactly one
1866            rbd            Zero or more
1867            sheepdog       Zero or more
1868            ssh            Exactly one
1869
1870           Each list element is a string specifying a server.  The string must
1871           be in one of the following formats:
1872
1873            hostname
1874            hostname:port
1875            tcp:hostname
1876            tcp:hostname:port
1877            unix:/path/to/socket
1878
1879           If the port number is omitted, then the standard port number for
1880           the protocol is used (see /etc/services).
1881
1882       "username"
1883           For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
1884           "tftp" protocols, this specifies the remote username.
1885
1886           If not given, then the local username is used for "ssh", and no
1887           authentication is attempted for ceph.  But note this sometimes may
1888           give unexpected results, for example if using the libvirt backend
1889           and if the libvirt backend is configured to start the qemu
1890           appliance as a special user such as "qemu.qemu".  If in doubt,
1891           specify the remote username you want.
1892
1893       "secret"
1894           For the "rbd" protocol only, this specifies the ‘secret’ to use
1895           when connecting to the remote device.  It must be base64 encoded.
1896
1897           If not given, then a secret matching the given username will be
1898           looked up in the default keychain locations, or if no username is
1899           given, then no authentication will be used.
1900
1901       "cachemode"
1902           Choose whether or not libguestfs will obey sync operations (safe
1903           but slow) or not (unsafe but fast).  The possible values for this
1904           string are:
1905
1906           "cachemode = "writeback""
1907               This is the default.
1908
1909               Write operations in the API do not return until a write(2) call
1910               has completed in the host [but note this does not imply that
1911               anything gets written to disk].
1912
1913               Sync operations in the API, including implicit syncs caused by
1914               filesystem journalling, will not return until an fdatasync(2)
1915               call has completed in the host, indicating that data has been
1916               committed to disk.
1917
1918           "cachemode = "unsafe""
1919               In this mode, there are no guarantees.  Libguestfs may cache
1920               anything and ignore sync requests.  This is suitable only for
1921               scratch or temporary disks.
1922
1923       "discard"
1924           Enable or disable discard (a.k.a. trim or unmap) support on this
1925           drive.  If enabled, operations such as "fstrim" will be able to
1926           discard / make thin / punch holes in the underlying host file or
1927           device.
1928
1929           Possible discard settings are:
1930
1931           "discard = "disable""
1932               Disable discard support.  This is the default.
1933
1934           "discard = "enable""
1935               Enable discard support.  Fail if discard is not possible.
1936
1937           "discard = "besteffort""
1938               Enable discard support if possible, but don't fail if it is not
1939               supported.
1940
1941               Since not all backends and not all underlying systems support
1942               discard, this is a good choice if you want to use discard if
1943               possible, but don't mind if it doesn't work.
1944
1945       "copyonread"
1946           The boolean parameter "copyonread" enables copy-on-read support.
1947           This only affects disk formats which have backing files, and causes
1948           reads to be stored in the overlay layer, speeding up multiple reads
1949           of the same area of disk.
1950
1951           The default is false.
1952
1953       "blocksize"
1954           This parameter sets the sector size of the disk.  Possible values
1955           are 512 (the default if the parameter is omitted) or 4096.  Use
1956           4096 when handling an "Advanced Format" disk that uses 4K sector
1957           size (https://en.wikipedia.org/wiki/Advanced_Format).
1958
1959           Only a subset of the backends support this parameter (currently
1960           only the libvirt and direct backends do).
1961
1962       This command has one or more optional arguments.  See "OPTIONAL
1963       ARGUMENTS".
1964
1965   add-drive-ro
1966   add-ro
1967        add-drive-ro filename
1968
1969       This function is the equivalent of calling "add-drive-opts" with the
1970       optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1, so the
1971       disk is added read-only, with the format being detected automatically.
1972
1973   add-drive-ro-with-if
1974        add-drive-ro-with-if filename iface
1975
1976       This is the same as "add-drive-ro" but it allows you to specify the
1977       QEMU interface emulation to use at run time.
1978
1979       This function is deprecated.  In new code, use the "add-drive" call
1980       instead.
1981
1982       Deprecated functions will not be removed from the API, but the fact
1983       that they are deprecated indicates that there are problems with correct
1984       use of these functions.
1985
1986   add-drive-scratch
1987   scratch
1988        add-drive-scratch size [name:..] [label:..] [blocksize:N]
1989
1990       This command adds a temporary scratch drive to the handle.  The "size"
1991       parameter is the virtual size (in bytes).  The scratch drive is blank
1992       initially (all reads return zeroes until you start writing to it).  The
1993       drive is deleted when the handle is closed.
1994
1995       The optional arguments "name", "label" and "blocksize" are passed
1996       through to "add-drive-opts".
1997
1998       This command has one or more optional arguments.  See "OPTIONAL
1999       ARGUMENTS".
2000
2001   add-drive-with-if
2002        add-drive-with-if filename iface
2003
2004       This is the same as "add-drive" but it allows you to specify the QEMU
2005       interface emulation to use at run time.
2006
2007       This function is deprecated.  In new code, use the "add-drive" call
2008       instead.
2009
2010       Deprecated functions will not be removed from the API, but the fact
2011       that they are deprecated indicates that there are problems with correct
2012       use of these functions.
2013
2014   aug-clear
2015        aug-clear augpath
2016
2017       Set the value associated with "path" to "NULL".  This is the same as
2018       the augtool(1) "clear" command.
2019
2020   aug-close
2021        aug-close
2022
2023       Close the current Augeas handle and free up any resources used by it.
2024       After calling this, you have to call "aug-init" again before you can
2025       use any other Augeas functions.
2026
2027   aug-defnode
2028        aug-defnode name expr val
2029
2030       Defines a variable "name" whose value is the result of evaluating
2031       "expr".
2032
2033       If "expr" evaluates to an empty nodeset, a node is created, equivalent
2034       to calling "aug-set" "expr", "val".  "name" will be the nodeset
2035       containing that single node.
2036
2037       On success this returns a pair containing the number of nodes in the
2038       nodeset, and a boolean flag if a node was created.
2039
2040   aug-defvar
2041        aug-defvar name expr
2042
2043       Defines an Augeas variable "name" whose value is the result of
2044       evaluating "expr".  If "expr" is NULL, then "name" is undefined.
2045
2046       On success this returns the number of nodes in "expr", or 0 if "expr"
2047       evaluates to something which is not a nodeset.
2048
2049   aug-get
2050        aug-get augpath
2051
2052       Look up the value associated with "path".  If "path" matches exactly
2053       one node, the "value" is returned.
2054
2055   aug-init
2056        aug-init root flags
2057
2058       Create a new Augeas handle for editing configuration files.  If there
2059       was any previous Augeas handle associated with this guestfs session,
2060       then it is closed.
2061
2062       You must call this before using any other "aug-*" commands.
2063
2064       "root" is the filesystem root.  "root" must not be NULL, use / instead.
2065
2066       The flags are the same as the flags defined in <augeas.h>, the logical
2067       or of the following integers:
2068
2069       "AUG_SAVE_BACKUP" = 1
2070           Keep the original file with a ".augsave" extension.
2071
2072       "AUG_SAVE_NEWFILE" = 2
2073           Save changes into a file with extension ".augnew", and do not
2074           overwrite original.  Overrides "AUG_SAVE_BACKUP".
2075
2076       "AUG_TYPE_CHECK" = 4
2077           Typecheck lenses.
2078
2079           This option is only useful when debugging Augeas lenses.  Use of
2080           this option may require additional memory for the libguestfs
2081           appliance.  You may need to set the "LIBGUESTFS_MEMSIZE"
2082           environment variable or call "set-memsize".
2083
2084       "AUG_NO_STDINC" = 8
2085           Do not use standard load path for modules.
2086
2087       "AUG_SAVE_NOOP" = 16
2088           Make save a no-op, just record what would have been changed.
2089
2090       "AUG_NO_LOAD" = 32
2091           Do not load the tree in "aug-init".
2092
2093       To close the handle, you can call "aug-close".
2094
2095       To find out more about Augeas, see http://augeas.net/.
2096
2097   aug-insert
2098        aug-insert augpath label true|false
2099
2100       Create a new sibling "label" for "path", inserting it into the tree
2101       before or after "path" (depending on the boolean flag "before").
2102
2103       "path" must match exactly one existing node in the tree, and "label"
2104       must be a label, ie. not contain /, "*" or end with a bracketed index
2105       "[N]".
2106
2107   aug-label
2108        aug-label augpath
2109
2110       The label (name of the last element) of the Augeas path expression
2111       "augpath" is returned.  "augpath" must match exactly one node, else
2112       this function returns an error.
2113
2114   aug-load
2115        aug-load
2116
2117       Load files into the tree.
2118
2119       See "aug_load" in the Augeas documentation for the full gory details.
2120
2121   aug-ls
2122        aug-ls augpath
2123
2124       This is just a shortcut for listing "aug-match" "path/*" and sorting
2125       the resulting nodes into alphabetical order.
2126
2127   aug-match
2128        aug-match augpath
2129
2130       Returns a list of paths which match the path expression "path".  The
2131       returned paths are sufficiently qualified so that they match exactly
2132       one node in the current tree.
2133
2134   aug-mv
2135        aug-mv src dest
2136
2137       Move the node "src" to "dest".  "src" must match exactly one node.
2138       "dest" is overwritten if it exists.
2139
2140   aug-rm
2141        aug-rm augpath
2142
2143       Remove "path" and all of its children.
2144
2145       On success this returns the number of entries which were removed.
2146
2147   aug-save
2148        aug-save
2149
2150       This writes all pending changes to disk.
2151
2152       The flags which were passed to "aug-init" affect exactly how files are
2153       saved.
2154
2155   aug-set
2156        aug-set augpath val
2157
2158       Set the value associated with "augpath" to "val".
2159
2160       In the Augeas API, it is possible to clear a node by setting the value
2161       to NULL.  Due to an oversight in the libguestfs API you cannot do that
2162       with this call.  Instead you must use the "aug-clear" call.
2163
2164   aug-setm
2165        aug-setm base sub val
2166
2167       Change multiple Augeas nodes in a single operation.  "base" is an
2168       expression matching multiple nodes.  "sub" is a path expression
2169       relative to "base".  All nodes matching "base" are found, and then for
2170       each node, "sub" is changed to "val".  "sub" may also be "NULL" in
2171       which case the "base" nodes are modified.
2172
2173       This returns the number of nodes modified.
2174
2175   aug-transform
2176        aug-transform lens file [remove:true|false]
2177
2178       Add an Augeas transformation for the specified "lens" so it can handle
2179       "file".
2180
2181       If "remove" is true ("false" by default), then the transformation is
2182       removed.
2183
2184       This command has one or more optional arguments.  See "OPTIONAL
2185       ARGUMENTS".
2186
2187   available
2188        available 'groups ...'
2189
2190       This command is used to check the availability of some groups of
2191       functionality in the appliance, which not all builds of the libguestfs
2192       appliance will be able to provide.
2193
2194       The libguestfs groups, and the functions that those groups correspond
2195       to, are listed in "AVAILABILITY" in guestfs(3).  You can also fetch
2196       this list at runtime by calling "available-all-groups".
2197
2198       The argument "groups" is a list of group names, eg: "["inotify",
2199       "augeas"]" would check for the availability of the Linux inotify
2200       functions and Augeas (configuration file editing) functions.
2201
2202       The command returns no error if all requested groups are available.
2203
2204       It fails with an error if one or more of the requested groups is
2205       unavailable in the appliance.
2206
2207       If an unknown group name is included in the list of groups then an
2208       error is always returned.
2209
2210       Notes:
2211
2212       ·   "feature-available" is the same as this call, but with a slightly
2213           simpler to use API: that call returns a boolean true/false instead
2214           of throwing an error.
2215
2216       ·   You must call "launch" before calling this function.
2217
2218           The reason is because we don't know what groups are supported by
2219           the appliance/daemon until it is running and can be queried.
2220
2221       ·   If a group of functions is available, this does not necessarily
2222           mean that they will work.  You still have to check for errors when
2223           calling individual API functions even if they are available.
2224
2225       ·   It is usually the job of distro packagers to build complete
2226           functionality into the libguestfs appliance.  Upstream libguestfs,
2227           if built from source with all requirements satisfied, will support
2228           everything.
2229
2230       ·   This call was added in version 1.0.80.  In previous versions of
2231           libguestfs all you could do would be to speculatively execute a
2232           command to find out if the daemon implemented it.  See also
2233           "version".
2234
2235       See also "filesystem-available".
2236
2237   available-all-groups
2238        available-all-groups
2239
2240       This command returns a list of all optional groups that this daemon
2241       knows about.  Note this returns both supported and unsupported groups.
2242       To find out which ones the daemon can actually support you have to call
2243       "available" / "feature-available" on each member of the returned list.
2244
2245       See also "available", "feature-available" and "AVAILABILITY" in
2246       guestfs(3).
2247
2248   base64-in
2249        base64-in (base64file|-) filename
2250
2251       This command uploads base64-encoded data from "base64file" to filename.
2252
2253       Use "-" instead of a filename to read/write from stdin/stdout.
2254
2255   base64-out
2256        base64-out filename (base64file|-)
2257
2258       This command downloads the contents of filename, writing it out to
2259       local file "base64file" encoded as base64.
2260
2261       Use "-" instead of a filename to read/write from stdin/stdout.
2262
2263   blkdiscard
2264        blkdiscard device
2265
2266       This discards all blocks on the block device "device", giving the free
2267       space back to the host.
2268
2269       This operation requires support in libguestfs, the host filesystem,
2270       qemu and the host kernel.  If this support isn't present it may give an
2271       error or even appear to run but do nothing.  You must also set the
2272       "discard" attribute on the underlying drive (see "add-drive-opts").
2273
2274       This command depends on the feature "blkdiscard".   See also "feature-
2275       available".
2276
2277   blkdiscardzeroes
2278        blkdiscardzeroes device
2279
2280       This call returns true if blocks on "device" that have been discarded
2281       by a call to "blkdiscard" are returned as blocks of zero bytes when
2282       read the next time.
2283
2284       If it returns false, then it may be that discarded blocks are read as
2285       stale or random data.
2286
2287       This command depends on the feature "blkdiscardzeroes".   See also
2288       "feature-available".
2289
2290   blkid
2291        blkid device
2292
2293       This command returns block device attributes for "device". The
2294       following fields are usually present in the returned hash. Other fields
2295       may also be present.
2296
2297       "UUID"
2298           The uuid of this device.
2299
2300       "LABEL"
2301           The label of this device.
2302
2303       "VERSION"
2304           The version of blkid command.
2305
2306       "TYPE"
2307           The filesystem type or RAID of this device.
2308
2309       "USAGE"
2310           The usage of this device, for example "filesystem" or "raid".
2311
2312   blockdev-flushbufs
2313        blockdev-flushbufs device
2314
2315       This tells the kernel to flush internal buffers associated with
2316       "device".
2317
2318       This uses the blockdev(8) command.
2319
2320   blockdev-getbsz
2321        blockdev-getbsz device
2322
2323       This returns the block size of a device.
2324
2325       Note: this is different from both size in blocks and filesystem block
2326       size.  Also this setting is not really used by anything.  You should
2327       probably not use it for anything.  Filesystems have their own idea
2328       about what block size to choose.
2329
2330       This uses the blockdev(8) command.
2331
2332   blockdev-getro
2333        blockdev-getro device
2334
2335       Returns a boolean indicating if the block device is read-only (true if
2336       read-only, false if not).
2337
2338       This uses the blockdev(8) command.
2339
2340   blockdev-getsize64
2341        blockdev-getsize64 device
2342
2343       This returns the size of the device in bytes.
2344
2345       See also "blockdev-getsz".
2346
2347       This uses the blockdev(8) command.
2348
2349   blockdev-getss
2350        blockdev-getss device
2351
2352       This returns the size of sectors on a block device.  Usually 512, but
2353       can be larger for modern devices.
2354
2355       (Note, this is not the size in sectors, use "blockdev-getsz" for that).
2356
2357       This uses the blockdev(8) command.
2358
2359   blockdev-getsz
2360        blockdev-getsz device
2361
2362       This returns the size of the device in units of 512-byte sectors (even
2363       if the sectorsize isn't 512 bytes ... weird).
2364
2365       See also "blockdev-getss" for the real sector size of the device, and
2366       "blockdev-getsize64" for the more useful size in bytes.
2367
2368       This uses the blockdev(8) command.
2369
2370   blockdev-rereadpt
2371        blockdev-rereadpt device
2372
2373       Reread the partition table on "device".
2374
2375       This uses the blockdev(8) command.
2376
2377   blockdev-setbsz
2378        blockdev-setbsz device blocksize
2379
2380       This call does nothing and has never done anything because of a bug in
2381       blockdev.  Do not use it.
2382
2383       If you need to set the filesystem block size, use the "blocksize"
2384       option of "mkfs".
2385
2386       This function is deprecated.  There is no replacement.  Consult the API
2387       documentation in guestfs(3) for further information.
2388
2389       Deprecated functions will not be removed from the API, but the fact
2390       that they are deprecated indicates that there are problems with correct
2391       use of these functions.
2392
2393   blockdev-setra
2394        blockdev-setra device sectors
2395
2396       Set readahead (in 512-byte sectors) for the device.
2397
2398       This uses the blockdev(8) command.
2399
2400   blockdev-setro
2401        blockdev-setro device
2402
2403       Sets the block device named "device" to read-only.
2404
2405       This uses the blockdev(8) command.
2406
2407   blockdev-setrw
2408        blockdev-setrw device
2409
2410       Sets the block device named "device" to read-write.
2411
2412       This uses the blockdev(8) command.
2413
2414   btrfs-balance-cancel
2415        btrfs-balance-cancel path
2416
2417       Cancel a running balance on a btrfs filesystem.
2418
2419       This command depends on the feature "btrfs".   See also "feature-
2420       available".
2421
2422   btrfs-balance-pause
2423        btrfs-balance-pause path
2424
2425       Pause a running balance on a btrfs filesystem.
2426
2427       This command depends on the feature "btrfs".   See also "feature-
2428       available".
2429
2430   btrfs-balance-resume
2431        btrfs-balance-resume path
2432
2433       Resume a paused balance on a btrfs filesystem.
2434
2435       This command depends on the feature "btrfs".   See also "feature-
2436       available".
2437
2438   btrfs-balance-status
2439        btrfs-balance-status path
2440
2441       Show the status of a running or paused balance on a btrfs filesystem.
2442
2443       This command depends on the feature "btrfs".   See also "feature-
2444       available".
2445
2446   btrfs-device-add
2447        btrfs-device-add 'devices ...' fs
2448
2449       Add the list of device(s) in "devices" to the btrfs filesystem mounted
2450       at "fs".  If "devices" is an empty list, this does nothing.
2451
2452       This command depends on the feature "btrfs".   See also "feature-
2453       available".
2454
2455   btrfs-device-delete
2456        btrfs-device-delete 'devices ...' fs
2457
2458       Remove the "devices" from the btrfs filesystem mounted at "fs".  If
2459       "devices" is an empty list, this does nothing.
2460
2461       This command depends on the feature "btrfs".   See also "feature-
2462       available".
2463
2464   btrfs-filesystem-balance
2465   btrfs-balance
2466        btrfs-filesystem-balance fs
2467
2468       Balance the chunks in the btrfs filesystem mounted at "fs" across the
2469       underlying devices.
2470
2471       This command depends on the feature "btrfs".   See also "feature-
2472       available".
2473
2474   btrfs-filesystem-defragment
2475        btrfs-filesystem-defragment path [flush:true|false] [compress:..]
2476
2477       Defragment a file or directory on a btrfs filesystem. compress is one
2478       of zlib or lzo.
2479
2480       This command has one or more optional arguments.  See "OPTIONAL
2481       ARGUMENTS".
2482
2483       This command depends on the feature "btrfs".   See also "feature-
2484       available".
2485
2486   btrfs-filesystem-resize
2487        btrfs-filesystem-resize mountpoint [size:N]
2488
2489       This command resizes a btrfs filesystem.
2490
2491       Note that unlike other resize calls, the filesystem has to be mounted
2492       and the parameter is the mountpoint not the device (this is a
2493       requirement of btrfs itself).
2494
2495       The optional parameters are:
2496
2497       "size"
2498           The new size (in bytes) of the filesystem.  If omitted, the
2499           filesystem is resized to the maximum size.
2500
2501       See also btrfs(8).
2502
2503       This command has one or more optional arguments.  See "OPTIONAL
2504       ARGUMENTS".
2505
2506       This command depends on the feature "btrfs".   See also "feature-
2507       available".
2508
2509   btrfs-filesystem-show
2510        btrfs-filesystem-show device
2511
2512       Show all the devices where the filesystems in "device" is spanned over.
2513
2514       If not all the devices for the filesystems are present, then this
2515       function fails and the "errno" is set to "ENODEV".
2516
2517       This command depends on the feature "btrfs".   See also "feature-
2518       available".
2519
2520   btrfs-filesystem-sync
2521        btrfs-filesystem-sync fs
2522
2523       Force sync on the btrfs filesystem mounted at "fs".
2524
2525       This command depends on the feature "btrfs".   See also "feature-
2526       available".
2527
2528   btrfs-fsck
2529        btrfs-fsck device [superblock:N] [repair:true|false]
2530
2531       Used to check a btrfs filesystem, "device" is the device file where the
2532       filesystem is stored.
2533
2534       This command has one or more optional arguments.  See "OPTIONAL
2535       ARGUMENTS".
2536
2537       This command depends on the feature "btrfs".   See also "feature-
2538       available".
2539
2540   btrfs-image
2541        btrfs-image 'source ...' image [compresslevel:N]
2542
2543       This is used to create an image of a btrfs filesystem.  All data will
2544       be zeroed, but metadata and the like is preserved.
2545
2546       This command has one or more optional arguments.  See "OPTIONAL
2547       ARGUMENTS".
2548
2549       This command depends on the feature "btrfs".   See also "feature-
2550       available".
2551
2552   btrfs-qgroup-assign
2553        btrfs-qgroup-assign src dst path
2554
2555       Add qgroup "src" to parent qgroup "dst". This command can group several
2556       qgroups into a parent qgroup to share common limit.
2557
2558       This command depends on the feature "btrfs".   See also "feature-
2559       available".
2560
2561   btrfs-qgroup-create
2562        btrfs-qgroup-create qgroupid subvolume
2563
2564       Create a quota group (qgroup) for subvolume at "subvolume".
2565
2566       This command depends on the feature "btrfs".   See also "feature-
2567       available".
2568
2569   btrfs-qgroup-destroy
2570        btrfs-qgroup-destroy qgroupid subvolume
2571
2572       Destroy a quota group.
2573
2574       This command depends on the feature "btrfs".   See also "feature-
2575       available".
2576
2577   btrfs-qgroup-limit
2578        btrfs-qgroup-limit subvolume size
2579
2580       Limit the size of the subvolume with path "subvolume".
2581
2582       This command depends on the feature "btrfs".   See also "feature-
2583       available".
2584
2585   btrfs-qgroup-remove
2586        btrfs-qgroup-remove src dst path
2587
2588       Remove qgroup "src" from the parent qgroup "dst".
2589
2590       This command depends on the feature "btrfs".   See also "feature-
2591       available".
2592
2593   btrfs-qgroup-show
2594        btrfs-qgroup-show path
2595
2596       Show all subvolume quota groups in a btrfs filesystem, including their
2597       usages.
2598
2599       This command depends on the feature "btrfs".   See also "feature-
2600       available".
2601
2602   btrfs-quota-enable
2603        btrfs-quota-enable fs true|false
2604
2605       Enable or disable subvolume quota support for filesystem which contains
2606       "path".
2607
2608       This command depends on the feature "btrfs".   See also "feature-
2609       available".
2610
2611   btrfs-quota-rescan
2612        btrfs-quota-rescan fs
2613
2614       Trash all qgroup numbers and scan the metadata again with the current
2615       config.
2616
2617       This command depends on the feature "btrfs".   See also "feature-
2618       available".
2619
2620   btrfs-replace
2621        btrfs-replace srcdev targetdev mntpoint
2622
2623       Replace device of a btrfs filesystem. On a live filesystem, duplicate
2624       the data to the target device which is currently stored on the source
2625       device.  After completion of the operation, the source device is wiped
2626       out and removed from the filesystem.
2627
2628       The "targetdev" needs to be same size or larger than the "srcdev".
2629       Devices which are currently mounted are never allowed to be used as the
2630       "targetdev".
2631
2632       This command depends on the feature "btrfs".   See also "feature-
2633       available".
2634
2635   btrfs-rescue-chunk-recover
2636        btrfs-rescue-chunk-recover device
2637
2638       Recover the chunk tree of btrfs filesystem by scanning the devices one
2639       by one.
2640
2641       This command depends on the feature "btrfs".   See also "feature-
2642       available".
2643
2644   btrfs-rescue-super-recover
2645        btrfs-rescue-super-recover device
2646
2647       Recover bad superblocks from good copies.
2648
2649       This command depends on the feature "btrfs".   See also "feature-
2650       available".
2651
2652   btrfs-scrub-cancel
2653        btrfs-scrub-cancel path
2654
2655       Cancel a running scrub on a btrfs filesystem.
2656
2657       This command depends on the feature "btrfs".   See also "feature-
2658       available".
2659
2660   btrfs-scrub-resume
2661        btrfs-scrub-resume path
2662
2663       Resume a previously canceled or interrupted scrub on a btrfs
2664       filesystem.
2665
2666       This command depends on the feature "btrfs".   See also "feature-
2667       available".
2668
2669   btrfs-scrub-start
2670        btrfs-scrub-start path
2671
2672       Reads all the data and metadata on the filesystem, and uses checksums
2673       and the duplicate copies from RAID storage to identify and repair any
2674       corrupt data.
2675
2676       This command depends on the feature "btrfs".   See also "feature-
2677       available".
2678
2679   btrfs-scrub-status
2680        btrfs-scrub-status path
2681
2682       Show status of running or finished scrub on a btrfs filesystem.
2683
2684       This command depends on the feature "btrfs".   See also "feature-
2685       available".
2686
2687   btrfs-set-seeding
2688        btrfs-set-seeding device true|false
2689
2690       Enable or disable the seeding feature of a device that contains a btrfs
2691       filesystem.
2692
2693       This command depends on the feature "btrfs".   See also "feature-
2694       available".
2695
2696   btrfs-subvolume-create
2697   btrfs-subvolume-create-opts
2698        btrfs-subvolume-create dest [qgroupid:..]
2699
2700       Create a btrfs subvolume.  The "dest" argument is the destination
2701       directory and the name of the subvolume, in the form
2702       /path/to/dest/name.  The optional parameter "qgroupid" represents the
2703       qgroup which the newly created subvolume will be added to.
2704
2705       This command has one or more optional arguments.  See "OPTIONAL
2706       ARGUMENTS".
2707
2708       This command depends on the feature "btrfs".   See also "feature-
2709       available".
2710
2711   btrfs-subvolume-delete
2712        btrfs-subvolume-delete subvolume
2713
2714       Delete the named btrfs subvolume or snapshot.
2715
2716       This command depends on the feature "btrfs".   See also "feature-
2717       available".
2718
2719   btrfs-subvolume-get-default
2720        btrfs-subvolume-get-default fs
2721
2722       Get the default subvolume or snapshot of a filesystem mounted at
2723       "mountpoint".
2724
2725       This command depends on the feature "btrfs".   See also "feature-
2726       available".
2727
2728   btrfs-subvolume-list
2729        btrfs-subvolume-list fs
2730
2731       List the btrfs snapshots and subvolumes of the btrfs filesystem which
2732       is mounted at "fs".
2733
2734       This command depends on the feature "btrfs".   See also "feature-
2735       available".
2736
2737   btrfs-subvolume-set-default
2738        btrfs-subvolume-set-default id fs
2739
2740       Set the subvolume of the btrfs filesystem "fs" which will be mounted by
2741       default.  See "btrfs-subvolume-list" to get a list of subvolumes.
2742
2743       This command depends on the feature "btrfs".   See also "feature-
2744       available".
2745
2746   btrfs-subvolume-show
2747        btrfs-subvolume-show subvolume
2748
2749       Return detailed information of the subvolume.
2750
2751       This command depends on the feature "btrfs".   See also "feature-
2752       available".
2753
2754   btrfs-subvolume-snapshot
2755   btrfs-subvolume-snapshot-opts
2756        btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]
2757
2758       Create a snapshot of the btrfs subvolume "source".  The "dest" argument
2759       is the destination directory and the name of the snapshot, in the form
2760       /path/to/dest/name. By default the newly created snapshot is writable,
2761       if the value of optional parameter "ro" is true, then a readonly
2762       snapshot is created. The optional parameter "qgroupid" represents the
2763       qgroup which the newly created snapshot will be added to.
2764
2765       This command has one or more optional arguments.  See "OPTIONAL
2766       ARGUMENTS".
2767
2768       This command depends on the feature "btrfs".   See also "feature-
2769       available".
2770
2771   btrfstune-enable-extended-inode-refs
2772        btrfstune-enable-extended-inode-refs device
2773
2774       This will Enable extended inode refs.
2775
2776       This command depends on the feature "btrfs".   See also "feature-
2777       available".
2778
2779   btrfstune-enable-skinny-metadata-extent-refs
2780        btrfstune-enable-skinny-metadata-extent-refs device
2781
2782       This enable skinny metadata extent refs.
2783
2784       This command depends on the feature "btrfs".   See also "feature-
2785       available".
2786
2787   btrfstune-seeding
2788        btrfstune-seeding device true|false
2789
2790       Enable seeding of a btrfs device, this will force a fs readonly so that
2791       you can use it to build other filesystems.
2792
2793       This command depends on the feature "btrfs".   See also "feature-
2794       available".
2795
2796   c-pointer
2797        c-pointer
2798
2799       In non-C language bindings, this allows you to retrieve the underlying
2800       C pointer to the handle (ie. "h *").  The purpose of this is to allow
2801       other libraries to interwork with libguestfs.
2802
2803   canonical-device-name
2804        canonical-device-name device
2805
2806       This utility function is useful when displaying device names to the
2807       user.  It takes a number of irregular device names and returns them in
2808       a consistent format:
2809
2810       /dev/hdX
2811       /dev/vdX
2812           These are returned as /dev/sdX.  Note this works for device names
2813           and partition names.  This is approximately the reverse of the
2814           algorithm described in "BLOCK DEVICE NAMING" in guestfs(3).
2815
2816       /dev/mapper/VG-LV
2817       /dev/dm-N
2818           Converted to /dev/VG/LV form using "lvm-canonical-lv-name".
2819
2820       Other strings are returned unmodified.
2821
2822   cap-get-file
2823        cap-get-file path
2824
2825       This function returns the Linux capabilities attached to "path".  The
2826       capabilities set is returned in text form (see cap_to_text(3)).
2827
2828       If no capabilities are attached to a file, an empty string is returned.
2829
2830       This command depends on the feature "linuxcaps".   See also "feature-
2831       available".
2832
2833   cap-set-file
2834        cap-set-file path cap
2835
2836       This function sets the Linux capabilities attached to "path".  The
2837       capabilities set "cap" should be passed in text form (see
2838       cap_from_text(3)).
2839
2840       This command depends on the feature "linuxcaps".   See also "feature-
2841       available".
2842
2843   case-sensitive-path
2844        case-sensitive-path path
2845
2846       This can be used to resolve case insensitive paths on a filesystem
2847       which is case sensitive.  The use case is to resolve paths which you
2848       have read from Windows configuration files or the Windows Registry, to
2849       the true path.
2850
2851       The command handles a peculiarity of the Linux ntfs-3g filesystem
2852       driver (and probably others), which is that although the underlying
2853       filesystem is case-insensitive, the driver exports the filesystem to
2854       Linux as case-sensitive.
2855
2856       One consequence of this is that special directories such as C:\windows
2857       may appear as /WINDOWS or /windows (or other things) depending on the
2858       precise details of how they were created.  In Windows itself this would
2859       not be a problem.
2860
2861       Bug or feature?  You decide:
2862       https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
2863
2864       "case-sensitive-path" attempts to resolve the true case of each element
2865       in the path. It will return a resolved path if either the full path or
2866       its parent directory exists. If the parent directory exists but the
2867       full path does not, the case of the parent directory will be correctly
2868       resolved, and the remainder appended unmodified. For example, if the
2869       file "/Windows/System32/netkvm.sys" exists:
2870
2871       "case-sensitive-path" ("/windows/system32/netkvm.sys")
2872           "Windows/System32/netkvm.sys"
2873
2874       "case-sensitive-path" ("/windows/system32/NoSuchFile")
2875           "Windows/System32/NoSuchFile"
2876
2877       "case-sensitive-path" ("/windows/system33/netkvm.sys")
2878           ERROR
2879
2880       Note: Because of the above behaviour, "case-sensitive-path" cannot be
2881       used to check for the existence of a file.
2882
2883       Note: This function does not handle drive names, backslashes etc.
2884
2885       See also "realpath".
2886
2887   cat
2888        cat path
2889
2890       Return the contents of the file named "path".
2891
2892       Because, in C, this function returns a "char *", there is no way to
2893       differentiate between a "\0" character in a file and end of string.  To
2894       handle binary files, use the "read-file" or "download" functions.
2895
2896   checksum
2897        checksum csumtype path
2898
2899       This call computes the MD5, SHAx or CRC checksum of the file named
2900       "path".
2901
2902       The type of checksum to compute is given by the "csumtype" parameter
2903       which must have one of the following values:
2904
2905       "crc"
2906           Compute the cyclic redundancy check (CRC) specified by POSIX for
2907           the "cksum" command.
2908
2909       "md5"
2910           Compute the MD5 hash (using the md5sum(1) program).
2911
2912       "sha1"
2913           Compute the SHA1 hash (using the sha1sum(1) program).
2914
2915       "sha224"
2916           Compute the SHA224 hash (using the sha224sum(1) program).
2917
2918       "sha256"
2919           Compute the SHA256 hash (using the sha256sum(1) program).
2920
2921       "sha384"
2922           Compute the SHA384 hash (using the sha384sum(1) program).
2923
2924       "sha512"
2925           Compute the SHA512 hash (using the sha512sum(1) program).
2926
2927       The checksum is returned as a printable string.
2928
2929       To get the checksum for a device, use "checksum-device".
2930
2931       To get the checksums for many files, use "checksums-out".
2932
2933   checksum-device
2934        checksum-device csumtype device
2935
2936       This call computes the MD5, SHAx or CRC checksum of the contents of the
2937       device named "device".  For the types of checksums supported see the
2938       "checksum" command.
2939
2940   checksums-out
2941        checksums-out csumtype directory (sumsfile|-)
2942
2943       This command computes the checksums of all regular files in directory
2944       and then emits a list of those checksums to the local output file
2945       "sumsfile".
2946
2947       This can be used for verifying the integrity of a virtual machine.
2948       However to be properly secure you should pay attention to the output of
2949       the checksum command (it uses the ones from GNU coreutils).  In
2950       particular when the filename is not printable, coreutils uses a special
2951       backslash syntax.  For more information, see the GNU coreutils info
2952       file.
2953
2954       Use "-" instead of a filename to read/write from stdin/stdout.
2955
2956   chmod
2957        chmod mode path
2958
2959       Change the mode (permissions) of "path" to "mode".  Only numeric modes
2960       are supported.
2961
2962       Note: When using this command from guestfish, "mode" by default would
2963       be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
2964       700.
2965
2966       The mode actually set is affected by the umask.
2967
2968   chown
2969        chown owner group path
2970
2971       Change the file owner to "owner" and group to "group".
2972
2973       Only numeric uid and gid are supported.  If you want to use names, you
2974       will need to locate and parse the password file yourself (Augeas
2975       support makes this relatively easy).
2976
2977   clear-backend-setting
2978        clear-backend-setting name
2979
2980       If there is a backend setting string matching "name" or beginning with
2981       "name=", then that string is removed from the backend settings.
2982
2983       This call returns the number of strings which were removed (which may
2984       be 0, 1 or greater than 1).
2985
2986       See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
2987
2988   command
2989        command 'arguments ...'
2990
2991       This call runs a command from the guest filesystem.  The filesystem
2992       must be mounted, and must contain a compatible operating system (ie.
2993       something Linux, with the same or compatible processor architecture).
2994
2995       The single parameter is an argv-style list of arguments.  The first
2996       element is the name of the program to run.  Subsequent elements are
2997       parameters.  The list must be non-empty (ie. must contain a program
2998       name).  Note that the command runs directly, and is not invoked via the
2999       shell (see "sh").
3000
3001       The return value is anything printed to stdout by the command.
3002
3003       If the command returns a non-zero exit status, then this function
3004       returns an error message.  The error message string is the content of
3005       stderr from the command.
3006
3007       The $PATH environment variable will contain at least /usr/bin and /bin.
3008       If you require a program from another location, you should provide the
3009       full path in the first parameter.
3010
3011       Shared libraries and data files required by the program must be
3012       available on filesystems which are mounted in the correct places.  It
3013       is the caller’s responsibility to ensure all filesystems that are
3014       needed are mounted at the right locations.
3015
3016       Because of the message protocol, there is a transfer limit of somewhere
3017       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3018
3019   command-lines
3020        command-lines 'arguments ...'
3021
3022       This is the same as "command", but splits the result into a list of
3023       lines.
3024
3025       See also: "sh-lines"
3026
3027       Because of the message protocol, there is a transfer limit of somewhere
3028       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3029
3030   compress-device-out
3031        compress-device-out ctype device (zdevice|-) [level:N]
3032
3033       This command compresses "device" and writes it out to the local file
3034       "zdevice".
3035
3036       The "ctype" and optional "level" parameters have the same meaning as in
3037       "compress-out".
3038
3039       Use "-" instead of a filename to read/write from stdin/stdout.
3040
3041       This command has one or more optional arguments.  See "OPTIONAL
3042       ARGUMENTS".
3043
3044   compress-out
3045        compress-out ctype file (zfile|-) [level:N]
3046
3047       This command compresses file and writes it out to the local file zfile.
3048
3049       The compression program used is controlled by the "ctype" parameter.
3050       Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
3051       Some compression types may not be supported by particular builds of
3052       libguestfs, in which case you will get an error containing the
3053       substring "not supported".
3054
3055       The optional "level" parameter controls compression level.  The meaning
3056       and default for this parameter depends on the compression program being
3057       used.
3058
3059       Use "-" instead of a filename to read/write from stdin/stdout.
3060
3061       This command has one or more optional arguments.  See "OPTIONAL
3062       ARGUMENTS".
3063
3064   config
3065        config hvparam hvvalue
3066
3067       This can be used to add arbitrary hypervisor parameters of the form
3068       -param value.  Actually it’s not quite arbitrary - we prevent you from
3069       setting some parameters which would interfere with parameters that we
3070       use.
3071
3072       The first character of "hvparam" string must be a "-" (dash).
3073
3074       "hvvalue" can be NULL.
3075
3076   copy-attributes
3077        copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]
3078
3079       Copy the attributes of a path (which can be a file or a directory) to
3080       another path.
3081
3082       By default no attribute is copied, so make sure to specify any (or
3083       "all" to copy everything).
3084
3085       The optional arguments specify which attributes can be copied:
3086
3087       "mode"
3088           Copy part of the file mode from "source" to "destination". Only the
3089           UNIX permissions and the sticky/setuid/setgid bits can be copied.
3090
3091       "xattributes"
3092           Copy the Linux extended attributes (xattrs) from "source" to
3093           "destination".  This flag does nothing if the linuxxattrs feature
3094           is not available (see "feature-available").
3095
3096       "ownership"
3097           Copy the owner uid and the group gid of "source" to "destination".
3098
3099       "all"
3100           Copy all the attributes from "source" to "destination". Enabling it
3101           enables all the other flags, if they are not specified already.
3102
3103       This command has one or more optional arguments.  See "OPTIONAL
3104       ARGUMENTS".
3105
3106   copy-device-to-device
3107        copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3108
3109       The four calls "copy-device-to-device", "copy-device-to-file", "copy-
3110       file-to-device", and "copy-file-to-file" let you copy from a source
3111       (device|file) to a destination (device|file).
3112
3113       Partial copies can be made since you can specify optionally the source
3114       offset, destination offset and size to copy.  These values are all
3115       specified in bytes.  If not given, the offsets both default to zero,
3116       and the size defaults to copying as much as possible until we hit the
3117       end of the source.
3118
3119       The source and destination may be the same object.  However overlapping
3120       regions may not be copied correctly.
3121
3122       If the destination is a file, it is created if required.  If the
3123       destination file is not large enough, it is extended.
3124
3125       If the destination is a file and the "append" flag is not set, then the
3126       destination file is truncated.  If the "append" flag is set, then the
3127       copy appends to the destination file.  The "append" flag currently
3128       cannot be set for devices.
3129
3130       If the "sparse" flag is true then the call avoids writing blocks that
3131       contain only zeroes, which can help in some situations where the
3132       backing disk is thin-provisioned.  Note that unless the target is
3133       already zeroed, using this option will result in incorrect copying.
3134
3135       This command has one or more optional arguments.  See "OPTIONAL
3136       ARGUMENTS".
3137
3138   copy-device-to-file
3139        copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3140
3141       See "copy-device-to-device" for a general overview of this call.
3142
3143       This command has one or more optional arguments.  See "OPTIONAL
3144       ARGUMENTS".
3145
3146   copy-file-to-device
3147        copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3148
3149       See "copy-device-to-device" for a general overview of this call.
3150
3151       This command has one or more optional arguments.  See "OPTIONAL
3152       ARGUMENTS".
3153
3154   copy-file-to-file
3155        copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]
3156
3157       See "copy-device-to-device" for a general overview of this call.
3158
3159       This is not the function you want for copying files.  This is for
3160       copying blocks within existing files.  See "cp", "cp-a" and "mv" for
3161       general file copying and moving functions.
3162
3163       This command has one or more optional arguments.  See "OPTIONAL
3164       ARGUMENTS".
3165
3166   copy-size
3167        copy-size src dest size
3168
3169       This command copies exactly "size" bytes from one source device or file
3170       "src" to another destination device or file "dest".
3171
3172       Note this will fail if the source is too short or if the destination is
3173       not large enough.
3174
3175       This function is deprecated.  In new code, use the "copy-device-to-
3176       device" call instead.
3177
3178       Deprecated functions will not be removed from the API, but the fact
3179       that they are deprecated indicates that there are problems with correct
3180       use of these functions.
3181
3182   cp
3183        cp src dest
3184
3185       This copies a file from "src" to "dest" where "dest" is either a
3186       destination filename or destination directory.
3187
3188   cp-a
3189        cp-a src dest
3190
3191       This copies a file or directory from "src" to "dest" recursively using
3192       the "cp -a" command.
3193
3194   cp-r
3195        cp-r src dest
3196
3197       This copies a file or directory from "src" to "dest" recursively using
3198       the "cp -rP" command.
3199
3200       Most users should use "cp-a" instead.  This command is useful when you
3201       don't want to preserve permissions, because the target filesystem does
3202       not support it (primarily when writing to DOS FAT filesystems).
3203
3204   cpio-out
3205        cpio-out directory (cpiofile|-) [format:..]
3206
3207       This command packs the contents of directory and downloads it to local
3208       file "cpiofile".
3209
3210       The optional "format" parameter can be used to select the format.  Only
3211       the following formats are currently permitted:
3212
3213       "newc"
3214           New (SVR4) portable format.  This format happens to be compatible
3215           with the cpio-like format used by the Linux kernel for initramfs.
3216
3217           This is the default format.
3218
3219       "crc"
3220           New (SVR4) portable format with a checksum.
3221
3222       Use "-" instead of a filename to read/write from stdin/stdout.
3223
3224       This command has one or more optional arguments.  See "OPTIONAL
3225       ARGUMENTS".
3226
3227   dd
3228        dd src dest
3229
3230       This command copies from one source device or file "src" to another
3231       destination device or file "dest".  Normally you would use this to copy
3232       to or from a device or partition, for example to duplicate a
3233       filesystem.
3234
3235       If the destination is a device, it must be as large or larger than the
3236       source file or device, otherwise the copy will fail.  This command
3237       cannot do partial copies (see "copy-device-to-device").
3238
3239       This function is deprecated.  In new code, use the "copy-device-to-
3240       device" call instead.
3241
3242       Deprecated functions will not be removed from the API, but the fact
3243       that they are deprecated indicates that there are problems with correct
3244       use of these functions.
3245
3246   device-index
3247        device-index device
3248
3249       This function takes a device name (eg. "/dev/sdb") and returns the
3250       index of the device in the list of devices.
3251
3252       Index numbers start from 0.  The named device must exist, for example
3253       as a string returned from "list-devices".
3254
3255       See also "list-devices", "part-to-dev".
3256
3257   df
3258        df
3259
3260       This command runs the df(1) command to report disk space used.
3261
3262       This command is mostly useful for interactive sessions.  It is not
3263       intended that you try to parse the output string.  Use "statvfs" from
3264       programs.
3265
3266   df-h
3267        df-h
3268
3269       This command runs the "df -h" command to report disk space used in
3270       human-readable format.
3271
3272       This command is mostly useful for interactive sessions.  It is not
3273       intended that you try to parse the output string.  Use "statvfs" from
3274       programs.
3275
3276   disk-create
3277        disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]
3278
3279       Create a blank disk image called filename (a host file) with format
3280       "format" (usually "raw" or "qcow2").  The size is "size" bytes.
3281
3282       If used with the optional "backingfile" parameter, then a snapshot is
3283       created on top of the backing file.  In this case, "size" must be
3284       passed as "-1".  The size of the snapshot is the same as the size of
3285       the backing file, which is discovered automatically.  You are
3286       encouraged to also pass "backingformat" to describe the format of
3287       "backingfile".
3288
3289       If filename refers to a block device, then the device is formatted.
3290       The "size" is ignored since block devices have an intrinsic size.
3291
3292       The other optional parameters are:
3293
3294       "preallocation"
3295           If format is "raw", then this can be either "off" (or "sparse") or
3296           "full" to create a sparse or fully allocated file respectively.
3297           The default is "off".
3298
3299           If format is "qcow2", then this can be "off" (or "sparse"),
3300           "metadata" or "full".  Preallocating metadata can be faster when
3301           doing lots of writes, but uses more space.  The default is "off".
3302
3303       "compat"
3304           "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
3305           supported by qemu ≥ 1.1.
3306
3307       "clustersize"
3308           "qcow2" only: Change the qcow2 cluster size.  The default is 65536
3309           (bytes) and this setting may be any power of two between 512 and
3310           2097152.
3311
3312       Note that this call does not add the new disk to the handle.  You may
3313       need to call "add-drive-opts" separately.
3314
3315       This command has one or more optional arguments.  See "OPTIONAL
3316       ARGUMENTS".
3317
3318   disk-format
3319        disk-format filename
3320
3321       Detect and return the format of the disk image called filename.
3322       filename can also be a host device, etc.  If the format of the image
3323       could not be detected, then "unknown" is returned.
3324
3325       Note that detecting the disk format can be insecure under some
3326       circumstances.  See "CVE-2010-3851" in guestfs(3).
3327
3328       See also: "DISK IMAGE FORMATS" in guestfs(3)
3329
3330   disk-has-backing-file
3331        disk-has-backing-file filename
3332
3333       Detect and return whether the disk image filename has a backing file.
3334
3335       Note that detecting disk features can be insecure under some
3336       circumstances.  See "CVE-2010-3851" in guestfs(3).
3337
3338   disk-virtual-size
3339        disk-virtual-size filename
3340
3341       Detect and return the virtual size in bytes of the disk image called
3342       filename.
3343
3344       Note that detecting disk features can be insecure under some
3345       circumstances.  See "CVE-2010-3851" in guestfs(3).
3346
3347   dmesg
3348        dmesg
3349
3350       This returns the kernel messages (dmesg(1) output) from the guest
3351       kernel.  This is sometimes useful for extended debugging of problems.
3352
3353       Another way to get the same information is to enable verbose messages
3354       with "set-verbose" or by setting the environment variable
3355       "LIBGUESTFS_DEBUG=1" before running the program.
3356
3357   download
3358        download remotefilename (filename|-)
3359
3360       Download file remotefilename and save it as filename on the local
3361       machine.
3362
3363       filename can also be a named pipe.
3364
3365       See also "upload", "cat".
3366
3367       Use "-" instead of a filename to read/write from stdin/stdout.
3368
3369   download-blocks
3370        download-blocks device start stop (filename|-) [unallocated:true|false]
3371
3372       Download the data units from start address to stop from the disk
3373       partition (eg. /dev/sda1) and save them as filename on the local
3374       machine.
3375
3376       The use of this API on sparse disk image formats such as QCOW, may
3377       result in large zero-filled files downloaded on the host.
3378
3379       The size of a data unit varies across filesystem implementations.  On
3380       NTFS filesystems data units are referred as clusters while on ExtX ones
3381       they are referred as fragments.
3382
3383       If the optional "unallocated" flag is true (default is false), only the
3384       unallocated blocks will be extracted.  This is useful to detect hidden
3385       data or to retrieve deleted files which data units have not been
3386       overwritten yet.
3387
3388       Use "-" instead of a filename to read/write from stdin/stdout.
3389
3390       This command has one or more optional arguments.  See "OPTIONAL
3391       ARGUMENTS".
3392
3393       This command depends on the feature "sleuthkit".   See also "feature-
3394       available".
3395
3396   download-inode
3397        download-inode device inode (filename|-)
3398
3399       Download a file given its inode from the disk partition (eg. /dev/sda1)
3400       and save it as filename on the local machine.
3401
3402       It is not required to mount the disk to run this command.
3403
3404       The command is capable of downloading deleted or inaccessible files.
3405
3406       Use "-" instead of a filename to read/write from stdin/stdout.
3407
3408       This command depends on the feature "sleuthkit".   See also "feature-
3409       available".
3410
3411   download-offset
3412        download-offset remotefilename (filename|-) offset size
3413
3414       Download file remotefilename and save it as filename on the local
3415       machine.
3416
3417       remotefilename is read for "size" bytes starting at "offset" (this
3418       region must be within the file or device).
3419
3420       Note that there is no limit on the amount of data that can be
3421       downloaded with this call, unlike with "pread", and this call always
3422       reads the full amount unless an error occurs.
3423
3424       See also "download", "pread".
3425
3426       Use "-" instead of a filename to read/write from stdin/stdout.
3427
3428   drop-caches
3429        drop-caches whattodrop
3430
3431       This instructs the guest kernel to drop its page cache, and/or dentries
3432       and inode caches.  The parameter "whattodrop" tells the kernel what
3433       precisely to drop, see https://linux-mm.org/Drop_Caches
3434
3435       Setting "whattodrop" to 3 should drop everything.
3436
3437       This automatically calls sync(2) before the operation, so that the
3438       maximum guest memory is freed.
3439
3440   du
3441        du path
3442
3443       This command runs the "du -s" command to estimate file space usage for
3444       "path".
3445
3446       "path" can be a file or a directory.  If "path" is a directory then the
3447       estimate includes the contents of the directory and all subdirectories
3448       (recursively).
3449
3450       The result is the estimated size in kilobytes (ie. units of 1024
3451       bytes).
3452
3453   e2fsck
3454        e2fsck device [correct:true|false] [forceall:true|false]
3455
3456       This runs the ext2/ext3 filesystem checker on "device".  It can take
3457       the following optional arguments:
3458
3459       "correct"
3460           Automatically repair the file system. This option will cause e2fsck
3461           to automatically fix any filesystem problems that can be safely
3462           fixed without human intervention.
3463
3464           This option may not be specified at the same time as the "forceall"
3465           option.
3466
3467       "forceall"
3468           Assume an answer of ‘yes’ to all questions; allows e2fsck to be
3469           used non-interactively.
3470
3471           This option may not be specified at the same time as the "correct"
3472           option.
3473
3474       This command has one or more optional arguments.  See "OPTIONAL
3475       ARGUMENTS".
3476
3477   e2fsck-f
3478        e2fsck-f device
3479
3480       This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
3481       checker on "device", noninteractively (-p), even if the filesystem
3482       appears to be clean (-f).
3483
3484       This function is deprecated.  In new code, use the "e2fsck" call
3485       instead.
3486
3487       Deprecated functions will not be removed from the API, but the fact
3488       that they are deprecated indicates that there are problems with correct
3489       use of these functions.
3490
3491   echo-daemon
3492        echo-daemon 'words ...'
3493
3494       This command concatenates the list of "words" passed with single spaces
3495       between them and returns the resulting string.
3496
3497       You can use this command to test the connection through to the daemon.
3498
3499       See also "ping-daemon".
3500
3501   egrep
3502        egrep regex path
3503
3504       This calls the external egrep(1) program and returns the matching
3505       lines.
3506
3507       Because of the message protocol, there is a transfer limit of somewhere
3508       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3509
3510       This function is deprecated.  In new code, use the "grep" call instead.
3511
3512       Deprecated functions will not be removed from the API, but the fact
3513       that they are deprecated indicates that there are problems with correct
3514       use of these functions.
3515
3516   egrepi
3517        egrepi regex path
3518
3519       This calls the external "egrep -i" program and returns the matching
3520       lines.
3521
3522       Because of the message protocol, there is a transfer limit of somewhere
3523       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3524
3525       This function is deprecated.  In new code, use the "grep" call instead.
3526
3527       Deprecated functions will not be removed from the API, but the fact
3528       that they are deprecated indicates that there are problems with correct
3529       use of these functions.
3530
3531   equal
3532        equal file1 file2
3533
3534       This compares the two files file1 and file2 and returns true if their
3535       content is exactly equal, or false otherwise.
3536
3537       The external cmp(1) program is used for the comparison.
3538
3539   exists
3540        exists path
3541
3542       This returns "true" if and only if there is a file, directory (or
3543       anything) with the given "path" name.
3544
3545       See also "is-file", "is-dir", "stat".
3546
3547   extlinux
3548        extlinux directory
3549
3550       Install the SYSLINUX bootloader on the device mounted at directory.
3551       Unlike "syslinux" which requires a FAT filesystem, this can be used on
3552       an ext2/3/4 or btrfs filesystem.
3553
3554       The directory parameter can be either a mountpoint, or a directory
3555       within the mountpoint.
3556
3557       You also have to mark the partition as "active" ("part-set-bootable")
3558       and a Master Boot Record must be installed (eg. using "pwrite-device")
3559       on the first sector of the whole disk.  The SYSLINUX package comes with
3560       some suitable Master Boot Records.  See the extlinux(1) man page for
3561       further information.
3562
3563       Additional configuration can be supplied to SYSLINUX by placing a file
3564       called extlinux.conf on the filesystem under directory.  For further
3565       information about the contents of this file, see extlinux(1).
3566
3567       See also "syslinux".
3568
3569       This command depends on the feature "extlinux".   See also "feature-
3570       available".
3571
3572   f2fs-expand
3573        f2fs-expand device
3574
3575       This expands a f2fs filesystem to match the size of the underlying
3576       device.
3577
3578       This command depends on the feature "f2fs".   See also "feature-
3579       available".
3580
3581   fallocate
3582        fallocate path len
3583
3584       This command preallocates a file (containing zero bytes) named "path"
3585       of size "len" bytes.  If the file exists already, it is overwritten.
3586
3587       Do not confuse this with the guestfish-specific "alloc" command which
3588       allocates a file in the host and attaches it as a device.
3589
3590       This function is deprecated.  In new code, use the "fallocate64" call
3591       instead.
3592
3593       Deprecated functions will not be removed from the API, but the fact
3594       that they are deprecated indicates that there are problems with correct
3595       use of these functions.
3596
3597   fallocate64
3598        fallocate64 path len
3599
3600       This command preallocates a file (containing zero bytes) named "path"
3601       of size "len" bytes.  If the file exists already, it is overwritten.
3602
3603       Note that this call allocates disk blocks for the file.  To create a
3604       sparse file use "truncate-size" instead.
3605
3606       The deprecated call "fallocate" does the same, but owing to an
3607       oversight it only allowed 30 bit lengths to be specified, effectively
3608       limiting the maximum size of files created through that call to 1GB.
3609
3610       Do not confuse this with the guestfish-specific "alloc" and "sparse"
3611       commands which create a file in the host and attach it as a device.
3612
3613   feature-available
3614        feature-available 'groups ...'
3615
3616       This is the same as "available", but unlike that call it returns a
3617       simple true/false boolean result, instead of throwing an exception if a
3618       feature is not found.  For other documentation see "available".
3619
3620   fgrep
3621        fgrep pattern path
3622
3623       This calls the external fgrep(1) program and returns the matching
3624       lines.
3625
3626       Because of the message protocol, there is a transfer limit of somewhere
3627       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3628
3629       This function is deprecated.  In new code, use the "grep" call instead.
3630
3631       Deprecated functions will not be removed from the API, but the fact
3632       that they are deprecated indicates that there are problems with correct
3633       use of these functions.
3634
3635   fgrepi
3636        fgrepi pattern path
3637
3638       This calls the external "fgrep -i" program and returns the matching
3639       lines.
3640
3641       Because of the message protocol, there is a transfer limit of somewhere
3642       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
3643
3644       This function is deprecated.  In new code, use the "grep" call instead.
3645
3646       Deprecated functions will not be removed from the API, but the fact
3647       that they are deprecated indicates that there are problems with correct
3648       use of these functions.
3649
3650   file
3651        file path
3652
3653       This call uses the standard file(1) command to determine the type or
3654       contents of the file.
3655
3656       This call will also transparently look inside various types of
3657       compressed file.
3658
3659       The exact command which runs is "file -zb path".  Note in particular
3660       that the filename is not prepended to the output (the -b option).
3661
3662       The output depends on the output of the underlying file(1) command and
3663       it can change in future in ways beyond our control.  In other words,
3664       the output is not guaranteed by the ABI.
3665
3666       See also: file(1), "vfs-type", "lstat", "is-file", "is-blockdev" (etc),
3667       "is-zero".
3668
3669   file-architecture
3670        file-architecture filename
3671
3672       This detects the architecture of the binary filename, and returns it if
3673       known.
3674
3675       Currently defined architectures are:
3676
3677       "aarch64"
3678           64 bit ARM.
3679
3680       "arm"
3681           32 bit ARM.
3682
3683       "i386"
3684           This string is returned for all 32 bit i386, i486, i586, i686
3685           binaries irrespective of the precise processor requirements of the
3686           binary.
3687
3688       "ia64"
3689           Intel Itanium.
3690
3691       "ppc"
3692           32 bit Power PC.
3693
3694       "ppc64"
3695           64 bit Power PC (big endian).
3696
3697       "ppc64le"
3698           64 bit Power PC (little endian).
3699
3700       "riscv32"
3701       "riscv64"
3702       "riscv128"
3703           RISC-V 32-, 64- or 128-bit variants.
3704
3705       "s390"
3706           31 bit IBM S/390.
3707
3708       "s390x"
3709           64 bit IBM S/390.
3710
3711       "sparc"
3712           32 bit SPARC.
3713
3714       "sparc64"
3715           64 bit SPARC V9 and above.
3716
3717       "x86_64"
3718           64 bit x86-64.
3719
3720       Libguestfs may return other architecture strings in future.
3721
3722       The function works on at least the following types of files:
3723
3724       ·   many types of Un*x and Linux binary
3725
3726       ·   many types of Un*x and Linux shared library
3727
3728       ·   Windows Win32 and Win64 binaries
3729
3730       ·   Windows Win32 and Win64 DLLs
3731
3732           Win32 binaries and DLLs return "i386".
3733
3734           Win64 binaries and DLLs return "x86_64".
3735
3736       ·   Linux kernel modules
3737
3738       ·   Linux new-style initrd images
3739
3740       ·   some non-x86 Linux vmlinuz kernels
3741
3742       What it can't do currently:
3743
3744       ·   static libraries (libfoo.a)
3745
3746       ·   Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
3747
3748       ·   x86 Linux vmlinuz kernels
3749
3750           x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
3751           and compressed code, and are horribly hard to unpack.  If you want
3752           to find the architecture of a kernel, use the architecture of the
3753           associated initrd or kernel module(s) instead.
3754
3755   filesize
3756        filesize file
3757
3758       This command returns the size of file in bytes.
3759
3760       To get other stats about a file, use "stat", "lstat", "is-dir", "is-
3761       file" etc.  To get the size of block devices, use "blockdev-getsize64".
3762
3763   filesystem-available
3764        filesystem-available filesystem
3765
3766       Check whether libguestfs supports the named filesystem.  The argument
3767       "filesystem" is a filesystem name, such as "ext3".
3768
3769       You must call "launch" before using this command.
3770
3771       This is mainly useful as a negative test.  If this returns true, it
3772       doesn't mean that a particular filesystem can be created or mounted,
3773       since filesystems can fail for other reasons such as it being a later
3774       version of the filesystem, or having incompatible features, or lacking
3775       the right mkfs.<fs> tool.
3776
3777       See also "available", "feature-available", "AVAILABILITY" in
3778       guestfs(3).
3779
3780   filesystem-walk
3781        filesystem-walk device
3782
3783       Walk through the internal structures of a disk partition (eg.
3784       /dev/sda1) in order to return a list of all the files and directories
3785       stored within.
3786
3787       It is not necessary to mount the disk partition to run this command.
3788
3789       All entries in the filesystem are returned. This function can list
3790       deleted or unaccessible files. The entries are not sorted.
3791
3792       The "tsk_dirent" structure contains the following fields.
3793
3794       "tsk_inode"
3795           Filesystem reference number of the node. It might be 0 if the node
3796           has been deleted.
3797
3798       "tsk_type"
3799           Basic file type information.  See below for a detailed list of
3800           values.
3801
3802       "tsk_size"
3803           File size in bytes. It might be "-1" if the node has been deleted.
3804
3805       "tsk_name"
3806           The file path relative to its directory.
3807
3808       "tsk_flags"
3809           Bitfield containing extra information regarding the entry.  It
3810           contains the logical OR of the following values:
3811
3812           0x0001
3813               If set to 1, the file is allocated and visible within the
3814               filesystem.  Otherwise, the file has been deleted.  Under
3815               certain circumstances, the function "download_inode" can be
3816               used to recover deleted files.
3817
3818           0x0002
3819               Filesystem such as NTFS and Ext2 or greater, separate the file
3820               name from the metadata structure.  The bit is set to 1 when the
3821               file name is in an unallocated state and the metadata structure
3822               is in an allocated one.  This generally implies the metadata
3823               has been reallocated to a new file.  Therefore, information
3824               such as file type, file size, timestamps, number of links and
3825               symlink target might not correspond with the ones of the
3826               original deleted entry.
3827
3828           0x0004
3829               The bit is set to 1 when the file is compressed using
3830               filesystem native compression support (NTFS). The API is not
3831               able to detect application level compression.
3832
3833       "tsk_atime_sec"
3834       "tsk_atime_nsec"
3835       "tsk_mtime_sec"
3836       "tsk_mtime_nsec"
3837       "tsk_ctime_sec"
3838       "tsk_ctime_nsec"
3839       "tsk_crtime_sec"
3840       "tsk_crtime_nsec"
3841           Respectively, access, modification, last status change and creation
3842           time in Unix format in seconds and nanoseconds.
3843
3844       "tsk_nlink"
3845           Number of file names pointing to this entry.
3846
3847       "tsk_link"
3848           If the entry is a symbolic link, this field will contain the path
3849           to the target file.
3850
3851       The "tsk_type" field will contain one of the following characters:
3852
3853       'b' Block special
3854
3855       'c' Char special
3856
3857       'd' Directory
3858
3859       'f' FIFO (named pipe)
3860
3861       'l' Symbolic link
3862
3863       'r' Regular file
3864
3865       's' Socket
3866
3867       'h' Shadow inode (Solaris)
3868
3869       'w' Whiteout inode (BSD)
3870
3871       'u' Unknown file type
3872
3873       This command depends on the feature "libtsk".   See also "feature-
3874       available".
3875
3876   fill
3877        fill c len path
3878
3879       This command creates a new file called "path".  The initial content of
3880       the file is "len" octets of "c", where "c" must be a number in the
3881       range "[0..255]".
3882
3883       To fill a file with zero bytes (sparsely), it is much more efficient to
3884       use "truncate-size".  To create a file with a pattern of repeating
3885       bytes use "fill-pattern".
3886
3887   fill-dir
3888        fill-dir dir nr
3889
3890       This function, useful for testing filesystems, creates "nr" empty files
3891       in the directory "dir" with names 00000000 through "nr-1" (ie. each
3892       file name is 8 digits long padded with zeroes).
3893
3894   fill-pattern
3895        fill-pattern pattern len path
3896
3897       This function is like "fill" except that it creates a new file of
3898       length "len" containing the repeating pattern of bytes in "pattern".
3899       The pattern is truncated if necessary to ensure the length of the file
3900       is exactly "len" bytes.
3901
3902   find
3903        find directory
3904
3905       This command lists out all files and directories, recursively, starting
3906       at directory.  It is essentially equivalent to running the shell
3907       command "find directory -print" but some post-processing happens on the
3908       output, described below.
3909
3910       This returns a list of strings without any prefix.  Thus if the
3911       directory structure was:
3912
3913        /tmp/a
3914        /tmp/b
3915        /tmp/c/d
3916
3917       then the returned list from "find" /tmp would be 4 elements:
3918
3919        a
3920        b
3921        c
3922        c/d
3923
3924       If directory is not a directory, then this command returns an error.
3925
3926       The returned list is sorted.
3927
3928   find0
3929        find0 directory (files|-)
3930
3931       This command lists out all files and directories, recursively, starting
3932       at directory, placing the resulting list in the external file called
3933       files.
3934
3935       This command works the same way as "find" with the following
3936       exceptions:
3937
3938       ·   The resulting list is written to an external file.
3939
3940       ·   Items (filenames) in the result are separated by "\0" characters.
3941           See find(1) option -print0.
3942
3943       ·   The result list is not sorted.
3944
3945       Use "-" instead of a filename to read/write from stdin/stdout.
3946
3947   find-inode
3948        find-inode device inode
3949
3950       Searches all the entries associated with the given inode.
3951
3952       For each entry, a "tsk_dirent" structure is returned.  See
3953       "filesystem_walk" for more information about "tsk_dirent" structures.
3954
3955       This command depends on the feature "libtsk".   See also "feature-
3956       available".
3957
3958   findfs-label
3959        findfs-label label
3960
3961       This command searches the filesystems and returns the one which has the
3962       given label.  An error is returned if no such filesystem can be found.
3963
3964       To find the label of a filesystem, use "vfs-label".
3965
3966   findfs-uuid
3967        findfs-uuid uuid
3968
3969       This command searches the filesystems and returns the one which has the
3970       given UUID.  An error is returned if no such filesystem can be found.
3971
3972       To find the UUID of a filesystem, use "vfs-uuid".
3973
3974   fsck
3975        fsck fstype device
3976
3977       This runs the filesystem checker (fsck) on "device" which should have
3978       filesystem type "fstype".
3979
3980       The returned integer is the status.  See fsck(8) for the list of status
3981       codes from "fsck".
3982
3983       Notes:
3984
3985       ·   Multiple status codes can be summed together.
3986
3987       ·   A non-zero return code can mean "success", for example if errors
3988           have been corrected on the filesystem.
3989
3990       ·   Checking or repairing NTFS volumes is not supported (by linux-
3991           ntfs).
3992
3993       This command is entirely equivalent to running "fsck -a -t fstype
3994       device".
3995
3996   fstrim
3997        fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]
3998
3999       Trim the free space in the filesystem mounted on "mountpoint".  The
4000       filesystem must be mounted read-write.
4001
4002       The filesystem contents are not affected, but any free space in the
4003       filesystem is "trimmed", that is, given back to the host device, thus
4004       making disk images more sparse, allowing unused space in qcow2 files to
4005       be reused, etc.
4006
4007       This operation requires support in libguestfs, the mounted filesystem,
4008       the host filesystem, qemu and the host kernel.  If this support isn't
4009       present it may give an error or even appear to run but do nothing.
4010
4011       In the case where the kernel vfs driver does not support trimming, this
4012       call will fail with errno set to "ENOTSUP".  Currently this happens
4013       when trying to trim FAT filesystems.
4014
4015       See also "zero-free-space".  That is a slightly different operation
4016       that turns free space in the filesystem into zeroes.  It is valid to
4017       call "fstrim" either instead of, or after calling "zero-free-space".
4018
4019       This command has one or more optional arguments.  See "OPTIONAL
4020       ARGUMENTS".
4021
4022       This command depends on the feature "fstrim".   See also "feature-
4023       available".
4024
4025   get-append
4026        get-append
4027
4028       Return the additional kernel options which are added to the libguestfs
4029       appliance kernel command line.
4030
4031       If "NULL" then no options are added.
4032
4033   get-attach-method
4034        get-attach-method
4035
4036       Return the current backend.
4037
4038       See "set-backend" and "BACKEND" in guestfs(3).
4039
4040       This function is deprecated.  In new code, use the "get-backend" call
4041       instead.
4042
4043       Deprecated functions will not be removed from the API, but the fact
4044       that they are deprecated indicates that there are problems with correct
4045       use of these functions.
4046
4047   get-autosync
4048        get-autosync
4049
4050       Get the autosync flag.
4051
4052   get-backend
4053        get-backend
4054
4055       Return the current backend.
4056
4057       This handle property was previously called the "attach method".
4058
4059       See "set-backend" and "BACKEND" in guestfs(3).
4060
4061   get-backend-setting
4062        get-backend-setting name
4063
4064       Find a backend setting string which is either "name" or begins with
4065       "name=".  If "name", this returns the string "1".  If "name=", this
4066       returns the part after the equals sign (which may be an empty string).
4067
4068       If no such setting is found, this function throws an error.  The errno
4069       (see "last-errno") will be "ESRCH" in this case.
4070
4071       See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4072
4073   get-backend-settings
4074        get-backend-settings
4075
4076       Return the current backend settings.
4077
4078       This call returns all backend settings strings.  If you want to find a
4079       single backend setting, see "get-backend-setting".
4080
4081       See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
4082
4083   get-cachedir
4084        get-cachedir
4085
4086       Get the directory used by the handle to store the appliance cache.
4087
4088   get-direct
4089        get-direct
4090
4091       Return the direct appliance mode flag.
4092
4093       This function is deprecated.  In new code, use the "internal-get-
4094       console-socket" call instead.
4095
4096       Deprecated functions will not be removed from the API, but the fact
4097       that they are deprecated indicates that there are problems with correct
4098       use of these functions.
4099
4100   get-e2attrs
4101        get-e2attrs file
4102
4103       This returns the file attributes associated with file.
4104
4105       The attributes are a set of bits associated with each inode which
4106       affect the behaviour of the file.  The attributes are returned as a
4107       string of letters (described below).  The string may be empty,
4108       indicating that no file attributes are set for this file.
4109
4110       These attributes are only present when the file is located on an
4111       ext2/3/4 filesystem.  Using this call on other filesystem types will
4112       result in an error.
4113
4114       The characters (file attributes) in the returned string are currently:
4115
4116       'A' When the file is accessed, its atime is not modified.
4117
4118       'a' The file is append-only.
4119
4120       'c' The file is compressed on-disk.
4121
4122       'D' (Directories only.)  Changes to this directory are written
4123           synchronously to disk.
4124
4125       'd' The file is not a candidate for backup (see dump(8)).
4126
4127       'E' The file has compression errors.
4128
4129       'e' The file is using extents.
4130
4131       'h' The file is storing its blocks in units of the filesystem blocksize
4132           instead of sectors.
4133
4134       'I' (Directories only.)  The directory is using hashed trees.
4135
4136       'i' The file is immutable.  It cannot be modified, deleted or renamed.
4137           No link can be created to this file.
4138
4139       'j' The file is data-journaled.
4140
4141       's' When the file is deleted, all its blocks will be zeroed.
4142
4143       'S' Changes to this file are written synchronously to disk.
4144
4145       'T' (Directories only.)  This is a hint to the block allocator that
4146           subdirectories contained in this directory should be spread across
4147           blocks.  If not present, the block allocator will try to group
4148           subdirectories together.
4149
4150       't' For a file, this disables tail-merging.  (Not used by upstream
4151           implementations of ext2.)
4152
4153       'u' When the file is deleted, its blocks will be saved, allowing the
4154           file to be undeleted.
4155
4156       'X' The raw contents of the compressed file may be accessed.
4157
4158       'Z' The compressed file is dirty.
4159
4160       More file attributes may be added to this list later.  Not all file
4161       attributes may be set for all kinds of files.  For detailed
4162       information, consult the chattr(1) man page.
4163
4164       See also "set-e2attrs".
4165
4166       Don't confuse these attributes with extended attributes (see
4167       "getxattr").
4168
4169   get-e2generation
4170        get-e2generation file
4171
4172       This returns the ext2 file generation of a file.  The generation (which
4173       used to be called the "version") is a number associated with an inode.
4174       This is most commonly used by NFS servers.
4175
4176       The generation is only present when the file is located on an ext2/3/4
4177       filesystem.  Using this call on other filesystem types will result in
4178       an error.
4179
4180       See "set-e2generation".
4181
4182   get-e2label
4183        get-e2label device
4184
4185       This returns the ext2/3/4 filesystem label of the filesystem on
4186       "device".
4187
4188       This function is deprecated.  In new code, use the "vfs-label" call
4189       instead.
4190
4191       Deprecated functions will not be removed from the API, but the fact
4192       that they are deprecated indicates that there are problems with correct
4193       use of these functions.
4194
4195   get-e2uuid
4196        get-e2uuid device
4197
4198       This returns the ext2/3/4 filesystem UUID of the filesystem on
4199       "device".
4200
4201       This function is deprecated.  In new code, use the "vfs-uuid" call
4202       instead.
4203
4204       Deprecated functions will not be removed from the API, but the fact
4205       that they are deprecated indicates that there are problems with correct
4206       use of these functions.
4207
4208   get-hv
4209        get-hv
4210
4211       Return the current hypervisor binary.
4212
4213       This is always non-NULL.  If it wasn't set already, then this will
4214       return the default qemu binary name.
4215
4216   get-identifier
4217        get-identifier
4218
4219       Get the handle identifier.  See "set-identifier".
4220
4221   get-libvirt-requested-credential-challenge
4222        get-libvirt-requested-credential-challenge index
4223
4224       Get the challenge (provided by libvirt) for the "index"'th requested
4225       credential.  If libvirt did not provide a challenge, this returns the
4226       empty string "".
4227
4228       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4229       example code.
4230
4231   get-libvirt-requested-credential-defresult
4232        get-libvirt-requested-credential-defresult index
4233
4234       Get the default result (provided by libvirt) for the "index"'th
4235       requested credential.  If libvirt did not provide a default result,
4236       this returns the empty string "".
4237
4238       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4239       example code.
4240
4241   get-libvirt-requested-credential-prompt
4242        get-libvirt-requested-credential-prompt index
4243
4244       Get the prompt (provided by libvirt) for the "index"'th requested
4245       credential.  If libvirt did not provide a prompt, this returns the
4246       empty string "".
4247
4248       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4249       example code.
4250
4251   get-libvirt-requested-credentials
4252        get-libvirt-requested-credentials
4253
4254       This should only be called during the event callback for events of type
4255       "GUESTFS_EVENT_LIBVIRT_AUTH".
4256
4257       Return the list of credentials requested by libvirt.  Possible values
4258       are a subset of the strings provided when you called "set-libvirt-
4259       supported-credentials".
4260
4261       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
4262       example code.
4263
4264   get-memsize
4265        get-memsize
4266
4267       This gets the memory size in megabytes allocated to the hypervisor.
4268
4269       If "set-memsize" was not called on this handle, and if
4270       "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
4271       default value for memsize.
4272
4273       For more information on the architecture of libguestfs, see guestfs(3).
4274
4275   get-network
4276        get-network
4277
4278       This returns the enable network flag.
4279
4280   get-path
4281        get-path
4282
4283       Return the current search path.
4284
4285       This is always non-NULL.  If it wasn't set already, then this will
4286       return the default path.
4287
4288   get-pgroup
4289        get-pgroup
4290
4291       This returns the process group flag.
4292
4293   get-pid
4294   pid
4295        get-pid
4296
4297       Return the process ID of the hypervisor.  If there is no hypervisor
4298       running, then this will return an error.
4299
4300       This is an internal call used for debugging and testing.
4301
4302   get-program
4303        get-program
4304
4305       Get the program name.  See "set-program".
4306
4307   get-qemu
4308        get-qemu
4309
4310       Return the current hypervisor binary (usually qemu).
4311
4312       This is always non-NULL.  If it wasn't set already, then this will
4313       return the default qemu binary name.
4314
4315       This function is deprecated.  In new code, use the "get-hv" call
4316       instead.
4317
4318       Deprecated functions will not be removed from the API, but the fact
4319       that they are deprecated indicates that there are problems with correct
4320       use of these functions.
4321
4322   get-recovery-proc
4323        get-recovery-proc
4324
4325       Return the recovery process enabled flag.
4326
4327   get-selinux
4328        get-selinux
4329
4330       This returns the current setting of the selinux flag which is passed to
4331       the appliance at boot time.  See "set-selinux".
4332
4333       For more information on the architecture of libguestfs, see guestfs(3).
4334
4335       This function is deprecated.  In new code, use the "selinux-relabel"
4336       call instead.
4337
4338       Deprecated functions will not be removed from the API, but the fact
4339       that they are deprecated indicates that there are problems with correct
4340       use of these functions.
4341
4342   get-smp
4343        get-smp
4344
4345       This returns the number of virtual CPUs assigned to the appliance.
4346
4347   get-sockdir
4348        get-sockdir
4349
4350       Get the directory used by the handle to store temporary socket files.
4351
4352       This is different from "get-tmpdir", as we need shorter paths for
4353       sockets (due to the limited buffers of filenames for UNIX sockets), and
4354       "get-tmpdir" may be too long for them.
4355
4356       The environment variable "XDG_RUNTIME_DIR" controls the default value:
4357       If "XDG_RUNTIME_DIR" is set, then that is the default.  Else /tmp is
4358       the default.
4359
4360   get-tmpdir
4361        get-tmpdir
4362
4363       Get the directory used by the handle to store temporary files.
4364
4365   get-trace
4366        get-trace
4367
4368       Return the command trace flag.
4369
4370   get-umask
4371        get-umask
4372
4373       Return the current umask.  By default the umask is 022 unless it has
4374       been set by calling "umask".
4375
4376   get-verbose
4377        get-verbose
4378
4379       This returns the verbose messages flag.
4380
4381   getcon
4382        getcon
4383
4384       This gets the SELinux security context of the daemon.
4385
4386       See the documentation about SELINUX in guestfs(3), and "setcon"
4387
4388       This function is deprecated.  In new code, use the "selinux-relabel"
4389       call instead.
4390
4391       Deprecated functions will not be removed from the API, but the fact
4392       that they are deprecated indicates that there are problems with correct
4393       use of these functions.
4394
4395       This command depends on the feature "selinux".   See also "feature-
4396       available".
4397
4398   getxattr
4399        getxattr path name
4400
4401       Get a single extended attribute from file "path" named "name".  This
4402       call follows symlinks.  If you want to lookup an extended attribute for
4403       the symlink itself, use "lgetxattr".
4404
4405       Normally it is better to get all extended attributes from a file in one
4406       go by calling "getxattrs".  However some Linux filesystem
4407       implementations are buggy and do not provide a way to list out
4408       attributes.  For these filesystems (notably ntfs-3g) you have to know
4409       the names of the extended attributes you want in advance and call this
4410       function.
4411
4412       Extended attribute values are blobs of binary data.  If there is no
4413       extended attribute named "name", this returns an error.
4414
4415       See also: "getxattrs", "lgetxattr", attr(5).
4416
4417       This command depends on the feature "linuxxattrs".   See also "feature-
4418       available".
4419
4420   getxattrs
4421        getxattrs path
4422
4423       This call lists the extended attributes of the file or directory
4424       "path".
4425
4426       At the system call level, this is a combination of the listxattr(2) and
4427       getxattr(2) calls.
4428
4429       See also: "lgetxattrs", attr(5).
4430
4431       This command depends on the feature "linuxxattrs".   See also "feature-
4432       available".
4433
4434   glob-expand
4435   glob-expand-opts
4436        glob-expand pattern [directoryslash:true|false]
4437
4438       This command searches for all the pathnames matching "pattern"
4439       according to the wildcard expansion rules used by the shell.
4440
4441       If no paths match, then this returns an empty list (note: not an
4442       error).
4443
4444       It is just a wrapper around the C glob(3) function with flags
4445       "GLOB_MARK|GLOB_BRACE".  See that manual page for more details.
4446
4447       "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
4448       and it defaults to true.  It can be explicitly set as off to return no
4449       trailing slashes in filenames of directories.
4450
4451       Notice that there is no equivalent command for expanding a device name
4452       (eg. /dev/sd*).  Use "list-devices", "list-partitions" etc functions
4453       instead.
4454
4455       This command has one or more optional arguments.  See "OPTIONAL
4456       ARGUMENTS".
4457
4458   grep
4459   grep-opts
4460        grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]
4461
4462       This calls the external grep(1) program and returns the matching lines.
4463
4464       The optional flags are:
4465
4466       "extended"
4467           Use extended regular expressions.  This is the same as using the -E
4468           flag.
4469
4470       "fixed"
4471           Match fixed (don't use regular expressions).  This is the same as
4472           using the -F flag.
4473
4474       "insensitive"
4475           Match case-insensitive.  This is the same as using the -i flag.
4476
4477       "compressed"
4478           Use zgrep(1) instead of grep(1).  This allows the input to be
4479           compress- or gzip-compressed.
4480
4481       This command has one or more optional arguments.  See "OPTIONAL
4482       ARGUMENTS".
4483
4484       Because of the message protocol, there is a transfer limit of somewhere
4485       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4486
4487   grepi
4488        grepi regex path
4489
4490       This calls the external "grep -i" program and returns the matching
4491       lines.
4492
4493       Because of the message protocol, there is a transfer limit of somewhere
4494       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4495
4496       This function is deprecated.  In new code, use the "grep" call instead.
4497
4498       Deprecated functions will not be removed from the API, but the fact
4499       that they are deprecated indicates that there are problems with correct
4500       use of these functions.
4501
4502   grub-install
4503        grub-install root device
4504
4505       This command installs GRUB 1 (the Grand Unified Bootloader) on
4506       "device", with the root directory being "root".
4507
4508       Notes:
4509
4510       ·   There is currently no way in the API to install grub2, which is
4511           used by most modern Linux guests.  It is possible to run the grub2
4512           command from the guest, although see the caveats in "RUNNING
4513           COMMANDS" in guestfs(3).
4514
4515       ·   This uses grub-install(8) from the host.  Unfortunately grub is not
4516           always compatible with itself, so this only works in rather narrow
4517           circumstances.  Careful testing with each guest version is
4518           advisable.
4519
4520       ·   If grub-install reports the error "No suitable drive was found in
4521           the generated device map."  it may be that you need to create a
4522           /boot/grub/device.map file first that contains the mapping between
4523           grub device names and Linux device names.  It is usually sufficient
4524           to create a file containing:
4525
4526            (hd0) /dev/vda
4527
4528           replacing /dev/vda with the name of the installation device.
4529
4530       This command depends on the feature "grub".   See also "feature-
4531       available".
4532
4533   head
4534        head path
4535
4536       This command returns up to the first 10 lines of a file as a list of
4537       strings.
4538
4539       Because of the message protocol, there is a transfer limit of somewhere
4540       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4541
4542   head-n
4543        head-n nrlines path
4544
4545       If the parameter "nrlines" is a positive number, this returns the first
4546       "nrlines" lines of the file "path".
4547
4548       If the parameter "nrlines" is a negative number, this returns lines
4549       from the file "path", excluding the last "nrlines" lines.
4550
4551       If the parameter "nrlines" is zero, this returns an empty list.
4552
4553       Because of the message protocol, there is a transfer limit of somewhere
4554       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4555
4556   hexdump
4557        hexdump path
4558
4559       This runs "hexdump -C" on the given "path".  The result is the human-
4560       readable, canonical hex dump of the file.
4561
4562       Because of the message protocol, there is a transfer limit of somewhere
4563       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4564
4565   hivex-close
4566        hivex-close
4567
4568       Close the current hivex handle.
4569
4570       This is a wrapper around the hivex(3) call of the same name.
4571
4572       This command depends on the feature "hivex".   See also "feature-
4573       available".
4574
4575   hivex-commit
4576        hivex-commit filename
4577
4578       Commit (write) changes to the hive.
4579
4580       If the optional filename parameter is null, then the changes are
4581       written back to the same hive that was opened.  If this is not null
4582       then they are written to the alternate filename given and the original
4583       hive is left untouched.
4584
4585       This is a wrapper around the hivex(3) call of the same name.
4586
4587       This command depends on the feature "hivex".   See also "feature-
4588       available".
4589
4590   hivex-node-add-child
4591        hivex-node-add-child parent name
4592
4593       Add a child node to "parent" named "name".
4594
4595       This is a wrapper around the hivex(3) call of the same name.
4596
4597       This command depends on the feature "hivex".   See also "feature-
4598       available".
4599
4600   hivex-node-children
4601        hivex-node-children nodeh
4602
4603       Return the list of nodes which are subkeys of "nodeh".
4604
4605       This is a wrapper around the hivex(3) call of the same name.
4606
4607       This command depends on the feature "hivex".   See also "feature-
4608       available".
4609
4610   hivex-node-delete-child
4611        hivex-node-delete-child nodeh
4612
4613       Delete "nodeh", recursively if necessary.
4614
4615       This is a wrapper around the hivex(3) call of the same name.
4616
4617       This command depends on the feature "hivex".   See also "feature-
4618       available".
4619
4620   hivex-node-get-child
4621        hivex-node-get-child nodeh name
4622
4623       Return the child of "nodeh" with the name "name", if it exists.  This
4624       can return 0 meaning the name was not found.
4625
4626       This is a wrapper around the hivex(3) call of the same name.
4627
4628       This command depends on the feature "hivex".   See also "feature-
4629       available".
4630
4631   hivex-node-get-value
4632        hivex-node-get-value nodeh key
4633
4634       Return the value attached to "nodeh" which has the name "key", if it
4635       exists.  This can return 0 meaning the key was not found.
4636
4637       This is a wrapper around the hivex(3) call of the same name.
4638
4639       This command depends on the feature "hivex".   See also "feature-
4640       available".
4641
4642   hivex-node-name
4643        hivex-node-name nodeh
4644
4645       Return the name of "nodeh".
4646
4647       This is a wrapper around the hivex(3) call of the same name.
4648
4649       This command depends on the feature "hivex".   See also "feature-
4650       available".
4651
4652   hivex-node-parent
4653        hivex-node-parent nodeh
4654
4655       Return the parent node of "nodeh".
4656
4657       This is a wrapper around the hivex(3) call of the same name.
4658
4659       This command depends on the feature "hivex".   See also "feature-
4660       available".
4661
4662   hivex-node-set-value
4663        hivex-node-set-value nodeh key t val
4664
4665       Set or replace a single value under the node "nodeh".  The "key" is the
4666       name, "t" is the type, and "val" is the data.
4667
4668       This is a wrapper around the hivex(3) call of the same name.
4669
4670       This command depends on the feature "hivex".   See also "feature-
4671       available".
4672
4673   hivex-node-values
4674        hivex-node-values nodeh
4675
4676       Return the array of (key, datatype, data) tuples attached to "nodeh".
4677
4678       This is a wrapper around the hivex(3) call of the same name.
4679
4680       This command depends on the feature "hivex".   See also "feature-
4681       available".
4682
4683   hivex-open
4684        hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]
4685
4686       Open the Windows Registry hive file named filename.  If there was any
4687       previous hivex handle associated with this guestfs session, then it is
4688       closed.
4689
4690       This is a wrapper around the hivex(3) call of the same name.
4691
4692       This command has one or more optional arguments.  See "OPTIONAL
4693       ARGUMENTS".
4694
4695       This command depends on the feature "hivex".   See also "feature-
4696       available".
4697
4698   hivex-root
4699        hivex-root
4700
4701       Return the root node of the hive.
4702
4703       This is a wrapper around the hivex(3) call of the same name.
4704
4705       This command depends on the feature "hivex".   See also "feature-
4706       available".
4707
4708   hivex-value-key
4709        hivex-value-key valueh
4710
4711       Return the key (name) field of a (key, datatype, data) tuple.
4712
4713       This is a wrapper around the hivex(3) call of the same name.
4714
4715       This command depends on the feature "hivex".   See also "feature-
4716       available".
4717
4718   hivex-value-string
4719        hivex-value-string valueh
4720
4721       This calls "hivex-value-value" (which returns the data field from a
4722       hivex value tuple).  It then assumes that the field is a UTF-16LE
4723       string and converts the result to UTF-8 (or if this is not possible, it
4724       returns an error).
4725
4726       This is useful for reading strings out of the Windows registry.
4727       However it is not foolproof because the registry is not strongly-typed
4728       and fields can contain arbitrary or unexpected data.
4729
4730       This command depends on the feature "hivex".   See also "feature-
4731       available".
4732
4733   hivex-value-type
4734        hivex-value-type valueh
4735
4736       Return the data type field from a (key, datatype, data) tuple.
4737
4738       This is a wrapper around the hivex(3) call of the same name.
4739
4740       This command depends on the feature "hivex".   See also "feature-
4741       available".
4742
4743   hivex-value-utf8
4744        hivex-value-utf8 valueh
4745
4746       This calls "hivex-value-value" (which returns the data field from a
4747       hivex value tuple).  It then assumes that the field is a UTF-16LE
4748       string and converts the result to UTF-8 (or if this is not possible, it
4749       returns an error).
4750
4751       This is useful for reading strings out of the Windows registry.
4752       However it is not foolproof because the registry is not strongly-typed
4753       and fields can contain arbitrary or unexpected data.
4754
4755       This function is deprecated.  In new code, use the "hivex-value-string"
4756       call instead.
4757
4758       Deprecated functions will not be removed from the API, but the fact
4759       that they are deprecated indicates that there are problems with correct
4760       use of these functions.
4761
4762       This command depends on the feature "hivex".   See also "feature-
4763       available".
4764
4765   hivex-value-value
4766        hivex-value-value valueh
4767
4768       Return the data field of a (key, datatype, data) tuple.
4769
4770       This is a wrapper around the hivex(3) call of the same name.
4771
4772       See also: "hivex-value-utf8".
4773
4774       This command depends on the feature "hivex".   See also "feature-
4775       available".
4776
4777   initrd-cat
4778        initrd-cat initrdpath filename
4779
4780       This command unpacks the file filename from the initrd file called
4781       initrdpath.  The filename must be given without the initial /
4782       character.
4783
4784       For example, in guestfish you could use the following command to
4785       examine the boot script (usually called /init) contained in a Linux
4786       initrd or initramfs image:
4787
4788        initrd-cat /boot/initrd-<version>.img init
4789
4790       See also "initrd-list".
4791
4792       Because of the message protocol, there is a transfer limit of somewhere
4793       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
4794
4795   initrd-list
4796        initrd-list path
4797
4798       This command lists out files contained in an initrd.
4799
4800       The files are listed without any initial / character.  The files are
4801       listed in the order they appear (not necessarily alphabetical).
4802       Directory names are listed as separate items.
4803
4804       Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
4805       as initrd.  We only support the newer initramfs format (compressed cpio
4806       files).
4807
4808   inotify-add-watch
4809        inotify-add-watch path mask
4810
4811       Watch "path" for the events listed in "mask".
4812
4813       Note that if "path" is a directory then events within that directory
4814       are watched, but this does not happen recursively (in subdirectories).
4815
4816       Note for non-C or non-Linux callers: the inotify events are defined by
4817       the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
4818
4819       This command depends on the feature "inotify".   See also "feature-
4820       available".
4821
4822   inotify-close
4823        inotify-close
4824
4825       This closes the inotify handle which was previously opened by
4826       inotify_init.  It removes all watches, throws away any pending events,
4827       and deallocates all resources.
4828
4829       This command depends on the feature "inotify".   See also "feature-
4830       available".
4831
4832   inotify-files
4833        inotify-files
4834
4835       This function is a helpful wrapper around "inotify-read" which just
4836       returns a list of pathnames of objects that were touched.  The returned
4837       pathnames are sorted and deduplicated.
4838
4839       This command depends on the feature "inotify".   See also "feature-
4840       available".
4841
4842   inotify-init
4843        inotify-init maxevents
4844
4845       This command creates a new inotify handle.  The inotify subsystem can
4846       be used to notify events which happen to objects in the guest
4847       filesystem.
4848
4849       "maxevents" is the maximum number of events which will be queued up
4850       between calls to "inotify-read" or "inotify-files".  If this is passed
4851       as 0, then the kernel (or previously set) default is used.  For Linux
4852       2.6.29 the default was 16384 events.  Beyond this limit, the kernel
4853       throws away events, but records the fact that it threw them away by
4854       setting a flag "IN_Q_OVERFLOW" in the returned structure list (see
4855       "inotify-read").
4856
4857       Before any events are generated, you have to add some watches to the
4858       internal watch list.  See: "inotify-add-watch" and "inotify-rm-watch".
4859
4860       Queued up events should be read periodically by calling "inotify-read"
4861       (or "inotify-files" which is just a helpful wrapper around "inotify-
4862       read").  If you don't read the events out often enough then you risk
4863       the internal queue overflowing.
4864
4865       The handle should be closed after use by calling "inotify-close".  This
4866       also removes any watches automatically.
4867
4868       See also inotify(7) for an overview of the inotify interface as exposed
4869       by the Linux kernel, which is roughly what we expose via libguestfs.
4870       Note that there is one global inotify handle per libguestfs instance.
4871
4872       This command depends on the feature "inotify".   See also "feature-
4873       available".
4874
4875   inotify-read
4876        inotify-read
4877
4878       Return the complete queue of events that have happened since the
4879       previous read call.
4880
4881       If no events have happened, this returns an empty list.
4882
4883       Note: In order to make sure that all events have been read, you must
4884       call this function repeatedly until it returns an empty list.  The
4885       reason is that the call will read events up to the maximum appliance-
4886       to-host message size and leave remaining events in the queue.
4887
4888       This command depends on the feature "inotify".   See also "feature-
4889       available".
4890
4891   inotify-rm-watch
4892        inotify-rm-watch wd
4893
4894       Remove a previously defined inotify watch.  See "inotify-add-watch".
4895
4896       This command depends on the feature "inotify".   See also "feature-
4897       available".
4898
4899   inspect-get-arch
4900        inspect-get-arch root
4901
4902       This returns the architecture of the inspected operating system.  The
4903       possible return values are listed under "file-architecture".
4904
4905       If the architecture could not be determined, then the string "unknown"
4906       is returned.
4907
4908       Please read "INSPECTION" in guestfs(3) for more details.
4909
4910   inspect-get-distro
4911        inspect-get-distro root
4912
4913       This returns the distro (distribution) of the inspected operating
4914       system.
4915
4916       Currently defined distros are:
4917
4918       "alpinelinux"
4919           Alpine Linux.
4920
4921       "altlinux"
4922           ALT Linux.
4923
4924       "archlinux"
4925           Arch Linux.
4926
4927       "buildroot"
4928           Buildroot-derived distro, but not one we specifically recognize.
4929
4930       "centos"
4931           CentOS.
4932
4933       "cirros"
4934           Cirros.
4935
4936       "coreos"
4937           CoreOS.
4938
4939       "debian"
4940           Debian.
4941
4942       "fedora"
4943           Fedora.
4944
4945       "freebsd"
4946           FreeBSD.
4947
4948       "freedos"
4949           FreeDOS.
4950
4951       "frugalware"
4952           Frugalware.
4953
4954       "gentoo"
4955           Gentoo.
4956
4957       "kalilinux"
4958           Kali Linux.
4959
4960       "linuxmint"
4961           Linux Mint.
4962
4963       "mageia"
4964           Mageia.
4965
4966       "mandriva"
4967           Mandriva.
4968
4969       "meego"
4970           MeeGo.
4971
4972       "msdos"
4973           Microsoft DOS.
4974
4975       "neokylin"
4976           NeoKylin.
4977
4978       "netbsd"
4979           NetBSD.
4980
4981       "openbsd"
4982           OpenBSD.
4983
4984       "openmandriva"
4985           OpenMandriva Lx.
4986
4987       "opensuse"
4988           OpenSUSE.
4989
4990       "oraclelinux"
4991           Oracle Linux.
4992
4993       "pardus"
4994           Pardus.
4995
4996       "pldlinux"
4997           PLD Linux.
4998
4999       "redhat-based"
5000           Some Red Hat-derived distro.
5001
5002       "rhel"
5003           Red Hat Enterprise Linux.
5004
5005       "scientificlinux"
5006           Scientific Linux.
5007
5008       "slackware"
5009           Slackware.
5010
5011       "sles"
5012           SuSE Linux Enterprise Server or Desktop.
5013
5014       "suse-based"
5015           Some openSuSE-derived distro.
5016
5017       "ttylinux"
5018           ttylinux.
5019
5020       "ubuntu"
5021           Ubuntu.
5022
5023       "unknown"
5024           The distro could not be determined.
5025
5026       "voidlinux"
5027           Void Linux.
5028
5029       "windows"
5030           Windows does not have distributions.  This string is returned if
5031           the OS type is Windows.
5032
5033       Future versions of libguestfs may return other strings here.  The
5034       caller should be prepared to handle any string.
5035
5036       Please read "INSPECTION" in guestfs(3) for more details.
5037
5038   inspect-get-drive-mappings
5039        inspect-get-drive-mappings root
5040
5041       This call is useful for Windows which uses a primitive system of
5042       assigning drive letters (like C:\) to partitions.  This inspection API
5043       examines the Windows Registry to find out how disks/partitions are
5044       mapped to drive letters, and returns a hash table as in the example
5045       below:
5046
5047        C      =>     /dev/vda2
5048        E      =>     /dev/vdb1
5049        F      =>     /dev/vdc1
5050
5051       Note that keys are drive letters.  For Windows, the key is case
5052       insensitive and just contains the drive letter, without the customary
5053       colon separator character.
5054
5055       In future we may support other operating systems that also used drive
5056       letters, but the keys for those might not be case insensitive and might
5057       be longer than 1 character.  For example in OS-9, hard drives were
5058       named "h0", "h1" etc.
5059
5060       For Windows guests, currently only hard drive mappings are returned.
5061       Removable disks (eg. DVD-ROMs) are ignored.
5062
5063       For guests that do not use drive mappings, or if the drive mappings
5064       could not be determined, this returns an empty hash table.
5065
5066       Please read "INSPECTION" in guestfs(3) for more details.  See also
5067       "inspect-get-mountpoints", "inspect-get-filesystems".
5068
5069   inspect-get-filesystems
5070        inspect-get-filesystems root
5071
5072       This returns a list of all the filesystems that we think are associated
5073       with this operating system.  This includes the root filesystem, other
5074       ordinary filesystems, and non-mounted devices like swap partitions.
5075
5076       In the case of a multi-boot virtual machine, it is possible for a
5077       filesystem to be shared between operating systems.
5078
5079       Please read "INSPECTION" in guestfs(3) for more details.  See also
5080       "inspect-get-mountpoints".
5081
5082   inspect-get-format
5083        inspect-get-format root
5084
5085       Before libguestfs 1.38, there was some unreliable support for detecting
5086       installer CDs.  This API would return:
5087
5088       "installed"
5089           This is an installed operating system.
5090
5091       "installer"
5092           The disk image being inspected is not an installed operating
5093           system, but a bootable install disk, live CD, or similar.
5094
5095       "unknown"
5096           The format of this disk image is not known.
5097
5098       In libguestfs ≥ 1.38, this only returns "installed".  Use libosinfo
5099       directly to detect installer CDs.
5100
5101       Please read "INSPECTION" in guestfs(3) for more details.
5102
5103       This function is deprecated.  There is no replacement.  Consult the API
5104       documentation in guestfs(3) for further information.
5105
5106       Deprecated functions will not be removed from the API, but the fact
5107       that they are deprecated indicates that there are problems with correct
5108       use of these functions.
5109
5110   inspect-get-hostname
5111        inspect-get-hostname root
5112
5113       This function returns the hostname of the operating system as found by
5114       inspection of the guest’s configuration files.
5115
5116       If the hostname could not be determined, then the string "unknown" is
5117       returned.
5118
5119       Please read "INSPECTION" in guestfs(3) for more details.
5120
5121   inspect-get-icon
5122        inspect-get-icon root [favicon:true|false] [highquality:true|false]
5123
5124       This function returns an icon corresponding to the inspected operating
5125       system.  The icon is returned as a buffer containing a PNG image (re-
5126       encoded to PNG if necessary).
5127
5128       If it was not possible to get an icon this function returns a zero-
5129       length (non-NULL) buffer.  Callers must check for this case.
5130
5131       Libguestfs will start by looking for a file called /etc/favicon.png or
5132       C:\etc\favicon.png and if it has the correct format, the contents of
5133       this file will be returned.  You can disable favicons by passing the
5134       optional "favicon" boolean as false (default is true).
5135
5136       If finding the favicon fails, then we look in other places in the guest
5137       for a suitable icon.
5138
5139       If the optional "highquality" boolean is true then only high quality
5140       icons are returned, which means only icons of high resolution with an
5141       alpha channel.  The default (false) is to return any icon we can, even
5142       if it is of substandard quality.
5143
5144       Notes:
5145
5146       ·   Unlike most other inspection API calls, the guest’s disks must be
5147           mounted up before you call this, since it needs to read information
5148           from the guest filesystem during the call.
5149
5150       ·   Security: The icon data comes from the untrusted guest, and should
5151           be treated with caution.  PNG files have been known to contain
5152           exploits.  Ensure that libpng (or other relevant libraries) are
5153           fully up to date before trying to process or display the icon.
5154
5155       ·   The PNG image returned can be any size.  It might not be square.
5156           Libguestfs tries to return the largest, highest quality icon
5157           available.  The application must scale the icon to the required
5158           size.
5159
5160       ·   Extracting icons from Windows guests requires the external
5161           wrestool(1) program from the "icoutils" package, and several
5162           programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
5163           package.  These must be installed separately.
5164
5165       ·   Operating system icons are usually trademarks.  Seek legal advice
5166           before using trademarks in applications.
5167
5168       This command has one or more optional arguments.  See "OPTIONAL
5169       ARGUMENTS".
5170
5171   inspect-get-major-version
5172        inspect-get-major-version root
5173
5174       This returns the major version number of the inspected operating
5175       system.
5176
5177       Windows uses a consistent versioning scheme which is not reflected in
5178       the popular public names used by the operating system.  Notably the
5179       operating system known as "Windows 7" is really version 6.1 (ie. major
5180       = 6, minor = 1).  You can find out the real versions corresponding to
5181       releases of Windows by consulting Wikipedia or MSDN.
5182
5183       If the version could not be determined, then 0 is returned.
5184
5185       Please read "INSPECTION" in guestfs(3) for more details.
5186
5187   inspect-get-minor-version
5188        inspect-get-minor-version root
5189
5190       This returns the minor version number of the inspected operating
5191       system.
5192
5193       If the version could not be determined, then 0 is returned.
5194
5195       Please read "INSPECTION" in guestfs(3) for more details.  See also
5196       "inspect-get-major-version".
5197
5198   inspect-get-mountpoints
5199        inspect-get-mountpoints root
5200
5201       This returns a hash of where we think the filesystems associated with
5202       this operating system should be mounted.  Callers should note that this
5203       is at best an educated guess made by reading configuration files such
5204       as /etc/fstab.  In particular note that this may return filesystems
5205       which are non-existent or not mountable and callers should be prepared
5206       to handle or ignore failures if they try to mount them.
5207
5208       Each element in the returned hashtable has a key which is the path of
5209       the mountpoint (eg. /boot) and a value which is the filesystem that
5210       would be mounted there (eg. /dev/sda1).
5211
5212       Non-mounted devices such as swap devices are not returned in this list.
5213
5214       For operating systems like Windows which still use drive letters, this
5215       call will only return an entry for the first drive "mounted on" /.  For
5216       information about the mapping of drive letters to partitions, see
5217       "inspect-get-drive-mappings".
5218
5219       Please read "INSPECTION" in guestfs(3) for more details.  See also
5220       "inspect-get-filesystems".
5221
5222   inspect-get-osinfo
5223        inspect-get-osinfo root
5224
5225       This function returns a possible short ID for libosinfo corresponding
5226       to the guest.
5227
5228       Note: The returned ID is only a guess by libguestfs, and nothing
5229       ensures that it actually exists in osinfo-db.
5230
5231       If no ID could not be determined, then the string "unknown" is
5232       returned.
5233
5234   inspect-get-package-format
5235        inspect-get-package-format root
5236
5237       This function and "inspect-get-package-management" return the package
5238       format and package management tool used by the inspected operating
5239       system.  For example for Fedora these functions would return "rpm"
5240       (package format), and "yum" or "dnf" (package management).
5241
5242       This returns the string "unknown" if we could not determine the package
5243       format or if the operating system does not have a real packaging system
5244       (eg. Windows).
5245
5246       Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
5247       "pkgsrc", "apk", "xbps".  Future versions of libguestfs may return
5248       other strings.
5249
5250       Please read "INSPECTION" in guestfs(3) for more details.
5251
5252   inspect-get-package-management
5253        inspect-get-package-management root
5254
5255       "inspect-get-package-format" and this function return the package
5256       format and package management tool used by the inspected operating
5257       system.  For example for Fedora these functions would return "rpm"
5258       (package format), and "yum" or "dnf" (package management).
5259
5260       This returns the string "unknown" if we could not determine the package
5261       management tool or if the operating system does not have a real
5262       packaging system (eg. Windows).
5263
5264       Possible strings include: "yum", "dnf", "up2date", "apt" (for all
5265       Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
5266       "apk", "xbps".  Future versions of libguestfs may return other strings.
5267
5268       Please read "INSPECTION" in guestfs(3) for more details.
5269
5270   inspect-get-product-name
5271        inspect-get-product-name root
5272
5273       This returns the product name of the inspected operating system.  The
5274       product name is generally some freeform string which can be displayed
5275       to the user, but should not be parsed by programs.
5276
5277       If the product name could not be determined, then the string "unknown"
5278       is returned.
5279
5280       Please read "INSPECTION" in guestfs(3) for more details.
5281
5282   inspect-get-product-variant
5283        inspect-get-product-variant root
5284
5285       This returns the product variant of the inspected operating system.
5286
5287       For Windows guests, this returns the contents of the Registry key
5288       "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
5289       which is usually a string such as "Client" or "Server" (other values
5290       are possible).  This can be used to distinguish consumer and enterprise
5291       versions of Windows that have the same version number (for example,
5292       Windows 7 and Windows 2008 Server are both version 6.1, but the former
5293       is "Client" and the latter is "Server").
5294
5295       For enterprise Linux guests, in future we intend this to return the
5296       product variant such as "Desktop", "Server" and so on.  But this is not
5297       implemented at present.
5298
5299       If the product variant could not be determined, then the string
5300       "unknown" is returned.
5301
5302       Please read "INSPECTION" in guestfs(3) for more details.  See also
5303       "inspect-get-product-name", "inspect-get-major-version".
5304
5305   inspect-get-roots
5306        inspect-get-roots
5307
5308       This function is a convenient way to get the list of root devices, as
5309       returned from a previous call to "inspect-os", but without redoing the
5310       whole inspection process.
5311
5312       This returns an empty list if either no root devices were found or the
5313       caller has not called "inspect-os".
5314
5315       Please read "INSPECTION" in guestfs(3) for more details.
5316
5317   inspect-get-type
5318        inspect-get-type root
5319
5320       This returns the type of the inspected operating system.  Currently
5321       defined types are:
5322
5323       "linux"
5324           Any Linux-based operating system.
5325
5326       "windows"
5327           Any Microsoft Windows operating system.
5328
5329       "freebsd"
5330           FreeBSD.
5331
5332       "netbsd"
5333           NetBSD.
5334
5335       "openbsd"
5336           OpenBSD.
5337
5338       "hurd"
5339           GNU/Hurd.
5340
5341       "dos"
5342           MS-DOS, FreeDOS and others.
5343
5344       "minix"
5345           MINIX.
5346
5347       "unknown"
5348           The operating system type could not be determined.
5349
5350       Future versions of libguestfs may return other strings here.  The
5351       caller should be prepared to handle any string.
5352
5353       Please read "INSPECTION" in guestfs(3) for more details.
5354
5355   inspect-get-windows-current-control-set
5356        inspect-get-windows-current-control-set root
5357
5358       This returns the Windows CurrentControlSet of the inspected guest.  The
5359       CurrentControlSet is a registry key name such as "ControlSet001".
5360
5361       This call assumes that the guest is Windows and that the Registry could
5362       be examined by inspection.  If this is not the case then an error is
5363       returned.
5364
5365       Please read "INSPECTION" in guestfs(3) for more details.
5366
5367   inspect-get-windows-software-hive
5368        inspect-get-windows-software-hive root
5369
5370       This returns the path to the hive (binary Windows Registry file)
5371       corresponding to HKLM\SOFTWARE.
5372
5373       This call assumes that the guest is Windows and that the guest has a
5374       software hive file with the right name.  If this is not the case then
5375       an error is returned.  This call does not check that the hive is a
5376       valid Windows Registry hive.
5377
5378       You can use "hivex-open" to read or write to the hive.
5379
5380       Please read "INSPECTION" in guestfs(3) for more details.
5381
5382   inspect-get-windows-system-hive
5383        inspect-get-windows-system-hive root
5384
5385       This returns the path to the hive (binary Windows Registry file)
5386       corresponding to HKLM\SYSTEM.
5387
5388       This call assumes that the guest is Windows and that the guest has a
5389       system hive file with the right name.  If this is not the case then an
5390       error is returned.  This call does not check that the hive is a valid
5391       Windows Registry hive.
5392
5393       You can use "hivex-open" to read or write to the hive.
5394
5395       Please read "INSPECTION" in guestfs(3) for more details.
5396
5397   inspect-get-windows-systemroot
5398        inspect-get-windows-systemroot root
5399
5400       This returns the Windows systemroot of the inspected guest.  The
5401       systemroot is a directory path such as /WINDOWS.
5402
5403       This call assumes that the guest is Windows and that the systemroot
5404       could be determined by inspection.  If this is not the case then an
5405       error is returned.
5406
5407       Please read "INSPECTION" in guestfs(3) for more details.
5408
5409   inspect-is-live
5410        inspect-is-live root
5411
5412       This is deprecated and always returns "false".
5413
5414       Please read "INSPECTION" in guestfs(3) for more details.
5415
5416       This function is deprecated.  There is no replacement.  Consult the API
5417       documentation in guestfs(3) for further information.
5418
5419       Deprecated functions will not be removed from the API, but the fact
5420       that they are deprecated indicates that there are problems with correct
5421       use of these functions.
5422
5423   inspect-is-multipart
5424        inspect-is-multipart root
5425
5426       This is deprecated and always returns "false".
5427
5428       Please read "INSPECTION" in guestfs(3) for more details.
5429
5430       This function is deprecated.  There is no replacement.  Consult the API
5431       documentation in guestfs(3) for further information.
5432
5433       Deprecated functions will not be removed from the API, but the fact
5434       that they are deprecated indicates that there are problems with correct
5435       use of these functions.
5436
5437   inspect-is-netinst
5438        inspect-is-netinst root
5439
5440       This is deprecated and always returns "false".
5441
5442       Please read "INSPECTION" in guestfs(3) for more details.
5443
5444       This function is deprecated.  There is no replacement.  Consult the API
5445       documentation in guestfs(3) for further information.
5446
5447       Deprecated functions will not be removed from the API, but the fact
5448       that they are deprecated indicates that there are problems with correct
5449       use of these functions.
5450
5451   inspect-list-applications
5452        inspect-list-applications root
5453
5454       Return the list of applications installed in the operating system.
5455
5456       Note: This call works differently from other parts of the inspection
5457       API.  You have to call "inspect-os", then "inspect-get-mountpoints",
5458       then mount up the disks, before calling this.  Listing applications is
5459       a significantly more difficult operation which requires access to the
5460       full filesystem.  Also note that unlike the other "inspect-get-*" calls
5461       which are just returning data cached in the libguestfs handle, this
5462       call actually reads parts of the mounted filesystems during the call.
5463
5464       This returns an empty list if the inspection code was not able to
5465       determine the list of applications.
5466
5467       The application structure contains the following fields:
5468
5469       "app_name"
5470           The name of the application.  For Linux guests, this is the package
5471           name.
5472
5473       "app_display_name"
5474           The display name of the application, sometimes localized to the
5475           install language of the guest operating system.
5476
5477           If unavailable this is returned as an empty string "".  Callers
5478           needing to display something can use "app_name" instead.
5479
5480       "app_epoch"
5481           For package managers which use epochs, this contains the epoch of
5482           the package (an integer).  If unavailable, this is returned as 0.
5483
5484       "app_version"
5485           The version string of the application or package.  If unavailable
5486           this is returned as an empty string "".
5487
5488       "app_release"
5489           The release string of the application or package, for package
5490           managers that use this.  If unavailable this is returned as an
5491           empty string "".
5492
5493       "app_install_path"
5494           The installation path of the application (on operating systems such
5495           as Windows which use installation paths).  This path is in the
5496           format used by the guest operating system, it is not a libguestfs
5497           path.
5498
5499           If unavailable this is returned as an empty string "".
5500
5501       "app_trans_path"
5502           The install path translated into a libguestfs path.  If unavailable
5503           this is returned as an empty string "".
5504
5505       "app_publisher"
5506           The name of the publisher of the application, for package managers
5507           that use this.  If unavailable this is returned as an empty string
5508           "".
5509
5510       "app_url"
5511           The URL (eg. upstream URL) of the application.  If unavailable this
5512           is returned as an empty string "".
5513
5514       "app_source_package"
5515           For packaging systems which support this, the name of the source
5516           package.  If unavailable this is returned as an empty string "".
5517
5518       "app_summary"
5519           A short (usually one line) description of the application or
5520           package.  If unavailable this is returned as an empty string "".
5521
5522       "app_description"
5523           A longer description of the application or package.  If unavailable
5524           this is returned as an empty string "".
5525
5526       Please read "INSPECTION" in guestfs(3) for more details.
5527
5528       This function is deprecated.  In new code, use the
5529       "inspect-list-applications2" call instead.
5530
5531       Deprecated functions will not be removed from the API, but the fact
5532       that they are deprecated indicates that there are problems with correct
5533       use of these functions.
5534
5535   inspect-list-applications2
5536        inspect-list-applications2 root
5537
5538       Return the list of applications installed in the operating system.
5539
5540       Note: This call works differently from other parts of the inspection
5541       API.  You have to call "inspect-os", then "inspect-get-mountpoints",
5542       then mount up the disks, before calling this.  Listing applications is
5543       a significantly more difficult operation which requires access to the
5544       full filesystem.  Also note that unlike the other "inspect-get-*" calls
5545       which are just returning data cached in the libguestfs handle, this
5546       call actually reads parts of the mounted filesystems during the call.
5547
5548       This returns an empty list if the inspection code was not able to
5549       determine the list of applications.
5550
5551       The application structure contains the following fields:
5552
5553       "app2_name"
5554           The name of the application.  For Linux guests, this is the package
5555           name.
5556
5557       "app2_display_name"
5558           The display name of the application, sometimes localized to the
5559           install language of the guest operating system.
5560
5561           If unavailable this is returned as an empty string "".  Callers
5562           needing to display something can use "app2_name" instead.
5563
5564       "app2_epoch"
5565           For package managers which use epochs, this contains the epoch of
5566           the package (an integer).  If unavailable, this is returned as 0.
5567
5568       "app2_version"
5569           The version string of the application or package.  If unavailable
5570           this is returned as an empty string "".
5571
5572       "app2_release"
5573           The release string of the application or package, for package
5574           managers that use this.  If unavailable this is returned as an
5575           empty string "".
5576
5577       "app2_arch"
5578           The architecture string of the application or package, for package
5579           managers that use this.  If unavailable this is returned as an
5580           empty string "".
5581
5582       "app2_install_path"
5583           The installation path of the application (on operating systems such
5584           as Windows which use installation paths).  This path is in the
5585           format used by the guest operating system, it is not a libguestfs
5586           path.
5587
5588           If unavailable this is returned as an empty string "".
5589
5590       "app2_trans_path"
5591           The install path translated into a libguestfs path.  If unavailable
5592           this is returned as an empty string "".
5593
5594       "app2_publisher"
5595           The name of the publisher of the application, for package managers
5596           that use this.  If unavailable this is returned as an empty string
5597           "".
5598
5599       "app2_url"
5600           The URL (eg. upstream URL) of the application.  If unavailable this
5601           is returned as an empty string "".
5602
5603       "app2_source_package"
5604           For packaging systems which support this, the name of the source
5605           package.  If unavailable this is returned as an empty string "".
5606
5607       "app2_summary"
5608           A short (usually one line) description of the application or
5609           package.  If unavailable this is returned as an empty string "".
5610
5611       "app2_description"
5612           A longer description of the application or package.  If unavailable
5613           this is returned as an empty string "".
5614
5615       Please read "INSPECTION" in guestfs(3) for more details.
5616
5617   inspect-os
5618        inspect-os
5619
5620       This function uses other libguestfs functions and certain heuristics to
5621       inspect the disk(s) (usually disks belonging to a virtual machine),
5622       looking for operating systems.
5623
5624       The list returned is empty if no operating systems were found.
5625
5626       If one operating system was found, then this returns a list with a
5627       single element, which is the name of the root filesystem of this
5628       operating system.  It is also possible for this function to return a
5629       list containing more than one element, indicating a dual-boot or multi-
5630       boot virtual machine, with each element being the root filesystem of
5631       one of the operating systems.
5632
5633       You can pass the root string(s) returned to other "inspect-get-*"
5634       functions in order to query further information about each operating
5635       system, such as the name and version.
5636
5637       This function uses other libguestfs features such as "mount-ro" and
5638       "umount-all" in order to mount and unmount filesystems and look at the
5639       contents.  This should be called with no disks currently mounted.  The
5640       function may also use Augeas, so any existing Augeas handle will be
5641       closed.
5642
5643       This function cannot decrypt encrypted disks.  The caller must do that
5644       first (supplying the necessary keys) if the disk is encrypted.
5645
5646       Please read "INSPECTION" in guestfs(3) for more details.
5647
5648       See also "list-filesystems".
5649
5650   is-blockdev
5651   is-blockdev-opts
5652        is-blockdev path [followsymlinks:true|false]
5653
5654       This returns "true" if and only if there is a block device with the
5655       given "path" name.
5656
5657       If the optional flag "followsymlinks" is true, then a symlink (or chain
5658       of symlinks) that ends with a block device also causes the function to
5659       return true.
5660
5661       This call only looks at files within the guest filesystem.  Libguestfs
5662       partitions and block devices (eg. /dev/sda) cannot be used as the
5663       "path" parameter of this call.
5664
5665       See also "stat".
5666
5667       This command has one or more optional arguments.  See "OPTIONAL
5668       ARGUMENTS".
5669
5670   is-chardev
5671   is-chardev-opts
5672        is-chardev path [followsymlinks:true|false]
5673
5674       This returns "true" if and only if there is a character device with the
5675       given "path" name.
5676
5677       If the optional flag "followsymlinks" is true, then a symlink (or chain
5678       of symlinks) that ends with a chardev also causes the function to
5679       return true.
5680
5681       See also "stat".
5682
5683       This command has one or more optional arguments.  See "OPTIONAL
5684       ARGUMENTS".
5685
5686   is-config
5687        is-config
5688
5689       This returns true iff this handle is being configured (in the "CONFIG"
5690       state).
5691
5692       For more information on states, see guestfs(3).
5693
5694   is-dir
5695   is-dir-opts
5696        is-dir path [followsymlinks:true|false]
5697
5698       This returns "true" if and only if there is a directory with the given
5699       "path" name.  Note that it returns false for other objects like files.
5700
5701       If the optional flag "followsymlinks" is true, then a symlink (or chain
5702       of symlinks) that ends with a directory also causes the function to
5703       return true.
5704
5705       See also "stat".
5706
5707       This command has one or more optional arguments.  See "OPTIONAL
5708       ARGUMENTS".
5709
5710   is-fifo
5711   is-fifo-opts
5712        is-fifo path [followsymlinks:true|false]
5713
5714       This returns "true" if and only if there is a FIFO (named pipe) with
5715       the given "path" name.
5716
5717       If the optional flag "followsymlinks" is true, then a symlink (or chain
5718       of symlinks) that ends with a FIFO also causes the function to return
5719       true.
5720
5721       See also "stat".
5722
5723       This command has one or more optional arguments.  See "OPTIONAL
5724       ARGUMENTS".
5725
5726   is-file
5727   is-file-opts
5728        is-file path [followsymlinks:true|false]
5729
5730       This returns "true" if and only if there is a regular file with the
5731       given "path" name.  Note that it returns false for other objects like
5732       directories.
5733
5734       If the optional flag "followsymlinks" is true, then a symlink (or chain
5735       of symlinks) that ends with a file also causes the function to return
5736       true.
5737
5738       See also "stat".
5739
5740       This command has one or more optional arguments.  See "OPTIONAL
5741       ARGUMENTS".
5742
5743   is-lv
5744        is-lv mountable
5745
5746       This command tests whether "mountable" is a logical volume, and returns
5747       true iff this is the case.
5748
5749   is-socket
5750   is-socket-opts
5751        is-socket path [followsymlinks:true|false]
5752
5753       This returns "true" if and only if there is a Unix domain socket with
5754       the given "path" name.
5755
5756       If the optional flag "followsymlinks" is true, then a symlink (or chain
5757       of symlinks) that ends with a socket also causes the function to return
5758       true.
5759
5760       See also "stat".
5761
5762       This command has one or more optional arguments.  See "OPTIONAL
5763       ARGUMENTS".
5764
5765   is-symlink
5766        is-symlink path
5767
5768       This returns "true" if and only if there is a symbolic link with the
5769       given "path" name.
5770
5771       See also "stat".
5772
5773   is-whole-device
5774        is-whole-device device
5775
5776       This returns "true" if and only if "device" refers to a whole block
5777       device. That is, not a partition or a logical device.
5778
5779   is-zero
5780        is-zero path
5781
5782       This returns true iff the file exists and the file is empty or it
5783       contains all zero bytes.
5784
5785   is-zero-device
5786        is-zero-device device
5787
5788       This returns true iff the device exists and contains all zero bytes.
5789
5790       Note that for large devices this can take a long time to run.
5791
5792   isoinfo
5793        isoinfo isofile
5794
5795       This is the same as "isoinfo-device" except that it works for an ISO
5796       file located inside some other mounted filesystem.  Note that in the
5797       common case where you have added an ISO file as a libguestfs device,
5798       you would not call this.  Instead you would call "isoinfo-device".
5799
5800   isoinfo-device
5801        isoinfo-device device
5802
5803       "device" is an ISO device.  This returns a struct of information read
5804       from the primary volume descriptor (the ISO equivalent of the
5805       superblock) of the device.
5806
5807       Usually it is more efficient to use the isoinfo(1) command with the -d
5808       option on the host to analyze ISO files, instead of going through
5809       libguestfs.
5810
5811       For information on the primary volume descriptor fields, see
5812       https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
5813
5814   journal-close
5815        journal-close
5816
5817       Close the journal handle.
5818
5819       This command depends on the feature "journal".   See also "feature-
5820       available".
5821
5822   journal-get
5823        journal-get
5824
5825       Read the current journal entry.  This returns all the fields in the
5826       journal as a set of "(attrname, attrval)" pairs.  The "attrname" is the
5827       field name (a string).
5828
5829       The "attrval" is the field value (a binary blob, often but not always a
5830       string).  Please note that "attrval" is a byte array, not a
5831       \0-terminated C string.
5832
5833       The length of data may be truncated to the data threshold (see:
5834       "journal-set-data-threshold", "journal-get-data-threshold").
5835
5836       If you set the data threshold to unlimited (0) then this call can read
5837       a journal entry of any size, ie. it is not limited by the libguestfs
5838       protocol.
5839
5840       This command depends on the feature "journal".   See also "feature-
5841       available".
5842
5843   journal-get-data-threshold
5844        journal-get-data-threshold
5845
5846       Get the current data threshold for reading journal entries.  This is a
5847       hint to the journal that it may truncate data fields to this size when
5848       reading them (note also that it may not truncate them).  If this
5849       returns 0, then the threshold is unlimited.
5850
5851       See also "journal-set-data-threshold".
5852
5853       This command depends on the feature "journal".   See also "feature-
5854       available".
5855
5856   journal-get-realtime-usec
5857        journal-get-realtime-usec
5858
5859       Get the realtime (wallclock) timestamp of the current journal entry.
5860
5861       This command depends on the feature "journal".   See also "feature-
5862       available".
5863
5864   journal-next
5865        journal-next
5866
5867       Move to the next journal entry.  You have to call this at least once
5868       after opening the handle before you are able to read data.
5869
5870       The returned boolean tells you if there are any more journal records to
5871       read.  "true" means you can read the next record (eg. using "journal-
5872       get"), and "false" means you have reached the end of the journal.
5873
5874       This command depends on the feature "journal".   See also "feature-
5875       available".
5876
5877   journal-open
5878        journal-open directory
5879
5880       Open the systemd journal located in directory.  Any previously opened
5881       journal handle is closed.
5882
5883       The contents of the journal can be read using "journal-next" and
5884       "journal-get".
5885
5886       After you have finished using the journal, you should close the handle
5887       by calling "journal-close".
5888
5889       This command depends on the feature "journal".   See also "feature-
5890       available".
5891
5892   journal-set-data-threshold
5893        journal-set-data-threshold threshold
5894
5895       Set the data threshold for reading journal entries.  This is a hint to
5896       the journal that it may truncate data fields to this size when reading
5897       them (note also that it may not truncate them).  If you set this to 0,
5898       then the threshold is unlimited.
5899
5900       See also "journal-get-data-threshold".
5901
5902       This command depends on the feature "journal".   See also "feature-
5903       available".
5904
5905   journal-skip
5906        journal-skip skip
5907
5908       Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
5909
5910       The number of entries actually skipped is returned (note "rskip ≥ 0").
5911       If this is not the same as the absolute value of the skip parameter
5912       ("|skip|") you passed in then it means you have reached the end or the
5913       start of the journal.
5914
5915       This command depends on the feature "journal".   See also "feature-
5916       available".
5917
5918   kill-subprocess
5919        kill-subprocess
5920
5921       This kills the hypervisor.
5922
5923       Do not call this.  See: "shutdown" instead.
5924
5925       This function is deprecated.  In new code, use the "shutdown" call
5926       instead.
5927
5928       Deprecated functions will not be removed from the API, but the fact
5929       that they are deprecated indicates that there are problems with correct
5930       use of these functions.
5931
5932   launch
5933   run
5934        launch
5935
5936       You should call this after configuring the handle (eg. adding drives)
5937       but before performing any actions.
5938
5939       Do not call "launch" twice on the same handle.  Although it will not
5940       give an error (for historical reasons), the precise behaviour when you
5941       do this is not well defined.  Handles are very cheap to create, so
5942       create a new one for each launch.
5943
5944   lchown
5945        lchown owner group path
5946
5947       Change the file owner to "owner" and group to "group".  This is like
5948       "chown" but if "path" is a symlink then the link itself is changed, not
5949       the target.
5950
5951       Only numeric uid and gid are supported.  If you want to use names, you
5952       will need to locate and parse the password file yourself (Augeas
5953       support makes this relatively easy).
5954
5955   ldmtool-create-all
5956        ldmtool-create-all
5957
5958       This function scans all block devices looking for Windows dynamic disk
5959       volumes and partitions, and creates devices for any that were found.
5960
5961       Call "list-ldm-volumes" and "list-ldm-partitions" to return all
5962       devices.
5963
5964       Note that you don't normally need to call this explicitly, since it is
5965       done automatically at "launch" time.  However you might want to call
5966       this function if you have hotplugged disks or have just created a
5967       Windows dynamic disk.
5968
5969       This command depends on the feature "ldm".   See also "feature-
5970       available".
5971
5972   ldmtool-diskgroup-disks
5973        ldmtool-diskgroup-disks diskgroup
5974
5975       Return the disks in a Windows dynamic disk group.  The "diskgroup"
5976       parameter should be the GUID of a disk group, one element from the list
5977       returned by "ldmtool-scan".
5978
5979       This command depends on the feature "ldm".   See also "feature-
5980       available".
5981
5982   ldmtool-diskgroup-name
5983        ldmtool-diskgroup-name diskgroup
5984
5985       Return the name of a Windows dynamic disk group.  The "diskgroup"
5986       parameter should be the GUID of a disk group, one element from the list
5987       returned by "ldmtool-scan".
5988
5989       This command depends on the feature "ldm".   See also "feature-
5990       available".
5991
5992   ldmtool-diskgroup-volumes
5993        ldmtool-diskgroup-volumes diskgroup
5994
5995       Return the volumes in a Windows dynamic disk group.  The "diskgroup"
5996       parameter should be the GUID of a disk group, one element from the list
5997       returned by "ldmtool-scan".
5998
5999       This command depends on the feature "ldm".   See also "feature-
6000       available".
6001
6002   ldmtool-remove-all
6003        ldmtool-remove-all
6004
6005       This is essentially the opposite of "ldmtool-create-all".  It removes
6006       the device mapper mappings for all Windows dynamic disk volumes
6007
6008       This command depends on the feature "ldm".   See also "feature-
6009       available".
6010
6011   ldmtool-scan
6012        ldmtool-scan
6013
6014       This function scans for Windows dynamic disks.  It returns a list of
6015       identifiers (GUIDs) for all disk groups that were found.  These
6016       identifiers can be passed to other "ldmtool-*" functions.
6017
6018       This function scans all block devices.  To scan a subset of block
6019       devices, call "ldmtool-scan-devices" instead.
6020
6021       This command depends on the feature "ldm".   See also "feature-
6022       available".
6023
6024   ldmtool-scan-devices
6025        ldmtool-scan-devices 'devices ...'
6026
6027       This function scans for Windows dynamic disks.  It returns a list of
6028       identifiers (GUIDs) for all disk groups that were found.  These
6029       identifiers can be passed to other "ldmtool-*" functions.
6030
6031       The parameter "devices" is a list of block devices which are scanned.
6032       If this list is empty, all block devices are scanned.
6033
6034       This command depends on the feature "ldm".   See also "feature-
6035       available".
6036
6037   ldmtool-volume-hint
6038        ldmtool-volume-hint diskgroup volume
6039
6040       Return the hint field of the volume named "volume" in the disk group
6041       with GUID "diskgroup".  This may not be defined, in which case the
6042       empty string is returned.  The hint field is often, though not always,
6043       the name of a Windows drive, eg. "E:".
6044
6045       This command depends on the feature "ldm".   See also "feature-
6046       available".
6047
6048   ldmtool-volume-partitions
6049        ldmtool-volume-partitions diskgroup volume
6050
6051       Return the list of partitions in the volume named "volume" in the disk
6052       group with GUID "diskgroup".
6053
6054       This command depends on the feature "ldm".   See also "feature-
6055       available".
6056
6057   ldmtool-volume-type
6058        ldmtool-volume-type diskgroup volume
6059
6060       Return the type of the volume named "volume" in the disk group with
6061       GUID "diskgroup".
6062
6063       Possible volume types that can be returned here include: "simple",
6064       "spanned", "striped", "mirrored", "raid5".  Other types may also be
6065       returned.
6066
6067       This command depends on the feature "ldm".   See also "feature-
6068       available".
6069
6070   lgetxattr
6071        lgetxattr path name
6072
6073       Get a single extended attribute from file "path" named "name".  If
6074       "path" is a symlink, then this call returns an extended attribute from
6075       the symlink.
6076
6077       Normally it is better to get all extended attributes from a file in one
6078       go by calling "getxattrs".  However some Linux filesystem
6079       implementations are buggy and do not provide a way to list out
6080       attributes.  For these filesystems (notably ntfs-3g) you have to know
6081       the names of the extended attributes you want in advance and call this
6082       function.
6083
6084       Extended attribute values are blobs of binary data.  If there is no
6085       extended attribute named "name", this returns an error.
6086
6087       See also: "lgetxattrs", "getxattr", attr(5).
6088
6089       This command depends on the feature "linuxxattrs".   See also "feature-
6090       available".
6091
6092   lgetxattrs
6093        lgetxattrs path
6094
6095       This is the same as "getxattrs", but if "path" is a symbolic link, then
6096       it returns the extended attributes of the link itself.
6097
6098       This command depends on the feature "linuxxattrs".   See also "feature-
6099       available".
6100
6101   list-9p
6102        list-9p
6103
6104       List all 9p filesystems attached to the guest.  A list of mount tags is
6105       returned.
6106
6107   list-devices
6108        list-devices
6109
6110       List all the block devices.
6111
6112       The full block device names are returned, eg. /dev/sda.
6113
6114       See also "list-filesystems".
6115
6116   list-disk-labels
6117        list-disk-labels
6118
6119       If you add drives using the optional "label" parameter of "add-drive-
6120       opts", you can use this call to map between disk labels, and raw block
6121       device and partition names (like /dev/sda and /dev/sda1).
6122
6123       This returns a hashtable, where keys are the disk labels (without the
6124       /dev/disk/guestfs prefix), and the values are the full raw block device
6125       and partition names (eg. /dev/sda and /dev/sda1).
6126
6127   list-dm-devices
6128        list-dm-devices
6129
6130       List all device mapper devices.
6131
6132       The returned list contains /dev/mapper/* devices, eg. ones created by a
6133       previous call to "luks-open".
6134
6135       Device mapper devices which correspond to logical volumes are not
6136       returned in this list.  Call "lvs" if you want to list logical volumes.
6137
6138   list-filesystems
6139        list-filesystems
6140
6141       This inspection command looks for filesystems on partitions, block
6142       devices and logical volumes, returning a list of "mountables"
6143       containing filesystems and their type.
6144
6145       The return value is a hash, where the keys are the devices containing
6146       filesystems, and the values are the filesystem types.  For example:
6147
6148        "/dev/sda1" => "ntfs"
6149        "/dev/sda2" => "ext2"
6150        "/dev/vg_guest/lv_root" => "ext4"
6151        "/dev/vg_guest/lv_swap" => "swap"
6152
6153       The key is not necessarily a block device. It may also be an opaque
6154       ‘mountable’ string which can be passed to "mount".
6155
6156       The value can have the special value "unknown", meaning the content of
6157       the device is undetermined or empty.  "swap" means a Linux swap
6158       partition.
6159
6160       In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
6161       might have included "mount" and "umount", and therefore you had to use
6162       this soon after launch and only when nothing else was mounted.  This
6163       restriction is removed in libguestfs ≥ 1.38.
6164
6165       Not all of the filesystems returned will be mountable.  In particular,
6166       swap partitions are returned in the list.  Also this command does not
6167       check that each filesystem found is valid and mountable, and some
6168       filesystems might be mountable but require special options.
6169       Filesystems may not all belong to a single logical operating system
6170       (use "inspect-os" to look for OSes).
6171
6172   list-ldm-partitions
6173        list-ldm-partitions
6174
6175       This function returns all Windows dynamic disk partitions that were
6176       found at launch time.  It returns a list of device names.
6177
6178       This command depends on the feature "ldm".   See also "feature-
6179       available".
6180
6181   list-ldm-volumes
6182        list-ldm-volumes
6183
6184       This function returns all Windows dynamic disk volumes that were found
6185       at launch time.  It returns a list of device names.
6186
6187       This command depends on the feature "ldm".   See also "feature-
6188       available".
6189
6190   list-md-devices
6191        list-md-devices
6192
6193       List all Linux md devices.
6194
6195   list-partitions
6196        list-partitions
6197
6198       List all the partitions detected on all block devices.
6199
6200       The full partition device names are returned, eg. /dev/sda1
6201
6202       This does not return logical volumes.  For that you will need to call
6203       "lvs".
6204
6205       See also "list-filesystems".
6206
6207   ll
6208        ll directory
6209
6210       List the files in directory (relative to the root directory, there is
6211       no cwd) in the format of "ls -la".
6212
6213       This command is mostly useful for interactive sessions.  It is not
6214       intended that you try to parse the output string.
6215
6216   llz
6217        llz directory
6218
6219       List the files in directory in the format of "ls -laZ".
6220
6221       This command is mostly useful for interactive sessions.  It is not
6222       intended that you try to parse the output string.
6223
6224       This function is deprecated.  In new code, use the "lgetxattrs" call
6225       instead.
6226
6227       Deprecated functions will not be removed from the API, but the fact
6228       that they are deprecated indicates that there are problems with correct
6229       use of these functions.
6230
6231   ln
6232        ln target linkname
6233
6234       This command creates a hard link.
6235
6236   ln-f
6237        ln-f target linkname
6238
6239       This command creates a hard link, removing the link "linkname" if it
6240       exists already.
6241
6242   ln-s
6243        ln-s target linkname
6244
6245       This command creates a symbolic link using the "ln -s" command.
6246
6247   ln-sf
6248        ln-sf target linkname
6249
6250       This command creates a symbolic link using the "ln -sf" command, The -f
6251       option removes the link ("linkname") if it exists already.
6252
6253   lremovexattr
6254        lremovexattr xattr path
6255
6256       This is the same as "removexattr", but if "path" is a symbolic link,
6257       then it removes an extended attribute of the link itself.
6258
6259       This command depends on the feature "linuxxattrs".   See also "feature-
6260       available".
6261
6262   ls
6263        ls directory
6264
6265       List the files in directory (relative to the root directory, there is
6266       no cwd).  The "." and ".." entries are not returned, but hidden files
6267       are shown.
6268
6269   ls0
6270        ls0 dir (filenames|-)
6271
6272       This specialized command is used to get a listing of the filenames in
6273       the directory "dir".  The list of filenames is written to the local
6274       file filenames (on the host).
6275
6276       In the output file, the filenames are separated by "\0" characters.
6277
6278       "." and ".." are not returned.  The filenames are not sorted.
6279
6280       Use "-" instead of a filename to read/write from stdin/stdout.
6281
6282   lsetxattr
6283        lsetxattr xattr val vallen path
6284
6285       This is the same as "setxattr", but if "path" is a symbolic link, then
6286       it sets an extended attribute of the link itself.
6287
6288       This command depends on the feature "linuxxattrs".   See also "feature-
6289       available".
6290
6291   lstat
6292        lstat path
6293
6294       Returns file information for the given "path".
6295
6296       This is the same as "stat" except that if "path" is a symbolic link,
6297       then the link is stat-ed, not the file it refers to.
6298
6299       This is the same as the lstat(2) system call.
6300
6301       This function is deprecated.  In new code, use the "lstatns" call
6302       instead.
6303
6304       Deprecated functions will not be removed from the API, but the fact
6305       that they are deprecated indicates that there are problems with correct
6306       use of these functions.
6307
6308   lstatlist
6309        lstatlist path 'names ...'
6310
6311       This call allows you to perform the "lstat" operation on multiple
6312       files, where all files are in the directory "path".  "names" is the
6313       list of files from this directory.
6314
6315       On return you get a list of stat structs, with a one-to-one
6316       correspondence to the "names" list.  If any name did not exist or could
6317       not be lstat'd, then the "st_ino" field of that structure is set to
6318       "-1".
6319
6320       This call is intended for programs that want to efficiently list a
6321       directory contents without making many round-trips.  See also
6322       "lxattrlist" for a similarly efficient call for getting extended
6323       attributes.
6324
6325       This function is deprecated.  In new code, use the "lstatnslist" call
6326       instead.
6327
6328       Deprecated functions will not be removed from the API, but the fact
6329       that they are deprecated indicates that there are problems with correct
6330       use of these functions.
6331
6332   lstatns
6333        lstatns path
6334
6335       Returns file information for the given "path".
6336
6337       This is the same as "statns" except that if "path" is a symbolic link,
6338       then the link is stat-ed, not the file it refers to.
6339
6340       This is the same as the lstat(2) system call.
6341
6342   lstatnslist
6343        lstatnslist path 'names ...'
6344
6345       This call allows you to perform the "lstatns" operation on multiple
6346       files, where all files are in the directory "path".  "names" is the
6347       list of files from this directory.
6348
6349       On return you get a list of stat structs, with a one-to-one
6350       correspondence to the "names" list.  If any name did not exist or could
6351       not be lstat'd, then the "st_ino" field of that structure is set to
6352       "-1".
6353
6354       This call is intended for programs that want to efficiently list a
6355       directory contents without making many round-trips.  See also
6356       "lxattrlist" for a similarly efficient call for getting extended
6357       attributes.
6358
6359   luks-add-key
6360        luks-add-key device keyslot
6361
6362       This command adds a new key on LUKS device "device".  "key" is any
6363       existing key, and is used to access the device.  "newkey" is the new
6364       key to add.  "keyslot" is the key slot that will be replaced.
6365
6366       Note that if "keyslot" already contains a key, then this command will
6367       fail.  You have to use "luks-kill-slot" first to remove that key.
6368
6369       This command has one or more key or passphrase parameters.  Guestfish
6370       will prompt for these separately.
6371
6372       This command depends on the feature "luks".   See also "feature-
6373       available".
6374
6375   luks-close
6376        luks-close device
6377
6378       This closes a LUKS device that was created earlier by "luks-open" or
6379       "luks-open-ro".  The "device" parameter must be the name of the LUKS
6380       mapping device (ie. /dev/mapper/mapname) and not the name of the
6381       underlying block device.
6382
6383       This command depends on the feature "luks".   See also "feature-
6384       available".
6385
6386   luks-format
6387        luks-format device keyslot
6388
6389       This command erases existing data on "device" and formats the device as
6390       a LUKS encrypted device.  "key" is the initial key, which is added to
6391       key slot "keyslot".  (LUKS supports 8 key slots, numbered 0-7).
6392
6393       This command has one or more key or passphrase parameters.  Guestfish
6394       will prompt for these separately.
6395
6396       This command depends on the feature "luks".   See also "feature-
6397       available".
6398
6399   luks-format-cipher
6400        luks-format-cipher device keyslot cipher
6401
6402       This command is the same as "luks-format" but it also allows you to set
6403       the "cipher" used.
6404
6405       This command has one or more key or passphrase parameters.  Guestfish
6406       will prompt for these separately.
6407
6408       This command depends on the feature "luks".   See also "feature-
6409       available".
6410
6411   luks-kill-slot
6412        luks-kill-slot device keyslot
6413
6414       This command deletes the key in key slot "keyslot" from the encrypted
6415       LUKS device "device".  "key" must be one of the other keys.
6416
6417       This command has one or more key or passphrase parameters.  Guestfish
6418       will prompt for these separately.
6419
6420       This command depends on the feature "luks".   See also "feature-
6421       available".
6422
6423   luks-open
6424        luks-open device mapname
6425
6426       This command opens a block device which has been encrypted according to
6427       the Linux Unified Key Setup (LUKS) standard.
6428
6429       "device" is the encrypted block device or partition.
6430
6431       The caller must supply one of the keys associated with the LUKS block
6432       device, in the "key" parameter.
6433
6434       This creates a new block device called /dev/mapper/mapname.  Reads and
6435       writes to this block device are decrypted from and encrypted to the
6436       underlying "device" respectively.
6437
6438       If this block device contains LVM volume groups, then calling "lvm-
6439       scan" with the "activate" parameter "true" will make them visible.
6440
6441       Use "list-dm-devices" to list all device mapper devices.
6442
6443       This command has one or more key or passphrase parameters.  Guestfish
6444       will prompt for these separately.
6445
6446       This command depends on the feature "luks".   See also "feature-
6447       available".
6448
6449   luks-open-ro
6450        luks-open-ro device mapname
6451
6452       This is the same as "luks-open" except that a read-only mapping is
6453       created.
6454
6455       This command has one or more key or passphrase parameters.  Guestfish
6456       will prompt for these separately.
6457
6458       This command depends on the feature "luks".   See also "feature-
6459       available".
6460
6461   luks-uuid
6462        luks-uuid device
6463
6464       This returns the UUID of the LUKS device "device".
6465
6466       This command depends on the feature "luks".   See also "feature-
6467       available".
6468
6469   lvcreate
6470        lvcreate logvol volgroup mbytes
6471
6472       This creates an LVM logical volume called "logvol" on the volume group
6473       "volgroup", with "size" megabytes.
6474
6475       This command depends on the feature "lvm2".   See also "feature-
6476       available".
6477
6478   lvcreate-free
6479        lvcreate-free logvol volgroup percent
6480
6481       Create an LVM logical volume called /dev/volgroup/logvol, using
6482       approximately "percent" % of the free space remaining in the volume
6483       group.  Most usefully, when "percent" is 100 this will create the
6484       largest possible LV.
6485
6486       This command depends on the feature "lvm2".   See also "feature-
6487       available".
6488
6489   lvm-canonical-lv-name
6490        lvm-canonical-lv-name lvname
6491
6492       This converts alternative naming schemes for LVs that you might find to
6493       the canonical name.  For example, /dev/mapper/VG-LV is converted to
6494       /dev/VG/LV.
6495
6496       This command returns an error if the "lvname" parameter does not refer
6497       to a logical volume.
6498
6499       See also "is-lv", "canonical-device-name".
6500
6501   lvm-clear-filter
6502        lvm-clear-filter
6503
6504       This undoes the effect of "lvm-set-filter".  LVM will be able to see
6505       every block device.
6506
6507       This command also clears the LVM cache and performs a volume group
6508       scan.
6509
6510   lvm-remove-all
6511        lvm-remove-all
6512
6513       This command removes all LVM logical volumes, volume groups and
6514       physical volumes.
6515
6516       This command depends on the feature "lvm2".   See also "feature-
6517       available".
6518
6519   lvm-scan
6520        lvm-scan true|false
6521
6522       This scans all block devices and rebuilds the list of LVM physical
6523       volumes, volume groups and logical volumes.
6524
6525       If the "activate" parameter is "true" then newly found volume groups
6526       and logical volumes are activated, meaning the LV /dev/VG/LV devices
6527       become visible.
6528
6529       When a libguestfs handle is launched it scans for existing devices, so
6530       you do not normally need to use this API.  However it is useful when
6531       you have added a new device or deleted an existing device (such as when
6532       the "luks-open" API is used).
6533
6534   lvm-set-filter
6535        lvm-set-filter 'devices ...'
6536
6537       This sets the LVM device filter so that LVM will only be able to "see"
6538       the block devices in the list "devices", and will ignore all other
6539       attached block devices.
6540
6541       Where disk image(s) contain duplicate PVs or VGs, this command is
6542       useful to get LVM to ignore the duplicates, otherwise LVM can get
6543       confused.  Note also there are two types of duplication possible:
6544       either cloned PVs/VGs which have identical UUIDs; or VGs that are not
6545       cloned but just happen to have the same name.  In normal operation you
6546       cannot create this situation, but you can do it outside LVM, eg.  by
6547       cloning disk images or by bit twiddling inside the LVM metadata.
6548
6549       This command also clears the LVM cache and performs a volume group
6550       scan.
6551
6552       You can filter whole block devices or individual partitions.
6553
6554       You cannot use this if any VG is currently in use (eg.  contains a
6555       mounted filesystem), even if you are not filtering out that VG.
6556
6557       This command depends on the feature "lvm2".   See also "feature-
6558       available".
6559
6560   lvremove
6561        lvremove device
6562
6563       Remove an LVM logical volume "device", where "device" is the path to
6564       the LV, such as /dev/VG/LV.
6565
6566       You can also remove all LVs in a volume group by specifying the VG
6567       name, /dev/VG.
6568
6569       This command depends on the feature "lvm2".   See also "feature-
6570       available".
6571
6572   lvrename
6573        lvrename logvol newlogvol
6574
6575       Rename a logical volume "logvol" with the new name "newlogvol".
6576
6577   lvresize
6578        lvresize device mbytes
6579
6580       This resizes (expands or shrinks) an existing LVM logical volume to
6581       "mbytes".  When reducing, data in the reduced part is lost.
6582
6583       This command depends on the feature "lvm2".   See also "feature-
6584       available".
6585
6586   lvresize-free
6587        lvresize-free lv percent
6588
6589       This expands an existing logical volume "lv" so that it fills "pc" % of
6590       the remaining free space in the volume group.  Commonly you would call
6591       this with pc = 100 which expands the logical volume as much as
6592       possible, using all remaining free space in the volume group.
6593
6594       This command depends on the feature "lvm2".   See also "feature-
6595       available".
6596
6597   lvs
6598        lvs
6599
6600       List all the logical volumes detected.  This is the equivalent of the
6601       lvs(8) command.
6602
6603       This returns a list of the logical volume device names (eg.
6604       /dev/VolGroup00/LogVol00).
6605
6606       See also "lvs-full", "list-filesystems".
6607
6608       This command depends on the feature "lvm2".   See also "feature-
6609       available".
6610
6611   lvs-full
6612        lvs-full
6613
6614       List all the logical volumes detected.  This is the equivalent of the
6615       lvs(8) command.  The "full" version includes all fields.
6616
6617       This command depends on the feature "lvm2".   See also "feature-
6618       available".
6619
6620   lvuuid
6621        lvuuid device
6622
6623       This command returns the UUID of the LVM LV "device".
6624
6625   lxattrlist
6626        lxattrlist path 'names ...'
6627
6628       This call allows you to get the extended attributes of multiple files,
6629       where all files are in the directory "path".  "names" is the list of
6630       files from this directory.
6631
6632       On return you get a flat list of xattr structs which must be
6633       interpreted sequentially.  The first xattr struct always has a zero-
6634       length "attrname".  "attrval" in this struct is zero-length to indicate
6635       there was an error doing "lgetxattr" for this file, or is a C string
6636       which is a decimal number (the number of following attributes for this
6637       file, which could be "0").  Then after the first xattr struct are the
6638       zero or more attributes for the first named file.  This repeats for the
6639       second and subsequent files.
6640
6641       This call is intended for programs that want to efficiently list a
6642       directory contents without making many round-trips.  See also
6643       "lstatlist" for a similarly efficient call for getting standard stats.
6644
6645       This command depends on the feature "linuxxattrs".   See also "feature-
6646       available".
6647
6648   max-disks
6649        max-disks
6650
6651       Return the maximum number of disks that may be added to a handle (eg.
6652       by "add-drive-opts" and similar calls).
6653
6654       This function was added in libguestfs 1.19.7.  In previous versions of
6655       libguestfs the limit was 25.
6656
6657       See "MAXIMUM NUMBER OF DISKS" in guestfs(3) for additional information
6658       on this topic.
6659
6660   md-create
6661        md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]
6662
6663       Create a Linux md (RAID) device named "name" on the devices in the list
6664       "devices".
6665
6666       The optional parameters are:
6667
6668       "missingbitmap"
6669           A bitmap of missing devices.  If a bit is set it means that a
6670           missing device is added to the array.  The least significant bit
6671           corresponds to the first device in the array.
6672
6673           As examples:
6674
6675           If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
6676           resulting array would be "[<missing>, "/dev/sda"]".
6677
6678           If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
6679           resulting array would be "["/dev/sda", <missing>]".
6680
6681           This defaults to 0 (no missing devices).
6682
6683           The length of "devices" + the number of bits set in "missingbitmap"
6684           must equal "nrdevices" + "spare".
6685
6686       "nrdevices"
6687           The number of active RAID devices.
6688
6689           If not set, this defaults to the length of "devices" plus the
6690           number of bits set in "missingbitmap".
6691
6692       "spare"
6693           The number of spare devices.
6694
6695           If not set, this defaults to 0.
6696
6697       "chunk"
6698           The chunk size in bytes.
6699
6700       "level"
6701           The RAID level, which can be one of: "linear", "raid0", 0,
6702           "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
6703           "raid10", 10.  Some of these are synonymous, and more levels may be
6704           added in future.
6705
6706           If not set, this defaults to "raid1".
6707
6708       This command has one or more optional arguments.  See "OPTIONAL
6709       ARGUMENTS".
6710
6711       This command depends on the feature "mdadm".   See also "feature-
6712       available".
6713
6714   md-detail
6715        md-detail md
6716
6717       This command exposes the output of "mdadm -DY <md>".  The following
6718       fields are usually present in the returned hash.  Other fields may also
6719       be present.
6720
6721       "level"
6722           The raid level of the MD device.
6723
6724       "devices"
6725           The number of underlying devices in the MD device.
6726
6727       "metadata"
6728           The metadata version used.
6729
6730       "uuid"
6731           The UUID of the MD device.
6732
6733       "name"
6734           The name of the MD device.
6735
6736       This command depends on the feature "mdadm".   See also "feature-
6737       available".
6738
6739   md-stat
6740        md-stat md
6741
6742       This call returns a list of the underlying devices which make up the
6743       single software RAID array device "md".
6744
6745       To get a list of software RAID devices, call "list-md-devices".
6746
6747       Each structure returned corresponds to one device along with additional
6748       status information:
6749
6750       "mdstat_device"
6751           The name of the underlying device.
6752
6753       "mdstat_index"
6754           The index of this device within the array.
6755
6756       "mdstat_flags"
6757           Flags associated with this device.  This is a string containing (in
6758           no specific order) zero or more of the following flags:
6759
6760           "W" write-mostly
6761
6762           "F" device is faulty
6763
6764           "S" device is a RAID spare
6765
6766           "R" replacement
6767
6768       This command depends on the feature "mdadm".   See also "feature-
6769       available".
6770
6771   md-stop
6772        md-stop md
6773
6774       This command deactivates the MD array named "md".  The device is
6775       stopped, but it is not destroyed or zeroed.
6776
6777       This command depends on the feature "mdadm".   See also "feature-
6778       available".
6779
6780   mkdir
6781        mkdir path
6782
6783       Create a directory named "path".
6784
6785   mkdir-mode
6786        mkdir-mode path mode
6787
6788       This command creates a directory, setting the initial permissions of
6789       the directory to "mode".
6790
6791       For common Linux filesystems, the actual mode which is set will be
6792       "mode & ~umask & 01777".  Non-native-Linux filesystems may interpret
6793       the mode in other ways.
6794
6795       See also "mkdir", "umask"
6796
6797   mkdir-p
6798        mkdir-p path
6799
6800       Create a directory named "path", creating any parent directories as
6801       necessary.  This is like the "mkdir -p" shell command.
6802
6803   mkdtemp
6804        mkdtemp tmpl
6805
6806       This command creates a temporary directory.  The "tmpl" parameter
6807       should be a full pathname for the temporary directory name with the
6808       final six characters being "XXXXXX".
6809
6810       For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
6811       one being suitable for Windows filesystems.
6812
6813       The name of the temporary directory that was created is returned.
6814
6815       The temporary directory is created with mode 0700 and is owned by root.
6816
6817       The caller is responsible for deleting the temporary directory and its
6818       contents after use.
6819
6820       See also: mkdtemp(3)
6821
6822   mke2fs
6823        mke2fs device [blockscount:N] [blocksize:N] [fragsize:N] [blockspergroup:N] [numberofgroups:N] [bytesperinode:N] [inodesize:N] [journalsize:N] [numberofinodes:N] [stridesize:N] [stripewidth:N] [maxonlineresize:N] [reservedblockspercentage:N] [mmpupdateinterval:N] [journaldevice:..] [label:..] [lastmounteddir:..] [creatoros:..] [fstype:..] [usagetype:..] [uuid:..] [forcecreate:true|false] [writesbandgrouponly:true|false] [lazyitableinit:true|false] [lazyjournalinit:true|false] [testfs:true|false] [discard:true|false] [quotatype:true|false] [extent:true|false] [filetype:true|false] [flexbg:true|false] [hasjournal:true|false] [journaldev:true|false] [largefile:true|false] [quota:true|false] [resizeinode:true|false] [sparsesuper:true|false] [uninitbg:true|false]
6824
6825       "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
6826       "device".
6827
6828       The optional "blockscount" is the size of the filesystem in blocks.  If
6829       omitted it defaults to the size of "device".  Note if the filesystem is
6830       too small to contain a journal, "mke2fs" will silently create an ext2
6831       filesystem instead.
6832
6833       This command has one or more optional arguments.  See "OPTIONAL
6834       ARGUMENTS".
6835
6836   mke2fs-J
6837        mke2fs-J fstype blocksize device journal
6838
6839       This creates an ext2/3/4 filesystem on "device" with an external
6840       journal on "journal".  It is equivalent to the command:
6841
6842        mke2fs -t fstype -b blocksize -J device=<journal> <device>
6843
6844       See also "mke2journal".
6845
6846       This function is deprecated.  In new code, use the "mke2fs" call
6847       instead.
6848
6849       Deprecated functions will not be removed from the API, but the fact
6850       that they are deprecated indicates that there are problems with correct
6851       use of these functions.
6852
6853   mke2fs-JL
6854        mke2fs-JL fstype blocksize device label
6855
6856       This creates an ext2/3/4 filesystem on "device" with an external
6857       journal on the journal labeled "label".
6858
6859       See also "mke2journal-L".
6860
6861       This function is deprecated.  In new code, use the "mke2fs" call
6862       instead.
6863
6864       Deprecated functions will not be removed from the API, but the fact
6865       that they are deprecated indicates that there are problems with correct
6866       use of these functions.
6867
6868   mke2fs-JU
6869        mke2fs-JU fstype blocksize device uuid
6870
6871       This creates an ext2/3/4 filesystem on "device" with an external
6872       journal on the journal with UUID "uuid".
6873
6874       See also "mke2journal-U".
6875
6876       This function is deprecated.  In new code, use the "mke2fs" call
6877       instead.
6878
6879       Deprecated functions will not be removed from the API, but the fact
6880       that they are deprecated indicates that there are problems with correct
6881       use of these functions.
6882
6883       This command depends on the feature "linuxfsuuid".   See also "feature-
6884       available".
6885
6886   mke2journal
6887        mke2journal blocksize device
6888
6889       This creates an ext2 external journal on "device".  It is equivalent to
6890       the command:
6891
6892        mke2fs -O journal_dev -b blocksize device
6893
6894       This function is deprecated.  In new code, use the "mke2fs" call
6895       instead.
6896
6897       Deprecated functions will not be removed from the API, but the fact
6898       that they are deprecated indicates that there are problems with correct
6899       use of these functions.
6900
6901   mke2journal-L
6902        mke2journal-L blocksize label device
6903
6904       This creates an ext2 external journal on "device" with label "label".
6905
6906       This function is deprecated.  In new code, use the "mke2fs" call
6907       instead.
6908
6909       Deprecated functions will not be removed from the API, but the fact
6910       that they are deprecated indicates that there are problems with correct
6911       use of these functions.
6912
6913   mke2journal-U
6914        mke2journal-U blocksize uuid device
6915
6916       This creates an ext2 external journal on "device" with UUID "uuid".
6917
6918       This function is deprecated.  In new code, use the "mke2fs" call
6919       instead.
6920
6921       Deprecated functions will not be removed from the API, but the fact
6922       that they are deprecated indicates that there are problems with correct
6923       use of these functions.
6924
6925       This command depends on the feature "linuxfsuuid".   See also "feature-
6926       available".
6927
6928   mkfifo
6929        mkfifo mode path
6930
6931       This call creates a FIFO (named pipe) called "path" with mode "mode".
6932       It is just a convenient wrapper around "mknod".
6933
6934       Unlike with "mknod", "mode" must contain only permissions bits.
6935
6936       The mode actually set is affected by the umask.
6937
6938       This command depends on the feature "mknod".   See also "feature-
6939       available".
6940
6941   mkfs
6942   mkfs-opts
6943        mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N] [label:..]
6944
6945       This function creates a filesystem on "device".  The filesystem type is
6946       "fstype", for example "ext3".
6947
6948       The optional arguments are:
6949
6950       "blocksize"
6951           The filesystem block size.  Supported block sizes depend on the
6952           filesystem type, but typically they are 1024, 2048 or 4096 for
6953           Linux ext2/3 filesystems.
6954
6955           For VFAT and NTFS the "blocksize" parameter is treated as the
6956           requested cluster size.
6957
6958           For UFS block sizes, please see mkfs.ufs(8).
6959
6960       "features"
6961           This passes the -O parameter to the external mkfs program.
6962
6963           For certain filesystem types, this allows extra filesystem features
6964           to be selected.  See mke2fs(8) and mkfs.ufs(8) for more details.
6965
6966           You cannot use this optional parameter with the "gfs" or "gfs2"
6967           filesystem type.
6968
6969       "inode"
6970           This passes the -I parameter to the external mke2fs(8) program
6971           which sets the inode size (only for ext2/3/4 filesystems at
6972           present).
6973
6974       "sectorsize"
6975           This passes the -S parameter to external mkfs.ufs(8) program, which
6976           sets sector size for ufs filesystem.
6977
6978       This command has one or more optional arguments.  See "OPTIONAL
6979       ARGUMENTS".
6980
6981   mkfs-b
6982        mkfs-b fstype blocksize device
6983
6984       This call is similar to "mkfs", but it allows you to control the block
6985       size of the resulting filesystem.  Supported block sizes depend on the
6986       filesystem type, but typically they are 1024, 2048 or 4096 only.
6987
6988       For VFAT and NTFS the "blocksize" parameter is treated as the requested
6989       cluster size.
6990
6991       This function is deprecated.  In new code, use the "mkfs" call instead.
6992
6993       Deprecated functions will not be removed from the API, but the fact
6994       that they are deprecated indicates that there are problems with correct
6995       use of these functions.
6996
6997   mkfs-btrfs
6998        mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]
6999
7000       Create a btrfs filesystem, allowing all configurables to be set.  For
7001       more information on the optional arguments, see mkfs.btrfs(8).
7002
7003       Since btrfs filesystems can span multiple devices, this takes a non-
7004       empty list of devices.
7005
7006       To create general filesystems, use "mkfs".
7007
7008       This command has one or more optional arguments.  See "OPTIONAL
7009       ARGUMENTS".
7010
7011       This command depends on the feature "btrfs".   See also "feature-
7012       available".
7013
7014   mklost-and-found
7015        mklost-and-found mountpoint
7016
7017       Make the "lost+found" directory, normally in the root directory of an
7018       ext2/3/4 filesystem.  "mountpoint" is the directory under which we try
7019       to create the "lost+found" directory.
7020
7021   mkmountpoint
7022        mkmountpoint exemptpath
7023
7024       "mkmountpoint" and "rmmountpoint" are specialized calls that can be
7025       used to create extra mountpoints before mounting the first filesystem.
7026
7027       These calls are only necessary in some very limited circumstances,
7028       mainly the case where you want to mount a mix of unrelated and/or read-
7029       only filesystems together.
7030
7031       For example, live CDs often contain a "Russian doll" nest of
7032       filesystems, an ISO outer layer, with a squashfs image inside, with an
7033       ext2/3 image inside that.  You can unpack this as follows in guestfish:
7034
7035        add-ro Fedora-11-i686-Live.iso
7036        run
7037        mkmountpoint /cd
7038        mkmountpoint /sqsh
7039        mkmountpoint /ext3fs
7040        mount /dev/sda /cd
7041        mount-loop /cd/LiveOS/squashfs.img /sqsh
7042        mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
7043
7044       The inner filesystem is now unpacked under the /ext3fs mountpoint.
7045
7046       "mkmountpoint" is not compatible with "umount-all".  You may get
7047       unexpected errors if you try to mix these calls.  It is safest to
7048       manually unmount filesystems and remove mountpoints after use.
7049
7050       "umount-all" unmounts filesystems by sorting the paths longest first,
7051       so for this to work for manual mountpoints, you must ensure that the
7052       innermost mountpoints have the longest pathnames, as in the example
7053       code above.
7054
7055       For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
7056
7057       Autosync [see "set-autosync", this is set by default on handles] can
7058       cause "umount-all" to be called when the handle is closed which can
7059       also trigger these issues.
7060
7061   mknod
7062        mknod mode devmajor devminor path
7063
7064       This call creates block or character special devices, or named pipes
7065       (FIFOs).
7066
7067       The "mode" parameter should be the mode, using the standard constants.
7068       "devmajor" and "devminor" are the device major and minor numbers, only
7069       used when creating block and character special devices.
7070
7071       Note that, just like mknod(2), the mode must be bitwise OR'd with
7072       S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
7073       a regular file).  These constants are available in the standard Linux
7074       header files, or you can use "mknod-b", "mknod-c" or "mkfifo" which are
7075       wrappers around this command which bitwise OR in the appropriate
7076       constant for you.
7077
7078       The mode actually set is affected by the umask.
7079
7080       This command depends on the feature "mknod".   See also "feature-
7081       available".
7082
7083   mknod-b
7084        mknod-b mode devmajor devminor path
7085
7086       This call creates a block device node called "path" with mode "mode"
7087       and device major/minor "devmajor" and "devminor".  It is just a
7088       convenient wrapper around "mknod".
7089
7090       Unlike with "mknod", "mode" must contain only permissions bits.
7091
7092       The mode actually set is affected by the umask.
7093
7094       This command depends on the feature "mknod".   See also "feature-
7095       available".
7096
7097   mknod-c
7098        mknod-c mode devmajor devminor path
7099
7100       This call creates a char device node called "path" with mode "mode" and
7101       device major/minor "devmajor" and "devminor".  It is just a convenient
7102       wrapper around "mknod".
7103
7104       Unlike with "mknod", "mode" must contain only permissions bits.
7105
7106       The mode actually set is affected by the umask.
7107
7108       This command depends on the feature "mknod".   See also "feature-
7109       available".
7110
7111   mksquashfs
7112        mksquashfs path (filename|-) [compress:..] [excludes:..]
7113
7114       Create a squashfs filesystem for the specified "path".
7115
7116       The optional "compress" flag controls compression.  If not given, then
7117       the output compressed using "gzip".  Otherwise one of the following
7118       strings may be given to select the compression type of the squashfs:
7119       "gzip", "lzma", "lzo", "lz4", "xz".
7120
7121       The other optional arguments are:
7122
7123       "excludes"
7124           A list of wildcards.  Files are excluded if they match any of the
7125           wildcards.
7126
7127       Please note that this API may fail when used to compress directories
7128       with large files, such as the resulting squashfs will be over 3GB big.
7129
7130       Use "-" instead of a filename to read/write from stdin/stdout.
7131
7132       This command has one or more optional arguments.  See "OPTIONAL
7133       ARGUMENTS".
7134
7135       This command depends on the feature "squashfs".   See also "feature-
7136       available".
7137
7138   mkswap
7139   mkswap-opts
7140        mkswap device [label:..] [uuid:..]
7141
7142       Create a Linux swap partition on "device".
7143
7144       The option arguments "label" and "uuid" allow you to set the label
7145       and/or UUID of the new swap partition.
7146
7147       This command has one or more optional arguments.  See "OPTIONAL
7148       ARGUMENTS".
7149
7150   mkswap-L
7151        mkswap-L label device
7152
7153       Create a swap partition on "device" with label "label".
7154
7155       Note that you cannot attach a swap label to a block device (eg.
7156       /dev/sda), just to a partition.  This appears to be a limitation of the
7157       kernel or swap tools.
7158
7159       This function is deprecated.  In new code, use the "mkswap" call
7160       instead.
7161
7162       Deprecated functions will not be removed from the API, but the fact
7163       that they are deprecated indicates that there are problems with correct
7164       use of these functions.
7165
7166   mkswap-U
7167        mkswap-U uuid device
7168
7169       Create a swap partition on "device" with UUID "uuid".
7170
7171       This function is deprecated.  In new code, use the "mkswap" call
7172       instead.
7173
7174       Deprecated functions will not be removed from the API, but the fact
7175       that they are deprecated indicates that there are problems with correct
7176       use of these functions.
7177
7178       This command depends on the feature "linuxfsuuid".   See also "feature-
7179       available".
7180
7181   mkswap-file
7182        mkswap-file path
7183
7184       Create a swap file.
7185
7186       This command just writes a swap file signature to an existing file.  To
7187       create the file itself, use something like "fallocate".
7188
7189   mktemp
7190        mktemp tmpl [suffix:..]
7191
7192       This command creates a temporary file.  The "tmpl" parameter should be
7193       a full pathname for the temporary directory name with the final six
7194       characters being "XXXXXX".
7195
7196       For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
7197       one being suitable for Windows filesystems.
7198
7199       The name of the temporary file that was created is returned.
7200
7201       The temporary file is created with mode 0600 and is owned by root.
7202
7203       The caller is responsible for deleting the temporary file after use.
7204
7205       If the optional "suffix" parameter is given, then the suffix (eg.
7206       ".txt") is appended to the temporary name.
7207
7208       See also: "mkdtemp".
7209
7210       This command has one or more optional arguments.  See "OPTIONAL
7211       ARGUMENTS".
7212
7213   modprobe
7214        modprobe modulename
7215
7216       This loads a kernel module in the appliance.
7217
7218       This command depends on the feature "linuxmodules".   See also
7219       "feature-available".
7220
7221   mount
7222        mount mountable mountpoint
7223
7224       Mount a guest disk at a position in the filesystem.  Block devices are
7225       named /dev/sda, /dev/sdb and so on, as they were added to the guest.
7226       If those block devices contain partitions, they will have the usual
7227       names (eg. /dev/sda1).  Also LVM /dev/VG/LV-style names can be used, or
7228       ‘mountable’ strings returned by "list-filesystems" or "inspect-get-
7229       mountpoints".
7230
7231       The rules are the same as for mount(2):  A filesystem must first be
7232       mounted on / before others can be mounted.  Other filesystems can only
7233       be mounted on directories which already exist.
7234
7235       The mounted filesystem is writable, if we have sufficient permissions
7236       on the underlying device.
7237
7238       Before libguestfs 1.13.16, this call implicitly added the options
7239       "sync" and "noatime".  The "sync" option greatly slowed writes and
7240       caused many problems for users.  If your program might need to work
7241       with older versions of libguestfs, use "mount-options" instead (using
7242       an empty string for the first parameter if you don't want any options).
7243
7244   mount-9p
7245        mount-9p mounttag mountpoint [options:..]
7246
7247       Mount the virtio-9p filesystem with the tag "mounttag" on the directory
7248       "mountpoint".
7249
7250       If required, "trans=virtio" will be automatically added to the options.
7251       Any other options required can be passed in the optional "options"
7252       parameter.
7253
7254       This command has one or more optional arguments.  See "OPTIONAL
7255       ARGUMENTS".
7256
7257   mount-local
7258        mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]
7259
7260       This call exports the libguestfs-accessible filesystem to a local
7261       mountpoint (directory) called "localmountpoint".  Ordinary reads and
7262       writes to files and directories under "localmountpoint" are redirected
7263       through libguestfs.
7264
7265       If the optional "readonly" flag is set to true, then writes to the
7266       filesystem return error "EROFS".
7267
7268       "options" is a comma-separated list of mount options.  See
7269       guestmount(1) for some useful options.
7270
7271       "cachetimeout" sets the timeout (in seconds) for cached directory
7272       entries.  The default is 60 seconds.  See guestmount(1) for further
7273       information.
7274
7275       If "debugcalls" is set to true, then additional debugging information
7276       is generated for every FUSE call.
7277
7278       When "mount-local" returns, the filesystem is ready, but is not
7279       processing requests (access to it will block).  You have to call
7280       "mount-local-run" to run the main loop.
7281
7282       See "MOUNT LOCAL" in guestfs(3) for full documentation.
7283
7284       This command has one or more optional arguments.  See "OPTIONAL
7285       ARGUMENTS".
7286
7287   mount-local-run
7288        mount-local-run
7289
7290       Run the main loop which translates kernel calls to libguestfs calls.
7291
7292       This should only be called after "mount-local" returns successfully.
7293       The call will not return until the filesystem is unmounted.
7294
7295       Note you must not make concurrent libguestfs calls on the same handle
7296       from another thread.
7297
7298       You may call this from a different thread than the one which called
7299       "mount-local", subject to the usual rules for threads and libguestfs
7300       (see "MULTIPLE HANDLES AND MULTIPLE THREADS" in guestfs(3)).
7301
7302       See "MOUNT LOCAL" in guestfs(3) for full documentation.
7303
7304   mount-loop
7305        mount-loop file mountpoint
7306
7307       This command lets you mount file (a filesystem image in a file) on a
7308       mount point.  It is entirely equivalent to the command "mount -o loop
7309       file mountpoint".
7310
7311   mount-options
7312        mount-options options mountable mountpoint
7313
7314       This is the same as the "mount" command, but it allows you to set the
7315       mount options as for the mount(8) -o flag.
7316
7317       If the "options" parameter is an empty string, then no options are
7318       passed (all options default to whatever the filesystem uses).
7319
7320   mount-ro
7321        mount-ro mountable mountpoint
7322
7323       This is the same as the "mount" command, but it mounts the filesystem
7324       with the read-only (-o ro) flag.
7325
7326   mount-vfs
7327        mount-vfs options vfstype mountable mountpoint
7328
7329       This is the same as the "mount" command, but it allows you to set both
7330       the mount options and the vfstype as for the mount(8) -o and -t flags.
7331
7332   mountable-device
7333        mountable-device mountable
7334
7335       Returns the device name of a mountable. In quite a lot of cases, the
7336       mountable is the device name.
7337
7338       However this doesn't apply for btrfs subvolumes, where the mountable is
7339       a combination of both the device name and the subvolume path (see also
7340       "mountable-subvolume" to extract the subvolume path of the mountable if
7341       any).
7342
7343   mountable-subvolume
7344        mountable-subvolume mountable
7345
7346       Returns the subvolume path of a mountable. Btrfs subvolumes mountables
7347       are a combination of both the device name and the subvolume path (see
7348       also "mountable-device" to extract the device of the mountable).
7349
7350       If the mountable does not represent a btrfs subvolume, then this
7351       function fails and the "errno" is set to "EINVAL".
7352
7353   mountpoints
7354        mountpoints
7355
7356       This call is similar to "mounts".  That call returns a list of devices.
7357       This one returns a hash table (map) of device name to directory where
7358       the device is mounted.
7359
7360   mounts
7361        mounts
7362
7363       This returns the list of currently mounted filesystems.  It returns the
7364       list of devices (eg. /dev/sda1, /dev/VG/LV).
7365
7366       Some internal mounts are not shown.
7367
7368       See also: "mountpoints"
7369
7370   mv
7371        mv src dest
7372
7373       This moves a file from "src" to "dest" where "dest" is either a
7374       destination filename or destination directory.
7375
7376       See also: "rename".
7377
7378   nr-devices
7379        nr-devices
7380
7381       This returns the number of whole block devices that were added.  This
7382       is the same as the number of devices that would be returned if you
7383       called "list-devices".
7384
7385       To find out the maximum number of devices that could be added, call
7386       "max-disks".
7387
7388   ntfs-3g-probe
7389        ntfs-3g-probe true|false device
7390
7391       This command runs the ntfs-3g.probe(8) command which probes an NTFS
7392       "device" for mountability.  (Not all NTFS volumes can be mounted read-
7393       write, and some cannot be mounted at all).
7394
7395       "rw" is a boolean flag.  Set it to true if you want to test if the
7396       volume can be mounted read-write.  Set it to false if you want to test
7397       if the volume can be mounted read-only.
7398
7399       The return value is an integer which 0 if the operation would succeed,
7400       or some non-zero value documented in the ntfs-3g.probe(8) manual page.
7401
7402       This command depends on the feature "ntfs3g".   See also "feature-
7403       available".
7404
7405   ntfscat-i
7406        ntfscat-i device inode (filename|-)
7407
7408       Download a file given its inode from a NTFS filesystem and save it as
7409       filename on the local machine.
7410
7411       This allows to download some otherwise inaccessible files such as the
7412       ones within the $Extend folder.
7413
7414       The filesystem from which to extract the file must be unmounted,
7415       otherwise the call will fail.
7416
7417       Use "-" instead of a filename to read/write from stdin/stdout.
7418
7419   ntfsclone-in
7420        ntfsclone-in (backupfile|-) device
7421
7422       Restore the "backupfile" (from a previous call to "ntfsclone-out") to
7423       "device", overwriting any existing contents of this device.
7424
7425       Use "-" instead of a filename to read/write from stdin/stdout.
7426
7427       This command depends on the feature "ntfs3g".   See also "feature-
7428       available".
7429
7430   ntfsclone-out
7431        ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]
7432
7433       Stream the NTFS filesystem "device" to the local file "backupfile".
7434       The format used for the backup file is a special format used by the
7435       ntfsclone(8) tool.
7436
7437       If the optional "metadataonly" flag is true, then only the metadata is
7438       saved, losing all the user data (this is useful for diagnosing some
7439       filesystem problems).
7440
7441       The optional "rescue", "ignorefscheck", "preservetimestamps" and
7442       "force" flags have precise meanings detailed in the ntfsclone(8) man
7443       page.
7444
7445       Use "ntfsclone-in" to restore the file back to a libguestfs device.
7446
7447       Use "-" instead of a filename to read/write from stdin/stdout.
7448
7449       This command has one or more optional arguments.  See "OPTIONAL
7450       ARGUMENTS".
7451
7452       This command depends on the feature "ntfs3g".   See also "feature-
7453       available".
7454
7455   ntfsfix
7456        ntfsfix device [clearbadsectors:true|false]
7457
7458       This command repairs some fundamental NTFS inconsistencies, resets the
7459       NTFS journal file, and schedules an NTFS consistency check for the
7460       first boot into Windows.
7461
7462       This is not an equivalent of Windows "chkdsk".  It does not scan the
7463       filesystem for inconsistencies.
7464
7465       The optional "clearbadsectors" flag clears the list of bad sectors.
7466       This is useful after cloning a disk with bad sectors to a new disk.
7467
7468       This command has one or more optional arguments.  See "OPTIONAL
7469       ARGUMENTS".
7470
7471       This command depends on the feature "ntfs3g".   See also "feature-
7472       available".
7473
7474   ntfsresize
7475   ntfsresize-opts
7476        ntfsresize device [size:N] [force:true|false]
7477
7478       This command resizes an NTFS filesystem, expanding or shrinking it to
7479       the size of the underlying device.
7480
7481       The optional parameters are:
7482
7483       "size"
7484           The new size (in bytes) of the filesystem.  If omitted, the
7485           filesystem is resized to fit the container (eg. partition).
7486
7487       "force"
7488           If this option is true, then force the resize of the filesystem
7489           even if the filesystem is marked as requiring a consistency check.
7490
7491           After the resize operation, the filesystem is always marked as
7492           requiring a consistency check (for safety).  You have to boot into
7493           Windows to perform this check and clear this condition.  If you
7494           don't set the "force" option then it is not possible to call
7495           "ntfsresize" multiple times on a single filesystem without booting
7496           into Windows between each resize.
7497
7498       See also ntfsresize(8).
7499
7500       This command has one or more optional arguments.  See "OPTIONAL
7501       ARGUMENTS".
7502
7503       This command depends on the feature "ntfsprogs".   See also "feature-
7504       available".
7505
7506   ntfsresize-size
7507        ntfsresize-size device size
7508
7509       This command is the same as "ntfsresize" except that it allows you to
7510       specify the new size (in bytes) explicitly.
7511
7512       This function is deprecated.  In new code, use the "ntfsresize" call
7513       instead.
7514
7515       Deprecated functions will not be removed from the API, but the fact
7516       that they are deprecated indicates that there are problems with correct
7517       use of these functions.
7518
7519       This command depends on the feature "ntfsprogs".   See also "feature-
7520       available".
7521
7522   parse-environment
7523        parse-environment
7524
7525       Parse the program’s environment and set flags in the handle
7526       accordingly.  For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
7527       flag is set in the handle.
7528
7529       Most programs do not need to call this.  It is done implicitly when you
7530       call "create".
7531
7532       See "ENVIRONMENT VARIABLES" in guestfs(3) for a list of environment
7533       variables that can affect libguestfs handles.  See also
7534       "guestfs_create_flags" in guestfs(3), and "parse-environment-list".
7535
7536   parse-environment-list
7537        parse-environment-list 'environment ...'
7538
7539       Parse the list of strings in the argument "environment" and set flags
7540       in the handle accordingly.  For example if "LIBGUESTFS_DEBUG=1" is a
7541       string in the list, then the ‘verbose’ flag is set in the handle.
7542
7543       This is the same as "parse-environment" except that it parses an
7544       explicit list of strings instead of the program's environment.
7545
7546   part-add
7547        part-add device prlogex startsect endsect
7548
7549       This command adds a partition to "device".  If there is no partition
7550       table on the device, call "part-init" first.
7551
7552       The "prlogex" parameter is the type of partition.  Normally you should
7553       pass "p" or "primary" here, but MBR partition tables also support "l"
7554       (or "logical") and "e" (or "extended") partition types.
7555
7556       "startsect" and "endsect" are the start and end of the partition in
7557       sectors.  "endsect" may be negative, which means it counts backwards
7558       from the end of the disk ("-1" is the last sector).
7559
7560       Creating a partition which covers the whole disk is not so easy.  Use
7561       "part-disk" to do that.
7562
7563   part-del
7564        part-del device partnum
7565
7566       This command deletes the partition numbered "partnum" on "device".
7567
7568       Note that in the case of MBR partitioning, deleting an extended
7569       partition also deletes any logical partitions it contains.
7570
7571   part-disk
7572        part-disk device parttype
7573
7574       This command is simply a combination of "part-init" followed by "part-
7575       add" to create a single primary partition covering the whole disk.
7576
7577       "parttype" is the partition table type, usually "mbr" or "gpt", but
7578       other possible values are described in "part-init".
7579
7580   part-expand-gpt
7581        part-expand-gpt device
7582
7583       Move backup GPT data structures to the end of the disk.  This is useful
7584       in case of in-place image expand since disk space after backup GPT
7585       header is not usable.  This is equivalent to "sgdisk -e".
7586
7587       See also sgdisk(8).
7588
7589       This command depends on the feature "gdisk".   See also "feature-
7590       available".
7591
7592   part-get-bootable
7593        part-get-bootable device partnum
7594
7595       This command returns true if the partition "partnum" on "device" has
7596       the bootable flag set.
7597
7598       See also "part-set-bootable".
7599
7600   part-get-disk-guid
7601        part-get-disk-guid device
7602
7603       Return the disk identifier (GUID) of a GPT-partitioned "device".
7604       Behaviour is undefined for other partition types.
7605
7606       This command depends on the feature "gdisk".   See also "feature-
7607       available".
7608
7609   part-get-gpt-attributes
7610        part-get-gpt-attributes device partnum
7611
7612       Return the attribute flags of numbered GPT partition "partnum".  An
7613       error is returned for MBR partitions.
7614
7615       This command depends on the feature "gdisk".   See also "feature-
7616       available".
7617
7618   part-get-gpt-guid
7619        part-get-gpt-guid device partnum
7620
7621       Return the GUID of numbered GPT partition "partnum".
7622
7623       This command depends on the feature "gdisk".   See also "feature-
7624       available".
7625
7626   part-get-gpt-type
7627        part-get-gpt-type device partnum
7628
7629       Return the type GUID of numbered GPT partition "partnum". For MBR
7630       partitions, return an appropriate GUID corresponding to the MBR type.
7631       Behaviour is undefined for other partition types.
7632
7633       This command depends on the feature "gdisk".   See also "feature-
7634       available".
7635
7636   part-get-mbr-id
7637        part-get-mbr-id device partnum
7638
7639       Returns the MBR type byte (also known as the ID byte) from the numbered
7640       partition "partnum".
7641
7642       Note that only MBR (old DOS-style) partitions have type bytes.  You
7643       will get undefined results for other partition table types (see "part-
7644       get-parttype").
7645
7646   part-get-mbr-part-type
7647        part-get-mbr-part-type device partnum
7648
7649       This returns the partition type of an MBR partition numbered "partnum"
7650       on device "device".
7651
7652       It returns "primary", "logical", or "extended".
7653
7654   part-get-name
7655        part-get-name device partnum
7656
7657       This gets the partition name on partition numbered "partnum" on device
7658       "device".  Note that partitions are numbered from 1.
7659
7660       The partition name can only be read on certain types of partition
7661       table.  This works on "gpt" but not on "mbr" partitions.
7662
7663   part-get-parttype
7664        part-get-parttype device
7665
7666       This command examines the partition table on "device" and returns the
7667       partition table type (format) being used.
7668
7669       Common return values include: "msdos" (a DOS/Windows style MBR
7670       partition table), "gpt" (a GPT/EFI-style partition table).  Other
7671       values are possible, although unusual.  See "part-init" for a full
7672       list.
7673
7674   part-init
7675        part-init device parttype
7676
7677       This creates an empty partition table on "device" of one of the
7678       partition types listed below.  Usually "parttype" should be either
7679       "msdos" or "gpt" (for large disks).
7680
7681       Initially there are no partitions.  Following this, you should call
7682       "part-add" for each partition required.
7683
7684       Possible values for "parttype" are:
7685
7686       "efi"
7687       "gpt"
7688           Intel EFI / GPT partition table.
7689
7690           This is recommended for >= 2 TB partitions that will be accessed
7691           from Linux and Intel-based Mac OS X.  It also has limited backwards
7692           compatibility with the "mbr" format.
7693
7694       "mbr"
7695       "msdos"
7696           The standard PC "Master Boot Record" (MBR) format used by MS-DOS
7697           and Windows.  This partition type will only work for device sizes
7698           up to 2 TB.  For large disks we recommend using "gpt".
7699
7700       Other partition table types that may work but are not supported
7701       include:
7702
7703       "aix"
7704           AIX disk labels.
7705
7706       "amiga"
7707       "rdb"
7708           Amiga "Rigid Disk Block" format.
7709
7710       "bsd"
7711           BSD disk labels.
7712
7713       "dasd"
7714           DASD, used on IBM mainframes.
7715
7716       "dvh"
7717           MIPS/SGI volumes.
7718
7719       "mac"
7720           Old Mac partition format.  Modern Macs use "gpt".
7721
7722       "pc98"
7723           NEC PC-98 format, common in Japan apparently.
7724
7725       "sun"
7726           Sun disk labels.
7727
7728   part-list
7729        part-list device
7730
7731       This command parses the partition table on "device" and returns the
7732       list of partitions found.
7733
7734       The fields in the returned structure are:
7735
7736       "part_num"
7737           Partition number, counting from 1.
7738
7739       "part_start"
7740           Start of the partition in bytes.  To get sectors you have to divide
7741           by the device’s sector size, see "blockdev-getss".
7742
7743       "part_end"
7744           End of the partition in bytes.
7745
7746       "part_size"
7747           Size of the partition in bytes.
7748
7749   part-resize
7750        part-resize device partnum endsect
7751
7752       This command resizes the partition numbered "partnum" on "device" by
7753       moving the end position.
7754
7755       Note that this does not modify any filesystem present in the partition.
7756       If you wish to do this, you will need to use filesystem resizing
7757       commands like "resize2fs".
7758
7759       When growing a partition you will want to grow the filesystem
7760       afterwards, but when shrinking, you need to shrink the filesystem
7761       before the partition.
7762
7763   part-set-bootable
7764        part-set-bootable device partnum true|false
7765
7766       This sets the bootable flag on partition numbered "partnum" on device
7767       "device".  Note that partitions are numbered from 1.
7768
7769       The bootable flag is used by some operating systems (notably Windows)
7770       to determine which partition to boot from.  It is by no means
7771       universally recognized.
7772
7773   part-set-disk-guid
7774        part-set-disk-guid device guid
7775
7776       Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
7777       Return an error if the partition table of "device" isn't GPT, or if
7778       "guid" is not a valid GUID.
7779
7780       This command depends on the feature "gdisk".   See also "feature-
7781       available".
7782
7783   part-set-disk-guid-random
7784        part-set-disk-guid-random device
7785
7786       Set the disk identifier (GUID) of a GPT-partitioned "device" to a
7787       randomly generated value.  Return an error if the partition table of
7788       "device" isn't GPT.
7789
7790       This command depends on the feature "gdisk".   See also "feature-
7791       available".
7792
7793   part-set-gpt-attributes
7794        part-set-gpt-attributes device partnum attributes
7795
7796       Set the attribute flags of numbered GPT partition "partnum" to
7797       "attributes". Return an error if the partition table of "device" isn't
7798       GPT.
7799
7800       See
7801       https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
7802       for a useful list of partition attributes.
7803
7804       This command depends on the feature "gdisk".   See also "feature-
7805       available".
7806
7807   part-set-gpt-guid
7808        part-set-gpt-guid device partnum guid
7809
7810       Set the GUID of numbered GPT partition "partnum" to "guid".  Return an
7811       error if the partition table of "device" isn't GPT, or if "guid" is not
7812       a valid GUID.
7813
7814       This command depends on the feature "gdisk".   See also "feature-
7815       available".
7816
7817   part-set-gpt-type
7818        part-set-gpt-type device partnum guid
7819
7820       Set the type GUID of numbered GPT partition "partnum" to "guid". Return
7821       an error if the partition table of "device" isn't GPT, or if "guid" is
7822       not a valid GUID.
7823
7824       See
7825       https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
7826       for a useful list of type GUIDs.
7827
7828       This command depends on the feature "gdisk".   See also "feature-
7829       available".
7830
7831   part-set-mbr-id
7832        part-set-mbr-id device partnum idbyte
7833
7834       Sets the MBR type byte (also known as the ID byte) of the numbered
7835       partition "partnum" to "idbyte".  Note that the type bytes quoted in
7836       most documentation are in fact hexadecimal numbers, but usually
7837       documented without any leading "0x" which might be confusing.
7838
7839       Note that only MBR (old DOS-style) partitions have type bytes.  You
7840       will get undefined results for other partition table types (see "part-
7841       get-parttype").
7842
7843   part-set-name
7844        part-set-name device partnum name
7845
7846       This sets the partition name on partition numbered "partnum" on device
7847       "device".  Note that partitions are numbered from 1.
7848
7849       The partition name can only be set on certain types of partition table.
7850       This works on "gpt" but not on "mbr" partitions.
7851
7852   part-to-dev
7853        part-to-dev partition
7854
7855       This function takes a partition name (eg. "/dev/sdb1") and removes the
7856       partition number, returning the device name (eg. "/dev/sdb").
7857
7858       The named partition must exist, for example as a string returned from
7859       "list-partitions".
7860
7861       See also "part-to-partnum", "device-index".
7862
7863   part-to-partnum
7864        part-to-partnum partition
7865
7866       This function takes a partition name (eg. "/dev/sdb1") and returns the
7867       partition number (eg. 1).
7868
7869       The named partition must exist, for example as a string returned from
7870       "list-partitions".
7871
7872       See also "part-to-dev".
7873
7874   ping-daemon
7875        ping-daemon
7876
7877       This is a test probe into the guestfs daemon running inside the
7878       libguestfs appliance.  Calling this function checks that the daemon
7879       responds to the ping message, without affecting the daemon or attached
7880       block device(s) in any other way.
7881
7882   pread
7883        pread path count offset
7884
7885       This command lets you read part of a file.  It reads "count" bytes of
7886       the file, starting at "offset", from file "path".
7887
7888       This may read fewer bytes than requested.  For further details see the
7889       pread(2) system call.
7890
7891       See also "pwrite", "pread-device".
7892
7893       Because of the message protocol, there is a transfer limit of somewhere
7894       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
7895
7896   pread-device
7897        pread-device device count offset
7898
7899       This command lets you read part of a block device.  It reads "count"
7900       bytes of "device", starting at "offset".
7901
7902       This may read fewer bytes than requested.  For further details see the
7903       pread(2) system call.
7904
7905       See also "pread".
7906
7907       Because of the message protocol, there is a transfer limit of somewhere
7908       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
7909
7910   pvchange-uuid
7911        pvchange-uuid device
7912
7913       Generate a new random UUID for the physical volume "device".
7914
7915       This command depends on the feature "lvm2".   See also "feature-
7916       available".
7917
7918   pvchange-uuid-all
7919        pvchange-uuid-all
7920
7921       Generate new random UUIDs for all physical volumes.
7922
7923       This command depends on the feature "lvm2".   See also "feature-
7924       available".
7925
7926   pvcreate
7927        pvcreate device
7928
7929       This creates an LVM physical volume on the named "device", where
7930       "device" should usually be a partition name such as /dev/sda1.
7931
7932       This command depends on the feature "lvm2".   See also "feature-
7933       available".
7934
7935   pvremove
7936        pvremove device
7937
7938       This wipes a physical volume "device" so that LVM will no longer
7939       recognise it.
7940
7941       The implementation uses the pvremove(8) command which refuses to wipe
7942       physical volumes that contain any volume groups, so you have to remove
7943       those first.
7944
7945       This command depends on the feature "lvm2".   See also "feature-
7946       available".
7947
7948   pvresize
7949        pvresize device
7950
7951       This resizes (expands or shrinks) an existing LVM physical volume to
7952       match the new size of the underlying device.
7953
7954       This command depends on the feature "lvm2".   See also "feature-
7955       available".
7956
7957   pvresize-size
7958        pvresize-size device size
7959
7960       This command is the same as "pvresize" except that it allows you to
7961       specify the new size (in bytes) explicitly.
7962
7963       This command depends on the feature "lvm2".   See also "feature-
7964       available".
7965
7966   pvs
7967        pvs
7968
7969       List all the physical volumes detected.  This is the equivalent of the
7970       pvs(8) command.
7971
7972       This returns a list of just the device names that contain PVs (eg.
7973       /dev/sda2).
7974
7975       See also "pvs-full".
7976
7977       This command depends on the feature "lvm2".   See also "feature-
7978       available".
7979
7980   pvs-full
7981        pvs-full
7982
7983       List all the physical volumes detected.  This is the equivalent of the
7984       pvs(8) command.  The "full" version includes all fields.
7985
7986       This command depends on the feature "lvm2".   See also "feature-
7987       available".
7988
7989   pvuuid
7990        pvuuid device
7991
7992       This command returns the UUID of the LVM PV "device".
7993
7994   pwrite
7995        pwrite path content offset
7996
7997       This command writes to part of a file.  It writes the data buffer
7998       "content" to the file "path" starting at offset "offset".
7999
8000       This command implements the pwrite(2) system call, and like that system
8001       call it may not write the full data requested.  The return value is the
8002       number of bytes that were actually written to the file.  This could
8003       even be 0, although short writes are unlikely for regular files in
8004       ordinary circumstances.
8005
8006       See also "pread", "pwrite-device".
8007
8008       Because of the message protocol, there is a transfer limit of somewhere
8009       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
8010
8011   pwrite-device
8012        pwrite-device device content offset
8013
8014       This command writes to part of a device.  It writes the data buffer
8015       "content" to "device" starting at offset "offset".
8016
8017       This command implements the pwrite(2) system call, and like that system
8018       call it may not write the full data requested (although short writes to
8019       disk devices and partitions are probably impossible with standard Linux
8020       kernels).
8021
8022       See also "pwrite".
8023
8024       Because of the message protocol, there is a transfer limit of somewhere
8025       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
8026
8027   read-file
8028        read-file path
8029
8030       This calls returns the contents of the file "path" as a buffer.
8031
8032       Unlike "cat", this function can correctly handle files that contain
8033       embedded ASCII NUL characters.
8034
8035   read-lines
8036        read-lines path
8037
8038       Return the contents of the file named "path".
8039
8040       The file contents are returned as a list of lines.  Trailing "LF" and
8041       "CRLF" character sequences are not returned.
8042
8043       Note that this function cannot correctly handle binary files
8044       (specifically, files containing "\0" character which is treated as end
8045       of string).  For those you need to use the "read-file" function and
8046       split the buffer into lines yourself.
8047
8048   readdir
8049        readdir dir
8050
8051       This returns the list of directory entries in directory "dir".
8052
8053       All entries in the directory are returned, including "." and "..".  The
8054       entries are not sorted, but returned in the same order as the
8055       underlying filesystem.
8056
8057       Also this call returns basic file type information about each file.
8058       The "ftyp" field will contain one of the following characters:
8059
8060       'b' Block special
8061
8062       'c' Char special
8063
8064       'd' Directory
8065
8066       'f' FIFO (named pipe)
8067
8068       'l' Symbolic link
8069
8070       'r' Regular file
8071
8072       's' Socket
8073
8074       'u' Unknown file type
8075
8076       '?' The readdir(3) call returned a "d_type" field with an unexpected
8077           value
8078
8079       This function is primarily intended for use by programs.  To get a
8080       simple list of names, use "ls".  To get a printable directory for human
8081       consumption, use "ll".
8082
8083       Because of the message protocol, there is a transfer limit of somewhere
8084       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
8085
8086   readlink
8087        readlink path
8088
8089       This command reads the target of a symbolic link.
8090
8091   readlinklist
8092        readlinklist path 'names ...'
8093
8094       This call allows you to do a "readlink" operation on multiple files,
8095       where all files are in the directory "path".  "names" is the list of
8096       files from this directory.
8097
8098       On return you get a list of strings, with a one-to-one correspondence
8099       to the "names" list.  Each string is the value of the symbolic link.
8100
8101       If the readlink(2) operation fails on any name, then the corresponding
8102       result string is the empty string "".  However the whole operation is
8103       completed even if there were readlink(2) errors, and so you can call
8104       this function with names where you don't know if they are symbolic
8105       links already (albeit slightly less efficient).
8106
8107       This call is intended for programs that want to efficiently list a
8108       directory contents without making many round-trips.
8109
8110   realpath
8111        realpath path
8112
8113       Return the canonicalized absolute pathname of "path".  The returned
8114       path has no ".", ".." or symbolic link path elements.
8115
8116   remount
8117        remount mountpoint [rw:true|false]
8118
8119       This call allows you to change the "rw" (readonly/read-write) flag on
8120       an already mounted filesystem at "mountpoint", converting a readonly
8121       filesystem to be read-write, or vice-versa.
8122
8123       Note that at the moment you must supply the "optional" "rw" parameter.
8124       In future we may allow other flags to be adjusted.
8125
8126       This command has one or more optional arguments.  See "OPTIONAL
8127       ARGUMENTS".
8128
8129   remove-drive
8130        remove-drive label
8131
8132       This function is conceptually the opposite of "add-drive-opts".  It
8133       removes the drive that was previously added with label "label".
8134
8135       Note that in order to remove drives, you have to add them with labels
8136       (see the optional "label" argument to "add-drive-opts").  If you didn't
8137       use a label, then they cannot be removed.
8138
8139       You can call this function before or after launching the handle.  If
8140       called after launch, if the backend supports it, we try to hot unplug
8141       the drive: see "HOTPLUGGING" in guestfs(3).  The disk must not be in
8142       use (eg. mounted) when you do this.  We try to detect if the disk is in
8143       use and stop you from doing this.
8144
8145   removexattr
8146        removexattr xattr path
8147
8148       This call removes the extended attribute named "xattr" of the file
8149       "path".
8150
8151       See also: "lremovexattr", attr(5).
8152
8153       This command depends on the feature "linuxxattrs".   See also "feature-
8154       available".
8155
8156   rename
8157        rename oldpath newpath
8158
8159       Rename a file to a new place on the same filesystem.  This is the same
8160       as the Linux rename(2) system call.  In most cases you are better to
8161       use "mv" instead.
8162
8163   resize2fs
8164        resize2fs device
8165
8166       This resizes an ext2, ext3 or ext4 filesystem to match the size of the
8167       underlying device.
8168
8169       See also "RESIZE2FS ERRORS" in guestfs(3).
8170
8171   resize2fs-M
8172        resize2fs-M device
8173
8174       This command is the same as "resize2fs", but the filesystem is resized
8175       to its minimum size.  This works like the -M option to the resize2fs(8)
8176       command.
8177
8178       To get the resulting size of the filesystem you should call "tune2fs-l"
8179       and read the "Block size" and "Block count" values.  These two numbers,
8180       multiplied together, give the resulting size of the minimal filesystem
8181       in bytes.
8182
8183       See also "RESIZE2FS ERRORS" in guestfs(3).
8184
8185   resize2fs-size
8186        resize2fs-size device size
8187
8188       This command is the same as "resize2fs" except that it allows you to
8189       specify the new size (in bytes) explicitly.
8190
8191       See also "RESIZE2FS ERRORS" in guestfs(3).
8192
8193   rm
8194        rm path
8195
8196       Remove the single file "path".
8197
8198   rm-f
8199        rm-f path
8200
8201       Remove the file "path".
8202
8203       If the file doesn't exist, that error is ignored.  (Other errors, eg.
8204       I/O errors or bad paths, are not ignored)
8205
8206       This call cannot remove directories.  Use "rmdir" to remove an empty
8207       directory, or "rm-rf" to remove directories recursively.
8208
8209   rm-rf
8210        rm-rf path
8211
8212       Remove the file or directory "path", recursively removing the contents
8213       if its a directory.  This is like the "rm -rf" shell command.
8214
8215   rmdir
8216        rmdir path
8217
8218       Remove the single directory "path".
8219
8220   rmmountpoint
8221        rmmountpoint exemptpath
8222
8223       This call removes a mountpoint that was previously created with
8224       "mkmountpoint".  See "mkmountpoint" for full details.
8225
8226   rsync
8227        rsync src dest [archive:true|false] [deletedest:true|false]
8228
8229       This call may be used to copy or synchronize two directories under the
8230       same libguestfs handle.  This uses the rsync(1) program which uses a
8231       fast algorithm that avoids copying files unnecessarily.
8232
8233       "src" and "dest" are the source and destination directories.  Files are
8234       copied from "src" to "dest".
8235
8236       The optional arguments are:
8237
8238       "archive"
8239           Turns on archive mode.  This is the same as passing the --archive
8240           flag to "rsync".
8241
8242       "deletedest"
8243           Delete files at the destination that do not exist at the source.
8244
8245       This command has one or more optional arguments.  See "OPTIONAL
8246       ARGUMENTS".
8247
8248       This command depends on the feature "rsync".   See also "feature-
8249       available".
8250
8251   rsync-in
8252        rsync-in remote dest [archive:true|false] [deletedest:true|false]
8253
8254       This call may be used to copy or synchronize the filesystem on the host
8255       or on a remote computer with the filesystem within libguestfs.  This
8256       uses the rsync(1) program which uses a fast algorithm that avoids
8257       copying files unnecessarily.
8258
8259       This call only works if the network is enabled.  See "set-network" or
8260       the --network option to various tools like guestfish(1).
8261
8262       Files are copied from the remote server and directory specified by
8263       "remote" to the destination directory "dest".
8264
8265       The format of the remote server string is defined by rsync(1).  Note
8266       that there is no way to supply a password or passphrase so the target
8267       must be set up not to require one.
8268
8269       The optional arguments are the same as those of "rsync".
8270
8271       This command has one or more optional arguments.  See "OPTIONAL
8272       ARGUMENTS".
8273
8274       This command depends on the feature "rsync".   See also "feature-
8275       available".
8276
8277   rsync-out
8278        rsync-out src remote [archive:true|false] [deletedest:true|false]
8279
8280       This call may be used to copy or synchronize the filesystem within
8281       libguestfs with a filesystem on the host or on a remote computer.  This
8282       uses the rsync(1) program which uses a fast algorithm that avoids
8283       copying files unnecessarily.
8284
8285       This call only works if the network is enabled.  See "set-network" or
8286       the --network option to various tools like guestfish(1).
8287
8288       Files are copied from the source directory "src" to the remote server
8289       and directory specified by "remote".
8290
8291       The format of the remote server string is defined by rsync(1).  Note
8292       that there is no way to supply a password or passphrase so the target
8293       must be set up not to require one.
8294
8295       The optional arguments are the same as those of "rsync".
8296
8297       Globbing does not happen on the "src" parameter.  In programs which use
8298       the API directly you have to expand wildcards yourself (see "glob-
8299       expand").  In guestfish you can use the "glob" command (see "glob"),
8300       for example:
8301
8302        ><fs> glob rsync-out /* rsync://remote/
8303
8304       This command has one or more optional arguments.  See "OPTIONAL
8305       ARGUMENTS".
8306
8307       This command depends on the feature "rsync".   See also "feature-
8308       available".
8309
8310   scrub-device
8311        scrub-device device
8312
8313       This command writes patterns over "device" to make data retrieval more
8314       difficult.
8315
8316       It is an interface to the scrub(1) program.  See that manual page for
8317       more details.
8318
8319       This command depends on the feature "scrub".   See also "feature-
8320       available".
8321
8322   scrub-file
8323        scrub-file file
8324
8325       This command writes patterns over a file to make data retrieval more
8326       difficult.
8327
8328       The file is removed after scrubbing.
8329
8330       It is an interface to the scrub(1) program.  See that manual page for
8331       more details.
8332
8333       This command depends on the feature "scrub".   See also "feature-
8334       available".
8335
8336   scrub-freespace
8337        scrub-freespace dir
8338
8339       This command creates the directory "dir" and then fills it with files
8340       until the filesystem is full, and scrubs the files as for "scrub-file",
8341       and deletes them.  The intention is to scrub any free space on the
8342       partition containing "dir".
8343
8344       It is an interface to the scrub(1) program.  See that manual page for
8345       more details.
8346
8347       This command depends on the feature "scrub".   See also "feature-
8348       available".
8349
8350   selinux-relabel
8351        selinux-relabel specfile path [force:true|false]
8352
8353       SELinux relabel parts of the filesystem.
8354
8355       The "specfile" parameter controls the policy spec file used.  You have
8356       to parse "/etc/selinux/config" to find the correct SELinux policy and
8357       then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
8358       "/contexts/files/file_contexts".
8359
8360       The required "path" parameter is the top level directory where
8361       relabelling starts.  Normally you should pass "path" as "/" to relabel
8362       the whole guest filesystem.
8363
8364       The optional "force" boolean controls whether the context is reset for
8365       customizable files, and also whether the user, role and range parts of
8366       the file context is changed.
8367
8368       This command has one or more optional arguments.  See "OPTIONAL
8369       ARGUMENTS".
8370
8371       This command depends on the feature "selinuxrelabel".   See also
8372       "feature-available".
8373
8374   set-append
8375   append
8376        set-append append
8377
8378       This function is used to add additional options to the libguestfs
8379       appliance kernel command line.
8380
8381       The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
8382       environment variable.
8383
8384       Setting "append" to "NULL" means no additional options are passed
8385       (libguestfs always adds a few of its own).
8386
8387   set-attach-method
8388   attach-method
8389        set-attach-method backend
8390
8391       Set the method that libguestfs uses to connect to the backend guestfsd
8392       daemon.
8393
8394       See "BACKEND" in guestfs(3).
8395
8396       This function is deprecated.  In new code, use the "set-backend" call
8397       instead.
8398
8399       Deprecated functions will not be removed from the API, but the fact
8400       that they are deprecated indicates that there are problems with correct
8401       use of these functions.
8402
8403   set-autosync
8404   autosync
8405        set-autosync true|false
8406
8407       If "autosync" is true, this enables autosync.  Libguestfs will make a
8408       best effort attempt to make filesystems consistent and synchronized
8409       when the handle is closed (also if the program exits without closing
8410       handles).
8411
8412       This is enabled by default (since libguestfs 1.5.24, previously it was
8413       disabled by default).
8414
8415   set-backend
8416   backend
8417        set-backend backend
8418
8419       Set the method that libguestfs uses to connect to the backend guestfsd
8420       daemon.
8421
8422       This handle property was previously called the "attach method".
8423
8424       See "BACKEND" in guestfs(3).
8425
8426   set-backend-setting
8427        set-backend-setting name val
8428
8429       Append "name=value" to the backend settings string list.  However if a
8430       string already exists matching "name" or beginning with "name=", then
8431       that setting is replaced.
8432
8433       See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8434
8435   set-backend-settings
8436        set-backend-settings 'settings ...'
8437
8438       Set a list of zero or more settings which are passed through to the
8439       current backend.  Each setting is a string which is interpreted in a
8440       backend-specific way, or ignored if not understood by the backend.
8441
8442       The default value is an empty list, unless the environment variable
8443       "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
8444       This environment variable contains a colon-separated list of settings.
8445
8446       This call replaces all backend settings.  If you want to replace a
8447       single backend setting, see "set-backend-setting".  If you want to
8448       clear a single backend setting, see "clear-backend-setting".
8449
8450       See "BACKEND" in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
8451
8452   set-cachedir
8453   cachedir
8454        set-cachedir cachedir
8455
8456       Set the directory used by the handle to store the appliance cache, when
8457       using a supermin appliance.  The appliance is cached and shared between
8458       all handles which have the same effective user ID.
8459
8460       The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
8461       the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
8462       default.  Else if "TMPDIR" is set, then that is the default.  Else
8463       /var/tmp is the default.
8464
8465   set-direct
8466   direct
8467        set-direct true|false
8468
8469       If the direct appliance mode flag is enabled, then stdin and stdout are
8470       passed directly through to the appliance once it is launched.
8471
8472       One consequence of this is that log messages aren't caught by the
8473       library and handled by "set-log-message-callback", but go straight to
8474       stdout.
8475
8476       You probably don't want to use this unless you know what you are doing.
8477
8478       The default is disabled.
8479
8480       This function is deprecated.  In new code, use the "internal-get-
8481       console-socket" call instead.
8482
8483       Deprecated functions will not be removed from the API, but the fact
8484       that they are deprecated indicates that there are problems with correct
8485       use of these functions.
8486
8487   set-e2attrs
8488        set-e2attrs file attrs [clear:true|false]
8489
8490       This sets or clears the file attributes "attrs" associated with the
8491       inode file.
8492
8493       "attrs" is a string of characters representing file attributes.  See
8494       "get-e2attrs" for a list of possible attributes.  Not all attributes
8495       can be changed.
8496
8497       If optional boolean "clear" is not present or false, then the "attrs"
8498       listed are set in the inode.
8499
8500       If "clear" is true, then the "attrs" listed are cleared in the inode.
8501
8502       In both cases, other attributes not present in the "attrs" string are
8503       left unchanged.
8504
8505       These attributes are only present when the file is located on an
8506       ext2/3/4 filesystem.  Using this call on other filesystem types will
8507       result in an error.
8508
8509       This command has one or more optional arguments.  See "OPTIONAL
8510       ARGUMENTS".
8511
8512   set-e2generation
8513        set-e2generation file generation
8514
8515       This sets the ext2 file generation of a file.
8516
8517       See "get-e2generation".
8518
8519   set-e2label
8520        set-e2label device label
8521
8522       This sets the ext2/3/4 filesystem label of the filesystem on "device"
8523       to "label".  Filesystem labels are limited to 16 characters.
8524
8525       You can use either "tune2fs-l" or "get-e2label" to return the existing
8526       label on a filesystem.
8527
8528       This function is deprecated.  In new code, use the "set-label" call
8529       instead.
8530
8531       Deprecated functions will not be removed from the API, but the fact
8532       that they are deprecated indicates that there are problems with correct
8533       use of these functions.
8534
8535   set-e2uuid
8536        set-e2uuid device uuid
8537
8538       This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
8539       "uuid".  The format of the UUID and alternatives such as "clear",
8540       "random" and "time" are described in the tune2fs(8) manpage.
8541
8542       You can use "vfs-uuid" to return the existing UUID of a filesystem.
8543
8544       This function is deprecated.  In new code, use the "set-uuid" call
8545       instead.
8546
8547       Deprecated functions will not be removed from the API, but the fact
8548       that they are deprecated indicates that there are problems with correct
8549       use of these functions.
8550
8551   set-hv
8552   hv
8553        set-hv hv
8554
8555       Set the hypervisor binary that we will use.  The hypervisor depends on
8556       the backend, but is usually the location of the qemu/KVM hypervisor.
8557       For the uml backend, it is the location of the "linux" or "vmlinux"
8558       binary.
8559
8560       The default is chosen when the library was compiled by the configure
8561       script.
8562
8563       You can also override this by setting the "LIBGUESTFS_HV" environment
8564       variable.
8565
8566       Note that you should call this function as early as possible after
8567       creating the handle.  This is because some pre-launch operations depend
8568       on testing qemu features (by running "qemu -help").  If the qemu binary
8569       changes, we don't retest features, and so you might see inconsistent
8570       results.  Using the environment variable "LIBGUESTFS_HV" is safest of
8571       all since that picks the qemu binary at the same time as the handle is
8572       created.
8573
8574   set-identifier
8575   identifier
8576        set-identifier identifier
8577
8578       This is an informative string which the caller may optionally set in
8579       the handle.  It is printed in various places, allowing the current
8580       handle to be identified in debugging output.
8581
8582       One important place is when tracing is enabled.  If the identifier
8583       string is not an empty string, then trace messages change from this:
8584
8585        libguestfs: trace: get_tmpdir
8586        libguestfs: trace: get_tmpdir = "/tmp"
8587
8588       to this:
8589
8590        libguestfs: trace: ID: get_tmpdir
8591        libguestfs: trace: ID: get_tmpdir = "/tmp"
8592
8593       where "ID" is the identifier string set by this call.
8594
8595       The identifier must only contain alphanumeric ASCII characters,
8596       underscore and minus sign.  The default is the empty string.
8597
8598       See also "set-program", "set-trace", "get-identifier".
8599
8600   set-label
8601        set-label mountable label
8602
8603       Set the filesystem label on "mountable" to "label".
8604
8605       Only some filesystem types support labels, and libguestfs supports
8606       setting labels on only a subset of these.
8607
8608       ext2, ext3, ext4
8609           Labels are limited to 16 bytes.
8610
8611       NTFS
8612           Labels are limited to 128 unicode characters.
8613
8614       XFS The label is limited to 12 bytes.  The filesystem must not be
8615           mounted when trying to set the label.
8616
8617       btrfs
8618           The label is limited to 255 bytes and some characters are not
8619           allowed.  Setting the label on a btrfs subvolume will set the label
8620           on its parent filesystem.  The filesystem must not be mounted when
8621           trying to set the label.
8622
8623       fat The label is limited to 11 bytes.
8624
8625       swap
8626           The label is limited to 16 bytes.
8627
8628       If there is no support for changing the label for the type of the
8629       specified filesystem, set_label will fail and set errno as ENOTSUP.
8630
8631       To read the label on a filesystem, call "vfs-label".
8632
8633   set-libvirt-requested-credential
8634        set-libvirt-requested-credential index cred
8635
8636       After requesting the "index"'th credential from the user, call this
8637       function to pass the answer back to libvirt.
8638
8639       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8640       example code.
8641
8642   set-libvirt-supported-credentials
8643        set-libvirt-supported-credentials 'creds ...'
8644
8645       Call this function before setting an event handler for
8646       "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
8647       that the program knows how to process.
8648
8649       The "creds" list must be a non-empty list of strings.  Possible strings
8650       are:
8651
8652       "username"
8653       "authname"
8654       "language"
8655       "cnonce"
8656       "passphrase"
8657       "echoprompt"
8658       "noechoprompt"
8659       "realm"
8660       "external"
8661
8662       See libvirt documentation for the meaning of these credential types.
8663
8664       See "LIBVIRT AUTHENTICATION" in guestfs(3) for documentation and
8665       example code.
8666
8667   set-memsize
8668   memsize
8669        set-memsize memsize
8670
8671       This sets the memory size in megabytes allocated to the hypervisor.
8672       This only has any effect if called before "launch".
8673
8674       You can also change this by setting the environment variable
8675       "LIBGUESTFS_MEMSIZE" before the handle is created.
8676
8677       For more information on the architecture of libguestfs, see guestfs(3).
8678
8679   set-network
8680   network
8681        set-network true|false
8682
8683       If "network" is true, then the network is enabled in the libguestfs
8684       appliance.  The default is false.
8685
8686       This affects whether commands are able to access the network (see
8687       "RUNNING COMMANDS" in guestfs(3)).
8688
8689       You must call this before calling "launch", otherwise it has no effect.
8690
8691   set-path
8692   path
8693        set-path searchpath
8694
8695       Set the path that libguestfs searches for kernel and initrd.img.
8696
8697       The default is "$libdir/guestfs" unless overridden by setting
8698       "LIBGUESTFS_PATH" environment variable.
8699
8700       Setting "path" to "NULL" restores the default path.
8701
8702   set-pgroup
8703   pgroup
8704        set-pgroup true|false
8705
8706       If "pgroup" is true, child processes are placed into their own process
8707       group.
8708
8709       The practical upshot of this is that signals like "SIGINT" (from users
8710       pressing "^C") won't be received by the child process.
8711
8712       The default for this flag is false, because usually you want "^C" to
8713       kill the subprocess.  Guestfish sets this flag to true when used
8714       interactively, so that "^C" can cancel long-running commands gracefully
8715       (see "user-cancel").
8716
8717   set-program
8718   program
8719        set-program program
8720
8721       Set the program name.  This is an informative string which the main
8722       program may optionally set in the handle.
8723
8724       When the handle is created, the program name in the handle is set to
8725       the basename from "argv[0]".  The program name can never be "NULL".
8726
8727   set-qemu
8728   qemu
8729        set-qemu hv
8730
8731       Set the hypervisor binary (usually qemu) that we will use.
8732
8733       The default is chosen when the library was compiled by the configure
8734       script.
8735
8736       You can also override this by setting the "LIBGUESTFS_HV" environment
8737       variable.
8738
8739       Setting "hv" to "NULL" restores the default qemu binary.
8740
8741       Note that you should call this function as early as possible after
8742       creating the handle.  This is because some pre-launch operations depend
8743       on testing qemu features (by running "qemu -help").  If the qemu binary
8744       changes, we don't retest features, and so you might see inconsistent
8745       results.  Using the environment variable "LIBGUESTFS_HV" is safest of
8746       all since that picks the qemu binary at the same time as the handle is
8747       created.
8748
8749       This function is deprecated.  In new code, use the "set-hv" call
8750       instead.
8751
8752       Deprecated functions will not be removed from the API, but the fact
8753       that they are deprecated indicates that there are problems with correct
8754       use of these functions.
8755
8756   set-recovery-proc
8757   recovery-proc
8758        set-recovery-proc true|false
8759
8760       If this is called with the parameter "false" then "launch" does not
8761       create a recovery process.  The purpose of the recovery process is to
8762       stop runaway hypervisor processes in the case where the main program
8763       aborts abruptly.
8764
8765       This only has any effect if called before "launch", and the default is
8766       true.
8767
8768       About the only time when you would want to disable this is if the main
8769       process will fork itself into the background ("daemonize" itself).  In
8770       this case the recovery process thinks that the main program has
8771       disappeared and so kills the hypervisor, which is not very helpful.
8772
8773   set-selinux
8774   selinux
8775        set-selinux true|false
8776
8777       This sets the selinux flag that is passed to the appliance at boot
8778       time.  The default is "selinux=0" (disabled).
8779
8780       Note that if SELinux is enabled, it is always in Permissive mode
8781       ("enforcing=0").
8782
8783       For more information on the architecture of libguestfs, see guestfs(3).
8784
8785       This function is deprecated.  In new code, use the "selinux-relabel"
8786       call instead.
8787
8788       Deprecated functions will not be removed from the API, but the fact
8789       that they are deprecated indicates that there are problems with correct
8790       use of these functions.
8791
8792   set-smp
8793   smp
8794        set-smp smp
8795
8796       Change the number of virtual CPUs assigned to the appliance.  The
8797       default is 1.  Increasing this may improve performance, though often it
8798       has no effect.
8799
8800       This function must be called before "launch".
8801
8802   set-tmpdir
8803   tmpdir
8804        set-tmpdir tmpdir
8805
8806       Set the directory used by the handle to store temporary files.
8807
8808       The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
8809       default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
8810       Else if "TMPDIR" is set, then that is the default.  Else /tmp is the
8811       default.
8812
8813   set-trace
8814   trace
8815        set-trace true|false
8816
8817       If the command trace flag is set to 1, then libguestfs calls,
8818       parameters and return values are traced.
8819
8820       If you want to trace C API calls into libguestfs (and other libraries)
8821       then possibly a better way is to use the external ltrace(1) command.
8822
8823       Command traces are disabled unless the environment variable
8824       "LIBGUESTFS_TRACE" is defined and set to 1.
8825
8826       Trace messages are normally sent to "stderr", unless you register a
8827       callback to send them somewhere else (see "set-event-callback").
8828
8829   set-uuid
8830        set-uuid device uuid
8831
8832       Set the filesystem UUID on "device" to "uuid".  If this fails and the
8833       errno is ENOTSUP, means that there is no support for changing the UUID
8834       for the type of the specified filesystem.
8835
8836       Only some filesystem types support setting UUIDs.
8837
8838       To read the UUID on a filesystem, call "vfs-uuid".
8839
8840   set-uuid-random
8841        set-uuid-random device
8842
8843       Set the filesystem UUID on "device" to a random UUID.  If this fails
8844       and the errno is ENOTSUP, means that there is no support for changing
8845       the UUID for the type of the specified filesystem.
8846
8847       Only some filesystem types support setting UUIDs.
8848
8849       To read the UUID on a filesystem, call "vfs-uuid".
8850
8851   set-verbose
8852   verbose
8853        set-verbose true|false
8854
8855       If "verbose" is true, this turns on verbose messages.
8856
8857       Verbose messages are disabled unless the environment variable
8858       "LIBGUESTFS_DEBUG" is defined and set to 1.
8859
8860       Verbose messages are normally sent to "stderr", unless you register a
8861       callback to send them somewhere else (see "set-event-callback").
8862
8863   setcon
8864        setcon context
8865
8866       This sets the SELinux security context of the daemon to the string
8867       "context".
8868
8869       See the documentation about SELINUX in guestfs(3).
8870
8871       This function is deprecated.  In new code, use the "selinux-relabel"
8872       call instead.
8873
8874       Deprecated functions will not be removed from the API, but the fact
8875       that they are deprecated indicates that there are problems with correct
8876       use of these functions.
8877
8878       This command depends on the feature "selinux".   See also "feature-
8879       available".
8880
8881   setxattr
8882        setxattr xattr val vallen path
8883
8884       This call sets the extended attribute named "xattr" of the file "path"
8885       to the value "val" (of length "vallen").  The value is arbitrary 8 bit
8886       data.
8887
8888       See also: "lsetxattr", attr(5).
8889
8890       This command depends on the feature "linuxxattrs".   See also "feature-
8891       available".
8892
8893   sfdisk
8894        sfdisk device cyls heads sectors 'lines ...'
8895
8896       This is a direct interface to the sfdisk(8) program for creating
8897       partitions on block devices.
8898
8899       "device" should be a block device, for example /dev/sda.
8900
8901       "cyls", "heads" and "sectors" are the number of cylinders, heads and
8902       sectors on the device, which are passed directly to sfdisk(8) as the
8903       -C, -H and -S parameters.  If you pass 0 for any of these, then the
8904       corresponding parameter is omitted.  Usually for ‘large’ disks, you can
8905       just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
8906       (or rather, the kernel) cannot work out the right geometry and you will
8907       need to tell it.
8908
8909       "lines" is a list of lines that we feed to sfdisk(8).  For more
8910       information refer to the sfdisk(8) manpage.
8911
8912       To create a single partition occupying the whole disk, you would pass
8913       "lines" as a single element list, when the single element being the
8914       string "," (comma).
8915
8916       See also: "sfdisk-l", "sfdisk-N", "part-init"
8917
8918       This function is deprecated.  In new code, use the "part-add" call
8919       instead.
8920
8921       Deprecated functions will not be removed from the API, but the fact
8922       that they are deprecated indicates that there are problems with correct
8923       use of these functions.
8924
8925   sfdiskM
8926        sfdiskM device 'lines ...'
8927
8928       This is a simplified interface to the "sfdisk" command, where partition
8929       sizes are specified in megabytes only (rounded to the nearest cylinder)
8930       and you don't need to specify the cyls, heads and sectors parameters
8931       which were rarely if ever used anyway.
8932
8933       See also: "sfdisk", the sfdisk(8) manpage and "part-disk"
8934
8935       This function is deprecated.  In new code, use the "part-add" call
8936       instead.
8937
8938       Deprecated functions will not be removed from the API, but the fact
8939       that they are deprecated indicates that there are problems with correct
8940       use of these functions.
8941
8942   sfdisk-N
8943        sfdisk-N device partnum cyls heads sectors line
8944
8945       This runs sfdisk(8) option to modify just the single partition "n"
8946       (note: "n" counts from 1).
8947
8948       For other parameters, see "sfdisk".  You should usually pass 0 for the
8949       cyls/heads/sectors parameters.
8950
8951       See also: "part-add"
8952
8953       This function is deprecated.  In new code, use the "part-add" call
8954       instead.
8955
8956       Deprecated functions will not be removed from the API, but the fact
8957       that they are deprecated indicates that there are problems with correct
8958       use of these functions.
8959
8960   sfdisk-disk-geometry
8961        sfdisk-disk-geometry device
8962
8963       This displays the disk geometry of "device" read from the partition
8964       table.  Especially in the case where the underlying block device has
8965       been resized, this can be different from the kernel’s idea of the
8966       geometry (see "sfdisk-kernel-geometry").
8967
8968       The result is in human-readable format, and not designed to be parsed.
8969
8970   sfdisk-kernel-geometry
8971        sfdisk-kernel-geometry device
8972
8973       This displays the kernel’s idea of the geometry of "device".
8974
8975       The result is in human-readable format, and not designed to be parsed.
8976
8977   sfdisk-l
8978        sfdisk-l device
8979
8980       This displays the partition table on "device", in the human-readable
8981       output of the sfdisk(8) command.  It is not intended to be parsed.
8982
8983       See also: "part-list"
8984
8985       This function is deprecated.  In new code, use the "part-list" call
8986       instead.
8987
8988       Deprecated functions will not be removed from the API, but the fact
8989       that they are deprecated indicates that there are problems with correct
8990       use of these functions.
8991
8992   sh
8993        sh command
8994
8995       This call runs a command from the guest filesystem via the guest’s
8996       /bin/sh.
8997
8998       This is like "command", but passes the command to:
8999
9000        /bin/sh -c "command"
9001
9002       Depending on the guest’s shell, this usually results in wildcards being
9003       expanded, shell expressions being interpolated and so on.
9004
9005       All the provisos about "command" apply to this call.
9006
9007   sh-lines
9008        sh-lines command
9009
9010       This is the same as "sh", but splits the result into a list of lines.
9011
9012       See also: "command-lines"
9013
9014   shutdown
9015        shutdown
9016
9017       This is the opposite of "launch".  It performs an orderly shutdown of
9018       the backend process(es).  If the autosync flag is set (which is the
9019       default) then the disk image is synchronized.
9020
9021       If the subprocess exits with an error then this function will return an
9022       error, which should not be ignored (it may indicate that the disk image
9023       could not be written out properly).
9024
9025       It is safe to call this multiple times.  Extra calls are ignored.
9026
9027       This call does not close or free up the handle.  You still need to call
9028       "close" afterwards.
9029
9030       "close" will call this if you don't do it explicitly, but note that any
9031       errors are ignored in that case.
9032
9033   sleep
9034        sleep secs
9035
9036       Sleep for "secs" seconds.
9037
9038   stat
9039        stat path
9040
9041       Returns file information for the given "path".
9042
9043       This is the same as the stat(2) system call.
9044
9045       This function is deprecated.  In new code, use the "statns" call
9046       instead.
9047
9048       Deprecated functions will not be removed from the API, but the fact
9049       that they are deprecated indicates that there are problems with correct
9050       use of these functions.
9051
9052   statns
9053        statns path
9054
9055       Returns file information for the given "path".
9056
9057       This is the same as the stat(2) system call.
9058
9059   statvfs
9060        statvfs path
9061
9062       Returns file system statistics for any mounted file system.  "path"
9063       should be a file or directory in the mounted file system (typically it
9064       is the mount point itself, but it doesn't need to be).
9065
9066       This is the same as the statvfs(2) system call.
9067
9068   strings
9069        strings path
9070
9071       This runs the strings(1) command on a file and returns the list of
9072       printable strings found.
9073
9074       The "strings" command has, in the past, had problems with parsing
9075       untrusted files.  These are mitigated in the current version of
9076       libguestfs, but see "CVE-2014-8484" in guestfs(3).
9077
9078       Because of the message protocol, there is a transfer limit of somewhere
9079       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
9080
9081   strings-e
9082        strings-e encoding path
9083
9084       This is like the "strings" command, but allows you to specify the
9085       encoding of strings that are looked for in the source file "path".
9086
9087       Allowed encodings are:
9088
9089       s   Single 7-bit-byte characters like ASCII and the ASCII-compatible
9090           parts of ISO-8859-X (this is what "strings" uses).
9091
9092       S   Single 8-bit-byte characters.
9093
9094       b   16-bit big endian strings such as those encoded in UTF-16BE or
9095           UCS-2BE.
9096
9097       l (lower case letter L)
9098           16-bit little endian such as UTF-16LE and UCS-2LE.  This is useful
9099           for examining binaries in Windows guests.
9100
9101       B   32-bit big endian such as UCS-4BE.
9102
9103       L   32-bit little endian such as UCS-4LE.
9104
9105       The returned strings are transcoded to UTF-8.
9106
9107       The "strings" command has, in the past, had problems with parsing
9108       untrusted files.  These are mitigated in the current version of
9109       libguestfs, but see "CVE-2014-8484" in guestfs(3).
9110
9111       Because of the message protocol, there is a transfer limit of somewhere
9112       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
9113
9114   swapoff-device
9115        swapoff-device device
9116
9117       This command disables the libguestfs appliance swap device or partition
9118       named "device".  See "swapon-device".
9119
9120   swapoff-file
9121        swapoff-file file
9122
9123       This command disables the libguestfs appliance swap on file.
9124
9125   swapoff-label
9126        swapoff-label label
9127
9128       This command disables the libguestfs appliance swap on labeled swap
9129       partition.
9130
9131   swapoff-uuid
9132        swapoff-uuid uuid
9133
9134       This command disables the libguestfs appliance swap partition with the
9135       given UUID.
9136
9137       This command depends on the feature "linuxfsuuid".   See also "feature-
9138       available".
9139
9140   swapon-device
9141        swapon-device device
9142
9143       This command enables the libguestfs appliance to use the swap device or
9144       partition named "device".  The increased memory is made available for
9145       all commands, for example those run using "command" or "sh".
9146
9147       Note that you should not swap to existing guest swap partitions unless
9148       you know what you are doing.  They may contain hibernation information,
9149       or other information that the guest doesn't want you to trash.  You
9150       also risk leaking information about the host to the guest this way.
9151       Instead, attach a new host device to the guest and swap on that.
9152
9153   swapon-file
9154        swapon-file file
9155
9156       This command enables swap to a file.  See "swapon-device" for other
9157       notes.
9158
9159   swapon-label
9160        swapon-label label
9161
9162       This command enables swap to a labeled swap partition.  See "swapon-
9163       device" for other notes.
9164
9165   swapon-uuid
9166        swapon-uuid uuid
9167
9168       This command enables swap to a swap partition with the given UUID.  See
9169       "swapon-device" for other notes.
9170
9171       This command depends on the feature "linuxfsuuid".   See also "feature-
9172       available".
9173
9174   sync
9175        sync
9176
9177       This syncs the disk, so that any writes are flushed through to the
9178       underlying disk image.
9179
9180       You should always call this if you have modified a disk image, before
9181       closing the handle.
9182
9183   syslinux
9184        syslinux device [directory:..]
9185
9186       Install the SYSLINUX bootloader on "device".
9187
9188       The device parameter must be either a whole disk formatted as a FAT
9189       filesystem, or a partition formatted as a FAT filesystem.  In the
9190       latter case, the partition should be marked as "active" ("part-set-
9191       bootable") and a Master Boot Record must be installed (eg. using
9192       "pwrite-device") on the first sector of the whole disk.  The SYSLINUX
9193       package comes with some suitable Master Boot Records.  See the
9194       syslinux(1) man page for further information.
9195
9196       The optional arguments are:
9197
9198       directory
9199           Install SYSLINUX in the named subdirectory, instead of in the root
9200           directory of the FAT filesystem.
9201
9202       Additional configuration can be supplied to SYSLINUX by placing a file
9203       called syslinux.cfg on the FAT filesystem, either in the root
9204       directory, or under directory if that optional argument is being used.
9205       For further information about the contents of this file, see
9206       syslinux(1).
9207
9208       See also "extlinux".
9209
9210       This command has one or more optional arguments.  See "OPTIONAL
9211       ARGUMENTS".
9212
9213       This command depends on the feature "syslinux".   See also "feature-
9214       available".
9215
9216   tail
9217        tail path
9218
9219       This command returns up to the last 10 lines of a file as a list of
9220       strings.
9221
9222       Because of the message protocol, there is a transfer limit of somewhere
9223       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
9224
9225   tail-n
9226        tail-n nrlines path
9227
9228       If the parameter "nrlines" is a positive number, this returns the last
9229       "nrlines" lines of the file "path".
9230
9231       If the parameter "nrlines" is a negative number, this returns lines
9232       from the file "path", starting with the "-nrlines"'th line.
9233
9234       If the parameter "nrlines" is zero, this returns an empty list.
9235
9236       Because of the message protocol, there is a transfer limit of somewhere
9237       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
9238
9239   tar-in
9240   tar-in-opts
9241        tar-in (tarfile|-) directory [compress:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9242
9243       This command uploads and unpacks local file "tarfile" into directory.
9244
9245       The optional "compress" flag controls compression.  If not given, then
9246       the input should be an uncompressed tar file.  Otherwise one of the
9247       following strings may be given to select the compression type of the
9248       input file: "compress", "gzip", "bzip2", "xz", "lzop".  (Note that not
9249       all builds of libguestfs will support all of these compression types).
9250
9251       The other optional arguments are:
9252
9253       "xattrs"
9254           If set to true, extended attributes are restored from the tar file.
9255
9256       "selinux"
9257           If set to true, SELinux contexts are restored from the tar file.
9258
9259       "acls"
9260           If set to true, POSIX ACLs are restored from the tar file.
9261
9262       Use "-" instead of a filename to read/write from stdin/stdout.
9263
9264       This command has one or more optional arguments.  See "OPTIONAL
9265       ARGUMENTS".
9266
9267   tar-out
9268   tar-out-opts
9269        tar-out directory (tarfile|-) [compress:..] [numericowner:true|false] [excludes:..] [xattrs:true|false] [selinux:true|false] [acls:true|false]
9270
9271       This command packs the contents of directory and downloads it to local
9272       file "tarfile".
9273
9274       The optional "compress" flag controls compression.  If not given, then
9275       the output will be an uncompressed tar file.  Otherwise one of the
9276       following strings may be given to select the compression type of the
9277       output file: "compress", "gzip", "bzip2", "xz", "lzop".  (Note that not
9278       all builds of libguestfs will support all of these compression types).
9279
9280       The other optional arguments are:
9281
9282       "excludes"
9283           A list of wildcards.  Files are excluded if they match any of the
9284           wildcards.
9285
9286       "numericowner"
9287           If set to true, the output tar file will contain UID/GID numbers
9288           instead of user/group names.
9289
9290       "xattrs"
9291           If set to true, extended attributes are saved in the output tar.
9292
9293       "selinux"
9294           If set to true, SELinux contexts are saved in the output tar.
9295
9296       "acls"
9297           If set to true, POSIX ACLs are saved in the output tar.
9298
9299       Use "-" instead of a filename to read/write from stdin/stdout.
9300
9301       This command has one or more optional arguments.  See "OPTIONAL
9302       ARGUMENTS".
9303
9304   tgz-in
9305        tgz-in (tarball|-) directory
9306
9307       This command uploads and unpacks local file "tarball" (a gzip
9308       compressed tar file) into directory.
9309
9310       Use "-" instead of a filename to read/write from stdin/stdout.
9311
9312       This function is deprecated.  In new code, use the "tar-in" call
9313       instead.
9314
9315       Deprecated functions will not be removed from the API, but the fact
9316       that they are deprecated indicates that there are problems with correct
9317       use of these functions.
9318
9319   tgz-out
9320        tgz-out directory (tarball|-)
9321
9322       This command packs the contents of directory and downloads it to local
9323       file "tarball".
9324
9325       Use "-" instead of a filename to read/write from stdin/stdout.
9326
9327       This function is deprecated.  In new code, use the "tar-out" call
9328       instead.
9329
9330       Deprecated functions will not be removed from the API, but the fact
9331       that they are deprecated indicates that there are problems with correct
9332       use of these functions.
9333
9334   touch
9335        touch path
9336
9337       Touch acts like the touch(1) command.  It can be used to update the
9338       timestamps on a file, or, if the file does not exist, to create a new
9339       zero-length file.
9340
9341       This command only works on regular files, and will fail on other file
9342       types such as directories, symbolic links, block special etc.
9343
9344   truncate
9345        truncate path
9346
9347       This command truncates "path" to a zero-length file.  The file must
9348       exist already.
9349
9350   truncate-size
9351        truncate-size path size
9352
9353       This command truncates "path" to size "size" bytes.  The file must
9354       exist already.
9355
9356       If the current file size is less than "size" then the file is extended
9357       to the required size with zero bytes.  This creates a sparse file (ie.
9358       disk blocks are not allocated for the file until you write to it).  To
9359       create a non-sparse file of zeroes, use "fallocate64" instead.
9360
9361   tune2fs
9362        tune2fs device [force:true|false] [maxmountcount:N] [mountcount:N] [errorbehavior:..] [group:N] [intervalbetweenchecks:N] [reservedblockspercentage:N] [lastmounteddirectory:..] [reservedblockscount:N] [user:N]
9363
9364       This call allows you to adjust various filesystem parameters of an
9365       ext2/ext3/ext4 filesystem called "device".
9366
9367       The optional parameters are:
9368
9369       "force"
9370           Force tune2fs to complete the operation even in the face of errors.
9371           This is the same as the tune2fs(8) "-f" option.
9372
9373       "maxmountcount"
9374           Set the number of mounts after which the filesystem is checked by
9375           e2fsck(8).  If this is 0 then the number of mounts is disregarded.
9376           This is the same as the tune2fs(8) "-c" option.
9377
9378       "mountcount"
9379           Set the number of times the filesystem has been mounted.  This is
9380           the same as the tune2fs(8) "-C" option.
9381
9382       "errorbehavior"
9383           Change the behavior of the kernel code when errors are detected.
9384           Possible values currently are: "continue", "remount-ro", "panic".
9385           In practice these options don't really make any difference,
9386           particularly for write errors.
9387
9388           This is the same as the tune2fs(8) "-e" option.
9389
9390       "group"
9391           Set the group which can use reserved filesystem blocks.  This is
9392           the same as the tune2fs(8) "-g" option except that it can only be
9393           specified as a number.
9394
9395       "intervalbetweenchecks"
9396           Adjust the maximal time between two filesystem checks (in seconds).
9397           If the option is passed as 0 then time-dependent checking is
9398           disabled.
9399
9400           This is the same as the tune2fs(8) "-i" option.
9401
9402       "reservedblockspercentage"
9403           Set the percentage of the filesystem which may only be allocated by
9404           privileged processes.  This is the same as the tune2fs(8) "-m"
9405           option.
9406
9407       "lastmounteddirectory"
9408           Set the last mounted directory.  This is the same as the tune2fs(8)
9409           "-M" option.
9410
9411       "reservedblockscount" Set the number of reserved filesystem blocks.
9412       This is the same as the tune2fs(8) "-r" option.
9413       "user"
9414           Set the user who can use the reserved filesystem blocks.  This is
9415           the same as the tune2fs(8) "-u" option except that it can only be
9416           specified as a number.
9417
9418       To get the current values of filesystem parameters, see "tune2fs-l".
9419       For precise details of how tune2fs works, see the tune2fs(8) man page.
9420
9421       This command has one or more optional arguments.  See "OPTIONAL
9422       ARGUMENTS".
9423
9424   tune2fs-l
9425        tune2fs-l device
9426
9427       This returns the contents of the ext2, ext3 or ext4 filesystem
9428       superblock on "device".
9429
9430       It is the same as running "tune2fs -l device".  See tune2fs(8) manpage
9431       for more details.  The list of fields returned isn't clearly defined,
9432       and depends on both the version of "tune2fs" that libguestfs was built
9433       against, and the filesystem itself.
9434
9435   txz-in
9436        txz-in (tarball|-) directory
9437
9438       This command uploads and unpacks local file "tarball" (an xz compressed
9439       tar file) into directory.
9440
9441       Use "-" instead of a filename to read/write from stdin/stdout.
9442
9443       This function is deprecated.  In new code, use the "tar-in" call
9444       instead.
9445
9446       Deprecated functions will not be removed from the API, but the fact
9447       that they are deprecated indicates that there are problems with correct
9448       use of these functions.
9449
9450       This command depends on the feature "xz".   See also "feature-
9451       available".
9452
9453   txz-out
9454        txz-out directory (tarball|-)
9455
9456       This command packs the contents of directory and downloads it to local
9457       file "tarball" (as an xz compressed tar archive).
9458
9459       Use "-" instead of a filename to read/write from stdin/stdout.
9460
9461       This function is deprecated.  In new code, use the "tar-out" call
9462       instead.
9463
9464       Deprecated functions will not be removed from the API, but the fact
9465       that they are deprecated indicates that there are problems with correct
9466       use of these functions.
9467
9468       This command depends on the feature "xz".   See also "feature-
9469       available".
9470
9471   umask
9472        umask mask
9473
9474       This function sets the mask used for creating new files and device
9475       nodes to "mask & 0777".
9476
9477       Typical umask values would be 022 which creates new files with
9478       permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
9479       new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
9480
9481       The default umask is 022.  This is important because it means that
9482       directories and device nodes will be created with 0644 or 0755 mode
9483       even if you specify 0777.
9484
9485       See also "get-umask", umask(2), "mknod", "mkdir".
9486
9487       This call returns the previous umask.
9488
9489   umount
9490   unmount
9491   umount-opts
9492        umount pathordevice [force:true|false] [lazyunmount:true|false]
9493
9494       This unmounts the given filesystem.  The filesystem may be specified
9495       either by its mountpoint (path) or the device which contains the
9496       filesystem.
9497
9498       This command has one or more optional arguments.  See "OPTIONAL
9499       ARGUMENTS".
9500
9501   umount-all
9502   unmount-all
9503        umount-all
9504
9505       This unmounts all mounted filesystems.
9506
9507       Some internal mounts are not unmounted by this call.
9508
9509   umount-local
9510        umount-local [retry:true|false]
9511
9512       If libguestfs is exporting the filesystem on a local mountpoint, then
9513       this unmounts it.
9514
9515       See "MOUNT LOCAL" in guestfs(3) for full documentation.
9516
9517       This command has one or more optional arguments.  See "OPTIONAL
9518       ARGUMENTS".
9519
9520   upload
9521        upload (filename|-) remotefilename
9522
9523       Upload local file filename to remotefilename on the filesystem.
9524
9525       filename can also be a named pipe.
9526
9527       See also "download".
9528
9529       Use "-" instead of a filename to read/write from stdin/stdout.
9530
9531   upload-offset
9532        upload-offset (filename|-) remotefilename offset
9533
9534       Upload local file filename to remotefilename on the filesystem.
9535
9536       remotefilename is overwritten starting at the byte "offset" specified.
9537       The intention is to overwrite parts of existing files or devices,
9538       although if a non-existent file is specified then it is created with a
9539       "hole" before "offset".  The size of the data written is implicit in
9540       the size of the source filename.
9541
9542       Note that there is no limit on the amount of data that can be uploaded
9543       with this call, unlike with "pwrite", and this call always writes the
9544       full amount unless an error occurs.
9545
9546       See also "upload", "pwrite".
9547
9548       Use "-" instead of a filename to read/write from stdin/stdout.
9549
9550   user-cancel
9551        user-cancel
9552
9553       This function cancels the current upload or download operation.
9554
9555       Unlike most other libguestfs calls, this function is signal safe and
9556       thread safe.  You can call it from a signal handler or from another
9557       thread, without needing to do any locking.
9558
9559       The transfer that was in progress (if there is one) will stop shortly
9560       afterwards, and will return an error.  The errno (see
9561       "guestfs_last_errno") is set to "EINTR", so you can test for this to
9562       find out if the operation was cancelled or failed because of another
9563       error.
9564
9565       No cleanup is performed: for example, if a file was being uploaded then
9566       after cancellation there may be a partially uploaded file.  It is the
9567       caller’s responsibility to clean up if necessary.
9568
9569       There are two common places that you might call "user-cancel":
9570
9571       In an interactive text-based program, you might call it from a "SIGINT"
9572       signal handler so that pressing "^C" cancels the current operation.
9573       (You also need to call "set-pgroup" so that child processes don't
9574       receive the "^C" signal).
9575
9576       In a graphical program, when the main thread is displaying a progress
9577       bar with a cancel button, wire up the cancel button to call this
9578       function.
9579
9580   utimens
9581        utimens path atsecs atnsecs mtsecs mtnsecs
9582
9583       This command sets the timestamps of a file with nanosecond precision.
9584
9585       "atsecs", "atnsecs" are the last access time (atime) in secs and
9586       nanoseconds from the epoch.
9587
9588       "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
9589       nanoseconds from the epoch.
9590
9591       If the *nsecs field contains the special value "-1" then the
9592       corresponding timestamp is set to the current time.  (The *secs field
9593       is ignored in this case).
9594
9595       If the *nsecs field contains the special value "-2" then the
9596       corresponding timestamp is left unchanged.  (The *secs field is ignored
9597       in this case).
9598
9599   utsname
9600        utsname
9601
9602       This returns the kernel version of the appliance, where this is
9603       available.  This information is only useful for debugging.  Nothing in
9604       the returned structure is defined by the API.
9605
9606   version
9607        version
9608
9609       Return the libguestfs version number that the program is linked
9610       against.
9611
9612       Note that because of dynamic linking this is not necessarily the
9613       version of libguestfs that you compiled against.  You can compile the
9614       program, and then at runtime dynamically link against a completely
9615       different libguestfs.so library.
9616
9617       This call was added in version 1.0.58.  In previous versions of
9618       libguestfs there was no way to get the version number.  From C code you
9619       can use dynamic linker functions to find out if this symbol exists (if
9620       it doesn't, then it’s an earlier version).
9621
9622       The call returns a structure with four elements.  The first three
9623       ("major", "minor" and "release") are numbers and correspond to the
9624       usual version triplet.  The fourth element ("extra") is a string and is
9625       normally empty, but may be used for distro-specific information.
9626
9627       To construct the original version string:
9628       "$major.$minor.$release$extra"
9629
9630       See also: "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
9631
9632       Note: Don't use this call to test for availability of features.  In
9633       enterprise distributions we backport features from later versions into
9634       earlier versions, making this an unreliable way to test for features.
9635       Use "available" or "feature-available" instead.
9636
9637   vfs-label
9638        vfs-label mountable
9639
9640       This returns the label of the filesystem on "mountable".
9641
9642       If the filesystem is unlabeled, this returns the empty string.
9643
9644       To find a filesystem from the label, use "findfs-label".
9645
9646   vfs-minimum-size
9647        vfs-minimum-size mountable
9648
9649       Get the minimum size of filesystem in bytes.  This is the minimum
9650       possible size for filesystem shrinking.
9651
9652       If getting minimum size of specified filesystem is not supported, this
9653       will fail and set errno as ENOTSUP.
9654
9655       See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
9656
9657   vfs-type
9658        vfs-type mountable
9659
9660       This command gets the filesystem type corresponding to the filesystem
9661       on "mountable".
9662
9663       For most filesystems, the result is the name of the Linux VFS module
9664       which would be used to mount this filesystem if you mounted it without
9665       specifying the filesystem type.  For example a string such as "ext3" or
9666       "ntfs".
9667
9668   vfs-uuid
9669   get-uuid
9670        vfs-uuid mountable
9671
9672       This returns the filesystem UUID of the filesystem on "mountable".
9673
9674       If the filesystem does not have a UUID, this returns the empty string.
9675
9676       To find a filesystem from the UUID, use "findfs-uuid".
9677
9678   vg-activate
9679        vg-activate true|false 'volgroups ...'
9680
9681       This command activates or (if "activate" is false) deactivates all
9682       logical volumes in the listed volume groups "volgroups".
9683
9684       This command is the same as running "vgchange -a y|n volgroups..."
9685
9686       Note that if "volgroups" is an empty list then all volume groups are
9687       activated or deactivated.
9688
9689       This command depends on the feature "lvm2".   See also "feature-
9690       available".
9691
9692   vg-activate-all
9693        vg-activate-all true|false
9694
9695       This command activates or (if "activate" is false) deactivates all
9696       logical volumes in all volume groups.
9697
9698       This command is the same as running "vgchange -a y|n"
9699
9700       This command depends on the feature "lvm2".   See also "feature-
9701       available".
9702
9703   vgchange-uuid
9704        vgchange-uuid vg
9705
9706       Generate a new random UUID for the volume group "vg".
9707
9708       This command depends on the feature "lvm2".   See also "feature-
9709       available".
9710
9711   vgchange-uuid-all
9712        vgchange-uuid-all
9713
9714       Generate new random UUIDs for all volume groups.
9715
9716       This command depends on the feature "lvm2".   See also "feature-
9717       available".
9718
9719   vgcreate
9720        vgcreate volgroup 'physvols ...'
9721
9722       This creates an LVM volume group called "volgroup" from the non-empty
9723       list of physical volumes "physvols".
9724
9725       This command depends on the feature "lvm2".   See also "feature-
9726       available".
9727
9728   vglvuuids
9729        vglvuuids vgname
9730
9731       Given a VG called "vgname", this returns the UUIDs of all the logical
9732       volumes created in this volume group.
9733
9734       You can use this along with "lvs" and "lvuuid" calls to associate
9735       logical volumes and volume groups.
9736
9737       See also "vgpvuuids".
9738
9739   vgmeta
9740        vgmeta vgname
9741
9742       "vgname" is an LVM volume group.  This command examines the volume
9743       group and returns its metadata.
9744
9745       Note that the metadata is an internal structure used by LVM, subject to
9746       change at any time, and is provided for information only.
9747
9748       This command depends on the feature "lvm2".   See also "feature-
9749       available".
9750
9751   vgpvuuids
9752        vgpvuuids vgname
9753
9754       Given a VG called "vgname", this returns the UUIDs of all the physical
9755       volumes that this volume group resides on.
9756
9757       You can use this along with "pvs" and "pvuuid" calls to associate
9758       physical volumes and volume groups.
9759
9760       See also "vglvuuids".
9761
9762   vgremove
9763        vgremove vgname
9764
9765       Remove an LVM volume group "vgname", (for example "VG").
9766
9767       This also forcibly removes all logical volumes in the volume group (if
9768       any).
9769
9770       This command depends on the feature "lvm2".   See also "feature-
9771       available".
9772
9773   vgrename
9774        vgrename volgroup newvolgroup
9775
9776       Rename a volume group "volgroup" with the new name "newvolgroup".
9777
9778   vgs
9779        vgs
9780
9781       List all the volumes groups detected.  This is the equivalent of the
9782       vgs(8) command.
9783
9784       This returns a list of just the volume group names that were detected
9785       (eg. "VolGroup00").
9786
9787       See also "vgs-full".
9788
9789       This command depends on the feature "lvm2".   See also "feature-
9790       available".
9791
9792   vgs-full
9793        vgs-full
9794
9795       List all the volumes groups detected.  This is the equivalent of the
9796       vgs(8) command.  The "full" version includes all fields.
9797
9798       This command depends on the feature "lvm2".   See also "feature-
9799       available".
9800
9801   vgscan
9802        vgscan
9803
9804       This rescans all block devices and rebuilds the list of LVM physical
9805       volumes, volume groups and logical volumes.
9806
9807       This function is deprecated.  In new code, use the "lvm-scan" call
9808       instead.
9809
9810       Deprecated functions will not be removed from the API, but the fact
9811       that they are deprecated indicates that there are problems with correct
9812       use of these functions.
9813
9814   vguuid
9815        vguuid vgname
9816
9817       This command returns the UUID of the LVM VG named "vgname".
9818
9819   wc-c
9820        wc-c path
9821
9822       This command counts the characters in a file, using the "wc -c"
9823       external command.
9824
9825   wc-l
9826        wc-l path
9827
9828       This command counts the lines in a file, using the "wc -l" external
9829       command.
9830
9831   wc-w
9832        wc-w path
9833
9834       This command counts the words in a file, using the "wc -w" external
9835       command.
9836
9837   wipefs
9838        wipefs device
9839
9840       This command erases filesystem or RAID signatures from the specified
9841       "device" to make the filesystem invisible to libblkid.
9842
9843       This does not erase the filesystem itself nor any other data from the
9844       "device".
9845
9846       Compare with "zero" which zeroes the first few blocks of a device.
9847
9848       This command depends on the feature "wipefs".   See also "feature-
9849       available".
9850
9851   write
9852        write path content
9853
9854       This call creates a file called "path".  The content of the file is the
9855       string "content" (which can contain any 8 bit data).
9856
9857       See also "write-append".
9858
9859   write-append
9860        write-append path content
9861
9862       This call appends "content" to the end of file "path".  If "path" does
9863       not exist, then a new file is created.
9864
9865       See also "write".
9866
9867   write-file
9868        write-file path content size
9869
9870       This call creates a file called "path".  The contents of the file is
9871       the string "content" (which can contain any 8 bit data), with length
9872       "size".
9873
9874       As a special case, if "size" is 0 then the length is calculated using
9875       "strlen" (so in this case the content cannot contain embedded ASCII
9876       NULs).
9877
9878       NB. Owing to a bug, writing content containing ASCII NUL characters
9879       does not work, even if the length is specified.
9880
9881       Because of the message protocol, there is a transfer limit of somewhere
9882       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
9883
9884       This function is deprecated.  In new code, use the "write" call
9885       instead.
9886
9887       Deprecated functions will not be removed from the API, but the fact
9888       that they are deprecated indicates that there are problems with correct
9889       use of these functions.
9890
9891   xfs-admin
9892        xfs-admin device [extunwritten:true|false] [imgfile:true|false] [v2log:true|false] [projid32bit:true|false] [lazycounter:true|false] [label:..] [uuid:..]
9893
9894       Change the parameters of the XFS filesystem on "device".
9895
9896       Devices that are mounted cannot be modified.  Administrators must
9897       unmount filesystems before this call can modify parameters.
9898
9899       Some of the parameters of a mounted filesystem can be examined and
9900       modified using the "xfs-info" and "xfs-growfs" calls.
9901
9902       This command has one or more optional arguments.  See "OPTIONAL
9903       ARGUMENTS".
9904
9905       This command depends on the feature "xfs".   See also "feature-
9906       available".
9907
9908   xfs-growfs
9909        xfs-growfs path [datasec:true|false] [logsec:true|false] [rtsec:true|false] [datasize:N] [logsize:N] [rtsize:N] [rtextsize:N] [maxpct:N]
9910
9911       Grow the XFS filesystem mounted at "path".
9912
9913       The returned struct contains geometry information.  Missing fields are
9914       returned as "-1" (for numeric fields) or empty string.
9915
9916       This command has one or more optional arguments.  See "OPTIONAL
9917       ARGUMENTS".
9918
9919       This command depends on the feature "xfs".   See also "feature-
9920       available".
9921
9922   xfs-info
9923        xfs-info pathordevice
9924
9925       "pathordevice" is a mounted XFS filesystem or a device containing an
9926       XFS filesystem.  This command returns the geometry of the filesystem.
9927
9928       The returned struct contains geometry information.  Missing fields are
9929       returned as "-1" (for numeric fields) or empty string.
9930
9931       This command depends on the feature "xfs".   See also "feature-
9932       available".
9933
9934   xfs-repair
9935        xfs-repair device [forcelogzero:true|false] [nomodify:true|false] [noprefetch:true|false] [forcegeometry:true|false] [maxmem:N] [ihashsize:N] [bhashsize:N] [agstride:N] [logdev:..] [rtdev:..]
9936
9937       Repair corrupt or damaged XFS filesystem on "device".
9938
9939       The filesystem is specified using the "device" argument which should be
9940       the device name of the disk partition or volume containing the
9941       filesystem.  If given the name of a block device, "xfs_repair" will
9942       attempt to find the raw device associated with the specified block
9943       device and will use the raw device instead.
9944
9945       Regardless, the filesystem to be repaired must be unmounted, otherwise,
9946       the resulting filesystem may be inconsistent or corrupt.
9947
9948       The returned status indicates whether filesystem corruption was
9949       detected (returns 1) or was not detected (returns 0).
9950
9951       This command has one or more optional arguments.  See "OPTIONAL
9952       ARGUMENTS".
9953
9954       This command depends on the feature "xfs".   See also "feature-
9955       available".
9956
9957   yara-destroy
9958        yara-destroy
9959
9960       Destroy previously loaded Yara rules in order to free libguestfs
9961       resources.
9962
9963       This command depends on the feature "libyara".   See also "feature-
9964       available".
9965
9966   yara-load
9967        yara-load (filename|-)
9968
9969       Upload a set of Yara rules from local file filename.
9970
9971       Yara rules allow to categorize files based on textual or binary
9972       patterns within their content.  See "yara-scan" to see how to scan
9973       files with the loaded rules.
9974
9975       Rules can be in binary format, as when compiled with yarac command, or
9976       in source code format. In the latter case, the rules will be first
9977       compiled and then loaded.
9978
9979       Rules in source code format cannot include external files. In such
9980       cases, it is recommended to compile them first.
9981
9982       Previously loaded rules will be destroyed.
9983
9984       Use "-" instead of a filename to read/write from stdin/stdout.
9985
9986       This command depends on the feature "libyara".   See also "feature-
9987       available".
9988
9989   yara-scan
9990        yara-scan path
9991
9992       Scan a file with the previously loaded Yara rules.
9993
9994       For each matching rule, a "yara_detection" structure is returned.
9995
9996       The "yara_detection" structure contains the following fields.
9997
9998       "yara_name"
9999           Path of the file matching a Yara rule.
10000
10001       "yara_rule"
10002           Identifier of the Yara rule which matched against the given file.
10003
10004       This command depends on the feature "libyara".   See also "feature-
10005       available".
10006
10007   zegrep
10008        zegrep regex path
10009
10010       This calls the external "zegrep" program and returns the matching
10011       lines.
10012
10013       Because of the message protocol, there is a transfer limit of somewhere
10014       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10015
10016       This function is deprecated.  In new code, use the "grep" call instead.
10017
10018       Deprecated functions will not be removed from the API, but the fact
10019       that they are deprecated indicates that there are problems with correct
10020       use of these functions.
10021
10022   zegrepi
10023        zegrepi regex path
10024
10025       This calls the external "zegrep -i" program and returns the matching
10026       lines.
10027
10028       Because of the message protocol, there is a transfer limit of somewhere
10029       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10030
10031       This function is deprecated.  In new code, use the "grep" call instead.
10032
10033       Deprecated functions will not be removed from the API, but the fact
10034       that they are deprecated indicates that there are problems with correct
10035       use of these functions.
10036
10037   zero
10038        zero device
10039
10040       This command writes zeroes over the first few blocks of "device".
10041
10042       How many blocks are zeroed isn't specified (but it’s not enough to
10043       securely wipe the device).  It should be sufficient to remove any
10044       partition tables, filesystem superblocks and so on.
10045
10046       If blocks are already zero, then this command avoids writing zeroes.
10047       This prevents the underlying device from becoming non-sparse or growing
10048       unnecessarily.
10049
10050       See also: "zero-device", "scrub-device", "is-zero-device"
10051
10052   zero-device
10053        zero-device device
10054
10055       This command writes zeroes over the entire "device".  Compare with
10056       "zero" which just zeroes the first few blocks of a device.
10057
10058       If blocks are already zero, then this command avoids writing zeroes.
10059       This prevents the underlying device from becoming non-sparse or growing
10060       unnecessarily.
10061
10062   zero-free-space
10063        zero-free-space directory
10064
10065       Zero the free space in the filesystem mounted on directory.  The
10066       filesystem must be mounted read-write.
10067
10068       The filesystem contents are not affected, but any free space in the
10069       filesystem is freed.
10070
10071       Free space is not "trimmed".  You may want to call "fstrim" either as
10072       an alternative to this, or after calling this, depending on your
10073       requirements.
10074
10075   zerofree
10076        zerofree device
10077
10078       This runs the zerofree program on "device".  This program claims to
10079       zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
10080       it possible to compress the filesystem more effectively.
10081
10082       You should not run this program if the filesystem is mounted.
10083
10084       It is possible that using this program can damage the filesystem or
10085       data on the filesystem.
10086
10087       This command depends on the feature "zerofree".   See also "feature-
10088       available".
10089
10090   zfgrep
10091        zfgrep pattern path
10092
10093       This calls the external "zfgrep" program and returns the matching
10094       lines.
10095
10096       Because of the message protocol, there is a transfer limit of somewhere
10097       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10098
10099       This function is deprecated.  In new code, use the "grep" call instead.
10100
10101       Deprecated functions will not be removed from the API, but the fact
10102       that they are deprecated indicates that there are problems with correct
10103       use of these functions.
10104
10105   zfgrepi
10106        zfgrepi pattern path
10107
10108       This calls the external "zfgrep -i" program and returns the matching
10109       lines.
10110
10111       Because of the message protocol, there is a transfer limit of somewhere
10112       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10113
10114       This function is deprecated.  In new code, use the "grep" call instead.
10115
10116       Deprecated functions will not be removed from the API, but the fact
10117       that they are deprecated indicates that there are problems with correct
10118       use of these functions.
10119
10120   zfile
10121        zfile meth path
10122
10123       This command runs file(1) after first decompressing "path" using
10124       "meth".
10125
10126       "meth" must be one of "gzip", "compress" or "bzip2".
10127
10128       Since 1.0.63, use "file" instead which can now process compressed
10129       files.
10130
10131       This function is deprecated.  In new code, use the "file" call instead.
10132
10133       Deprecated functions will not be removed from the API, but the fact
10134       that they are deprecated indicates that there are problems with correct
10135       use of these functions.
10136
10137   zgrep
10138        zgrep regex path
10139
10140       This calls the external zgrep(1) program and returns the matching
10141       lines.
10142
10143       Because of the message protocol, there is a transfer limit of somewhere
10144       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10145
10146       This function is deprecated.  In new code, use the "grep" call instead.
10147
10148       Deprecated functions will not be removed from the API, but the fact
10149       that they are deprecated indicates that there are problems with correct
10150       use of these functions.
10151
10152   zgrepi
10153        zgrepi regex path
10154
10155       This calls the external "zgrep -i" program and returns the matching
10156       lines.
10157
10158       Because of the message protocol, there is a transfer limit of somewhere
10159       between 2MB and 4MB.  See "PROTOCOL LIMITS" in guestfs(3).
10160
10161       This function is deprecated.  In new code, use the "grep" call instead.
10162
10163       Deprecated functions will not be removed from the API, but the fact
10164       that they are deprecated indicates that there are problems with correct
10165       use of these functions.
10166

EXIT STATUS

10168       guestfish returns 0 if the commands completed without error, or 1 if
10169       there was an error.
10170

ENVIRONMENT VARIABLES

10172       EDITOR
10173           The "edit" command uses $EDITOR as the editor.  If not set, it uses
10174           "vi".
10175
10176       GUESTFISH_DISPLAY_IMAGE
10177           The "display" command uses $GUESTFISH_DISPLAY_IMAGE to display
10178           images.  If not set, it uses display(1).
10179
10180       GUESTFISH_INIT
10181           Printed when guestfish starts.  See "PROMPT".
10182
10183       GUESTFISH_OUTPUT
10184           Printed before guestfish output.  See "PROMPT".
10185
10186       GUESTFISH_PID
10187           Used with the --remote option to specify the remote guestfish
10188           process to control.  See section "REMOTE CONTROL GUESTFISH OVER A
10189           SOCKET".
10190
10191       GUESTFISH_PS1
10192           Set the command prompt.  See "PROMPT".
10193
10194       GUESTFISH_RESTORE
10195           Printed before guestfish exits.  See "PROMPT".
10196
10197       HEXEDITOR
10198           The "hexedit" command uses $HEXEDITOR as the external hex editor.
10199           If not specified, the external hexedit(1) program is used.
10200
10201       HOME
10202           If compiled with GNU readline support, various files in the home
10203           directory can be used.  See "FILES".
10204
10205       LIBGUESTFS_APPEND
10206           Pass additional options to the guest kernel.
10207
10208       LIBGUESTFS_ATTACH_METHOD
10209           This is the old way to set "LIBGUESTFS_BACKEND".
10210
10211       LIBGUESTFS_BACKEND
10212           Choose the default way to create the appliance.  See
10213           "guestfs_set_backend" in guestfs(3).
10214
10215       LIBGUESTFS_BACKEND_SETTINGS
10216           A colon-separated list of backend-specific settings.  See "BACKEND"
10217           in guestfs(3), "BACKEND SETTINGS" in guestfs(3).
10218
10219       LIBGUESTFS_CACHEDIR
10220           The location where libguestfs will cache its appliance, when using
10221           a supermin appliance.  The appliance is cached and shared between
10222           all handles which have the same effective user ID.
10223
10224           If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used.  If
10225           "TMPDIR" is not set, then /var/tmp is used.
10226
10227           See also "LIBGUESTFS_TMPDIR", "set-cachedir".
10228
10229       LIBGUESTFS_DEBUG
10230           Set "LIBGUESTFS_DEBUG=1" to enable verbose messages.  This has the
10231           same effect as using the -v option.
10232
10233       LIBGUESTFS_HV
10234           Set the default hypervisor (usually qemu) binary that libguestfs
10235           uses.  If not set, then the qemu which was found at compile time by
10236           the configure script is used.
10237
10238       LIBGUESTFS_MEMSIZE
10239           Set the memory allocated to the qemu process, in megabytes.  For
10240           example:
10241
10242            LIBGUESTFS_MEMSIZE=700
10243
10244       LIBGUESTFS_PATH
10245           Set the path that guestfish uses to search for kernel and
10246           initrd.img.  See the discussion of paths in guestfs(3).
10247
10248       LIBGUESTFS_QEMU
10249           This is the old way to set "LIBGUESTFS_HV".
10250
10251       LIBGUESTFS_TMPDIR
10252           The location where libguestfs will store temporary files used by
10253           each handle.
10254
10255           If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used.  If
10256           "TMPDIR" is not set, then /tmp is used.
10257
10258           See also "LIBGUESTFS_CACHEDIR", "set-tmpdir".
10259
10260       LIBGUESTFS_TRACE
10261           Set "LIBGUESTFS_TRACE=1" to enable command traces.
10262
10263       PAGER
10264           The "more" command uses $PAGER as the pager.  If not set, it uses
10265           "more".
10266
10267       PATH
10268           Libguestfs and guestfish may run some external programs, and rely
10269           on $PATH being set to a reasonable value.  If using the libvirt
10270           backend, libvirt will not work at all unless $PATH contains the
10271           path of qemu/KVM.
10272
10273       SUPERMIN_KERNEL
10274       SUPERMIN_KERNEL_VERSION
10275       SUPERMIN_MODULES
10276           These three environment variables allow the kernel that libguestfs
10277           uses in the appliance to be selected.  If $SUPERMIN_KERNEL is not
10278           set, then the most recent host kernel is chosen.  For more
10279           information about kernel selection, see supermin(1).
10280
10281       TMPDIR
10282           See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
10283
10284       XDG_RUNTIME_DIR
10285           This directory represents a user-specific directory for storing
10286           non-essential runtime files.
10287
10288           If it is set, then is used to store temporary sockets.  Otherwise,
10289           /tmp is used.
10290
10291           See also "get-sockdir",
10292           http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
10293

FILES

10295       $XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
10296       $HOME/.libguestfs-tools.rc
10297       $XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
10298       /etc/libguestfs-tools.conf
10299           This configuration file controls the default read-only or read-
10300           write mode (--ro or --rw).
10301
10302           See libguestfs-tools.conf(5).
10303
10304       $HOME/.guestfish
10305           If compiled with GNU readline support, then the command history is
10306           saved in this file.
10307
10308       $HOME/.inputrc
10309       /etc/inputrc
10310           If compiled with GNU readline support, then these files can be used
10311           to configure readline.  For further information, please see
10312           "INITIALIZATION FILE" in readline(3).
10313
10314           To write rules which only apply to guestfish, use:
10315
10316            $if guestfish
10317            ...
10318            $endif
10319
10320           Variables that you can set in inputrc that change the behaviour of
10321           guestfish in useful ways include:
10322
10323           completion-ignore-case (default: on)
10324               By default, guestfish will ignore case when tab-completing
10325               paths on the disk.  Use:
10326
10327                set completion-ignore-case off
10328
10329               to make guestfish case sensitive.
10330
10331       test1.img
10332       test2.img (etc)
10333           When using the -N or --new option, the prepared disk or filesystem
10334           will be created in the file test1.img in the current directory.
10335           The second use of -N will use test2.img and so on.  Any existing
10336           file with the same name will be overwritten.  You can use a
10337           different filename by using the "filename=" prefix.
10338

SEE ALSO

10340       guestfs(3), http://libguestfs.org/, virt-alignment-scan(1),
10341       virt-builder(1), virt-builder-repository(1), virt-cat(1),
10342       virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
10343       virt-diff(1), virt-edit(1), virt-filesystems(1), virt-inspector(1),
10344       virt-list-filesystems(1), virt-list-partitions(1), virt-log(1),
10345       virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
10346       virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
10347       virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
10348       virt-win-reg(1), libguestfs-tools.conf(5), display(1), hexedit(1),
10349       supermin(1).
10350

AUTHORS

10352       Richard W.M. Jones ("rjones at redhat dot com")
10353
10355       Copyright (C) 2009-2020 Red Hat Inc.
10356

LICENSE

10358       This program is free software; you can redistribute it and/or modify it
10359       under the terms of the GNU General Public License as published by the
10360       Free Software Foundation; either version 2 of the License, or (at your
10361       option) any later version.
10362
10363       This program is distributed in the hope that it will be useful, but
10364       WITHOUT ANY WARRANTY; without even the implied warranty of
10365       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
10366       General Public License for more details.
10367
10368       You should have received a copy of the GNU General Public License along
10369       with this program; if not, write to the Free Software Foundation, Inc.,
10370       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
10371

BUGS

10373       To get a list of bugs against libguestfs, use this link:
10374       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
10375
10376       To report a new bug against libguestfs, use this link:
10377       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
10378
10379       When reporting a bug, please supply:
10380
10381       ·   The version of libguestfs.
10382
10383       ·   Where you got libguestfs (eg. which Linux distro, compiled from
10384           source, etc)
10385
10386       ·   Describe the bug accurately and give a way to reproduce it.
10387
10388       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
10389           into the bug report.
10390
10391
10392
10393libguestfs-1.42.0                 2020-03-09                      guestfish(1)
Impressum