bihactl

bihactl
Пред.	Наверх	Серверные приложения Postgres Pro	Начало	След.

bihactl — создать BiHA-кластер в Postgres Pro

Синтаксис

bihactl cluster init [параметр...] --host --pgdata

bihactl cluster status [параметр...]

bihactl cluster show-config [параметр...]

bihactl node add [параметр...] --pgdata { --use-leader | --magic-file | --magic-string }

bihactl segment add [параметр...] { --use-leader | --magic-file | --magic-string }

bihactl --version

bihactl --help

Описание

bihactl — это утилита командной строки, которая позволяет создать BiHA-кластер, изменять его состав, а также отслеживать статус кластера. За подробной информацией о решении BiHA обратитесь к главе Встроенная отказоустойчивость (BiHA).

Важно

bihactl для Postgres Pro Enterprise 17.8 и выше обеспечивает обратную совместимость с bihactl для Postgres Pro Enterprise 16.X и Postgres Pro Enterprise 17.7 и ниже. Однако команды bihactl из предыдущих версий считаются устаревшими, поэтому рекомендуется использовать команды bihactl, описанные в этой документации.

Важно

bihactl для Postgres Pro Enterprise не поддерживается на архитектуре процессоров Эльбрус.

В этом разделе содержится информация о командах утилиты bihactl:

Узел-последователь можно добавить с использованием «‎‎магической» строки, сохранённой после выполнения команды bihactl cluster init, передав в команде bihactl node add параметр -s.

Справка по командной строке #

cluster init #

Синтаксис:

bihactl cluster init [--biha-node-id=идентификатор_узла]
                     [--biha-port=порт_biha]
                     [--cluster-name=имя_кластера]
                     [--convert  [--server-cert=/путь/к/сертификату_сервера \
                     --server-key=/путь/к/ключу_сервера]]
                     [--enable-proxima]
                     --host=хост
                     [--magic-file=магический_файл]
                     [--max-replicas=макс_число_реплик]
                     [--minnodes=мин_число_узлов]
                     [--node-name=имя_узла]
                     [--no-password]
                     [--nquorum=значение_кворума]
                     [--options=параметры_initdb]
                     --pgdata=каталог_данных
                     [--port=порт]
                     [--preferred-roles=предпочтительные_роли_для_репликации]
                     [--priority=приоритет_узла]
                     [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
                     --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]] \
                     [--sync-standbys=число_синхронных_ведомых_серверов [--sync-standbys-min=мин_число_синхронных_ведомых_серверов]]
                     [--use-ssl]

Инициализирует кластер и задаёт узел-лидер. При выполнении этой команды bihactl запускает утилиту initdb. На этом этапе также можно указать необходимые параметры этой утилиты при помощи флага -o.

Эта команда может принимать следующие параметры:

-I id_узла --biha-node-id=id_узла #

Указывает уникальный идентификатор узла.

-P порт_biha --biha-port=порт_biha #

Указывает порт для обмена служебной информацией между узлами. Если порт не указан, устанавливается значение --port + 1.

--biha-ssl-mode=режим_ssl #

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

verify-full (по умолчанию)
require
verify-ca

За подробной информацией о режимах обратитесь к sslmode.

--cluster-name=имя_кластера #

Указывает имя BiHA-кластера. Имя по умолчанию — biha_node_1111.

-C --convert #

Преобразовывает существующий узел в узел-лидер отказоустойчивого кластера.

-x --enable-proxima #

Включает расширение proxima с параметрами по умолчанию в BiHA-кластере при его создании с нуля или на лидере при преобразовании существующего кластера конструкции ведущий-ведомый в BiHA-кластер.

-h хост --host=хост #

Указывает хост для входящих подключений. Значение по умолчанию — PGHOST.

-f файл_с_магической_строкой --magic-file=файл_с_магической_строкой #

Указывает путь к «магическому» файлу, который содержит закодированные данные для подключения к лидеру. Файл должен существовать в момент выполнения команды bihactl node add.

--max-replicas=макс_число_реплик #

Указывает максимальное число репликационных подключений biha к узлу, т.е. максимальное число процессов walsender, где в качестве application_name указано biha_node_*.

Возможные значения: 0, INT_MAX. Значение по умолчанию — INT_MAX, количество подключений неограниченно.

