Версия: 4.6.X

Справочник CLI — резервное копирование и восстановление

komrad-cli backup create

Создаёт набор резервных копий.

komrad-cli backup create [флаги]

Флаг	Тип	Умолчание	Описание
`--to`	`[]string`	`/var/backups/komrad`	Хранилище. Допустимые формы: локальный путь (всё остальное, что не подходит под формы ниже, тоже становится локальным каталогом с этим буквальным именем — не «тихим» SFTP/S3), голый токен `sftp` или `s3` (имя цели из `--config`), либо `@N` (N-й элемент `targets` в `--config`, с нуля). Формы `sftp:host/path` и `s3:bucket/prefix` не поддерживаются и отвергаются явной ошибкой. Флаг повторяется.
`--passphrase`	`string`	—	Фраза-пароль шифрования (или `KOMRAD_BACKUP_PASSPHRASE`); игнорируется при `--cipher jacarta`, где escrow-секрет задаётся только через `cipher.escrow.passphrase`
`--cipher`	`string`	`age`	Бэкенд шифрования: `age` \| `aes-gcm` \| `openssl` \| `jacarta`
`--config`	`string`	—	Путь к `komrad-backup.yaml` с настройками хранилищ и шифрования
`--no-pg`	`bool`	`false`	Пропустить поверхность PostgreSQL
`--no-ch`	`bool`	`false`	Пропустить поверхность ClickHouse
`--no-natsjs`	`bool`	`false`	Пропустить поверхность NATS JetStream
`--no-events`	`bool`	`false`	Пропустить таблицу событий (только управляющая плоскость)
`--ch-mode`	`string`	`full`	Режим ClickHouse: `full` \| `incremental`. В версии 4.6 `incremental` не поддерживается — команда завершается с ошибкой. См. предупреждение.
`--ch-base-rotate`	`string`	`7d`	Возраст, после которого создаётся новая базовая копия при инкрементальном режиме. В версии 4.6 не имеет эффекта: значение принимается, но нигде не используется, так как сам инкрементальный режим не работает — в отличие от `--ch-mode incremental`, это не ошибка, а молчаливая инертность.
`--events-window`	`string`	—	Окно событий: `1h` \| `1d` \| `1w` \| `1m` \| `6m` \| `1y` \| `all`
`--events-since`	`string`	—	Начало периода событий `YYYY-MM-DD`
`--events-until`	`string`	—	Конец периода событий `YYYY-MM-DD`
`--exact`	`bool`	`false`	Точное окно партиций через логический экспорт
`--exclude`	`[]string`	—	Исключить поверхность или под-объект: `<поверхность>[:<под>]` (например, `natsjs`, `natsjs:EVENTS`). Флаг повторяется.
`--files`	`[]string`	—	Файловая поверхность: `имя=путь`. Флаг повторяется.
`--pg-bindir`	`string`	—	Директория с `pg_dump`/`pg_restore` (по умолчанию — встроенный echelonpg)
`--pg-config-dir`	`string`	`/etc/echelon/komrad/`	Директория конфигов сервисов KOMRAD (для обнаружения БД PostgreSQL)
`--fail-fast`	`bool`	`false`	Прервать выполнение при ошибке любого хранилища
`--print-set`	`bool`	`false`	Напечатать имя созданного набора первой строкой stdout — только при успехе. Используется скриптами, например обёрткой запланированного копирования, чтобы затем передать это же имя в `verify`

Команда завершается с ненулевым кодом, если хотя бы одно хранилище из --to вернуло ошибку, даже когда остальные хранилища записались успешно — так несопровождаемый вызов (cron, systemd-таймер) не примет частично неудавшийся набор за успех.

komrad-cli backup verify

Проверяет целостность набора резервных копий.

komrad-cli backup verify <set-dir> [флаги]

Флаг	Тип	Умолчание	Описание
`--passphrase`	`string`	—	Фраза-пароль шифрования (или `KOMRAD_BACKUP_PASSPHRASE`); не требуется для JaCarta-копий
`--config`	`string`	—	Путь к `komrad-backup.yaml`; обязателен для JaCarta-копий

