Improved mysqld_multi documentation, especially the --example

section, which had gotten somewhat out-dated.

BitKeeper/etc/logging_ok

@@ -66,6 +66,7 @@ igor@hundin.mysql.fi
 igor@rurik.mysql.com
 ingo@mysql.com
 jan@hundin.mysql.fi
+jani@a193-229-222-105.elisa-laajakaista.fi
 jani@a193-229-222-2.elisa-laajakaista.fi
 jani@a80-186-24-72.elisa-laajakaista.fi
 jani@a80-186-41-201.elisa-laajakaista.fi

scripts/mysqld_multi.sh

@@ -4,7 +4,7 @@ use Getopt::Long;
 use POSIX qw(strftime);
 
 $|=1;
-$VER="2.10";
+$VER="2.11";
 
 $opt_config_file   = undef();
 $opt_example       = 0;
@@ -577,67 +577,73 @@ sub my_which
 sub example
 {
   print <<EOF;
-# This is an example of a my.cnf file on behalf of $my_progname.
-# This file should probably be in your home dir (~/.my.cnf) or /etc/my.cnf
-# Version $VER by Jani Tolonen
-# NOTES:
-# 1.Make sure that the MySQL user, who is stopping the mysqld services (e.g
-#   using the mysqladmin) have the same password and username for all the
-#   data directories accessed (to the 'mysql' database) And make sure that
-#   the user has the 'Shutdown_priv' privilege! If you have many data-
-#   directories and many different 'mysql' databases with different passwords
-#   for the MySQL 'root' user, you may want to create a common 'multi_admin'
-#   user for each using the same password (see below). Example how to do it:
-#   shell> mysql -u root -S /tmp/mysql.sock -proot_password -e
-#   "GRANT SHUTDOWN ON *.* TO multi_admin\@localhost IDENTIFIED BY 'multipass'"
-#   You will have to do the above for each mysqld running in each data
-#   directory, that you have (just change the socket, -S=...)
-#   See more detailed information from chapter:
-#   '6 The MySQL Access Privilege System' from the MySQL manual.
-# 2.pid-file is very important, if you are using mysqld_safe to start mysqld
-#   (e.g. --mysqld=mysqld_safe) Every mysqld should have it's own pid-file.
-#   The advantage using mysqld_safe instead of mysqld directly here is, that
-#   mysqld_safe 'guards' every mysqld process and will restart it, if mysqld
-#   process fails due to signal kill -9, or similar. (Like segmentation fault,
-#   which MySQL should never do, of course ;) Please note that mysqld_safe
-#   script may require that you start it from a certain place. This means that
-#   you may have to CD to a certain directory, before you start the
-#   mysqld_multi. If you have problems starting, please see the script.
-#   Check especially the lines:
-#   --------------------------------------------------------------------------
-#   MY_PWD=`pwd`
-#   Check if we are starting this relative (for the binary release)
-#   if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
-#   -x ./bin/mysqld
-#   --------------------------------------------------------------------------
-#   The above test should be successful, or you may encounter problems.
-# 3.Beware of the dangers starting multiple mysqlds in the same data directory.
-#   Use separate data directories, unless you *KNOW* what you are doing!
-# 4.The socket file and the TCP/IP port must be different for every mysqld.
-# 5.The first and fifth mysqld was intentionally left out from the example.
-#   You may have 'gaps' in the config file. This gives you more flexibility.
-#   The order in which the mysqlds are started or stopped depends on the order
-#   in which they appear in the config file.
-# 6.When you want to refer to a certain group with GNR with this program,
-#   just use the number in the end of the group name ( [mysqld# <== )
-# 7.You may want to use option '--user' for mysqld, but in order to do this
-#   you need to be root when you start this script. Having the option
-#   in the config file doesn't matter; you will just get a warning, if you are
-#   not the superuser and the mysqlds are started under *your* unix account.
-#   IMPORTANT: Make sure that the pid-file and the data directory are
-#   read+write(+execute for the latter one) accessible for *THAT* UNIX user,
-#   who the specific mysqld process is started as. *DON'T* use the UNIX root
-#   account for this, unless you *KNOW* what you are doing!
-# 8.MOST IMPORTANT: Make sure that you understand the meanings of the options
-#   that are passed to the mysqlds and why *WOULD YOU WANT* to have separate
-#   mysqld processes. Starting multiple mysqlds in one data directory *WON'T*
-#   give you extra performance in a threaded system!
+# This is an example of a my.cnf file for $my_progname.
+# Usually this file is located in home dir ~/.my.cnf or /etc/my.cnf
 #
+# SOME IMPORTANT NOTES FOLLOW:
+#
+# 1.COMMON USER
+#
+#   Make sure that the MySQL user, who is stopping the mysqld services, has
+#   the same password to all MySQL servers being accessed by $my_progname.
+#   This user needs to have the 'Shutdown_priv' -privilege, but for security
+#   reasons should have no other privileges. It is advised that you create a
+#   common 'multi_admin' user for all MySQL servers being controlled by
+#   $my_progname. Here is an example how to do it:
+#
+#   GRANT SHUTDOWN ON *.* TO multi_admin\@localhost IDENTIFIED BY 'password'
+#
+#   You will need to apply the above to all MySQL servers that are being
+#   controlled by $my_progname. 'multi_admin' will shutdown the servers
+#   using 'mysqladmin' -binary, when '$my_progname stop' is being called.
+#
+# 2.PID-FILE
+#
+#   If you are using mysqld_safe to start mysqld, make sure that every
+#   MySQL server has a separate pid-file. In order to use mysqld_safe
+#   via $my_progname, you need to use two options:
+#
+#   mysqld=/path/to/mysqld_safe
+#   ledir=/path/to/mysqld-binary/
+#
+#   ledir (library executable directory), is an option that only mysqld_safe
+#   accepts, so you will get an error if you try to pass it to mysqld directly.
+#   For this reason you might want to use the above options within [mysqld#]
+#   group directly.
+#
+# 3.DATA DIRECTORY
+#
+#   It is NOT advised to run many MySQL servers within the same data directory.
+#   You can do so, but please make sure to understand and deal with the
+#   underlying caveats. In short they are:
+#   - Speed penalty
+#   - Risk of table/data corruption
+#   - Data synchronising problems between the running servers
+#   - Heavily disk bound
+#   - Relies on the system (external) file locking
+#
+# 4.TCP/IP Port
+#
+#   Every server requires one and it must be unique.
+#
+# 5.[mysqld#] Groups
+#
+#   In the example below the first and the fifth mysqld group was
+#   intentionally left out. You may have 'gaps' in the config file. This
+#   gives you more flexibility.
+#
+# 6.MySQL Server User
+#
+#   You can pass the user=... option inside [mysqld#] groups. This
+#   can be very handy in some cases, but then you need to run $my_progname
+#   as UNIX root.
+#
+
 [mysqld_multi]
 mysqld     = @bindir@/mysqld_safe
 mysqladmin = @bindir@/mysqladmin
-user       = root
-password   = your_password
+user       = multi_admin
+password   = my_password
 
 [mysqld2]
 socket     = /tmp/mysql.sock2
@@ -645,15 +651,18 @@ port       = 3307
 pid-file   = @localstatedir@2/hostname.pid2
 datadir    = @localstatedir@2
 language   = @datadir@/mysql/english
-user       = john
+user       = unix_user1
 
 [mysqld3]
+mysqld     = /path/to/safe_mysqld/safe_mysqld
+ledir      = /path/to/mysqld-binary/
+mysqladmin = /path/to/mysqladmin/mysqladmin
 socket     = /tmp/mysql.sock3
 port       = 3308
 pid-file   = @localstatedir@3/hostname.pid3
 datadir    = @localstatedir@3
 language   = @datadir@/mysql/swedish
-user       = monty
+user       = unix_user2
 
 [mysqld4]
 socket     = /tmp/mysql.sock4
@@ -661,16 +670,15 @@ port       = 3309
 pid-file   = @localstatedir@4/hostname.pid4
 datadir    = @localstatedir@4
 language   = @datadir@/mysql/estonia
-user       = tonu
+user       = unix_user3
  
-
 [mysqld6]
 socket     = /tmp/mysql.sock6
 port       = 3311
 pid-file   = @localstatedir@6/hostname.pid6
 datadir    = @localstatedir@6
 language   = @datadir@/mysql/japanese
-user       = jani
+user       = unix_user4
 EOF
   exit(0);
 }
