The aim of this article is to understand where the numbers that are shown by <code>stat</code>/<code>df</code> utils in [[VEcontainer]] come from.

== Conventions and Notations notations ==Consider typical OpenVZ setup, where <code>ext2</code> separate filesystem is mounted on <code>/vz</code>. <code>ext2</code> is called ''underlying filesystem'' in such situation.

Consider typical OpenVZ setup, where <code>ext2</code> separate file system is mounted on <code>/vz</code>. <code>ext2</code> is called ''underlying file system'' in such situation. Linux VFS design allows every filesystem file system to export to userspace user space the following information concerning disk space (here and further I use <math>{subscript }</math> is used to specify paricular filesystem particular file system type):

Note, that not all free blocks can be used by non-root users: some amount of disk space is reserved for root. For example on <code>ext2</code> filesystem file system only root can use last free 5 percent (by default) of disk space. This is the difference between <math>avail_{ext2}</math> and <math>free_{ext2}</math>. Also marknote, that the following inequality is always true:

Inside a [[VEcontainer]] , a special filesystem file system type is used: , called <code>simfs</code>. This filesystem file system allows to isolate a particular [[VECT]] from other [[VE]]sCTs. Hence, when <code>df</code> or <code>stat</code> utils utilities are invoked , they get information from <code>simfs</code>, which exports to them the following values (by analogy with <code>ext2</code>):

This article is in fact devoted to how simfs filesystem file system calculates the values above.

To produce any calculations , input data are required. What are input data for <code>simfs</code>? Except Aside from already discussed mentioned information from underlying filesystem file system (<math>total_{ext2}</math>, <math>total_{ext2}</math>, <math>total_{ext2}</math>) , one more element comes into force in OpenVZ environment. It is OpenVZ ''per-VE container disk quotas''. The values that provide this element are:

* <math>quota_{used}</math> - the number of blocks currently used by a [[VECT]]* <math>quota_{barrier}</math> - the number of blocks this [[VE]] CT can potentially can obtain

OpenVZ disk quota counts the number of blocks currently used by VE a CT and prevents this number to be greater than the limit/barrier set.

<!-- TODO: Uncoment Uncomment after adding examples.

 Consider three basic possible scenarios, that are possible. === '''Quota is off for VE''' CT ===: If quota is off for [[VE]] a CT (<code>DISK_QUOTA=no</code>), the total amount of space, that [[VE]] this CT potentially can acquire, equals the amount of total space on a partition. Certainly some space can be used by other [[VE]]sCTs, but potentially [[VE]] a CT can have all the space on device. Number So, the number of free blocks for [[VE]] the CT equals the number of free blocks on partition. Note, that it implies that [[VE]] a CT root user, can fill in all the space, including the space, that is reserved for root user of the [[HNhost system]]. This is why, you shouldn't one should not reside [[VE]]s CTs private areas on root filesystem file system of your [[HN]]host system. Amount The amount of available disk space for [[VE]] CT equals the number of available blocks for the underlying filsystemfile system. Thus, we have the following relationships: 

: Rather valuable disadvantage of switching off OpenVZ quota (besides having unlimited CTs) is that you will not be able to get information about how much disk space is used by a CT (without doing possibly long term <code>du</code> command) using <code>df</code>/<code>stat</code>. I mean, that :: <math>df_{usage} = total_{simfs} - free_{simfs} = total_{ext2} - free_{ext2},</math>: thus in the CT you obtain information about disk usage of partition, but not disk usage of the CT. === '''Quota is on for VE CT, and there is enough space on partition''' ( ===: [[:Image:Vzquota1.png|illustration 1thumb|left]]) ===: If disk quota is on, the amount of disk space that [[VE]] a CT can potentially can acquire should be equal to the quota barrier:

: Amount The amount of free space in this case should logically be the following:

: However here is a pitfall. Suppose that the amount of free disk space actually on the underlying filesystem is less than it is estimated from quota using the formule formula above, i.e.:

: Then, definitely, the amount of free disk space reported by <code>simfs</code> should be other! different. This situation will be considered in the next point and in this point examined later; here we assume that there is enough space on partition, i.e

: As concerns for amount of disk space available for non-root users, if there is enough disk space:

: then amount of disk space available for non-root users in [[VE]] a CT equals the free space estimated from quota:

