MyCAT - Mysql Cluster Administration Tools
              (using the term 'cluster' loosely here)

The "MyCAT" project is my attempt at giving to the OS community the tools
that I have created, and found indispensable, through my work with MySQL
on Linux, over the past five years.

At this time, MyCAT includes three programs:

   binlog_mon  -- monitor mysql binary logs, purging only when disk usage
                  exceeds given thresholds

   rep_mon     -- monitor mysql replication
                  configurable for any topology

   rcall       -- remote execution of arbitrary shell commands
                  Now also copies files en masse

and a default configuration file and supportive perl libraries.

`binlog_mon`: Binary Log Monitor
   Monitor the disk space used by a MySQL replicatiom master's binary logs,
   and PURGE the oldest file when specified disk usage limits are exceeded.
   This can be configured to purge logs when total used kB on a volume is
   greater than a limit, when the % used is above a limit, or when total
   free kB is below a limit. Binlog_mon also verifies that no replication
   slaves are still reading each binary log before deleting it.
   Additionally, binlog_mon has a second "critical" threshhold. Should a
   master server's disk exceed this critical threshold, binlog_mon *can*
   delete binary log files to prevent the disk from filling up -- if configured
   to do so. By default, this would be considered an error state, since it will
   most likely corrupt your slaves, so binlog_mon will send an email immediately
   notifying you what happened. It can be configured to simply send an email,
   instead of deleting still-needed files.

`rep_mon`: Replication Monitor
   Checks/verifies the status of replication between any number of servers
   in any variety of configurations: master->slave, master-> many slaves,
   round robin (A->B->C-A), etc.
   This script can be run as a cron, to send an email or page if any
   errors are detected.

`rcall`: Remote Call
   Tool to ease use and administration of groups (clusters) of *nix servers
   by creating logical groupings and a single location from which to run
   commands on all servers (while entering it only once).
   rcall requires that SSH key-based (passwordless) logins be previously
   set up across the servers to function properly. There is a great chapter
   on setting this up in 'Linux Server Hacks' by O'Reilly press, also
   viewable online at http://hacks.oreilly.com/pub/h/66.
   Rcall now has the ability to "scp" files from the local host to configured
   groups of servers, just as it would run a command on them.


Future plans include two other tools: `conftool`, which creates a single
location from which to change, sync, backup, and restore all types of
configuration files throughout these "clusters"; and a database backup
program (whose name has yet to be decided), which I have not yet
found a way to generalize so that others may install it w/o hassle. (But
I will, I promise!)




This package contains the following files:
README                  - this file
INSTALL                 - Installation and configuration instructions
CHANGELOG               - version history
lib/Mycat/*             - Perl modules
mycat.cnf               - Template XML config file, requires that you modify it (details in INSTALL)
bin/binlog_mon          - tool to monitor and rotate mysql binary logs
bin/rep_mon             - tool to monitor the status of replication on servers
bin/rcall               - tool to run arbitrary shell commands on clusters of servers



Installation and post-install configuration instructions are in the INSTALL file.




NOTES:

- If rep_mon is unable to authenticate with your MySQL server(s), it is probably because your
  DBI/DBD::mysql module was compiled against an older (pre 4.1) version of MySQL.
  If you can not upgrade your DBD::mysql or recompile it against recent MySQL libraries,
  you must adjust the password within MySQL for the user account that rep_mon will connect with.

  In brief, it is done like this:
    mysql> SET PASSWORD FOR 'mycat_user'@'mycat_host' = OLD_PASSWORD('mycat_pass');
  Alternately, like this:
    mysql> UPDATE mysql.user SET password = OLD_PASSWORD('mycat_pass') WHERE ....;

  Full documentation is available at: http://dev.mysql.com/doc/refman/5.0/en/old-client.html

- If your MySQL servers are in a chain or ring configuration, the binary log position on the slave(s)
  may often appear to be far behind their master(s), even though Seconds_Behind_Master is 0.
  rep_mon does not report this as an error because it is a known bug in MySQL's output of
  Exec_Master_Log_Pos. More information is available at http://bugs.mysql.com/bug.php?id=13023

- If you encounter either of the following errors, "Failed to allocate shared memory"
  or "Failed to write shared memory before connect", you can modify the value of $shm_size in
  lib/Mycat/mysql.pm line 12. Please also send a bug report to the author.



Mailing list: mycat-general@lists.sourceforge.net
Author: Devananda van der Veen,
        devananda.vdv@gmail.com