.TH "MYSQLFAILOVER" "1" "May 09, 2012" "1.0.3" "MySQL Utilities" .SH NAME mysqlfailover \- Automatic replication health monitoring and failover . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" Man page generated from reStructeredText. . .SH SYNOPSIS .sp .nf .ft C mysqlfailover [options] .ft P .fi .SH DESCRIPTION .sp This utility permits users to perform replication health monitoring and automatic failover on a replication topology consisting of a master and its slaves. The utility is designed to run interactively or continuously refreshing the health information at periodic intervals. Its primary mission is to monitor the master for failure and when a failure occurs, execute failover to the best slave available. The utility accepts a list of slaves to be considered the candidate slave. .sp This utility is designed to work exclusively for servers that support global transaction identifiers (GTIDs) and have GTID_MODE=ON. MySQL server versions 5.6.5 and higher support GTIDs. See the MySQL server online reference manual for more information about setting up replication with GTIDs enabled. .sp The user can specify the interval in seconds to use for detecting the master status and generating the health report using the \fI\%--interval\fP option. At each interval, the utility will check to see if the server is alive via a ping operation followed by a check of the connector to detect if the server is still reachable. The ping operation can be controlled with the \fI\-\-ping\fP option (see below). .sp If the master is found to be offline or unreachable, the utility will execute one of the following actions based on the value of the \fI\%--failover-mode\fP option. .sp \fBauto\fP Execute automatic failover to the list of candidates first and if no slaves are viable, continue to locate a viable candidate from the list of slaves. If no slaves are found to be a viable candidate, the utility will generate and error and exit. .sp Once a candidate is found, the utility will conduct failover to the best slave. The command will test each candidate slave listed for the prerequisites. Once a candidate slave is elected, it is made a slave of each of the other slaves thereby collecting any transactions executed on other slaves but not the candidate. In this way, the candidate becomes the most up\-to\-date slave. .sp \fBelect\fP This mode is the same as auto except if no candidates specified in the list of candidate slaves are viable, it does not check the remaining slaves and generates and error and exits. .sp \fBfail\fP This mode produces an error and does not failover when the master is downed. This mode is used to provide periodic health monitoring without the failover action taken. .sp For all options that permit specifying multiple servers, the options require a comma\-separated list of connection parameters in the following form where the password, port, and socket are optional.: .sp .nf .ft C <*user*>[:<*passwd*>]@<*host*>[:<*port*>][:<*socket*>], .ft P .fi .sp The utility permits users to discover slaves connected to the master. In order to use the discover slaves feature, all slaves must use the \-\-report\-host and \-\-report\-port startup variables to specify the correct hostname and ip port of the slave. If these are missing or report the incorrect information, the slaves health may not be reported correctly or the slave may not be listed at all. The discover slaves feature ignores any slaves it cannot connect to. .sp The discover slaves feature is run automatically on each interval. .sp The utility permits the user to specify an external script to execute before and after the switchover and failover commands. The user can specify these with the \fI\-\-exec\-before\fP and \fI\-\-exec\-after\fP options. The return code of the script is used to determine success thus each script must report 0 (success) to be considered successful. If a script returns a value other than 0, the result code is presented in an error message. .sp The utility also permits the user to specify a script to be used for detecting a downed master or an application\-level event to trigger failover. This can be specified using the \fI\%--exec-fail-check\fP option. The return code for the script is used to invoke failover. A return code of 0 indicates failover should not take place. A return code other than 0 indicates failover should take place. This is checked at the start of each interval if a script is supplied. The timeout option is not used in this case and the script is run once at the start of each interval. .sp The utility permits the user to log all actions taken during the commands. The \fI\-\-log\fP option requires a valid path and file name of the file to use for logging operations. The log is active only when this option is specified. The option \fI\-\-log\-age\fP specifies the age in days that log entries are kept. The default is seven (7) days. Older entries are automatically deleted from the log file (but only if the \fI\-\-log\fP option is specified). .sp The format of the log file includes the date and time of the event, the level of the event (informational \- INFO, warning \- WARN, error \- ERROR, critical failure \- CRITICAL), and the message reported by the utility. .sp The interface provides the user with a number of options for displaying additional information. The user can choose to see the replication health report (default), or choose to see the list of GTIDs in use, the UUIDs in use, and if logging is enabled the contents of the log file. Each of these reports is described below. .sp \fBhealth\fP Display the replication health of the topology. This report is the default view for the interface. By default, this includes the host name, port, role (MASTER or SLAVE) of the server, state of the server (UP = is connected, WARN = not connected but can ping, DOWN = not connected and cannot ping), the GTID_MODE, and health state. .sp The master health state is based on the following; if GTID_MODE=ON, the server must have binary log enabled, and there must exist a user with the REPLICATE SLAVE privilege. .sp The slave health state is based on the following; the IO_THREAD and SQL_THREADS must be running, it must be connected to the master, there are no errors, the slave delay for non\-gtid enabled scenarios is not more than the threshold provided by the \fI\-\-max\-position\fP and the slave is reading the correct master log file, and slave delay is not more than the \fI\-\-seconds\-behind\fP threshold option. .sp At each interval, if the discover slaves option was specified at startup and new slaves are discovered, the health report is refreshed. .sp \fBgtid\fP Display the contents of the GTID variables, @@GLOBAL.GTID_DONE, @@GLOBAL.GTID_LOST, and @@GLOBAL.GTID_OWNED. .sp \fBUUID\fP Display universally unique identifiers (UUIDs) for all servers. .sp \fBLog\fP This option is visible only if the \fI\-\-log\fP option is specified. Show the contents of the log file. This can be helpful to see at a later time when failover occurred and the actions or messages recorded at the time. .sp The user interface is designed to match the size of the terminal window in which it is run. A refresh option is provided to permit users to resize their terminal windows or refresh the display at any time. However, the interface will automatically resize to the terminal window on each interval. .sp The interface will display the name of the utility, the master\(aqs status including binary log file, position, and filters as well as the date and time of the next interval event. .sp The interface will also permit the user to scroll up or down through a list longer than what the terminal window permits. When a long list is presented, the scroll options become enabled. The user can scroll the list up with the up arrow key and down with the down arrow key. .sp Use the \fI\-\-verbose\fP option to see additional information in the health report and additional messages during failover. .SH OPTIONS .sp \fBmysqlfailover\fP accepts the following command\-line options: .INDENT 0.0 .TP .B \-\-help Display a help message and exit. .UNINDENT .INDENT 0.0 .TP .B \-\-candidates= Connection information for candidate slave servers for failover in the form: <\fIuser\fP>[:<\fIpasswd\fP>]@<\fIhost\fP>[:<\fIport\fP>][:<\fIsocket\fP>]. Valid only with failover command. List multiple slaves in comma\- separated list. .UNINDENT .INDENT 0.0 .TP .B \-\-discover\-slaves\-login= At startup, query master for all registered slaves and use the user name and password specified to connect. Supply the user and password in the form <\fIuser\fP>[:<\fIpasswd\fP>]. For example, \-\-discover=joe:secret will use \(aqjoe\(aq as the user and \(aqsecret\(aq as the password for each discovered slave. .UNINDENT .INDENT 0.0 .TP .B \-\-exec\-after=