ospackage/man/saptune-migrate.7
.\"/*
.\" * Copyright (c) 2017-2021 SUSE LLC.
.\" * All rights reserved
.\" * Authors: Sören 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-migrate" "7" "January 2021" "" "migration from saptune version 1 to saptune version 3"
.SH NAME
saptune\-migration \- migration of saptune version \fB1\fP to saptune version 3
.SH DESCRIPTION
As there are too many logical and structural changes between the saptune versions 1 and 3 the migration has to be planned carefully and performed manually.
To determine the current version please run 'saptune version'.
ATTENTION: If the saptune version reported back is \fB2\fP or higher \fBNO\fP migration is needed!
The section MIGRATION will guide you through the migration process step by step. The sections SOLUTIONS and SAP NOTES will help you planning the migration.
.SH FILES TO REMOVE AFTER MIGRATION
The package update from version 1 to version 3 creates or copies some files during post install to allows this smooth migration. But after finishing the migration these files should be removed manually.
.BI /etc/saptune/extra/SAP_BOBJ-SAP_Business_OBJects.conf
.PP
.BI /etc/saptune/extra/SAP_ASE-SAP_Adaptive_Server_Enterprise.conf
.PP
.BI /etc/tuned/saptune/tuned.conf
and the directory
.BI /etc/tuned/saptune
.PP
.BI /etc/sysconfig/saptune-note-*
.SH IMPORTANT
\fBOnly a migration from version 1 to version 3 is supported!\fP
.SH SOLUTIONS
The following solutions are shipped:
.TS
tab(:) box;
c | l | l
l | l | l.
SOLUTION:Version 1:Version 3
_
BOBJ:T{
1275776* 1557506** 1984787 SAP_BOBJ
T}:T{
941735 1771258 1984787 SAP_BOBJ
T}
HANA:T{
1275776* 1557506** 1984787 2205917
T}:T{
941735 1771258 1980196 1984787 2205917 2382421 2534844
T}
MAXDB:T{
1275776* 1557506** 1984787
T}:T{
941735 1771258 1984787
T}
NETWEAVER:T{
1275776* 1557506** 1984787
T}:T{
941735 1771258 1984787
T}
NETWEAVER+HANA:T{
-
T}:T{
941735 1771258 1980196 1984787 2205917 2382421 2534844
T}
S4HANA-APP+DB:T{
-
T}:T{
941735 1771258 1980196 1984787 2205917 2382421 2534844
T}
S4HANA-APPSERVER:T{
1275776* 1557506** 1984787
T}:T{
941735 1771258 1984787
T}
S4HANA-DBSERVER:T{
1275776* 1557506** 1984787 2205917
T}:T{
941735 1771258 1980196 1984787 2205917 2382421 2534844
T}
SAP-ASE:T{
1275776* 1557506** 1984787 2205917 SAP_ASE
T}:T{
941735 1410736 1680803 1771258 1984787
T}
.TE
* SAP Note \fB1275776\fP has been rewritten and therefore removed in version 3.
.HP 4
** SAP Note \fB1557506\fP has been removed from the solutions in version 3 because it is only required in a few workload specific use cases.
.PP
Note: In version 1 the solutions BOBJ and SAP-ASE were not available on ppc64 little-endian.
For details about the SAP Notes see section \fBSAP NOTES\fP.
.SH SAP NOTES
The following SAP Notes are shipped:
.TS
tab(:) box;
c | l | l | c
l | l | l | l
l | l | l | l
l | l | l | l
l | l s s
l | l l l
l | l l l
l | l l l
l | l l l
l | l l l
l | l l l
l | l l l
l | l l l
l | l l l
l | l | l | l.
SAP Note:v1:v3:comment
_
941735:no:yes:T{
newly introduced in version 3
T}
_
1275776:yes*:no:T{
This SAP Note has been rewritten and no longer contains any settings.
.br
recommendations and therefore has been removed from version 3.
.br
The SAP Note is still part of version 1 with the former recommendations.
T}
:
:T{
The parameters are now covered by the following notes
T}
:kernel.sem:->:SAP_BOBJ (new default value)
:kernel.shmall:->:941735 (now fixed value)
:kernel.shmmax:->:T{
941735 and SAP_BOBJ (new default value)
T}
:T{
nofile for @sapsys, @sdba, @dba
T}:->:1771258 (new default value)
:vm.max_map_count:->:1980196 (same default value)
:VSZ_TMPFS_PERCENT:->:941735 (same default value)
:SHM_COUNT_REF_VALUE:->:T{
2534844(as kernel.shmmni with new default value)
T}
:T{
To replace 1275776, you can use:
.br
941735 1980196 2534844 1557506 1771258
T}
_
1410736:no:yes:T{
newly introduced in version 3
T}
_
1557506:yes:yes:T{
In version 3 only the HANA formula is used.
T}
_
1680803:no:yes:T{
newly introduced in version 3
T}
_
1771258:no:yes:T{
newly introduced in version 3
T}
_
1805750:no:yes:T{
newly introduced in version 3
T}
_
1980196:no:yes:T{
newly introduced in version 3
T}
_
1984787:yes**:yes:T{
.br
In version 3 DefaultUserTaskMax is set/removed at SAP Note apply and a reboot is no longer required.
T}
_
2161991:yes**:yes:T{
same defaults between version 1 and 3
T}
_
2205917:yes*:yes:T{
In version 1 the configuration was partially hard coded and partially done by tuned (always enabled regardless if note was active or not!)
.br
In version 3 this done by saptune itself.
T}
_
2382421:no:yes:T{
newly introduced in version 3
T}
_
2534844:no:yes:T{
newly introduced in version 3
T}
_
SAP_ASE:yes:no:T{
Has been replaced by \fB1680803\fP in version 3. The same defaults, but 1680803 also covers
.br
net.ipv4.tcp_keepalive_intvl and
.br
net.ipv4.tcp_keepalive_time.
T}
_
SAP_BOBJ:yes:yes:T{
no changes between version 1 and 3
T}
_
SUSE-GUIDE-01:yes:no:T{
deprecated since not an official SAP recommendation
T}
_
SUSE-GUIDE-02:yes:no:T{
deprecated since not an official SAP recommendation
T}
.TE
* Configuration was partially hard coded in version 1.
.br
** Configuration was fully hard coded in version 1.
In version 1 part of configuration was hard coded or configurable via /etc/sysconfig/saptune-note-*, /etc/saptune/extra/{SAP_BOBJ-SAP_Business_OBJects.conf,SAP_ASE-SAP_Adaptive_Server_Enterprise.conf} and /etc/tuned/saptune/tuned.conf.
.br
Due to tuned CPU tuning (see SAP Note 2205917) was always active.
In version 3 everything can be configured via an override file in /etc/saptune/override/.
.br
For details and defaults read the configuration in the corresponding Note definition files in /usr/share/saptune/notes/.
Version 1 of saptune uses the following configurations:
1275776: /etc/sysconfig/saptune-note-1275776
The following parameters are hardcoded:
size of TMPFS_PERCENT : 75%
nofile limit @sapsys, @sdba, @dba : 32800 (if lower)
kernel.shmmax : VSZ*1024*1024*1024 (if lower, min. 20GB)
kernel.shmall : VSZ*1024*(1024/PSZ) (if lower, min. 20GB)
SHM_COUNT_REF_VALUE : max(2048, SHM_COUNT_REF_VALUE, 32768)
vm.max_map_count : 2147483647 (if lower)
kernel.sem : max(current,1250) max(current,256000) max(current,100) max(current,8192)
1557506: everything is configurable in /etc/sysconfig/saptune-note-1557506
1984787: no configuration file
systemd version : done on installation by RPM requirements
UserTasksMax : RPM installation creates /etc/systemd/login.d/sap.conf
2161991: no configuration file
The following parameters are hardcoded:
IO_SCHEDULER : noop
2205917: no configuration file
The following parameters are hardcoded:
THP : never
KSM : 0
numa_balancing : disable
The following parameters are handled by tuned:
[cpu] energy_perf_bias
[cpu] governor
[cpu] force_latency
[cpu] min_perf_pct
SAP_ASE: everything is configurable in /etc/saptune/extra/SAP_ASE-SAP_Adaptive_Server_Enterprise.conf
SAP_BOBJ: everything is configurable in /etc/saptune/extra/SAP_BOBJ-SAP_Business_OBJects.conf
.SH MIGRATION
.SS Migration Planning:
Before starting the migration, familiarize yourself with saptune version 3.
Please read the man pages of saptune(8) and saptune-note(5).
.br
Solutions of version 3 can encompass more SAP Notes then in version 1.
.br
Please check section SOLUTIONS for details. You might want to deselect some SAP Notes, change or disable parameters.
SAP notes are more comprehensive in version 3.
.br
Please check section SAP NOTES for details. You might want to change or disable parameters.
Some SAP notes have been removed in version 3.
.br
Please check section SAP NOTES for details. You might want to add your own configuration file.
In version 1 multiple solutions can be applied, in saptune version 3 only one at the same time.
.br
If you had multiple solutions in the past, choose the most suitable one and add additional notes.
Version 1 has changed system parameters only when the current value was lower.
.br
Version 3 will set the parameter always to the configured value, no matter the current value.
.br
.SS Migration Steps:
The following steps describe the easisest way to migrate from version 1 to version 3.
.nr step 1 1
.IP \n[step]. 4
Determine current solutions and SAP Notes for version 1 and plan the ones for version 3.
Use these commands to get a list of selected solutions and notes.
saptune solution list
saptune note list
Use the sections SOLUTIONS and SAP NOTES above to familiarize yourself with the changes and create a list
of the solution and SAP Notes you are going to use with version 3.
.IP \n+[step].
(Skip, if saptune defaults are acceptable) Check each chosen SAP Note and former configuration.
Verify that the shipped defaults of version 3 meet your requirements.
\fBSince saptune is running in version 1 prior to migration you cannot use 'saptune note show' yet. Please check the files in /usr/share/saptune/notes/ directly.\fP
Verify the version 1 configuration (see SAP NOTES above) for settings to carry over.
For step 8 you need to prepare a list with all parameters that have to be added, altered or disabled.
.IP \n+[step].
Revert *all* solutions and notes.
Use the following commands:
saptune solution revert <solution>
saptune note revert <note>
Please check if the following variables in /etc/sysconfig/saptune are empty:
TUNE_FOR_SOLUTIONS=""
TUNE_FOR_NOTES=""
NOTE_APPLY_ORDER=""
.IP \n+[step].
Change saptune version variable to "3".
Open /etc/sysconfig/saptune in an editor and set the variable SAPTUNE_VERSION from "1" to "3".
.IP \n+[step].
Remove the configuration directory /etc/tuned/saptune/.
During the package upgrade a comatibility configuration /etc/tuned/saptune/ was created, which
has to be removed to run version 3 properly.
It is possible that it was created manually in the past to alter the configuration.
In this case verify the configuration and extend your future saptune configuration (step 2).
Saptune version 3 performs all tuning settings itself and no longer uses tuned for tuning.
The line "#stv1tov2#" is in inidicator that the configuration file was created by the update process
and not manually.
.IP \n+[step].
Remove files which are not needed anymore.
\fBPlease copy each file to a safe location before deleting it! You might need it to check for former configuration values.\fP
- Delete the configuration files SAP_BOBJ-SAP_Business_OBJects.conf and SAP_ASE-SAP_Adaptive_Server_Enterprise.conf.
rm /etc/saptune/extra/{SAP_BOBJ-SAP_Business_OBJects.conf,SAP_ASE-SAP_Adaptive_Server_Enterprise.conf}
- Delete old note configuration files.
rm /etc/sysconfig/saptune-note-*
- Delete /etc/systemd/logind.conf.d/sap.conf.
\fBBe aware that the file also is used by sapconf and is only created on package installation! Saptune will create it's own configuration file dynamically, if needed.\fP
rm /etc/systemd/logind.conf.d/sap.conf
- Delete obsolete log directory /var/log/saptune/.
rm -rf /var/log/saptune/*
- Remove 'nofile' entries for @sapsys, @sdba and @dba in /etc/security/limits.conf.
This is now handled by individual files in /etc/security/limits.d/.
- Remove all entries in /etc/sysctl.conf or files in /etc/sysctl.d/*.conf which are handled by saptune.
Consider moving SAP-related settings from there to a saptune extra file.
.IP \n+[step].
Restart saptune.service.
systemctl restart saptune.service
.IP \n+[step].
Apply the new configuration.
- (Skip, if saptune defaults are acceptable) Create override files for SAP Notes, if you need do change or disable parameters:
saptune note customize <id>
- (Skip, if saptune defaults are acceptable) Create your own configuration for parameters not coverd by an existing SAP Note:
saptune note create <id>
- Apply the chosen solution:
saptune solution apply <solution>
- Revert any SAP Note of the solution you do not need:
saptune note revert <id>
- Apply all aditional SAP Notes:
saptune note apply <id>
.IP \n+[step].
Use saptune verify to check your configuration:
saptune note verify
.IP \n+[step].
Check the log file /var/log/saptune/saptune.log for any errors.
.IP \n+[step].
(Optional) Do a reboot and verify that everything works as expected.
.RE
The migration is completed.
.br
Please verify, that any configuration management system or scripts which interact with saptune are adjusted accordingly.
.SH SEE ALSO
.NF
saptune-note(5) saptune(8) tuned(8) tuned-adm(8)
.SH AUTHOR
.NF
Soeren Schmidt <soeren.schmidt@suse.com>, Angela Briel <abriel@suse.com>