=== '''Quota is on for VE CT and there is NOT enough space on partition''' (==={|[[:Image:Vzquota2.png|illustration 2thumb|left]], [[:Image:Vzquota3.png|illustration 3thumb|left]], [[:Image:Vzquota4.png|illustration 4thumb|left]], [[:Image:Vzquota5.png|illustration 5thumb|left]]) ===: ||This is the most interesting and difficult to explain case. Nevertheless I tried to do it. So, our assumption is that::: <math>quota_{barrier} - quota_{used} > free_{ext2}</math>: What should be reported as free space in such case? Of course, <math>free_{ext2}</math>! This is the actual amount of space that can be used by [[VE]]a CT. Hence::: <math>free_{simfs} = free_{ext2}</math>: And now Now consider the following situation. There is are two [[VE]]scontainers. One of [[VE]]s First CT writes nothing to disk. Second [[VE]] CT writes something to disc some informationthe disk. Administrator An administrator of [[VE]] CT #1 looks at <code>df</code> output. He observes , noting the "Usage" column. What does she see?

: <math>free_{ext2}</math> decreases because [[VE]] CT #2 writes to discdisk, consequently <math>df_{usage}</math> increases! "What “What the hell is going on?!" - ”, — thinks the administrator - "Nobody : “Nobody writes on to the disk [in my [[VE]container], but the usage increasesincreases”!" To avoid such a situation , the following approach is used in OpenVZ: decrease <math>total_{simfs}</math> , so, that <math>df_{usage}</math> remains the same, i.e.::: <math>total_{simfs} = quota_{usage} + free_{ext2}</math> (4): Substituting By substituting (4) in to (3) obtain, we get::: <math>df_{usage} = total_{simfs} - free_{simfs} = quota_{usage} + free_{ext2} - free_{ext2} = quota_{usage} = const</math>: In this case, administrator of [[VE]] CT #1 sees that total amount of space decreases, but usage however is constant.: The same reasoning reason as with <math>free_{simfs}</math> suits fits for calculating <math>avail_simfs</math>. Two cases are possible. If:: <math>avail_{ext2} \ge quota_{barrier} - quota_{used}</math>: then :: <math>avail_{simfs} = free_{ext2}</math>: and if:: <math>avail_{ext2} < quota_{barrier} - quota_{used}</math>: then:: <math>avail_{simfs} = quota_{barrier} - quota_{used}</math>

So we have there are three basic variants. Variant number one is not good, because [[VE]] a container's administrator can't not get information about [[VE]] CT disk usage and the [[HNhost system]] administrator can't limit [[VE]] CT disk usage. Variant three is not good 'cause because we have some weird (but logical) values in <code>df</code>/<code>stat</code> output in [[VE]]CT, e.g. total disk space can decrease. Variant two is perfect. How can we provide make sure that this varaint variant always take place? Here is the simple rule:

{{OutWarning|Do not set random disk quota barrier/limit!}} Even if you want a container to be unlimited, consider reasonable values. Use the following formula:

Here <math>q_i</math> is quota barrier for CT<math>i</math>,<br/><math>S</math> — total amount of space on underlying file system<br/><math>s</math> - — amount of space used by not [[VE]]s everything else than CT private area: templates, locks, etc.

Note, that if you install a template - , you decrease <math>s</math>. This is bad, because, ideally, after each templateinstallation you have to check inequality (5). To avoid this I suggest to mount separate partion partition on <code>/vz/private</code>, rather thanon <code>/vz</code>. In such case <math>s</math> always equals <math>0</math>.

{| borderclass="1" cellpadding="5" cellspacing="0wikitable" align="center"

At the moment I see only two more reasons, why numbers in <code>df</code>/<code>stat</code> output can confuse you.* # The quota is inconsistent. This can happen if you turned quota off for some time, if you wrote directly to private area (<code>/vz/private</code>), but not through <code>simfs</code>, etc. When you have doubts whether your quota is consistent or not, just drop quota (<code>vzquota drop <veidctid></code>, where <code><veidctid></code> is the id of a stopped [[VECT]]). While starting [[VECT]] , <code>vzctl</code> will automatically initalize initialize quota.* # Unsupported underlying filesystem. Currently OpenVZ quota only supports <code>ext2</code> and <code>ext3</code>. With other filesystem file system types you can have unpredictable results. Praemonitus praemunitus!