Конфигурация сервера Reindexer

В этом разделе рассматривается настройка сервера и определение его параметров, а также настройка индивидуальных уровней доступа для разных пользователей. В качестве примера используется вариант Standalone (Автономный сервер). Настройки Reindexer, установленного из deb/rpm-пакета, через brew или собранного из исходников отличаются от конфигурирования сервера при использовании официального Docker-образа. Различия будут рассмотрены в этом разделе.

Способы настройки сервера Reindexer

Настройки сервера Reindexer могут задаваться с помощью:

конфигурационного файла reindexer.conf;
аргументов командной строки, которые указываются при запуске сервера.

Если один и тот же параметр задан и в файле, и в командной строке, приоритет отдается значению, указанному в командной строке. Таким образом, параметры, заданные в конфигурационном файле сервера Reindexer, можно временно (для текущего запуска) переопределить, используя опции командной строки.

Структура файла конфигурации, настройки и соответствующие им аргументы командной строки

Чтобы использовать файл конфигурации, путь к нему необходимо задать в качестве аргумента командной строки -c (--config) при запуске сервера, например: -c file/path/config.conf. Если этот аргумент не указать при запуске сервера Reindexer, файл конфигурации использоваться не будет.

Для запуска сервера Reindexer из предсобранного пакета с помощью скрипта автозапуска по умолчанию используется команда:

/usr/bin/reindexer_server -c /etc/reindexer.conf -d --pidfile=/run/reindexer/reindexer_server.pid

Она предписывает использовать файл конфигурации, который располагается в локальной файловой системе по адресу /etc/reindexer.conf.

Конфигурационный файл по умолчанию выглядит следующим образом:

# Reindexer server configuration file
storage: 
  path: /var/lib/reindexer
  engine: leveldb
  startwitherrors: false

# Network configuration
net:
  httpaddr: 0.0.0.0:9088
  rpcaddr: 0.0.0.0:6534
  # TLS ports
  httspaddr: 0.0.0.0:9089
  rpcsaddr: 0.0.0.0:6535
  # Paths to the SSL key and certificate files if TLS-protocol support is required 
  ssl_cert: /var/lib/reindexer/cert.pem
  ssl_key: /var/lib/reindexer/key.pem
  # Unix domain socket path for ucproto scheme. Empty string or "none"-value means, that unix-socket RPC-server is disabled
  urpcaddr: none
  webroot: ${REINDEXER_INSTALL_PREFIX}/share/reindexer/web
  # Enables authorization via login/password (requires users.yml file in db directory)
  security: false
  # Idle timeout for http transactions
  tx_idle_timeout: 600
  # Http read|write operations timeouts
  # Optional timeout (seconds) for HTTP read operations (i.e. selects, get meta, transactions and others).
  # Default is 0 (forever waiting).
  http_read_timeout: 0
  # Optional timeout (seconds) for HTTP write operations (i.e. update, delete, put meta, add index, transactions new|modify|commit and others). May not be set to 0.
  # Default is 60 seconds.
  http_write_timeout: 60
  # Max replicated online-updates queue size in bytes (defaul value is 1GB)
  maxupdatessize: 1073741824

# Logger configuration
logger:
  serverlog: /var/log/reindexer/reindexer_server.log
  corelog: /var/log/reindexer/reindexer_server.log
  httplog: /var/log/reindexer/reindexer_server.log
  rpclog: ""
  loglevel: info

# System options
system:
  user: reindexer
  # Recommended maximum free cache size of tcmalloc memory allocator in bytes. Disabled by default (-1)
  allocator_cache_limit: -1
  # Recommended maximum cache size of tcmalloc memory allocator in relation to total reindexer allocated memory size, in units. Disabled by default (-1)
  allocator_cache_part: -1

# Debugging features
debug:
  pprof: false
  allocs: false

# Metrics configuration
metrics:
  prometheus: false
  # Metrics collect period in millisecods
  collect_period: 1000
  # Clients connections statistic
  clientsstats: false

Ниже в описании параметров конфигурации из файла reindexer.conf в скобках (после аббревиатуры CLI — Command Line Interface) указаны соответствующие им аргументы командной строки reindexer_server.

Файл конфигурации состоит из 6 разделов:

storage - настройки дискового хранилища. Здесь настраиваются параметры:

path (CLI: -s, --db) — путь к дисковому хранилищу. Если не задан, по умолчанию используется /tmp/reindex;
engine (CLI: -e, --engine) — тип дискового хранилища. Возможные значения — leveldb и rocksdb;
startwitherrors (CLI: --startwitherrors) — флаг, определяющий, можно ли запускать сервер при ошибках считывания данных для той или иной базы из дискового хранилища;

net - сетевые настройки. Здесь настраиваются параметры:

httpaddr (CLI: -p, --httpaddr) — адрес и порт для доступа к серверу Reindexer по протоколу HTTP. По умолчанию используется порт 9088;
rpcaddr (CLI: -r, --rpcaddr) — адрес и порт для доступа к серверу Reindexer по протоколу CPROTO (RPC черз TCP). По умолчанию используется порт 6534; urpcaddr (CLI: --urpcaddr) — путь к файлу для доступа к серверу Reindexer по протоколу UCPROTO (RPC черз Unix-сокет). Не поддерживается на Windows. По умолчанию задано значение none (unix-сокет отключен);
httpsaddr (CLI: --httpsaddr) — адрес и порт для доступа к серверу Reindexer по протоколу HTTPs. По умолчанию используется порт 9089;
rpcsaddr (CLI: --rpcsaddr) — адрес и порт для доступа к серверу Reindexer по протоколу CPROTOs (RPC с поддержкой TLS). По умолчанию используется порт 6535; ssl_cert (CLI: --ssl-cert) — путь к файлу с SSL-сертификатом в PEM-формате. Если не задан, по умолчанию Reindexer будет искать файл path/cert.pem;
ssl_key (CLI: --ssl-key) — путь к файлу с приватным SSL-ключом в PEM-формате. Если не задан, по умолчанию Reindexer будет искать файл path/key.pem;

Чтобы не запускать какой-либо сервер (HTTP, RPC, HTTPs, RPCs), нужно указать значение none для соответствующего параметра.

Для запуска Reindexer с поддержкой протокола TLS необходимо, чтобы в системе была установлена библиотека libssl, которая подключается динамически, если Reindexer собран с поддержкой openssl (по умолчанию). После успешной загрузки символов библиотеки libssl в логе должна появиться соответствующая запись или информация об ошибке. Если Reindexer’у удается загрузить динамическую библиотеку libssl, найти ключ и сертификат, он запускает HTTPs-, RPCs-серверы на соответствующих портах, если их значения не равны none.

Для RPC-соединений с поддержкой TLS через TCP используется внутренний протокол cprotos.

grpcaddr (CLI: -g, --grpcaddr) — адрес и порт для доступа к серверу Reindexer по протоколу gRPC, обычный для данного случая номер порта — 16534;

Если окажется, что какие-либо два порта (HTTP, RPC, HTTPs, RPCs, GRPC) совпадают, будет выведено сообщение об ошибке.

О факте успешного старта серверов (HTTP, RPC, HTTPs, RPCs, GRPC) делается запись в логе с указанием портов, на которых запущены сервера.

grpc (CLI: --grpc) — флаг, определяющий, следует ли включить поддержку gRPC. При необходимости использования gRPC этот флаг должен быть выставлен явно;
rpc_threading (CLI: -X, --rpc-threading) — режим обработки входящих соединений со стороны клиентов при использовании RPC. Возможные значения:
- shared (используется по умолчанию) — разделяемый режим, в котором сервер Reindexer создает фиксированное количество потоков для обработки клиентских подключений — по одному потоку на каждое физическое ядро процессора. Все подключения будут распределены между этими потоками. Запросы, от клиентов в рамках различных подключений могут быть принудительно выполнены последовательно;
- dedicated — выделенный режим. Сервер создает по отдельному потоку для обслуживания каждого соединения. Из-за существенных накладных расходов на создание потоков этот подход может оказаться неэффективным при частых повторных подключениях, инициируемых одним и тем же клиентом, либо при значительном количестве одновременно подключающихся клиентов. Вместе с тем выделенный режим позволяет достичь наибольшей степени параллелизма при выполнении запросов;
http_threading (CLI: --http-threading) — режим обработки входящих соединений со стороны клиентов при использовании HTTP. Возможные значения:
- shared (используется по умолчанию) — разделяемый режим, в котором сервер Reindexer создает фиксированное количество потоков для обработки клиентских подключений — по одному потоку на каждое физическое ядро процессора. Все подключения будут распределены между этими потоками. Запросы, от клиентов в рамках различных подключений могут быть принудительно выполнены последовательно;
- dedicated — выделенный режим. Сервер создает по отдельному потоку для обслуживания каждого соединения. Из-за существенных накладных расходов на создание потоков этот подход может оказаться неэффективным при частых повторных подключениях, инициируемых одним и тем же клиентом, либо при значительном количестве одновременно подключающихся клиентов. Вместе с тем выделенный режим позволяет достичь наибольшей степени параллелизма при выполнении запросов;

