Диагностика проблем с сервером

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

1. Задача

Чтобы эффективно устранить неполадки и решить проблемы с StarVault, необходимо изучить и объединить информацию из трех разных источников, чтобы найти первопричины:

Условия среды операционной системы, например, ограничения на количество пользователей.
Файл конфигурации сервера StarVault.
Вывод лога сервера StarVault, как описано в разделе "Логи сервера StarVault" учебника "Устранение неполадок StarVault".

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

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

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

Инструмент, помогающий операторам StarVault собирать и интерпретировать эту информацию, снижает нагрузку на поиск неисправностей, сокращает время обнаружения первопричины и значительно уменьшает время простоя во время отключения.

2. Решение

В StarVault есть подкоманда diagnose для команды operator CLI, которая помогает операторам выявлять основные причины наиболее часто встречающихся проблем с конфигурацией и запуском сервера.

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

Более подробную информацию о диагностике можно получить из Документации по диагностике оператора или вызвав starvault operator diagnose -help в терминале.

Приведем пример фактического вывода, чтобы ознакомить вас с типами проверок, выполняемых и сообщаемых диагностикой.

В результате диагностики был получен отказ в отношении хранилища, а также несколько предупреждений об использовании диска, лицензировании и TLS.

Команда предназначена для объяснения результатов на понятном языке, поэтому результаты часто не требуют пояснений. Она также содержит рекомендации, помогающие устранять предупреждения и сбои, такие как, например, рекомендация иметь как минимум 1 ГБ свободного места на каждом разделе.

2.1. Что проверяет диагностика?

На высоком уровне диагностика проверяет и сообщает об следующих распространенных причинах проблем с запуском сервера:

Среда
- Ограничения пользователя: максимальное количество открытых файлов
- Емкости для хранения
Сборка
- Доступ к настроенному хранилищу
- Доступ к хранилищу HA
- Создание ограничений
- Установочное ядро
- Адрес перенаправления
- Адрес кластера
- Прослушиватели
  - Настройка TLS
- Блокировка

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

3. Предпосылки

Для выполнения действий, описанных в сценарии, вам понадобятся:

StarVault.
- Руководство по установке StarVault (поможет вам справиться с установкой).
jq для обработки вывода JSON из StarVault CLI.

4. Представление сценария

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

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

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

5. Подготовка среды

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

$ mkdir -pm 0000 /tmp/learn-starvault-diagnose/data && \
  export LEARN_STARVAULT=/tmp/learn-starvault-diagnose

6. Запись примера конфигурации

Начните сценарий с примера файла конфигурации, starvault-server.hcl.

Запишите его в домашний каталог сценария.

$ cat > "${LEARN_STARVAULT}"/starvault-server.hcl << EOF
api_addr                = "http://127.0.0.1:8200"
cluster_addr            = "http://127.0.0.1:8201"
cluster_name            = "learn-diagnose-cluster"
default_lease_ttl       = "10h"
disable_mlock           = true
max_lease_ttl           = "10h"
pid_file                = "$LEARN_STARVAULT/pidfile"
ui                      = true

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_disable   = "true"
  tls_cert_file = "starvault.crt"
  tls_key_file  = "starvault.key"
}

backend "file" {
  path    = "$LEARN_STARVAULT/data"
  node_id = "learn-diagnose-server"
}
EOF

7. Выполнение диагностики

Выполните команду диагностики, чтобы проверить начальную конфигурацию примера.

$ starvault operator diagnose -config $LEARN_STARVAULT/starvault-server.hcl

Вывод должен быть похож на этот пример.

StarVault v1.2.0 ('1a46c26ee4e8fd00b4111300a865499c0e522e67+CHANGES'), built 2025-03-14T20:50:17Z

Results:
[ failure ] Vault Diagnose: HCP link check will not run on OSS Vault.
  [ success ] Check Operating System
    [ success ] Check Open File Limits: Open file limits are set to 262144.
    [ success ] Check Disk Usage: / usage ok.
  [ success ] Parse Configuration
  [ warning ] Check Telemetry: Telemetry is using default configuration
    By default only Prometheus and JSON metrics are available.  Ignore this warning if you are using telemetry or are
    using these metrics and are satisfied with the default retention time and gauge period.
  [ failure ] Check Storage
    [ success ] Create Storage Backend
    [ failure ] Check Storage Access: mkdir /tmp/learn-starvault-diagnose/data/diagnose: permission denied
  [ skipped ] Check Service Discovery: No service registration configured.
  [ success ] Create Vault Server Configuration Seals
  [ skipped ] Check Transit Seal TLS: No transit seal found in seal configuration.
  [ success ] Create Core Configuration
    [ success ] Initialize Randomness for Core
  [ success ] HA Storage
    [ success ] Create HA Storage Backend
  [ success ] Determine Redirect Address
  [ success ] Check Cluster Address: Cluster address is logically valid and can be found.
  [ success ] Check Core Creation
  [ skipped ] Check For Autoloaded License: License check will not run on OSS Vault.
  [ warning ] Start Listeners
    [ warning ] Check Listener TLS: Listener at address 127.0.0.1:8200: TLS is disabled in a listener config
      stanza.
    [ success ] Create Listeners
  [ skipped ] Check Autounseal Encryption: Skipping barrier encryption test. Only supported for auto-unseal.
  [ success ] Check Server Before Runtime
  [ success ] Finalize Shamir Seal

Диагностика привела к общему сбою в строке 4, а в строках 12 и 14 есть сообщение о сбое хранилища, а также предупреждения о конфигурации TLS слушателя в строках 27-28 и о конфигурации телеметрии в строке 9.

