Below is the list of changes that have just been committed into a local
mysqldoc repository of root. When root does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html
ChangeSet
1.2898 05/04/29 09:17:59 Mike.Hillyer@stripped +1 -0
First run of the new instance manager doc.
Docs/manual.texi
1.2749 05/04/29 09:17:57 Mike.Hillyer@stripped +322 -3
First run of the new instance manager doc.
# This is a BitKeeper patch. What follows are the unified diffs for the
# set of deltas contained in the patch. The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: Mike.Hillyer
# Host: www.openwin.org
# Root: /home/mysqldoc/mysqldoc
--- 1.2748/Docs/manual.texi 2005-04-26 09:44:22 -06:00
+++ 1.2749/Docs/manual.texi 2005-04-29 09:17:57 -06:00
@@ -18308,6 +18308,7 @@
@menu
* Server-Side Scripts:: The MySQL Server and Server Startup Scripts
+* Instance Manager:: The MySQL Instance Manager
* Configuring MySQL:: Configuring the MySQL Server
* Server Shutdown:: The MySQL Server Shutdown Process
* Security:: General Security Issues
@@ -18321,7 +18322,7 @@
@end menu
-@node Server-Side Scripts, Configuring MySQL, MySQL Database Administration, MySQL Database Administration
+@node Server-Side Scripts, Instance Manager, MySQL Database Administration, MySQL Database Administration
@section The MySQL Server and Server Startup Scripts
@c TODO: describe mysql_secure_installation, make_binary_distribution here
@@ -19168,8 +19169,326 @@
@xref{Option files}.
+@node Instance Manager, Configuring MySQL, Server-Side Scripts, MySQL Database Administration
+@section The MySQL Instance Manager
-@node Configuring MySQL, Server Shutdown, Server-Side Scripts, MySQL Database Administration
+This section discusses use of the MySQL Instance Manager.
+
+@menu
+* Instance Manager Overview:: Instance Manager Overview
+* Instance Manager Startup Process:: Starting the MySQL Sever with MySQL Instance Manager
+* Instance Manager Security:: Connecting to the MySQL Instance Manager and Creating User Accounts
+* Instance Manager Command Line Options:: MySQL Instance Manager Command-Line Options
+* Instance Manager Configuration Files:: MySQL Instance Manager Configuration Files
+* Instance Manager Commands:: Commands Recognized by the MySQL Instance Manager
+@end menu
+
+@node Instance Manager Overview, Instance Manager Startup Process, Instance Manager, Instance Manager
+@subsection Instance Manager Overview
+
+
+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 currently available for unix-like operating systems.
+
+MySQL Instance Manager is included in MySQL distributions from version 5.0.3.
+MySQL Instance Manager can be used to start the MySQL Server
+instead of the mysqld_safe script. MySQL Instance Manager also implements the functionality
+(and most of the syntax) of the @command{mysqld_multi}
+script. A more detailed description of the MySQL Instance Manager follows.
+
+@node Instance Manager Startup Process, Instance Manager Security, Instance Manager Overview, Instance Manager
+@subsection Starting the MySQL Sever with MySQL Instance Manager
+
+Normally, the MySQL Database Server is started with the @command{mysql} script, which
+usually resides in the @code{/etc/init.d/} folder. In MySQL 5.0.3 this script
+invokes @command{mysqlmanager} (the MySQL Instance Manager binary) to start MySQL. In prior versions
+of MySQL the @command{mysqld_safe} script is used for this purpose. Starting from MySQL 5.0.4
+the behaviour of the init script was changed again to incorporate both setup
+schemes. In 5.0.4 the init startup script uses the old scheme (invoking
+@command{mysqld_safe}) by default, but one can set the @code{use_mysqld_safe} variable in
+the script to @code{0} to use the MySQL Instance Manager to start a server.
+
+Instance Manager behaviour 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 @code{mysqld} and attempts to start it with default
+(compiled-in) configuration values. This means that the IM cannot guess the
+placement of @command{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.
+
+If there is a configuration file, the IM will parse the configuration file in
+search of @code{[mysqld]} sections (E.g. @code{[mysqld]}, @code{[mysqld1]}, @code{[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 which is recognized only by the IM called @code{mysqld-path}
+(@code{mysqld-path = <path-to-mysqld-binary>}). Use this
+variable to let the IM know where the mysqld binary resides.
+You should also set @code{basedir} and @code{datadir} options for the server.
+
+The typical startup/shutdown cycle for a MySQL server with the MySQL Instance Manager enabled
+is as follows:
+
+@itemize @bullet
+@item
+The MySQL Instance Manager is started with @command{/etc/init.d/mysql} script.
+
+@item
+The MySQL Instance Manager starts all instances and monitors them.
+
+@item
+If a server instance fails the MySQL Instance Manager restarts it.
+
+@item
+If the MySQL Instance Manager is shut down (for instance with the @command{/etc/init.d/mysql stop} command), all
+instances are shut down by the MySQL Instance Manager.
+
+@end itemize
+
+@node Instance Manager Security, Instance Manager Command Line Options, Instance Manager Startup Process, Instance Manager
+@subsection 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 @command{mysql} client program, as well as the
+MySQL C API. The IM supports the new version of the MySQL client-server protocol,
+so one should use 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 @file{/etc/mysqlmanager.passwd}
+
+Password entries look like the following:
+
+@example
+petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848
+@end example
+
+To generate such an entry one should invoke IM with the @command{--passwd} option. Then
+the output can be redirected to the @file{/etc/mysqlmanager.passwd} file to add a
+new user. The sample command is given below.
+
+@example
+./mysqlmanager --passwd >> /etc/mysqlmanager.passwd
+Creating record for new user.
+Enter user name: mike
+Enter password: <password>
+Re-type password: <password>
+@end example
+
+The following line is added to @file{/etc/mysqlmanager.passwd}:
+
+@example
+mike:*00A51F3F48415C7D4E8908980D443C29C69B60C9
+@end example
+
+If there are no entries in the @file{/etc/mysqlmanager.passwd} file one cannot connect to
+the IM.
+
+@node Instance Manager Command Line Options, Instance Manager Configuration Files, Instance Manager Security, Instance Manager
+@subsection 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 @command{./mysqlmanager --help} command. The following commands are available:
+
+@table @code
+@item -?, --help
+Display the help and exit.
+
+@item --log=name
+Path to the IM log file. This used with the @command{--run-as-service} option.
+
+@item --pid-file=name
+Pid file to use. By default it is @file{mysqlmanager.pid}.
+
+@item --socket=name
+Socket file to use for connection. By default it is @file{/tmp/mysqlmanager.sock}.
+
+@item -P, --passwd
+Prepare entry for passwd file and exit.
+
+@item --bind-address=name
+Bind address to use for connections.
+
+@item --port=#
+Port number to use for connections (default port number, assigned by IANA, is 2273).
+
+@item --password-file=name
+Look for the Instance Manager users and passwords here. The default one is @file{/etc/mysqlmanager.passwd}.
+
+@item --default-mysqld-path=name
+Where to look for MySQL Server binary, if no path was provided in the instance section.
+E.g. @code{default-mysqld-path = /usr/sbin/mysqld}
+
+@item --monitoring-interval=#
+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 behaviour for particular instances with the @code{nonguarded} option in the appropriate instance
+section. If no value was given, the default of 20 seconds will be used.
+
+@item --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.
+
+@item --user=name
+Username to start and run the @command{mysqlmanager} under. It is recommended to run @command{mysqlmanager} under
+the same user account used to run the @command{mysqld} server.
+
+@item -V, --version
+Output version information and exit.
+@end table
+
+@node Instance Manager Configuration Files, Instance Manager Commands, Instance Manager Command Line Options, Instance Manager
+@subsection MySQL Instance Manager Configuration Files
+
+Instance Manager uses the standard @file{my.cnf} file. It uses the
+@code{[manager]} section to read options for itself and the @code{[mysqld]} sections to
+create instances. The @code{[manager]} section contains any of the options listed
+above. An example @code{[manager]} section is given below:
+
+@example
+# 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
+@end example
+
+Instance sections specify options given to each instance at startup.
+These are mainly common MySQL server options, but there are some IM-specific
+options:
+
+@table @code
+@item mysqld-path = <path-to-mysqld-binary>
+The path to the @command{mysqld} server binary.
+
+@item shutdown-delay = #
+A number of seconds IM should wait for the instance to shut down. Default time 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.
+
+@item nonguarded
+This option should be set if you want to disable IM monitoring functionality for a certain instance.
+@end table
+
+Several sample instance sections are given below.
+
+@example
+[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-4.1/sql/mysqld
+socket = /tmp/mysql.sock4
+pid-file = /tmp/hostname.pid4
+datadir= /home/cps/mysql_data/data_dir1
+language=/home/cps/mysql/trees/mysql-4.1/sql/share/english
+log-bin
+log=/tmp/fordel.log
+@end example
+
+@node Instance Manager Commands, , Instance Manager Configuration Files, Instance Manager
+@subsection 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 @command{mysql} client tool connect
+through a standard MySQL API. Below goes the list of commands the MySQL Instance Manager
+currently accepts, with samples.
+
+@table @code
+@item START INSTANCE <instance_name>
+This command will attempt to start an instance:
+
+@example
+mysql> start instance mysqld4;
+Query OK, 0 rows affected (0,00 sec)
+@end example
+
+@item STOP INSTANCE <instance_name>
+This will attempt to stop an instance:
+
+@example
+mysql> stop instance mysqld4;
+Query OK, 0 rows affected (0,00 sec)
+@end example
+
+@item SHOW INSTANCES
+Show the names of all loaded instances:
+
+@example
+mysql> show instances;
++---------------+---------+
+| instance_name | status |
++---------------+---------+
+| mysqld3 | offline |
+| mysqld4 | online |
+| mysqld2 | offline |
++---------------+---------+
+3 rows in set (0,04 sec)
+@end example
+
+@item SHOW INSTANCE STATUS <instance_name>
+Show the status and the version info of selected instance:
+
+@example
+mysql> show instance status mysqld3;
++---------------+--------+---------+
+| instance_name | status | version |
++---------------+--------+---------+
+| mysqld3 | online | unknown |
++---------------+--------+---------+
+1 row in set (0.00 sec)
+@end example
+
+@item SHOW INSTANCE OPTIONS <instance_name>
+Show options used by an instance:
+
+@example
+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)
+@end example
+
+@item 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:
+
+@example
+mysql> flush instances;
+Query OK, 0 rows affected (0.04 sec)
+@end example
+
+@end table
+
+@node Configuring MySQL, Server Shutdown, Instance Manager, MySQL Database Administration
@section Configuring the MySQL Server
This section discusses MySQL server configuration topics:
@@ -38642,7 +38961,7 @@
@item --test, -t
Don't actually pack the table, just test packing it.
-@item --tmp_dir=@var{path}, -T @var{path}
+@item --tmpdir=@var{path}, -T @var{path}
Use the named directory as the location in which to write the temporary table.
@item --verbose, -v
| Thread |
|---|
| • bk commit - mysqldoc tree (Mike.Hillyer:1.2898) | mhillyer | 29 Apr |