-M мин_число_узлов --minnodes=мин_число_узлов #

Указывает минимальное число работающих узлов, при котором узел-лидер будет доступен для пишущих транзакций. Если параметр не задан, его значение будет равно значению параметра --nquorum.

--no-password #

Если задан, bihactl не предлагает вручную указать пароль для роли biha_replication_user.

--node-name=имя_узла #

Указывает имя узла-лидера.

-N значение_кворума --nquorum=значение_кворума #

Указывает минимальное число узлов, которые должны проголосовать за нового лидера при отказе текущего лидера. Значение по умолчанию — 2.

Устанавливая это значение, принимайте во внимание возможный риск разделения кластера. Рекомендуется использовать следующую формулу: (общее_число_узлов + 1)/2. Например, если в кластере 3 узла, значение_кворума должно быть 2.

-o параметры_initdb --options=параметры_initdb #

Дополнительно указывает параметры утилиты initdb.

-D каталог_данных --pgdata=каталог_данных #

Указывает каталог, где будет храниться кластер баз данных. По умолчанию bihactl использует значение PGDATA.

-p порт --port=порт #

Указывает порт узла для входящих соединений.

Если не указан, bihactl использует значение по умолчанию — 5432.

--preferred-roles=предпочтительные_роли_для_репликации #

Указывает предпочтительную роль узла для репликации в BiHA-кластере с каскадной репликацией.

Возможные значения: комбинации L (лидер), F (последователь) и R (рефери). Значение должно содержать от 1 до 3 символов, которые не должны повторяться. Например: L, F, LFR или LF.

Значение по умолчанию — L, которое означает, что данные реплицируются только с лидера.

--priority=приоритет_узла #

Задаёт вес узла, который влияет как на выборы, так и на репликацию в кластере, в миллисекундах. Возможные значения: 0, INT_MAX. Значение по умолчанию — -1, при котором параметр игнорируется. Значение параметра можно изменить только функцией biha.set_priority.

BiHA использует этот параметр конфигурации для следующих целей:

Задать тайм-аут начала репликации при выборе источника репликации в BiHA-кластере с каскадной репликацией. Чем выше значение, тем позднее узел начинает репликацию и разрешает подключение менее приоритетных узлов. Параметр необходим для того, чтобы узлы кластера могли наладить схему каскадной репликации автоматически.
Установить приоритет узла в кластере с синхронной репликацией. Значение определяет тайм-аут, по истечении которого узел предложит себя в качестве кандидата на выборах. Нулевое значение указывает на самый высокий приоритет.
Важно
Чтобы обеспечить корректную работу параметра, задайте для --sync-standbys значение на одну единицу меньше, чем общее число узлов кластера.

--root-cert=/путь/к/сертификату_цс #

Указывает путь к сертификату доверенного ЦС в формате PEM.

--server-cert=/путь/к/сертификату_сервера #

Указывает путь к SSL-сертификату для узла BiHA в формате PEM.

--server-key=/путь/к/ключу_сервера #

Указывает путь к закрытому ключу сертификата --server-cert в формате PEM.

-Y число_синхронных_ведомых_серверов --sync-standbys=число_синхронных_ведомых_серверов #

Включает кворумную синхронную репликацию, устанавливая параметр synchronous_standby_names и указывая число синхронных резервных узлов (кворум) с методом ANY. Рекомендуется указывать значение число_синхронных_резервных_узлов меньше, чем значение параметра --minnodes.

-y мин_число_синхронных_ведомых_серверов --sync-standbys-min=мин_число_синхронных_ведомых_серверов #

Включает нестрогую кворумную синхронную репликацию, указывая значение поля MIN параметра synchronous_standby_names. Это значение задаёт минимальное число синхронных резервных узлов, которые должны быть доступны, чтобы лидер продолжал работать. Значение минимальное_число_синхронных_резервных_узлов должно быть меньше, чем --sync-standbys, и не может быть отрицательным. Если параметр не задан, BiHA-кластер будет работать в соответствии с ограничениями синхронной репликации по умолчанию, т.е. лидер будет недоступен для пишущих транзакций, пока все последователи не достигнут его текущего состояния.

-S --use-ssl #

Включает защищённый режим передачи служебной информации между узлами кластера по протоколу SSL/TLS управляющего канала biha (BCP).

