Обзор конфигурации

Серверы Stronghold настраиваются с использованием конфигурационного файла в формате HCL или JSON.

Чтобы усилить контроль за доступом к файлам, можно включить проверку прав доступа к файлам с помощью переменной окружения VAULT_ENABLE_FILE_PERMISSIONS_CHECK. Если проверка активирована, Stronghold проверяет, принадлежат ли директория конфигурации и файлы пользователю, который запускает Stronghold. Дополнительно проверяется, что у группы или других пользователей нет прав на запись или выполнение этих файлов.

При необходимости оператор может указать пользователя и права доступа к директории плагинов и исполняемым файлам. Для этого используются параметры plugin_file_uid и plugin_file_permissions в конфигурации. По умолчанию проверка прав в Stronghold отключена.

Вот пример конфигурации:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_id"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

Для применения новых параметров после изменения файла конфигурации нужно перезапустить сервис Stronghold: systemctl restart stronghold.

Обзор параметров

  • storage — обязательный блок параметров. Настройка бэкенда хранилища, где будут сохраняться данные Stronghold. Для работы Stronghold в режиме высокой доступности (HA) нужно использовать бэкенд, который поддерживает семантику координации. Если выбранный бэкенд хранения это позволяет, параметры HA можно указать прямо внутри блока storage. В ином случае следует настроить отдельный параметр ha_storage с бэкендом, который поддерживает HA, вместе с соответствующими параметрами HA. Подробности о параметрах бэкенда хранилища — в разделе Секция storage.

  • ha_storage — необязательный блок параметров. Настройка бэкенда хранилища, где будет происходить координация Stronghold в режиме высокой доступности (HA). Указанный бэкенд должен поддерживать HA. Если параметр не установлен, будет выполнена попытка запустить HA на бэкенде, который указан в параметре storage. Если бэкенд хранилища уже поддерживает координацию HA и если специфические параметры HA уже указаны в блоке storage, дополнительная настройка ha_storage не требуется.

  • listener — обязательный блок параметров. Настройка параметров прослушивания запросов API Stronghold. Подробности — в разделе Секция listener.

  • user_lockout — необязательный блок параметров. Настройка поведения блокировки пользователя при неудачном входе в систему. Подробности — в разделе Секция user_lockout.

  • cluster_name — необязательный строковый параметр. Указывает идентификатор для кластера Stronghold. Если значение не указано, Stronghold его сгенерирует.

  • cache_size — необязательный строковый параметр. Определяет размер кэша чтения, который использует физическая подсистема хранения. Значение указывается в количестве хранимых записей, поэтому общий размер кэша зависит от их размера. По умолчанию 131072.

  • disable_cache — необязательный логический параметр. Отключает все кэши в Stronghold, в том числе кэш чтения, который использует физическая подсистема хранения. Сильно влияет на производительность. По умолчанию false.

  • disable_mlock — необязательный логический параметр. Отключает возможность сервера выполнять системный вызов mlock, который предотвращает выгрузку памяти на диск.

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

    Не рекомендуется отключать mlock, если системы, на которых работает Stronghold, не используют swap или используют только зашифрованный swap. Поддержка блокировки памяти реализована только в UNIX-подобных системах, таких как Linux или FreeBSD, которые поддерживают системный вызов mlock() . В таких системах как, например, Windows, NaCL, Android нет механизмов для предотвращения записи всего адресного пространства памяти процесса на диск, поэтому данная функция автоматически отключается для неподдерживаемых платформ.

    Напротив, настоятельно рекомендуется отключить mlock при использовании интегрированного хранилища. Этот системный вызов плохо совместим с отображаемыми в памяти файлами, такими как те, что создаются BoltDB, который Raft использует для отслеживания состояния.

    Использование mlock с интегрированным хранилищем может вызвать нехватку памяти, если объём данных Stronghold превысит доступный объём ОЗУ. Дело в том, что отображаемые в память файлы загружаются в резидентную память, а это приводит к загрузке всех данных Stronghold в оперативную память. В этом случае, несмотря на то, что данные в BoltDB остаются зашифрованными в состоянии покоя, swap нужно отключить. Это позволит предотвратить выгрузку на диск других конфиденциальных данных Stronghold, которые находятся в памяти.

    В Linux можно дать исполняемому файлу Stronghold возможность использовать системный вызов mlock без запуска процесса от имени root, выполнив следующую команду:

sudo setcap cap_ipc_lock=+ep $(readlink -f $(which stronghold))

Каждый плагин запускается как отдельный процесс, поэтому нужно применить аналогичные настройки для каждого плагина в директории plugins. Если вы используете дистрибутив Linux с актуальной версией systemd, то можете добавить следующую директиву в секцию [Service] конфигурационного файла:

