doc: Document fs listquota 2TB partition limit
authorAndrew Deason <adeason@sinenomine.net>
Tue, 10 Jun 2014 19:47:31 +0000 (14:47 -0500)
committerJeffrey Altman <jaltman@your-file-system.com>
Wed, 3 Dec 2014 06:02:20 +0000 (01:02 -0500)
We have previously documented that volumes over 2TB can result in
inaccuracies, but this documentation does not say how the 'partition'
field in "fs listquota" can be inaccurate. It is confusing to see a
usage of 0% for a partition that you know is being used, so try to
briefly explain in what way this field is inaccurate.

The reason we _under_-report the partition usage is that the
fileserver actually gives back PartBlocksAvail and PartMaxBlocks (not
"blocks used" and "blocks total"). So 1TB used and 4TB total is
truncated to 2TB and given back as 2TB free and 2TB total. One we hit
3TB used we'll report it as 1TB free 2TB total (50%) when the actual
usage is 75%.

Change-Id: I0b3de04ef2bd6cd32fdcb1a82cbac58d5d621e5b
Reviewed-on: http://gerrit.openafs.org/11245
Reviewed-by: Benjamin Kaduk <kaduk@mit.edu>
Tested-by: BuildBot <buildbot@rampaginggeek.com>

doc/man-pages/pod1/fs_listquota.pod.in

index c8e0ef6..b0e83ba 100644 (file)
@@ -90,6 +90,15 @@ volume. Although not directly related to how much of the user's quota is
 used, it is reported because a full partition can cause writing of data
 back to the volume to fail even when the volume has not reached its quota.
 
+Note that due to limitations in the current wire protocol, OpenAFS cannot
+accurately calculate this field for partitions over 2 terabytes (2^41 bytes)
+in size. As a result, the percentage displayed in this field may be smaller
+than reality. For example, if the partition has over 2 terabytes (2^41 bytes)
+free, B<fs listquota> will report the partition usage as 0%. If the partition
+has less than 2 terabytes (2^41 bytes) free, but is larger than 2 terabytes
+(2^41 bytes) in size, the reported partition usage will be larger than
+0%, but will still be less than the actual usage.
+
 =back
 
 =head1 EXAMPLES