Debian Codegraph @

upstream/debian-unstable/man5/iocost.conf.5

raw
1 '\" t
2 .TH "IOCOST\&.CONF" "5" "" "systemd 261~rc3" "iocost.conf"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 iocost.conf \- Configuration files for the iocost solution manager
24 .SH "SYNOPSIS"
25 .PP
26 /etc/systemd/iocost\&.conf
27 /etc/systemd/iocost\&.conf\&.d/*\&.conf
28 .SH "DESCRIPTION"
29 .PP
30 This file configures the behavior of
31 "iocost", a tool mostly used by
32 \fBsystemd-udevd\fR(8)
33 rules to automatically apply I/O cost solutions to
34 /sys/fs/cgroup/io\&.cost\&.*\&.
35 .PP
36 The qos and model values are calculated based on benchmarks collected on the
37 \m[blue]\fBiocost\-benchmark\fR\m[]\&\s-2\u[1]\d\s+2
38 project and turned into a set of solutions that go from most to least isolated\&. Isolation allows the system to remain responsive in face of high I/O load\&. Which solutions are available for a device can be queried from the udev metadata attached to it\&. By default the naive solution is used, which provides the most bandwidth\&.
39 .SH "CONFIGURATION DIRECTORIES AND PRECEDENCE"
40 .PP
41 The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults\&. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used:
42 /etc/systemd/,
43 /run/systemd/,
44 /usr/local/lib/systemd/
45 \&\s-2\u[2]\d\s+2,
46 /usr/lib/systemd/\&. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator\&. Local overrides can also be created by creating drop\-ins, as described below\&. The main configuration file can also be edited for this purpose (or a copy in
47 /etc/
48 if it is shipped under
49 /usr/), however using drop\-ins for local configuration is recommended over modifications to the main configuration file\&.
50 .PP
51 In addition to the main configuration file, drop\-in configuration snippets are read from
52 /usr/lib/systemd/*\&.conf\&.d/,
53 /usr/local/lib/systemd/*\&.conf\&.d/, and
54 /etc/systemd/*\&.conf\&.d/\&. Those drop\-ins have higher precedence and override the main configuration file\&. Files in the
55 *\&.conf\&.d/
56 configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside\&. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files\&.
57 .PP
58 When packages need to customize the configuration, they can install drop\-ins under
59 /usr/\&. Files in
60 /etc/
61 are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages\&. Drop\-ins have to be used to override package drop\-ins, since the main configuration file has lower precedence\&. It is recommended to prefix all filenames in those subdirectories with a two\-digit number and a dash, to simplify the ordering\&. This also defines a concept of drop\-in priorities to allow OS vendors to ship drop\-ins within a specific range lower than the range used by users\&. This should lower the risk of package drop\-ins overriding accidentally drop\-ins defined by users\&. It is recommended to use the range 10\-40 for drop\-ins in
62 /usr/
63 and the range 60\-90 for drop\-ins in
64 /etc/
65 and
66 /run/, to make sure that local and transient drop\-ins take priority over drop\-ins shipped by the OS vendor\&.
67 .PP
68 To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to
69 /dev/null
70 in the configuration directory in
71 /etc/, with the same filename as the vendor configuration file\&.
72 .SH "OPTIONS"
73 .PP
74 All options are configured in the [IOCost] section:
75 .PP
76 \fITargetSolution=\fR
77 .RS 4
78 Chooses which I/O cost solution (identified by named string) should be used for the devices in this system\&. The known solutions can be queried from the udev metadata attached to the devices\&. If a device does not have the specified solution, the first one listed in
79 \fIIOCOST_SOLUTIONS\fR
80 is used instead\&.
81 .sp
82 E\&.g\&.
83 "TargetSolution=isolated\-bandwidth"\&.
84 .sp
85 Added in version 254\&.
86 .RE
87 .SH "SEE ALSO"
88 .PP
89 \fBudevadm\fR(8), \m[blue]\fBThe iocost\-benchmarks github project\fR\m[]\&\s-2\u[1]\d\s+2, \m[blue]\fBThe resctl\-bench documentation details how the values are obtained\fR\m[]\&\s-2\u[3]\d\s+2
90 .SH "NOTES"
91 .IP " 1." 4
92 iocost-benchmark
93 .RS 4
94 \%https://github.com/iocost-benchmark/iocost-benchmarks
95 .RE
96 .IP " 2." 4
97 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If
98 /usr/local/
99 is a separate partition, it may not be available during early boot, and must not be used for configuration.
100 .IP " 3." 4
101 The resctl-bench documentation details how the values are obtained
102 .RS 4
103 \%https://github.com/facebookexperimental/resctl-demo/tree/main/resctl-bench/doc
104 .RE