SUSE/saptune

.\"/*
.\" * Copyright (c) 2017-2024 SUSE LLC.
.\" * All rights reserved
.\" * Authors: Soeren Schmidt, 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 "8" "October 2024" "" "System optimization For SAP"
.SH NAME
saptune \- Comprehensive system optimization management for SAP solutions (\fBVersion 3\fP)

ATTENTION: If you still use version \fB1\fP of saptune it's now time to migrate to saptune version \fB3\fP, so please refer to man page saptune-migrate(7).

.SH SYNOPSIS
\fBsaptune\fP [--format FORMAT] [--force-color] \fBdaemon\fP
( start | stop | status [--non-compliance-check] ) \fBATTENTION: deprecated\fP

\fBsaptune\fP [--format FORMAT] [--force-color] \fBservice\fP
( start | stop | restart | takeover | enable | disable | enablestart | disablestop | status [--non-compliance-check] )

\fBsaptune\fP [--format FORMAT] [--force-color] \fBnote\fP
( list | verify | revertall | enabled | applied )

\fBsaptune\fP [--format FORMAT] [--force-color] \fBnote\fP
( apply | simulate | customise | create | edit | revert | show | delete ) NOTEID

\fBsaptune\fP [--format FORMAT] [--force-color] \fBnote\fP
verify [--colorscheme SCHEME] [--show-non-compliant] [NOTEID|applied]

\fBsaptune\fP [--format FORMAT] [--force-color] \fBnote\fP
rename NOTEID NEWNOTEID

\fBsaptune\fP [--format FORMAT] [--force-color] \fBsolution\fP
( list | verify | enabled | applied )

\fBsaptune\fP [--format FORMAT] [--force-color] \fBsolution\fP
( apply | simulate | customise | create | edit | revert | show | delete ) SOLUTIONNAME

\fBsaptune\fP [--format FORMAT] [--force-color] \fBsolution\fP
change [--force] SOLUTIONNAME

\fBsaptune\fP [--format FORMAT] [--force-color] \fBsolution\fP
verify [--colorscheme SCHEME] [--show-non-compliant] [SOLUTIONNAME]

\fBsaptune\fP [--format FORMAT] [--force-color] \fBsolution\fP
rename SOLUTIONNAME NEWSOLUTIONNAME

\fBsaptune\fP [--format FORMAT] [--force-color] \fBstaging\fP
( status | enable | disable | is-enabled | list )

\fBsaptune\fP [--format FORMAT] [--force-color] \fBstaging\fP
( analysis | diff ) [ ( NOTEID | SOLUTIONNAME )... | all ]

\fBsaptune\fP [--format FORMAT] [--force-color] \fBstaging\fP
release [--force|--dry-run] [ ( NOTEID | SOLUTIONNAME )... | all ]

\fBsaptune\fP [--format FORMAT] [--force-color] \fBconfigure\fP
( COLOR_SCHEME | SKIP_SYSCTL_FILES | IGNORE_RELOAD | DEBUG ) Value

\fBsaptune\fP [--format FORMAT] [--force-color] \fBconfigure\fP
( reset | show )

\fBsaptune\fP [--format FORMAT] [--force-color] \fBverify\fP
applied

\fBsaptune\fP [--format FORMAT] [--force-color] \fBrevert\fP
all

\fBsaptune\fP [--format FORMAT] [--force-color] \fBcheck\fP

\fBsaptune\fP [--format FORMAT] [--force-color] \fBstatus [--non-compliance-check]\fP

\fBsaptune\fP [--format FORMAT] [--force-color] \fBversion\fP

\fBsaptune\fP [--format FORMAT] [--force-color] \fBhelp\fP

.SH DESCRIPTION
saptune is designed to automate the configuration recommendations from SAP and SUSE to run an SAP application on SLES for SAP. These configuration recommendations are normally referred to as SAP Notes. So some dedicated SAP Notes are the base for the work of saptune. Additional some best practice guides are added as Note definitions to optimize the system for some really special cases.

saptune can apply settings for a single Note definition or can set all settings for a predefined solution, which is a collection of several SAP Notes. Additionally it can revert all these settings back to the previous system settings.

It can verify, if the current system configuration is in sync with a specific Note definition or a defined solution and displays the differences.
Additionally, it can simulate the setting of a single SAP Note definition or a defined solution and will display the changes which will be done to the system.

saptune does not only set kernel values (like sysctl does), but also values like cpu governor, energy perf bias, force latency (dma latency) and the disk io scheduler. Additionally it will check/verify, if suitable rpm versions are installed and special kernel command line values are set, according to the relevant SAP Notes. So saptune checks and applies values in various locations during runtime like
.PP
/proc/sys/, /proc/sys/vm/, /proc/sys/kernel, /proc/sys/fs, /sys/block/*/queue/scheduler and /sys/block/*/queue/nr_requests, /sys/devices/system/cpu/*/cpufreq/scaling_governor, /sys/devices/system/cpu/*/cpuidle/state*/latency, /sys/devices/system/cpu/*/cpuidle/state*/disable, /dev/shm, /etc/security/limits.d/, /etc/systemd/logind.conf.d/ and some others.

By default saptune is printing all results to stdout, Errors and Warnings are printed to stderr. By using \fB--format FORMAT\fP this behaviour can be changed.
.br
Supported formats are:
.TP
.B json
Print all results in a machine readable json output format defined by the schemata delivered in \fI/usr/share/saptune/schemas/1.0\fP.

saptune does no longer use tuned(8) to restart after a system reboot. It is using its own systemd service named "saptune.service".

We decided to have only ONE solution applied, but multiple Notes. Each Note is applied exactly once.

