Upgrade to MaxScale 2.5 on CentOS 6

These instructions detail the upgrade to MariaDB MaxScale 2.5 on CentOS Linux 6 in a MaxScale Instance configuration.

MariaDB MaxScale is an advanced database proxy, firewall, and query router.

Term Definitions

Term

Definition

MaxScale instance

upgrade

  • A change from lower-versioned release of MariaDB MaxScale to a higher-versioned release of MariaDB MaxScale.

Backing Up Configuration

Upgrades can move or change configuration files. Before starting an upgrade, always back up your configuration files to ensure you can revert to the working system in the event that you encounter any issues during the upgrade.

To back up a configuration file, create a copy:

$ sudo cp /etc/maxscale.cnf /data/backups/config/maxscale.cnf

Upgrade

MariaDB Corporation provides a YUM package repository for CentOS Linux 6.

Stop the MaxScale Process

Before upgrading MariaDB MaxScale, first stop the current process.

  1. Stop the server process using the service command:

    $ sudo service maxscale stop
    

Upgrade via YUM (RHEL/CentOS)

  1. Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for customer_download_token in the following directions.

  2. Configure the YUM package repository.

    To configure YUM package repositories:

    $ sudo yum install wget
    
    $ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
    
    $ echo "eeebe9e08dffb8a4e820cc0f673afe437621060129169ea3db0790eb649dbe9b  mariadb_es_repo_setup" \
        | sha256sum -c -
    
    $ chmod +x mariadb_es_repo_setup
    
    $ sudo ./mariadb_es_repo_setup --token="customer_download_token" --apply \
       --mariadb-maxscale-version="2.5"
    
  3. Upgrade MariaDB MaxScale and package dependencies:

    $ sudo yum update maxscale
    
  4. Configure MaxScale.

    The upgrade process only loads MaxScale onto the system. MaxScale requires configuration before MaxScale is ready for use.

Configuration

Configuration parameters can change between releases of MariaDB MaxScale, which can have unexpected results.

  1. Determine which parameters have changed in your specific release.

    • If you are upgrading from MaxScale 2.2 or earlier to MaxScale 2.5, then review the configuration parameter changes in the Upgrading to MaxScale 2.3 guide.

    • If you are upgrading from MaxScale 2.3 or earlier to MaxScale 2.5, then review the configuration parameter changes in the Upgrading to MaxScale 2.4 guide.

    • If you are upgrading from MaxScale 2.4 or earlier to MaxScale 2.5, then review the configuration parameter changes in the sections below below.

  2. Change the specific parameters in maxscale.cnf.

General Configuration Changes in MaxScale 2.5

  • MaxScale's password encryption features have been updated to be more secure. Passwords encrypted in old versions will still work, but it is recommended to generate a new encryption key with the maxkeys command and to re-encrypt passwords with the maxpasswd command.

MariaDB Monitor Configuration Changes in MaxScale 2.5

MaxScale 2.5 includes configuration changes for MariaDB Monitor (mariadbmon):

  • The detect_stale_master and the detect_standalone_master parameters have been deprecated. They can still be used, but they will be removed in a later version of MaxScale. Users should use the master_conditions parameter instead.

    For example:

    [repl-monitor]
    type          = monitor
    module        = mariadbmon
    servers       = server1,server2,server3
    user          = maxscale
    password      = max_passwd
    auto_failover = ON
    auto_rejoin   = ON
    master_conditions = connected_slave,running_slave
    
  • The detect_stale_slave parameter has been deprecated. It can still be used, but it will be removed in a later version of MaxScale. Users should use the slave_conditions parameter instead.

    For example:

    [repl-monitor]
    type          = monitor
    module        = mariadbmon
    servers       = server1,server2,server3
    user          = maxscale
    password      = max_passwd
    auto_failover = ON
    auto_rejoin   = ON
    slave_conditions  = running_master,writable_master
    

ColumnStore Monitor Configuration Changes in MaxScale 2.5

MaxScale 2.5 includes configuration changes for ColumnStore Monitor (csmon):

  • The version parameter was previously optional, but it is now required.

    For example:

    [col-monitor]
    type          = monitor
    module        = csmon
    servers       = server1,server2,server3
    user          = maxscale
    password      = max_passwd
    version       = 1.5
    