Важно

Чтобы использовать SSL для служебных подключений, установленная версия OpenSSL должна быть 1.1.1 или выше. В противном случае BiHA-кластер будет создан без SSL для служебных подключений, и в журнале будет записано соответствующее сообщение.

--user-biha-cert=/путь/к/сертификату_клиента #

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента #

Указывает путь к закрытому ключу для сертификата --user-biha-cert в формате PEM.

cluster show-config #

Синтаксис:

bihactl cluster show-config [--format=формат_вывода_данных]
                            [--host=хост]
                            [--magic-file=магический_файл]
                            [--magic-string=магическая_строка]
                            [--port=порт]
                            [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
                            --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]]

Отображает полную информацию о конфигурации кластера. Эта команда может принимать следующие параметры:

--biha-ssl-mode=режим_ssl

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

verify-full (по умолчанию)
require
verify-ca

За подробной информацией о режимах обратитесь к sslmode.

--format=формат_вывода_данных

Указывает формат вывода информации о статусе. Возможные значения: json, yaml и table (по умолчанию).

-h хост --host=хост

Указывает хост для входящих подключений. Значение по умолчанию — PGHOST.

-f файл_с_магической_строкой --magic-file=файл_с_магической_строкой

Указывает путь к файлу с «‎‎магической» строкой, содержащей закодированные данные для подключения к узлу-лидеру.

-s магическая_строка --magic-string=магическая_строка

Указывает «‎‎магическую» строку, содержащую закодированные данные для подключения к лидеру.

-p порт --port=порт

Указывает порт узла для входящих соединений.

Если не указан, bihactl использует значение по умолчанию — 5432.

--root-cert=/путь/к/сертификату_цс

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к сертификату доверенного ЦС в формате PEM.

--user-biha-cert=/путь/к/сертификату_клиента

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к закрытому ключу для сертификата -user-biha-cert в формате PEM.

cluster status #

Синтаксис:

bihactl cluster status [--format=формат_вывода_данных]
                       [--host=хост]
                       [--magic-file=магический_файл]
                       [--magic-string=магическая_строка]
                       [--port=порт]
                       [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
                       --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]]

Проверяет статус узла и отображает его в представлении biha.status_v. Эта команда может принимать следующие параметры:

--biha-ssl-mode=режим_ssl

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

verify-full (по умолчанию)
require
verify-ca

За подробной информацией о режимах обратитесь к sslmode.

--format=формат_вывода_данных

Указывает формат вывода информации о статусе. Возможные значения: json, yaml и table (по умолчанию).

-h хост --host=хост

Указывает хост для входящих подключений. Значение по умолчанию — PGHOST.

-f файл_с_магической_строкой --magic-file=файл_с_магической_строкой

-s магическая_строка --magic-string=магическая_строка

Указывает «‎‎магическую» строку, содержащую закодированные данные для подключения к лидеру.

-p порт --port=порт

Указывает порт узла для входящих соединений.

Если не указан, bihactl использует значение по умолчанию — 5432.

--root-cert=/путь/к/сертификату_цс

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к сертификату доверенного ЦС в формате PEM.

--user-biha-cert=/путь/к/сертификату_клиента

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Указывает путь к закрытому ключу для сертификата -user-biha-cert в формате PEM.

node add #

Синтаксис:

bihactl node add [--backup-method=средство_резервного_копирования]
                 [--backup-options=параметры_резервного_копирования]
                 [--biha-node-id=идентификатор_узла]
                 [--biha-port=порт_biha]
                 [--can-vote=true_или_false]
                 [--convert-standby [--server-cert=/путь/к/сертификату_сервера \
                 --server-key=/путь/к/ключу_сервера]]
                 [--host=хост]
                 [--max-replicas=макс_число_реплик]
                 [--mode=режим_узла] [--referee-with-postgres-db]]
                 [--name=имя_узла]
                 [--pgdata=каталог_данных]
                 [--port=порт]
                 [--preferred-roles=предпочтительные_роли_для_репликации]
                 [--priority=приоритет_узла]
                 [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
                 --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]]
                 {--segment-id=идентификатор_сегмента | --segment-name=имя_сегмента}
                 {--use-leader=информация_для_подключения | --magic-string=магическая_строка | --magic-file=магический_файл}