LimitMEMLOCK=infinity

  • plugin_directory — необязательный строковый параметр. Определяет каталог, из которого разрешено загружать плагины. Для успешной загрузки плагинов Stronghold должен иметь разрешение на чтение файлов в этой директории, а значение не может быть символической ссылкой. По умолчанию параметр не задан и имеет значение "".

  • plugin_tmpdir — необязательный строковый параметр. Указывает каталог, где Stronghold может создавать временные файлы для поддержки взаимодействия Unix-сокета с контейнеризированными плагинами. Если значение не задано, Stronghold будет использовать каталог по умолчанию для временных файлов. В большинстве случаев настройка этого параметра не требуется, за исключением ситуаций, когда используются контейнеризированные плагины и Stronghold разделяет временную папку с другими процессами, например при использовании параметра PrivateTmp в systemd.

  • plugin_file_uid — необязательный целочисленный параметр. Идентификатор пользователя (UID) директорий плагинов и исполняемых файлов плагинов в случае, если они принадлежат пользователю, отличному от того, кто запускает Stronghold.

  • plugin_file_permissions — необязательный строковый параметр. Строка восьмеричных прав доступа для директорий плагинов и исполняемых файлов плагинов в случае, если установлены права на запись или выполнение для группы или других пользователей.

  • telemetry — необязательный блок параметров. Указывает систему телеметрии для сбора и отправки статистики.

  • default_lease_ttl — необязательный строковый параметр. Определяет срок действия аренды для токенов и секретов по умолчанию. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час), и не может быть больше, чем max_lease_ttl. По умолчанию 768h.

  • max_lease_ttl — необязательный строковый параметр. Определяет максимальный срок действия аренды для токенов и секретов. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час). Отдельные точки монтирования могут переопределить это значение, настроив точку монтирования с помощью флага max-lease-ttl в командах auth или secret. По умолчанию 768h.

  • default_max_request_duration — необязательный строковый параметр. Указывает максимальное стандартное время выполнения запроса, после которого Stronghold его отменит. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час) и может быть переопределено для каждого слушателя (listener) через параметр max_request_duration. По умолчанию 90s.

  • detect_deadlocks — необязательный строковый параметр. Строка значений, разделённых запятыми. Указывает внутренние взаимоисключающие блокировки, за которыми следует следить на предмет потенциальных взаимоблокировок. Сейчас поддерживаются значения statelock, quotas и expiration, что приведёт к записи "POTENTIAL DEADLOCK:"в лог , если попытка блокировки состояния ядра кажется заблокированной. Включение detect_deadlocks может негативно повлиять на производительность из-за отслеживания каждой попытки блокировки. По умолчанию параметр не задан и имеет значение "".

  • raw_storage_endpoint — необязательный логический параметр. Активирует эндпоинт sys/raw с высоким уровнем привилегий. Этот эндпоинт позволяет выполнять дешифрование и шифрование необработанных данных на входе и выходе из защитного барьера. По умолчанию false.

  • introspection_endpoint — необязательный логический параметр. Активирует эндпоинт sys/internal/inspect, который позволяет проводить инспекцию определённых подсистем внутри Stronghold пользователям с root-токеном или привилегиями sudo. По умолчанию false.

  • ui — необязательный логический параметр. Активирует встроенный веб-интерфейс пользователя, доступный на всех слушателях (адрес + порт) по пути /ui. При обращении браузеров к стандартному адресу API Stronghold они будут автоматически перенаправлены на интерфейс. По умолчанию false. Подробности — в разделе Секция ui.

  • pid_file — необязательный строковый параметр. Указывает путь к файлу, где должен храниться идентификатор процесса (PID) сервера Stronghold.

  • enable_response_header_hostname — необязательный логический параметр. Активирует добавление HTTP-заголовка X-Vault-Hostname во все HTTP-ответы Stronghold. Этот заголовок будет содержать имя узла Stronghold, который обработал HTTP-запрос. Наличие этой информации не гарантируется — она будет предоставлена по возможности. Если опция включена, но заголовок X-Vault-Hostname отсутствует в ответе, это может указывать на ошибку при извлечении имени хоста из операционной системы. По умолчанию false.

  • enable_response_header_raft_node_id — необязательный логический параметр. Активирует добавление HTTP-заголовка X-Vault-Raft-Node-ID во все HTTP-ответы Stronghold. Если Stronghold использует интегрированное хранилище (то есть участвует в кластере Raft), заголовок X-Vault-Raft-Node-ID будет содержать идентификатор узла Raft, который обработал HTTP-запрос. Если же узел Stronghold не участвует в кластере Raft, этот заголовок будет опущен независимо от того, включена ли опция. По умолчанию false.

  • log_level — необязательный строковый параметр. Определяет уровень подробности журнала. Поддерживаются следующие пять значений в порядке убывания детализации: trace, debug, info, warn и error. Это значение также можно задать с помощью переменной окружения VAULT_LOG_LEVEL. По умолчанию info.

    Если указано корректное значение параметра log_level, при SIGHUP (sudo kill -s HUP pid Stronghold), Stronghold обновит существующий уровень журнала. При этом будут отменены как флаг CLI, так и переменная окружения. Динамически изменять таким образом уровень журнала могут не все части журнала Stronghold. Например, сейчас не обновляются динамически плагины secrets/auth.

  • log_format — необязательный строковый параметр. Формат журнала. Поддерживаются два значения: standard и json. По умолчанию standard.

  • log_file — необязательный строковый параметр. Абсолютный путь, по которому Stronghold должен сохранять сообщения журнала в дополнение к другим существующим выводам, таким как journald/stdout. Пути, которые заканчиваются разделителем пути, используют имя файла по умолчанию — vault.log. Пути, которые не заканчиваются расширением файла, используют расширение по умолчанию — .log. Если файл журнала перезаписывается, в момент перезаписи Stronghold добавляет к имени файла текущую временную метку.

  • log_rotate_duration — необязательный строковый параметр. Указывает максимальную продолжительность записи в файл журнала перед до его перезаписи. Значение указывается с использованием суффикса времени, например, 40s. По умолчанию 24h.

  • log_rotate_bytes — необязательный целочисленный параметр. Указывает количество байт, которое можно записать в файл журнала до его перезаписи. Если значение не указано, то количество байт, которое можно записать в файл журнала, не ограничено.

  • log_rotate_max_files — необязательный целочисленный параметр. Указывает максимальное количество старых файлов журнала, которые нужно сохранять. По умолчанию установлено значение 0, то есть файлы никогда не удаляются. Чтобы удалять старые файлы журналы при создании нового установите значение -1.

  • imprecise_lease_role_tracking — необязательный логический параметр. Позволяет пропустить подсчёт аренды по ролям, если квоты на основе ролей не включены. Когда этот параметр установлен в значение true и включена новая квота на основе ролей, последующий подсчёт аренд начнётся 0. Параметр влияет на квоты подсчёта аренды на основе ролей, но уменьшает задержки, если квоты на основе роли не используются.

  • experiments — необязательный массив значений. Список экспериментальных функций, которые следует активировать для узла. Не используйте экспериментальные функции в production-среде! Связанные с ними API могут между релизами претерпевать несовместимые с предыдущими версиями изменения. Дополнительные экспериментальные функции также можно указать через переменную окружения VAULT_EXPERIMENTS в виде списка значений, разделённых запятыми.

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

