Documentation Home
MySQL and Linux/Unix
Related Documentation Download this Excerpt
PDF (US Ltr) - 374.0Kb
PDF (A4) - 376.2Kb


MySQL and Linux/Unix  / Installing MySQL on Linux  /  Managing MySQL Server with systemd

2.10 Managing MySQL Server with systemd

If you install MySQL using an RPM or Debian package on the following Linux platforms, server startup and shutdown is managed by systemd:

  • RPM package platforms:

    • Enterprise Linux variants version 7 and higher

    • SUSE Linux Enterprise Server 12 and higher

  • Debian family platforms:

    • Debian platforms

    • Ubuntu platforms

If you install MySQL from a generic binary distribution on a platform that uses systemd, you can manually configure systemd support for MySQL following the instructions provided in the post-installation setup section of theMySQL 5.7 Secure Deployment Guide.

If you install MySQL from a source distribution on a platform that uses systemd, obtain systemd support for MySQL by configuring the distribution using the-DWITH_SYSTEMD=1CMake option. SeeMySQL Source-Configuration Options.

The following discussion covers these topics:

Note

On platforms for which systemd support for MySQL is installed, scripts such asmysqld_safe and the System V initialization script are unnecessary and are not installed. For example,mysqld_safe can handle server restarts, but systemd provides the same capability, and does so in a manner consistent with management of other services rather than by using an application-specific program.

One implication of the non-use ofmysqld_safe on platforms that use systemd for server management is that use of[mysqld_safe] or[safe_mysqld] sections in option files is not supported and might lead to unexpected behavior.

Because systemd has the capability of managing multiple MySQL instances on platforms for which systemd support for MySQL is installed,mysqld_multi andmysqld_multi.server are unnecessary and are not installed.

Overview of systemd

systemd provides automatic MySQL server startup and shutdown. It also enables manual server management using thesystemctl command. For example:

systemctl {start|stop|restart|status} mysqld

Alternatively, use theservice command (with the arguments reversed), which is compatible with System V systems:

service mysqld {start|stop|restart|status}
Note

For thesystemctl orservice commands, if the MySQL service name is notmysqld, use the appropriate name. For example, usemysql rather thanmysqld on Debian-based and SLES systems.

