diff --git a/tuned/plugins/plugin_audio.py b/tuned/plugins/plugin_audio.py index 0f427d8..c525531 100644 --- a/tuned/plugins/plugin_audio.py +++ b/tuned/plugins/plugin_audio.py @@ -12,10 +12,28 @@ cmd = commands() class AudioPlugin(base.Plugin): """ - Plugin for tuning audio cards powersaving options. - - Power management is supported per module, not device. From this reason, - we take kernel module names as device names. + `audio`:: + + Sets audio cards power saving options. The plug-in sets the auto suspend + timeout for audio codecs to the value specified by the [option]`timeout` + option. + + + Currently, the `snd_hda_intel` and `snd_ac97_codec` codecs are + supported and the [option]`timeout` value is in seconds. To disable + auto suspend for these codecs, set the [option]`timeout` value + to `0`. To enforce the controller reset, set the option + [option]`reset_controller` to `true`. Note that power management + is supported per module. Hence, the kernel module names are used as + device names. + + + .Set the timeout value to 10s and enforce the controller reset + ==== + ---- + [audio] + timeout=10 + reset_controller=true + ---- + ==== """ def _init_devices(self): diff --git a/tuned/plugins/plugin_bootloader.py b/tuned/plugins/plugin_bootloader.py index ad2d4d5..9331888 100644 --- a/tuned/plugins/plugin_bootloader.py +++ b/tuned/plugins/plugin_bootloader.py @@ -14,10 +14,177 @@ log = tuned.logs.get() class BootloaderPlugin(base.Plugin): """ - Plugin for tuning bootloader options. - - Currently only grub2 is supported and reboot is required to apply the tunings. - These tunings are unloaded only on profile change followed by reboot. + `bootloader`:: + + Adds options to the kernel command line. This plug-in supports the + GRUB 2 boot loader and the Boot Loader Specification (BLS). + + + NOTE: *TuneD* will not remove or replace kernel command line + parameters added via other methods like *grubby*. *TuneD* will manage + the kernel command line parameters added via *TuneD*. Please refer + to your platform bootloader documentation about how to identify and + manage kernel command line parameters set outside of *TuneD*. + + + Customized non-standard location of the GRUB 2 configuration file + can be specified by the [option]`grub2_cfg_file` option. + + + The kernel options are added to the current GRUB configuration and + its templates. Reboot the system for the kernel option to take effect. + + + Switching to another profile or manually stopping the `tuned` + service removes the additional options. If you shut down or reboot + the system, the kernel options persist in the [filename]`grub.cfg` + file and grub environment files. + + + The kernel options can be specified by the following syntax: + + + [subs="+quotes,+macros"] + ---- + cmdline__suffix__=__arg1__ __arg2__ ... __argN__ + ---- + + + Or with an alternative, but equivalent syntax: + + + [subs="+quotes,+macros"] + ---- + cmdline__suffix__=+__arg1__ __arg2__ ... __argN__ + ---- + + + Where __suffix__ can be arbitrary (even empty) alphanumeric + string which should be unique across all loaded profiles. It is + recommended to use the profile name as the __suffix__ + (for example, [option]`cmdline_my_profile`). If there are multiple + [option]`cmdline` options with the same suffix, during the profile + load/merge the value which was assigned previously will be used. This + is the same behavior as any other plug-in options. The final kernel + command line is constructed by concatenating all the resulting + [option]`cmdline` options. + + + It is also possible to remove kernel options by the following syntax: + + + [subs="+quotes,+macros"] + ---- + cmdline__suffix__=-__arg1__ __arg2__ ... __argN__ + ---- + + + Such kernel options will not be concatenated and thus removed during + the final kernel command line construction. + + + .Modifying the kernel command line + ==== + For example, to add the [option]`quiet` kernel option to a *TuneD* + profile, include the following lines in the [filename]`tuned.conf` + file: + + ---- + [bootloader] + cmdline_my_profile=+quiet + ---- + + An example of a custom profile `my_profile` that adds the + [option]`isolcpus=2` option to the kernel command line: + + ---- + [bootloader] + cmdline_my_profile=isolcpus=2 + ---- + + An example of a custom profile `my_profile` that removes the + [option]`rhgb quiet` options from the kernel command line (if + previously added by *TuneD*): + + ---- + [bootloader] + cmdline_my_profile=-rhgb quiet + ---- + ==== + + + .Modifying the kernel command line, example with inheritance + ==== + For example, to add the [option]`rhgb quiet` kernel options to a + *TuneD* profile `profile_1`: + + ---- + [bootloader] + cmdline_profile_1=+rhgb quiet + ---- + + In the child profile `profile_2` drop the [option]`quiet` option + from the kernel command line: + + ---- + [main] + include=profile_1 + + [bootloader] + cmdline_profile_2=-quiet + ---- + + The final kernel command line will be [option]`rhgb`. In case the same + [option]`cmdline` suffix as in the `profile_1` is used: + + ---- + [main] + include=profile_1 + + [bootloader] + cmdline_profile_1=-quiet + ---- + + It will result in the empty kernel command line because the merge + executes and the [option]`cmdline_profile_1` gets redefined to just + [option]`-quiet`. Thus there is nothing to remove in the final kernel + command line processing. + ==== + + + The [option]`initrd_add_img=IMAGE` adds an initrd overlay file + `IMAGE`. If the `IMAGE` file name begins with '/', the absolute path is + used. Otherwise, the current profile directory is used as the base + directory for the `IMAGE`. + + + The [option]`initrd_add_dir=DIR` creates an initrd image from the + directory `DIR` and adds the resulting image as an overlay. + If the `DIR` directory name begins with '/', the absolute path + is used. Otherwise, the current profile directory is used as the + base directory for the `DIR`. + + + The [option]`initrd_dst_img=PATHNAME` sets the name and location of + the resulting initrd image. Typically, it is not necessary to use this + option. By default, the location of initrd images is `/boot` and the + name of the image is taken as the basename of `IMAGE` or `DIR`. This can + be overridden by setting [option]`initrd_dst_img`. + + + The [option]`initrd_remove_dir=VALUE` removes the source directory + from which the initrd image was built if `VALUE` is true. Only 'y', + 'yes', 't', 'true' and '1' (case insensitive) are accepted as true + values for this option. Other values are interpreted as false. + + + .Adding an overlay initrd image + ==== + ---- + [bootloader] + initrd_remove_dir=True + initrd_add_dir=/tmp/tuned-initrd.img + ---- + + This creates an initrd image from the `/tmp/tuned-initrd.img` directory + and and then removes the `tuned-initrd.img` directory from `/tmp`. + ==== + + + The [option]`skip_grub_config=VALUE` does not change grub + configuration if `VALUE` is true. However, [option]`cmdline` + options are still processed, and the result is used to verify the current + cmdline. Only 'y', 'yes', 't', 'true' and '1' (case insensitive) are accepted + as true values for this option. Other values are interpreted as false. + + + .Do not change grub configuration + ==== + ---- + [bootloader] + skip_grub_config=True + cmdline=+systemd.cpu_affinity=1 + ---- + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_cpu.py b/tuned/plugins/plugin_cpu.py index 8ab9dd3..e2630b1 100644 --- a/tuned/plugins/plugin_cpu.py +++ b/tuned/plugins/plugin_cpu.py @@ -16,7 +16,132 @@ cpuidle_states_path = "/sys/devices/system/cpu/cpu0/cpuidle" class CPULatencyPlugin(base.Plugin): """ - Plugin for tuning CPU options. Powersaving, governor, required latency, etc. + `cpu`:: + + Sets the CPU governor to the value specified by the [option]`governor` + option and dynamically changes the Power Management Quality of + Service (PM QoS) CPU Direct Memory Access (DMA) latency according + to the CPU load. + + `governor`::: + The [option]`governor` option of the 'cpu' plug-in supports specifying + CPU governors. Multiple governors are separated using '|'. The '|' + character is meant to represent a logical 'or' operator. Note that the + same syntax is used for the [option]`energy_perf_bias` option. *TuneD* + will set the first governor that is available on the system. + + + For example, with the following profile, *TuneD* will set the 'ondemand' + governor, if it is available. If it is not available, but the 'powersave' + governor is available, 'powersave' will be set. If neither of them are + available, the governor will not be changed. + + + .Specifying a CPU governor + ==== + ---- + [cpu] + governor=ondemand|powersave + ---- + ==== + + `sampling_down_factor`::: + The sampling rate determines how frequently the governor checks + to tune the CPU. The [option]`sampling_down_factor` is a tunable + that multiplies the sampling rate when the CPU is at its highest + clock frequency thereby delaying load evaluation and improving + performance. Allowed values for sampling_down_factor are 1 to 100000. + + + .The recommended setting for jitter reduction + ==== + ---- + [cpu] + sampling_down_factor = 100 + ---- + ==== + + `energy_perf_bias`::: + [option]`energy_perf_bias` supports managing energy + vs. performance policy via x86 Model Specific Registers using the + `x86_energy_perf_policy` tool. Multiple alternative Energy Performance + Bias (EPB) values are supported. The alternative values are separated + using the '|' character. The following EPB values are supported + starting with kernel 4.13: "performance", "balance-performance", + "normal", "balance-power" and "power". + + + .Specifying alternative Energy Performance Bias values + ==== + ---- + [cpu] + energy_perf_bias=powersave|power + ---- + + *TuneD* will try to set EPB to 'powersave'. If that fails, it will + try to set it to 'power'. + ==== + + `latency_low, latency_high, load_threshold`::: + + + If the CPU load is lower than the value specified by + the[option]`load_threshold` option, the latency is set to the value + specified either by the [option]`latency_high` option or by the + [option]`latency_low` option. + + + `force_latency`::: + You can also force the latency to a specific value and prevent it from + dynamically changing further. To do so, set the [option]`force_latency` + option to the required latency value. + + + The maximum latency value can be specified in several ways: + + + * by a numerical value in microseconds (for example, `force_latency=10`) + * as the kernel CPU idle level ID of the maximum C-state allowed + (for example, force_latency = cstate.id:1) + * as a case sensitive name of the maximum C-state allowed + (for example, force_latency = cstate.name:C1) + * by using 'None' as a fallback value to prevent errors when alternative + C-state IDs/names do not exist. When 'None' is used in the alternatives + pipeline, all the alternatives that follow 'None' are ignored. + + + It is also possible to specify multiple fallback values separated by '|' as + the C-state names and/or IDs may not be available on some systems. + + + .Specifying fallback C-state values + ==== + ---- + [cpu] + force_latency=cstate.name:C6|cstate.id:4|10 + ---- + This configuration tries to obtain and set the latency of C-state named C6. + If the C-state C6 does not exist, kernel CPU idle level ID 4 (state4) latency + is searched for in sysfs. Finally, if the state4 directory in sysfs is not found, + the last latency fallback value is `10` us. The value is encoded and written into + the kernel's PM QoS file `/dev/cpu_dma_latency`. + ==== + + + .Specifying fallback C-state values using 'None'. + ==== + ---- + [cpu] + force_latency=cstate.name:XYZ|None + ---- + In this case, if C-state with the name `XYZ` does not exist + [option]`force_latency`, no latency value will be written into the + kernel's PM QoS file, and no errors will be reported due to the + presence of 'None'. + ==== + + `min_perf_pct, max_perf_pct, no_turbo`::: + These options set the internals of the Intel P-State driver exposed via the kernel's + `sysfs` interface. + + + .Adjusting the configuration of the Intel P-State driver + ==== + ---- + [cpu] + min_perf_pct=100 + ---- + Limit the minimum P-State that will be requested by the driver. It states + it as a percentage of the max (non-turbo) performance level. + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_disk.py b/tuned/plugins/plugin_disk.py index a5a855e..ffeb8ee 100644 --- a/tuned/plugins/plugin_disk.py +++ b/tuned/plugins/plugin_disk.py @@ -11,7 +11,78 @@ log = tuned.logs.get() class DiskPlugin(hotplug.Plugin): """ - Plugin for tuning options of disks. + `disk`:: + + Plug-in for tuning various block device options. This plug-in can also + dynamically change the advanced power management and spindown timeout + setting for a drive according to the current drive utilization. The + dynamic tuning is controlled by the [option]`dynamic` and the global + [option]`dynamic_tuning` option in `tuned-main.conf`. + + + The disk plug-in operates on all supported block devices unless a + comma separated list of [option]`devices` is passed to it. + + + .Operate only on the sda block device + ==== + ---- + [disk] + # Comma separated list of devices, all devices if commented out. + devices=sda + ---- + ==== + + + The [option]`elevator` option sets the Linux I/O scheduler. + + + .Use the bfq I/O scheduler on xvda block device + ==== + ---- + [disk] + device=xvda + elevator=bfq + ---- + ==== + + + The [option]`scheduler_quantum` option only applies to the CFQ I/O + scheduler. It defines the number of I/O requests that CFQ sends to + one device at one time, essentially limiting queue depth. The default + value is 8 requests. The device being used may support greater queue + depth, but increasing the value of quantum will also increase latency, + especially for large sequential write work loads. + + + The [option]`apm` option sets the Advanced Power Management feature + on drives that support it. It corresponds to using the `-B` option of + the `hdparm` utility. The [option]`spindown` option puts the drive + into idle (low-power) mode, and also sets the standby (spindown) + timeout for the drive. It corresponds to using `-S` option of the + `hdparm` utility. + + + .Use a medium-agressive power management with spindown + ==== + ---- + [disk] + apm=128 + spindown=6 + ---- + ==== + + + The [option]`readahead` option controls how much extra data the + operating system reads from disk when performing sequential + I/O operations. Increasing the `readahead` value might improve + performance in application environments where sequential reading of + large files takes place. The default unit for readahead is KiB. This + can be adjusted to sectors by specifying the suffix 's'. If the + suffix is specified, there must be at least one space between the + number and suffix (for example, `readahead=8192 s`). + + + .Set the `readahead` to 4MB unless already set to a higher value + ==== + ---- + [disk] + readahead=>4096 + ---- + ==== + The disk readahead value can be multiplied by the constant + specified by the [option]`readahead_multiply` option. """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_eeepc_she.py b/tuned/plugins/plugin_eeepc_she.py index 3733a81..7d5c56f 100644 --- a/tuned/plugins/plugin_eeepc_she.py +++ b/tuned/plugins/plugin_eeepc_she.py @@ -8,7 +8,23 @@ log = tuned.logs.get() class EeePCSHEPlugin(base.Plugin): """ - Plugin for tuning FSB (front side bus) speed on Asus EEE PCs with SHE (Super Hybrid Engine) support. + `eeepc_she`:: + + Dynamically sets the front-side bus (FSB) speed according to the + CPU load. This feature can be found on some netbooks and is also + known as the Asus Super Hybrid Engine. If the CPU load is lower or + equal to the value specified by the [option]`load_threshold_powersave` + option, the plug-in sets the FSB speed to the value specified by the + [option]`she_powersave` option. If the CPU load is higher or + equal to the value specified by the [option]`load_threshold_normal` + option, it sets the FSB speed to the value specified by the + [option]`she_normal` option. Static tuning is not supported and the + plug-in is transparently disabled if the hardware support for this + feature is not detected. + + NOTE: For details about the FSB frequencies and corresponding values, see + link:https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-platform-eeepc-laptop[the kernel documentation]. + The provided defaults should work for most users. """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_irqbalance.py b/tuned/plugins/plugin_irqbalance.py index 5bcffac..d8e9e59 100644 --- a/tuned/plugins/plugin_irqbalance.py +++ b/tuned/plugins/plugin_irqbalance.py @@ -10,7 +10,23 @@ log = tuned.logs.get() class IrqbalancePlugin(base.Plugin): """ - Plugin for irqbalance settings management. + `irqbalance`:: + + Plug-in for irqbalance settings management. The plug-in + configures CPUs which should be skipped when rebalancing IRQs in + `/etc/sysconfig/irqbalance`. It then restarts irqbalance if and + only if it was previously running. + + + The banned/skipped CPUs are specified as a CPU list via the + [option]`banned_cpus` option. + + + .Skip CPUs 2,4 and 9-13 when rebalancing IRQs + ==== + ---- + [irqbalance] + banned_cpus=2,4,9-13 + ---- + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_modules.py b/tuned/plugins/plugin_modules.py index 369c2ce..2de46a0 100644 --- a/tuned/plugins/plugin_modules.py +++ b/tuned/plugins/plugin_modules.py @@ -11,7 +11,41 @@ log = tuned.logs.get() class ModulesPlugin(base.Plugin): """ - Plugin for applying custom kernel modules options. + `modules`:: + + Plug-in for applying custom kernel modules options. + + + This plug-in can set parameters to kernel modules. It creates + `/etc/modprobe.d/tuned.conf` file. The syntax is + `_module_=_option1=value1 option2=value2..._` where `_module_` is + the module name and `_optionx=valuex_` are module options which may + or may not be present. + + + .Load module `netrom` with module parameter `nr_ndevs=2` + ==== + ---- + [modules] + netrom=nr_ndevs=2 + ---- + ==== + Modules can also be forced to load/reload by using an additional + `+r` option prefix. + + + .(Re)load module `netrom` with module parameter `nr_ndevs=2` + ==== + ---- + [modules] + netrom=+r nr_ndevs=2 + ---- + ==== + The `+r` switch will also cause *TuneD* to try and remove `netrom` + module (if loaded) and try and (re)insert it with the specified + parameters. The `+r` can be followed by an optional comma (`+r,`) + for better readability. + + + When using `+r` the module will be loaded immediately by the *TuneD* + daemon itself rather than waiting for the OS to load it with the + specified parameters. """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_mounts.py b/tuned/plugins/plugin_mounts.py index 7109427..e64111c 100644 --- a/tuned/plugins/plugin_mounts.py +++ b/tuned/plugins/plugin_mounts.py @@ -11,7 +11,13 @@ cmd = commands() class MountsPlugin(base.Plugin): """ - Plugin for tuning options of mount-points. + `mounts`:: + + Enables or disables barriers for mounts according to the value of the + [option]`disable_barriers` option. The [option]`disable_barriers` + option has an optional value `force` which disables barriers even + on mountpoints with write back caches. Note that only extended file + systems (ext) are supported by this plug-in. """ @classmethod diff --git a/tuned/plugins/plugin_net.py b/tuned/plugins/plugin_net.py index f360d75..687afb8 100644 --- a/tuned/plugins/plugin_net.py +++ b/tuned/plugins/plugin_net.py @@ -13,7 +13,142 @@ WOL_VALUES = "pumbagsd" class NetTuningPlugin(base.Plugin): """ - Plugin for ethernet card options tuning. + `net`:: + + Configures network driver, hardware and Netfilter settings. + Dynamic change of the interface speed according to the interface + utilization is also supported. The dynamic tuning is controlled by + the [option]`dynamic` and the global [option]`dynamic_tuning` + option in `tuned-main.conf`. + + + The [option]`wake_on_lan` option sets wake-on-lan to the specified + value as when using the `ethtool` utility. + + + .Set Wake-on-LAN for device eth0 on MagicPacket(TM) + ==== + ---- + [net] + devices=eth0 + wake_on_lan=g + ---- + ==== + + + The [option]`coalesce` option allows changing coalescing settings + for the specified network devices. The syntax is: + + + [subs="+quotes,+macros"] + ---- + coalesce=__param1__ __value1__ __param2__ __value2__ ... __paramN__ __valueN__ + ---- + Note that not all the coalescing parameters are supported by all + network cards. For the list of coalescing parameters of your network + device, use `ethtool -c device`. + + + .Setting coalescing parameters rx/tx-usecs for all network devices + ==== + ---- + [net] + coalesce=rx-usecs 3 tx-usecs 16 + ---- + ==== + + + The [option]`features` option allows changing + the offload parameters and other features for the specified + network devices. To query the features of your network device, + use `ethtool -k device`. The syntax of the option is the same as + the [option]`coalesce` option. + + + .Turn off TX checksumming, generic segmentation and receive offload + ==== + ---- + [net] + features=tx off gso off gro off + ---- + ==== + The [option]`pause` option allows changing the pause parameters for + the specified network devices. To query the pause parameters of your + network device, use `ethtool -a device`. The syntax of the option + is the same as the [option]`coalesce` option. + + + .Disable autonegotiation + ==== + ---- + [net] + pause=autoneg off + ---- + ==== + + + The [option]`ring` option allows changing the rx/tx ring parameters + for the specified network devices. To query the ring parameters of your + network device, use `ethtool -g device`. The syntax of the option + is the same as the [option]`coalesce` option. + + + .Change the number of ring entries for the Rx/Tx rings to 1024/512 respectively + ===== + ----- + [net] + ring=rx 1024 tx 512 + ----- + ===== + + + The [option]`channels` option allows changing the numbers of channels + for the specified network device. A channel is an IRQ and the set + of queues that can trigger that IRQ. To query the channels parameters of your + network device, use `ethtool -l device`. The syntax of the option + is the same as the [option]`coalesce` option. + + + .Set the number of multi-purpose channels to 16 + ===== + ----- + [net] + channels=combined 16 + ----- + ===== + + + A network device either supports rx/tx or combined queue + mode. The [option]`channels` option automatically adjusts the + parameters based on the mode supported by the device as long as a + valid configuration is requested. + + + The [option]`nf_conntrack_hashsize` option sets the size of the hash + table which stores lists of conntrack entries by writing to + `/sys/module/nf_conntrack/parameters/hashsize`. + + + .Adjust the size of the conntrack hash table + ==== + ---- + [net] + nf_conntrack_hashsize=131072 + ---- + ==== + + + The [option]`txqueuelen` option allows changing txqueuelen (the length + of the transmit queue). It uses `ip` utility that is in package iproute + recommended for TuneD, so the package needs to be installed for its correct + functionality. To query the txqueuelen parameters of your network device + use `ip link show` and the current value is shown after the qlen column. + + + .Adjust the length of the transmit queue + ==== + ---- + [net] + txqueuelen=5000 + ---- + ==== + + + The [option]`mtu` option allows changing MTU (Maximum Transmission Unit). + It uses `ip` utility that is in package iproute recommended for TuneD, so + the package needs to be installed for its correct functionality. To query + the MTU parameters of your network device use `ip link show` and the + current value is shown after the MTU column. + + + .Adjust the size of the MTU + ==== + ---- + [net] + mtu=9000 + ---- + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_rtentsk.py b/tuned/plugins/plugin_rtentsk.py index 22d873f..31e2167 100644 --- a/tuned/plugins/plugin_rtentsk.py +++ b/tuned/plugins/plugin_rtentsk.py @@ -10,6 +10,8 @@ log = tuned.logs.get() class RTENTSKPlugin(base.Plugin): """ + `rtentsk`:: + Plugin for avoiding interruptions due to static key IPIs due to opening socket with timestamping enabled (by opening a socket ourselves the static key is kept enabled). diff --git a/tuned/plugins/plugin_scheduler.py b/tuned/plugins/plugin_scheduler.py index 739744b..672fdb1 100644 --- a/tuned/plugins/plugin_scheduler.py +++ b/tuned/plugins/plugin_scheduler.py @@ -136,8 +136,292 @@ class SchedulerUtilsSchedutils(SchedulerUtils): class SchedulerPlugin(base.Plugin): """ - Plugin for tuning of scheduler. Currently it can control scheduling - priorities of system threads (it is substitution for the rtctl tool). + `scheduler`:: + + Allows tuning of scheduling priorities, process/thread/IRQ + affinities, and CPU isolation. + + + To prevent processes/threads/IRQs from using certain CPUs, use + the [option]`isolated_cores` option. It changes process/thread + affinities, IRQs affinities and it sets `default_smp_affinity` + for IRQs. The CPU affinity mask is adjusted for all processes and + threads matching [option]`ps_whitelist` option subject to success + of the `sched_setaffinity()` system call. The default setting of + the [option]`ps_whitelist` regular expression is `.*` to match all + processes and thread names. To exclude certain processes and threads + use [option]`ps_blacklist` option. The value of this option is also + interpreted as a regular expression and process/thread names (`ps -eo + cmd`) are matched against that expression. Profile rollback allows + all matching processes and threads to run on all CPUs and restores + the IRQ settings prior to the profile application. + + + Multiple regular expressions for [option]`ps_whitelist` + and [option]`ps_blacklist` options are allowed and separated by + `;`. Quoted semicolon `\;` is taken literally. + + + .Isolate CPUs 2-4 + ==== + ---- + [scheduler] + isolated_cores=2-4 + ps_blacklist=.*pmd.*;.*PMD.*;^DPDK;.*qemu-kvm.* + ---- + Isolate CPUs 2-4 while ignoring processes and threads matching + `ps_blacklist` regular expressions. + ==== + The [option]`default_irq_smp_affinity` option controls the values + *TuneD* writes to `/proc/irq/default_smp_affinity`. The file specifies + default affinity mask that applies to all non-active IRQs. Once an + IRQ is allocated/activated its affinity bitmask will be set to the + default mask. + + + The following values are supported: + + + -- + `calc`:: + Content of `/proc/irq/default_smp_affinity` will be calculated + from the `isolated_cores` parameter. Non-isolated cores + are calculated as an inversion of the `isolated_cores`. Then + the intersection of the non-isolated cores and the previous + content of `/proc/irq/default_smp_affinity` is written to + `/proc/irq/default_smp_affinity`. If the intersection is + an empty set, then just the non-isolated cores are written to + `/proc/irq/default_smp_affinity`. This behavior is the default if + the parameter `default_irq_smp_affinity` is omitted. + `ignore`:: + *TuneD* will not touch `/proc/irq/default_smp_affinity`. + explicit cpulist:: + The cpulist (such as 1,3-4) is unpacked and written directly to + `/proc/irq/default_smp_affinity`. + -- + + + .An explicit CPU list to set the default IRQ smp affinity to CPUs 0 and 2 + ==== + ---- + [scheduler] + isolated_cores=1,3 + default_irq_smp_affinity=0,2 + ---- + ==== + To adjust scheduling policy, priority and affinity for a group of + processes/threads, use the following syntax. + + + [subs="+quotes,+macros"] + ---- + group.__groupname__=__rule_prio__:__sched__:__prio__:__affinity__:__regex__ + ---- + + + where `__rule_prio__` defines internal *TuneD* priority of the + rule. Rules are sorted based on priority. This is needed for + inheritence to be able to reorder previously defined rules. Equal + `__rule_prio__` rules should be processed in the order they were + defined. However, this is Python interpreter dependant. To disable + an inherited rule for `__groupname__` use: + + + [subs="+quotes,+macros"] + ---- + group.__groupname__= + ---- + + + `__sched__` must be one of: + *`f`* for FIFO, + *`b`* for batch, + *`r`* for round robin, + *`o`* for other, + *`*`* do not change. + + + `__affinity__` is CPU affinity in hexadecimal. Use `*` for no change. + + + `__prio__` scheduling priority (see `chrt -m`). + + + `__regex__` is Python regular expression. It is matched against the output of + + + [subs="+quotes,+macros"] + ---- + ps -eo cmd + ---- + + + Any given process name may match more than one group. In such a case, + the priority and scheduling policy are taken from the last matching + `__regex__`. + + + .Setting scheduling policy and priorities to kernel threads and watchdog + ==== + ---- + [scheduler] + group.kthreads=0:*:1:*:\[.*\]$ + group.watchdog=0:f:99:*:\[watchdog.*\] + ---- + ==== + + + The scheduler plug-in uses perf event loop to catch newly created + processes. By default it listens to `perf.RECORD_COMM` and + `perf.RECORD_EXIT` events. By setting [option]`perf_process_fork` + option to `true`, `perf.RECORD_FORK` events will be also listened + to. In other words, child processes created by the `fork()` system + call will be processed. Since child processes inherit CPU affinity + from their parents, the scheduler plug-in usually does not need to + explicitly process these events. As processing perf events can + pose a significant CPU overhead, the [option]`perf_process_fork` + option parameter is set to `false` by default. Due to this, child + processes are not processed by the scheduler plug-in. + + + The CPU overhead of the scheduler plugin can be mitigated by using + the scheduler [option]`runtime` option and setting it to `0`. This + will completely disable the dynamic scheduler functionality and the + perf events will not be monitored and acted upon. The disadvantage + ot this approach is the procees/thread tuning will be done only at + profile application. + + + .Disabling the scheduler dynamic functionality + ==== + ---- + [scheduler] + runtime=0 + isolated_cores=1,3 + ---- + ==== + + + NOTE: For perf events, memory mapped buffer is used. Under heavy load + the buffer may overflow. In such cases the `scheduler` plug-in + may start missing events and failing to process some newly created + processes. Increasing the buffer size may help. The buffer size can + be set with the [option]`perf_mmap_pages` option. The value of this + parameter has to expressed in powers of 2. If it is not the power + of 2, the nearest higher power of 2 value is calculated from it + and this calculated value used. If the [option]`perf_mmap_pages` + option is omitted, the default kernel value is used. + + + The scheduler plug-in supports process/thread confinement using + cgroups v1. + + + [option]`cgroup_mount_point` option specifies the path to mount the + cgroup filesystem or where *TuneD* expects it to be mounted. If unset, + `/sys/fs/cgroup/cpuset` is expected. + + + If [option]`cgroup_groups_init` option is set to `1` *TuneD* + will create (and remove) all cgroups defined with the `cgroup*` + options. This is the default behavior. If it is set to `0` the + cgroups need to be preset by other means. + + + If [option]`cgroup_mount_point_init` option is set to `1`, + *TuneD* will create (and remove) the cgroup mountpoint. It implies + `cgroup_groups_init = 1`. If set to `0` the cgroups mount point + needs to be preset by other means. This is the default behavior. + + + The [option]`cgroup_for_isolated_cores` option is the cgroup + name used for the [option]`isolated_cores` option functionality. For + example, if a system has 4 CPUs, `isolated_cores=1` means that all + processes/threads will be moved to CPUs 0,2-3. + The scheduler plug-in will isolate the specified core by writing + the calculated CPU affinity to the `cpuset.cpus` control file of + the specified cgroup and move all the matching processes/threads to + this group. If this option is unset, classic cpuset affinity using + `sched_setaffinity()` will be used. + + + [option]`cgroup.__cgroup_name__` option defines affinities for + arbitrary cgroups. Even hierarchic cgroups can be used, but the + hieararchy needs to be specified in the correct order. Also *TuneD* + does not do any sanity checks here, with the exception that it forces + the cgroup to be under [option]`cgroup_mount_point`. + + + The syntax of the scheduler option starting with `group.` has been + augmented to use `cgroup.__cgroup_name__` instead of the hexadecimal + `__affinity__`. The matching processes will be moved to the cgroup + `__cgroup_name__`. It is also possible to use cgroups which have + not been defined by the [option]`cgroup.` option as described above, + i.e. cgroups not managed by *TuneD*. + + + All cgroup names are sanitized by replacing all all dots (`.`) with + slashes (`/`). This is to prevent the plug-in from writing outside + [option]`cgroup_mount_point`. + + + .Using cgroups v1 with the scheduler plug-in + ==== + ---- + [scheduler] + cgroup_mount_point=/sys/fs/cgroup/cpuset + cgroup_mount_point_init=1 + cgroup_groups_init=1 + cgroup_for_isolated_cores=group + cgroup.group1=2 + cgroup.group2=0,2 + + group.ksoftirqd=0:f:2:cgroup.group1:ksoftirqd.* + ps_blacklist=ksoftirqd.*;rcuc.*;rcub.*;ktimersoftd.* + isolated_cores=1 + ---- + Cgroup `group1` has the affinity set to CPU 2 and the cgroup `group2` + to CPUs 0,2. Given a 4 CPU setup, the [option]`isolated_cores=1` + option causes all processes/threads to be moved to CPU + cores 0,2-3. Processes/threads that are blacklisted by the + [option]`ps_blacklist` regular expression will not be moved. + + The scheduler plug-in will isolate the specified core by writing the + CPU affinity 0,2-3 to the `cpuset.cpus` control file of the `group` + and move all the matching processes/threads to this cgroup. + ==== + Option [option]`cgroup_ps_blacklist` allows excluding processes + which belong to the blacklisted cgroups. The regular expression specified + by this option is matched against cgroup hierarchies from + `/proc/PID/cgroups`. Cgroups v1 hierarchies from `/proc/PID/cgroups` + are separated by commas ',' prior to regular expression matching. The + following is an example of content against which the regular expression + is matched against: `10:hugetlb:/,9:perf_event:/,8:blkio:/` + + + Multiple regular expressions can be separated by semicolon ';'. The + semicolon represents a logical 'or' operator. + + + .Cgroup-based exclusion of processes from the scheduler + ==== + ---- + [scheduler] + isolated_cores=1 + cgroup_ps_blacklist=:/daemons\b + ---- + + The scheduler plug-in will move all processes away from core 1 except processes which + belong to cgroup '/daemons'. The '\b' is a regular expression + metacharacter that matches a word boundary. + + ---- + [scheduler] + isolated_cores=1 + cgroup_ps_blacklist=\b8:blkio: + ---- + + The scheduler plug-in will exclude all processes which belong to a cgroup + with hierarchy-ID 8 and controller-list blkio. + ==== + Recent kernels moved some `sched_` and `numa_balancing_` kernel run-time + parameters from `/proc/sys/kernel`, managed by the `sysctl` utility, to + `debugfs`, typically mounted under `/sys/kernel/debug`. TuneD provides an + abstraction mechanism for the following parameters via the scheduler plug-in: + [option]`sched_min_granularity_ns`, [option]`sched_latency_ns`, + [option]`sched_wakeup_granularity_ns`, [option]`sched_tunable_scaling`, + [option]`sched_migration_cost_ns`, [option]`sched_nr_migrate`, + [option]`numa_balancing_scan_delay_ms`, + [option]`numa_balancing_scan_period_min_ms`, + [option]`numa_balancing_scan_period_max_ms` and + [option]`numa_balancing_scan_size_mb`. + Based on the kernel used, TuneD will write the specified value to the correct + location. + + + .Set tasks' "cache hot" value for migration decisions. + ==== + ---- + [scheduler] + sched_migration_cost_ns=500000 + ---- + On the old kernels, this is equivalent to: + ---- + [sysctl] + kernel.sched_migration_cost_ns=500000 + ---- + that is, value `500000` will be written to `/proc/sys/kernel/sched_migration_cost_ns`. + However, on more recent kernels, the value `500000` will be written to + `/sys/kernel/debug/sched/migration_cost_ns`. + ==== """ def __init__(self, monitor_repository, storage_factory, hardware_inventory, device_matcher, device_matcher_udev, plugin_instance_factory, global_cfg, variables): diff --git a/tuned/plugins/plugin_script.py b/tuned/plugins/plugin_script.py index 19b7fc6..e3dda67 100644 --- a/tuned/plugins/plugin_script.py +++ b/tuned/plugins/plugin_script.py @@ -8,7 +8,47 @@ log = tuned.logs.get() class ScriptPlugin(base.Plugin): """ - Plugin for running custom scripts with profile activation and deactivation. + `script`:: + + Executes an external script or binary when the profile is loaded or + unloaded. You can choose an arbitrary executable. + + + IMPORTANT: The `script` plug-in is provided mainly for compatibility + with earlier releases. Prefer other *TuneD* plug-ins if they cover + the required functionality. + + + *TuneD* calls the executable with one of the following arguments: + + + -- + ** `start` when loading the profile + ** `stop` when unloading the profile + -- + + + You need to correctly implement the `stop` action in your executable + and revert all settings that you changed during the `start` + action. Otherwise, the roll-back step after changing your *TuneD* + profile will not work. + + + Bash scripts can import the [filename]`/usr/lib/tuned/functions` + Bash library and use the functions defined there. Use these + functions only for functionality that is not natively provided + by *TuneD*. If a function name starts with an underscore, such as + `_wifi_set_power_level`, consider the function private and do not + use it in your scripts, because it might change in the future. + + + Specify the path to the executable using the `script` parameter in + the plug-in configuration. + + + .Running a Bash script from a profile + ==== + To run a Bash script named `script.sh` that is located in the profile + directory, use: + + ---- + [script] + script=${i:PROFILE_DIR}/script.sh + ---- + ==== """ @classmethod diff --git a/tuned/plugins/plugin_scsi_host.py b/tuned/plugins/plugin_scsi_host.py index 89366ec..2a087de 100644 --- a/tuned/plugins/plugin_scsi_host.py +++ b/tuned/plugins/plugin_scsi_host.py @@ -11,7 +11,24 @@ log = tuned.logs.get() class SCSIHostPlugin(hotplug.Plugin): """ - Plugin for tuning options of SCSI hosts. + `scsi_host`:: + + Tunes options for SCSI hosts. + + + The plug-in sets Aggressive Link Power Management (ALPM) to the value specified + by the [option]`alpm` option. The option takes one of three values: + `min_power`, `medium_power` and `max_performance`. + + + NOTE: ALPM is only available on SATA controllers that use the Advanced + Host Controller Interface (AHCI). + + + .ALPM setting when extended periods of idle time are expected + ==== + ---- + [scsi_host] + alpm=min_power + ---- + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_selinux.py b/tuned/plugins/plugin_selinux.py index b244d3c..c228f6c 100644 --- a/tuned/plugins/plugin_selinux.py +++ b/tuned/plugins/plugin_selinux.py @@ -9,7 +9,27 @@ log = tuned.logs.get() class SelinuxPlugin(base.Plugin): """ - Plugin for tuning SELinux options. + `selinux`:: + + Plug-in for tuning SELinux options. + + + SELinux decisions, such as allowing or denying access, are + cached. This cache is known as the Access Vector Cache (AVC). When + using these cached decisions, SELinux policy rules need to be checked + less, which increases performance. The [option]`avc_cache_threshold` + option allows adjusting the maximum number of AVC entries. + + + NOTE: Prior to changing the default value, evaluate the system + performance with care. Increasing the value could potentially + decrease the performance by making AVC slow. + + + .Increase the AVC cache threshold for hosts with containers. + ==== + ---- + [selinux] + avc_cache_threshold=8192 + ---- + ==== """ @classmethod diff --git a/tuned/plugins/plugin_service.py b/tuned/plugins/plugin_service.py index bad3bb3..5f2b23c 100644 --- a/tuned/plugins/plugin_service.py +++ b/tuned/plugins/plugin_service.py @@ -170,7 +170,44 @@ class SystemdHandler(InitHandler): class ServicePlugin(base.Plugin): """ - Plugin for handling sysvinit, openrc, and systemd services. + `service`:: + + Plug-in for handling sysvinit, sysv-rc, openrc and systemd services. + + + The syntax is as follows: + + + [subs="+quotes,+macros"] + ---- + [service] + service.__service_name__=__commands__[,file:__file__] + ---- + + + Supported service-handling `_commands_` are `start`, `stop`, `enable` + and `disable`. The optional `file:__file__` directive installs an overlay + configuration file `__file__`. Multiple commands must be comma (`,`) + or semicolon (`;`) separated. If the directives conflict, the last + one is used. + + + The service plugin supports configuration overlays only for systemd. + In other init systems, this directive is ignored. The configuration + overlay files are copied to `/etc/systemd/system/__service_name__.service.d/` + directories. Upon profile unloading, the directory is removed if it is empty. + + + With systemd, the `start` command is implemented by `restart` in order + to allow loading of the service configuration file overlay. + + + NOTE: With non-systemd init systems, the plug-in operates on the + current runlevel only. + + + .Start and enable the `sendmail` service with an overlay file + ==== + ---- + [service] + service.sendmail=start,enable,file:${i:PROFILE_DIR}/tuned-sendmail.conf + ---- + The internal variable `${i:PROFILE_DIR}` points to the directory + from which the profile is loaded. + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_sysctl.py b/tuned/plugins/plugin_sysctl.py index ee7596d..0272d95 100644 --- a/tuned/plugins/plugin_sysctl.py +++ b/tuned/plugins/plugin_sysctl.py @@ -16,7 +16,27 @@ SYSCTL_CONFIG_DIRS = [ "/run/sysctl.d", class SysctlPlugin(base.Plugin): """ - Plugin for applying custom sysctl options. + `sysctl`:: + + Sets various kernel parameters at runtime. + + + This plug-in is used for applying custom `sysctl` settings and should + only be used to change system settings that are not covered by other + *TuneD* plug-ins. If the settings are covered by other *TuneD* plug-ins, + use those plug-ins instead. + + + The syntax for this plug-in is + `_key_=_value_`, where + `_key_` is the same as the key name provided by the + `sysctl` utility. + + + .Adjusting the kernel runtime kernel.sched_min_granularity_ns value + ==== + ---- + [sysctl] + kernel.sched_min_granularity_ns=3000000 + ---- + ==== """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_sysfs.py b/tuned/plugins/plugin_sysfs.py index 6c6cc66..8bff0ad 100644 --- a/tuned/plugins/plugin_sysfs.py +++ b/tuned/plugins/plugin_sysfs.py @@ -11,7 +11,26 @@ log = tuned.logs.get() class SysfsPlugin(base.Plugin): """ - Plugin for applying custom sysfs options, using specific plugins is preferred. + `sysfs`:: + + Sets various `sysfs` settings specified by the plug-in options. + + + The syntax is `_name_=_value_`, where + `_name_` is the `sysfs` path to use and `_value_` is + the value to write. The `sysfs` path supports the shell-style + wildcard characters (see `man 7 glob` for additional detail). + + + Use this plugin in case you need to change some settings that are + not covered by other plug-ins. Prefer specific plug-ins if they + cover the required settings. + + + .Ignore corrected errors and associated scans that cause latency spikes + ==== + ---- + [sysfs] + /sys/devices/system/machinecheck/machinecheck*/ignore_ce=1 + ---- + ==== """ # TODO: resolve possible conflicts with sysctl settings from other plugins diff --git a/tuned/plugins/plugin_systemd.py b/tuned/plugins/plugin_systemd.py index af26803..ecd8358 100644 --- a/tuned/plugins/plugin_systemd.py +++ b/tuned/plugins/plugin_systemd.py @@ -12,9 +12,25 @@ log = tuned.logs.get() class SystemdPlugin(base.Plugin): """ - Plugin for tuning systemd options. - - These tunings are unloaded only on profile change followed by reboot. + `systemd`:: + + Plug-in for tuning systemd options. + + + The [option]`cpu_affinity` option allows setting CPUAffinity in + `/etc/systemd/system.conf`. This configures the CPU affinity for the + service manager as well as the default CPU affinity for all forked + off processes. The option takes a comma-separated list of CPUs with + optional CPU ranges specified by the minus sign (`-`). + + + .Set the CPUAffinity for `systemd` to `0 1 2 3` + ==== + ---- + [systemd] + cpu_affinity=0-3 + ---- + ==== + + + NOTE: These tunings are unloaded only on profile change followed by a reboot. """ def __init__(self, *args, **kwargs): diff --git a/tuned/plugins/plugin_usb.py b/tuned/plugins/plugin_usb.py index 23d9bbd..536a2f2 100644 --- a/tuned/plugins/plugin_usb.py +++ b/tuned/plugins/plugin_usb.py @@ -8,7 +8,23 @@ log = tuned.logs.get() class USBPlugin(base.Plugin): """ - Plugin for tuning various options of USB subsystem. + `usb`:: + + Sets autosuspend timeout of USB devices to the value specified by the + [option]`autosuspend` option in seconds. If the [option]`devices` + option is specified, the [option]`autosuspend` option applies to only + the USB devices specified, otherwise it applies to all USB devices. + + + The value `0` means that autosuspend is disabled. + + + .To turn off USB autosuspend for USB devices `1-1` and `1-2` + ==== + ---- + [usb] + devices=1-1,1-2 + autosuspend=0 + ---- + ==== """ def _init_devices(self): diff --git a/tuned/plugins/plugin_video.py b/tuned/plugins/plugin_video.py index d87a920..e955ad9 100644 --- a/tuned/plugins/plugin_video.py +++ b/tuned/plugins/plugin_video.py @@ -9,7 +9,36 @@ log = tuned.logs.get() class VideoPlugin(base.Plugin): """ - Plugin for tuning powersave options for some graphic cards. + `video`:: + + Sets various powersave levels on video cards. Currently, only the + Radeon cards are supported. The powersave level can be specified + by using the [option]`radeon_powersave` option. Supported values are: + + + -- + * `default` + * `auto` + * `low` + * `mid` + * `high` + * `dynpm` + * `dpm-battery` + * `dpm-balanced` + * `dpm-perfomance` + -- + + + For additional detail, see + link:https://www.x.org/wiki/RadeonFeature/#kmspowermanagementoptions[KMS Power Management Options]. + + + NOTE: This plug-in is experimental and the option might change in future releases. + + + .To set the powersave level for the Radeon video card to high + ==== + ---- + [video] + radeon_powersave=high + ---- + ==== """ def _init_devices(self): diff --git a/tuned/plugins/plugin_vm.py b/tuned/plugins/plugin_vm.py index 9021ac3..9b5e4f7 100644 --- a/tuned/plugins/plugin_vm.py +++ b/tuned/plugins/plugin_vm.py @@ -12,7 +12,25 @@ cmd = commands() class VMPlugin(base.Plugin): """ - Plugin for tuning memory management. + `vm`:: + + Enables or disables transparent huge pages depending on value of the + [option]`transparent_hugepages` option. The option can have one of three + possible values `always`, `madvise` and `never`. + + + .Disable transparent hugepages + ==== + ---- + [vm] + transparent_hugepages=never + ---- + ==== + + + The [option]`transparent_hugepage.defrag` option specifies the + defragmentation policy. Possible values for this option are `always`, + `defer`, `defer+madvise`, `madvise` and `never`. For a detailed + explanation of these values refer to + link:https://www.kernel.org/doc/Documentation/vm/transhuge.txt[Transparent Hugepage Support]. """ @classmethod @@ -48,7 +66,7 @@ class VMPlugin(base.Plugin): cmdline = cmd.read_file("/proc/cmdline", no_error = True) if cmdline.find("transparent_hugepage=") > 0: if not sim: - log.info("transparent_hugepage is already set in kernel boot cmdline, ingoring value from profile") + log.info("transparent_hugepage is already set in kernel boot cmdline, ignoring value from profile") return None sys_file = os.path.join(self._thp_path(), "enabled")