Добавляет последователя в инициализированный кластер. При выполнении этой команды создаётся резервная копия лидера с помощью pg_basebackup. При добавлении узла утилита bihactl удерживает слот репликации, вызывая pg_basebackup с параметрами --slot=ИМЯ_СЛОТА, --wal-method=stream, --checkpoint=fast, что предотвращает удаление WAL на лидере во время создания резервной копии.

Примечание

Узлы необходимо добавлять по очереди. Не добавляйте новый узел, если создание ранее добавленного узла ещё не завершено и узел находится в состоянии CSTATE_FORMING. В противном случае может возникнуть следующая ошибка:

          WARNING:  aborting backup due to backend exiting before pg_backup_stop was
          called

Для выбора утилиты резервного копирования используется параметр -m, а параметры выбранной утилиты можно задать при помощи параметра -O.

Эта команда может принимать следующие параметры:

-m метод_резервирования --backup-method=метод_резервирования #

Указывает утилиту резервного копирования. Единственное допустимое значение — pg_basebackup, которое является значением по умолчанию. Если не указывать параметр --backup-method, будет использован метод резервного копирования по умолчанию.

Если вы хотите добавить последователя с помощью pg_probackup, обратитесь к соответствующей инструкции.

-O параметры_резервирования --backup-options=параметры_резервирования #

Указывает дополнительные параметры pg_basebackup.

-I id_узла --biha-node-id=id_узла #

Указывает уникальный идентификатор узла.

--biha-ssl-mode=режим_ssl #

Примечание

Этот параметр необходимо указывать, если используется SSL-аутентификация для biha_replication_user.

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

verify-full (по умолчанию)
require
verify-ca

За подробной информацией о режимах обратитесь к sslmode.

-P порт_biha --biha-port=порт_biha #

--can-vote #

Определяет, может ли узел голосовать. Значение по умолчанию — true. Если задано false, узел не может голосовать, а также не может выдвигать себя в качестве кандидата на выборах лидера.

-c --convert-standby #

Преобразовывает существующий узел в узел-последователь отказоустойчивого кластера. Узел должен быть репликой узла-лидера до преобразования.

-h хост --host=хост #

Указывает хост для входящих подключений. Значение по умолчанию — PGHOST.

-f файл_с_магической_строкой --magic-file=файл_с_магической_строкой #

Использует файл с «‎‎магической» строкой, содержащей закодированные данные, для подключения к узлу-лидеру.

-s магическая_строка --magic-string=магическая_строка #

Использует «‎‎магическую» строку, содержащую закодированные данные, для подключения к узлу-лидеру.

--max-replicas=макс_число_реплик #

Возможные значения: 0, INT_MAX. Значение по умолчанию — INT_MAX, количество подключений неограниченно.

-r режим_работы_узла --mode=режим_работы_узла #

Указывает режим работы узла. Допустимы следующие значения:

regular — узел может быть как лидером, так и последователем. Это значение по умолчанию.
referee — узел только участвует в выборах лидера и не содержит пользовательских баз данных.
referee_with_wal — узел участвует в выборах лидера так же, как в режиме referee, и получает все файлы WAL от узла-лидера.

По умолчанию база данных postgres не копируется на узел в режиме referee или referee_with_wal. Чтобы скопировать базу данных postgres на рефери, воспользуйтесь параметром --referee-with-postgres-db.

--node-name=имя_узла #

Указывает имя узла-последователя. Если не указано, имя генерируется автоматически в формате biha_node_ + --biha-node-id. Например, если --biha-node-id — 1, имя узла — biha_node_1.

-D каталог_данных --pgdata=каталог_данных #

Указывает каталог, где будет храниться кластер баз данных. Если параметр не задан, bihactl будет использовать значение PGDATA.

-p порт --port=порт #

Указывает порт узла для входящих соединений.

Если не указан, bihactl использует значение по умолчанию — 5432.

--preferred-roles=предпочтительные_роли_для_репликации #

Указывает предпочтительную роль узла для репликации в BiHA-кластере с каскадной репликацией.

Значение по умолчанию — L, которое означает, что данные реплицируются только с лидера.

--priority=приоритет_узла #

BiHA использует этот параметр конфигурации для следующих целей:

Задать тайм-аут начала репликации при выборе источника репликации в BiHA-кластере с каскадной репликацией. Чем выше значение, тем позднее узел начинает репликацию и разрешает подключение менее приоритетных узлов. Параметр необходим для того, чтобы узлы кластера могли наладить схему каскадной репликации автоматически.
Установить приоритет узла в кластере с синхронной репликацией. Значение определяет тайм-аут, по истечении которого узел предложит себя в качестве кандидата на выборах. Нулевое значение указывает на самый высокий приоритет.
Важно
Чтобы обеспечить корректную работу параметра, задайте для --sync-standbys значение на одну единицу меньше, чем общее число узлов кластера.

-R --referee-with-postgres-db #

Копирует базу данных postgres со всеми объектами на узел-рефери. Этот параметр можно использовать только при добавлении узла в режиме referee или referee_with_wal.

--root-cert=/путь/к/сертификату_цс #

Указывает путь к сертификату доверенного ЦС в формате PEM.

--server-cert=/путь/к/сертификату_сервера #

Указывает путь к SSL-сертификату для узла BiHA в формате PEM.

--server-key=/путь/к/ключу_сервера #

Указывает путь к закрытому ключу сертификата --server-cert в формате PEM.

--segment-id=идентификатор_сегмента #

Указывает уникальный идентификатор сегмента, в который добавляется узел. Если сегмент не указать, по умолчанию узел будет добавлен в сегмент 111. Необходимо использовать либо --segment-id, либо --segment-name для указания сегмента.

--segment-name=имя_сегмента #

Указывает имя сегмента, в который добавляется узел. Если сегмент не указать, по умолчанию узел будет добавлен в сегмент 111. Необходимо использовать либо --segment-name, либо --segment-id для указания сегмента.

-l параметры_подключения --use-leader=параметры_подключения #

Указывает параметры подключения к узлу-лидеру в следующем формате:

host=хост_узла_лидера port=порт_лидера biha-port=порт_biha_лидера

--user-biha-cert=/путь/к/сертификату_клиента #

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента #

Указывает путь к закрытому ключу для сертификата --user-biha-cert в формате PEM.

segment add #

Синтаксис:

bihactl segment add [--id=идентификатор_сегмента]
                    [--minnodes=мин_число_узлов]
                    [--name=имя_сегмента]
                    [--nquorum=значение_кворума]
                    [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
                    --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]]
                    {--use-leader=информация_для_подключения | --magic-string=магическая_строка | --magic-file=магический_файл}

Добавляет сегмент, который предназначен для объединения узлов BiHA-кластера, размещённых в одном центре обработки данных.

Предупреждение

Эта команда является частью функциональности многоуровневой геораспределённости и катастрофоустойчивости, которая в настоящий момент является экспериментальной и не рекомендуется к использованию в производственной среде.

Эта команда может принимать следующие параметры:

--biha-ssl-mode=режим_ssl #

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

verify-full (по умолчанию)
require
verify-ca

За подробной информацией о режимах обратитесь к sslmode.

-I идентификатор_сегмента --id=идентификатор_сегмента #

Указывает уникальный идентификатор сегмента.

-f файл_с_магической_строкой --magic-file=файл_с_магической_строкой #

Использует файл с «‎‎магической» строкой, содержащей закодированные данные для подключения к узлу кластера.

-s магическая_строка --magic-string=магическая_строка #

Использует «‎‎магическую» строку, содержащую закодированные данные для подключения к узлу кластера.

--name=имя_сегмента #

Указывает имя сегмента. Если не указано, имя генерируется автоматически в формате biha_node_ + --id. Например, если --id — 1, имя сегмента — biha_node_1.

--root-cert=/путь/к/сертификату_цс #

Указывает путь к сертификату доверенного ЦС в формате PEM.

-l параметры_подключения --use-leader=параметры_подключения #

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

host=хост_узла port=порт_узла biha-port=biha_порт_узла

--user-biha-cert=/путь/к/сертификату_клиента #

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента #

Указывает путь к закрытому ключу для сертификата --user-biha-cert в формате PEM.

-v | --version #

Синтаксис:

bihactl -v
bihactl --version

Отображает текущую версию утилиты bihactl.

--help #

Синтаксис:

bihactl --help

Выводит справку по параметрам командной строки.

См. также

initdb, pg_basebackup