.SH DAEMON ACTIONS - ATTENTION: deprecated
.SS
.TP
.B start
As saptune no longer uses tuned, this action is internally linked to 'saptune service takeover'. See description below
.TP
.B status
As saptune no longer uses tuned, this action is internally linked to 'saptune service status'. See description below
.TP
.B stop
As saptune no longer uses tuned, this action is internally linked to 'saptune service disablestop'. See description below

.SH SERVICE ACTIONS
.SS
.TP
.B start
Start saptune service and apply a set of optimizations to the system, if solutions or notes were selected during a previous call of saptune. If the service is enabled, the tuning will be automatically activated upon system boot.
.br
It redirects to '\fIsystemctl start saptune.service\fP'
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

It will fail in case sapconf.service is running or has exited or save state files are present.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B status
Reports the following status information on stdout:
.RS 5
.IP \[bu] 2
status of saptune.service (enabled/disabled, active/inactive/failed/...the other possible unit states...)
.IP \[bu]
saptune package version
.IP \[bu]
configured saptune major version (from \fI/etc/sysconfig/saptune\fP)
.IP \[bu]
enabled Solution
.br
The entry 'enabled Solution' shows the Solution, which was manually applied by '\fIsaptune solution apply <solution name>\fP' and its related Notes.
.IP \[bu]
applied Solution
.br
The entry 'applied Solution' shows the Solution, which is currently applied and its related and applied Notes.
.IP \[bu]
additional enabled Notes, sorted lexicographically
.br
The entry 'additional enabled Notes' shows all Notes, which were additionally applied manually by '\fIsaptune note apply <note name>\fP'. They are \fBone\fP part of the list of notes in the entry 'applied Notes' and 'enabled Notes'.
.IP \[bu]
all selected Notes in applied order
.br
The list of 'enabled Notes' includes all Notes from 'additional enabled Notes' and additional all the Notes related to the 'enabled Solution' too. The list shows the order in which these Notes were applied and will be re-applied after a system reboot, if the \fBsaptune.service\fP is enabled.
.IP \[bu]
all currently applied Notes in applied order
.br
The list of 'applied Notes' includes the \fBmanually\fP applied Notes. Additional it includes all the Notes related to the 'configured Solution' too. These Notes get applied when using '\fIsaptune solution apply\fP'. The solutions and their related notes can be listed by '\fIsaptune solution list\fP'.

And additional 'applied Notes' shows if the system is '\fBactively\fP' tuned at the moment. If the list is empty, the system is \fBnot\fP tuned. If the list is \fBnot\fP empty, the system \fBis\fP tuned.
.IP \[bu]
A list of orphaned Overrides
.br
These are override files existing in \fI/etc/saptune/override\fP, but with no related Note definition file found in the working area \fI/var/lib/saptune/working/\fP or in the custom/vendor directory \fI/etc/saptune/extra\fP.
.IP \[bu]
state of staging
.IP \[bu]
staged Notes
.IP \[bu]
staged Solutions
.IP \[bu]
status of sapconf.service (enabled/disabled, active/inactive/failed/...the other possible unit states...)
.IP \[bu]
status of tuned (enabled/disabled, active/inactive/failed/...the other possible unit states..., profile)
.IP \[bu]
the overall systemd 'system' status, read from \fI'systemctl is-system-running'\fP (running, degraded, ....)
.IP \[bu]
the tuning state of the system, gathered by 'saptune note verify'.
.br
"unknown (checking disabled)", if the flage '--non-compliance-check' is used.
.br
"not tuned", if \fBno\fP Solution or Note is applied.
.br
"not-present", if 'verify' hit an error.
.br
"not compliant", if one or more parameter values differ from the related SAP Note. For detailed information please use \fI'saptune note verify'\fP.
.br
"compliant", if all parameter values comply with the values from the related SAP Notes.

This information is not logged, but only printed to stdout.

If saptune.service is \fBnot\fP 'active' the exit code is 1. If the system is '\fBnot tuned\fP' - which means no Note or Solution is enabled - the exit code is 3. If the system is tuned, but the tuning is \fBnot compliant\fP the exit code is 4. Otherwise the exit code is 0.
.SS
.TP
.B stop
Stop saptune service and revert all optimizations that were previously applied by saptune. If the service is disabled, the tuning will no longer automatically activate upon boot.
.br
It redirects to '\fIsystemctl stop saptune.service\fP'
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B restart
Revert all optimizations that were previously applied by saptune. And after that apply a set of optimizations to the system, if solutions or notes were selected during a previous call of saptune.
.br
It redirects to '\fIsystemctl restart saptune.service\fP'
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.

If '\fIIGNORE_RELOAD\fP' is set to '\fByes\fP' in the saptune configuration file the action '\fIrestart\fP' will do \fBnothing\fP. The reason will be logged.
See the 'NOTE' section at the end of the man page for more information.
.TP
.B enable
Enables the saptune service. To activate the tuning, the saptune service needs to be started. But as the service is now enabled, the tuning will automatically activated upon system boot.
.br
It redirects to '\fIsystemctl enable saptune.service\fP'
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

It will fail in case sapconf.service is running or has exited or save state files are present.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B disable
Disable the saptune service. To revert all optimizations that were previously applied by saptune, the saptune service needs to be stopped. But as the service is now disabled, the tuning will no longer automatically activated upon system boot.
.br
It redirects to '\fIsystemctl disable saptune.service\fP'
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B enablestart
Enables and start the saptune service and apply a set of optimizations to the system, if solutions or notes were selected during a previous call of saptune. As the service is now enabled, the tuning will automatically activated upon system boot.
.br
Calls '\fIsystemctl enable saptune.service\fP' and '\fIsystemctl start saptune.service\fP' in this order.
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B disablestop
Disable and stop the saptune service and revert all optimizations that were previously applied by saptune. As the service is now disabled, the tuning will no longer automatically activated upon system boot.
.br
Calls '\fIsystemctl disable saptune.service\fP' and '\fIsystemctl stop saptune.service\fP' in this order.
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.
.TP
.B takeover
This action is meant to start and enable saptune service where competing services like sapconf and/or tuned get stopped and disabled. This is the modern replacement for the obsolete '\fIsaptune daemon start\fP'
.br
Calls '\fIsystemctl enablestart saptune.service\fP' after stopping and disabling sapconf.service and tuned.service.
.br
Success is reported on stdout, errors including systemd error messages are printed on stderr. The action gets logged.

