module-mysql/README

Introduction/Notes
==================

This module manages your mysql resources. 

Requirements
------------

The puppetlabs-stdlib module is required for some functions used in this module.

If you are wanting munin integration, you will need the munin module installed.

If you are wanting shorewall integration, you will need the shorewall module
installed.

If you are wanting nagios integration, you will need the nagios module
installed, specifically it must have nagios::plugin::deploy functionality. 

You will need to have activated storedconfigs on the puppetmaster.

You need to ensure that the PATH environment variable contains the appropriate
directories else the root password will not be set correctly to the requested
value. Since the variable is empty by default when running puppet, you need to
have something similar to this somewhere in your manifests:

    Exec { path => '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' }

Special Notes
=============

By using this module, the following users will be automatically removed, if they
exist: "root@${fqdn}", "root@127.0.0.1", "@${fqdn}", "@localhost", "@%"

Mysql Server
============

On a node where you wish to have a mysql server installed, you should include
mysql::server, for example:

node foo {
  class{'mysql::server':
    root_password => 'foo',
  }
}

This will manage the necessary directories and configuration files, it will
install the mysql client program and set the root password to 'foo',
along with setting a /root/.my.cnf for various module operations. It will also
make sure the mysql service is running, and setup all the databases, users and
grant tables.

The my.cnf file will installed from one of many possible places, see
manifests/server/base.pp for possible locations for managing this.

Configuration snippets
----------------------

To make managing mysql configuration easier, you can use the define
mysql::conf. Note, though that there currently is only the Debian default
configuration file that includes files in /etc/mysql/conf.d/.

For example:

mysql::conf { 'test':
  ensure  => present,
  section => 'mysqld',
  config  => {
    table_cache => '15000',
    skip_slave  => '',
    something   => '""',
  }
}

The above example shows two possibilities for empty values.

 * If a value only has an empty value in the hash passed to the config
   parameter, that will define a boolean option in mysql by simply mentioning
   the option name with no equal sign. So in the above, you'd have a line that
   contains only "skip_slave".

 * If you need to declare a variable with an empty value (e.g. with the equal
   sign), you can use two quotes as the option's value. In the above example,
   you'd have a line that looks like "something=".

Backups
-------

If you wish to automatically setup a cronjob to backup your databases, you can
set the "$mysql_backup_cron = true" variable. This will setup a cronjob to do a
mysqldump at 1am of all the databases on the system and put them in
/var/backups/mysql by default. You can override this location by specifying
$mysql_backup_dir.

Optimizing tables
-----------------

If you wish mysql to periodically optimize tables, set the
"$mysql_optimize_cron = true" variable before you include mysql::server.

By default, time of execution for the optimization script will be randomly
chosen (and will stay consistant for a server) any day between midnight and
7:00 AM. If you wish to force at least one value, you can use the following
parameters to the mysql::server class (all values are used directly as a
cronjob value so they should be set within cron value space):

* optimize_day => sets the day of the week (integer value) during which the script will run.
* optimize_hour => sets the hour at which the optimization script will run.
* optimize_minute => sets the minute in the hour at which the script will run.

Munin
-----

If you wish to use munin you need to set the variables use_munin to "true" in
hiera, before you include mysql::server. This will be used to
setup a mysql user for munin, with reduced privileges to allow for the various
munin graphs to be setup and queried. The munin graphs are: mysql_bytes,
mysql_queries, mysql_slowqueries and mysql_threads. NOTE: The
munin_mysql_password will be taken from what you passed to the mysql::server
class, but it is not necessary on Debian systems as it will handled with
Debian's /etc/mysql/debian.cnf.

Nagios
------

If you wish nagios to check mysql, you can set the variable "manage_nagios" to
"true" in hiera along with the "nagios_check_mysql" variable to "true". A
password for the nagios mysql user will be created for you with reduced privileges
used only for nagios checks. This will be what you passed as nagios_password_hash
to mysql::server and should be a mysql md5 hash. These should be set before you
include mysql::server.

Unless you specify otherwise, the default nagios check which will be performed
is the basic 'check_mysql' nagios plugin which simply tests connectivity to a
MySQL server. You can specify more advanced mysql health checks as follows:

mysql::server::nagios::check_health { [ 'connection-time', 'uptime', 'threads-connected', 
				        'slave-lag', 'slave-io-running', 'slave-sql-running' ]:  }

See the files/nagios/check_mysql_health script for the various mysql health
checks that you can perform. Additionally, see the define "check_health" in
manifests/server/nagios.pp for various options that you can pass to check_health.

Note that if you need to use some specific logic to decide whether or not to
create a nagios service check, you should set $manage_nagios to false, and
include mysql::server::nagios from within your own manifests.

Firewall
--------

If you wish to have firewall rules setup automatically for you, using shorewall,
you will need to set the hiera variable "use_shorewall" to "true". See the
shorewall module for more information about how this works.


Client
======

On a node where you wish to have the mysql client managed, you can 'include
mysql::client' in the node definition. This will install the appropriate
package.

You can also 'include mysql::client::ruby' if you want the 'libmysql-ruby'
libraries installed.