Для бэкендов, которые поддерживают режим высокой доступности (HA), используются следующие параметры:

  • api_addr — необязательный строковый параметр. Указывает адрес, который будет анонсироваться другим серверам Stronghold в кластере для перенаправления клиентов. Также это значение используется для бэкендов плагинов. Параметр api_addr также можно задать через переменную окружения VAULT_API_ADDR. В общем случае это должен быть полный URL, который указывает на значение адреса слушателя (listener). Адрес может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

  • cluster_addr — необязательный строковый параметр. Указывает адрес для анонсирования другим серверам Stronghold в кластере для перенаправления запросов. Этот параметр также можно задать через переменную окружения VAULT_CLUSTER_ADDR. Подобно api_addr это полный URL, но Stronghold будет игнорировать схему (все участники кластера всегда используют TLS с приватным ключом/сертификатом). Адрес может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

  • disable_clustering — необязательный логический параметр. Указывает, включены ли функции кластеризации, например, переадресация запросов. Если установить значение true для одного узла хранилища, функции кластеризации будут отключены только в случае, если этот узел является активным. Параметр нельзя установить в true, если типом хранилища является raft. По умолчанию false.

Секция listener

Секция listener настраивает адреса и порты, на которых Stronghold будет отвечать на запросы. Сейчас существует два типа слушателей:

  1. TCP
  2. Unix Domain Socket

TCP

TCP-слушатель настраивает Stronghold на прослушивание TCP-адреса/порта.

listener "tcp" {
  address = "127.0.0.1:8200"
}

Можно указать секцию listener больше одного раза, чтобы Stronghold прослушивал несколько интерфейсов. При настройке нескольких слушателей обязательно указывайте параметры api_addr и cluster_addr, чтобы Stronghold анонсировал другим узлам корректный адрес.

Сокрытие конфиденциальных данных для неаутентифицированных эндпоинтов

Неаутентифицированные API-эндпоинты могут возвращать такую конфиденциальную информацию:

  1. Номер версии Stronghold.
  2. Дату сборки бинарного файла Stronghold.
  3. Имя кластера Stronghold.
  4. IP-адрес узлов в кластере.

При этом Stronghold позволяет настроить каждую секцию tcp listener так, чтобы при необходимости удалить эти данные из ответов API. Удаление чувствительной информации на основе конфигурации секции listener поддерживают три эндпоинта API:

  1. /sys/health
  2. /sys/leader
  3. /sys/seal-status

Удалённую информацию Stronghold заменяет пустой строкой — "". Также некоторые API Stronghold опускают ключи в ответе, если соответствующее значение пустое ("").

Удаление значений влияет на ответы для всех клиентов API. Клиентская командная строка Stronghold и пользовательский интерфейс используют ответы API Stronghold. В результате настройки удаления будут применяться к выводу в CLI и пользовательском интерфейсе, а также к прямым вызовам API.

Пользовательские заголовки ответов

Stronghold позволяет задавать пользовательские HTTP-заголовки ответов для корневого пути (/) и для эндпоинтов API (/v1/). Эти заголовки определяются на основе возвращаемого кода состояния. Например, пользователь может определить один список пользовательских заголовков ответов для кода состояния 200 и другой список для кода состояния 307.

Эндпоинт API /sys/config/ui позволяет пользователям устанавливать специфические для UI пользовательские заголовки. Однако если заголовок настроен в конфигурационном файле, перенастроить его через данный эндпоинт нельзя. Чтобы удалить пользовательский заголовок или изменить его значение, нужно изменить файл конфигурации Stronghold и отправить сигнал SIGHUP в процесс Stronghold.

Если в конфигурационном файле задан пользовательский заголовок и такой же заголовок используют внутренние процессы Stronghold, настроенный заголовок не будет принят. Например, не будет принят пользовательский заголовок с префиксом X-Vault-. При запуске в журналах Stronghold будет зарегистрировано соответствующее сообщение.

Порядок приоритетов

Если один и тот же заголовок указан как в конфигурационном файле, так и через эндпоинт API /sys/config/ui, приоритет отдаётся заголовку из конфигурационного файла. Например, заголовок Content-Security-Policy по умолчанию определён в эндпоинте API /sys/config/ui. Однако если этот же заголовок прописан в конфигурационном файле, Stronghold использует именно его, подставляя в ответ вместо значения по умолчанию в /sys/config/ui.

