MYSQLMANAGER(1)

NAME
mysqlmanager - the MySQL Instance Manager

SYNOPSIS

mysqlmanager [options]

DESCRIPTION

The MySQL Instance Manager (IM) is a daemon running on a TCP/IP port, which serves for monitoring and management of MySQL Database Server instances. MySQL Instance Manager is available for Unix-like operating systems, and also on Windows as of MySQL 5.0.13.

MySQL Instance Manager is included in MySQL distributions from version 5.0.3, and can be used in place of the mysqld_safe script to start and stop the MySQL Server, even from a remote host. MySQL Instance Manager also implements the functionality (and most of the syntax) of the mysqld_multi script. A more detailed description of MySQL Instance Manager follows.

STARTING THE MYSQL SERVER WITH MYSQL INSTANCE MANAGER

Normally, the MySQL Database Server is started with the mysql.server script, which usually resides in the /etc/init.d/ folder. In MySQL 5.0.3 this script invokes mysqlmanager (the MySQL Instance Manager binary) to start MySQL. (In prior versions of MySQL the mysqld_safe script is used for this purpose.) Starting from MySQL 5.0.4 the behavior of the init script was changed again to incorporate both setup schemes. In version 5.0.4, the init startup script uses the old scheme (invoking mysqld_safe) by default, but one can set the use_mysqld_safe variable in the script to 0 (zero) in order to use the MySQL Instance Manager to start a server.

The Instance Manager's behavior in this case depends on the options given in the MySQL configuration file. If there is no configuration file, the MySQL Instance Manager creates an instance named mysqld and attempts to start it with default (compiled-in) configuration values. This means that the IM cannot guess the placement of mysqld if it is not installed in the default location. If you have installed the MySQL server in a non-standard location you should use a configuration file. See Section 1.5, “Installation Layouts”.

If there is a configuration file, the IM will parse the configuration file in search of [mysqld] sections (E.g. [mysqld], [mysqld1], [mysqld2], etc.) Each such section specifies an instance. At startup the IM will start all found instances. The IM stops all instances at shutdown by default.

Note that there is a special option mysqld-path (mysqld-path = path-to-mysqld-binary) which is recognized only by the IM. Use this variable to let the IM know where the mysqld binary resides. You should also set basedir and datadir options for the server.

The typical startup/shutdown cycle for a MySQL server with the MySQL Instance Manager enabled is as follows:

•   The MySQL Instance Manager is started with /etc/init.d/mysql script.

•   The MySQL Instance Manager starts all instances and monitors them.

•   If a server instance fails the MySQL Instance Manager restarts it.

•   If the MySQL Instance Manager is shut down (for instance with the /etc/init.d/mysql stop command), all instances are shut down by the MySQL Instance Manager.

CONNECTING TO THE MYSQL INSTANCE MANAGER AND CREATING USER ACCOUNTS

Communication with the MySQL Instance Manager is handled using the MySQL client-server protocol. As such, you can connect to the IM using the standard mysql client program, as well as the MySQL C API. The IM supports the version of the MySQL client-server protocol used by the client tools and libraries distributed along with mysql-4.1 or later.

The IM stores its user information in a password file. Default placement for the password file is /etc/mysqlmanager.passwd

Password entries look like the following:

petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848

To generate such an entry one should invoke IM with the --passwd option. Then the output can be redirected to the /etc/mysqlmanager.passwd file to add a new user. A sample command is given below.

Creating record for new user.
Enter user name: mike
Enter password: <password>
Re-type password: <password>

The following line is added to /etc/mysqlmanager.passwd:

mike:*00A51F3F48415C7D4E8908980D443C29C69B60C9

If there are no entries in the /etc/mysqlmanager.passwd file one cannot connect to the IM.

MYSQL INSTANCE MANAGER COMMAND-LINE OPTIONS

The MySQL Instance Manager supports a number of command line options. A brief listing is available by executing the ./mysqlmanager --help command. The following options are available:

•   --help, -?

    Display the help message and exit.

•   --bind-address=name

    Bind address to use for connections.

•   --default-mysqld-path=name

    On Unix, where to look for the MySQL Server binary, if no path was provided in the instance section. Example: default-mysqld-path = /usr/sbin/mysqld

•   --defaults-file=file_name

    Read Instance Manager and MySQL Server settings from the given file. All configuration changes by the Instance Manager will be made to this file. This should be used only as the first option to Instance Manager.

•   --install

    On Windows, install Instance Manager as a Windows service. This option was added in MySQL 5.0.11.

•   --log=name

    The path to the IM log file. This is used with the --run-as-service option.

