Что делает этот модуль #
Почти любому сервису на вашем инстансе нужен секрет: пароль к базе данных, парольная фраза для инструмента контроля целостности, ключ API… Хранить их вручную — или, что ещё хуже, оставлять значения по умолчанию — один из самых распространённых способов довести машину до компрометации.
Модуль secrets берёт на себя этот жизненный цикл локально: генерирует каждый секрет криптографически стойким генератором (CSPRNG), сохраняет его с правами 0600 (читать может только root), возвращает его с чистым выводом, готовым для передачи по pipe, и ротирует его, когда это нужно. Всё организовано по доменам (например, mariadb или tripwire), и каждый домен может иметь несколько полей.
generate идемпотентен: если секрет домена уже существует, он его не трогает. Так один и тот же образ может создавать свои секреты при первом запуске каждого инстанса, не допуская, чтобы две машины разделяли один и тот же пароль. Значения никогда не записываются в лог и не показываются в list.
Типовые задачи #
Выберите, что хотите сделать. В каждом рецепте команда уже написана — просто замените домен на свой и нажмите Копировать.
1
Сгенерировать секрет для сервиса
Создаёт стойкий пароль для домена, только если его ещё нет.
Подключитесь по SSH к своему серверу под пользователем ubuntu.
Сгенерируйте секрет домена mariadb. Поскольку команда идемпотентна, вы можете запускать её сколько угодно раз без риска перезаписи:
$ sudo imaxe secrets generate mariadbНужна длинная парольная фраза для другого инструмента и в конкретном поле? Настройте --format, --len и --field:
$ sudo imaxe secrets generate tripwire --field local.passphrase --format passphrase --len 400600. Если он уже существовал, он не изменён — команда всё равно завершается успешно.2
Прочитать секрет для использования
Получите значение в чистом виде, готовое для передачи в другую команду.
get выводит только значение, без украшений и лишних переносов, чтобы вы могли передать его другому процессу по pipe:
$ sudo imaxe secrets get mariadbСекрет хранится в конкретном поле домена? Укажите его через --field:
$ sudo imaxe secrets get tripwire --field local.passphrasePASS="$(sudo imaxe secrets get mariadb)" и использовать его прямо в своём скрипте.3
Ротировать секрет
Заменяет значение на новое и помечает домен как ротированный.
Сгенерируйте новое значение для домена. В отличие от generate, команда rotate всё же заменяет существующий секрет:
$ sudo imaxe secrets rotate mariadblist). Не забудьте обновить сервис, использующий этот секрет, новым значением из get.4
Посмотреть, какие домены существуют
Запросите метаданные, не раскрывая ни одного значения.
Выводит список доменов с их метаданными (когда созданы и когда ротированы). Сам секрет никогда не показывается:
$ sudo imaxe secrets listНужно для скрипта или автоматической проверки? Запросите вывод в формате JSON:
$ sudo imaxe secrets list --jsonСекрет читается только root, пока он лежит на диске. Как только вы читаете его через get, он попадает в ваш терминал и вашу оболочку: не оставляйте его в истории (history), в лишних экспортированных переменных окружения или в логах. Предпочитайте точечные подстановки команд вроде "$(sudo imaxe secrets get mariadb)".
Синопсис #
imaxe secrets <subcomando> [<dominio>] [--field CLAVE] [flags]Все подкоманды требуют привилегий root (используйте sudo), потому что они читают и пишут файлы 0600 в /etc/imaxe/. Добавьте --json к list, чтобы получить машиночитаемый вывод, пригодный для скриптинга. Помните: get выдаёт значение в чистом виде, без оформления, готовым для pipe.
Подкоманды #
| Подкоманда | Что делает | Значимые флаги |
|---|---|---|
| generate | Создаёт секрет домена, если его нет (идемпотентно, CSPRNG). Без домена генерирует секреты из generate_on_first_boot. | --len, --format, --field |
| get | Возвращает значение секрета с чистым выводом, пригодным для pipe. | --field |
| rotate | Генерирует новый секрет и помечает домен как ротированный. | --field |
| list | Выводит список доменов и метаданные (создан, ротирован). Никогда не показывает значения. | --json |
Аргументы и флаги #
| Флаг | Тип | По умолчанию | Описание |
|---|---|---|---|
| <dominio> | string | — | Домен секрета (напр. mariadb, tripwire). Обязателен в get и rotate. В generate пусто = домены из generate_on_first_boot. |
| --field | string | value | Поле внутри домена. Позволяет хранить несколько секретов на домен (напр. local.passphrase). |
| --len | int | 32 | В generate: длина секрета в символах. |
| --format | enum | password | В generate: формат значения — password, passphrase или hex. |
| --json | bool | false | В list выдаёт метаданные как структурированный JSON в stdout. |
Файлы и пути #
| Путь | Содержимое |
|---|---|
| /etc/imaxe/secrets.yml | Конфигурация модуля: значения по умолчанию (length, format), домены и список generate_on_first_boot. Сохраняется с правами 0600. |
Пример secrets.yml:
defaults:
length: 32
format: password
domains: {}
generate_on_first_boot:
- mariadb
- tripwireС такой конфигурацией sudo imaxe secrets generate без домена при первом запуске создаёт секреты mariadb и tripwire с длиной и форматом по умолчанию.
Коды возврата и логи #
Каждый запуск возвращает код, который можно проверить через echo $? — удобно для сцепления в скриптах:
get без домена).Типичное использование в скрипте с учётом чистого вывода get:
$ sudo imaxe secrets generate mariadb \
&& sudo imaxe secrets get mariadb | some-tool --stdin-password \
|| echo "falló con código $?"Устранение неполадок #
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Выдаёт NOTFOUND (код 3) | Домен или --field ещё не сгенерированы. | Сначала создайте его через secrets generate <dominio> (и тот же --field). |
| Выдаёт USAGE (код 2) | get или rotate запущены без указания домена. | Передайте домен как аргумент; он обязателен в этих подкомандах. |
generate не меняет значение | Секрет уже существовал: generate идемпотентен по замыслу. | Если нужно новое значение, используйте secrets rotate <dominio>. |
Permission denied при чтении | Файл имеет права 0600, а вы запустили без привилегий. | Выполните команду с sudo; доступ к секрету есть только у root. |
Застряли с модулем Секреты?
Напишите нам, приложив вывод «imaxe <module> status --json», и мы быстро ответим.