If the action was successfully the exit code is 0, otherwise 1.

.TP
.B ATTENTION:
.br
saptune is able to start/stop/enable/disable systemd units, but on boot the outcome depends on the order of execution.

If saptune is starting (or stopping) a systemd service ([service] section) it might happen, that the action gets reverted later by systemd because that service is disabled (or enabled) and executed after saptune.service.

Similar a service enabled (or disabled) by saptune might already be stopped (or started) by systemd, because it came before saptune.service.

If the execution order cannot be assured by service dependencies, it is recommended to set both ('start,enable' or 'stop,disable') in a Note definition or an Override.

.SH NOTE ACTIONS
Note denotes either a SAP Note, a vendor specific tuning definition or SUSE recommendation article.
.SS
.TP
.B apply
Apply optimization settings specified in the Note. The Note will be automatically activated upon system boot if the saptune service is enabled.

If a Note definition contains a '\fB[reminder]\fP' section, this section will be printed after the note has applied successfully. It will be highlighted with red color.

A Note can only be applied once.

ATTENTION:
Please be in mind: If a Note definition to be applied contains parameter settings which are likewise set before by an already applied Note these settings get be overwritten.
.br
The last comes, the last wins, it's all about 'order'.

So be careful when applying solutions or notes or when reverting notes, especially if these notes are part of an already applied solution. You can re-apply such a note, but the order - and may be the resulting parameter settings - will be unlike before.
.br
Special attention is needed, if customer or vendor specific notes from \fI/etc/saptune/extra\fP are used.
.TP
.B list
List all SAP Notes, vendor specific tuning definitions and SUSE recommendation articles that saptune is capable of implementing.

Currently implemented notes are marked with '\fB+\fP', if manually enabled, '\fB*\fP', if enabled by solutions or '\fB-\fP', if a note belonging to an enabled solution was reverted manually. In all cases the notes are highlighted with green color.
.br
If an \fBoverride\fP file exists for a NoteID, the note is marked with '\fBO\fP' and a customer or vendor specific note is marked with '\fBC\fP'..
.TP
.B enabled
Print all currently enabled notes as a list separated by blanks without trailing line feed.
.TP
.B applied
Print all currently applied notes as a list separated by blanks without trailing line feed.
.TP
.B verify
If a Note ID is specified, saptune verifies the currently running system against the recommendations specified in the Note. If Note ID is \fBnot\fP specified or the string \fIapplied\fP is specified, saptune verifies all system parameters against all applied Notes. As a result you will see a table containing the following columns

SAPNote, Version | Parameter | Expected | Override | Actual | Compliant

\fBExpected\fP shows the values read from the Note definition file
.br
\fBOverride\fP shows the values found in an \fBoverride\fP file
.br
\fBActual\fP shows the current system value
.br
\fBCompliant\fP shows \fByes\fP, if the 'Expected' and 'Actual' value matches, or \fBno\fP, if there is no match.
.br
In some rows you can find references to \fBfootnotes\fP containing additional information. They may explain, why a value does not match.

