MDEV-11670: mariadb@.service remove alias, clean up documentation/order

Author: grooverdan

support-files/mariadb@.service.in

@@ -2,47 +2,36 @@
 #
 # Use this if you run multiple instances of MariaDB on a single server.
 #
+# This systemd service is not suitable for Galera as specialised SST recovery
+# scripts are needed.
+#
+#
 # Copyright notice:
 #
 # This file is free software; you can redistribute it and/or modify it
 # under the terms of the GNU Lesser General Public License as published by
 # the Free Software Foundation; either version 2.1 of the License, or
 # (at your option) any later version.
 #
+#
 # MULTI INSTANCES
 #
 # When multiple instances of MariaDB are running on a server they need to
 # ensure that they don't conflict with each other. This includes elements
-# like network ports, sockets and data directories. The systemd environment
-# variable MYSQLD_MULTI_INSTANCE controls each instance to ensure it is
-# run independently.
-#
-# This is not suitable for Galera as specialised SST recovery scripts are
-# needed.
-#
-# Suffix Mechanism (default):
-#
-# MYSQLD_MULTI_INSTANCE=--defaults-group-suffix=.%I --basedir=@prefix@
-#
-# With this option, the [mysqld.{instancename}] group is read from the default
-# configuration file.
-#
-# Command Line Mechanism:
-#
-# MYSQLD_MULTI_INSTANCE="--socket=/var/run/mysqld/%I.sock \
-#                        --datadir=/var/lib/mysqld-multi/%I \
-#                        --skip-networking"
-#
-# This is a good way run multiple instance where there is little difference
-# in configuration between instances.
+# like network ports, sockets and data directories listed under CONFLICTING
+# VARIABLES below. The systemd environment variable MYSQLD_MULTI_INSTANCE
+# controls each instance to ensure it is run independently. It is passed to
+# mysqld and mysql_install
 #
-# Configuration File Based Mechanism:
+# By default, a group suffix exists andw ithin the default configuration
+# files, a group [mysqld.{instancename}] is read for each service. Other
+# default groups, like [server.{instancename}] and [mariadb.{instancename}],
+# are also read. For each instance, one of the groups will need to contain
+# the conflicting variables listed below under CONFLICTING VARIABLES.
 #
-# MYSQLD_MULTI_INSTANCE=@sysconfdir@/my%I.cnf
+# The MYSQLD_MULTI_INSTANCE environment used is:
+#    Environment='MYSQLD_MULTI_INSTANCE=--defaults-group-suffix=.%I --basedir=@prefix@'
 #
-# Here you need to create a file for each instance. Recommend the systemd
-# configuration "ConditionPathExists=@sysconf@/my%I.cnf" at the same time to
-# ensure the file exists for the instance before starting.
 #
 # APPLYING YOUR MULTI INSTANCE MECHANISM
 #
@@ -55,18 +44,53 @@
 # Include any other settings you which to override. Directives like Exec* are
 # lists and adding a directive will append to the list. You can clear the list
 # by starting with "Directive=" and no value. Follow this by the list that you
-# do want.
+# do want. See the systemd.unit(5) manual page for more information.
 #
 # Then run "systemctl daemon-reload".
 #
-# Multi User Based Mechanism
+#
+# EXAMPLE MYSQLD_MULTI_INSTANCE CONFIGURATIONS
+#
+# Configuration File Based Mechanism:
+#
+# This has a configuration file per instance.
+#
+#   [Unit]
+#   ConditionPathExists=@sysconfdir@/my.%I.cnf
+#
+#   [Service]
+#   Environment=MYSQLD_MULTI_INSTANCE=--defaults-file=@sysconfdir@/my.%I.cnf
+#
+# Here you need to create a configuration file @sysconfdir@/my.%I.cnf for each
+# instance, each containing the conflicting variables to separate instances.
+#
+#
+# Multi User Based Mechanism:
+#
+# Here each user (the instance name) has their own mysql instance.
 #
 # Create instances in users home directory with abstract socket:
 #
 #   [Service]
 #   User=%I
 #   ProtectHome=false