•   --monitoring-interval=seconds

    Interval to monitor instances in seconds. Instance manager will try to connect to each of monitored instances to check whether they are alive/not hanging. In the case of a failure IM will perform several (in fact many) attempts to restart the instance. One can disable this behavior for particular instances with the nonguarded option in the appropriate instance section. If no value was given, the default of 20 seconds will be used.

•   --passwd, -P

    Prepare entry for passwd file and exit.

•   --password-file=name

    Look for the Instance Manager users and passwords in this file. The default file is /etc/mysqlmanager.passwd.

•   --pid-file=name

    The process ID file to use. By default, this file is named mysqlmanager.pid.

•   --port=port_num

    The port number to use for connections. (The default port number, assigned by IANA, is 2273).

•   --print-defaults

    Print the current defaults and exit. This should be used only as the first option to Instance Manager.

•   --remove

    On Windows, removes Instance Manager as a Windows service. This assumes that Instance Manager has been run with --install previously. This option was added in MySQL 5.0.11.

•   --run-as-service

    Daemonize and start the angel process. The angel process is simple and unlikely to crash. It will restart the IM itself in case of a failure.

•   --socket=name

    On Unix, the socket file to use for the connection. By default, the file is named /tmp/mysqlmanager.sock.

•   --standalone

    On Windows, run Instance Manager in standalone mode. This option was added in MySQL 5.0.13.

•   --user=name

    Username to start and run the mysqlmanager under. It is recommended to run mysqlmanager under the same user account used to run the mysqld server.

•   --version, -V

    Output version information and exit.

MYSQL INSTANCE MANAGER CONFIGURATION FILES

Instance Manager uses the standard my.cnf file. It uses the [manager] section to read options for itself and the [mysqld] sections to create instances. The [manager] section contains any of the options listed above. An example [manager] section is given below:

# MySQL Instance Manager options section
[manager]
default-mysqld-path = /usr/local/mysql/libexec/mysqld
socket=/tmp/manager.sock
pid-file=/tmp/manager.pid
password-file = /home/cps/.mysqlmanager.passwd
monitoring-interval = 2
port = 1999
bind-address = 192.168.1.5

Prior to MySQL 5.0.10, the MySQL Instance Manager read the same configuration files as the MySQL Server, including /etc/my.cnf, ~/.my.cnf, etc. As of MySQL 5.0.10, the MySQL Instance Manager reads and manages the /etc/my.cnf file only on Unix. On Windows, MySQL Instance Manager reads the my.ini file in the directory where Instance Manager is installed. The default option file location can be changed with the --defaults-file=file_name option.

Instance sections specify options given to each instance at startup. These are mainly common MySQL server options, but there are some IM-specific options:

•   mysqld-path = <path-to-mysqld-binary>

    The path to the mysqld server binary.

•   shutdown-delay = seconds

    The number of seconds IM should wait for the instance to shut down. The default is 35 seconds. After the delay expires, the IM assumes that the instance is hanging and attempts to kill -9 it. If you use InnoDB with large tables, you should increase this value.

•   nonguarded

    This option should be set if you want to disable IM monitoring functionality for a certain instance.

Several sample instance sections are given below.

[mysqld]
mysqld-path=/usr/local/mysql/libexec/mysqld
socket=/tmp/mysql.sock
port=3307
server_id=1
skip-stack-trace
core-file
skip-bdb
log-bin
log-error
log=mylog
log-slow-queries
[mysqld2]
nonguarded
port=3308
server_id=2
mysqld-path= /home/cps/mysql/trees/mysql-5.0/sql/mysqld
socket     = /tmp/mysql.sock5
pid-file   = /tmp/hostname.pid5
datadir= /home/cps/mysql_data/data_dir1
language=/home/cps/mysql/trees/mysql-5.0/sql/share/english
log-bin
log=/tmp/fordel.log

COMMANDS RECOGNIZED BY THE MYSQL INSTANCE MANAGER

Once you've set up a password file for the MySQL Instance Manager and the IM is running, you can connect to it. You can use the mysql client tool connect through a standard MySQL API. Below goes the list of commands the MySQL Instance Manager currently accepts, with samples.

•   START INSTANCE <instance_name>

    This command will attempt to start an instance:

    mysql> START INSTANCE mysqld4;
    Query OK, 0 rows affected (0,00 sec)

•   STOP INSTANCE <instance_name>

    This will attempt to stop an instance:

    mysql> STOP INSTANCE mysqld4;
    Query OK, 0 rows affected (0,00 sec)

•   SHOW INSTANCES

    Show the names of all loaded instances:

    mysql> show instances;
    +---------------+---------+
    | instance_name | status  |
    +---------------+---------+
    | mysqld3       | offline |
    | mysqld4       | online  |
    | mysqld2       | offline |
    +---------------+---------+
    3 rows in set (0,04 sec)

