SUSE/saptune

.\"/* 
.\" * Copyright (c) 2018-2021 SUSE LLC.
.\" * All rights reserved
.\" * Authors: Angela Briel
.\" *
.\" * This program 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; either version 2
.\" * of the License, or (at your option) any later version.
.\" *
.\" * This program 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.
.\" */
.\" 

.TH "saptune-note" "5" "Januar 2023" "" "saptune note file format description"
.SH NAME
saptune\-note - Note definition files for saptune version \fB3\fP
.SH DESCRIPTION
This man page documents the format of the Note definition files for saptune version \fB3\fP. If you still use version \fB1\fP of saptune please refer to the configuration files \fI/etc/sysconfig/saptune-note-*\fP

The saptune Note definitions will be installed by the rpm in \fI/usr/share/saptune/notes\fP (the \fBpackage area\fP), but for the execution they will be searched in \fI/var/lib/saptune/working/notes\fP (the \fBworking area\fP) for the saptune SAP Note definitions or in \fI/etc/saptune/override\fP for customer specific changes to the saptune SAP Note definitions or in \fI/etc/saptune/extra\fP for vendor or customer specific tuning definitions.
.br
The \fBNote definition\fP files use the INI file format.
.br
A comment line starts with #.
.br
Inline comments are possible and start with a blank followed by a # followed by any non-# character. (' #anything except #')
.br
If you need to add a character sequenze of ' #anything' to your description, please write it as ' ##anything' (double the #) to give saptune the chance to distinguish this text from an inline comment. saptune will strip the second # from the output result, so that the resulting text will appear as ' #anything'.
.br
Lines starting with '[' indicate the begin of a new section.
.SH SECTIONS
A section starts with a '[section_name]' keyword in the first line, followed by lines with options and comments.

It is possible to limit the scope of a section (e.g. to a special \fIhardware architecture\fP and/or a special \fIos version\fP, a special \fIblock device hardware\fP or a \fIcloud service provider\fP) by adding \fBtags\fP to the section definition.
.br
Tags are separated by ':' and can appear in any order. Unsupported tags are considered an error and the whole section is ignored.
.br
For some tags the value of the tag is treated as a string and used as a regular expression to match the content of the respective source. This is mentioned in the description of the possible tags below. As a reference https://golang.org/pkg/regexp/#MatchString can be used to see, what additional expressions may be possible inside the tag value. But attention, only some basic ones are really supprted (like 'sd[ab]' for block devices).

Attention: as the IBM Power platform (hardware architecture 'ppc64le') does not support files in \fI/sys/class/dmi\fP (the directory is not available on this hardware architecture) some of the tags listed below are not usable on Power systems for now.

The \fBsyntax\fP for such sections is:

[section_name:[tag=value]...]

Supported tags are:
.TP
.BI os= <os_version>
to define a special \fIos version\fP
.br
Valid values for \fBos=\fP are the values from the \fBVERSION=\fP line of \fB/etc/os-release\fP, e.g. 12-SP5, 12, 15 or 15-SP1
.br
To mark an entire major release the string 12-* or 15-* can be used.
.TP
.BI arch= <hardware_architecture>
to define a special \fIhardware architecture\fP:
.br
Valid values for \fBarch=\fP are the output from \fBuname -i\fP

.RS 4
Example:
.br
[sysctl:os=15-SP1:arch=ppc64le]
.RE
.TP
.BI vendor= <hardware vendor>
to define a special \fIsystem hardware vendor\fP
.br
Valid values for \fBvendor=\fP are the values found in \fB/sys/class/dmi/id/board_vendor\fP or parts of the string available in this file.
.br
The value of the vendor tag is used as a regular expression '\fB.*<value>.*\fP' to match the content of the vendor file.

For IBM Power platform (hardware architecture 'ppc64le') the value is set to 'IBM'.

.TP
.BI model= <hardware model>
to define a special \fIsystem hardware model\fP
.br
Valid values for \fBmodel=\fP are the values found in \fB/sys/class/dmi/id/product_name\fP or parts of the string available in this file.
.br
The value of the model tag is used as a regular expression '\fB.*<value>.*\fP' to match the content of the model file.

On IBM Power platform (hardware architecture 'ppc64le') the file \fB/sys/firmware/devicetree/base/model\fP is used to identify the hardware model.

.RS 4
Example:
.br
[sysctl:vendor=FUJITSU:model=RX4770 M*]
.RE
.TP
.BI csp= <cloud service provider>
to define a special \fIcloud service provider\fP
.br
Valid values for \fBcsp=\fP are \fBazure\fP and \fBaws\fP

.RS 4
Example:
.br
[sysctl:csp=azure]
.RE
.TP
.BI DMI interface tag: <filename>= <file content>
.br
Additional every filename from \fI/sys/class/dmi/id/\fP can be used as a tag.
.br
This way it's possible to restrict a section to a special hardware vendor or hardware model regarding the bios, the chassis, the board or anything else provided by the DMI interface.
.br
The value of the DMI interface tag is used as a regular expression '\fB.*<value>.*\fP' to match the content of the file in \fI/sys/class/dmi/id/<filename>\fP.

Attention: if the pattern does not match any filename in \fI/sys/class/dmi/id\fP, the section will be skipped as unknown.

Attention: not usable on IBM Power platform (hardware architecture 'ppc64le')

.RS 4
Example:
.br
[sysctl:bios_vendor=Dell]
.RE

For the following 3 tags we have special rules:
.br
This tags have different effects regarding the section they are used. In all sections except the \fB[block]\fP section they are used the same way all other tags are used to restrict the section to be only valid on a system which includes this special sort of block device.
.br
But used in the \fB[block]\fP section they mean that all the settings available in this section will \fBonly\fP apply to block devices, which match the tag value. So you can restrict the settings to dedicated block devices.
.TP
.BI blkvendor= <block device hardware vendor>
to define a \fIhardware vendor\fP to match a special block device
.br
Valid values for \fBblkvendor=\fP are the values found in \fB/sys/block/<dev>/device/vendor\fP or parts of the string available in this file.
.br
The value of the blkvendor tag is used as a regular expression '\fB.*<value>.*\fP' to match the content of the vendor file.
.TP
.BI blkmodel= <block device hardware model>
to define a \fIhardware model\fP to match a special block device
.br
Valid values for \fBblkmodel=\fP are the values found in \fB/sys/block/<dev>/device/model\fP or parts of the string available in this file.
.br
The value of the blkmodel tag is used as a regular expression '\fB.*<value>.*\fP' to match the content of the model file.

Attention: if the tag does not match any block device, no block device will be handled by saptune. e.g. '\fBsaptune note verify\fP' will list NO block devices.

.RS 4
Example:
.br
[block:blkvendor=ATA]
.br
[block:blkmodel=QEMU HARDDISK]
.br
[block:blkvendor=FTS:blkmodel=PRAID EP420*]
.br
[block:blkvendor=FUJITSU:blkmodel=ETERNUS_]
.RE
.TP
.BI blkpat= <pattern>
to define a \fIpattern\fP to match a special block device in \fI/sys/block/\fP

Attention: if the pattern does not match any block device, no block device will be handled by saptune. e.g. '\fBsaptune note verify\fP' will list NO block device. There will be NO Warning or Error message logged in such a case.

.RS 4
example:
.br
[block:blkpat=nvme] to match all \fI/sys/block/nvme.*\fP block devices
.br
[block:blkpat=sd[ab]] to match \fI/sys/block/sda\fP and \fI/sys/block/sdb\fP
.RE


For processing a section the following rules apply:
.IP \[bu]
Only sections that match the system are processed. Sections without a tag are always used.
.IP \[bu]
The order of the section within the file matter. Eache section and each line in a section gets processed from top to down.
.RE

The rules apply for shipped Note definition files as well as for customer defined Note definition files. Tagged sections can be used in override files.

\fBATTENTION:\fP To be clear - if there are more sections with the \fBsame\fP \fIsection_name\fP containing the \fBsame\fP \fIparameters\fP with \fBdifferent\fP \fIvalues\fP, the last valid section will win.

So it's all about \fBorder\fP.

The following section definitions are available and used in the saptune SAP Note definition files. Each of these sections can be used in a vendor or customer specific Note definition file placed in \fI/etc/saptune/extra\fP.

List of supported sections:
.br
version, block, cpu, filesystem, grub, limits, login, mem, pagecache, reminder, rpm, service, sysctl, sys, vm

See detailed description below:
\" section version - Mandatory
.SH "[version]"
This section is a mandatory section and is used to display version, description and last change date of the underlying Note during saptune action 'list'.

Old Syntax: \fBATTENTION: deprecated\fP
.br
.nf
.B # <prefix>NOTE=<noteId> CATEGORY=<category> VERSION=<versionNo> DATE=<release date of used note and related values> NAME="<description of the note>"
.fi

Example:
.br
# VIP-NOTE=vip1 CATEGORY=VIP VERSION=5 DATE=16.04.2019 NAME="VIP: this is VIP Note 1, which contains Very Important Parameters"

All fields are separated by spaces. But please do not use spaces around the equal operator (=) of the fields. And please do not change the order of the fields.

The <noteId> must be a text string without spaces. It was planned for future use, but this field was never used.

The internal used NoteID - the unique identifier of a Note definition - was always taken from the filename of the Note definition file without extension '.conf'. It will be displayed during the action 'saptune note list' and used for all other actions, where the NoteID is needed as parameter.

The CATEGORY is for future use. So we do not have defined CATEGORIES at the moment. It must be a text string without spaces.

VERSION is a number that should indicate how many changes are done for this Note definition in the past. Allowed are digits, upper-case and lower-case letters, dots, underscores, minus and plus signs.

DATE is the date of the last changes.

NAME is the description of the Note, which will be displayed during the action 'saptune note list'
.br
Attention: The note description from the field NAME must be placed in double quotes even if there are no spaces used inside the description.

\fBATTENTION:\fP The old syntax for the version section is deprecated. A Warning message will point to the affected Note definition file. Customer specific Note definition files need to be adapted to the new syntax by the admin.

Only in the Solution definition files the old syntax is still valid. This may change with a next saptune version.

New Syntax:
.br
.nf
.B
VERSION=<versionNo>
.br
DATE=<release date of used note and related values>
.br
DESCRIPTION=<description of the note>
.br
REFERENCES=<list of URLs containing information regarding the Note separated by blank>

Example:
.br
VERSION=5
.br
DATE=16.04.2019
.br
DESCRIPTION=VIP: this is VIP Note 1, which contains Very Important Parameters
.br
REFERENCES=https://inter.net.addr.com/path/Note_Info http://inter.net.addr.com/another_path/A_second_Note_Info

The entries are treated as 'Key Value' pairs. The equal operator (=) is mandatory, but can be used with spaces around. The entries can be placed in any order inside the version section.

We skipped the fields 'CATEGORY' and '<noteId>' from the old syntax because these values are not in use. The '<noteId>' was always taken from the filename of the Note definition file and we stay with this behaviour for now.

\"The <noteId> must be a text string without spaces, which will be used as the unique identifier of this Note definition. It will be displayed during the action 'saptune note list' and used for all other actions, where the NoteID is needed as parameter.

VERSION is a number that should indicate how many changes are done for this Note definition in the past. Allowed are digits, upper-case and lower-case letters, dots, underscores, minus and plus signs.

DATE is the date of the last changes.

DESCRIPTION is the description of the Note, which will be displayed during the action 'saptune note list'.

REFERENCES is a list of URLs separated by blank, which contain additional information about the Note definition and the content. If you need to use a 'blank' inside the URL definition please mask it as '%20'.
\" section block
.SH "[block]"
The settings of the "[block]" section will be set on \fBall\fP block devices found in \fI/sys/block\fP, which are considered as \fBvalid\fP.

.RE
The following rules apply for \fBvalid\fP devices:
.IP \[bu]
all multipath devices (dm-*, if mpath-, but not LVM- or other dm-)
.IP \[bu]
all physical disks (indicated by device/type=0 or names like nvme*, vd*)
.br
\fBexcept\fP they are part of a device mapper construct (like mpath-).
.RE

The section "[block]" can contain the following options:
.TP
.BI IO_SCHEDULER= STRING
The default I/O scheduler for single-queued block layer devices offers satisfactory performance for wide range of I/O task, however choosing an alternative scheduler may potentially yield better latency characteristics and throughput.
"noop" is an alternative scheduler, in comparison to other schedulers it may offer more consistent performance, lower computation overhead, and potentially higher throughput.
For most SAP environments (RAID, storage arrays, virtualizaton) 'noop' is the better choice.
.br
With the new introduced multi-queue scheduler for block layer devices the recommended I/O scheduler is 'none' as an equivalent to 'noop' for single-queued block layer devices.

So IO_SCHEDULER can now contain a comma separated list of possible schedulers, which are checked from left to right. The first one which is available in \fI/sys/block/<device>/queue/scheduler\fP will be used as new scheduler setting for the respective block device.
.br
The selection per device is logged.
.br
When set, \fBall\fP block devices on the system will be switched to one of the chosen schedulers.
.br
Valid values can be found in \fI/sys/block/<device>/queue/scheduler\fP.
.TP
.BI NRREQ= INT
IO nr_requests specifies the maximum number of read and write requests that can be queued at one time. The default value is 128, which means that 128 read requests and 128 write requests can be queued before the next process to request a read or write is put to sleep.
.br
When set, the number of requests for \fBall\fP block devices on the system will be switched to the chosen value
.TP
.BI READ_AHEAD_KB= INT
disk readahead (queue/read_ahead_kb) defines the maximum number of kilobytes that the operating system may read ahead during a sequential read operation. As a result, the likely-needed information is already present within the kernel page cache for the next sequential read, which improves read I/O performance.
Device mappers often benefit from a high read_ahead_kb value.
Increasing the read_ahead_kb value might improve performance in environments where sequential reading of large files takes place.
.br
When set, the value of read_ahead_kb for \fBall\fP block devices on the system will be switched to the chosen value
.TP
.BI MAX_SECTORS_KB= INT
disk max_sectors_kb (queue/max_sectors_kb) defines the maximum number of kilobytes that the block layer will allow for a filesystem request. Must be smaller than or equal to the maximum size allowed by the hardware (queue/max_hw_sectors_kb).
.br
When set, the value of max_sectors_kb for \fBall\fP block devices on the system will be switched to the chosen value.
.br
If the value is higher than 'max_hw_sectors_kb' it will be limited to 'max_hw_sectors_kb' and a footnote is displayed.
\" section cpu
.SH "[cpu]"
The section "[cpu]" manipulates files in \fI/sys/devices/system/cpu/cpu*\fP.
.br
This section can only contain the following options:
.TP
.BI energy_perf_bias= STRING
Energy Performance Bias EPB (applies to Intel-based systems only)
.br
supported values are: \fBperformance\fP (0), \fBnormal\fP (6) and \fBpowersave\fP (15)
.br
The command 'cpupower set -b <value>' is used to set the value, if the system supports Intel's performance bias setting.
See cpupower(1) and cpupower-set(1) for more information.
.br
If system does not support Intel's performance bias setting - '\fBall:none\fP' is used in the column '\fIActual\fP' of the verify table and the \fIfootnote\fP '[1] setting is not supported by the system' is displayed.

When set as 'energy_perf_bias=<performance|normal|powersave> in the Note definition file, the value will be set for \fBall\fP available CPUs.
.br
The command '\fBcpupower -c all set -b <value>\fP' or '\fBcpupower -c <cpu> set -b <value>\fP' is used to set the value.
.TP
.BI governor= STRING
CPU Frequency/Voltage scaling (applies to Intel-based systems only)
.br
The clock frequency and voltage of modern CPUs can scale, in order to save energy when there's less work to be done. However HANA as a high-performance database benefits from high CPU frequencies.
.br
supported values are: \fBperformance\fP (0), \fBnormal\fP (6) and \fBpowersave\fP (15)
.br
The command 'cpupower frequency-set -g <value>' is used to set the value, if the value is a supported governor listed in \fI/sys/devices/system/cpu/cpu*/cpufreq/scaling_governor\fP'
See cpupower(1) and cpupower-frequency-set(1) for more information.
.br
If the governor settings of all available CPUs are equal, '\fBall:<governor>\fP' is used in the column '\fIActual\fP' of the verify table. If not, each CPU with its assigned governor is listed (e.g. cpu1:powersave cpu2:powersave cpu3:powersave cpu4:powersave cpu5:powersave cpu6:powersave cpu7:powersave cpu0:performance)

When set as 'governor=<performance|powersave> in the Note definition file, the value will be set for \fBall\fP available CPUs.
.br
The command '\fBcpupower -c all frequency-set -g <value>\fP' or '\fBcpupower -c <cpu> frequency-set -g <value>\fP' is used to set the value.
.TP
.BI force_latency= STRING
force latency - configure C-States for lower latency (applies to Intel-based systems only)
.br
Input is a string, which is internally treated as a decimal (not a hexadecimal) integer number representing a maximum response time in microseconds.
.br
It is used to establish a latency upper limit by limiting the use of C-States (CPU idle or CPU latency states) to only those with an exit latency smaller than the value set here. That means only those states that require less than the requested number of microseconds to wake up are enabled, all the other C-States are disabled.
.br
The files \fI/sys/devices/system/cpu/cpu*/cpuidle/state*/latency\fP and \fI/sys/devices/system/cpu/cpu*/cpuidle/state*/disable\fP are used to limit the C-States.

If system does not support force latency settings - '\fBall:none\fP' is used in the column '\fIActual\fP' of the verify table and the \fIfootnote\fP '[1] setting is not supported by the system' is displayed.

When set in the Note definition file for all available CPUs all CPU latency states with a value read from \fI/sys/devices/system/cpu/cpu*/cpuidle/state*/latency\fP \fB>=\fP (higher than) the value from the Note definition file are disabled by writing '\fB1\fP' to \fI/sys/devices/system/cpu/cpu*/cpuidle/state*/disable\fP

ATTENTION: not idling *at all* increases power consumption significantly and reduces the life span of the machine because of wear and tear. So do not use a too strict latency setting. For SAP HANA workloads a value of '\fB70\fP' microseconds (as a "light sleep") seems to be sufficient. And the impact on power consumption and life of the CPUs is less severe. But don't forget: The deeper the idle state, the larger is the exit latency.
\" section filesysten
.SH "[filesystem]"
The section "[filesystem]" is checking filesystem mount options.
.br
The values from the Note definition files are only checked against \fI/proc/mounts\fP and \fI/etc/fstab\fP. Changing the filesystem mount options is not supported by saptune.

This section can only contain the following parameter:
.TP
.BI xfs_options= STRING
.br
where STRING is a list of valid mount options separated by '\fB,\fP'
.br
A prefix '-' for the option indicates, that the option should NOT be available on any 'xfs' filesystem. A prefix '+' or no prefix for the option indicates, that the option should be available on any 'xfs' filesystem.

For the check first the \fBmounted\fP filesystems of the requested filesystem type (for now only 'xfs') will be read from \fI/proc/mounts\fP and separated in a list with mount points containing the option and another list with mount points NOT containing the option.
.br
Then the defined filesystems of the requested filesystem type (for now only 'xfs') will be read from \fI/etc/fstab\fP, skipping the already mounted mount points and split the remaining entries in a list with mount points containing the option and another list with mount points NOT containing the option.
.br
At least combine the lists from proc and fstab to get one list of mount points containing the option and another list with mount points NOT containing the option.

To decide, if a mount point contains the option or not, we use a simple string comparison between the value from the Note definition file and the option available on the system.
.br
\fBThis can lead to a not-compliant result even everything is in order!
.br
Because default options might not appear in the output of /proc/mounts, they are not found even if they are set internally. Also the content of the the 'defaults' entry of not-mounted filesystem is opaque.
.br
Keep this in mind when crafting overrides or extra Notes!\fP
\" section grub
.SH "[grub]"
The section "[grub]" is checking kernel command line settings for grub.
The values from the Note definition files are only checked against \fI/proc/cmdline\fP. Changing the grub configuration is not supported by saptune.

Some of these values are set by 'alternative' settings by saptune during runtime, so changing the grub configuration is possible but not needed.

This section can contain options like:
.TP
\fBintel_idle.max_cstate=1\fP and \fBprocessor.max_cstate=1\fP
Configure C-States for lower latency in Linux (applies to Intel-based systems only) - see force_latency in section [cpu] as 'alternative' settings
.TP
.BI numa_balancing=disable
Turn off autoNUMA balancing - see kernel.numa_balancing in section [sysctl] as 'alternative' settings
.TP
.BI transparent_hugepage=never
Disable transparent hugepages - see THP in section [vm] as 'alternative' settings
\" section limits
.SH "[limits]"
The section "[limits]" is dealing with ulimit settings for user login sessions in the pam_limits module. The settings will \fBNOT\fP be done in the central limits file \fI/etc/security/limits.conf\fP. Instead there will be a \fBdrop-in file\fP in \fI/etc/security/limits.d\fP for each domain-item-type combination used in the Note definition file.

The drop-in file name syntax will be:
.br
saptune-<domain>-<item>-<type>.conf

For more information and a description of the syntax and the needed fields please look at limits.conf(5).

This section has to contain the following option:
.TP
.BI LIMITS= STRING
.br
where STRING is a list of valid limit definitions separated by '\fB,\fP'
.br
a valid limit definition contains the fields 'domain item type value' separated by one space
.br
For more information about the syntax of valid limit definitions please refer to limits.conf(5) or the comment section of \fI/etc/security/limits.conf\fP.
.br
Note: The "@" sign in front of the domain name matches a group.

To leave \fBall\fP limits definitions of a Note definition file 'untouched' in the system, leave the \fBLIMITS\fP string in the \fBoverride file\fP of the Note definition file empty

To leave only \fBsome\fP of the limits definitions of a Note definition file 'untouched' in the system, remove these limits definitions from the \fBLIMITS\fP string in the \fBoverride file\fP of the Note definition file.
\" section login
.SH "[login]"
The section "[login]" manipulates the behaviour of the systemd login manager.
.br
This section can \fBonly\fP contain the following option:
.TP
.BI UserTasksMax= STRING
This option is only available on SLE12. In SLE15 the limit is removed from the systemd login manager and therefore the setting is no longer supported by saptune.

This option configures a parameter of the systemd login manager. It sets the maximum number of OS tasks each user may run concurrently. The behaviour of the systemd login manager was changed starting SLES12SP2 to prevent fork bomb attacks.

Recommended value is '\fBinfinity\fP'.

If set, the drop-in file \fI/etc/systemd/logind.conf.d/saptune-UserTasksMax.conf\fP is created and for all currently logged in users the maximum number of OS tasks each user may run concurrently is changed using the command '\fBsystemctl --runtime set-property user-<uid>.slice TasksMax=<value>\fP'.
.br
After creating the drop-in file the \fIsystemd-logind.service\fP will be reloaded.

ATTENTION: With this setting your system is vulnerable to fork bomb attacks
\" section mem
.SH "[mem]"
The section "[mem]" manipulates the size of TMPFS (\fI/dev/shm\fP).

With the STD implementation, the SAP Extended Memory is no longer stored in the TMPFS (under /dev/shm). However, the TMPFS is required by the Virtual Machine Container (VMC). For this reason, we still recommend the same configuration of the TMPFS:
.br
75% (RAM + Swap) is still recommended as the size.
.br
This section can contain the following options:
.TP
.BI ShmFileSystemSizeMB= INT
Use ShmFileSystemSizeMB to set an absolute value for your TMPFS.
.br
If ShmFileSystemSizeMB is set to a value > 0, the setting for VSZ_TMPFS_PERCENT will be ignored and the size will NOT be calculated.
.br
If ShmFileSystemSizeMB is set to '\fB0\fP' the size will be calculated using VSZ_TMPFS_PERCENT
.TP
.BI VSZ_TMPFS_PERCENT= INT
Size of tmpfs mounted on \fI/dev/shm\fP in percent of the virtual memory.
.br
Depending on the size of the virtual memory (physical+swap) the value is calculated by (RAM + SWAP) * VSZ_TMPFS_PERCENT/100
.br
If VSZ_TMPFS_PERCENT is set to '\fB0\fP', the value is calculated by (RAM + SWAP) * 75/100, as the default is 75.

As this parameter is only used to calculate the value of \fIShmFileSystemSizeMB\fP it will not be checked and compared during the saptune operation 'verify'. A footnote is pointing this out.
\" section pagecache
.SH "[pagecache]"
The section "[pagecache]" is dealing with the pagecache limit feature as described in SAP Note 1557506, which is only available on SLE12.

ATTENTION: The pagecache limit Note will \fBNOT\fP be part of any solution definition by default. As it is essential to configure this feature really carefully, you need to customize the Note definition file first to enable the feature and then you can apply the note settings manually. After that, the settings will be applied automatically during each startup of the system.
.br
This section can contain the following options:
.TP
.BI ENABLE_PAGECACHE_LIMIT= yesno
This defines whether pagecache limit feature should be enabled or not. It is a yesno value. By default it is set to \fBno\fP
.br
Consider to enable pagecache limit feature if your SAP workloads cause frequent and excessive swapping activities.
It is recommended to leave pagecache limit disabled if the system has low or no swap space.
.TP
.BI vm.pagecache_limit_ignore_dirty= INT
Whether or not to ignore dirty memory when enforcing the pagecache limit.
.br
If set to 0, dirty memory will be freed (written onto disk) when enforcing the pagecache limit.
.br
If set to 1 (default), dirty memory will not be freed when enforcing the pagecache limit.
.br
If set to 2 - a middle ground, some dirty memory will be freed when enforcing the limit.
.TP
.BI OVERRIDE_PAGECACHE_LIMIT_MB= INT
When pagecache limit feature is enabled, the limit value is usually automatically calculated using the 'HANA formula', which means 2% of system memory is used as pagecache limit.
.br
However, the value can be overridden if you set this parameter to the desired limit value.
.br
To remove the override, set the parameter to empty string.
\" section reminder
.SH "[reminder]"
The section "[reminder]" contains important information and all settings of a SAP Note, which can not set by saptune. 

This section is displayed at the end of the saptune options 'verify', 'simulate' and 'apply'. It will be highlighted with red color to get the attention of the customer.

Sometimes this section may include lines with parameter settings commented out as the SAP Note only contains rough estimations as the settings are highly customer environment and workload dependend. Please be aware that these parameter settings can't be activated by an override file. If you need to set such parameters you need to create a 'custom' note containing these settings by using 'saptune note create'
\" section rpm
.SH "[rpm]"
The section "[rpm]" is checking rpm versions on the system.
The values from the Note definition files are only checked against the installed rpm versions on the system. No other action is supported.
.br
Package dependencies - if needed - are handled by the saptune package installation.

With the availability of tagged sections, we support 2 different types of rpm line syntax. The first one - our \fBOld\fP Syntax - only for compatibility reasons. The second one - our \fBNew\fP Syntax - is our preferred syntax in combination with tagged rpm sections.

\fBOld\fP Syntax:
.br
<rpm package name> <SLE Version> <rpm package version>
.br
this syntax is mainly used for compatibility reasons and when using a 'non-tagged' rpm section.
.br
Add one line for each SLE version a package should be checked for, even if the package version is the same.
.br
The SLE version has to be noted in the same format as the '\fBVERSION=\fP' entry in \fI/etc/os-release\fP.

To address all SLE versions and service packs the keyword '\fBall\fP' can be used instead of a dedicated SLE version.

e.g
.br
systemd 12-SP2 228-142.1
.br
sapinit-systemd-compat 12 1.0-2.1
.br
sapinit-systemd-compat 12-SP1 1.0-2.1
.br
util-linux 12-SP1 2.25-22.1
.br
bzip2 all 1.0.8

Only the lines where the SLE version is matching the running system OS are checked and displayed during the 'verify' and 'simulate' option.
.br
That means, if there is no matching SLE version for the running OS no rpm entries are listed during the 'verify' and 'simulate' operation.

\fBNew\fP Syntax:
.br
<rpm package name> <rpm package version>
.br
this syntax is the preferred syntax when using a 'tagged' rpm section, where the targeted operating system and/or system architecture is defined by using the tags \fBos=\fP and/or \fBarch=\fP
.br
Add one line for each package and package version to be checked.

e.g
.br
systemd 228-142.1
.br
util-linux 2.25-22.1

Only the lines where the tags of the section match the running system OS and/or the system architecture are checked and displayed during the 'verify' and 'simulate' option.
.br
That means, if there is no matching SLE version for the running OS and/or no matching system architecture in the tags of the rpm section no rpm entries are listed during the 'verify' and 'simulate' operation.


\" section service
.SH "[service]"
The section "[service]" is dealing with starting, enabling, disabling and stopping services controlled by systemd.
.br
The syntax for the entries are:
.TP
.BI <servicename>= STRING
.br
where STRING is a list of valid values separated by '\fB,\fP', which are checked from left to right. The first entry of the pair 'start'/'stop' or 'enable'/'disable' will be used as new settings for the service.
.br
Valid services are those listed by the command '\fIsystemctl list-unit-files\fP'.
.br
Valid values are '\fBstart\fP' or '\fBstop\fP', '\fBenable\fP' or '\fBdisable\fP'.
.TP
.BI Exceptions\ and\ Warnings:
For the service \fBuuidd.socket\fP only '\fBstart\fP' is a valid value, because the uuidd.socket service is essential for a working SAP environment.

Concerning \fBsysstat.service\fP please be in mind: A running sysstat service can effect the system performance. But if there are real performance trouble with the SAP system, SAP service normally orders the sysstat reports collected in /var/log/sa.
.br
See sar(1), sa2(8), sa1(8) for more information

If a service is enabled or disabled by default or admin choice, saptune will NOT disable or enable this service, if only '\fBstart\fP' or '\fBstop\fP' is used. In this case it will only start/stop the service. If such a service is started by systemd during a system reboot \fBafter\fP the start of saptune.service it will be possible that a service is stopped/running even if it was started/stopped by saptune. To change this, the service can be additional enabled or disabled by using '\fBenable\fP' or '\fBdisable\fP' in the Note definition file.
\" section sysctl
.SH "[sysctl]"
The section "[sysctl]" can be used to modify kernel parameters. The parameters available are those listed under /proc/sys/.
.br
Please write the section keyword '[sysctl]' in the first line and add the desired tunables in 'sysctl.conf' syntax.
.TP
.BI sysctl.parameter= VALUE

There will be a detection of conflicting (system) sysctl entries.
.br
When parsing the section '[sysctl]' in the Note definition file saptune additional collects all defined sysctl settings (parameter and value) availabel in "/etc/sysctl.conf", "/run/sysctl.d/", "/etc/sysctl.d/", "/usr/local/lib/sysctl.d/", "/usr/lib/sysctl.d/", "/lib/sysctl.d/", "/boot/" (list retrieved from the comment in /etc/sysctl.conf and man page sysctl.conf(5)). When this file list contains a directory (like /etc/sysctl.d/) the files located in this directory are read too.
.br
saptune will now check, if the parameters from the section '[sysctl]' in the Note definition file are additional defined in one or more of the (system) sysctl config files. If yes, a warning is displayed and logged and a footnote will be prepared for the 'saptune verify' output. The info shown is the filename, where the parameter is additionally defined with it's value in brackets.
.br
The central saptune configuration file \fI/etc/sysconfig/saptune\fP contains a parameter \fbSKIP_SYSCTL_FILES\fP, which contains a comma separated list of sysctl.conf files or directories containing sysctl.conf files, which should be excluded from this warning message and the footnote.
.br
Default is \fbSKIP_SYSCTL_FILES="/boot"\fP to skip the WARNINGS for \fI/boot/sysctl.conf-<kernelversion>\fP

Hint: At the moment links are not recognized. So the linked files will be added both in the file list.

\" section sys
.SH "[sys]"
The section "[sys]" can be used to modify parameters available under /sys/, if the related file is writable.
.br
The syntax for the sys.parameters is following the 'sysctl.conf' syntax. So it's the absolute filename without the prefixed /sys/ and all remaining '/' exchanged by '.'
.br
e.g. \fI/sys/module/watchdog/parameters/open_timeout\fP should be written as \fBmodule.watchdog.parameters.open_timeout\fP
.TP
.BI sys.parameter= VALUE
.br
ATTENTION: saptune is NOT validating the value before trying to apply.
\" section vm
.SH "[vm]"
The section "[vm]" manipulates \fI/sys/kernel/mm\fP switches.
.br
This section can to contain the following options:
.TP
.BI THP= STRING
This option disables transparent hugepages by changing \fI/sys/kernel/mm/transparent_hugepage/enabled\fP
.br
Possible values are '\fBnever\fP' to disable and '\fBalways\fP' to enable.
.TP
.BI KSM= INT
Kernel Samepage Merging (KSM). KSM allows for an application to register with the kernel so as to have its memory pages merged with other processes that also register to have their pages merged. For KVM the KSM mechanism allows for guest virtual machines to share pages with each other. In today's environment where many of the guest operating systems like XEN, KVM are similar and are running on same host machine, this can result in significant memory savings, the default value is set to 0.

.SH FILES
\fI/usr/share/saptune/notes\fP
.RS 4
here you can find examples how to set the 'parameter value' pairs of the available sections.
.br
But please do not change the files located here. You will lose all your changes during a saptune package update. Use an override or extra file for your changes as described in saptune_v2(8).
.RE

.SH "SEE ALSO"
.LP
saptune-migrate(7) saptune(8)

.SH AUTHOR
.NF
Soeren Schmidt <soeren.schmidt@suse.com>, Angela Briel <abriel@suse.com>