Параметры слушателя TCP

  • address — строковый параметр в формате ip-адрес:порт. Указывает назначенные для прослушивания адрес и порт. Параметр может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

  • cluster_address — строковый параметр в формате ip-адрес:порт. Указывает адрес и порт, назначенные для прослушивания запросов типа сервер-сервер в кластере. По умолчанию значение параметра на один порт выше значения address. В большинстве случаев задавать cluster_address не нужно, однако параметр может быть полезен, если изолированным серверам Stronghold нужно перескакивать через TCP-балансировщик нагрузки или использовать какую-то другую схему для связи. Параметр может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

  • http_idle_timeout — строковый параметр. Указывает максимальное время ожидания следующего запроса при включении режима keep-alives. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час). Если значение параметра равно нулю, будет использоваться значение http_read_timeout. Если же оба этих значения равны нулю, будет использоваться значение http_read_header_timeout.

  • http_read_header_timeout — строковый параметр. Указывает время, отведённое на чтение заголовков запроса. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • http_read_timeout — строковый параметр. Указывает максимальную продолжительность чтения всего запроса, включая заголовки и тело. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • http_write_timeout — строковый параметр. Указывает максимальную продолжительность записи ответа. Сбрасывается каждый раз, когда считывается заголовок нового запроса. Значение по умолчанию 0 означает отсутствие ограничения по времени. Задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • max_request_size — целочисленный параметр. Указывает максимально допустимый размер запроса в байтах. По умолчанию равен 32 МБ, если не задан или установлен в 0. Значение меньше 0 отключает ограничение.

  • max_request_duration — строковый параметр. Указывает максимальное время обработки запроса, после которого Stronghold его отменит. Этот параметр отменяет значение default_max_request_duration для данного слушателя. Задаётся с помощью суффикса времени, например "90s" (90 секунд).

  • proxy_protocol_behavior — строковый параметр. Включает поведение протокола PROXY версии 1 для слушателя. Принимаются следующие значения:
    • use_always — всегда будет использоваться IP-адрес клиента.
    • allow_authorized — будет использоваться IP-адрес клиента, если исходный IP-адрес находится в списке.
    • proxy_protocol_authorized_addrs — будет использоваться исходный IP-адрес, если исходного IP в списке нет.
    • deny_unauthorized — если исходный IP-адрес не в списке proxy_protocol_authorized_addrs, трафик будет отклонён.

  • proxy_protocol_authorized_addrs — строковый параметр или массив строк. Определяет список разрешённых IP-адресов источников для использования с протоколом PROXY. Не требуется, если для параметра proxy_protocol_behavior установлено значение use_always. При указании в формате строки значения нужно разделить запятыми. Значение proxy_protocol_authorized_addrs не может быть пустым: нужно указать как минимум один IP-адрес источника.

  • redact_addresses — логический параметр. Скрывает значения leader_address и cluster_leader_address в соответствующих ответах API, если установлен в значение true.

  • redact_cluster_name — логический параметр. Скрывает значения cluster_name в соответствующих ответах API, если установлен в значение true.

  • redact_version — логический параметр. Скрывает значения version и build_date в соответствующих ответах API, если установлен в значение true.

  • tls_disable — логический параметр. Указывает, будет ли отключен TLS. Stronghold использует TLS по умолчанию, и поэтому необходимо явно отключить TLS, чтобы отказаться от небезопасной связи. Отключение может привести к отключению некоторых функций пользовательского интерфейса.

  • tls_cert_file — строковый параметр. Указывает путь к файлу сертификата для TLS. Файл должен быть в кодировке PEM. Для настройки слушателя на использование сертификата ЦС нужно объединить основной сертификат и сертификат ЦС. При этом в начале объединённого файла должен находиться основной сертификат. Указанный в параметре tls_cert_file путь используется при запуске Stronghold. Изменение значения во время работы Stronghold ни на что не повлияет.

  • tls_key_file — строковый параметр. Указывает путь к закрытому ключу для сертификата. Файл должен быть в кодировке PEM. Если файл ключа зашифрован, при запуске сервера потребуется ввести парольную фразу. При перезагрузке конфигурации с помощью SIGHUP парольная фраза между файлами ключей должна оставаться неизменной. Указанный в параметре tls_key_file путь используется при запуске Stronghold. Изменение значения во время работы Stronghold ни на что не повлияет.

  • tls_min_version — строковый параметр. Указывает минимальную версию TLS, поддерживаемую слушателем. Допустимые значения: "tls10", "tls11", "tls12" или "tls13". TLS 1.1 и ниже, то есть значения tls10 и tls11, указанные в параметре tls_min_version, считаются небезопасными и не рекомендуются.

  • tls_max_version — строковый параметр. Указывает максимальную версию TLS, поддерживаемую слушателем. Допустимые значения: "tls10", "tls11", "tls12" или "tls13". TLS 1.1 и ниже, то есть значения tls10 и tls11, указанные в параметре tls_max_version, считаются небезопасными и не рекомендуются.

  • tls_cipher_suites — строковый параметр. Указывает список поддерживаемых наборов шифров в виде списка значений, перечисленных через запятую. Список всех доступных наборов шифров можно найти в документации по TLS для Go.

    Go использует список, заданный в параметре tls_cipher_suites, только для TLSv1.2 и более ранних версий. Порядок шифров при этом не важен. Для эффективности tls_cipher_suites, параметр tls_max_version нужно установить в "tls12", чтобы предотвратить согласование TLSv1.3. Подробнее об этом и других связанных с TLS изменениях можно узнать из официального поста о TLS от Go.

  • tls_require_and_verify_client_cert — логический параметр. Включает аутентификацию клиента для данного слушателя. При этом слушателю понадобится представленный клиентский сертификат, успешно проверенный на системных ЦС.

  • tls_client_ca_file — строковый параметр. Файл сертификата ЦС в кодировке PEM, который используется для проверки подлинности клиента.

  • tls_disable_client_certs — логический параметр. Отключает аутентификацию клиента для данного слушателя. По умолчанию — при установленном значении false — Stronghold запрашивает сертификаты аутентификации клиента, когда они доступны.

    Внимание. Поля tls_disable_client_certs и tls_require_and_verify_client_cert в секции listener — взаимоисключающие. Обязательно убедитесь, что они оба не установлены в значение true. С настройками по умолчанию проверка клиента TLS не обязательна.

  • x_forwarded_for_authorized_addrs — строковый параметр. Может быть указан в формате строки со списком разделённых запятыми значений или в формате JSON-массива. Указывает список CIDR исходных IP-адресов, для которых заголовок X-Forwarded-For будет доверенным. Включает поддержку X-Forwarded-For.

    Например, Stronghold получает соединение от IP-адреса балансировщика нагрузки 1.2.3.4. Добавление 1.2.3.4 в параметр x_forwarded_for_authorized_addrs приведёт к тому, что в поле remote_address журнала аудита будет отображён IP-адрес клиента, инициировавшего подключение, например 3.4.5.6. Важно, чтобы балансировщик нагрузки отправлял IP-адрес подключающегося клиента в заголовке X-Forwarded-For.

  • x_forwarded_for_hop_skips — строковый параметр. Указывает количество адресов, которые нужно пропустить с конца набора переходов. Например, если в заголовке X-Forwarded-For указаны адреса 1.2.3.4, 2.3.4.5, 3.4.5.6, 4.5.6.7, и параметр x_forwarded_for_hop_skips установлен в значение "1", то в качестве IP-адреса исходящего клиента будет использован 3.4.5.6.

  • x_forwarded_for_reject_not_authorized — логический параметр. При установке значения false позволяет игнорировать заголовок X-Forwarded-For, если он поступает в соединении с неавторизованного адреса. Клиентское соединение в этом случае будет использоваться как есть, а не будет отклонено.

  • x_forwarded_for_reject_not_present — логический параметр. При установке значения false позволяет использовать адрес клиента как есть, если заголовок X-Forwarded-For отсутствует или пуст, вместо того чтобы отклонить соединение с клиентом.

  • disable_replication_status_endpoints — логический параметр. При установке значения true отключит эндпоинты статуса репликации для данного слушателя.

