From 91e13d2c9a88f34c4a5ee389e8972d650d0a701a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Fri, 9 Mar 2018 13:00:52 +0200 Subject: [PATCH] Update MaxScale-Tutorial.md 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. --- .../Tutorials/Connection-Routing-Tutorial.md | 11 +- Documentation/Tutorials/MaxScale-Tutorial.md | 172 +++++------------- .../Read-Write-Splitting-Tutorial.md | 11 +- 3 files changed, 50 insertions(+), 144 deletions(-) diff --git a/Documentation/Tutorials/Connection-Routing-Tutorial.md b/Documentation/Tutorials/Connection-Routing-Tutorial.md index e3f5e8bac..ec4632339 100644 --- a/Documentation/Tutorials/Connection-Routing-Tutorial.md +++ b/Documentation/Tutorials/Connection-Routing-Tutorial.md @@ -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. 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 -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'@'%'; -``` +parameters that define the credentials that the service will use. **Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md). diff --git a/Documentation/Tutorials/MaxScale-Tutorial.md b/Documentation/Tutorials/MaxScale-Tutorial.md index 3053942b6..fc9770216 100644 --- a/Documentation/Tutorials/MaxScale-Tutorial.md +++ b/Documentation/Tutorials/MaxScale-Tutorial.md @@ -1,103 +1,42 @@ # 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. +This document is designed as a quick introduction to setting up MariaDB MaxScale. -The installation and configuration of the MariaDB Replication or the Galera cluster -will not be covered nor will any discussion of installation management tools -to handle automated or semi-automated failover of the replication cluster. -The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) +The installation and configuration of the MariaDB Server will not be covered in +this document. 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 -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 available and has installed this in the default location. Building from source code in GitHub is covered in the [Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. -## Process +## Installing MaxScale -The steps involved in setting up MariaDB MaxScale are: - -* Install the package relevant to your distribution - -* 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. +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 MaxScale download page](https://mariadb.com/downloads/mariadb-tx/maxscale) +when you select the distribution you are downloading from. ## Creating Database Users -MariaDB MaxScale needs to connect to the backend databases and run queries for -two reasons; one to determine the current state of the database and the other to -retrieve the user information for the database cluster. The first pair of -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. +After installation, we need to create a database user. We do this as we need to +connect to the backend databases to retrieve the user authentication +information. To create this user, execute the following SQL commands. ``` -MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*'; - -**Query OK, 0 rows affected (0.00 sec)** +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'@'%'; ``` -If you wish to use two different usernames for the two different roles of monitoring -and collecting user information then create a different username using the first -two steps from above. +These credentials will be used by the services in MaxScale to populate the user +authentication data. The tutorials that follow will be using these credentials. ## 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 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 -MariaDB MaxScale's hostname. The best way to describe this process is with an -example. +MaxScale's address. This usually means that you must create two sets of grants +for each user. -User `'jdoe'@'192.168.0.200` has the following grant on the cluster: -`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`. -When the user connects directly to the server it will see it as -`'jdoe'@'192.168.0.200` connecting to the server and it will match -the grant for `'jdoe'@'192.168.0.200`. +For example, if you have the `'jdoe'@'client-host'` user and MaxScale is located +at `maxscale-host`, the `'jdoe'@'maxscale-host'` user must be created with the +same password as `'jdoe'@'client-host'` and given the same grants that +`'jdoe'@'client-host'` has. -If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe` -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. +The quickest way to do this is to first create the new user: -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) ``` -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'; -Query OK, 0 rows affected (0.00 sec) -``` - -The other option is to use a wildcard grant like the following: +Followed by copying grant the same grants to the `'jdoe'@'maxscale-host'` user. ``` -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 -client's address and MariaDB MaxScale's address as it allows access from all +Another other option is to use a wildcard grant that covers both hosts. This is +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. ## 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 - -* [MariaDB Replication Connection Routing Tutorial](MariaDB-Replication-Connection-Routing-Tutorial.md) -* [MariaDB Replication Read-Write Splitting Tutorial](MariaDB-Replication-Read-Write-Splitting-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) +For a fully automated read/write splitting setup, read the +[Read Write Splitting Tutorial](Read-Write-Splitting-Tutorial.md). +For a simpler connection based setup, read the +[Connection Routing Tutorial](Connection-Routing-Tutorial.md). diff --git a/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md b/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md index f47da2753..b2d778b48 100644 --- a/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md +++ b/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md @@ -52,16 +52,7 @@ in the configuration file (to be defined later) and not the physical hostnames or addresses of the servers. 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 -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'@'%'; -``` +parameters that define the credentials that the service will use. **Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md).