hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update MaxScale-Tutorial.md

Browse Source 
Made the document more concise and added links to the download page. Made
the user grants easier to copy-paste and explained that they are used in
the following tutorials. Updated the links to the new tutorials.
This commit is contained in:
Markus Mäkelä
2018-03-09 13:00:52 +02:00
parent fe2dfe03f4
commit 91e13d2c9a
3 changed files with 50 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
Documentation/Tutorials/Connection-Routing-Tutorial.md
View File

@ -71,16 +71,7 @@ servers the service will use. For the write service we use the _master_ type and
for the read service we use the _slave_ type. for the read service we use the _slave_ type.
The final part of the service configuration is the `user` and `password` The final part of the service configuration is the `user` and `password`
parameters that define the credentials that the service will use to populate the parameters that define the credentials that the service will use.
user authentication data. To create this user, execute the following SQL commands.
```
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
```
**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md). **Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md).

172
Documentation/Tutorials/MaxScale-Tutorial.md
View File

@ -1,103 +1,42 @@
# Setting up MariaDB MaxScale # Setting up MariaDB MaxScale
This document is designed as a quick introduction to setting up MariaDB MaxScale This document is designed as a quick introduction to setting up MariaDB MaxScale.
in an environment in which you have either a MariaDB Master-Slave replication cluster
with one master and multiple slave servers or a multi-node Galera cluster.
The process of setting and configuring MariaDB MaxScale will be covered within this document.
The installation and configuration of the MariaDB Replication or the Galera cluster The installation and configuration of the MariaDB Server will not be covered in
will not be covered nor will any discussion of installation management tools this document. The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/)
to handle automated or semi-automated failover of the replication cluster.
The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/)
article on the MariaDB knowledgebase can help you get started with replication clusters article on the MariaDB knowledgebase can help you get started with replication clusters
and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster. and the
[Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/)
article will help you set up a Galera cluster.
This tutorial will assume the user is running from one of the binary distributions This tutorial will assume the user is running from one of the binary distributions
available and has installed this in the default location. available and has installed this in the default location.
Building from source code in GitHub is covered in the Building from source code in GitHub is covered in the
[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. [Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
## Process ## Installing MaxScale
The steps involved in setting up MariaDB MaxScale are: The precise installation process will vary from one distribution to another.
Details of what to do with the RPM and DEB packages
* Install the package relevant to your distribution [can be found on the MaxScale download page](https://mariadb.com/downloads/mariadb-tx/maxscale)
when you select the distribution you are downloading from.
* Create the required users in your MariaDB or MySQL Replication cluster
* Create a MariaDB MaxScale configuration file
## Installation
The precise installation process will vary from one distribution to another
details of what to do with the RPM and DEB packages can be found on the download
site when you select the distribution you are downloading from.
The process involves setting up your package manager to include the MariaDB repositories
and then running the package manager for your distribution (usually yum or apt-get).
Upon successful completion of the installation command you will have MariaDB MaxScale
installed and ready to be run but without a configuration.
You must create a configuration file before you first run MariaDB MaxScale
which is covered in a later section.
## Creating Database Users ## Creating Database Users
MariaDB MaxScale needs to connect to the backend databases and run queries for After installation, we need to create a database user. We do this as we need to
two reasons; one to determine the current state of the database and the other to connect to the backend databases to retrieve the user authentication
retrieve the user information for the database cluster. The first pair of information. To create this user, execute the following SQL commands.
credentials will be used by the monitor modules and the second is used by
MariaDB MaxScale itself. This may be done either using two separate usernames
or with a single user.
The first user required must be able to select data from the table mysql.user,
to create this user follow the steps below.
1. Connect to the current master server in your replication tree as the root user
2. Create the user, substituting the username, password and host on which maxscale
runs within your environment
```
MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*';
**Query OK, 0 rows affected (0.00 sec)**
```
3. Grant select privileges on the mysql.user table.
```
MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.03 sec)**
```
Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables
and `SHOW DATABASES` privileges are required in order to load databases name
and grants suitable for database name authorization.
```
MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
MariaDB [(none)]> GRANT SELECT ON mysql.tables_priv TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
```
The second user is used to monitored the state of the cluster. This user, which may be
the same username as the first, requires permissions to access the various sources
of monitoring data. In order to monitor a replication cluster this user must be granted
the role REPLICATION CLIENT. This is only required by the MySQL monitor
and Multi-Master monitor modules.
``` ```
MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*'; CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
**Query OK, 0 rows affected (0.00 sec)** GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
``` ```
If you wish to use two different usernames for the two different roles of monitoring These credentials will be used by the services in MaxScale to populate the user
and collecting user information then create a different username using the first authentication data. The tutorials that follow will be using these credentials.
two steps from above.
## Creating additional grants for users ## Creating additional grants for users
@ -106,64 +45,49 @@ two steps from above.
Because MariaDB MaxScale sits between the clients and the backend databases, the Because MariaDB MaxScale sits between the clients and the backend databases, the
backend databases will see all clients as if they were connecting from MariaDB backend databases will see all clients as if they were connecting from MariaDB
MaxScale's address. This usually requires users to create additional grants for MaxScale's address. This usually means that you must create two sets of grants
MariaDB MaxScale's hostname. The best way to describe this process is with an for each user.
example.
User `'jdoe'@'192.168.0.200` has the following grant on the cluster: For example, if you have the `'jdoe'@'client-host'` user and MaxScale is located
`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`. at `maxscale-host`, the `'jdoe'@'maxscale-host'` user must be created with the
When the user connects directly to the server it will see it as same password as `'jdoe'@'client-host'` and given the same grants that
`'jdoe'@'192.168.0.200` connecting to the server and it will match `'jdoe'@'client-host'` has.
the grant for `'jdoe'@'192.168.0.200`.
If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe` The quickest way to do this is to first create the new user:
connects to this MariaDB MaxScale, the backend server will see the connection as
`'jdoe'@'192.168.0.101'`. Since the backend server has no grants for
`'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server
will be refused.
We can fix this by either creating a matching grant for user `jdoe` from
the MariaDB MaxScale address or by using a wildcard to cover both addresses.
The quickest way to do this is by doing a SHOW GRANTS query:
``` ```
MariaDB [(none)]> SHOW GRANTS FOR 'jdoe'@'192.168.0.200'; CREATE USER 'jdoe'@'maxscale-host' IDENTIFIED BY 'my_secret_password';
```
Then do a `SHOW GRANTS` query:
```
MariaDB [(none)]> SHOW GRANTS FOR 'jdoe'@'client-host';
+-----------------------------------------------------------------------+ +-----------------------------------------------------------------------+
| Grants for jdoe@192.168.0.200 | | Grants for jdoe@client-host |
+-----------------------------------------------------------------------+ +-----------------------------------------------------------------------+
| GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200' | | GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'client-host' |
+-----------------------------------------------------------------------+ +-----------------------------------------------------------------------+
1 row in set (0.01 sec) 1 row in set (0.01 sec)
``` ```
Then creating the user `'jdoe'@'192.168.0.101'` and giving it the same grants:
```
MariaDB [(none)]> CREATE USER 'jdoe'@'192.168.0.101' IDENTIFIED BY 'secret_password';
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.101'; Followed by copying grant the same grants to the `'jdoe'@'maxscale-host'` user.
Query OK, 0 rows affected (0.00 sec)
```
The other option is to use a wildcard grant like the following:
``` ```
GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%' IDENTIFIED BY 'secret_password' GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'maxscale-host';
``` ```
This is more convenient but less secure than having specific grants for both the Another other option is to use a wildcard grant that covers both hosts. This is
client's address and MariaDB MaxScale's address as it allows access from all more convenient but less secure than having specific grants for both the
client's hostname and MariaDB MaxScale's hostname as it allows access from all
hosts. hosts.
## Creating the configuration file ## Creating the configuration file
The configuration file creation is covered in different tutorials. The next step is to create the configuration file. This part is covered in two
different tutorials.
### Master-Slave cluster For a fully automated read/write splitting setup, read the
[Read Write Splitting Tutorial](Read-Write-Splitting-Tutorial.md).
* [MariaDB Replication Connection Routing Tutorial](MariaDB-Replication-Connection-Routing-Tutorial.md) For a simpler connection based setup, read the
* [MariaDB Replication Read-Write Splitting Tutorial](MariaDB-Replication-Read-Write-Splitting-Tutorial.md) [Connection Routing Tutorial](Connection-Routing-Tutorial.md).
### Galera cluster
* [Galera Cluster Connection Routing Tutorial](Galera-Cluster-Connection-Routing-Tutorial.md)
* [Galera Cluster Read Write Splitting Tutorial](Galera-Cluster-Read-Write-Splitting-Tutorial.md)

11
Documentation/Tutorials/Read-Write-Splitting-Tutorial.md
View File

@ -52,16 +52,7 @@ in the configuration file (to be defined later) and not the physical hostnames
or addresses of the servers. or addresses of the servers.
The final part of the service configuration is the `user` and `password` The final part of the service configuration is the `user` and `password`
parameters that define the credentials that the service will use to populate the parameters that define the credentials that the service will use.
user authentication data. To create this user, execute the following SQL commands.
```
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
```
**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md). **Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md).