Binlog Router Configuration Changes in MaxScale 2.5

MaxScale 2.5 includes a completely re-implemented Binlog Router (binlogrouter):

  • Thoroughly test your configuration with the new implementation to ensure that the new version meets your needs.

Starting the MaxScale Instance

MariaDB MaxScale installations includes configuration to start, stop, restart, enable/disable on boot, and check the status of the MaxScale Instance using the operating system default process management system.

CentOS Linux 6 uses Upstart. You can manage the MaxScale process using the service and chkconfig utilities:

Operation

Command

Start

sudo service maxscale start

Stop

sudo service maxscale stop

Restart

sudo service maxscale restart

Enable during startup

sudo chkconfig --add maxscale

Disable during startup

sudo chkconfig --del maxscale

Status

sudo service maxscale status

Testing

When you have MariaDB MaxScale up and running, you should test it to ensure that it is working and that weren't any issues during startup.

Checking MaxScale Status

  1. Check that MaxScale is running properly by using the MaxCtrl utility:

    $ sudo maxctrl show maxscale
    
    ┌──────────────┬──────────────────────────────────────────────────────────────────────┐
    │ Version      │                                                               │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Commit       │ 61b8bbf7f63c38ca9c408674e66f3627a0b2192e                             │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Started At   │ Fri, 03 Jan 2020 18:05:18 GMT                                        │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Activated At │ Fri, 03 Jan 2020 18:05:18 GMT                                        │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Uptime       │ 109                                                                  │
    ├──────────────┼──────────────────────────────────────────────────────────────────────┤
    │ Parameters   │ {                                                                    │
    │              │     "libdir": "/usr/lib/x86_64-linux-gnu/maxscale",                  │
    │              │     "datadir": "/var/lib/maxscale",                                  │
    │              │     "process_datadir": "/var/lib/maxscale/data3850",                 │
    │              │     "cachedir": "/var/cache/maxscale",                               │
    │              │     "configdir": "/etc",                                             │
    │              │     "config_persistdir": "/var/lib/maxscale/maxscale.cnf.d",         │
    │              │     "module_configdir": "/etc/maxscale.modules.d",                   │
    │              │     "piddir": "/var/run/maxscale",                                   │
    │              │     "logdir": "/var/log/maxscale",                                   │
    │              │     "langdir": "/var/lib/maxscale",                                  │
    │              │     "execdir": "/usr/bin",                                           │
    │              │     "connector_plugindir": "/usr/lib/x86_64-linux-gnu/mysql/plugin", │
    │              │     "threads": 1,                                                    │
    │              │     "thread_stack_size": 8388608,                                    │
    │              │     "writeq_high_water": 0,                                          │
    │              │     "writeq_low_water": 0,                                           │
    │              │     "auth_connect_timeout": 3,                                       │
    │              │     "auth_read_timeout": 1,                                          │
    │              │     "auth_write_timeout": 2,                                         │
    │              │     "skip_permission_checks": false,                                 │
    │              │     "admin_auth": true,                                              │
    │              │     "admin_enabled": true,                                           │
    │              │     "admin_log_auth_failures": true,                                 │
    │              │     "admin_host": "127.0.0.1",                                       │
    │              │     "admin_port": 8989,                                              │
    │              │     "admin_ssl_key": "",                                             │
    │              │     "admin_ssl_cert": "",                                            │
    │              │     "admin_ssl_ca_cert": "",                                         │
    │              │     "admin_pam_readwrite_service": "",                               │
    │              │     "admin_pam_readonly_service": "",                                │
    │              │     "passive": false,                                                │
    │              │     "query_classifier": "",                                          │
    │              │     "query_classifier_cache_size": 155008819,                        │
    │              │     "retain_last_statements": 0,                                     │
    │              │     "dump_last_statements": "never",                                 │
    │              │     "session_trace": 0,                                              │
    │              │     "load_persisted_configs": true,                                  │
    │              │     "max_auth_errors_until_block": 10                                │
    │              │ }                                                                    │
    └──────────────┴──────────────────────────────────────────────────────────────────────┘