Параметры telemetry:

  • unauthenticated_metrics_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/metrics.

Параметры profiling:

  • unauthenticated_pprof_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/pprof.

Параметры inflight_requests_logging:

  • unauthenticated_in_flight_requests_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/in-flight-req.

Параметры custom_response_headers default:

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

позволяет сопоставить имена заголовков по умолчанию с массивом значений. Заголовки по умолчанию устанавливаются на всех эндпоинтах независимо от значения кода состояния.

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

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

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

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

Примеры конфигурации секции listener tcp

Пример 1. Указание необходимых параметров для TLS.

Здесь демонстрируется указание сертификата и ключа для TLS.

listener "tcp" {
  tls_cert_file = "/etc/certs/tls.crt"
  tls_key_file  = "/etc/certs/tls.key"
}

Пример 2. Прослушивание на нескольких интерфейсах.

Здесь показано прослушивание Stronghold на частном интерфейсе, а также localhost.

listener "tcp" {
  address = "127.0.0.1:8200"
}

listener "tcp" {
  address = "10.0.0.5:8200"
}

# Advertise the non-loopback interface
api_addr = "https://10.0.0.5:8200"
cluster_addr = "https://10.0.0.5:8201"

Пример 3. Разрешение неаутентифицированного доступа к метрикам.

listener "tcp" {
  telemetry {
    unauthenticated_metrics_access = true
  }
}

Пример 4. Разрешение неаутентифицированного доступа к профилированию.

listener "tcp" {
  profiling {
    unauthenticated_pprof_access = true
    unauthenticated_in_flight_request_access = true
  }
}

Пример 5. Настройка пользовательских HTTP-заголовков ответов.

Операторы могут настроить подсекцию custom_response_headers в секции listener для добавления пользовательских HTTP-заголовков, соответствующих их приложениям.

listener "tcp" {
  custom_response_headers {
    "default" = {
      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
      "X-Custom-Header" = ["Custom Header Default Value"],
    },
    "2xx" = {
      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
    },
    "301" = {
      "Strict-Transport-Security" = ["max-age=31536000"],
      "Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
    },
  }
}

Примеры пользовательских HTTP-заголовков — Strict-Transport-Security и Content-Security-Policy. Их можно настроить для усиления безопасности приложения, которое взаимодействует с эндпоинтами Stronghold. Сканеры уязвимостей часто исследуют такие связанные с безопасностью HTTP-заголовки. Также можно настроить и специфические для приложения пользовательские заголовки, как настроен X-Custom-Header в примере выше.

Если заголовок определён в нескольких подразделах кодов состояния, будет возвращён заголовок, соответствующий наиболее конкретному коду ответа. Из примера конфигурации ниже, ответ 306 вернёт значение заголовка Custom для 3xx, а 307 вернёт значение заголовка Custom для 307.

listener "tcp" {
  custom_response_headers {
    "default" = {
       "X-Custom-Header" = ["default Custom header value"]
    },
    "3xx" = {
       "X-Custom-Header" = ["3xx Custom header value"]
    },
    "307" = {
       "X-Custom-Header" = ["307 Custom header value"]
    }
  }
}

Пример 6. Прослушивание на всех IPv4- и IPv6-интерфейсах.

В этом примере Stronghold прослушивает все интерфейсы IPv4 и IPv6, включая localhost.

listener "tcp" {
  address         = "[::]:8200"
  cluster_address = "[::]:8201"
}

Пример 7. Прослушивание на определённых IPv6-адресах.

