Editing UBC auxiliary parameters

{{UBC toc}}

Configuration of primary and secondary resource control parameters is
important for security and stability of the whole system. Auxiliary
parameters differ much from primary and secondary parameters in this respect.

The primary functions of auxiliary parameters are the following.
<ul>
<li>These parameters improve application's handling of errors and resource
consumption limitations.

Without these auxiliary parameters, possible bugs in applications (such
as forgetting to unlock locked files or forgetting to collect signals) will
cause slowdown and, after some time, killing of the applications because
of memory exhaustion. In presence of these parameters, applications
will notice the problem (because, for example, attempts to create new
file locks start to fail) and show an appropriate message helping to
debug the problem.

Another example. Each object such as opened file or established network
connection consume certain resources. When the Virtual Environment
is close to exhaustion of the resources allowed to him, it is
usually better to refuse creation of new object than to allow it but deny
memory allocation or terminate (in case of complete exhaustion of the
resources) an already running application.
</li>

<li>
These parameters improve fault isolation between applications in the
same Virtual Environment. Failures or misbehavior of one application
inside a Virtual Environment is more likely to cause hitting a
limit on some auxiliary parameter and normal termination of this mis-
behaving application, rather than abnormal termination of some other
long-running application inside the same Virtual Environment.
</li>

<li>
These parameters may be used to impose some administrative limits
on the Virtual Environment (for example, to not allow the user to run
database servers by limiting the amount of [[shmpages]], or limiting the
number of simultaneous shell sessions through [[numpty]]).
</li>
</ul>

So, auxiliary parameters play a role similar to limits imposed by
<code>setrlimit(2)</code> interface and limits configurable by
<code>sysctl(8)</code> in standard
Linux installations.

Because of this helper role in resource control, system management software
may show auxiliary parameters only in advanced mode for experienced
administrators and hide them in “basic” management modes.

== lockedpages ==
Process pages not allowed to be swapped out (pages locked by <code>mlock(2)</code>).

The size of these pages is also accounted into <code>[[kmemsize]]</code>.
The <code>barrier</code> may be set equal to the <code>limit</code> or may allow
some gap between the <code>barrier</code> and the <code>limit</code>, depending
on the nature of applications using memory locking features.

Note that typical server applications like Web, FTP, mail servers
do not use memory locking features.

The configuration of this parameter doesn't affect security and
stability of the whole system or isolation between Virtual Environments.
Its configuration affects functionality and resource shortage reaction
of applications in the given Virtual Environment only.

== shmpages ==
The total size of shared memory (IPC, shared anonymous mappings and
<code>tmpfs</code> objects).

These pages are also accounted into <code>[[privvmpages]]</code>.

The <code>barrier</code> should be set equal to the <code>limit</code>.
The configuration of this parameter doesn't affect security and
stability of the whole system or isolation between Virtual Environments.
Its configuration affects functionality and resource shortage reaction
of applications in the given Virtual Environment only.

== physpages ==
Total number of RAM pages used by processes in this Virtual Environment.

For memory pages used by several different Virtual Environments (mappings of
shared libraries, for example), only a fraction of a page is charged to each
Virtual Environment.
The sum of the <code>physpages</code> usage for all Virtual Environments
corresponds to the total number of pages used in the system by all
Virtual Environments.

<code>Physpages</code> is an accounting-only parameter currently.
In future OpenVZ releases, this parameter will allow to provide guaranteed
amount of application memory, residing in RAM and not swappable.
For compatibility with future versions, the <code>barrier</code> of this
parameter should be set to <code>0</code> and the <code>limit</code> to
the maximal allowed value ([[MAX_ULONG]]).

== numfile ==
Number of open files.

The <code>barrier</code> should be set equal to the <code>limit</code>.
The configuration of this parameter doesn't affect security and
stability of the whole system or isolation between Virtual Environments.
Its configuration affects functionality and resource shortage reaction
of applications in the given Virtual Environment only.

== numflock ==
Number of file locks.

The configuration of this parameter should have a
gap between the <code>barrier</code> and the <code>limit</code>, as illustrated in
[[UBC configuration examples]].

Very high limits on <code>numflock</code> parameters and the big number
of file locks in the system may cause certain slowdown of
the whole system (but not fatal).
So, the limits on this parameter should be reasonable, depending
on the real requirements of the applications.

== numpty ==
Number of pseudo-terminals.

This parameter is usually used to limit the number of simultaneous shell
sessions.
The <code>barrier</code> should be set equal to the <code>limit</code>.
The configuration of this parameter doesn't affect security and
stability of the whole system or isolation between Virtual Environments.
Its configuration affects functionality and resource shortage reaction
of applications in the given Virtual Environment only.
However, in OpenVZ systems, the actual number of pseudo-terminals allowed
for one Virtual Environment is limited to <code>256</code>.

== numsiginfo ==
Number of <code>siginfo</code> structures.

The size of the structure is also accounted into <code>[[kmemsize]]</code>.
The default installations of stand-alone Linux systems limit this number
to <code>1024</code> for the whole system.
In OpenVZ installations, <code>numsiginfo</code> limit applies to each
Virtual Environment individually.

The <code>barrier</code> should be set equal to the <code>limit</code>.
Very high settings of the <code>limit</code> of this parameter may reduce
responsiveness of the system.
It is unlikely that any Virtual Environment will need the limit greater than
the Linux default — <code>1024</code>.

== dcachesize ==
The total size of <code>dentry</code> and <code>inode</code> structures locked in memory.

<code>Dcachesize</code> parameter controls filesystem-related caches, such as
directory entry (<code>dentry</code>) and inode caches.
The value accounted into <code>dcachesize</code> is also included into
<code>[[kmemsize]]</code>.

<code>Dcachesize</code> exists as a separate parameter to impose a limit causing
file operations to sense memory shortage and return an error to applications,
protecting from memory shortages during critical operations that shouldn't
fail.

The configuration of this parameter should have a
gap between the <code>barrier</code> and the <code>limit</code>, as illustrated in
[[UBC configuration examples]].
The configuration of this parameter doesn't affect security and
stability of the whole system or isolation between Virtual Environments.
Its configuration affects functionality and resource shortage reaction
of applications in the given Virtual Environment only.

== numiptent ==
The number of NETFILTER (IP packet filtering) entries.

The <code>barrier</code> should be set equal to the <code>limit</code>.
There is a restriction on the total number of <code>numiptent</code>.
It depends on the amount of other allocations in so called “vmalloc”
memory area and constitutes about <code>250000</code> entries.
Violation of this restriction may cause failures of operations with
IP packet filter tables (execution of <code>iptables(8)</code>)
in any Virtual Environment or the host system,
or failures of Virtual Environment starts.
Also, large <code>numiptent</code> cause considerable slowdown of processing
of network packets.  It is not recommended to allow Virtual Environments
to create more than 200–300 <code>numiptent</code>.