•   SHOW INSTANCE STATUS <instance_name>

    Show the status and the version info of selected instance:

    mysql> SHOW INSTANCE STATUS mysqld3;
    +---------------+--------+---------+
    | instance_name | status | version |
    +---------------+--------+---------+
    | mysqld3       | online | unknown |
    +---------------+--------+---------+
    1 row in set (0.00 sec)

•   SHOW INSTANCE OPTIONS <instance_name>

    Show options used by an instance:

    mysql> SHOW INSTANCE OPTIONS mysqld3;
    +---------------+---------------------------------------------------+
    | option_name   | value                                             |
    +---------------+---------------------------------------------------+
    | instance_name | mysqld3                                           |
    | mysqld-path   | /home/cps/mysql/trees/mysql-4.1/sql/mysqld        |
    | port          | 3309                                              |
    | socket        | /tmp/mysql.sock3                                  |
    | pid-file      | hostname.pid3                                     |
    | datadir       | /home/cps/mysql_data/data_dir1/                   |
    | language      | /home/cps/mysql/trees/mysql-4.1/sql/share/english |
    +---------------+---------------------------------------------------+
    7 rows in set (0.01 sec)

•   SHOW <instance_name> LOG FILES

    The command provides a listing of all log files used by the instance. The result set contains the path to the log file and the log file size. If no log file path is specified in the configuration file (i.e. log=/var/mysql.log), the IM tries to guess its placement. If the IM is unable to guess the logfile placement you should specify the log file location explicitly.

    mysql> SHOW mysqld LOG FILES;
    +-------------+------------------------------------+----------+
    | Logfile     | Path                               | Filesize |
    +-------------+------------------------------------+----------+
    | ERROR LOG   | /home/cps/var/mysql/owlet.err      | 9186     |
    | GENERAL LOG | /home/cps/var/mysql/owlet.log      | 471503   |
    | SLOW LOG    | /home/cps/var/mysql/owlet-slow.log | 4463     |
    +-------------+------------------------------------+----------+
    3 rows in set (0.01 sec)

•   SHOW <instance_name> LOG {ERROR | SLOW | GENERAL} size[,offset_from_end]

    This command retrieves a portion of the specified log file. Because most users are interested in the latest log messages, the size parameter defines the number of bytes you would like to retrieve starting from the log end. You can retrieve data from the middle of the log file by specifying the optional offset_from_end parameter. The following example retrieves 21 bytes of data, starting 23 bytes from the end of the log file and ending 2 bytes from the end of the log file:

    mysql> SHOW mysqld LOG GENERAL 21, 2;
    +---------------------+
    | Log                 |
    +---------------------+
    | using password: YES |
    +---------------------+
    1 row in set (0.00 sec)

•   SET instance_name.option_name=option_value

    This commands edits the specified instance's configuration file to change/add instance options. The IM assumes that the configuration file is located at /etc/my.cnf. You should check that the file exists and has appropriate permissions.

    mysql> SET mysqld2.port=3322;
    Query OK, 0 rows affected (0.00 sec)
    Changes made to the configuration file will not take effect until the MySQL server is restarted. In addition, these changes are not stored in the instance manager's local cache of instance settings until a FLUSH INSTANCES command is executed.

•   UNSET instance_name.option_name

    This command removes an option from an instance's configuration file.

    mysql> UNSET mysqld2.port;
    Query OK, 0 rows affected (0.00 sec)
    Changes made to the configuration file will not take effect until the MySQL server is restarted. In addition, these changes are not stored in the instance manager's local cache of instance settings until a FLUSH INSTANCES command is executed.

•   FLUSH INSTANCES

    This command forces IM to reread the configuration file and to refresh internal structures. This command should be performed after editing the configuration file. This command does not restart instances:

    mysql> FLUSH INSTANCES;
    Query OK, 0 rows affected (0.04 sec)

SEE ALSO
msql2mysql(1), myisamchk(1), myisamlog(1), myisampack(1), mysql(1), mysql.server(1), mysql_config(1), mysql_fix_privilege_tables(1), mysql_zap(1), mysqlaccess(1), mysqladmin(1), mysqlbinlog(1), mysqlcheck(1), mysqld(1), mysqld_multi(1), mysqld_safe(1), mysqldump(1), mysqlhotcopy(1), mysqlimport(1), mysqlshow(1), perror(1), replace(1), safe_mysqld(1)

For more information, please refer to the MySQL Reference Manual, which may already be installed locally and which is also available online at http://dev.mysql.com/doc/.

AUTHOR
MySQL AB (http://www.mysql.com/). This software comes with no warranty.