--- a/dev/provisioning/modules/mysql/README.md Fri Apr 08 17:50:49 2016 +0200
+++ b/dev/provisioning/modules/mysql/README.md Fri Apr 08 17:53:56 2016 +0200
@@ -3,104 +3,108 @@
#### Table of Contents
1. [Module Description - What the module does and why it is useful](#module-description)
-2. [Backwards compatibility information](#backwards-compatibility)
-3. [Setup - The basics of getting started with mysql](#setup)
+2. [Setup - The basics of getting started with mysql](#setup)
* [Beginning with mysql](#beginning-with-mysql)
-4. [Usage - Configuration options and additional functionality](#usage)
- * [Customizing Server Options](#customizing-server-options)
- * [Creating a Database](#creating-a-database)
- * [Custom Configuration](#custom-configuration)
-5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
-6. [Limitations - OS compatibility, etc.](#limitations)
-7. [Development - Guide for contributing to the module](#development)
+3. [Usage - Configuration options and additional functionality](#usage)
+ * [Customize server options](#customize-server-options)
+ * [Create a database](#create-a-database)
+ * [Customize configuration](#create-custom-configuration)
+ * [Work with an existing server](#work-with-an-existing-server)
+ * [Specify passwords](#specify-passwords)
+4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
+5. [Limitations - OS compatibility, etc.](#limitations)
+6. [Development - Guide for contributing to the module](#development)
## Module Description
-The MySQL module installs, configures, and manages the MySQL service.
+The mysql module installs, configures, and manages the MySQL service.
-The MySQL module manages both the installation and configuration of MySQL, as well as extending Puppet to allow management of MySQL resources, such as databases, users, and grants.
+This module manages both the installation and configuration of MySQL, as well as extending Puppet to allow management of MySQL resources, such as databases, users, and grants.
## Setup
-### Beginning with MySQL
+### Beginning with mysql
-If you want a server installed with the default options you can run
+To install a server with the default options:
+
`include '::mysql::server'`.
-If you need to customize options, such as the root
-password or `/etc/my.cnf` settings, then you must also pass in an override hash:
+To customize options, such as the root
+password or `/etc/my.cnf` settings, you must also pass in an override hash:
-~~~
+```puppet
class { '::mysql::server':
root_password => 'strongpassword',
remove_default_accounts => true,
override_options => $override_options
}
-~~~
+```
-See [**Customizing Server Options**](#customizing-server-options) below for examples of the hash structure for $override_options`.
+See [**Customize Server Options**](#customize-server-options) below for examples of the hash structure for $override_options`.
## Usage
All interaction for the server is done via `mysql::server`. To install the client, use `mysql::client`. To install bindings, use `mysql::bindings`.
-### Customizing Server Options
+### Customize server options
-The hash structure for overrides in `mysql::server` can be structured like a hash in the my.cnf file, so:
+To define server options, structure a hash structure of overrides in `mysql::server`. This hash resembles a hash in the my.cnf file:
-~~~
+```puppet
$override_options = {
'section' => {
'item' => 'thing',
}
}
-~~~
+```
-For items that you would traditionally represent as
+For options that you would traditionally represent in this format:
-~~~
+```
[section]
thing = X
-~~~
+```
-you can make an entry like `thing => true`, `thing => value`, or `thing => "` in the hash. Alternatively, you can pass an array, as `thing => ['value', 'value2']`, or list each `thing => value` separately on separate lines.
+...you can make an entry like `thing => true`, `thing => value`, or `thing => "` in the hash. Alternatively, you can pass an array, as `thing => ['value', 'value2']`, or list each `thing => value` separately on separate lines.
-MySQL doesn't care if 'thing' is alone or set to a value; it happily accepts both. To keep an option out of the my.cnf file --- e.g., when using `override_options` to revert to a default value --- you can pass `thing => undef`.
+You can pass a variable in the hash without setting a value for it; the variable would then use MySQL's default settings. To exclude an option from the my.cnf file --- for example, when using `override_options` to revert to a default value --- pass `thing => undef`.
-If an option needs multiple instances, you can pass an array. For example,
+If an option needs multiple instances, pass an array. For example,
-~~~
+```puppet
$override_options = {
'mysqld' => {
'replicate-do-db' => ['base1', 'base2'],
}
}
-~~~
+```
produces
-~~~
+```
[mysqld]
replicate-do-db = base1
replicate-do-db = base2
-~~~
+```
-### Creating a database
+To implement version specific parameters, specify the version, such as [mysqld-5.5]. This allows one config for different versions of MySQL.
-To use `mysql::db` to create a database with a user and assign some privileges:
+### Create a database
-~~~
+To create a database with a user and some assigned privileges:
+
+```puppet
mysql::db { 'mydb':
user => 'myuser',
password => 'mypass',
host => 'localhost',
grant => ['SELECT', 'UPDATE'],
}
-~~~
+```
-Or to use a different resource name with exported resources:
+To use a different resource name with exported resources:
-~~~
+```puppet
@@mysql::db { "mydb_${fqdn}":
user => 'myuser',
password => 'mypass',
@@ -109,19 +113,19 @@
grant => ['SELECT', 'UPDATE'],
tag => $domain,
}
-~~~
+```
Then you can collect it on the remote DB server:
-~~~
+```puppet
Mysql::Db <<| tag == $domain |>>
-~~~
+```
-If you set the sql param to a file when creating a database, the file gets imported into the new database.
+If you set the sql parameter to a file when creating a database, the file is imported into the new database.
-For large sql files, you should raise the $import_timeout parameter, set by default to 300 seconds.
+For large sql files, increase the `import_timeout` parameter, which defaults to 300 seconds.
-~~~
+```puppet
mysql::db { 'mydb':
user => 'myuser',
password => 'mypass',
@@ -130,27 +134,37 @@
sql => '/path/to/sqlfile',
import_timeout => 900,
}
-~~~
+```
-### Custom Configuration
+### Customize configuration
-To add custom MySQL configuration, drop additional files into
-`includedir`. Dropping files into `includedir` allows you to override settings or add additional ones, which is helpful if you choose not to use `override_options` in `mysql::server`. The `includedir` location is by default set to /etc/mysql/conf.d.
+To add custom MySQL configuration, place additional files into `includedir`. This allows you to override settings or add additional ones, which is helpful if you don't use `override_options` in `mysql::server`. The `includedir` location is by default set to `/etc/mysql/conf.d`.
-### Working with an existing server
+### Work with an existing server
+
+To instantiate databases and users on an existing MySQL server, you need a `.my.cnf` file in `root`'s home directory. This file must specify the remote server address and credentials. For example:
-You can use the MySQL module to instantiate databases and
-users on an existing MySQL server. For this to work, you need an
-appropriate `.my.cnf` in `root`'s home directory containing the remote
-server address and credentials. For example:
+```
+[client]
+user=root
+host=localhost
+password=secret
+```
+
+When working with a remote server, do *not* use the `mysql::server` class in your Puppet manifests.
+
+### Specify passwords
- [client]
- user=root
- host=localhost
- password=secret
+In addition to passing passwords as plain text, you can input them as hashes. For example:
-When working with a remote server, do *not* use the
-`mysql::server` class in your Puppet manifests.
+```puppet
+mysql::db { 'mydb':
+ user => 'myuser',
+ password => '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4',
+ host => 'localhost',
+ grant => ['SELECT', 'UPDATE'],
+}
+```
## Reference
@@ -168,6 +182,7 @@
#### Private classes
* `mysql::server::install`: Installs packages.
+* `mysql::server::installdb`: Implements setup of mysqld data directory (e.g. /var/lib/mysql)
* `mysql::server::config`: Configures MYSQL.
* `mysql::server::service`: Manages service.
* `mysql::server::account_security`: Deletes default MySQL accounts.
@@ -191,23 +206,21 @@
##### `create_root_user`
-Specify whether root user should be created. Valid values are 'true', 'false'. Defaults to 'true'.
+Whether root user should be created. Valid values are true, false. Defaults to true.
-This is useful for a cluster setup with Galera. The root user has to
-be created only once. `create_root_user` can be set to 'true' on one node while
-it is set to 'false' on the remaining nodes.
+This is useful for a cluster setup with Galera. The root user has to be created only once. You can set this parameter true on one node and set it to false on the remaining nodes.
##### `create_root_my_cnf`
-If set to 'true', creates `/root/.my.cnf`. Valid values are 'true', 'false'. Defaults to 'true'.
+Whether to create `/root/.my.cnf`. Valid values are true, false. Defaults to true.
-`create_root_my_cnf` allows creation of `/root/.my.cnf` independently of `create_root_user`. This can be used for a cluster setup with Galera where you want `/root/.my.cnf` to exist on all nodes.
+`create_root_my_cnf` allows creation of `/root/.my.cnf` independently of `create_root_user`. You can use this for a cluster setup with Galera where you want `/root/.my.cnf` to exist on all nodes.
##### `root_password`
The MySQL root password. Puppet attempts to set the root password and update `/root/.my.cnf` with it.
-This is required if `create_root_user` or `create_root_my_cnf` are 'true'. If `root_password` is 'UNSET', then `create_root_user` and `create_root_my_cnf` are assumed to be false --- that is, the MySQL root user and `/root/.my.cnf` are not created.
+This is required if `create_root_user` or `create_root_my_cnf` are true. If `root_password` is 'UNSET', then `create_root_user` and `create_root_my_cnf` are assumed to be false --- that is, the MySQL root user and `/root/.my.cnf` are not created.
Password changes are supported; however, the old password must be set in `/root/.my.cnf`. Effectively, Puppet uses the old password, configured in `/root/my.cnf`, to set the new password in MySQL, and then updates `/root/.my.cnf` with the new password.
@@ -217,17 +230,17 @@
##### `override_options`
-The hash of override options to pass into MySQL. Structured like a hash in the my.cnf file:
+Specifies override options to pass into MySQL. Structured like a hash in the my.cnf file:
-~~~
+```puppet
$override_options = {
'section' => {
'item' => 'thing',
}
}
-~~~
+```
-See [**Customizing Server Options**](#customizing-server-options) above for usage details.
+See [**Customize Server Options**](#customize-server-options) above for usage details.
##### `config_file`
@@ -235,21 +248,21 @@
##### `manage_config_file`
-Whether the MySQL configuration file should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
+Whether the MySQL configuration file should be managed. Valid values are true, false. Defaults to true.
##### `includedir`
The location, as a path, of !includedir for custom configuration overrides.
##### `install_options`
-Pass [install_options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) array to managed package resources. You must pass the appropriate options for the specified package manager.
+Passes [install_options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) array to managed package resources. You must pass the appropriate options for the specified package manager.
##### `purge_conf_dir`
-Whether the `includedir` directory should be purged. Valid values are 'true', 'false'. Defaults to 'false'.
+Whether the `includedir` directory should be purged. Valid values are true, false. Defaults to false.
##### `restart`
-Whether the service should be restarted when things change. Valid values are 'true', 'false'. Defaults to 'false'.
+Whether the service should be restarted when things change. Valid values are true, false. Defaults to false.
##### `root_group`
@@ -273,15 +286,15 @@
##### `remove_default_accounts`
-Specify whether to automatically include `mysql::server::account_security`. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether to automatically include `mysql::server::account_security`. Valid values are true, false. Defaults to false.
##### `service_enabled`
-Specify whether the service should be enabled. Valid values are 'true', 'false'. Defaults to 'true'.
+Specifies whether the service should be enabled. Valid values are true, false. Defaults to true.
##### `service_manage`
-Specify whether the service should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
+Specifies whether the service should be managed. Valid values are true, false. Defaults to true.
##### `service_name`
@@ -295,7 +308,7 @@
Optional hash of users to create, which are passed to [mysql_user](#mysql_user).
-~~~
+```
users => {
'someuser@localhost' => {
ensure => 'present',
@@ -306,13 +319,13 @@
password_hash => '*F3A2A51A9B0F2BE2468926B4132313728C250DBF',
},
}
-~~~
+```
##### `grants`
Optional hash of grants, which are passed to [mysql_grant](#mysql_grant).
-~~~
+```
grants => {
'someuser@localhost/somedb.*' => {
ensure => 'present',
@@ -322,20 +335,20 @@
user => 'someuser@localhost',
},
}
-~~~
+```
##### `databases`
Optional hash of databases to create, which are passed to [mysql_database](#mysql_database).
-~~~
+```
databases => {
'somedb' => {
ensure => 'present',
charset => 'utf8',
},
}
-~~~
+```
#### mysql::server::backup
@@ -368,7 +381,7 @@
##### `backupcompress`
-Whether backups should be compressed. Valid values are 'true', 'false'. Defaults to 'true'.
+Whether backups should be compressed. Valid values are true, false. Defaults to true.
##### `backuprotate`
@@ -376,23 +389,23 @@
##### `delete_before_dump`
-Whether to delete old .sql files before backing up. Setting to 'true' deletes old files before backing up, while setting to 'false' deletes them after backup. Valid values are 'true', 'false'. Defaults to 'false'.
+Whether to delete old .sql files before backing up. Setting to true deletes old files before backing up, while setting to false deletes them after backup. Valid values are true, false. Defaults to false.
##### `backupdatabases`
-Specify an array of databases to back up.
+Specifies an array of databases to back up.
##### `file_per_database`
-Whether a separate file be used per database. Valid values are 'true', 'false'. Defaults to 'false'.
+Whether a separate file be used per database. Valid values are true, false. Defaults to false.
##### `include_routines`
-Whether or not to include routines for each database when doing a `file_per_database` backup. Defaults to `false`.
+Whether or not to include routines for each database when doing a `file_per_database` backup. Defaults to false.
##### `include_triggers`
-Whether or not to include triggers for each database when doing a `file_per_database` backup. Defaults to `false`.
+Whether or not to include triggers for each database when doing a `file_per_database` backup. Defaults to false.
##### `ensure`
@@ -450,41 +463,41 @@
##### `source`
-Parameter to optionally specify the source. If not specified, defaults to `https://github.com/major/MySQLTuner-perl/raw/${version}/mysqltuner.pl`
+Specifies the source. If not specified, defaults to `https://github.com/major/MySQLTuner-perl/raw/${version}/mysqltuner.pl`
#### mysql::bindings
##### `client_dev`
-Specify whether `::mysql::bindings::client_dev` should be included. Valid values are true', 'false'. Defaults to 'false'.
+Specifies whether `::mysql::bindings::client_dev` should be included. Valid values are true', false. Defaults to false.
##### `daemon_dev`
-Specify whether `::mysql::bindings::daemon_dev` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `::mysql::bindings::daemon_dev` should be included. Valid values are true, false. Defaults to false.
##### `java_enable`
-Specify whether `::mysql::bindings::java` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `::mysql::bindings::java` should be included. Valid values are true, false. Defaults to false.
##### `perl_enable`
-Specify whether `mysql::bindings::perl` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `mysql::bindings::perl` should be included. Valid values are true, false. Defaults to false.
##### `php_enable`
-Specify whether `mysql::bindings::php` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `mysql::bindings::php` should be included. Valid values are true, false. Defaults to false.
##### `python_enable`
-Specify whether `mysql::bindings::python` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `mysql::bindings::python` should be included. Valid values are true, false. Defaults to false.
##### `ruby_enable`
-Specify whether `mysql::bindings::ruby` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether `mysql::bindings::ruby` should be included. Valid values are true, false. Defaults to false.
##### `install_options`
-Pass `install_options` array to managed package resources. You must pass the [appropriate options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) for the package manager(s).
+Passes `install_options` array to managed package resources. You must pass the [appropriate options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) for the package manager(s).
##### `client_dev_package_ensure`
@@ -570,7 +583,7 @@
##### `bindings_enable`
-Whether to automatically install all bindings. Valid values are 'true', 'false'. Default to 'false'.
+Whether to automatically install all bindings. Valid values are true, false. Default to false.
##### `install_options`
Array of install options for managed package resources. You must pass the appropriate options for the package manager.
@@ -591,7 +604,7 @@
#### mysql::db
-~~~
+```
mysql_database { 'information_schema':
ensure => 'present',
charset => 'utf8',
@@ -602,7 +615,7 @@
charset => 'latin1',
collate => 'latin1_swedish_ci',
}
-~~~
+```
##### `user`
@@ -638,11 +651,11 @@
##### `enforce_sql`
-Specify whether executing the sqlfiles should happen on every run. If set to 'false', sqlfiles only run once. Valid values are 'true', 'false'. Defaults to 'false'.
+Specifies whether executing the sqlfiles should happen on every run. If set to false, sqlfiles only run once. Valid values are true, false. Defaults to false.
##### `ensure`
-Specify whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'.
+Specifies whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'.
##### `import_timeout`
@@ -674,7 +687,7 @@
Creates and manages user grants within MySQL.
-~~~
+```
mysql_user { 'root@127.0.0.1':
ensure => 'present',
max_connections_per_hour => '0',
@@ -682,16 +695,16 @@
max_updates_per_hour => '0',
max_user_connections => '0',
}
-~~~
+```
You can also specify an authentication plugin.
-~~~
+```
mysql_user{ 'myuser'@'localhost':
ensure => 'present',
plugin => 'unix_socket',
}
-~~~
+```
##### `name`
@@ -724,7 +737,7 @@
MySQL. To create grant permissions to access databases with MySQL, use it you must create the title of the resource as shown below,
following the pattern of `username@hostname/database.table`:
-~~~
+```
mysql_grant { 'root@localhost/*.*':
ensure => 'present',
options => ['GRANT'],
@@ -732,18 +745,18 @@
table => '*.*',
user => 'root@localhost',
}
-~~~
+```
It is possible to specify privileges down to the column level:
-~~~
+```
mysql_grant { 'root@localhost/mysql.user':
ensure => 'present',
privileges => ['SELECT (Host, User)'],
table => 'mysql.user',
user => 'root@localhost',
}
-~~~
+```
##### `ensure`
@@ -773,12 +786,12 @@
`mysql_plugin` can be used to load plugins into the MySQL Server.
-~~~
+```
mysql_plugin { 'auth_socket':
ensure => 'present',
soname => 'auth_socket.so',
}
-~~~
+```
##### `ensure`
@@ -792,6 +805,17 @@
The library file name.
+#### `mysql_datadir`
+
+Initializes the MySQL data directory with version specific code. Pre MySQL 5.7.6
+it uses mysql_install_db. After MySQL 5.7.6 it uses mysqld --initialize-insecure.
+
+Insecure initialization is needed, as mysqld version 5.7 introduced "secure by default" mode.
+This means MySQL generates a random password and writes it to STDOUT. This means puppet
+can never accesss the database server afterwards, as no credencials are available.
+
+This type is an internal type and should not be called directly.
+
### Facts
#### `mysql_version`