Глава 4. Конфигурация

MySQL Router настраивается, используя необходимый конфигурационный файл, дополнительные дополнительные конфигурационные файлы и некоторые опции также доступны из командной строки.

Самонастройка это предпочтительный и общий подход к созданию конфигурационного файла MySQL Router. См. опцию --bootstrap. Самонастройка производит полностью функциональный файл mysqlrouter.conf.

4.1. Синтаксис конфигурационного файла

Формат файла настройки напоминает традиционный формат файла INI с секциями и параметрами, но с несколькими дополнительными расширениями.

Наклонные черты вправо и влево поддерживаются. Наклонные черты влево безоговорочно копируются, поскольку они не символы ESC.

Комментарии

Конфигурационный файл может содержать строки комментария. Они начинаются с решетки (#) или точки с запятой (;) и продолжаются до конца строки.

Секции

Каждый конфигурационный файл состоит из списка секций, где каждая секция содержит последовательность опций. У каждого параметра конфигурации есть имя и значение. Например:

[section name]
option = value
option = value
option = value
[section name:optional section key]
option = value
option = value
option = value

Заголовок секции конфигурационного файла начинается с открывающей скобки ([) и завершается закрывающей скобкой (]). Допустимы знаки начального и конечного пробелов в строке, которые проигнорированы, но никаких пробелов в скобках секции быть не должно.

Заголовок секции в скобках состоит из имени и дополнительного ключа, который отделен от заголовка секции двоеточием (:). Комбинация имени секции и ключа уникальна для конфигурации.

Имена секции и ключи из последовательности из одной или более букв, цифр или подчеркивания (_). Никакие другие знаки не разрешены в имени секции или ключа.

Секция подобна пространству имен. Например, значение user зависит от своей связанной секции. user секции [DEFAULT] отсылает к пользователю системы, от мени коего запущен MySQL Router, которым также управляет опция командной строки --user. Не связанный с этим user в секции [metadata_cache] относится к пользователю MySQL, который получает доступ к метаданным сервера MySQL.

Секция Default

Специальное имя секции DEFAULT (любой регистр) используется для значений по умолчанию для опций. Опции, не найденные в секции, ищутся в секции по умолчанию. Секция по умолчанию не принимает ключ секции.

Опции

После заголовка начала секции может быть последовательность из ноля или большего количества опций, где каждая строка имеет форму:

name = value

Любые знаки начального или конечного пробела в имени или значении опции удалены прежде, чем опция обработана. Имена нечувствительны к регистру. Концевые комментарии не поддерживаются, таким образом, в этом примере опция mode получает значение "read-only # Read only mode" и поэтому произведет ошибку.

[routing:round-robin]
# Trailing comments are not supported so the following is incorrect
routing_strategy = round-robin   # Circles back to first server

Интерполяция переменной

Значения опций понимают интерполяцию переменной, используя имя опции, данное в скобах { и }. Интерполяция сделана на поиске значения опции, когда это прочитано из конфигурационного файла. Если переменная не определяется тогда, никакие замены не сделаны, и значение опции прочитано буквально.

Рассмотрите этот типовой конфигурационный файл:

[DEFAULT]
prefix = /usr/

[sample]
bin = {prefix}bin/{name}
lib = {prefix}lib/{name}
name = magic
directory = C:\foo\bar\{3a339172-6898-11e6-8540-9f7b235afb23}

Здесь значение bin = "/usr/bin/magic", значение lib = "/usr/lib/magic" и значение directory = "C:\foo\bar\{3a339172-6898-11e6-8540-9f7b235afb23}", так как переменная, названная "{3a339172-6898-11e6-8540-9f7b235afb23}" не определяется.

Предварительно определенные переменные

MySQL Router определяет предварительно определенные переменные, которые доступны конфигурационному файлу. Переменные используют скобки, например, {program} для предварительно определенно переменной program.

Таблица 4.1. Предварительно определенные переменные

Имя Описание
program Название программы, обычно mysqlrouter
origin Путь к каталогу, где расположен двоичный модуль
logging_folder Путь к папке для файлов журнала
plugin_folder Путь к папке для плагинов
runtime_folder Путь к папке для данных во время выполнения
config_folder Путь к папке для конфигурационных файлов

4.2. Местоположения конфигурационного файла

MySQL Router ищет конфигурационный файл по умолчанию при запуске и произвольно загружает определенные пользователем конфигурационные файлы во времени выполнения из командной строки.

Местоположения конфигурационного файла по умолчанию

По умолчанию MySQL Router просматривает определенные местоположения для своих конфигурационных файлов, которые зависят от платформы и того, как MySQL Router был установлен.

Можно изменить местоположения по умолчанию во время компиляции при помощи опции -DROUTER_CONFIGDIR=<path>. Вы могли также отредактировать cmake/settings.cmake, чтобы изменить местоположения по умолчанию прежде, чем собрать MySQL Router, таким образом добавляя новые местоположения или исключения для определенных платформ.

Выполните mysqlrouter --help, чтобы увидеть местоположения конфигурационного файла по умолчанию (и их доступность) на вашей системе. Например:

shell> mysqlrouter --help

MySQL Router v8.0.14 on macOS v10.12 (64-bit) (GPL community edition)
Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of
their respective owners.

Start MySQL Router.

Configuration read from the following files in the given order (enclosed
in parentheses means not available for reading):
(/usr/local/mysql-router/mysqlrouter.conf)
/Users/philip/.mysqlrouter.conf
Plugins Path:
/usr/local/lib/mysqlrouter
Default Log Directory:
/usr/local/mysql-router
Default Persistent Data Directory:
/usr/local/mysql-router/data
Default Runtime State Directory:
/usr/local/mysql-router/run

Usage: mysqlrouter [-v|--version] [-h|--help]

...

Конфигурационный файл по умолчанию не загружается, если определенный пользователями конфигурационный файл передается опцией --config.

В Linux MySQL Router просматривает следующие местоположения по умолчанию, хотя эти местоположения системно-зависимы:

  1. /etc/mysqlrouter/mysqlrouter.conf

    В отличие от сервера MySQL, обратно совместимый путь "/etc/mysqlrouter.conf" не поддерживается.

  2. $HOME/.mysqlrouter.conf

Для обратной совместимости MySQL Router также ищет вариант .ini в каждом каталоге. При этом Router смотрит первоначальный каталог для варианта .conf, затем вариант .ini, затем повторяет процесс в следующем каталоге, который, как правило, является корневым каталогом пользователя в системе.

Определенные пользователями и дополнительные конфигурационные файлы

Две опции параметров командной строки управляет этими местоположениями конфигурационного файла:

Например:

shell> mysqlrouter --config /custom/path/to/router.conf \
                      --extra-config /another/config.conf

Многократные дополнительные параметры конфигурации могут быть переданы, и файлы загружаются в порядке, в которым они введены опцией --config, загружаемые перед --extra-config:

shell> mysqlrouter --extra-config a.conf --config b.conf \
                      --extra-config c.conf

В вышеупомянутом примере b.conf загружается сначала, затем a.conf и c.conf, именно в этом порядке. Кроме того, конфигурационный файл по умолчанию, такой как /etc/mysqlrouter/mysqlrouter.conf, не загружается потому, что используется --config.

Каждый загруженный конфигурационный файл отвергает параметры конфигурации от ранее прочитанных конфигурационных файлов.

Местоположения конфигурационного файла по умолчанию (Linux)

Ниже перечислено расположение файла по умолчанию, чтобы прочитать конфигурационные файлы на популярных платформах Linux.

Выполните mysqlrouter --help, чтобы увидеть местоположения конфигурационного файла по умолчанию (и доступность) в вашей системе.

Местоположения конфигурационного файла по умолчанию (Windows)

Выполните mysqlrouter --help, чтобы увидеть местоположения конфигурационного файла по умолчанию (и доступность) в вашей системе.

4.3. Опции настройки

Опции конфигурационного файла и параметры командной строки служат различным целям и описаны в отдельных местах.

При bootstrapping параметры настройки произведенного конфигурационного файла зависят от опций, переданых mysqlrouter. Например, передача --conf-use-sockets позволяет сокетные соединения, определяя socket для каждого маршрута в произведенном конфигурационном файле. Или --directory добавляет все произведенные файлы и подкаталоги к единственному каталогу и регулирует произведенные значения конфигурационного файла соответственно.

4.3.1. Командная строка MySQL Router

Эта секция описывает команды MySQL Router. Команда mysqlrouter используется для большинства задач, включая самонастройку и управление MySQL Router, mysqlrouter_plugin_info это дополнительное средство отладки.

4.3.1.1. Параметры командной строки mysqlrouter

MySQL Router принимает параметры командной строки, которые передаются в mysqlrouter, чтобы затронуть его поведение или изменить маршрутизатор на основе кластера InnoDB.

Запуская Router, можно произвольно использовать --config, чтобы перейти в местоположение главного конфигурационного файла (иначе местоположение по умолчанию используется), и --extra-config для дополнительного конфигурационного файла.

Самонастройка параметров командной строки затрагивает произведенные файлы и каталоги, которые используются, запуская MySQL Router.

Обзор опций mysqlrouter

Таблица 4.2. Основные опции

Формат Описание
--config Прочитайте параметры конфигурации из обеспеченного файла.
--extra-config Прочитайте этот файл после того, как конфигурационные файлы будут прочитаны из местоположений по умолчанию или из файлов, определенных опцией --config.
--help Вывод справочной информации.
--user Запустить mysqlrouter как пользователь, имеющий указанное имя или числовой идентификатор пользователя.
--version Вывод информации о версии.

Таблица 4.3. Опции самонастройки

ФорматОписание Введено
--account-host Образец хоста для настройки учетных записей. 8.0.12
--bootstrap Настроить Router для работы с кластером MySQL InnoDB.
--bootstrap-socket Соединитесь с сервером метаданных MySQL через сокет Unix, используется вместе с --bootstrap.
--conf-base-port Основной порт, чтобы использовать для портов Router.
--conf-bind-address IP-адрес интерфейса, с которым надо связать роутер.
--conf-skip-tcp Отключить ли закрепление порта TCP для поступающих связей.
--conf-use-sockets Использовать ли сокеты Unix.
--connect-timeout Число секунд перед попытками подключения к серверу метаданных. 8.0.4
--directory Создает отдельный каталог для нового роутера.
--force Реконфигурация возможно существующего маршрутизатора.
--force-password-validation Создавая учетную запись пользователя автоматически, не пропускайте стадию validate_password.
--master-key-reader Скрипт, который возвращает главный ключ в STDOUT. 8.0.12
--master-key-writer Скрипт, который читает главный ключ из STDIN. 8.0.12
--name Дает символьное имя для роутера.
--password-retries Количество повторений, чтобы использовать для создания пароля пользователя.
--read-timeout Число секунд перед операциями чтения метаданных сервера. 8.0.4
--report-host Имя хоста роутера, отвергает автообнаружение. 8.0.12

Таблица 4.4. Опции SSL

ФорматОписание Введено
--ssl-ca Путь к файлу сертификата SSL, чтобы проверить сертификат сервера.
--ssl-capath Каталог, который содержит файлы доверенных сертификатов SSL Certificate Authority
--ssl-cert Клиентский сертификат SSL, чтобы облегчить клиентскую идентификацию во время bootstrap 8.0.4
--ssl-cipher Отделенный двоеточиями список шифров SSL, если SSL позволен.
--ssl-crl Путь к файлу SSL CRL, чтобы использовать, проверяя сертификат сервера.
--ssl-crlpath Путь к каталогу, содержащему файлы SSL CRL, чтобы использовать, проверяя сертификат сервера.
--ssl-key Частный ключ SSL, чтобы облегчить клиентскую идентификацию во время bootstrap8.0.4
--ssl-mode Способ связи SSL для использования во время bootstrap и нормального функционирования, соединяясь с сервером метаданных. Аналогично --ssl-mode в клиенте mysql.
--tls-version Список разделенных запятой значений версий TLS, если SSL позволен.

Таблица 4.5. Опции сервисов Windows

Формат Описание
--clear-all-credentials Удаляет все сохраненные данные авторизации
--install-service В Windows установить MySQL Router как сервис MySQLRouter и установить его автоматически запускаться, когда Windows перезапустится.
--install-service-manual В Windows установить MySQL Router как сервис MySQLRouter, который может быть вручную запущен.
--remove-credentials-section Удалите параметры авторизации.
--remove-service Удалить MySQL Router как сервис Windows.
--service Запустить MySQL Router как сервис Windows.
--update-credentials-section Обновите данные авторизации.
Описание опций mysqlrouter

4.3.1.2. Параметры командной строки mysqlrouter_plugin_info

mysqlrouter_plugin_info это средство отладки, которое осматривает плагин MySQL Router для поиска потенциальных конфликтов и общих проблем.

Примеры как использовать:

shell> ./mysqlrouter_plugin_info --help

Usage:
./mysqlrouter_plugin_info <mysqlrouter_plugin_file> <mysql_plugin_name>

Example:
./mysqlrouter_plugin_info /usr/lib/mysqlrouter/routing.so routing

To print help information:
./mysqlrouter_plugin_info --help
To print application version:
./mysqlrouter_plugin_info --version

shell> ./bin/mysqlrouter_plugin_info --version

MySQLRouter Plugin Info App 8.0.3
shell> ./bin/mysqlrouter_plugin_info lib/mysqlrouter/routing.so routing
{
"abi-version": "2.0",
"arch-descriptor": "i386/darwin//",
"brief": "Routing MySQL connections between MySQL clients/connectors and servers",
"plugin-version": "0.0.1",
"requires": [],
"conflicts": []
}

4.3.2. Варианты конфигурационного файла

Когда запущен, MySQL Router читает список конфигурационных файлов, которые вместе составляют конфигурацию маршрутизатора. По крайней мере один конфигурационный файл требуется.

MySQL Router читает опции из конфигурационных файлов, которые напоминают традиционный формат файла INI с секциями и вариантами. Они определяют набор вариантов, когда MySQL Router запускается. Для получения информации о синтаксисе файла посмотрите раздел 4.1.

Варианты определяются согласно секциям, которые диктуют значение выбора. Например, user в секции [DEFAULT] отсылает к пользователю системы, запустившему роутер, в то время как user в секции [metadata_cache] отсылает к пользователю MySQL для доступа к метаданным.

Следующие таблицы разделены по секциям и суммируют опции MySQL Router, определенные в конфигурационном файле MySQL Router. Подробная информация о каждом из этих вариантов, таких как описания и позволенные значения, есть ниже этих таблиц.

Основные опции

Таблица 4.7. Секция [DEFAULT]

Опция Описание Тип
config_folder Путь к конфигурационным файлам String
connect_timeout Число секунд тайм-аута при попытках подключения к серверу метаданных Integer
keyring_path Путь к файлу брелока String
logging_folder Путь к журналам регистрации String
master_key_path Путь к основному файлу брелока String
master-key-reader Скрипт, который возвращает главный ключ на STDOUT String
master-key-writer Скрипт, который читает главный ключ из STDIN String
plugin_folder Путь к плагинам роутера String
runtime_folder Путь к файлам времени выполнения String
sinks Метод(ы) журналирования, чтобы получить данные String
thread_stack_size Размер в KB памяти, выделенной каждому стеку потока Integer
user Пользователь системы, который запустил роутер String

Опции маршрутизации

Таблица 4.8. Секция [routing]

Опция Описание Тип
bind_address Адрес роутера, также используется bind_port, если порт не определяется String
bind_port Порт по умолчанию, используется bind_address Integer
client_connect_timeout Максимальное количество секунд, чтобы получить пакеты от сервера MySQL Integer
connect_timeout Число секунд тайми-аута при подключении к серверу MySQL Integer
destinations Места назначения маршрутов как список разделенных запятой значений серверов MySQL или как определение кэша метаданных String
dynamic_config Путь к произведенному файлу JSON, используемому для отслеживания и хранения активных адресов сервера метаданных кластера MySQL InnoDB String
max_connect_errors Максимальное количество неудавшихся связей сервера MySQL перед отказом Integer
max_connections Максимальное количество связей, назначенных на сервер MySQL назначения Integer
mode Как маршрутизатор выбирает серверы назначения MySQL String
protocol Протокол для соединения с MySQL Server String
read_timeout Число секунд тайм-аута операций чтения сервера метаданных Integer
routing_strategy (Дополнительная) стратегия маршрутизации, как роутер выбирает серверы назначения MySQL String
socket Путь к файлу сокета unixString

Опции кэша метаданных

Таблица 4.9. Секция [metadata_cache]

Опция Описание Тип
bootstrap_server_addresses Серверы MySQL с метаданными, как список разделенных запятой значений String
metadata_cluster Имя кластера InnoDB String
router_id Router IDInteger
ssl_mode Способ связи SSL для соединения с сервером метаданных, по умолчанию PREFERRED, если не задан String
ttl Time To Live в секундах Integer
user Пользователь MySQL, который получает доступ к схеме метаданных MySQL Server String

Опции журналирования

Таблица 4.10. Секция [logger]

Опция Описание Тип
level Уровень журналированияString

Таблица 4.11. Секция [http_server]

Опция Описание Тип
bind_address Адрес IPv4, который связан с портом HTTP String
port Порт TCP сервера HTTPInteger
require_realm Имя [http_auth_realm]String
ssl_cert Имя файла сертификата SSLString
ssl_cipher Одобренные шифры SSLString
ssl_dh_param Имя файла параметра DHString
ssl Позволяет поддержку TLSv1.2 или более позднегоInteger
ssl_key Имя файла ключа SSLString
static_folder Каталог для статических файлов сервера HTTP String

Описания опций конфигурационного файла MySQL Router

4.3.3. Пример конфигурационного файла

Вот основной пример направления связи к кластеру MySQL InnoDB mycluster. Включены протоколы classic и X protocol, это использует связи TCP/IP вместо сокетов Unix и это было произведено, используя --bootstrap как автономная конфигурация с --directory, установелнной в /opt/routers/myrouter.

В этом примере трафик чтения-записи (primary) посылают по портам 6446 (classic) или 64460 (x), трафик только чтения (secondaries) использует порты 6447 (classic) или 64470 (x).

Ключи секции направления (такие как mycluster_default_rw) дополнительные, но использовать эти описательные ключи секции полезно для отладки, а также позволяет многократные секции конфигурации для того же самого плагина.

destinations ссылается на metadata-cache, чтобы использовать кэш метаданных кластера InnoDB, который динамично формирует информацию о хосте. Альтернативно destinations мог быть списком разделенных запятой значений хостов, чтобы задать основное направление связи без кластера InnoDB.

# File automatically generated during MySQL Router bootstrap
[DEFAULT]
logging_folder=/opt/routers/myrouter/log
runtime_folder=/opt/routers/myrouter/run
data_folder=/opt/routers/myrouter/data
keyring_path=/opt/routers/router/data/keyring
master_key_path=/opt/routers/myrouter/mysqlrouter.key
connect_timeout=30
read_timeout=30

[logger]
level = INFO

[metadata_cache:mycluster]
router_id=5
bootstrap_server_addresses=mysql://localhost:3310,mysql://localhost:3320,mysql://localhost:3330
user=mysql_router5_6owf3spq1c6n
metadata_cluster=mycluster
ttl=5

[routing:mycluster_default_rw]
bind_address=0.0.0.0
bind_port=6446
destinations=metadata-cache://mycluster/default?role=PRIMARY
routing_strategy=round-robin
protocol=classic

[routing:mycluster_default_ro]
bind_address=0.0.0.0
bind_port=6447
destinations=metadata-cache://mycluster/default?role=SECONDARY
routing_strategy=round-robin
protocol=classic

[routing:mycluster_default_x_rw]
bind_address=0.0.0.0
bind_port=64460
destinations=metadata-cache://mycluster/default?role=PRIMARY
routing_strategy=round-robin
protocol=x

[routing:mycluster_default_x_ro]
bind_address=0.0.0.0
bind_port=64470
destinations=metadata-cache://mycluster/default?role=SECONDARY
routing_strategy=round-robin
protocol=x