Сбой в строке 14 Check Storage Access: mkdir /tmp/learn-starvault-diagnose/data/diagnose: permission denied указывает на проблему с каталогом данных StarVault. Попробуйте подтвердить режимы в этом каталоге.

$ ls -l /tmp/learn-starvault-diagnose/
total 4
d---------. 2 nova wheel   6 May 23 03:24 data
-rw-r--r--. 1 nova wheel 596 May 23 03:22 starvault-server.hcl

Слишком строгие разрешения на каталог данных.

Чтобы понять сообщения журнала StarVault об этой проблеме на данном этапе, попробуйте запустить сервер StarVault с такой конфигурацией.

$ starvault server -config $LEARN_STARVAULT/starvault-server.hcl

WARNING! Unable to read storage migration status.
2025-05-23T03:39:50.688-0400 [INFO]  proxy environment: http_proxy="" https_proxy="" no_proxy=""
2025-05-23T03:39:50.688-0400 [WARN]  storage migration check error: error="open /tmp/learn-starvault-diagnose/data/core/_migration: permission denied"

При попытке получить доступ к ключу миграции основного хранилища сервер StarVault выдает аналогичную ошибку о запрете доступа к пути данных.

Нажмите Ctrl+C для остановки сервера.

Измените режим на 0700, чтобы StarVault мог писать в файловое хранилище, сконфигурированное для этого пути.

$ chmod 0700 /tmp/learn-starvault-diagnose/data

Выполните команду диагностики еще раз, чтобы повторно проверить конфигурацию.

$ starvault operator diagnose -config $LEARN_STARVAULT/starvault-server.hcl

Вывод должен быть похож на этот пример.

StarVault v1.2.0 ('1a46c26ee4e8fd00b4111300a865499c0e522e67+CHANGES'), built 2025-03-14T20:50:17Z

Results:
[ warning ] Vault Diagnose: HCP link check will not run on OSS Vault.
  [ success ] Check Operating System
    [ success ] Check Open File Limits: Open file limits are set to 262144.
    [ success ] Check Disk Usage: / usage ok.
  [ success ] Parse Configuration
  [ warning ] Check Telemetry: Telemetry is using default configuration
    By default only Prometheus and JSON metrics are available.  Ignore this warning if you are using telemetry or are
    using these metrics and are satisfied with the default retention time and gauge period.
  [ success ] Check Storage
    [ success ] Create Storage Backend
    [ success ] Check Storage Access
  [ skipped ] Check Service Discovery: No service registration configured.
  [ success ] Create Vault Server Configuration Seals
  [ skipped ] Check Transit Seal TLS: No transit seal found in seal configuration.
  [ success ] Create Core Configuration
    [ success ] Initialize Randomness for Core
  [ success ] HA Storage
    [ success ] Create HA Storage Backend
  [ success ] Determine Redirect Address
  [ success ] Check Cluster Address: Cluster address is logically valid and can be found.
  [ success ] Check Core Creation
  [ skipped ] Check For Autoloaded License: License check will not run on OSS Vault.
  [ warning ] Start Listeners
    [ warning ] Check Listener TLS: Listener at address 127.0.0.1:8200: TLS is disabled in a listener config
      stanza.
    [ success ] Create Listeners
  [ skipped ] Check Autounseal Encryption: Skipping barrier encryption test. Only supported for auto-unseal.
  [ success ] Check Server Before Runtime
  [ success ] Finalize Shamir Seal

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

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

Одно из предупреждений сообщает, что в слушателе не включен TLS.

Это предупреждение очень важно, но оно не мешает вам работать с StarVault (например, в качестве разработчика или QA).

Лучшие примеры, описанные в Документации по усилению производственной защиты, рекомендуют использовать StarVault со включенным сквозным TLS для производственного использования.

Учитывая отсутствие сбоев, сервер StarVault должен запуститься даже при наличии предупреждений в результатах диагностики.

Запустите сервер снова.

$ starvault server -config $LEARN_STARVAULT/starvault-server.hcl
==> StarVault server configuration:

Administrative Namespace:
             Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
   Environment Variables: BASH_FUNC_which%%, DBUS_SESSION_BUS_ADDRESS, GODEBUG, GOTRACEBACK, HISTSIZE, HOME, HOSTNAME, LANG, LEARN_STARVAULT, LESSOPEN, LOGNAME, LS_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, STARVAULT_ADDR, STARVAULT_DETAILED, STARVAULT_EXPERIMENTS, STARVAULT_FORMAT, STARVAULT_LICENSE, STARVAULT_LICENSE_PATH, SUDO_COMMAND, SUDO_GID, SUDO_UID, SUDO_USER, TERM, USER, _, which_declare
              Go Version: go1.22.1
              Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
               Log Level:
                   Mlock: supported: true, enabled: false
           Recovery Mode: false
                 Storage: file
                 Version: StarVault v1.2.0, built 2025-03-14T20:50:17Z
             Version Sha: 1a46c26ee4e8fd00b4111300a865499c0e522e67+CHANGES

==> StarVault server started! Log data will stream in below:

2025-05-23T03:42:45.028-0400 [INFO]  proxy environment: http_proxy="" https_proxy="" no_proxy=""

Сервер StarVault запустился, подтвердив решение проблемы с разрешением пути хранения.

8. Очистка

В терминале, где запущен сервер StarVault, нажмите Ctrl+C, чтобы остановить сервер.
Удалите временный каталог, содержащий конфигурацию и данные сервера StarVault.

$ rm -rf "$LEARN_STARVAULT"

9. Резюме

Вы узнали о подкоманде диагностики и о том, как использовать ее в конфигурации StarVault для проверки общих проблем.