Update Administration-Tutorial.md

Removed manual TOC, updated and combined the starting and stopping sections,
removed leading space from code blocks.

Documentation/Tutorials/Administration-Tutorial.md

@@ -5,41 +5,37 @@ to a few of the common administration tasks. This is intended to be an
 introduction for administrators who are new to MariaDB MaxScale and not a
 reference to all the tasks that may be performed.
 
-- [Starting MariaDB MaxScale](#starting)
+## Starting and Stopping MariaDB MaxScale
-- [Stopping MariaDB MaxScale](#stopping)
-- [Checking The Status Of The MariaDB MaxScale Services](#checking)
-- [Persistent Connections](#persistent)
-- [What Clients Are Connected To MariaDB MaxScale](#clients)
-- [Rotating the Log File](#rotating)
-- [Taking A Database Server Out Of Use](#outofuse)
 
-<a name="starting"></a>
+### Systemd
-## Starting MariaDB MaxScale
 
-There are several ways to start MariaDB MaxScale, the most convenient mechanism
+Most modern operating systems support the Systemd interface.
-is probably using the Linux service interface. When a MariaDB MaxScale package
-is installed, the package manager will also install a script in /etc/init.d
-which may be used to start and stop MariaDB MaxScale either directly or via the
-service interface.
 
+**Starting MaxScale:**
 ```
-	$ service maxscale start
+systemctl start maxscale
 ```
 
-or
+**Stopping MaxScale:**
-
 ```
-	$ /etc/init.d/maxscale start
+systemctl stop maxscale
 ```
 
-It is also possible to start MariaDB MaxScale by executing the maxscale command
+The MaxScale service file is located in `/lib/systemd/system/maxscale.service`.
-itself. Running the executable /usr/bin/maxscale will result in MariaDB MaxScale
-running as a daemon process, unattached to the terminal in which it was started
-and using configuration files that it finds in the /etc directory.
 
-Options may be passed to the MariaDB MaxScale binary that alter this default
+### SysV
-behavior. For a full list of all parameters, refer to the MariaDB MaxScale help
+
-output by executing `maxscale --help`.
+Legacy platforms should use the service interface to start MaxScale.
+
+**Starting MaxScale:**
+```
+service maxscale start
+```
+
+**Stopping MaxScale:**
+```
+service maxscale stop
+```
 
 Additional command line arguments can be passed to MariaDB MaxScale with a
 configuration file placed at `/etc/sysconfig/maxscale` on RPM installations and
@@ -51,43 +47,18 @@ quotes. The file should only contain environment variable declarations.
 MAXSCALE_OPTIONS="--logdir=/home/maxscale/logs --piddir=/tmp --syslog=no"
 ```
 
-<a name="stopping"></a>
+Note that this is only supported on legacy SysV systems.
-## Stopping MariaDB MaxScale
 
-There are numerous ways in which MariaDB MaxScale can be stopped; using the
+## Stopping MariaDB MaxScale via MaxAdmin
-service interface, killing the process or by using the maxadmin utility.
-
-Stopping MariaDB MaxScale with the service interface is simply a case of using
-the service stop command or calling the init.d script with the stop argument.
-
-```
-	$ service maxscale stop
-```
-
-or
-
-```
-	$ /etc/init.d/maxscale stop
-```
-
-MariaDB MaxScale will also stop gracefully if it received a terminate signal, to
-find the process id of the MariaDB MaxScale server use the ps command or read
-the contents of the maxscale.pid file located in the /var/run/maxscale
-directory.
-
-```
-	$ kill `cat /var/run/maxscale/maxscale.pid`
-```
 
 In order to shutdown MariaDB MaxScale using the maxadmin command you may either
 connect with maxadmin in interactive mode or pass the "shutdown maxscale"
 command you wish to execute as an argument to maxadmin.
 
 ```
-	$ maxadmin shutdown maxscale
+sudo maxadmin shutdown maxscale
 ```
 
-<a name="checking"></a>
 ## Checking The Status Of The MariaDB MaxScale Services
 
 It is possible to use the maxadmin command to obtain statistics about the
@@ -122,7 +93,6 @@ Network listeners count as a user of the service, therefore there will always be
 one user per network port in which the service listens. More details can be
 obtained by using the "show service" command.
 
-<a name="persistent"></a>
 ## Persistent Connections
 
 When clients who are accessing a database system through MariaDB MaxScale make
@@ -162,7 +132,6 @@ the desired configuration. In exceptional cases this feature could be a problem.
 It is possible to have pools for as many servers as you wish, with configuration
 values in each server section.
 
-<a name="clients"></a>
 ## What Clients Are Connected To MariaDB MaxScale
 
 To determine what client are currently connected to MariaDB MaxScale, you can
@@ -189,7 +158,6 @@ maxadmin.
 	$
 ```
 
-<a name="rotating"></a>
 ## Rotating the Log File
 
 MariaDB MaxScale logs messages of different priority into a single log file.
@@ -206,20 +174,12 @@ Log file rotation is achieved by use of the "flush log" or “flush logs” comm
 in maxadmin.
 
 ```
-	$ maxadmin flush logs
+maxadmin flush logs
 ```
 
 As there currently is only the maxscale log, that is the only one that will be
 rotated.
 
-The maxscale log can also be flushed explicitly.
-
-```
-	$ maxadmin
-	MaxScale> flush log maxscale
-	MaxScale>
-```
-
 This may be integrated into the Linux _logrotate_ mechanism by adding a
 configuration file to the /etc/logrotate.d directory. If we assume we want to
 rotate the log files once per month and wish to keep 5 log files worth of
@@ -266,14 +226,13 @@ endscript
 }
 ```
 
-Since MaxScale currently renames the log file, the behaviour is not fully
+In older versions MaxScale renamed the log file, behaviour which is not fully
 compliant with the assumptions of logrotate and may lead to issues, depending on
 the used logrotate configuration file. From version 2.1 onwards, MaxScale will
 not itself rename the log file, but when the log is rotated, MaxScale will
 simply close and reopen (and truncate) the same log file. That will make the
 behaviour fully compliant with logrotate.
 
-<a name="outofuse"></a>
 ## Taking A Database Server Out Of Use
 
 MariaDB MaxScale supports the concept of maintenance mode for servers within a
@@ -286,8 +245,7 @@ may be done interactively within maxadmin or by passing the command on the
 command line.
 
 ```
-	MaxScale> set server dbserver3 maintenance
+sudo maxadmin set server dbserver3 maintenance
-	MaxScale>
 ```
 
 This will cause MariaDB MaxScale to stop routing any new requests to the server,
@@ -298,14 +256,8 @@ To bring the server back into service use the "clear server" command to clear
 the maintenance mode bit for that server.
 
 ```
-	MaxScale> clear server dbserver3 maintenance
+sudo maxadmin clear server dbserver3 maintenance
-	MaxScale>
 ```
 
-Note that maintenance mode is not persistent, if MariaDB MaxScale restarts when
+If multiple MariaDB MaxScale instances are configured to use the node
-a node is in maintenance mode a new instance of MariaDB MaxScale will not honor
+them maintenance mode must be set within each MariaDB MaxScale instance.
-this mode. If multiple MariaDB MaxScale instances are configured to use the node
-them maintenance mode must be set within each MariaDB MaxScale instance. However
-if multiple services within one MariaDB MaxScale instance are using the server
-then you only need set the maintenance mode once on the server for all services
-to take note of the mode change.