X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=generator%2Fgenerator_actions.ml;h=f7a6a6cf0a49ef2df30d65b225e8229a5e49ea81;hp=41a01670663870cc1fa7227cf1436178e924b0c7;hb=5d93d70b4d36b2337104b3dbca07722fa4d47ff5;hpb=31de91f6d2605899b3a797b73b358eec9c0b1196 diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml index 41a0167..f7a6a6c 100644 --- a/generator/generator_actions.ml +++ b/generator/generator_actions.ml @@ -726,9 +726,6 @@ See also C."); [], "get type of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the type of the inspected operating system. Currently defined types are: @@ -746,6 +743,14 @@ Any Microsoft Windows operating system. FreeBSD. +=item \"netbsd\" + +NetBSD. + +=item \"hurd\" + +GNU/Hurd. + =item \"unknown\" The operating system type could not be determined. @@ -761,9 +766,6 @@ Please read L for more details."); [], "get architecture of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the architecture of the inspected operating system. The possible return values are listed under C. @@ -777,9 +779,6 @@ Please read L for more details."); [], "get distro of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the distro (distribution) of the inspected operating system. @@ -811,6 +810,10 @@ Gentoo. Linux Mint. +=item \"mageia\" + +Mageia. + =item \"mandriva\" Mandriva. @@ -819,6 +822,10 @@ Mandriva. MeeGo. +=item \"opensuse\" + +OpenSUSE. + =item \"pardus\" Pardus. @@ -839,6 +846,10 @@ Scientific Linux. Slackware. +=item \"ttylinux\" + +ttylinux. + =item \"ubuntu\" Ubuntu. @@ -863,9 +874,6 @@ Please read L for more details."); [], "get major version of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the major version number of the inspected operating system. @@ -884,9 +892,6 @@ Please read L for more details."); [], "get minor version of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the minor version number of the inspected operating system. @@ -899,9 +904,6 @@ See also C."); [], "get product name of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the product name of the inspected operating system. The product name is generally some freeform string which can be displayed to the user, but should not be @@ -916,9 +918,6 @@ Please read L for more details."); [], "get mountpoints of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns a hash of where we think the filesystems associated with this operating system should be mounted. Callers should note that this is at best an educated guess @@ -949,9 +948,6 @@ See also C."); [], "get filesystems associated with inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns a list of all the filesystems that we think are associated with this operating system. This includes the root filesystem, other ordinary filesystems, and @@ -1015,7 +1011,7 @@ be mountable but require special options. Filesystems may not all belong to a single logical operating system (use C to look for OSes)."); - ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"]), -1, [FishAlias "add"], + ("add_drive_opts", (RErr, [String "filename"], [Bool "readonly"; String "format"; String "iface"; String "name"]), -1, [FishAlias "add"], [], "add an image to examine or modify", "\ @@ -1058,15 +1054,17 @@ this security hole. This rarely-used option lets you emulate the behaviour of the deprecated C call (q.v.) +=item C + +The name the drive had in the original guest, e.g. /dev/sdb. This is used as a +hint to the guest inspection process if it is available. + =back"); ("inspect_get_windows_systemroot", (RString "systemroot", [Device "root"], []), -1, [], [], "get Windows systemroot of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the Windows systemroot of the inspected guest. The systemroot is a directory path such as C. @@ -1096,7 +1094,14 @@ Please read L for more details."); This returns the internal QEMU command line. 'debug' commands are not part of the formal API and can be removed or changed at any time."); - ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"]), -1, [FishAlias "domain"], + ("debug_drives", (RStringList "cmdline", [], []), -1, [NotInDocs], + [], + "debug the drives (internal use only)", + "\ +This returns the internal list of drives. 'debug' commands are +not part of the formal API and can be removed or changed at any time."); + + ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"; String "readonlydisk"]), -1, [FishAlias "domain"], [], "add the disk(s) from a named libvirt domain", "\ @@ -1135,12 +1140,58 @@ I be passed instead of the domain name. The C string is treated as a UUID first and looked up, and if that lookup fails then we treat C as a name as usual. +The optional C parameter controls what we do for +disks which are marked Ereadonly/E in the libvirt XML. +Possible values are: + +=over 4 + +=item readonlydisk = \"error\" + +If C is false: + +The whole call is aborted with an error if any disk with +the Ereadonly/E flag is found. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"read\" + +If C is false: + +Disks with the Ereadonly/E flag are added read-only. +Other disks are added read/write. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"write\" (default) + +If C is false: + +Disks with the Ereadonly/E flag are added read/write. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"ignore\" + +If C is true or false: + +Disks with the Ereadonly/E flag are skipped. + +=back + The other optional parameters are passed directly through to C."); (* This interface is not quite baked yet. -- RWMJ 2010-11-11 - ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"]), -1, [NotInFish], + ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"; String "readonlydisk"]), -1, [NotInFish], [], "add the disk(s) from a libvirt domain", "\ @@ -1170,6 +1221,10 @@ XML definition. The default (if the flag is omitted) is never to try. See L for more information. +The optional C parameter controls what we do for +disks which are marked Ereadonly/E in the libvirt XML. +See C for possible values. + The other optional parameters are passed directly through to C."); *) @@ -1178,9 +1233,6 @@ C."); [], "get package format used by the operating system", "\ -This function should only be called with a root device string -as returned by C. - This function and C return the package format and package management tool used by the inspected operating system. For example for Fedora these @@ -1191,7 +1243,8 @@ This returns the string C if we could not determine the package format I if the operating system does not have a real packaging system (eg. Windows). -Possible strings include: C, C, C, C, C. +Possible strings include: +C, C, C, C, C, C. Future versions of libguestfs may return other strings. Please read L for more details."); @@ -1200,9 +1253,6 @@ Please read L for more details."); [], "get package management tool used by the operating system", "\ -This function should only be called with a root device string -as returned by C. - C and this function return the package format and package management tool used by the inspected operating system. For example for Fedora these @@ -1215,7 +1265,7 @@ a real packaging system (eg. Windows). Possible strings include: C, C, C (for all Debian derivatives), -C, C, C, C. +C, C, C, C, C. Future versions of libguestfs may return other strings. Please read L for more details."); @@ -1224,9 +1274,6 @@ Please read L for more details."); [], "get list of applications installed in the operating system", "\ -This function should only be called with a root device string -as returned by C. - Return the list of applications installed in the operating system. I This call works differently from other parts of the @@ -1323,9 +1370,6 @@ Please read L for more details."); [], "get hostname of the operating system", "\ -This function should only be called with a root device string -as returned by C. - This function returns the hostname of the operating system as found by inspection of the guest's configuration files. @@ -1338,9 +1382,6 @@ Please read L for more details."); [], "get format of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the format of the inspected operating system. You can use it to detect install images, live CDs and similar. @@ -1372,9 +1413,6 @@ Please read L for more details."); [], "get live flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if a live image was detected on the disk. @@ -1385,9 +1423,6 @@ Please read L for more details."); [], "get netinst (network installer) flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if the disk is a network installer, ie. not a self-contained install CD but @@ -1400,9 +1435,6 @@ Please read L for more details."); [], "get multipart flag for install disk", "\ -This function should only be called with a root device string -as returned by C. - If C returns C (this is an install disk), then this returns true if the disk is part of a set. @@ -1444,9 +1476,6 @@ Return the current attach method. See C."); [], "get product variant of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the product variant of the inspected operating system. @@ -1474,9 +1503,6 @@ C."); [], "get Windows CurrentControlSet of inspected operating system", "\ -This function should only be called with a root device string -as returned by C. - This returns the Windows CurrentControlSet of the inspected guest. The CurrentControlSet is a registry key name such as C. @@ -1490,9 +1516,6 @@ Please read L for more details."); [], "get drive letter mappings", "\ -This function should only be called with a root device string -as returned by C. - This call is useful for Windows which uses a primitive system of assigning drive letters (like \"C:\") to partitions. This inspection API examines the Windows Registry to find out @@ -1522,6 +1545,105 @@ Please read L for more details. See also C, C."); + ("inspect_get_icon", (RBufferOut "icon", [Device "root"], [Bool "favicon"; Bool "highquality"]), -1, [], + [], + "get the icon corresponding to this operating system", + "\ +This function returns an icon corresponding to the inspected +operating system. The icon is returned as a buffer containing a +PNG image (re-encoded to PNG if necessary). + +If it was not possible to get an icon this function returns a +zero-length (non-NULL) buffer. I. + +Libguestfs will start by looking for a file called +C or C +and if it has the correct format, the contents of this file will +be returned. You can disable favicons by passing the +optional C boolean as false (default is true). + +If finding the favicon fails, then we look in other places in the +guest for a suitable icon. + +If the optional C boolean is true then +only high quality icons are returned, which means only icons of +high resolution with an alpha channel. The default (false) is +to return any icon we can, even if it is of substandard quality. + +Notes: + +=over 4 + +=item * + +Unlike most other inspection API calls, the guest's disks must be +mounted up before you call this, since it needs to read information +from the guest filesystem during the call. + +=item * + +B The icon data comes from the untrusted guest, +and should be treated with caution. PNG files have been +known to contain exploits. Ensure that libpng (or other relevant +libraries) are fully up to date before trying to process or +display the icon. + +=item * + +The PNG image returned can be any size. It might not be square. +Libguestfs tries to return the largest, highest quality +icon available. The application must scale the icon to the +required size. + +=item * + +Extracting icons from Windows guests requires the external +C program from the C package, and +several programs (C, C, C) +from the C package. These must be installed separately. + +=item * + +Operating system icons are usually trademarks. Seek legal +advice before using trademarks in applications. + +=back"); + + ("set_pgroup", (RErr, [Bool "pgroup"], []), -1, [FishAlias "pgroup"], + [], + "set process group flag", + "\ +If C is true, child processes are placed into +their own process group. + +The practical upshot of this is that signals like C (from +users pressing C<^C>) won't be received by the child process. + +The default for this flag is false, because usually you want +C<^C> to kill the subprocess."); + + ("get_pgroup", (RBool "pgroup", [], []), -1, [], + [], + "get process group flag", + "\ +This returns the process group flag."); + + ("set_smp", (RErr, [Int "smp"], []), -1, [FishAlias "smp"], + [], + "set number of virtual CPUs in appliance", + "\ +Change the number of virtual CPUs assigned to the appliance. The +default is C<1>. Increasing this may improve performance, though +often it has no effect. + +This function must be called before C."); + + ("get_smp", (RInt "smp", [], []), -1, [], + [], + "get number of virtual CPUs in appliance", + "\ +This returns the number of virtual CPUs assigned to the appliance."); + ] (* daemon_functions are any functions which cause some action @@ -1552,15 +1674,12 @@ exist. The mounted filesystem is writable, if we have sufficient permissions on the underlying device. -B -When you use this call, the filesystem options C and C -are set implicitly. This was originally done because we thought it -would improve reliability, but it turns out that I<-o sync> has a -very large negative performance impact and negligible effect on -reliability. Therefore we recommend that you avoid using -C in any code that needs performance, and instead -use C (use an empty string for the first -parameter if you don't want any options)."); +Before libguestfs 1.13.16, this call implicitly added the options +C and C. The C option greatly slowed +writes and caused many problems for users. If your program +might need to work with older versions of libguestfs, use +C instead (using an empty string for the +first parameter if you don't want any options)."); ("sync", (RErr, [], []), 2, [], [ InitEmpty, Always, TestRun [["sync"]]], @@ -1798,7 +1917,12 @@ do not overwrite original. Overrides C. =item C = 4 -Typecheck lenses (can be expensive). +Typecheck lenses. + +This option is only useful when debugging Augeas lenses. Use +of this option may require additional memory for the libguestfs +appliance. You may need to set the C +environment variable or call C. =item C = 8 @@ -2137,7 +2261,7 @@ example C."); ("sfdisk", (RErr, [Device "device"; Int "cyls"; Int "heads"; Int "sectors"; - StringList "lines"], []), 43, [DangerWillRobinson], + StringList "lines"], []), 43, [DeprecatedBy "part_add"], [], "create partitions on a block device", "\ @@ -2238,7 +2362,7 @@ This unmounts all mounted filesystems. Some internal mounts are not unmounted by this call."); - ("lvm_remove_all", (RErr, [], []), 48, [DangerWillRobinson; Optional "lvm2"], + ("lvm_remove_all", (RErr, [], []), 48, [Optional "lvm2"], [], "remove all LVM LVs, VGs and PVs", "\ @@ -2268,15 +2392,12 @@ The exact command which runs is C. Note in particular that the filename is not prepended to the output (the I<-b> option). -This command can also be used on C devices -(and partitions, LV names). You can for example use this -to determine if a device contains a filesystem, although -it's usually better to use C. +The output depends on the output of the underlying L +command and it can change in future in ways beyond our control. +In other words, the output is not guaranteed by the ABI. -If the C does not begin with C then -this command only works for the content of regular files. -For other file types (directory, symbolic link etc) it -will just return the string C etc."); +See also: L, C, C, +C, C (etc), C."); ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning], [InitScratchFS, Always, TestOutput ( @@ -2468,7 +2589,10 @@ C should be a file or directory in the mounted file system This is the same as the C system call."); ("tune2fs_l", (RHashtable "superblock", [Device "device"], []), 55, [], - [], (* XXX test *) + [InitScratchFS, Always, TestOutputHashtable ( + [["tune2fs_l"; "/dev/sdb1"]], + ["Filesystem magic number", "0xEF53"; + "Filesystem OS type", "Linux"])], "get ext2/ext3/ext4 superblock details", "\ This returns the contents of the ext2, ext3 or ext4 filesystem @@ -2594,7 +2718,7 @@ This uses the L command."); [InitScratchFS, Always, TestOutput ( (* Pick a file from cwd which isn't likely to change. *) [["mkdir"; "/upload"]; - ["upload"; "../COPYING.LIB"; "/upload/COPYING.LIB"]; + ["upload"; "../../COPYING.LIB"; "/upload/COPYING.LIB"]; ["checksum"; "md5"; "/upload/COPYING.LIB"]], Digest.to_hex (Digest.file "COPYING.LIB"))], "upload a file from the local machine", @@ -2610,7 +2734,7 @@ See also C."); [InitScratchFS, Always, TestOutput ( (* Pick a file from cwd which isn't likely to change. *) [["mkdir"; "/download"]; - ["upload"; "../COPYING.LIB"; "/download/COPYING.LIB"]; + ["upload"; "../../COPYING.LIB"; "/download/COPYING.LIB"]; ["download"; "/download/COPYING.LIB"; "testdownload.tmp"]; ["upload"; "testdownload.tmp"; "/download/upload"]; ["checksum"; "md5"; "/download/upload"]], @@ -2970,10 +3094,9 @@ Checking or repairing NTFS volumes is not supported This command is entirely equivalent to running C."); ("zero", (RErr, [Device "device"], []), 85, [Progress], - [InitBasicFS, Always, TestOutput ( + [InitBasicFS, Always, TestRun ( [["umount"; "/dev/sda1"]; - ["zero"; "/dev/sda1"]; - ["file"; "/dev/sda1"]], "data")], + ["zero"; "/dev/sda1"]])], "write zeroes to the device", "\ This command writes zeroes over the first few blocks of C. @@ -2982,9 +3105,14 @@ How many blocks are zeroed isn't specified (but it's I enough to securely wipe the device). It should be sufficient to remove any partition tables, filesystem superblocks and so on. -See also: C, C."); +If blocks are already zero, then this command avoids writing +zeroes. This prevents the underlying device from becoming non-sparse +or growing unnecessarily. + +See also: C, C, +C"); - ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [], + ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [Optional "grub"], (* See: * https://bugzilla.redhat.com/show_bug.cgi?id=484986 * https://bugzilla.redhat.com/show_bug.cgi?id=479760 @@ -2994,12 +3122,32 @@ See also: C, C."); ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"]; ["grub_install"; "/"; "/dev/vda"]; ["is_dir"; "/boot"]])], - "install GRUB", + "install GRUB 1", "\ -This command installs GRUB (the Grand Unified Bootloader) on +This command installs GRUB 1 (the Grand Unified Bootloader) on C, with the root directory being C. -Note: If grub-install reports the error +Notes: + +=over 4 + +=item * + +There is currently no way in the API to install grub2, which +is used by most modern Linux guests. It is possible to run +the grub2 command from the guest, although see the +caveats in L. + +=item * + +This uses C from the host. Unfortunately grub is +not always compatible with itself, so this only works in rather +narrow circumstances. Careful testing with each guest version +is advisable. + +=item * + +If grub-install reports the error \"No suitable drive was found in the generated device map.\" it may be that you need to create a C file first that contains the mapping between grub device names @@ -3008,7 +3156,9 @@ a file containing: (hd0) /dev/vda -replacing C with the name of the installation device."); +replacing C with the name of the installation device. + +=back"); ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [], [InitScratchFS, Always, TestOutput ( @@ -3228,7 +3378,7 @@ volume to match the new size of the underlying device."); ("sfdisk_N", (RErr, [Device "device"; Int "partnum"; Int "cyls"; Int "heads"; Int "sectors"; - String "line"], []), 99, [DangerWillRobinson], + String "line"], []), 99, [DeprecatedBy "part_add"], [], "modify a single partition on a block device", "\ @@ -3240,7 +3390,7 @@ pass C<0> for the cyls/heads/sectors parameters. See also: C"); - ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [], + ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [DeprecatedBy "part_list"], [], "display the partition table", "\ @@ -3277,9 +3427,6 @@ be parsed."); "\ This command activates or (if C is false) deactivates all logical volumes in all volume groups. -If activated, then they are made known to the -kernel, ie. they appear as C devices. If deactivated, -then those devices disappear. This command is the same as running C"); @@ -3289,9 +3436,6 @@ This command is the same as running C"); "\ This command activates or (if C is false) deactivates all logical volumes in the listed volume groups C. -If activated, then they are made known to the -kernel, ie. they appear as C devices. If deactivated, -then those devices disappear. This command is the same as running C @@ -3480,7 +3624,7 @@ It is just a wrapper around the C L function with flags C. See that manual page for more details."); - ("scrub_device", (RErr, [Device "device"], []), 114, [DangerWillRobinson; Optional "scrub"], + ("scrub_device", (RErr, [Device "device"], []), 114, [Optional "scrub"], [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *) [["scrub_device"; "/dev/sdc"]])], "scrub (securely wipe) a device", @@ -3859,7 +4003,7 @@ This function is primarily intended for use by programs. To get a simple list of names, use C. To get a printable directory for human consumption, use C."); - ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson], + ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DeprecatedBy "part_add"], [], "create partitions on a block device", "\ @@ -4675,10 +4819,31 @@ for the file until you write to it). To create a non-sparse file of zeroes, use C instead."); ("utimens", (RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"], []), 201, [], + (* Test directories, named pipes etc (RHBZ#761451, RHBZ#761460) *) [InitScratchFS, Always, TestOutputStruct ( - [["touch"; "/utimens"]; - ["utimens"; "/utimens"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens"]], [CompareWithInt ("mtime", 9876)])], + [["touch"; "/utimens-file"]; + ["utimens"; "/utimens-file"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-file"]], [CompareWithInt ("mtime", 9876)]); + InitScratchFS, Always, TestOutputStruct ( + [["mkdir"; "/utimens-dir"]; + ["utimens"; "/utimens-dir"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-dir"]], [CompareWithInt ("mtime", 9876)]); + InitScratchFS, Always, TestOutputStruct ( + [["mkfifo"; "0o644"; "/utimens-fifo"]; + ["utimens"; "/utimens-fifo"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-fifo"]], [CompareWithInt ("mtime", 9876)]); + InitScratchFS, Always, TestOutputStruct ( + [["ln_sf"; "/utimens-file"; "/utimens-link"]; + ["utimens"; "/utimens-link"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-link"]], [CompareWithInt ("mtime", 9876)]); + InitScratchFS, Always, TestOutputStruct ( + [["mknod_b"; "0o644"; "8"; "0"; "/utimens-block"]; + ["utimens"; "/utimens-block"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-block"]], [CompareWithInt ("mtime", 9876)]); + InitScratchFS, Always, TestOutputStruct ( + [["mknod_c"; "0o644"; "1"; "3"; "/utimens-char"]; + ["utimens"; "/utimens-char"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-char"]], [CompareWithInt ("mtime", 9876)])], "set timestamp of a file with nanosecond precision", "\ This command sets the timestamps of a file with nanosecond @@ -4829,7 +4994,9 @@ Possible values for C are: =over 4 -=item B | B +=item B + +=item B Intel EFI / GPT partition table. @@ -4837,7 +5004,9 @@ This is recommended for >= 2 TB partitions that will be accessed from Linux and Intel-based Mac OS X. It also has limited backwards compatibility with the C format. -=item B | B +=item B + +=item B The standard PC \"Master Boot Record\" (MBR) format used by MS-DOS and Windows. This partition type will B work @@ -4855,7 +5024,9 @@ supported include: AIX disk labels. -=item B | B +=item B + +=item B Amiga \"Rigid Disk Block\" format. @@ -4916,7 +5087,7 @@ backwards from the end of the disk (C<-1> is the last sector). Creating a partition which covers the whole disk is not so easy. Use C to do that."); - ("part_disk", (RErr, [Device "device"; String "parttype"], []), 210, [DangerWillRobinson], + ("part_disk", (RErr, [Device "device"; String "parttype"], []), 210, [], [InitEmpty, Always, TestRun ( [["part_disk"; "/dev/sda"; "mbr"]]); InitEmpty, Always, TestRun ( @@ -5075,7 +5246,7 @@ See also C. =back"); - ("dd", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []), 217, [], + ("dd", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []), 217, [DeprecatedBy "copy_device_to_device"], [InitScratchFS, Always, TestOutputBuffer ( [["mkdir"; "/dd"]; ["write"; "/dd/src"; "hello, world"]; @@ -5090,7 +5261,8 @@ example to duplicate a filesystem. If the destination is a device, it must be as large or larger than the source file or device, otherwise the copy will fail. -This command cannot do partial copies (see C)."); +This command cannot do partial copies +(see C)."); ("filesize", (RInt64 "size", [Pathname "file"], []), 218, [], [InitScratchFS, Always, TestOutputInt ( @@ -5183,7 +5355,7 @@ calls to associate logical volumes and volume groups. See also C."); - ("copy_size", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []), 227, [Progress], + ("copy_size", (RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []), 227, [Progress; DeprecatedBy "copy_device_to_device"], [InitScratchFS, Always, TestOutputBuffer ( [["mkdir"; "/copy_size"]; ["write"; "/copy_size/src"; "hello, world"]; @@ -5197,14 +5369,18 @@ or file C to another destination device or file C. Note this will fail if the source is too short or if the destination is not large enough."); - ("zero_device", (RErr, [Device "device"], []), 228, [DangerWillRobinson; Progress], + ("zero_device", (RErr, [Device "device"], []), 228, [Progress], [InitBasicFSonLVM, Always, TestRun ( [["zero_device"; "/dev/VG/LV"]])], "write zeroes to an entire device", "\ This command writes zeroes over the entire C. Compare with C which just zeroes the first few blocks of -a device."); +a device. + +If blocks are already zero, then this command avoids writing +zeroes. This prevents the underlying device from becoming non-sparse +or growing unnecessarily."); ("txz_in", (RErr, [FileIn "tarball"; Pathname "directory"], []), 229, [Optional "xz"], [InitScratchFS, Always, TestOutput ( @@ -5223,12 +5399,21 @@ I tar file) into C."); This command packs the contents of C and downloads it to local file C (as an xz compressed tar archive)."); - ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"], + ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"], [], "resize an NTFS filesystem", "\ This command resizes an NTFS filesystem, expanding or shrinking it to the size of the underlying device. + +I After the resize operation, the filesystem is marked +as requiring a consistency check (for safety). You have to boot +into Windows to perform this check and clear this condition. +Furthermore, ntfsresize refuses to resize filesystems +which have been marked in this way. So in effect it is +not possible to call ntfsresize multiple times on a single +filesystem without booting into Windows between each resize. + See also L."); ("vgscan", (RErr, [], []), 232, [], @@ -5410,7 +5595,9 @@ to ensure the length of the file is exactly C bytes."); "create a new file", "\ This call creates a file called C. The content of the -file is the string C (which can contain any 8 bit data)."); +file is the string C (which can contain any 8 bit data). + +See also C."); ("pwrite", (RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []), 247, [ProtocolLimitWarning], [InitScratchFS, Always, TestOutput ( @@ -5452,7 +5639,7 @@ allows you to specify the new size (in bytes) explicitly."); This command is the same as C except that it allows you to specify the new size (in bytes) explicitly."); - ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"], + ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"], [], "resize an NTFS filesystem (with size)", "\ @@ -5579,7 +5766,10 @@ encrypted to the underlying C respectively. If this block device contains LVM volume groups, then calling C followed by C -will make them visible."); +will make them visible. + +Use C to list all device mapper +devices."); ("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"], [], @@ -5598,7 +5788,7 @@ C parameter must be the name of the LUKS mapping device (ie. C) and I the name of the underlying block device."); - ("luks_format", (RErr, [Device "device"; Key "key"; Int "keyslot"], []), 260, [Optional "luks"; DangerWillRobinson], + ("luks_format", (RErr, [Device "device"; Key "key"; Int "keyslot"], []), 260, [Optional "luks"], [], "format a block device as a LUKS encrypted device", "\ @@ -5607,7 +5797,7 @@ the device as a LUKS encrypted device. C is the initial key, which is added to key slot C. (LUKS supports 8 key slots, numbered 0-7)."); - ("luks_format_cipher", (RErr, [Device "device"; Key "key"; Int "keyslot"; String "cipher"], []), 261, [Optional "luks"; DangerWillRobinson], + ("luks_format_cipher", (RErr, [Device "device"; Key "key"; Int "keyslot"; String "cipher"], []), 261, [Optional "luks"], [], "format a block device as a LUKS encrypted device", "\ @@ -5739,12 +5929,14 @@ removes the partition number, returning the device name (eg. \"/dev/sdb\"). The named partition must exist, for example as a string returned -from C."); +from C. + +See also C."); ("upload_offset", (RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []), 273, [Progress], (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in [InitScratchFS, Always, TestOutput ( - [["upload_offset"; "../COPYING.LIB"; "/upload_offset"; "0"]; + [["upload_offset"; "../../COPYING.LIB"; "/upload_offset"; "0"]; ["checksum"; "md5"; "/upload_offset"]], md5)]), "upload a file from the local machine with offset", "\ @@ -5772,7 +5964,7 @@ See also C, C."); [InitScratchFS, Always, TestOutput ( (* Pick a file from cwd which isn't likely to change. *) [["mkdir"; "/download_offset"]; - ["upload"; "../COPYING.LIB"; "/download_offset/COPYING.LIB"]; + ["upload"; "../../COPYING.LIB"; "/download_offset/COPYING.LIB"]; ["download_offset"; "/download_offset/COPYING.LIB"; "testdownload.tmp"; offset; size]; ["upload_offset"; "testdownload.tmp"; "/download_offset/COPYING.LIB"; offset]; ["checksum"; "md5"; "/download_offset/COPYING.LIB"]], md5)]), @@ -5837,10 +6029,10 @@ not refer to a logical volume. See also C."); - ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"]), 278, [], + ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"; Int "inode"; Int "sectorsize"]), 278, [], [InitEmpty, Always, TestOutput ( [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs_opts"; "ext2"; "/dev/sda1"; "4096"; ""]; + ["mkfs_opts"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""]; ["mount_options"; ""; "/dev/sda1"; "/"]; ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], @@ -5875,6 +6067,16 @@ for more details. You cannot use this optional parameter with the C or C filesystem type. +=item C + +This passes the I<-I> parameter to the external L program +which sets the inode size (only for ext2/3/4 filesystems at present). + +=item C + +This passes the I<-S> parameter to external L program, +which sets sector size for ufs filesystem. + =back"); ("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"], @@ -5940,6 +6142,461 @@ Instead, use the autosync flag (C) to control whether or not this operation is performed when the handle is closed."); + ("is_zero", (RBool "zeroflag", [Pathname "path"], []), 283, [], + [InitISOFS, Always, TestOutputTrue ( + [["is_zero"; "/100kallzeroes"]]); + InitISOFS, Always, TestOutputFalse ( + [["is_zero"; "/100kallspaces"]])], + "test if a file contains all zero bytes", + "\ +This returns true iff the file exists and the file is empty or +it contains all zero bytes."); + + ("is_zero_device", (RBool "zeroflag", [Device "device"], []), 284, [], + [InitBasicFS, Always, TestOutputTrue ( + [["umount"; "/dev/sda1"]; + ["zero_device"; "/dev/sda1"]; + ["is_zero_device"; "/dev/sda1"]]); + InitBasicFS, Always, TestOutputFalse ( + [["is_zero_device"; "/dev/sda1"]])], + "test if a device contains all zero bytes", + "\ +This returns true iff the device exists and contains all zero bytes. + +Note that for large devices this can take a long time to run."); + + ("list_9p", (RStringList "mounttags", [], []), 285, [], + [], + "list 9p filesystems", + "\ +List all 9p filesystems attached to the guest. A list of +mount tags is returned."); + + ("mount_9p", (RErr, [String "mounttag"; String "mountpoint"], [String "options"]), 286, [], + [], + "mount 9p filesystem", + "\ +Mount the virtio-9p filesystem with the tag C on the +directory C. + +If required, C will be automatically added to the options. +Any other options required can be passed in the optional C +parameter."); + + ("list_dm_devices", (RStringList "devices", [], []), 287, [], + [], + "list device mapper devices", + "\ +List all device mapper devices. + +The returned list contains C devices, eg. ones created +by a previous call to C. + +Device mapper devices which correspond to logical volumes are I +returned in this list. Call C if you want to list logical +volumes."); + + ("ntfsresize_opts", (RErr, [Device "device"], [Int64 "size"; Bool "force"]), 288, [Optional "ntfsprogs"], + [], + "resize an NTFS filesystem", + "\ +This command resizes an NTFS filesystem, expanding or +shrinking it to the size of the underlying device. + +The optional parameters are: + +=over 4 + +=item C + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to fit the container (eg. partition). + +=item C + +If this option is true, then force the resize of the filesystem +even if the filesystem is marked as requiring a consistency check. + +After the resize operation, the filesystem is always marked +as requiring a consistency check (for safety). You have to boot +into Windows to perform this check and clear this condition. +If you I set the C option then it is not +possible to call C multiple times on a +single filesystem without booting into Windows between each resize. + +=back + +See also L."); + + ("btrfs_filesystem_resize", (RErr, [Pathname "mountpoint"], [Int64 "size"]), 289, [Optional "btrfs"], + [], + "resize a btrfs filesystem", + "\ +This command resizes a btrfs filesystem. + +Note that unlike other resize calls, the filesystem has to be +mounted and the parameter is the mountpoint not the device +(this is a requirement of btrfs itself). + +The optional parameters are: + +=over 4 + +=item C + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to the maximum size. + +=back + +See also L."); + + ("write_append", (RErr, [Pathname "path"; BufferIn "content"], []), 290, [ProtocolLimitWarning], + [InitScratchFS, Always, TestOutput ( + [["write"; "/write_append"; "line1\n"]; + ["write_append"; "/write_append"; "line2\n"]; + ["write_append"; "/write_append"; "line3a"]; + ["write_append"; "/write_append"; "line3b\n"]; + ["cat"; "/write_append"]], "line1\nline2\nline3aline3b\n")], + "append content to end of file", + "\ +This call appends C to the end of file C. If +C does not exist, then a new file is created. + +See also C."); + + ("compress_out", (RErr, [String "ctype"; Pathname "file"; FileOut "zfile"], [Int "level"]), 291, [], + [], + "output compressed file", + "\ +This command compresses C and writes it out to the local +file C. + +The compression program used is controlled by the C parameter. +Currently this includes: C, C, C, C or C. +Some compression types may not be supported by particular builds of +libguestfs, in which case you will get an error containing the +substring \"not supported\". + +The optional C parameter controls compression level. The +meaning and default for this parameter depends on the compression +program being used."); + + ("compress_device_out", (RErr, [String "ctype"; Device "device"; FileOut "zdevice"], [Int "level"]), 292, [], + [], + "output compressed device", + "\ +This command compresses C and writes it out to the local +file C. + +The C and optional C parameters have the same meaning +as in C."); + + ("part_to_partnum", (RInt "partnum", [Device "partition"], []), 293, [], + [InitPartition, Always, TestOutputInt ( + [["part_to_partnum"; "/dev/sda1"]], 1); + InitEmpty, Always, TestLastFail ( + [["part_to_partnum"; "/dev/sda"]])], + "convert partition name to partition number", + "\ +This function takes a partition name (eg. \"/dev/sdb1\") and +returns the partition number (eg. C<1>). + +The named partition must exist, for example as a string returned +from C. + +See also C."); + + ("copy_device_to_device", (RErr, [Device "src"; Device "dest"], [Int64 "srcoffset"; Int64 "destoffset"; Int64 "size"]), 294, [Progress], + [], + "copy from source device to destination device", + "\ +The four calls C, +C, +C, and +C +let you copy from a source (device|file) to a destination +(device|file). + +Partial copies can be made since you can specify optionally +the source offset, destination offset and size to copy. These +values are all specified in bytes. If not given, the offsets +both default to zero, and the size defaults to copying as much +as possible until we hit the end of the source. + +The source and destination may be the same object. However +overlapping regions may not be copied correctly. + +If the destination is a file, it is created if required. If +the destination file is not large enough, it is extended."); + + ("copy_device_to_file", (RErr, [Device "src"; Pathname "dest"], [Int64 "srcoffset"; Int64 "destoffset"; Int64 "size"]), 295, [Progress], + [], + "copy from source device to destination file", + "\ +See C for a general overview +of this call."); + + ("copy_file_to_device", (RErr, [Pathname "src"; Device "dest"], [Int64 "srcoffset"; Int64 "destoffset"; Int64 "size"]), 296, [Progress], + [], + "copy from source file to destination device", + "\ +See C for a general overview +of this call."); + + ("copy_file_to_file", (RErr, [Pathname "src"; Pathname "dest"], [Int64 "srcoffset"; Int64 "destoffset"; Int64 "size"]), 297, [Progress], + [InitScratchFS, Always, TestOutputBuffer ( + [["mkdir"; "/copyff"]; + ["write"; "/copyff/src"; "hello, world"]; + ["copy_file_to_file"; "/copyff/src"; "/copyff/dest"; ""; ""; ""]; + ["read_file"; "/copyff/dest"]], "hello, world")], + "copy from source file to destination file", + "\ +See C for a general overview +of this call. + +This is B the function you want for copying files. This +is for copying blocks within existing files. See C, +C and C for general file copying and +moving functions."); + + ("tune2fs", (RErr, [Device "device"], [Bool "force"; Int "maxmountcount"; Int "mountcount"; String "errorbehavior"; Int64 "group"; Int "intervalbetweenchecks"; Int "reservedblockspercentage"; String "lastmounteddirectory"; Int64 "reservedblockscount"; Int64 "user"]), 298, [], + [InitScratchFS, Always, TestOutputHashtable ( + [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "0"; ""; "NOARG"; ""; ""]; + ["tune2fs_l"; "/dev/sdb1"]], + ["Check interval", "0 ()"; + "Maximum mount count", "-1"]); + InitScratchFS, Always, TestOutputHashtable ( + [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "86400"; ""; "NOARG"; ""; ""]; + ["tune2fs_l"; "/dev/sdb1"]], + ["Check interval", "86400 (1 day)"; + "Maximum mount count", "-1"]); + InitScratchFS, Always, TestOutputHashtable ( + [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "1"; ""; ""; "NOARG"; ""; "1"]; + ["tune2fs_l"; "/dev/sdb1"]], + ["Reserved blocks uid", "1 (user bin)"; + "Reserved blocks gid", "1 (group bin)"]); + InitScratchFS, Always, TestOutputHashtable ( + [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "0"; ""; ""; "NOARG"; ""; "0"]; + ["tune2fs_l"; "/dev/sdb1"]], + ["Reserved blocks uid", "0 (user root)"; + "Reserved blocks gid", "0 (group root)"]) + ], + "adjust ext2/ext3/ext4 filesystem parameters", + "\ +This call allows you to adjust various filesystem parameters of +an ext2/ext3/ext4 filesystem called C. + +The optional parameters are: + +=over 4 + +=item C + +Force tune2fs to complete the operation even in the face of errors. +This is the same as the tune2fs C<-f> option. + +=item C + +Set the number of mounts after which the filesystem is checked +by L. If this is C<0> then the number of mounts is +disregarded. This is the same as the tune2fs C<-c> option. + +=item C + +Set the number of times the filesystem has been mounted. +This is the same as the tune2fs C<-C> option. + +=item C + +Change the behavior of the kernel code when errors are detected. +Possible values currently are: C, C, C. +In practice these options don't really make any difference, +particularly for write errors. + +This is the same as the tune2fs C<-e> option. + +=item C + +Set the group which can use reserved filesystem blocks. +This is the same as the tune2fs C<-g> option except that it +can only be specified as a number. + +=item C + +Adjust the maximal time between two filesystem checks +(in seconds). If the option is passed as C<0> then +time-dependent checking is disabled. + +This is the same as the tune2fs C<-i> option. + +=item C + +Set the percentage of the filesystem which may only be allocated +by privileged processes. +This is the same as the tune2fs C<-m> option. + +=item C + +Set the last mounted directory. +This is the same as the tune2fs C<-M> option. + +=item C +Set the number of reserved filesystem blocks. +This is the same as the tune2fs C<-r> option. + +=item C + +Set the user who can use the reserved filesystem blocks. +This is the same as the tune2fs C<-u> option except that it +can only be specified as a number. + +=back + +To get the current values of filesystem parameters, see +C. For precise details of how tune2fs +works, see the L man page."); + + ("md_create", (RErr, [String "name"; DeviceList "devices"], [Int64 "missingbitmap"; Int "nrdevices"; Int "spare"; Int64 "chunk"; String "level"]), 299, [Optional "mdadm"], + [], + "create a Linux md (RAID) device", + "\ +Create a Linux md (RAID) device named C on the devices +in the list C. + +The optional parameters are: + +=over 4 + +=item C + +A bitmap of missing devices. If a bit is set it means that a +missing device is added to the array. The least significant bit +corresponds to the first device in the array. + +As examples: + +If C and C then +the resulting array would be C<[EmissingE, \"/dev/sda\"]>. + +If C and C then +the resulting array would be C<[\"/dev/sda\", EmissingE]>. + +This defaults to C<0> (no missing devices). + +The length of C + the number of bits set in +C must equal C + C. + +=item C + +The number of active RAID devices. + +If not set, this defaults to the length of C plus +the number of bits set in C. + +=item C + +The number of spare devices. + +If not set, this defaults to C<0>. + +=item C + +The chunk size in bytes. + +=item C + +The RAID level, which can be one of: +I, I, I<0>, I, I, I<1>, I, +I, I<4>, I, I<5>, I, I<6>, I, I<10>. +Some of these are synonymous, and more levels may be added in future. + +If not set, this defaults to C. + +=back"); + + ("list_md_devices", (RStringList "devices", [], []), 300, [], + [], + "list Linux md (RAID) devices", + "\ +List all Linux md devices."); + + ("md_detail", (RHashtable "info", [Device "md"], []), 301, [Optional "mdadm"], + [], + "obtain metadata for an MD device", + "\ +This command exposes the output of 'mdadm -DY '. The following fields are +usually present in the returned hash. Other fields may also be present. + +=over + +=item C + +The raid level of the MD device. + +=item C + +The number of underlying devices in the MD device. + +=item C + +The metadata version used. + +=item C + +The UUID of the MD device. + +=item C + +The name of the MD device. + +=back"); + + ("md_stop", (RErr, [Device "md"], []), 302, [Optional "mdadm"], + [], + "stop a Linux md (RAID) device", + "\ +This command deactivates the MD array named C. The +device is stopped, but it is not destroyed or zeroed."); + + ("blkid", (RHashtable "info", [Device "device"], []), 303, [], + [InitScratchFS, Always, TestOutputHashtable ( + [["blkid"; "/dev/sdb1"]], + ["TYPE", "ext2"; + "USAGE", "filesystem"; + "PART_ENTRY_NUMBER", "1"; + "PART_ENTRY_TYPE", "0x83"; + "PART_ENTRY_OFFSET", "128"; + "PART_ENTRY_SIZE", "102145"])], + "print block device attributes", + "\ +This command returns block device attributes for C. The following fields are +usually present in the returned hash. Other fields may also be present. + +=over + +=item C + +The uuid of this device. + +=item C