Команда проверяет манифест и sha256-контрольные суммы всех блобов. Завершается с ненулевым кодом, если хотя бы один блоб повреждён. Для копий, зашифрованных JaCarta, проверяются только контрольные суммы; полная проверка HMAC выполняется при restore.

komrad-cli backup prune

Удаляет наборы резервных копий вне окна хранения. Подробное описание сценария — в «Ротация».

komrad-cli backup prune <target> [флаги]

Флаг	Тип	Умолчание	Описание
`--keep-days`	`int`	`0`	Хранить наборы, созданные за последние N дней
`--keep-last`	`int`	`0`	Хранить N последних наборов
`--dry-run`	`bool`	`false`	Вывести план без удаления
`--no-staging`	`bool`	`false`	Пропустить очистку осиротевших директорий стейджинга ClickHouse на диске `komrad_backup`
`--ch-config-dir`	`string`	—	Директория с `komrad-processor.yaml` для обнаружения ClickHouse (используется только очисткой стейджинга)

Нужен хотя бы один из --keep-days/--keep-last; без обоих команда завершается ошибкой. Оба параметра объединяются по ИЛИ: набор сохраняется, если его оставляет хотя бы один критерий. Самый новый набор не удаляется никогда. Базовый набор не удаляется, пока от него зависит другой сохраняемый набор. Набор, чей манифест не удалось прочитать или разобрать, всегда сохраняется и отмечается в отчёте отдельной строкой. Директории <набор>.partial (незавершённая выгрузка) никогда не перечисляются и не удаляются.

<target> — только локальный путь к каталогу с наборами; хранилища sftp:/s3: и ссылки @N на komrad-backup.yaml командой не поддерживаются и завершаются явной ошибкой, а не тихим бездействием.

komrad-cli restore

Восстанавливает узел KOMRAD из набора резервных копий.

komrad-cli restore <set-dir> [флаги]

Флаг	Тип	Умолчание	Описание
`--passphrase`	`string`	—	Фраза-пароль шифрования (или `KOMRAD_BACKUP_PASSPHRASE`)
`--only`	`[]string`	—	Восстановить только указанные поверхности: `postgres` \| `clickhouse` \| `natsjs` \| `files`. Флаг повторяется.
`--restore-root`	`string`	`/`	Корневая директория для файловых поверхностей
`--pg-bindir`	`string`	—	Директория с `pg_dump`/`pg_restore`
`--pg-config-dir`	`string`	`/etc/echelon/komrad/`	Директория конфигов сервисов (для подключения к PostgreSQL)
`--config`	`string`	—	Путь к `komrad-backup.yaml`
`--force`	`bool`	`false`	Игнорировать проверку версии и проверку запущенных сервисов
`--no-start`	`bool`	`false`	Восстановить данные без запуска сервисов
`--start`	`bool`	`false`	Запустить сервисы после восстановления (явно)

backup.env

Конфигурация запланированного копирования (/etc/echelon/komrad/backup.env, права 0600 root:root), которую читает обёртка /usr/libexec/komrad/komrad-backup.sh. Подробное описание сценария — в «Настройка».

Ключ	Умолчание	Описание
`KOMRAD_BACKUP_PASSPHRASE`	(пусто)	Фраза-пароль шифрования. Обязательна: пока пуста, обёртка отказывается запускать резервное копирование.
`KOMRAD_BACKUP_TARGET`	`/var/backups/komrad`	Хранилище, передаваемое как `--to` в `backup create`.
`KOMRAD_BACKUP_KEEP_DAYS`	`14`	Передаётся в `backup prune --keep-days`.
`KOMRAD_BACKUP_EXTRA_ARGS`	(пусто)	Дополнительные аргументы `backup create`; значение разбивается по пробелам (word-split), поэтому можно передать несколько флагов.
`KOMRAD_BACKUP_LOG`	`/var/log/echelon/komrad/backup.log`	Файл полного вывода `create`/`verify`/`prune`.
`KOMRAD_BACKUP_PATH`	`/opt/echelon/komrad/bin:/usr/bin:/bin`	`PATH` для запуска обёртки.
`PGPASSFILE`	`/root/.pgpass`	Файл паролей libpq для подключения к PostgreSQL.
`KOMRAD_BACKUP_NOTIFY_CMD`	(пусто)	Запускается при сбое с кодом возврата первым аргументом. В отличие от `KOMRAD_BACKUP_EXTRA_ARGS` значение не разбивается по пробелам: это путь к одному исполняемому файлу, а не командная строка с аргументами.