В примере настроено использование только IPv6 с привязкой к интерфейсу с IP-адресом 2001:1c04:90d:1c00:a00:27ff:fefa:58ec.

listener "tcp" {
  address         = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
  cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
}

Объявление не loopback-интерфейса:

api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"

Примеры скрытия информации

Пример 1. Конфигурация с использованием параметров redact_addresses, redact_cluster_name и redact_version для скрытия информации в ответах.

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address             = "127.0.0.1:8200",
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
  redact_addresses    = "true"
  redact_cluster_name = "true"
  redact_version      = "true"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

Пример 2. Результаты применения параметров скрытия API: /sys/health.

Пример вызова /sys/health/, где скрыты cluster_name и version. Поле cluster_name полностью исключено из ответа, а version представлено пустой строкой ("").

$ curl -s https://127.0.0.1:8200/v1/sys/health | jq

{
  "initialized": true,
  "sealed": false,
  "standby": false,
  "performance_standby": false,
  "replication_performance_mode": "disabled",
  "replication_dr_mode": "disabled",
  "server_time_utc": 1715935559,
  "version": "",
  "cluster_id": "be574716-e7e9-a950-ee34-d62d56cd6d4a"
}

Пример 3. Результаты применения параметров скрытия API: sys/leader.

Пример вызова /sys/leader/, где скрыты leader_address и leader_cluster_address. Они установлены в пустую строку ("").

$ curl -s https://127.0.0.1:8200/v1/sys/leader | jq

{
  "ha_enabled": true,
  "is_self": true,
  "active_time": "2024-05-13T07:54:20.471072843Z",
  "leader_address": "",
  "leader_cluster_address": "",
  "performance_standby": false,
  "performance_standby_last_remote_wal": 0,
  "raft_committed_index": 78,
  "raft_applied_index": 78
}

Пример 4. Результаты применения параметров скрытия API: sys/seal-status.

Пример вызова /sys/seal-status/, где скрыты поля cluster_name, build_date и version. Поле cluster_name полностью исключено из ответа, а build_date и version представлены пустыми строками ("").

$ curl -s https://127.0.0.1:8200/v1/sys/seal-status | jq

{
  "type": "shamir",
  "initialized": true,
  "sealed": false,
  "t": 3,
  "n": 6,
  "progress": 0,
  "nonce": "",
  "version": "",
  "build_date": "",
  "migration": false,
  "cluster_id": "be574716-e7e9-a950-ee34-d62d56cd6d4a",
  "recovery_seal": false,
  "storage_type": "raft"
}

Пример 5. CLI: stronghold status

Команда CLI stronghold status использует эндпоинты, которые поддерживают скрытие данных, поэтому в выводе скрываются Version, Build Date, HA Cluster и Active Node Address.

Version, Build Date и HA Cluster показывают n/a, потому что соответствующий эндпоинт вернул пустую строку. В свою очередь Active Node Address показывается как <none>, потому что адрес был опущен в ответе API.

stronghold status

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            6
Threshold               3
Version                 n/a
Build Date              n/a
Storage Type            raft
HA Enabled              true
HA Cluster              n/a
HA Mode                 active
Active Since            2024-05-13T07:54:20.471072843Z
Active Node Address     <none>
Raft Committed Index    78
Raft Applied Index      78

Unix

Конфигурация слушателя Unix настраивает Stronghold на прослушивание на указанном Unix доменном сокете:

listener "unix" {
  address = "/run/vault.sock"
}

Можно указать секцию listener больше одного раза, чтобы Stronghold прослушивал несколько сокетов.

Параметры слушателя Unix

  • address — обязательный строковый параметр. Указывает адрес для привязки Unix-сокета.

  • socket_mode — необязательный строковый параметр. Изменяет права доступа и специальные флаги Unix-сокета.

  • socket_user — необязательный строковый параметр. Изменяет пользователя-владельца Unix-сокета.

  • socket_group — необязательный строковый параметр. Изменяет группу-владельца Unix-сокета.

Примеры конфигурации секции listener unix

Пример 1. Прослушивание на нескольких сокетах.

В примере Stronghold настроен на прослушивание на указанном сокете и сокете по умолчанию.

listener "unix" {}

listener "unix" {
  address = "/var/run/vault.sock"
}

Пример 2. Прослушивание на нескольких интерфейсах.

В этом примере Stronghold настроен на прослушивание на указанном Unix-сокете, а также на loopback-интерфейсе.

listener "unix" {
  address = "/var/run/vault.sock"
}

listener "tcp" {
  address = "127.0.0.1:8200"
}

Пример 3. Настройка прав.

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

listener "unix" {
  address = "/var/run/vault.sock"
  socket_mode = "644"
  socket_user = "1000"
  socket_group = "1000"
}

Секция storage

Секция storage настраивает бэкенд хранения, который используется для долговременного хранения данных Stronghold.

У каждого бэкенда — свои плюсы и минусы, преимущества и компромиссы. Так, одни бэкенды предоставляют более надёжный процесс резервного копирования и восстановления, а другие поддерживают высокую доступность.

Конфигурация

Бэкенд хранилища настраивается в конфигурационном файле Stronghold через секцию storage.

storage [NAME] {
  [PARAMETERS...]
}

Например:

storage "file" {
  path = "/mnt/vault/data"
}

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

Бэкенд хранения filesystem

Бэкенд хранения типа filesystem сохраняет данные Stronghold в файловой системе, используя стандартную структуру каталогов. Его можно использовать в ситуациях с одним долговечным сервером или для локальной разработки, где долговечность не является критической.

Бэкенд хранения типа filesystem не поддерживает высокую доступность.

