sfsglobaliolimits.cfg(5)
========================

== NAME

sfsglobaliolimits.cfg - global I/O limiting configuration

== DESCRIPTION

The file *sfsglobaliolimits.cfg* contains configuration of the global I/O
limiter.

== SYNTAX

Syntax is:

'option' 'value'

Lines starting with *#* character are ignored.

== OPTIONS

Configuration options:

*subsystem <subsystem>*:: The cgroups subsystem by which clients are
classified. If left unspecified, all clients are considered 'unclassified' (see
below).

*limit unclassified <throughput in KiB/s>*:: This is a special entry for
clients that don't match any group specified in configuration file or for all
clients if *subsystem* is unspecified. If this entry is unspecified and
subsystem is unspecified as well, I/O limiting is disabled entirely. If this
entry is unspecified but subsystem is specified, unclassified clients are not
allowed to perform I/O.

*limit <group> <throughput in KiB/s>*:: Set limit for clients belonging to the
cgroups group *<group>*. In SaunaFS, subgroups of *<group>* constitute
independent groups; they are not allowed to use *<group>'s* bandwidth
reservation and they don't count against *<group>'s* usage.

== EXAMPLES

 # empty file

I/O limiting is disabled, no limits are enforced.

 limit unclassified 1024

All clients are 'unclassified' and share 1MiB/s of bandwidth.

 subsystem blkio
 limit /a 1024

Clients in the *blkio* */a* group are limited to 1MiB/s, no other clients can
perform any I/O.

 subsystem blkio
 limit unclassified 256
 limit /a   1024
 limit /b/a 2048

The *blkio* group */a* is allowed to transfer 1MiB/s, while */b/a* gets 2MiB/s.
Clients from other groups (e.g. */b*, */z*, */a/a*, */b/z*) are considered
'unclassified' and share 256KiB/s of bandwidth.

== TUNING NOTES

Global I/O limiting is managed by the master server. Mount instances reserve
bandwidth allocations from master when they want to perform I/O to
chunkservers.

To avoid overloading the master under heavy traffic, mounts try to predict their
future usage and reserve at once all the bandwidth they will for the next
renegotiation period (see sfsmaster.cfg(5)).

Such reservation are wasted if the traffic at given mount instance suddenly
drops.

The ratio of bandwidth being wasted due to this phenomenon shouldn't exceed
*fsp/b*, where:

 f is the frequency of sudden traffic drops in the whole installation (in 1/s)
 s is the average size of such drop (in KiB/s)
 p is the renegotiation period (in s)
 b is the bandwidth limit (in KiB/s)

This applies to each group separately, because groups reserve their bandwidth
independently from each other.

== REPORTING BUGS

Report bugs to the GitHub repository <https://github.com/leil-io/saunafs> as an
issue.

== COPYRIGHT

Copyright 2008-2009 Gemius SA

Copyright 2013-2019 Skytechnology sp. z o.o.

Copyright 2023-2024 Leil Storage OÜ

SaunaFS is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, version 3.

SaunaFS is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
SaunaFS. If not, see <http://www.gnu.org/licenses/>.

== SEE ALSO

sfsmaster.cfg(5)