Настройки организации потоков для обработки клиентских подключений применительно к RPC и HTTP независимы и задаются индивидуально для каждого протокола;

max_http_req (CLI: --max-http-req) — максимально допустимый размер HTTP-запроса в байтах. По умолчанию действует ограничение в 2 мегабайта. Значение 0 соответствует неограниченной длине запроса. Вместе с тем потоковая передача данных (streaming) не поддерживается;
webroot (CLI: -w, --webroot) — путь к каталогу со статическими файлами, которые должны отдаваться в ответ на запросы ресурсов с соответствующими URL по протоколу HTTP. Назначается корневым каталогом дерева документов сервера;
updatessize (CLI: --updatessize) — максимальный размер кешируемых обновлений данных в байтах. Значение по умолчанию — 1 гигабайт;
security (--security) — флаг, определяющий, нужно ли задействовать механизмы авторизации/аутентификации клиентов при их обращениях через HTTP или RPC.
tx_idle_timeout (--tx-idle-timeout) — тайм-аут отсутствия активности для созданных через HTTP транзакций (таких, как добавление данных в существующую транзакцию, ее коммит или откат);
http_read_timeout (--http-read-timeout) — опциональный тайм-аут (в секундах) длительности операций чтения данных через HTTP (таких, как select, get meta и других). По умолчанию равен 0 - бесконечное ожидание;
http_write_timeout (--http-write-timeout) — опциональный тайм-аут (в секундах) длительности операций записи данных через HTTP (таких, как update, delete, put meta, операции с индексами и транзакциями new|modify|commit|rollback и другими). Не может быть равным 0. По умолчанию равен 60 секундам.
maxupdatessize (--maxupdatessize) — максимальный размер очереди обновлений для онлайн-репликации в байтах. Если очередь переполняется, то происходит попытка WAL-синхронизации. По умолчанию — 1 ГБ.

logger - настройки логирования. Здесь настраиваются параметры:

пути для файлов логов:
- corelog (CLI: --corelog) — логи ядра, то есть главной подсистемы Reindexer, за счет которой реализуется управление данными;
- serverlog (CLI: --serverlog) — логи сервера — подсистемы Reindexer, которая отвечает за взаимодействие с клиентами;
- httplog (CLI: --httplog) — логи взаимодействия по HTTP;
- rpclog (CLI: --rpclog) — логи взаимодействия по RPC;

Если для любого из этих параметров (corelog, serverlog, httplog или rpclog) установить значение none, соответствующий вид логирования будет отключен. Например с помощью аргумента командной строки --corelog=none отключаются логи ядра.

loglevel (CLI: -l, --loglevel) — уровень логирования. Возможные варианты в порядке возрастания количества логируемых событий: none, error, warning, info, trace;

system - системные настройки. Здесь настраиваются параметры:

user (CLI: -u, --user) — имя локального пользователя в операционной системе, от имени которого должен исполняться процесс сервера Reindexer;
allocator_cache_limit — рекомендуемый максимальный размер незанятой части кеша аллокатора в байтах;
allocator_cache_part — рекомендуемый максимальный размер незанятой части кеша аллокатора в долях от всей занимаемой reindexer-ом памяти;

Если для любого из параметров (allocator_cache_limit, allocator_cache_part) установить значение -1(-1.0), соответствующий способ контроля размера свободной части кеша будет отключен. Значение по умолчанию -1(-1.0). Данные параметры значимы только при использовании менеджера памяти tcmalloc (входит в комплект google-perftools).

debug - флаги, определяющие, должна ли подготавливаться отладочная информация. Здесь настраиваются параметры:

pprof (CLI: -f, --pprof) — включение http-обработчиков для pprof;
allocs (CLI: -a, --allocs) — статистика выделения оперативной памяти;

metrics— настройки сбора метрик. Здесь настраиваются параметры:

prometheus (CLI: --prometheus) — флаг, определяющий, должны ли подготавливаться метрики для системы мониторинга Prometheus;
collect_period (CLI: --prometheus-period) — периодичность сбора метрик для Prometheus в миллисекундах;
clientsstats (CLI: --clientsstats) — флаг, определяющий, нужно ли собирать статистику о соединениях с клиентами.

Конфигурирование сервера Reindexer через командную строку

Пример команды для запуска и конфигурирования Reindexer через командную строку:

/usr/bin/reindexer_server -c /etc/reindexer.conf -d --pidfile=/run/reindexer/reindexer_server.pid

Такая команда применяется для запуска Reindexer с помощью скрипта автозапуска из предсобранного пакета. Здесь используются аргументы:

ключ -c (--config) задает путь к конфигурационному файлу, который надлежит использовать серверу;
параметр -d (--daemonize) предписывает серверу запускаться в режиме демона;
аргумент --pidfile определяет путь к файлу процесса сервера.

Для получения краткой справки об аргументах командной строки запустите сервер с параметром -h (--help).

Еще один пример запуска сервера Reindexer с аргументами командной строки для конфигурирования:

reindexer_server --db /tmp/rx --rpc-threading dedicated --http-threading shared

Здесь используются аргументы:

--db - путь к дисковому хранилищу;
--rpc-threading - режим обработки входящих соединений со стороны клиентов при использовании RPC (в данном случае используется выделенный режим dedicated);
--http-threading - режим обработки входящих соединений со стороны клиентов при использовании HTTP (в данном случае используется разделяемый режим shared).

Настройка индивидуальных уровней доступа для пользователей

К каждой отдельной базе данных можно назначать индивидуальные уровни доступа каждого клиента, определяемого именем пользователя. Для этого нужно:

в каталогах баз данных (обычно пути к ним соответствуют шаблону /var/lib/reindexer/<database_name>/) разместить YAML-файлы с именем users.yml;
установить значение true флагу security в разделе net файла настроек reindexer.conf или использовать аргумент командной строки --security при запуске сервера.

Если активирован флаг security, и при этом Reindexer не найдет файла users.yml в том или ином каталоге базы данных, он автоматически создаст там такой файл с реквизитами доступа по умолчанию: логин reindexer, пароль reindexer.

Файл users.yml должен иметь вид:

user_data_read:
  hash: $1$salt1$sxceK5uCFboYZNAuscl7U.
  roles:
    *: data_read
user_data_write:
  hash: $1$salt2$mVTUg8rz3JZbWZdu8BmgB.
  roles:
    *: data_write
user_db_admin:
  hash: $1$salt3$vX3bUgz2B6qUtO8/Pp8..1
  roles:
    *: db_admin
user_owner:
  hash: $1$salt4$FP6vfMCasfDJIl7o3YzvC.
  roles:
    *: owner

Значения параметров в файле users.yml:

user_data_read, user_data_write, user_db_admin, user_owner — имена пользователей;
hash — для каждого пользователя:
- если начинается с символа $ — хеш пароля с возможным добавлением к нему некоторой произвольной последовательности символов — соли (salt) — в формате BSD MD5 Crypt. Может быть сгенерирован с помощью утилиты openssl с применением команды вида: openssl passwd -1 -salt <salt> <password>, где <salt> — соль, а <password> — пароль в виде строк;
- в противном случае — пароль в открытом виде (не рекомендуется из соображений безопасности);
roles — описание ролей пользователей по отношению к базам данных:
- * — символ, обозначающий все базы данных. Вместо него может использоваться имя конкретной базы данных или несколько имен, разделенные запятыми;
- возможные роли:
  - data_read — пользователь с этой ролью имеет право чтения информации из базы данных;
  - data_write — пользователь с такой ролью имеет право записи в базу данных;
  - db_admin — пользователь с данной ролью имеет право управлять базой данных, что подразумевает наличие прав записи, создания/удаления неймспейсов и модификации индексов;
  - owner — пользователь имеет все привилегии, связанные с доступом к базе данных, включая создание и удаление базы данных с заданным именем.

Маскирование чувствительных данных