Пример конфигурации секции storage с таким бэкендом хранения:

storage "file" {
  path = "/mnt/vault/data"
}

Хотя данные Stronghold и зашифрованы в состоянии покоя, нужно принять соответствующие меры для обеспечения безопасности доступа к файловой системе.

Параметры

  • path — обязательный строковый параметр. Абсолютный путь к каталогу, где будут храниться данные. Если каталога не существует, Stronghold его создаст.

Бэкенд хранения Raft

Бэкенд интегрированного хранилища (Raft) используется для хранения данных Stronghold. В отличие от других бэкендов хранения, он не работает с одним источником данных: вместо этого все узлы кластера Stronghold будут иметь реплицированную копию данных. Данные реплицируются между всеми узлами с помощью алгоритма консенсуса Raft.

Бэкенд хранения Raft поддерживает высокую доступность.

Пример конфигурации секции storage с бэкендом хранения типа Raft:

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}
cluster_addr = "http://127.0.0.1:8201"

При использовании бэкенда интегрированного хранилища нужно указать параметр cluster_addr, то есть адрес и порт, которые будут использоваться для связи между узлами в кластере Raft.

Также при использовании бэкенда интегрированного хранилища нельзя объявлять отдельный бэкенд ha_storage. Плюс настоятельно рекомендуется установить disable_mlock в значение true и отключить своппинг в системе.

Параметры

  • path — cтроковый параметр. Указывает путь к каталогу в файловой системе, где хранятся данные Stronghold. Значение может быть переопределено установкой переменной окружения VAULT_RAFT_PATH.

  • node_id — cтроковый параметр. Идентификатор узла в кластере Raft. Значение может быть переопределено установкой переменной окружения VAULT_RAFT_NODE_ID.

  • performance_multiplier — целочисленный параметр. Множитель, который используют серверы для масштабирования ключевых параметров времени Raft.

    Настройка параметра performance_multiplier влияет на время, необходимое Stronghold для обнаружения сбоев лидера и выбора лидера. Это достигается за счёт требования большего количества сетевых и вычислительных ресурсов для улучшения производительности. Если значение не задано или установлено в 0, будет использоваться стандартное время, описанное ниже. Более низкие значения используются для ужесточения времени и повышения чувствительности, а более высокие ослабляют время и снижают чувствительность.

    По умолчанию Stronghold использует временные параметры с более низкой производительностью, которые подходят для серверов Stronghold, соответствующих минимальным требованиям. Сейчас это эквивалентно установке значения в 5, но стандарт может измениться в будущих версиях Stronghold, если поменяется целевой минимальный профиль сервера. Установка значения performance_multiplier в 1 настроит Raft на режим с наивысшей производительностью и рекомендуется для серверов Stronghold в production-среде. Максимально допустимое значение — 10.

  • trailing_logs — целочисленный параметр. Контролирует количество записей журнала, которые остаются в хранилище журналов на диске после создания снимка. Этот параметр стоит регулировать только если последователи не могут догнать лидера из-за очень большого размера снимка и высокой пропускной способности записи, вызывающей усечение журнала до того, как снимок может быть полностью установлен.

    Если вам нужно использовать это для восстановления кластера, рассмотрите возможность снижения пропускной способности записи или объёма данных, которые хранятся в Stronghold. Значение по умолчанию — 10000, и оно подходит для всех нормальных рабочих нагрузок. Метрика trailing_logs не тождественна параметру max_trailing_logs.

  • snapshot_threshold — целочисленный параметр. Контролирует минимальное количество записей фиксации Raft между снимками, которые сохраняются на диск. Обычно этот низкоуровневый параметр не требует изменений. В сильно загруженных кластерах, которые испытывают чрезмерный дисковый ввод-вывод, можно увеличить значение, чтобы снизить нагрузку на диск и минимизировать вероятность одновременного создания снимков на всех серверах.

    Увеличение параметра snapshot_threshold — это компромисс между дисковым вводом-выводом и дисковым пространством, так как журнал Raft будет значительно расти, и пространство в файле в raft.db нельзя будет очистить до следующего снимка. Кроме того, при восстановлении после сбоев или переключении на резервный узел серверам понадобится больше времени, ведь потребуется воспроизвести больше журналов. Значение по умолчанию — 8192.

  • snapshot_interval — целочисленный параметр. Интервал между снимками в секундах, который контролирует, как часто Raft проверяет необходимость сделать снимок. Чтобы предотвратить ситуацию, когда весь кластер создаёт снимок одновременно, Raft случайным образом выбирает время между указанным интервалом и его удвоенным значением. По умолчанию 120 секунд.

  • retry_join — список параметров. Позволяет настроить набор параметров подключения для других узлов кластера. Этот набор используется для помощи узлам в поиске лидера для присоединения к кластеру. Можно задать несколько секций retry_join.

    Если параметры подключения для всех узлов в кластере известны заранее, можно включить эти секции. В таком случае как только один из узлов будет инициализирован как лидер, оставшиеся будут использовать свою конфигурацию retry_join для поиска лидера и присоединения к кластеру. Обратите внимание, что при использовании схемы разделения секрета Шамира присоединенные узлы нужно будет разблокировать вручную.

    Подробнее о параметрах секции retry_join — в разделе Параметры секции retry_join.

  • retry_join_as_non_voter — логический параметр. Если установить значение true, то любая конфигурация retry_join присоединяется к кластеру Raft как не участвующая в голосовании. Узел не будет участвовать в кворуме Raft, но будет получать поток репликации данных. Это позволяет добавить кластеру масштабируемость чтения.

    Опция имеет тот же эффект, что и флаг -non-voter для команды stronghold operator raft join, но влияет только на статус голосования при присоединении через конфигурацию retry_join. Параметр можно переопределить на true, установив переменную окружения VAULT_RAFT_RETRY_JOIN_AS_NON_VOTER в непустое значение. Действует только при наличии хотя бы одной секции retry_join.

  • max_entry_size — целочисленный параметр. Настройка максимального количество байт для записи Raft. Применяется как к операциям put, так и к транзакциям. Любая операция put или транзакция, превышающая это значение конфигурации, приведёт к сбою соответствующей операции. У Raft есть рекомендуемый максимальный размер данных в записи журнала. Он основан на текущей архитектуре, стандартном времени и т. д.

    Интегрированное хранилище также использует размер блока — порог, применяемый для разделения большого значения на блоки. По умолчанию размер блока равен максимальному размеру записи журнала Raft. Значение по умолчанию 1048576.

  • autopilot_reconcile_interval — строковый параметр. Задаёт временной интервал, после которого автопилот обнаружит любые изменения состояния.

    Изменение состояния может означать множество вещей, например:

    1. узел, изначально добавленный как не голосующий в кластер Raft, успешно завершил период стабилизации, что квалифицирует его для продвижения в голосующие;
    2. узел должен получить статус unhealthy в API состояния;
    3. узел был помечен как dead и должен быть исключён из конфигурации Raft.

    Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • autopilot_update_interval — строковый параметр. Временной интервал, после которого автопилот будет опрашивать Stronghold на предмет обновления интересующей информации. Включает такие данные, как конфигурация автопилота и его текущее состояние, конфигурация Raft, известные серверы, последний индекс Raft и статистика для всех известных серверов. Полученная информация будет использоваться для расчёта следующего состояния автопилота. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