e.g.
.br
[1] setting is not supported by the system
.br
This may result in a ' - ' in column 'Compliant', but the system will nevertheless be reported as fully conforms to the specified note.
.br
[2] setting is not available on the system
.br
In case of 'grub' settings, this may result in a 'no' in column 'Compliant', but the system will nevertheless be reported as fully conforms to the specified note, because most 'grub' settings mentioned in the SAP Notes are covered by other, alternative settings.
.br
[3] value is only checked, but NOT set
.br
In case of 'grub' settings, this may result in a 'no' in column 'Compliant', but the system will nevertheless be reported as fully conforms to the specified note, because most 'grub' settings mentioned in the SAP Notes are covered by other, alternative settings.
.br
[4] cpu idle state settings differ
.br
[5] expected value does not contain a supported scheduler
.br
[6] grub settings are mostly covered by other settings. See man page saptune-note(5) for details
.br
[7] parameter value is untouched by default
.br
If the parameter value in the Note definition file is left 'empty', the current system value of the parameter will not be changed.
.br
[8] cannot set Perf Bias because SecureBoot is enabled"
.br
If SecureBoot is enabled some system settings are 'read only' and can not be changed.
.br
[9] expected value limited to 'max_hw_sectors_kb'"
.br
The possible value for parameter 'MAX_SECTORS_KB' (/sys/block/*/queue/max_sectors_kb) is limited by the value of /sys/block/*/queue/max_hw_sectors_kb.

If a Note definition contains a '\fB[reminder]\fP' section, this section will be printed below the table and the footnotes. It will be highlighted with red color.

By using the command line argument '\fB--show-non-compliant\fP' it is possible to limit the verify output to show only non-compliant parameter. The output will \fBnot\fP be colorized even that a \fBcolor scheme\fP is defined.

It is possible to use a \fBcolor scheme\fP for the verify output table.
.br
The \fBcolor scheme\fP can be given as a command line argument '\fB--colorscheme SCHEME\fP' or as variable '\fBCOLOR_SCHEME SCHEME\fP' in the saptune configuration file \fI/etc/sysconfig/saptune\fP.
.br
Possible \fBcolor schemes\fP are:
.RS 7
.IP \[bu]
full-green-zebra   - whole line is colored green (compliant) or red (not compliant)
.IP \[bu]
full-blue-zebra    - whole line is colored blue (compliant) or yellow (not compliant)
.IP \[bu]
cmpl-green-zebra   - only the content in the Compliant column is colored green (compliant) or red (not compliant)
.IP \[bu]
cmpl-blue-zebra    - only the content in the Compliant column is colored blue (compliant) or yellow (not compliant)
.IP \[bu]
full-red-noncmpl - only the whole line of the not compliant parameter is colored red
.IP \[bu]
full-yellow-noncmpl - only the whole line of the not compliant parameter is colored yellow
.IP \[bu]
red-noncmpl      - only the content in the Compliant column of the not compliant parameter is colored red
.IP \[bu]
yellow-noncmpl      - only the content in the Compliant column of the not compliant parameter is colored yellow
.RS 0

The default, if no \fBcolor scheme\fP is given, is \fBfull-red-noncmpl\fP. If an unknown \fBcolor scheme\fP is given in the command line or in the config file, non-colorized, simple black text is printed.

The 'final lines' with the overall result of the verify operation are colored green (compliant) or red (not compliant) independent from the chosen \fBcolor scheme\fP
.SS
.TP
.B simulate - ATTENTION: deprecated
Show all changes that will be applied to the system if the specified Note is applied.
As a result you will see a table containing the following columns

Parameter | Value set | Value expected | Override | Comment

\fBValue set\fP shows the current system value
.br
\fBValue expected\fP shows the values read from the Note definition file
.br
\fBOverride\fP shows the values found in an \fBoverride\fP file
.br
\fBComment\fP shows references to \fBfootnotes\fP containing additional information. They may explain, why a value will not be set by saptune.

e.g.
.br
[1] setting is not supported by the system
.br
[2] setting is not available on the system
.br
[3] value is only checked, but NOT set
.br
[4] cpu idle state settings differ
.br
[5] expected value does not contain a supported scheduler

If a Note definition contains a '\fB[reminder]\fP' section, this section will be printed below the table and the footnotes. It will be highlighted with red color.
.TP
.B edit
This allows to edit the values of the customer or vendor specific Note definitions in \fI/etc/saptune/extra\fP.
An editor will be launched to allow changing the Note definitions.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.

You can change already available parameters and values or you can add new parameters and values or additional sections with parameter value pairs.

If the Note is currently applied and/or an override file exists, saptune will remind you to take care of this situation.
.TP
.B customise
This allows to customize the values of the saptune Note definitions. The Note definition file will be copied from \fI/usr/share/saptune/notes\fP or \fI/etc/saptune/extra\fP to the override location at \fI/etc/saptune/override\fP, if the file does not exist already. After that an editor will be launched to allow changing the Note definitions.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.

You can only change the value from already available parameters of the note. But you are not able to add new parameters.

If you want to use new parameters to tune the system, please create your own custom Note definition file in \fI/etc/saptune/extra\fP.

You can prevent a parameter from being changed by leaving the parameter value in the override file empty. The parameter will be marked as 'untouched' in the override column of the verify table.

The values from the override files will take precedence over the values from \fI/usr/share/saptune/notes\fP or \fI/etc/saptune/extra\fP. In such case you will not lose your customized Notes between saptune or vendor updates.
.br
The saptune options 'list', 'verify' and 'simulate' will mark the existence of an override file and the contained values.

ATTENTION:
Creating or changing an override file just changes the configuration \fIinside\fP this Note definition file, but does not change the \fIrunning\fP configuration of the system.
.br
That means: When creating or changing an override file for an \fBalready applied\fP Note definition, please do a '\fIsaptune note revert <NoteID>\fP' and then apply this Note again, to get the changes take effect.
.TP
.B create
This allows to create own Note definition files in \fI/etc/saptune/extra\fP. The Note definition file will be created from a template file into the location \fI/etc/saptune/extra\fP, if the file does not exist already. After that an editor will be launched to allow changing the Note definitions.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.
You need to choose an unique NoteID for this operation. Use '\fIsaptune note list\fP' to find the already used NoteIDs.
.TP
.B revert
Revert optimization settings carried out by the Note, and the Note will no longer be activated automatically upon system boot.
.TP
.B revertall
Revert optimization settings carried out by all applied notes, and the notes will no longer be activated automatically upon system boot.
.TP
.B show
Print content of Note definition file to stdout
.TP
.B delete
This allows to delete a customer or vendor specific Note definition file including the corresponding override file if available. A confirmation is needed to finish the action.

ATTENTION:
.br
Note definition files shipped by the saptune package - so called \fIinternal\fP saptune Note definition files - \fBmust not\fP be deleted. There will be an appropriate error message.
.br
If a corresponding override file is available, there will be the possibility to delete this file instead.

ATTENTION:
.br
If the Note is already applied, the command will be terminated with the information, that the Note first needs to be reverted before it can be deleted.
.TP
.B rename
This allows to rename a customer or vendor specific Note definition file to a new name. If a corresponding override file is available, this file will be renamed too. A confirmation is needed to finish the action.
.br
If the \fBnew\fP Note definition name already exists the command will be terminated with a respective message.

ATTENTION:
.br
Note definition files shipped by the saptune package - so called \fIinternal\fP saptune Note definition files - and their corresponding override files, if available, \fBmust not\fP be renamed. There will be an appropriate error message.

ATTENTION:
.br
If the Note is already applied, the command will be terminated with the information, that the Note first needs to be reverted before it can be renamed.

.SH SOLUTION ACTIONS
A solution is a collection of one or more Notes. Activation of a solution will activate all associated Notes.
.br
The solution definitions shipped with saptune can be found in the directory \fI/usr/share/saptune/sols\fP or vendor/customer specific solution definitions can be found in the directory \fI/etc/saptune/extra\fP.

It's not possible to combine solutions, there can only be\fBone\fP solution enabled. But it is possible to change a solution definition by using an override file in \fI/etc/saptune/override\fP or by creating a custom specific solution definition in the directory \fI/etc/saptune/extra\fP.

The following solution definitions are currently shipped with saptune:
.TS
tab(:) box;
c | l
l | l.
SOLUTION:Definition
_
BOBJ:Solution for running SAP BusinessObjects.
HANA:Solution for running an SAP HANA database.
MAXDB:Solution for running an SAP MaxDB database.
NETWEAVER:Solution for running SAP NetWeaver application servers.
NETWEAVER+HANA:Solution for running both SAP application servers and SAP HANA on the same host.
NETWEAVER+MAXDB:Solution for running both SAP application servers and SAP MaxDB on the same host.
S4HANA-APPSERVER:Solution for running SAP S/4HANA application servers
S4HANA-APP+DB:Solution for running both SAP S/4HANA application servers and SAP HANA on the same host
S4HANA-DBSERVER:Solution for running the SAP HANA database of an SAP S/4HANA installation
SAP-ASE:Solution for running an SAP Adaptive Server Enterprise database.
.TE

.SS
.RS 0
Syntax of the solution definition file names:
<solutionName>.sol
.br
e.g. V4711.sol

.SS
.TP
.B apply
Apply optimization settings recommended by the solution. These settings will be automatically activated upon system boot if the saptune service is enabled.
.TP
.B list
List all solution names that saptune is capable of implementing.
.br
The currently implemented solution is marked with '\fB*\fP' and is highlighted with green color. A deprecated solution is marked with '\fBD\fP'.
.br
If an \fBoverride\fP file exists for a solution, the solution is marked with '\fBO\fP'. A custom specific solution is marked with '\fBC\fP'.
.br
If a note belonging to an enabled solution is reverted manually, the note is highlighted with red color (instead of green) and is crossed out.
.TP
.B enabled
Print the currently enabled solution.
.TP
.B applied
Print the currently applied solution.
.br
If one or more notes of the solution are \fBreverted\fP, which is indicated by a '-' in the output of 'saptune note list', the string '\fB(partial)\fP is added to the solution name.
.TP
.B simulate - ATTENTION: deprecated
Show all notes that are associated with the specified solution, and all changes that will be applied once the solution is activated.
.TP
.B verify
If a solution name is specified, saptune verifies the running system against the recommended settings of this solution. If the solution name is not specified, saptune verifies all system parameters against all implemented solutions.
.TP
.B edit
This allows to edit the note list of the customer or vendor specific solution definitions in \fI/etc/saptune/extra\fP.
An editor will be launched to allow changing the Note definitions.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.

You can change, add or delete noteIDs in the list of notes defining the solution.

If the solution is currently applied and/or an override file exists, saptune will remind you to take care of this situation.
.TP
.B customise
This allows to customize the note list of the saptune solution definitions. The solution definition file will be copied from \fI/usr/share/saptune/sols\fP or \fI/etc/saptune/extra\fP to the override location at \fI/etc/saptune/override\fP, if the file does not exist already. After that an editor will be launched to allow changing the solution definitions.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.

You can change, add or delete noteIDs in the list of notes defining the solution.

The values from the override files will take precedence over the values from \fI/usr/share/saptune/sols\fP or \fI/etc/saptune/extra\fP. In such case you will not lose your customized solutions between saptune or vendor updates.
.br
The saptune option 'list' will mark the existence of an override file.

ATTENTION:
Creating or changing an override file just changes the configuration \fIinside\fP this solution definition file, but does not change the \fIrunning\fP configuration of the system.
.br
That means: When creating or changing an override file for an \fBalready applied\fP solution definition, please do a '\fIsaptune solution revert <solutionName>\fP' and then apply this solution again, to get the changes take effect.
.TP
.B create
This allows to create own solution definition files in \fI/etc/saptune/extra\fP. The solution definition file will be created from a template file into the location \fI/etc/saptune/extra\fP, if the file does not exist already. After that an editor will be launched to allow changing the solution definition.
The editor is defined by the \fBEDITOR\fP environment variable. If not set editor defaults to /usr/bin/vim.
You need to choose an unique solution name for this operation. Use '\fIsaptune solution list\fP' to find the already used solution names.
.TP
.B revert
Revert optimization settings recommended by the solution, and these settings will no longer be activated automatically upon system boot.
.TP
.B change
Switch to a new solution even that another solution was already applied.
.br This is basically a revert of the old solution and an apply of the new solution. A confirmation is needed to finish the revert action of the old solution. The confirmation can be suppressed by '--force'
.br
ATTENTION:
.br
because of the revert of the old solution during the execution of the action 'change' the system will be not sufficient tuned for SAP workloads for a short period of time until the new solution is applied successfully. This may harm a running SAP system. So use this action carefully.
.br
And please be in mind: Because of the 'revert' and 'apply' the order of notes and therefore the active tuning may change, especially if additional notes were applied beside the old applied solution.
.TP
.B show
Print content of solution definition file to stdout
.TP
.B delete
This allows to delete a customer or vendor specific solution definition file including the corresponding override file if available. A confirmation is needed to finish the action.

ATTENTION:
.br
Solution definition files shipped by the saptune package - so called \fIinternal\fP saptune solution definition files - \fBmust not\fP be deleted. There will be an appropriate error message.
.br
If a corresponding override file is available, there will be the possibility to delete this file instead.

ATTENTION:
.br
If the Solution is already applied, the command will be terminated with the information, that the Solution first needs to be reverted before it can be deleted.
.TP
.B rename
This allows to rename a customer or vendor specific solution definition file to a new name. If a corresponding override file is available, this file will be renamed too. A confirmation is needed to finish the action.
.br
If the \fBnew\fP solution definition name already exists the command will be terminated with a respective message.

ATTENTION:
.br
Solution definition files shipped by the saptune package - so called \fIinternal\fP saptune solution definition files - and their corresponding override files, if available, \fBmust not\fP be renamed. There will be an appropriate error message.

ATTENTION:
.br
If the Solution is already applied, the command will be terminated with the information, that the Solution first needs to be reverted before it can be renamed.

.SH STAGING ACTIONS
Staging is implemented to enable customers to control and release changes shipped by package updates to their working environment.
.br
The basic idea is, that Note definition files shipped by saptune in updates are not used by saptune for system tuning immediately. An administrator has to explicitly release the updates before being used by saptune. This allows customers to update saptune, even with changed Notes, without having changes in system behavior.

Staging is disabled by default, as not every customer needs the feature and having it enabled by default would break the preveious behaviour. 

Staging can be enable by '\fBsaptune staging enable\fP' (see desciption below)

So now we will have 3 areas, where Note definition files and solution definitions shipped by saptune can reside:
.br
This is only related to Note definition files and solution definitions shipped by saptune. Custom definition files or override files are \fBNOT\fP affected.

\fBPackage Area\fP
.br
Directory where the saptune package stores and maintains shipped Note definition files and solution definitions. This directory gets changed by RPM package operations solely.
.br
Currently this is \fB/usr/share/saptune/\fP.

\fBWorking Area\fP
.br
Directory which contains configuration objects saptune note|solution|daemon|service will use. Only Notes and solutions from here can be applied.
.br
Currently this is \fB/var/lib/saptune/working/\fP.

\fBStaging Area\fP
.br
Directory where configuration objects are stored, which are present in the package area but differ from the objects in the working area.
.br
Currently this is \fB/var/lib/saptune/staging/\fP.
.br
At the moment only the Notes from the last update are kept in \fB/var/lib/saptune/staging/latest\fP.
.SS
.TP
.B status
Displays the status of staging, basically the content of the variable STAGING in /etc/sysconfig/saptune.
.TP
.B is-enabled
Returns the status of staging, basically the content of the variable STAGING in /etc/sysconfig/saptune, as exit code (0 == enabled, 1 == disabled).
No output is generated as this is meant to be used in scripts.
.TP
.B enable|disable
Enables or disables staging, by setting the variable STAGING in /etc/sysconfig/saptune. The result of the status change is displayed.

Altering the setting does not changes the content of the staging and working directory.
.br
If a user disables staging an package updated might clean the staging area and update the working area.
.TP
.B list
Lists all Notes and the solution definition which can be released from the staging area including name, description, version and release date.
.br
The solution definition is shown as a whole object. It is only possible to release the entire definition, but not single solutions.
.br
Lastly a hint is printed to remind the user that he has to release staged objects before he can use them and that it is possible to view the changes.
.TP
.B diff [ ( NOTEID | SOLUTIONNAME )... | all ]
Shows the differences between the Note (or all Notes) or the Solution definition in the staging area and the working area.
.br
For each Note in the staging area the output contains the values of all parameter which differ. This includes new or removed parameters as well as changes in the reminder section.
.br
For the Solution, all changed solutions are displayed with their differences.
.br
Lastly a hint is printed to remind the user that he has to release staged objects before he can use them.
.TP
.B analysis [ ( NOTEID | SOLUTIONNAME )... | all ]
Does an analysis of the requested Notes, the Solution definitions or everything in the staging area to warn the user about possible issues or additional steps to perform.
.br
Lastly a hint is printed to remind the user that he has to release staged objects before he can use them as well that he should check out the differences.
.TP
.B release [ ( NOTEID | SOLUTIONNAME )... | all ]
Releases the requested Notes, the Solution definitions or everything in the stages area.
.br
This means the Notes or the Solution definitions get moved from the staging area to the working area. In case of a deleted Note/Solution, it will be removed from the working area.
.br
First the command will show an analysis of the objects going to be released to make the user aware of further needed actions or potential problems (for details see saptune staging dependencies).
.br

Because the release is irreversible, the user has to confirm the action.

.SH CONFIGURE ACTIONS
Replaces the direct editing of the saptune configuration file /etc/sysconfig/saptune, which will be replaced by an intern configuration file and not be present in future versions.
.br
Not all of the former variables will be available as configure option, only those who should be changeable by the user.
.br
.SS
.TP
.B COLOR_SCHEME SCHEME
Default color scheme. See saptune verify --colorscheme SCHEME for available schemes.
.TP
.B SKIP_SYSCTL_FILES FILE[,FILE...]
Comma-separated list of sysctl config files or directories which should be excluded when checking if parameters handled by saptune are handled by sysctl as well.
Input is checked, if the given files are in a location which is searched by sysctl command. If not, the files will be skipped.
.TP
.B IGNORE_RELOAD yes||no
Controls behavior of systemctl reload saptune.service and the systemctl try-restart saptune.service during package installation.
.TP
.B reset
Reverts the tuning and reset the content of the saptune configuration file to the installation default. Asks for confirmation.
.TP
.B show
Shows the content of the saptune configuration file

.SH VERIFY ACTIONS
.TP
.B verify applied
Verifies all system parameters against all applied Notes.
.br
Same as a \fIsaptune note verify\fP

.SH REVERT ACTIONS
.TP
.B revert all
Revert all optimization settings recommended by the SAP solution and/or the Notes, and these settings will no longer be activated automatically upon system boot.

.SH CHECK ACTIONS
.TP
.B check
Will simply call the external script '/usr/sbin/saptune_check'.

.SH STATUS ACTIONS
.TP
.B status
Will display the currently saptune status. This will be short for 'saptune service status'.

.SH VERSION ACTIONS
.TP
.B version
Will display the currently active saptune version.

.SH HELP ACTIONS
.TP
.B help
Will display the syntax of saptune

.SH VENDOR SUPPORT
To support vendor or customer specific tuning values, saptune supports 'drop-in' files residing in \fI/etc/saptune/extra\fP. All files found in \fI/etc/saptune/extra\fP are listed when running '\fBsaptune note list\fP'. All \fBnote options\fP are available for these files.

We simplified the file name syntax for these vendor files.
.br
Related to this we add 'header' support (see description of section [version] in saptune-note(5)) for the vendor files as already available for the Note definition files in /usr/share/saptune/notes to get a proper description during saptune option 'list'
.br
The old file names are still valid, but \fBdeprecated\fP. The support will be dropped in the near future. That means, files without a valid header information (see description of section [version] in saptune-note(5)) will be skipped in the future.

.SS
.RS 0
Syntax of the file names:
<NoteID>.conf
.br
e.g. V4711.conf

old syntax of the file names:
<NoteID>-<description>
.br
e.g. Vendor-Recommended_OS_Settings
.br
or   SAP4711-very_aromatic_tunings
.RE
.SS
.RS 0
Syntax of the file:
The content of the 'drop-in' file should be written in a INI file style with sections headed by '[section_name]' keywords. See saptune-note(5) to find the supported sections and their available options.

ATTENTION:
If renaming or removing an active (aka 'already applied') note definition file from the file system the \fBold\fP name of this note still remains in the configuration of saptune. This may lead to unexpected messages.
.br
So please always revert the note \fBbefore\fP renaming or removing it from the file system.
.br
Even if editing an active vendor or customer specific note definition file on the file system level, please do a revert of that note and then apply the Note again, to get the changes take effect.
.PP

.SS
.RS 0
customer specific solution definitions
.br
In addition to the vendor or customer specific note file definitions described previously saptune now supports vendor or customer specific \fBsolution definitions\fP by using 'drop-in' files in \fI/etc/saptune/extra\fP. All solutions found in \fI/etc/saptune/extra\fP are listed when running '\fBsaptune solution list\fP'. All \fBsolution options\fP are available for these solutions.

.SS
.RS 0
Syntax of the solution definition file names:
<solutionName>.sol
.br
e.g. V4711.sol

.SH ATTENTION
Trento support:
If you plan to use Trento and its capability of checking the correctness of the configuration of your SAP environment please adapt the following solution name schema for your custom solutions.
.br
<saptune_shipped_solutionname>\fB_\fP<your_preferred_badge>.sol
.br
e.g. NETWEAVER_MyOwnSolution.sol

Syntax of the file:
The content of the custom specific solution files should be written in a INI file style with sections headed by '[section_name]' keywords.
.br
At the moment saptune supports two architectures - \fIArchX86\fP for the x86 platform and \fIArchPPC64LE\fP for 64-bit PowerPC little endian platform for the solution definitions.
.br
So possible sections for solution definitions are [version] (see description of section [version] in saptune-note(5)) for a brief description of the solutions, and [ArchX86] and [ArchPPC64LE] for the solution definitions.
.br
The solution itself is described as a list of note definition files separated by blanks. The solution \fBname\fP is defined by the filename without the \fI.sol\fP suffix. A solution is only valid and listed by '\fBsaptune solution list\fP', if all listed note definition files can be found in the working area or in \fI/etc/saptune/extra\fP.

e.g. 
filename is \fBNEWSOL1.sol\fP with content

[version]
.br
VERSION=1
.br
DATE=15.12.2020
.br
DESCRIPTION=My custom specific solution definitions
.br
REFERENCES=
.br
[ArchX86]
.br
1980196 CUSTOMNOTE1 CUSTOMNOTE2
.br
[ArchPPC64LE]
.br
1980196 CUSTOMNOTE1 CUSTOMNOTE2
.PP

.SH CHANGES
.TP
.B changelog
The changelog file of the saptune rpm package contains detailed information, what was changed between the various package versions. The command

rpm -q --changes saptune | more

will show the content of the file
.TP
.B version 3
With the update to saptune version 3 saptune does no longer use tuned(8) to restart after a system reboot. It is using its own systemd service named "saptune.service".
.br
So we now \fBdeprecated\fP all "DAEMON ACTIONS" like '\fIsaptune daemon start\fP'. These commands will still work as they are internally linked to the related "SERVICE ACTIONS" like '\fIsaptune service takeover\fP'. Please refer to the related section descriptions at the top of this man page.
.TP
.B version 3.1
With the update to saptune version 3.1 we \fBdeprecated\fP the actions '\fIsaptune note simulate\fP' and '\fIsaptune solution simulate\fP'.

.SH FILES
.PP
\fI/usr/share/saptune/schemas/1.0\fP
.RS 4
schemata defining the json output format available since saptune version 3.1
.RE
.PP
\fI/usr/share/saptune/notes\fP
.RS 4
part of the \fBPackage Area\fP
.br
the saptune SAP Note definitions, which are shipped by the saptune RPM package
.br
Please do not change the files located here. You will lose all your changes during a saptune package update.
.RE
.PP
\fI/usr/share/saptune/sols\fP
.RS 4
part of the \fBPackage Area\fP
.br
the saptune solution definitions, which are shipped by the saptune RPM package

Please do not change as maintenance updates of package saptune will overwrite these files without preserving any custom changes.
.RE
.PP
\fI/var/lib/saptune/working/notes\fP
.RS 4
part of the \fBWorking Area\fP
.br
the saptune SAP Note definitions, which can be listed by '\fBsaptune note list\fP'

The files are named with the number of their corresponding SAP Note (==NoteID).
.br
A description of the syntax and the available tuning options can be found in saptune-note(5)
.br
Please do not change the files located here. You will lose all your changes during a '\fBsaptune staging release\fP' command. Use override files to change parameter values if needed.
.RE
.PP
\fI/var/lib/saptune/working/sols\fP
.RS 4
part of the \fBWorking Area\fP
.br
the saptune solution definitions, which can be listed by '\fBsaptune solution list\fP'
.br
At the moment saptune supports two architectures - \fIArchX86\fP for the x86 platform and \fIArchPPC64LE\fP for 64-bit PowerPC little endian platform - with different solution definitions.

Please do not change the files located here as the command '\fBsaptune staging release\fP' may overwrite these files without preserving any custom changes. Use override files to change the note list of the solutions.
.RE
.PP
\fI/var/lib/saptune/staging/latests\fP
.RS 4
part of the \fBStaging Area\fP
.br
the saptune SAP Note or solution definitions, which are present in the Package Area but differ from the files in the Working Area.
.RE
.PP
\fI/etc/sysconfig/saptune\fP
.RS 4
the central saptune configuration file containing the information about the currently enabled notes and solutions, the order in which these notes are applied and the version of saptune currently used.
.br
ATTENTION:
the manual editing of this file will be \fBdeprecated\fP as the main configuration file will be (re)moved in the near future.
.br
Please use \fBsaptune configure\fP command instead of editing the file directly.
.RE
.PP
\fI/etc/saptune/extra\fP
.RS 4
vendor or customer specific tuning or solution definitions.
.br
Please see \fBVENDOR SUPPORT\fP above for more information.

You can use '\fBsaptune note create NoteID\fP' or '\fBsaptune solution create solutionName\fP' to create a new vendor or customer specific definition or '\fBsaptune note edit NoteID\fP' or '\fBsaptune solution edit solutionName\fP' to modify an already existing vendor or customer specific definition.
.RE
.PP
\fI/etc/saptune/override\fP
.RS 4
the saptune Note and solution definition override location.

If you need to customize the Note or solution definitions found in \fI/usr/share/saptune/notes\fP or \fI/usr/share/saptune/sols\fP or in \fI/etc/saptune/extra\fP, you can copy them to \fI/etc/saptune/override\fP and modify them as you need. Please stay with the original name of the Note or solution definition (the NoteID or solution name) and do \fBNOT\fP rename it.

Or use '\fBsaptune note customize NoteID\fP' or '\fBsaptune solution customize solutionName\fP' to do the job for you.
.RE
.PP
\fI/run/saptune/saved_state/\fP
\fI/run/saptune/parameter/\fP
.RS 4
saptune was designed to preserve the state of the system before starting the SAP specific tuning, so that it will be possible to restore this previous state of the system, if the SAP specific tuning is no longer needed or should be changed.

This system state is saved during the 'apply' operation of saptune in the saptune internal used files in /run/saptune/saved_state and /run/saptune/parameter. The content of these files highly depends on the previous state of the system.
.br
If the values are applied by saptune, no further monitoring of the system parameters are done, so changes of saptune relevant parameters will not be observed. If a SAP Note or a SAP solution should be reverted, then first the values read from the /run/saptune/saved_state and /run/saptune/parameter files will be applied to the system to restore the previous system state and then the corresponding save_state file will be removed.

Please do not change or remove files in this directory. The knowledge about the previous system state gets lost and the revert functionality of saptune will be destructed. So you will lose the capability to revert back the tunings saptune has done.
.RE

.SH NOTE
Using saptune within a pipe, the color information will be removed from the output.
.br
It is possible to change this behavior by using the command line option \fB--force-color\fP
.SH NOTE
When the values from the saptune Note definitions are applied to the system, no further monitoring of the system parameters are done. So changes of saptune relevant parameters by using the 'sysctl' command or by editing configuration files will not be observed. If the values set by saptune should be reverted, these unrecognized changed settings will be overwritten by the previous saved system settings from saptune.
.SH NOTE
To prevent unintended reload/restart of saptune during package installation/update of saptune or normal work, which will result in a short time period, where the system is not tuned for SAP workloads, it's possible to set the parameter \fBIGNORE_RELOAD\fP in the central saptune configuration file \fI/etc/sysconfig/saptune\fP.
.br
\fBIGNORE_RELOAD\fP is used to control the '\fBsystemctl reload saptune.service\fP' behavior.
.br
Default is \fBIGNORE_RELOAD="no"\fP, which means that the 'reload' is working as expected.
.br
If set to '\fByes\fP' a '\fBsystemctl reload saptune.service\fP' and a '\fBsaptune service restart\fP' will do \fBnothing\fP. The reason will be logged.
.br
Additional this parameter setting will prevent '\fBsystemctl restart saptune.service\fP' (which is a 'ExecStop' followed by 'ExecStart') called from macros used during the package installation/update of the saptune package from restarting the tuning.
.br
ATTENTION: Outside the saptune package installation '\fBsystemctl restart saptune.service\fP' can \fBnot\fP be blocked.

.SH ATTENTION
Higher or lower system values set by the system, the SAP installer or by the administrator using sysctl command or sysctl configuration files will be now \fBoverwritten\fP by saptune, if they are part of the applied Note definitions.

saptune now sets the values read from the Note definition files irrespective of already set higher system values. If you need other tuning values as defined in the Note definition files, please use the possibility to create \fBoverride\fP files, which contain the values you need.

.SH SEE ALSO
.NF
saptune-note(5) saptune-migrate(7) saptune(8)

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