Конфигурация
Хотя сервер NATS имеет множество флагов для простого тестирования возможностей, продукты NATS Server предоставляют гибкий формат конфигурации, сочетающий лучшие стороны традиционных форматов и современных подходов, таких как JSON и YAML.
Синтаксис
Файл конфигурации NATS поддерживает следующий синтаксис:
- Строки можно комментировать с помощью
#и// - Значения можно присваивать свойствам с помощью:
- Equals sign:
foo = 2 - Colon:
foo: 2 - Whitespace:
foo 2
- Equals sign:
- Массивы заключаются в квадратные скобки:
["a", "b", "c"] - Объекты заключаются в фигурные скобки:
{foo: 2} - Объекты можно присваивать без разделителя после ключа
- Точка с запятой может завершать выражение
Файл конфигурации NATS разбирается в кодировке UTF-8.
Конфигурацию NATS в файле также можно представить в виде объекта JSON (с комментариями!), однако при использовании переменных их по-прежнему нужно указывать без кавычек.
Строки и числа
Как видно, синтаксический анализатор конфигурации допускает множество вариантов:
- Значениями могут быть примитивы, списки или объекты
- Строки и числа обычно обрабатываются ожидаемым образом
- Числа поддерживают единицы, например 1K для 1000 и 1KB для 1024
Строковые значения, начинающиеся с цифры или точки '.', могут вызывать проблемы. Чтобы явно задать их как строки, заключите их в кавычки.
Неверная конфигурация:
listen: 127.0.0.1:4222
authorization: {
# НЕВЕРНО!
token: 3secret
}
Верная конфигурация:
listen: 127.0.0.1:4222
authorization: {
token: "3secret"
}
Переменные
В конфигурациях сервера можно задавать переменные. Они позволяют ссылаться на значение из одного или нескольких разделов конфигурации. Переменные:
- Имеют область видимости блока
- Используют префикс
$при обращении. Ссылки на переменные не заключаются в кавычки: например, присваиваниеfoo = "$example"задаст дляfooбуквальную строку"$example". - Могут получать значения из одноимённых переменных окружения
Если значение переменной окружения начинается с цифры, при его разрешении могут возникнуть проблемы в зависимости от версии сервера.
# Определите переменную в конфигурации
TOKEN: "secret"
# Используйте переменную
authorization {
token: $TOKEN
}
Аналогичная конфигурация, но теперь значение задано в окружении:
# TOKEN задана в окружении
authorization {
token: $TOKEN
}
Переменную окружения можно задать непосредственно в команде (ниже) или экспортировать заранее.
TOKEN="hello" nats-server -c /config/file
Директива включения
Директива include позволяет разделить конфигурацию сервера на несколько файлов. Это удобно для выделения частей конфигурации, которые можно повторно использовать на разных серверах.
Включаемые файлы должны задаваться относительными путями от основного файла конфигурации (указанного параметром -c):
server.conf:
listen: 127.0.0.1:4222
include ./auth.conf
После include не ставится = или :, поскольку это директива.
auth.conf:
authorization: {
token: "f0oBar"
}
При запуске сервера достаточно указать файл конфигурации верхнего уровня, содержащий включение.
nats-server -c server.conf
Свойства
Подключения
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
host | Хост для клиентских соединений. | string | 0.0.0.0 | Нет |
port | Порт клиентских соединений. Значение -1 выбирает случайный свободный порт. | integer | 4222 | Нет* |
listen | <host>:<port> для клиентских соединений. | string | - | Нет |
client_advertise | Объявляемый клиентский адрес <host>:<port>. Полезен для кластеров за NAT. | string | - | Да |
tls | Конфигурация TLS для клиентов и мониторинга HTTP. | object | - | Да* |
allow_non_tls | Разрешить TLS и незашифрованные соединения на одном порту. | boolean | - | Нет |
ocsp | OCSP Stapling по умолчанию применяется для сертификатов с флагом status_request Must-Staple. При явном отключении сервер не запрашивает прикрепляемые ответы даже при наличии Must-Staple. | (multiple) | true | Да |
ocsp_cache | Кэшировать прикрепляемые сервером ответы OCSP, чтобы не обращаться к ответчику при каждом рукопожатии. | (multiple) | - | Да |
mqtt | Конфигурация включения интерфейса MQTT. | object | - | Да* |
websocket | Конфигурация включения интерфейса WebSocket. | object | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
Централизованная аутентификация
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
authorization | Статическое объявление одного или нескольких пользователей. | object | - | Да |
accounts | Статические аккаунты, заданные конфигурацией. | object | - | Да |
no_auth_user | Имя пользователя, чьи разрешения наследуют неаутентифицированные клиенты. Пользователь должен быть определён в блоке authorization или accounts. | string | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
Децентрализованная аутентификация
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
operator | Один или несколько JWT оператора в файлах или непосредственно в конфигурации. | (multiple) | - | Нет |
trusted_keys | Один или несколько доверенных открытых ключей операторов. | string | - | Нет |
resolver | Имеет приоритет перед значением из operator, если задано. Строковое значение должно быть MEMORY или URL(<url>), где url — HTTP-адрес резолвера аккаунтов NATS. Примечание: резолвер аккаунтов NATS устарел; следует использовать встроенный резолвер на базе NATS. | (multiple) | - | Да* |
resolver_tls | object | - | Да | |
resolver_preload | Отображение открытых ключей аккаунтов на их JWT. | string | - | Да* |
resolver_pinned_accounts | (multiple) | - | Да | |
system_account | Имя или открытый ключ аккаунта, который будет считаться системным. | string | $SYS | Нет |
no_system_account | boolean | - | Нет |
* Ограничения перезагрузки описаны на странице параметра.
Кластеризация
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
cluster | Конфигурация объединения серверов в кластер. | object | - | Да* |
gateway | Конфигурация соединений шлюзов между кластерами. | object | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
Листовые узлы
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
leafnodes | Конфигурация соединений листовых узлов. | object | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
JetStream
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
jetstream | (multiple) | false | Да* | |
store_dir | Каталог файлового хранилища JetStream. | string | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
Отображение субъектов
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
mappings | (multiple) | - | Да |
Журналирование
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
debug | Если true, включает отладочные сообщения журнала. | boolean | false | Да* |
trace | Если true, включает трассировку протокола в журнале, кроме системного аккаунта. | boolean | false | Да* |
trace_headers | Трассировать заголовки сообщений. Также включает trace. | boolean | false | Да |
trace_verbose | Если true, включает трассировку протокола в журнале, включая системный аккаунт. | boolean | false | Да* |
logtime | Если false, записи журнала не содержат временных меток. | string | true | Да* |
logtime_utc | Если true, временные метки журнала используют UTC вместо местного часового пояса. | string | false | Да |
logfile | Имя файла журнала. | string | - | Да* |
logfile_max_num | Максимальное число сохраняемых файлов ротации журнала. Более старые файлы удаляются. | integer | - | Нет |
logfile_size_limit | Размер в байтах, после которого журнал переключается на новый файл. | integer | 0 | Нет |
syslog | Записывать журнал в syslog. | boolean | false | Да* |
remote_syslog | Адрес удалённого syslog. | string | - | Да* |
* Ограничения перезагрузки описаны на странице параметра.
Мониторинг и трассировка
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
server_name | Имя сервера, отображаемое в журнале. По умолчанию используется сгенерированный идентификатор сервера. При использовании JetStream имена всех серверов в пределах домена должны быть уникальными. | string | - | Нет |
server_tags | Один или несколько тегов сервера. Сейчас используются для размещения потоков и потребителей JetStream. | (multiple) | - | Да* |
http | Адрес прослушивания <host>:<port> для мониторинга сервера. | string | - | Нет |
https | Адрес прослушивания <host>:<port> для мониторинга сервера по TLS. | string | - | Нет |
http_port | Порт HTTP для мониторинга сервера. | integer | - | Нет |
https_port | Порт HTTPS для мониторинга сервера. | integer | - | Нет |
http_base_path | Базовый путь конечных точек мониторинга. | string | - | Нет* |
connect_error_reports | Число попыток, через которое сообщается о повторяющейся ошибке подключения маршрута, шлюза или листового узла. Попытки подключения выполняются раз в секунду. | integer | 3600 | Да* |
reconnect_error_reports | Число неудачных попыток переподключения маршрута, шлюза или листового узла между сообщениями об ошибке. По умолчанию сообщается о каждой попытке. | integer | 1 | Да |
max_traced_msg_len | Ограничить объём полезной нагрузки сообщения, записываемый в трассировку. | integer | 0 | Да |
* Ограничения перезагрузки описаны на странице параметра.
Настройки времени выполнения
| Имя | Описание | Тип | По умолчанию | Перезагрузка |
|---|---|---|---|---|
max_control_line | Максимальная длина строки протокола (включая суммарную длину субъекта и группы очереди). Использование увеличенного значения может потребовать изменений в клиентах. Применяется ко всему трафику. | string | 4KB | Да* |
max_connections | Максимальное число активных клиентских соединений. | string | 64K | Да |
max_payload | Максимальное число байтов полезной нагрузки сообщения. Уменьшение размера может потребовать реализации разбиения сообщений в клиентах. Применяется к полезной нагрузке клиентов и листовых узлов. Значения больше 8 МБ не рекомендуются, однако max_payload можно увеличить до 64 МБ. Максимальная полезная нагрузка не должна превышать max_pending. | string | 1MB | Да |
max_pending | Максимальное число байтов, буферизуемых для соединения. Применяется к клиентским соединениям. Приложения также могут задавать PendingLimits (число сообщений и общий размер) для своих подписок. | string | 64MB | Нет |
max_subscriptions | Максимальное число подписок на соединение аккаунта клиента или листового узла. Значение 0 снимает ограничение. | string | 0 | Нет* |
max_subscription_tokens | integer | - | Нет | |
ping_interval | Интервал отправки ping клиентам, листовым узлам и маршрутам. При наличии клиентского трафика, например сообщений или ping от клиента, сервер не отправляет ping. Поэтому рекомендуется задавать значение больше используемого клиентами. | string | 2m | Да |
ping_max | Число оставшихся без ответа ping, после которого сервер закрывает соединение. | integer | 2 | Да |
max_closed_clients | Число закрытых соединений, сохраняемых сервером для отчётов /connz. | integer | 10000 | Нет |
no_fast_producer_stall | Не задерживать быстрого издателя, когда потребитель не успевает. Вместо этого сервер отбрасывает сообщения для медленного потребителя. | boolean | false | Да |
default_sentinel | Имя пользователя для соединений, аутентифицирующихся с помощью sentinel JWT, который сам по себе не содержит разрешений. | string | - | Да |
write_deadline | Максимальное время блокировки сервера при записи в секундах. При превышении соединение закрывается. О способах обработки на стороне клиента см. раздел о медленных потребителях. | duration | 10s | Да* |
no_header_support | Отключает поддержку заголовков сообщений. | boolean | - | Нет |
disable_sublist_cache | Если true, отключает кэши подписок для всех аккаунтов. Это экономит ресурсы, когда постоянно используются разные субъекты. | boolean | false | Нет |
lame_duck_duration | Должно быть не менее 30 с. | duration | 2m | Нет |
lame_duck_grace_period | Время ожидания сервера после перехода в режим lame duck до начала закрытия клиентских соединений. | duration | 10s | Нет |
pidfile | string | - | Да | |
ports_file_dir | string | - | Да | |
prof_block_rate | Частота выборки профиля блокировок Go. Задавайте только при профилировании: параметр замедляет сервер. | integer | - | Да |
prof_port | integer | - | Нет | |
default_js_domain | Отображение аккаунтов на доменные имена. | string | - | Нет |
* Ограничения перезагрузки описаны на странице параметра.