Параметры секции retry_join

  • leader_api_addr — строковый параметр. IP-адрес возможного узла-лидера.

  • leader_tls_servername — строковый параметр. Имя сервера TLS, которое используется при подключении по HTTPS. Должно соответствовать одному из имён в DNS SANs (Subject Alternative Names) TLS-сертификата лидера. Узел использует leader_tls_servername для верификации сертификата лидера, когда пытается соединиться с лидером кластера. Это помогает обеспечить безопасность соединения и убедиться, что соединение происходит с правильным сервером.

  • leader_ca_cert_file — строковый параметр. Путь к файлу с сертификатом ЦС возможного узла-лидера.

  • leader_client_cert_file — строковый параметр. Путь к файлу сертификата клиента, который используется для аутентификации при соединении с лидером кластера по протоколу TLS. Узел Raft предъявляет этот сертификат при установлении защищённого соединения с лидером, чтобы подтвердить свою подлинность.

  • leader_client_key_file — строковый параметр. Путь к файлу приватного ключа, который используется вместе с клиентским сертификатом для аутентификации при соединении с лидером кластера по протоколу TLS.

  • leader_ca_cert — строковый параметр. Значение сертификата ЦС возможного узла-лидера.

  • leader_client_cert — строковый параметр. Значение сертификата клиента, который используется для аутентификации при соединении с лидером кластера по протоколу TLS. Узел Raft предъявляет этот сертификат при установлении защищённого соединения с лидером, чтобы подтвердить свою подлинность.

  • leader_client_key — строковый параметр. Значение приватного ключа, который используется вместе с клиентским сертификатом для аутентификации при соединении с лидером кластера по протоколу TLS.

Каждый блок retry_join может предоставлять TLS-сертификаты через пути к файлам или как значение сертификата, но не комбинацию обоих. Если передаётся значение сертификата, оно должно быть указано в одной строке с использованием \n для указания необходимых переносов на новую строку.

Секция ui

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

Активация ui

По умолчанию пользовательский интерфейс Stronghold не активирован. Для его активации установите параметр ui в конфигурации сервера Stronghold в значение true.

ui = true

listener "tcp" {
  # ...
}

Доступ к Stronghold UI

Пользовательский интерфейс работает на том же порту, что и слушатель Stronghold. Для доступа к UI необходимо настроить хотя бы одну секцию listener.

listener "tcp" {
  address = "10.0.1.35:8200"
  ...
}

Пользовательский интерфейс в приведённом примере доступен по URL-адресу https://10.0.1.35:8200/ui/ с любой машины в подсети — при условии отсутствия межсетевых экранов или соответствующей их настройке. Также UI доступен по любой записи DNS, которая разрешается на этот IP-адрес.

Секция user_lockout

Секция user_lockout определяет настройки блокировки пользователей при неудачных попытках входа в Stronghold. Настройки можно применить как глобально — для всех методов аутентификации (userpass, ldap и approle) с использованием общего имени секции user_lockout "all", так и индивидуально — для конкретного метода, указав его имя в секции. Поддерживаются следующие значения: all, userpass, ldap и approle.

Конфигурации, заданные для конкретного метода аутентификации, имеют более высокий приоритет по сравнению с настройками для всех методов аутентификации с использованием общего имени секции user_lockout "all". Если присутствуют обе конфигурации, будут применены параметры, которые относятся к конкретному методу.

Параметры секции user_lockout

  • lockout_threshold — строковый параметр. Указывает количество неудачных попыток входа в систему, после которых пользователь будет заблокирован.

  • lockout_duration — строковый параметр. Указывает длительность блокировки пользователя. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • lockout_counter_reset — строковый параметр. Определяет временной интервал, после которого счётчик блокировки сбрасывается, если нет неудачных попыток входа в систему. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

  • disable_lockout — логический параметр. Отключает функцию блокировки пользователя, если установить значение true.