From: Richard W.M. Jones Date: Wed, 27 Apr 2011 19:10:24 +0000 (+0100) Subject: guestfs(3): Document limits. X-Git-Tag: 1.11.4~19 X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=c0f96e9c6eda77e5e99de862dd4366010e4a1ab8 guestfs(3): Document limits. --- diff --git a/src/guestfs.pod b/src/guestfs.pod index c22ad51..4e216f1 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -879,29 +879,6 @@ representation. Also consider how it might work in guestfish. =back -=head2 PROTOCOL LIMITS - -Internally libguestfs uses a message-based protocol to pass API calls -and their responses to and from a small "appliance" (see L -for plenty more detail about this). The maximum message size used by -the protocol is slightly less than 4 MB. For some API calls you may -need to be aware of this limit. The API calls which may be affected -are individually documented, with a link back to this section of the -documentation. - -A simple call such as L returns its result (the file -data) in a simple string. Because this string is at some point -internally encoded as a message, the maximum size that it can return -is slightly under 4 MB. If the requested file is larger than this -then you will get an error. - -In order to transfer large files into and out of the guest filesystem, -you need to use particular calls that support this. The sections -L and L document how to do this. - -You might also consider mounting the disk image using our FUSE -filesystem support (L). - =head2 KEYS AND PASSPHRASES Certain libguestfs calls take a parameter that contains sensitive key @@ -2773,6 +2750,97 @@ Language bindings. =back +=head1 LIMITS + +=head2 PROTOCOL LIMITS + +Internally libguestfs uses a message-based protocol to pass API calls +and their responses to and from a small "appliance" (see L +for plenty more detail about this). The maximum message size used by +the protocol is slightly less than 4 MB. For some API calls you may +need to be aware of this limit. The API calls which may be affected +are individually documented, with a link back to this section of the +documentation. + +A simple call such as L returns its result (the file +data) in a simple string. Because this string is at some point +internally encoded as a message, the maximum size that it can return +is slightly under 4 MB. If the requested file is larger than this +then you will get an error. + +In order to transfer large files into and out of the guest filesystem, +you need to use particular calls that support this. The sections +L and L document how to do this. + +You might also consider mounting the disk image using our FUSE +filesystem support (L). + +=head2 MAXIMUM NUMBER OF DISKS + +When using virtio disks (the default) the current limit is B<25> +disks. + +Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited +to 31 slots. However febootstrap only understands disks with names +C through C (26 letters) and it reserves one disk +for its own purposes. + +We are working to substantially raise this limit in future versions +but it requires complex changes to qemu. + +In future versions of libguestfs it should also be possible to "hot +plug" disks (add and remove disks after calling L). +This also requires changes to qemu. + +=head2 MAXIMUM NUMBER OF PARTITIONS PER DISK + +Virtio limits the maximum number of partitions per disk to B<15>. + +This is because it reserves 4 bits for the minor device number (thus +C, and C through C). + +If you attach a disk with more than 15 partitions, the extra +partitions are ignored by libguestfs. + +=head2 MAXIMUM SIZE OF A DISK + +Probably the limit is between 2**63-1 and 2**64-1 bytes. + +We have tested block devices up to 1 exabyte (2**60 or +1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS +host filesystem. + +=head2 MAXIMUM SIZE OF A PARTITION + +The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector +numbers. Assuming a 512 byte sector size, this means that MBR cannot +address a partition located beyond 2 TB on the disk. + +It is recommended that you use GPT partitions on disks which are +larger than this size. GPT uses 64 bit sector numbers and so can +address partitions which are theoretically larger than the largest +disk we could support. + +=head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES + +This depends on the filesystem type. libguestfs itself does not +impose any known limit. Consult Wikipedia or the filesystem +documentation to find out what these limits are. + +=head2 MAXIMUM UPLOAD AND DOWNLOAD + +The API functions L, L, +L, L and the like allow unlimited +sized uploads and downloads. + +=head2 INSPECTION LIMITS + +The inspection code has several arbitrary limits on things like the +size of Windows Registry hive it will read, and the length of product +name. These are intended to stop a malicious guest from consuming +arbitrary amounts of memory and disk space on the host, and should not +be reached in practice. See the source code for more information. + =head1 ENVIRONMENT VARIABLES =over 4