@@ -691,39 +699,43 @@ Description:
 $my_progname can be used to start, or stop any number of separate
 mysqld processes running in different TCP/IP ports and UNIX sockets.
 
-This program can read group [mysqld_multi] from my.cnf file.
-You may want to put options mysqld=... and mysqladmin=... there.
-
-The program will search for group(s) named [mysqld#] from my.cnf (or
-the given --config-file=...), where # can be any positive number
-starting from 1. These groups should be the same as the usual [mysqld]
-group (e.g. options to mysqld, see MySQL manual for detailed
-information about this group), but with those port, socket
-etc. options that are wanted for each separate mysqld processes. The
-number in the group name has another function; it can be used for
-starting, stopping, or reporting some specific mysqld servers with
-this program. See the usage and options below for more information.
+$my_progname can read group [mysqld_multi] from my.cnf file. You may
+want to put options mysqld=... and mysqladmin=... there.  Since
+version 2.10 these options can also be given under groups [mysqld#],
+which gives more control over different versions.  One can have the
+default mysqld and mysqladmin under group [mysqld_multi], but this is
+not mandatory. Please note that if mysqld or mysqladmin is missing
+from both [mysqld_multi] and [mysqld#], a group that is tried to be
+used, $my_progname will abort with an error.
+
+$my_progname will search for groups named [mysqld#] from my.cnf (or
+the given --config-file=...), where '#' can be any positive integer
+starting from 1. These groups should be the same as the regular
+[mysqld] group, but with those port, socket and any other options
+that are to be used with each separate mysqld process. The number
+in the group name has another function; it can be used for starting,
+stopping, or reporting any specific mysqld server.
 
 Usage: $my_progname [OPTIONS] {start|stop|report} [GNR,GNR,GNR...]
 or     $my_progname [OPTIONS] {start|stop|report} [GNR-GNR,GNR,GNR-GNR,...]
 
-The GNR above means the group number. You can start, stop or report
-any GNR, or several of them at the same time. (See --example) The GNRs
-list can be comma separated, or a dash combined, of which the latter
-means that all the GNRs between GNR1-GNR2 will be affected. Without
-GNR argument all the found groups will be either started, stopped, or
-reported. Note that you must not have any white spaces in the GNR
-list. Anything after a white space are ignored.
+The GNR means the group number. You can start, stop or report any GNR,
+or several of them at the same time. (See --example) The GNRs list can
+be comma separated or a dash combined. The latter means that all the
+GNRs between GNR1-GNR2 will be affected. Without GNR argument all the
+groups found will either be started, stopped, or reported. Note that
+syntax for specifying GNRs must appear without spaces.
 
 Options:
 --config-file=...  Alternative config file.
                    Using: $opt_config_file
---example          Give an example of a config file.
+--example          Give an example of a config file with extra information.
 --help             Print this help and exit.
 --log=...          Log file. Full path to and the name for the log file. NOTE:
                    If the file exists, everything will be appended.
                    Using: $opt_log
 --mysqladmin=...   mysqladmin binary to be used for a server shutdown.
+                   Since version 2.10 this can be given within groups [mysqld#]
                    Using: $mysqladmin
 --mysqld=...       mysqld binary to be used. Note that you can give mysqld_safe
                    to this option also. The options are passed to mysqld. Just
@@ -732,19 +744,19 @@ Options:
                    Please note: Since mysqld_multi version 2.3 you can also
                    give this option inside groups [mysqld#] in ~/.my.cnf,
                    where '#' stands for an integer (number) of the group in
-                   question. This will be recognized as a special option and
+                   question. This will be recognised as a special option and
                    will not be passed to the mysqld. This will allow one to
                    start different mysqld versions with mysqld_multi.
 --no-log           Print to stdout instead of the log file. By default the log
                    file is turned on.
---password=...     Password for user for mysqladmin.
+--password=...     Password for mysqladmin user.
 --silent           Disable warnings.
 --tcp-ip           Connect to the MySQL server(s) via the TCP/IP port instead
                    of the UNIX socket. This affects stopping and reporting.
                    If a socket file is missing, the server may still be
                    running, but can be accessed only via the TCP/IP port.
                    By default connecting is done via the UNIX socket.
---user=...         MySQL user for mysqladmin. Using: $opt_user
+--user=...         mysqladmin user. Using: $opt_user
 --verbose          Be more verbose.
 --version          Print the version number and exit.
 EOF