Support for systemd includes these files:

  • mysqld.service (RPM platforms),mysql.service (Debian platforms): systemd service unit configuration file, with details about the MySQL service.

  • mysqld@.service (RPM platforms),mysql@.service (Debian platforms): Likemysqld.service ormysql.service, but used for managing multiple MySQL instances.

  • mysqld.tmpfiles.d: File containing information to support thetmpfiles feature. This file is installed under the namemysql.conf.

  • mysqld_pre_systemd (RPM platforms),mysql-system-start (Debian platforms): Support script for the unit file. This script assists in creating the error log file only if the log location matches a pattern (/var/log/mysql*.log for RPM platforms,/var/log/mysql/*.log for Debian platforms). In other cases, the error log directory must be writable or the error log must be present and writable for the user running themysqld process.

Configuring systemd for MySQL

To add or change systemd options for MySQL, these methods are available:

  • Use a localized systemd configuration file.

  • Arrange for systemd to set environment variables for the MySQL server process.

  • Set theMYSQLD_OPTS systemd variable.

To use a localized systemd configuration file, create the/etc/systemd/system/mysqld.service.d directory if it does not exist. In that directory, create a file that contains a[Service] section listing the desired settings. For example:

[Service]LimitNOFILE=max_open_filesPIDFile=/path/to/pid/fileNice=nice_levelLimitCore=core_file_limitEnvironment="LD_PRELOAD=/path/to/malloc/library"Environment="TZ=time_zone_setting"

The discussion here usesoverride.conf as the name of this file. Newer versions of systemd support the following command, which opens an editor and permits you to edit the file:

systemctl edit mysqld  # RPM platformssystemctl edit mysql   # Debian platforms

Whenever you create or changeoverride.conf, reload the systemd configuration, then tell systemd to restart the MySQL service:

systemctl daemon-reloadsystemctl restart mysqld  # RPM platformssystemctl restart mysql   # Debian platforms

With systemd, theoverride.conf configuration method must be used for certain parameters, rather than settings in a[mysqld],[mysqld_safe], or[safe_mysqld] group in a MySQL option file:

  • For some parameters,override.conf must be used because systemd itself must know their values and it cannot read MySQL option files to get them.

  • Parameters that specify values otherwise settable only using options known tomysqld_safe must be specified using systemd because there is no correspondingmysqld parameter.

For additional information about using systemd rather thanmysqld_safe, seeMigrating from mysqld_safe to systemd.

You can set the following parameters inoverride.conf:

  • To specify the process ID file:

    • As of MySQL 5.7.10: Useoverride.conf and change bothPIDFile andExecStart to name the PID file path name. Any setting of the process ID file in MySQL option files is ignored. To modifyExecStart, it must first be cleared. For example:

      [Service]PIDFile=/var/run/mysqld/mysqld-custom.pidExecStart=ExecStart=/usr/sbin/mysqld --pid-file=/var/run/mysqld/mysqld-custom.pid $MYSQLD_OPTS
    • Before MySQL 5.7.10: UsePIDFile inoverride.conf rather than the--pid-file option formysqld ormysqld_safe. systemd must know the PID file location so that it can restart or stop the server. If the PID file value is specified in a MySQL option file, the value must match thePIDFile value or MySQL startup may fail.

  • To set the number of file descriptors available to the MySQL server, useLimitNOFILE inoverride.conf rather than theopen_files_limit system variable formysqld or--open-files-limit option formysqld_safe.

  • To set the maximum core file size, useLimitCore inoverride.conf rather than the--core-file-size option formysqld_safe.

  • To set the scheduling priority for the MySQL server, useNice inoverride.conf rather than the--nice option formysqld_safe.

Some MySQL parameters are configured using environment variables:

  • LD_PRELOAD: Set this variable if the MySQL server should use a specific memory-allocation library.

  • TZ: Set this variable to specify the default time zone for the server.

There are multiple ways to specify environment variable values for use by the MySQL server process managed by systemd:

  • UseEnvironment lines in theoverride.conf file. For the syntax, see the example in the preceding discussion that describes how to use this file.

  • Specify the values in the/etc/sysconfig/mysql file (create the file if it does not exist). Assign values using the following syntax:

    LD_PRELOAD=/path/to/malloc/libraryTZ=time_zone_setting

    After modifying/etc/sysconfig/mysql, restart the server to make the changes effective:

    systemctl restart mysqld  # RPM platformssystemctl restart mysql   # Debian platforms

To specify options formysqld without modifying systemd configuration files directly, set or unset theMYSQLD_OPTS systemd variable. For example:

systemctl set-environment MYSQLD_OPTS="--general_log=1"systemctl unset-environment MYSQLD_OPTS

MYSQLD_OPTS can also be set in the/etc/sysconfig/mysql file.

After modifying the systemd environment, restart the server to make the changes effective:

systemctl restart mysqld  # RPM platformssystemctl restart mysql   # Debian platforms

For platforms that use systemd, the data directory is initialized if empty at server startup. This might be a problem if the data directory is a remote mount that has temporarily disappeared: The mount point would appear to be an empty data directory, which then would be initialized as a new data directory. As of MySQL 5.7.20, to suppress this automatic initialization behavior, specify the following line in the/etc/sysconfig/mysql file (create the file if it does not exist):

NO_INIT=true

Configuring Multiple MySQL Instances Using systemd

This section describes how to configure systemd for multiple instances of MySQL.

Note

Because systemd has the capability of managing multiple MySQL instances on platforms for which systemd support is installed,mysqld_multi andmysqld_multi.server are unnecessary and are not installed. This is true as of MySQL 5.7.13 for RPM platforms, 5.7.19 for Debian platforms.

To use multiple-instance capability, modify themy.cnf option file to include configuration of key options for each instance. These file locations are typical:

  • /etc/my.cnf or/etc/mysql/my.cnf (RPM platforms)

  • /etc/mysql/mysql.conf.d/mysqld.cnf (Debian platforms)

For example, to manage two instances namedreplica01 andreplica02, add something like this to the option file:

RPM platforms:

[mysqld@replica01]datadir=/var/lib/mysql-replica01socket=/var/lib/mysql-replica01/mysql.sockport=3307log-error=/var/log/mysqld-replica01.log[mysqld@replica02]datadir=/var/lib/mysql-replica02socket=/var/lib/mysql-replica02/mysql.sockport=3308log-error=/var/log/mysqld-replica02.log

Debian platforms:

[mysqld@replica01]datadir=/var/lib/mysql-replica01socket=/var/lib/mysql-replica01/mysql.sockport=3307log-error=/var/log/mysql/replica01.log[mysqld@replica02]datadir=/var/lib/mysql-replica02socket=/var/lib/mysql-replica02/mysql.sockport=3308log-error=/var/log/mysql/replica02.log

The replica names shown here use@ as the delimiter because that is the only delimiter supported by systemd.

Instances then are managed by normal systemd commands, such as:

systemctl start mysqld@replica01systemctl start mysqld@replica02

To enable instances to run at boot time, do this:

systemctl enable mysqld@replica01systemctl enable mysqld@replica02

Use of wildcards is also supported. For example, this command displays the status of all replica instances:

systemctl status 'mysqld@replica*'

For management of multiple MySQL instances on the same machine, systemd automatically uses a different unit file:

  • mysqld@.service rather thanmysqld.service (RPM platforms)

  • mysql@.service rather thanmysql.service (Debian platforms)

In the unit file,%I and%i reference the parameter passed in after the@ marker and are used to manage the specific instance. For a command such as this:

systemctl start mysqld@replica01

systemd starts the server using a command such as this:

mysqld --defaults-group-suffix=@%I ...

The result is that the[server],[mysqld], and[mysqld@replica01] option groups are read and used for that instance of the service.

Note

On Debian platforms, AppArmor prevents the server from reading or writing/var/lib/mysql-replica*, or anything other than the default locations. To address this, you must customize or disable the profile in/etc/apparmor.d/usr.sbin.mysqld.

Note

On Debian platforms, the packaging scripts for MySQL uninstallation cannot currently handlemysqld@ instances. Before removing or upgrading the package, you must stop any extra instances manually first.

Migrating from mysqld_safe to systemd

Becausemysqld_safe is not installed on platforms that use systemd to manage MySQL, options previously specified for that program (for example, in an[mysqld_safe] or[safe_mysqld] option group) must be specified another way:

  • Somemysqld_safe options are also understood bymysqld and can be moved from the[mysqld_safe] or[safe_mysqld] option group to the[mysqld] group. This doesnot include--pid-file,--open-files-limit, or--nice. To specify those options, use theoverride.conf systemd file, described previously.

    Note

    On systemd platforms, use of[mysqld_safe] and[safe_mysqld] option groups is not supported and may lead to unexpected behavior.

  • For somemysqld_safe options, there are similarmysqld options. For example, themysqld_safe option for enablingsyslog logging is--syslog, which is deprecated. Formysqld, enable thelog_syslog system variable instead. For details, seeThe Error Log.

  • mysqld_safe options not understood bymysqld can be specified inoverride.conf or environment variables. For example, withmysqld_safe, if the server should use a specific memory allocation library, this is specified using the--malloc-lib option. For installations that manage the server with systemd, arrange to set theLD_PRELOAD environment variable instead, as described previously.