Для системных неймспейсов (#config, #replicationstats) Reindexer автоматически выполняет маскирование системных полей, содержащих логины/пароли (DSN) при выборках и при выводе в лог. В случае неймпейса #config маскирование используется, только если была передана опция security, и отключено для пользователей с ролью db_admin и owner. Для #replicationstats и RPC-логов маскирование активно всегда.

Механизм маскирования никогда не используется для данных в пользовательских неймспейсах

Конфигурирование сервера Reindexer при использовании официального Docker-образа

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

RX_DATABASE - путь к дисковому хранилищу. По умолчанию используется значение /db;
RX_CORELOG - путь к файлу логов ядра. Значение по умолчанию stdout. Для отключения логирования нужно установить значение none;
RX_HTTPLOG - путь к файлу логов взаимодействия по протоколу HTTP. Значение по умолчанию stdout. Для отключения логирования нужно установить значение none;
RX_SERVERLOG- путь к файлу логов сервера — подсистемы Reindexer, отвечающей за взаимодействие с клиентами. Значение по умолчанию stdout. Для отключения логирования нужно установить значение none;
RX_RPCLOG - путь к файлу логов взаимодействия по RPC. Значение по умолчанию stdout. Для отключения логирования нужно установить значение none;
RX_LOGLEVEL - уровень логирования. Возможные варианты в порядке возрастания количества логируемых событий: none, warning, error, info, trace. Значение по умолчанию info;
RX_PPROF - флаг, определяющий, нужно ли включать http-обработчики для pprof. По умолчанию они отключены;
RX_SECURITY - флаг, определяющий, нужно ли включать механизмы авторизации/аутентификации клиентов при их обращениях через HTTP или RPC. По умолчанию они отключены;
RX_PROMETHEUS - флаг, определяющий, должны ли подготавливаться метрики для системы мониторинга Prometheus. По умолчанию их подготовка отключена;
RX_RPC_QR_IDLE_TIMEOUT - таймаут очистки неиспользуемых результатов запросов RPC-сервером (в секундах). Значени по умолчанию - 0 (результаты запросов не удаляются, пока не будут прочитаны до конца);
RX_DISABLE_NS_LEAK - флаг, отключающий намеренную утечку памяти при остановке сервера (существенно замедлит остановку сервера). В штатной ситуации нет причин использовать этот флаг;
RX_MAX_HTTP_REQ - максимальный размер HTTP-запроса (в байтах). Значение по умолчанию 2097152 (= 2 MB). 0 отключает ограничение на максимальный размер запроса;
RX_HTTP_READ_TIMEOUT - задаёт таймаут для всех читающих HTTP-запросов (в секундах). Значение по умолчанию 0. 0 означает, что таймаут отключен;
RX_HTTP_WRITE_TIMEOUT - адаёт таймаут для всех пишущих HTTP-запросов (в секундах). Обычно этот таймаут полезен совместно с RAFT-кластером для того, чтобы избежать бесконечного ожидания при отсутствии консенсуса. Значение по умолчанию 60. 0 означает, что таймаут отключен;
RX_SSL_CERT - путь к файлу с ssl-сертификатом. Если не передан, Reindexer будет запущен без поддержки TLS;
RX_SSL_KEY - путь к файлу с приватным ssl-ключом. Если не передан, Reindexer будет запущен без поддержки TLS;
RX_IVF_OMP_THREADS - задаёт количество OpenMP-потоков, которые будут использованы при построении векторных IVF-индексов. Не будет превышать количество логических CPU. Значение по умолчанию 8.

Для запуска Reindexer с поддержкой TLS должны быть установлены оба параметра RX_SSL_CERT и RX_SSL_KEY. Файлы сертификата и ключа могут быть добавлены в контейнер путем монтирования внешнего каталога с помощью опций -v или --mount во время запуска контейнера:

docker run -it -p 9088:9088 -p 6534:6534 -p 9089:9089 -p 6535:6535 -v<path_to_ssl_files_on_your_fs>:/cert -e RX_SSL_CERT=/cert/<your_cert>.pem -e RX_SSL_KEY=/cert/<your_key>.pem reindexer/reindexer

Также при необходимости возможно использование внешнего файла конфигурации сервера при помощи передачи пользовательской команды запуска в entrypoint (в этом случае она заменяет собой обычный запуск reindexer_server):

docker run -v <path_to_config_dir_on_your_fs>:/rx_config-it reindexer/reindexer reindexer_server -c /rx_config/reindexer.conf

Установка Reindexer Утилита reindexer_tool для управления БД Reindexer через командную строку