komrad-backup.yaml

Конфигурационный файл хранилищ и шифрования (--config). В строковых значениях поддерживается подстановка ${ИМЯ} из переменных окружения. Ключи *_file задают путь к файлу с секретом; явное значение имеет приоритет над файлом.

cipher:
  backend: age            # age | aes-gcm | openssl | jacarta
  passphrase: ""          # фраза-пароль (или ${ENV})
  openssl:
    cipher: ""            # обязателен для backend: openssl (например, kuznyechik-ctr)
    mac: hmac-sha256      # hmac-sha256 | gost-mac | magma-mac
    engine: auto          # auto | engine | provider | none
    iter: 600000          # итерации PBKDF2
  jacarta:                # см. «Шифрование токеном JaCarta»
    module: ""            # путь к библиотеке PKCS#11
    token_label: ""       # метка токена (CKA_LABEL)
    user_pin: ""          # PIN пользователя (или ${ENV})
    key_label: ""         # метка ключа на токене
    public_key_pem: ""    # путь к открытому ключу получателя
    agent_path: ""        # путь к сайдкару komrad-jacarta
    verify_before_write: false  # выгружать блоб во временный файл и сверять
                                # имитовставку (токен, затем escrow) до выдачи
                                # открытого текста; включает откат на escrow
                                # ценой двойной выгрузки
    scratch_dir: ""       # каталог временного файла verify_before_write
                          # (умолчание — TMPDIR); нужно место под самый
                          # крупный отдельный блоб, не под весь набор
  escrow:
    passphrase: ""        # аварийная escrow-фраза для восстановления без токена;
                          # единственный способ задать escrow при создании копии

targets:
  - type: local           # local | sftp | s3
    path: /var/backups/komrad

  - type: sftp
    host: backup-server
    port: 22
    user: komrad
    password: ""          # или password_file
    key_file: /etc/echelon/komrad/keys/backup_id_ed25519
    key_passphrase: ""    # или key_passphrase_file
    known_hosts: ""       # путь к known_hosts
    fingerprint: ""       # альтернатива known_hosts: SHA256-отпечаток ключа хоста
    remote_dir: /backups/komrad
    legacy_compat: false  # включить совместимость со старыми SSH-серверами
    insecure_skip_host_key: false  # отключить проверку ключа хоста (небезопасно)

  - type: s3
    endpoint: https://s3.example.com
    bucket: komrad-backups
    access_key: ""
    secret_key: ""        # или secret_key_file
    region: ""
    prefix: komrad
    use_ssl: true

fanout:
  tee_threshold: 1GiB     # блобы крупнее порога пишутся во все хранилища параллельно

komrad-jacarta

Сайдкар для операций с токеном JaCarta (см. Шифрование токеном JaCarta). PIN передаётся только через переменную окружения KOMRAD_JACARTA_PIN.

Команда	Назначение
`init-key`	Сгенерировать ключевую пару ГОСТ Р 34.10-2012 на токене и выгрузить открытый ключ
`import-key`	Выгрузить открытый ключ существующего ключа на токене
`decrypt-dek`	Расшифровать ключ данных при восстановлении (вызывается `komrad-cli restore` автоматически)

Флаг	Команды	Описание
`--module`	все	Путь к библиотеке PKCS#11 (обязателен)
`--token-label`	все	Метка токена (CKA_LABEL)
`--key-label`	все	Метка ключа на токене
`--paramset`	`init-key`	Параметры кривой ГОСТ: `TCA` (умолчание) \| `A` \| `B`
`--pubkey-out`	`init-key`, `import-key`	Путь для записи открытого ключа (PEM)

komrad-cli backup create​

komrad-cli backup verify​

komrad-cli backup prune​

komrad-cli restore​

backup.env​

komrad-backup.yaml​

komrad-jacarta​