-#   Environment=MYSQLD_MULTI_INSTANCE="--defaults-file=/home/%I/my%I.cnf --datadir=/home/%I/mysqldatadir --skip-networking --socket=@mysql-%I"
+#   ExecStartPre=
+#   ExecStartPre=@scriptdir@/mysql_install_db $MYSQLD_MULTI_INSTANCE \
+#       --auth-root-authentication-method=socket --auth-root-socket-user=%I
+#   Environment=MYSQLD_MULTI_INSTANCE="--defaults-file=/home/%I/my%I.cnf \
+#       --datadir=/home/%I/mysqldatadir --skip-networking --socket=@mysql-%I"
+#
+#
+# Command Line Mechanism:
+#
+# This is a good way run multiple instance where there is little difference
+# in configuration between instances.
+#
+#   [Service]
+#   Environment=MYSQLD_MULTI_INSTANCE="--socket=/var/run/mysqld/%I.sock \
+#                        --datadir=/var/lib/mysqld-multi/%I \
+#                        --skip-networking"
+#
 #
 # CONFLICTING VARIABLES
 #
@@ -76,6 +100,7 @@
 #   * port
 #   * datadir
 #
+#
 # PRE-10.3
 #
 # Before 10.3 MYSQLD_MULTI_INSTANCE was effectively --defaults-file=@sysconf2dir@/my%I.cnf
@@ -84,17 +109,20 @@
 # continue a file based multi-instance mysqld, recommend the Configuration File
 # Based Mechanism above and moving @sysconf2dir@/my%I.cnf files to @sysconfdir@/my%I.cnf.
 #
+#
 # SELINUX
 #
 # As basic selinux rules are written around a single instance of MariaDB you may need
 # to define labels for the files and network ports of all instances.
 #
 # See: https://mariadb.com/kb/en/library/what-to-do-if-mariadb-doesnt-start/#selinux
 #
+#
 # STARTING
 #
 # Start the instance: systemctl start mariadb@{instancename}.service
 #
+#
 # DOCUMENTATION:
 #
 # Read https://mariadb.com/kb/en/mariadb/systemd/ regarding customisation.
@@ -108,22 +136,20 @@ Documentation=man:mysqld(8)
 Documentation=https://mariadb.com/kb/en/library/systemd/
 After=network.target
 
-# Negated condition here is because 10.2 had @sysconf2dir@/my%I.cnf
+# Negated condition here is because 10.3 and before had @sysconf2dir@/my%I.cnf
 # as the configuration difference for multiple instances. This condition here
 # to prevent an accidental change during an upgrade in the case the user
 # created these file(s).
 #
 ## See Environment=MYSQLD_MULTI_INSTANCE below for current recommended options.
 ConditionPathExists=!@sysconf2dir@/my%I.cnf
 
+
 [Install]
 WantedBy=multi-user.target
-Alias=mysql.service
-Alias=mysqld.service
 
 
 [Service]
-
 ##############################################################################
 ## Core requirements
 ##
@@ -198,12 +224,12 @@ UMask=007
 PrivateTmp=false
 
 # Controlling how multiple instances are separated. See top of this file.
-# Note 1: This service isn't User=mysql be default so we need to be explicit.
+# Note 1: This service isn't User=mysql by default so we need to be explicit.
 # Note 2: we set --basedir to prevent probes that might trigger SELinux alarms,
 # per bug https://bugzilla.redhat.com/show_bug.cgi?id=547485. Its as an option
 # here as a user may want to use the MYSQLD_MULTI_INSTANCE to run multiple
 # versions.
-Environment=MYSQLD_MULTI_INSTANCE=--defaults-group-suffix=.%I --basedir=@prefix@
+Environment='MYSQLD_MULTI_INSTANCE=--defaults-group-suffix=.%I --basedir=@prefix@'
 
 # While you can override these, you shouldn't leave them empty as that
 # will default to root.