mariadb/man/mariadbd-safe.1

'\" t
.\"
.TH "\fBMARIADBD-SAFE\fR" "1" "3 September 2024" "MariaDB 11.4" "MariaDB Database System"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.\" mariadbd-safe
.\" tools: mariadbd-safe
.\" scripts
.SH "NAME"
mariadbd-safe \- MariaDB server startup script (mariadbd-safe is now a symlink to mariadbd-safe)
.SH "SYNOPSIS"
.HP \w'\fBmariadbd-safe\ \fR\fB\fIoptions\fR\fR\ 'u
\fBmariadbd-safe \fR\fB\fIoptions\fR\fR
.SH "DESCRIPTION"
.PP
\fBmariadbd-safe\fR
is the recommended way to start a
\fBmariadbd\fR
server on Unix\&.
\fBmariadbd-safe\fR
adds some safety features such as restarting the server when an error occurs and logging runtime information to an error log file\&. Descriptions of error logging is given later in this section\&.
.sp
\fBmariadbd-safe\fR
tries to start an executable named
\fBmariadbd\fR\&. To override the default behavior and specify explicitly the name of the server you want to run, specify a
\fB\-\-mariadbd\fR
or
\fB\-\-mariadbd\-version\fR
option to
\fBmariadbd-safe\fR\&. You can also use
\fB\-\-ledir\fR
to indicate the directory where
\fBmariadbd-safe\fR
should look for the server\&.
.PP
Many of the options to
\fBmariadbd-safe\fR
are the same as the options to
\fBmariadbd\fR\&.
.PP
Options unknown to
\fBmariadbd-safe\fR
are passed to
\fBmariadbd\fR
if they are specified on the command line, but ignored if they are specified in the
[mariadbd-safe] or [mariadbd_safe]
groups of an option file\&.
.PP
\fBmariadbd-safe\fR
reads all options from the
[mariadbd],
[server],
[mariadbd-safe] and [mariadbd_safe]
sections in option files\&. For example, if you specify a
[mariadbd]
section like this,
\fBmariadbd-safe\fR
will find and use the
\fB\-\-log\-error\fR
option:
.sp
.if n \{\
.RS 4
.\}
.nf
[mariadbd]
log\-error=error\&.log
.fi
.if n \{\
.RE
.\}
.PP
For backward compatibility,
\fBmariadbd-safe\fR
also reads
[safe_mariadbd]
sections, although you should rename such sections to
[mariadbd-safe]
in current installations\&.
.PP
\fBmariadbd-safe\fR
supports the options in the following list\&. It also reads option files and supports the options for processing them.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: help option
.\" help option: mariadbd-safe
\fB\-\-help\fR
.sp
Display a help message and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: basedir option
.\" basedir option: mariadbd-safe
\fB\-\-basedir=\fR\fB\fIpath\fR\fR
.sp
The path to the MariaDB installation directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: core-file-size option
.\" core-file-size option: mariadbd-safe
\fB\-\-core\-file\-size=\fR\fB\fIsize\fR\fR
.sp
The size of the core file that
\fBmariadbd\fR
should be able to create\&. The option value is passed to
\fBulimit \-c\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: crash-script option
.\" crash-script option: mariadbd-safe
\fB\-\-crash\-script=\fR\fB\fIfile\fR\fR
.sp
Script to call in the event of mariadbd crashing\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: datadir option
.\" datadir option: mariadbd-safe
\fB\-\-datadir=\fR\fB\fIpath\fR\fR
.sp
The path to the data directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: defaults-extra-file option
.\" defaults-extra-file option: mariadbd-safe
\fB\-\-defaults\-extra\-file=\fR\fB\fIpath\fR\fR
.sp
The name of an option file to be read in addition to the usual option files\&. This must be the first option on the command line if it is used\&. If the file does not exist or is otherwise inaccessible, the server will exit with an error\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: defaults-file option
.\" defaults-file option: mariadbd-safe
\fB\-\-defaults\-file=\fR\fB\fIfile_name\fR\fR
.sp
The name of an option file to be read instead of the usual option files\&. This must be the first option on the command line if it is used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: flush-caches option
.\" flush-caches option: mariadbd-safe
\fB\-\-flush\-caches\fR
.sp
Flush and purge buffers/caches before starting the server\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: ledir option
.\" ledir option: mariadbd-safe
\fB\-\-ledir=\fR\fB\fIpath\fR\fR
.sp
If
\fBmariadbd-safe\fR
cannot find the server, use this option to indicate the path name to the directory where the server is located\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: log-error option
.\" log-error option: mariadbd-safe
\fB\-\-log\-error=\fR\fB\fIfile_name\fR\fR
.sp
Write the error log to the given file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: malloc-lib option
.\" malloc-lib option: mariadbd-safe
\fB\-\-malloc\-lib=\fR\fB\fIlib\fR\fR
.sp
Preload shared library lib if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: mariadbd option
.\" mariadbd option: mariadbd-safe
\fB\-\-mariadbd=\fR\fB\fIprog_name\fR\fR
.sp
The name of the server program (in the
ledir
directory) that you want to start\&. This option is needed if you use the MariaDB binary distribution but have the data directory outside of the binary distribution\&. If
\fBmariadbd-safe\fR
cannot find the server, use the
\fB\-\-ledir\fR
option to indicate the path name to the directory where the server is located\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: mariadbd-version option
.\" mariadbd-version option: mariadbd-safe
\fB\-\-mariadbd\-version=\fR\fB\fIsuffix\fR\fR
.sp
This option is similar to the
\fB\-\-mariadbd\fR
option, but you specify only the suffix for the server program name\&. The basename is assumed to be
\fBmariadbd\fR\&. For example, if you use
\fB\-\-mariadbd\-version=debug\fR,
\fBmariadbd-safe\fR
starts the
\fBmariadbd\-debug\fR
program in the
ledir
directory\&. If the argument to
\fB\-\-mariadbd\-version\fR
is empty,
\fBmariadbd-safe\fR
uses
\fBmariadbd\fR
in the
ledir
directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: nice option
.\" nice option: mariadbd-safe
\fB\-\-nice=\fR\fB\fIpriority\fR\fR
.sp
Use the
nice
program to set the server's scheduling priority to the given value\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: no-auto-restart option
.\" no-auto-restart option: mariadbd-safe
\fB\-\-no\-auto\-restart\fR,
\fB\-\-nowatch\fR,
\fB\-\-no\-watch\fR
.sp
Exit after starting mariadbd\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: no-defaults option
.\" no-defaults option: mariadbd-safe
\fB\-\-no\-defaults\fR
.sp
Do not read any option files\&. This must be the first option on the command line if it is used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: numa-interleave option
.\" numa-interleave option: mariadbd-safe
\fB\-\-numa\-interleave\fR
.sp
Run mariadbd with its memory interleaved on all NUMA nodes\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: open-files-limit option
.\" open-files-limit option: mariadbd-safe
\fB\-\-open\-files\-limit=\fR\fB\fIcount\fR\fR
.sp
The number of files that
\fBmariadbd\fR
should be able to open\&. The option value is passed to
\fBulimit \-n\fR\&. Note that you need to start
\fBmariadbd-safe\fR
as
root
for this to work properly!
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: pid-file option
.\" pid-file option: mariadbd-safe
\fB\-\-pid\-file=\fR\fB\fIfile_name\fR\fR
.sp
The path name of the process ID file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: plugin-dir option
.\" plugin-dir option: mariadbd-safe
\fB\-\-plugin\-dir=\fIdir_name\fR
.sp
Directory for client-side plugins\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: port option
.\" port option: mariadbd-safe
\fB\-\-port=\fR\fB\fIport_num\fR\fR
.sp
The port number that the server should use when listening for TCP/IP connections\&. The port number must be 1024 or higher unless the server is started by the
root
system user\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: skip-kill-mariadbd option
.\" skip-kill-mariadbd option: mariadbd-safe
\fB\-\-skip\-kill\-mariadbd\fR
.sp
Do not try to kill stray
\fBmariadbd\fR
processes at startup\&. This option works only on Linux\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: socket option
.\" socket option: mariadbd-safe
\fB\-\-socket=\fR\fB\fIpath\fR\fR
.sp
The Unix socket file that the server should use when listening for local connections\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: syslog option
.\" syslog option: mariadbd-safe
.\" mariadbd-safe: skip-syslog option
.\" skip-syslog option: mariadbd-safe
\fB\-\-syslog\fR,
\fB\-\-skip\-syslog\fR
.sp
\fB\-\-syslog\fR
causes error messages to be sent to
syslog
on systems that support the
\fBlogger\fR
program\&.
\-\-skip\-syslog
suppresses the use of
syslog; messages are written to an error log file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: syslog-tag option
.\" syslog-tag option: mariadbd-safe
\fB\-\-syslog\-tag=\fR\fB\fItag\fR\fR
.sp
For logging to
syslog, messages from
\fBmariadbd-safe\fR
and
\fBmariadbd\fR
are written with a tag of
mariadbd-safe
and
mariadbd, respectively\&. To specify a suffix for the tag, use
\fB\-\-syslog\-tag=\fR\fB\fItag\fR\fR, which modifies the tags to be
mariadbd-safe\-\fItag\fR
and
mariadbd\-\fItag\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: timezone option
.\" timezone option: mariadbd-safe
\fB\-\-timezone=\fR\fB\fItimezone\fR\fR
.sp
Set the
TZ
time zone environment variable to the given option value\&. Consult your operating system documentation for legal time zone specification formats\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
.\" mariadbd-safe: user option
.\" user option: mariadbd-safe
\fB\-\-user={\fR\fB\fIuser_name\fR\fR\fB|\fR\fB\fIuser_id\fR\fR\fB}\fR
.sp
Run the
\fBmariadbd\fR
server as the user having the name
\fIuser_name\fR
or the numeric user ID
\fIuser_id\fR\&. (\(lqUser\(rq
in this context refers to a system login account, not a MariaDB user listed in the grant tables\&.)
.RE
.PP
If you execute
\fBmariadbd-safe\fR
with the
\fB\-\-defaults\-file\fR
or
\fB\-\-defaults\-extra\-file\fR
option to name an option file, the option must be the first one given on the command line or the option file will not be used\&. For example, this command will not use the named option file:
.sp
.if n \{\
.RS 4
.\}
.nf
mariadb> \fBmariadbd-safe \-\-port=\fR\fB\fIport_num\fR\fR\fB \-\-defaults\-file=\fR\fB\fIfile_name\fR\fR
.fi
.if n \{\
.RE
.\}
.PP
Instead, use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
mariadb> \fBmariadbd-safe \-\-defaults\-file=\fR\fB\fIfile_name\fR\fR\fB \-\-port=\fR\fB\fIport_num\fR\fR
.fi
.if n \{\
.RE
.\}
.PP
The
\fBmariadbd-safe\fR
script is written so that it normally can start a server that was installed from either a source or a binary distribution of MariaDB, even though these types of distributions typically install the server in slightly different locations\&.
\fBmariadbd-safe\fR
expects one of the following conditions to be true:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The server and databases can be found relative to the working directory (the directory from which
\fBmariadbd-safe\fR
is invoked)\&. For binary distributions,
\fBmariadbd-safe\fR
looks under its working directory for
bin
and
data
directories\&. For source distributions, it looks for
libexec
and
var
directories\&. This condition should be met if you execute
\fBmariadbd-safe\fR
from your MariaDB installation directory (for example,
/usr/local/mysql
for a binary distribution)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If the server and databases cannot be found relative to the working directory,
\fBmariadbd-safe\fR
attempts to locate them by absolute path names\&. Typical locations are
/usr/local/libexec
and
/usr/local/var\&. The actual locations are determined from the values configured into the distribution at the time it was built\&. They should be correct if MariaDB is installed in the location specified at configuration time\&.
.RE
.PP
Because
\fBmariadbd-safe\fR
tries to find the server and databases relative to its own working directory, you can install a binary distribution of MariaDB anywhere, as long as you run
\fBmariadbd-safe\fR
from the MariaDB installation directory:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBcd \fR\fB\fImysql_installation_directory\fR\fR
shell> \fBbin/mariadbd-safe &\fR
.fi
.if n \{\
.RE
.\}
.PP
If
\fBmariadbd-safe\fR
fails, even when invoked from the MariaDB installation directory, you can specify the
\fB\-\-ledir\fR
and
\fB\-\-datadir\fR
options to indicate the directories in which the server and databases are located on your system\&.
.PP
When you use
\fBmariadbd-safe\fR
to start
\fBmariadbd\fR,
\fBmariadbd-safe\fR
arranges for error (and notice) messages from itself and from
\fBmariadbd\fR
to go to the same destination\&.
.PP
There are several
\fBmariadbd-safe\fR
options for controlling the destination of these messages:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-syslog\fR: Write error messages to
syslog
on systems that support the
\fBlogger\fR
program\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-skip\-syslog\fR: Do not write error messages to
syslog\&. Messages are written to the default error log file (\fIhost_name\fR\&.err
in the data directory), or to a named file if the
\fB\-\-log\-error\fR
option is given\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-log\-error=\fR\fB\fIfile_name\fR\fR: Write error messages to the named error file\&.
.RE
.PP
If none of these options is given, the default is
\fB\-\-skip\-syslog\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
.sp .5v
.RE
.PP
If
\fB\-\-syslog\fR
and
\fB\-\-log\-error\fR
are both given, a warning is issued and
\fB\-\-log\-error\fR
takes precedence\&.
.PP
When
\fBmariadbd-safe\fR
writes a message, notices go to the logging destination (syslog
or the error log file) and
stdout\&. Errors go to the logging destination and
stderr\&.
.PP
Normally, you should not edit the
\fBmariadbd-safe\fR
script\&. Instead, configure
\fBmariadbd-safe\fR
by using command\-line options or options in the
[mariadbd-safe]
section of a
my\&.cnf
option file\&. In rare cases, it might be necessary to edit
\fBmariadbd-safe\fR
to get it to start the server properly\&. However, if you do this, your modified version of
\fBmariadbd-safe\fR
might be overwritten if you upgrade MariaDB in the future, so you should make a copy of your edited version that you can reinstall\&.
.PP
On NetWare,
\fBmariadbd-safe\fR
is a NetWare Loadable Module (NLM) that is ported from the original Unix shell script\&. It starts the server as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Runs a number of system and option checks\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Runs a check on
MyISAM
tables\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Provides a screen presence for the MariaDB server\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
Starts
\fBmariadbd\fR, monitors it, and restarts it if it terminates in error\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
Sends error messages from
\fBmariadbd\fR
to the
\fIhost_name\fR\&.err
file in the data directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
Sends
\fBmariadbd-safe\fR
screen output to the
\fIhost_name\fR\&.safe
file in the data directory\&.
.RE
.SH "COPYRIGHT"
.br
.PP
Copyright 2007-2008 MySQL AB, 2008-2010 Sun Microsystems, Inc., 2010-2024 MariaDB Foundation
.PP
This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
.PP
This documentation 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.
.PP
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA or see http://www.gnu.org/licenses/.
.sp
.SH "SEE ALSO"
For more information, please refer to the MariaDB Knowledge Base, available online at https://mariadb.com/kb/
.SH AUTHOR
MariaDB Foundation (http://www.mariadb.org/).