Runbook: установка, systemd и проверка IOBackup

Этот документ описывает эксплуатацию IOBackup на Linux в проде-подобном режиме:

• установка из пакетов (.deb, .rpm), а не сборка из исходников;
• запуск iobackup-agent как сервис systemd;
• управление заданиями через установленный iobackupctl (бинарник в PATH).

Сценарии с Docker Compose под «dev-стенды» (Vault, LDAP, ClickHouse и т.д.) предполагают, что у вас есть каталог examples/ из репозитория (или копия нужных docker-compose-файлов) — пакет с бинарями не обязан поставлять эти YAML.

Содержание (кратко)

1. Обзор компонентов и портов
2. Предварительные требования на хосте
3. Установка .deb / .rpm
4. Файловая раскладка, каталоги и права
5. Конфигурация: agent.yaml, agent.env
6. Unit systemd и первый запуск
7. Проверка здоровья API и авторизация
8. Клиент iobackupctl: типовые флаги
9. Откуда брать описания jobs (YAML)
   10–15. Пошаговые проверки (filesystem, Postgres, MySQL, S3, …)
10. Manifest, логи задач, webhooks
11. Полный matrix (опционально, из git)
12. Диагностика и журнал systemd
13. Обновление и откат версии

1) Обзор компонентов

По умолчанию агент слушает адрес из IOBACKUP_LISTEN (часто 127.0.0.1:8735). Базовый URL для клиента и curl:

http://127.0.0.1:8735

Если смените IOBACKUP_LISTEN (например 0.0.0.0:8735 за reverse-proxy), все команды ниже подставляйте свой базовый URL.

2) Предварительные требования на хосте

Обязательно после установки пакета:

• systemd (типично для поддерживаемых дистрибутивов с .deb / .rpm);
• возможность записи в каталоги данных и логов (см. §4).

Не нужен Go ни на сервере с агентом, ни на машине оператора для обычного iobackupctl, если установлен готовый пакет клиента или тот же пакет (в нём оба бинаря).

Внешние утилиты (по задачам в YAML):

Проверка (выполняйте только для тех режимов, которые используете):

command -v docker
command -v pg_dump
command -v mysqldump
command -v aws

3) Установка пакета

Debian / Ubuntu (.deb)

Из собранного артефакта (версию подставьте свою):

sudo apt-get update   # при необходимости
sudo dpkg -i iobackup_<версия>_<архитектура>.deb
sudo apt-get -f install -y   # подтянуть зависимости, если пожаловался dpkg

Проверка:

iobackup-agent -version
iobackupctl -version
which iobackup-agent iobackupctl

RHEL / Alma / Rocky / Fedora (.rpm)

sudo dnf install -y ./iobackup-<версия>.<архитектура>.rpm
# или на старых системах: sudo yum localinstall ...

Файловая траектория пакета: агент в /usr/sbin, CLI в /usr/bin (см. docs/packaging/package-layout.md).

4) Файловая раскладка, каталоги и права

Рекомендуемая схема (можно изменить через переменные в env-файле):

Пакет создаёт пользователя iobackup и каталоги state/log. jobs.dir / auto-load с диска не включены в v1.0 — задания через API/iobackupctl (см. docs/reference/agent-config.md).

Первый запуск без agent.yaml:

curl -sS http://127.0.0.1:8735/api/v1/health | jq .config
# ожидается config.missing: true до cp agent.yaml.example → agent.yaml

5) Конфигурация: agent.yaml и agent.env

Полная справка: docs/reference/agent-config.md.

1. Активируйте runtime config (пакет ставит только example):

   sudo cp /etc/iobackup/agent.yaml.example /etc/iobackup/agent.yaml
   sudo ${EDITOR:-vi} /etc/iobackup/agent.yaml
   iobackup-agent config validate --config /etc/iobackup/agent.yaml

2. Секреты и overrides — /etc/iobackup/agent.env (подхватывается unit как EnvironmentFile=-/etc/iobackup/agent.env):

   sudo install -d -m 0750 -o root -g iobackup /etc/iobackup
   printf 'IOBACKUP_API_TOKEN=%s\n' "$(openssl rand -hex 24)" | sudo tee /etc/iobackup/agent.env >/dev/null
   sudo chmod 600 /etc/iobackup/agent.env
   sudo chown root:iobackup /etc/iobackup/agent.env

3. Отредактируйте YAML/env (listen, auth, пути, feature gates). Пароли БД и ключи S3 — через env, как в job (*_env), не в открытом YAML.

Смысл блоков:

• Сеть и идентичность агента: IOBACKUP_LISTEN, IOBACKUP_AGENT_ID, IOBACKUP_AGENT_NAME, IOBACKUP_AGENT_MODE, IOBACKUP_AGENT_LABELS, IOBACKUP_IDENTITY_DIR, IOBACKUP_HOSTNAME.
• Пути: IOBACKUP_DB_PATH, IOBACKUP_LOG_PATH, IOBACKUP_RUNS_LOG_DIR.
• Логирование: IOBACKUP_LOG_LEVEL, IOBACKUP_LOG_OUTPUT (stderr удобен вместе с journalctl, если направляете вывод в journal — см. политику вашего unit), IOBACKUP_TASK_LOG_DUP_DB.
• Ротация: IOBACKUP_RUN_LOGS_RETENTION_DAYS, IOBACKUP_DB_RETENTION_DAYS, IOBACKUP_RETENTION_CLEANUP_INTERVAL (читает процесс агента из окружения при старте).
• TLS: пустые IOBACKUP_TLS_* если HTTPS/mTLS не используются; иначе пути к файлам.
• Секреты провайдеров: значения задаются только так, как указано в job: *_env (видит процесс агента), *_path (файл на узле агента) или *_vault (KV v2 ref; клиент Vault — настройки iobackup-agent: IOBACKUP_VAULT_ADDR, токен, CA, -job-secrets-file / IOBACKUP_JOB_SECRETS_FILE для overlay перед validate). Plaintext ключей в «основном» YAML discouraged — см. job-format-v1.md.

Права на env-файл:

sudo chmod 600 /etc/iobackup/agent.env
sudo chown root:iobackup /etc/iobackup/agent.env

6) Unit systemd и первый запуск

6.1 Пакетный unit

DEB/RPM устанавливают unit в /usr/lib/systemd/system/iobackup-agent.service:

ExecStart=/usr/sbin/iobackup-agent --config /etc/iobackup/agent.yaml
EnvironmentFile=-/etc/iobackup/agent.env
User=iobackup

См. docs/packaging/systemd-unit.md. Ручная установка из examples/iobackup-agent.service — только для dev без пакета.

sudo systemctl daemon-reload

6.2 Включение и запуск

sudo systemctl enable --now iobackup-agent.service
sudo systemctl status iobackup-agent.service --no-pager

6.3 Логи

Если IOBACKUP_LOG_OUTPUT=file (как в шаблоне env), смотрите файл:

sudo tail -n 200 /var/log/iobackup/agent.log

Интеграция с journal (если перенастроите вывод на stderr/both и не дублируете в файл — по вашей политике):

sudo journalctl -u iobackup-agent.service -f

6.4 Перезапуск после смены env

sudo systemctl restart iobackup-agent.service

7) Проверка здоровья API и авторизация

Подставьте свой базовый URL (ниже — дефолт 127.0.0.1:8735):

export IOBACKUP_API_BASE="http://127.0.0.1:8735"
curl -sS "${IOBACKUP_API_BASE}/api/v1/health"

Список jobs (с Bearer, как в типовом prod-включённом -auth-enabled):

curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" \
  "${IOBACKUP_API_BASE}/api/v1/jobs"

8) Клиент iobackupctl

Установлен в PATH вместе с агентом.

Типовой вызов:

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN <команда>

Полезно зафиксировать в shell-профиле оператора:

export IOBACKUP_API_BASE="http://127.0.0.1:8735"

Справка:

iobackupctl --help
iobackupctl job --help

Коды выхода и глобальные флаги (--server, --token-env, --output, --timeout): docs/reference/cli-standards.md.

9) Откуда брать YAML заданий

Варианты:

1. Локальные файлы оператора (удобно хранить копии в /etc/iobackup/jobs/ или в git): iobackupctl job submit /path/to/job.yaml — автозагрузка каталога jobs.dir в v1.0 не включена.
2. Каталог примеров на сайте (при раздаче site/): удобно для чтения; для submit всё равно нужен локальный путь к файлу на машине, где запускается iobackupctl.
3. Клон репозитория на админской машине или на сервере: пути ./examples/... как в разделах ниже.

Далее в примерах используется переменная:

# пример: разместили копии в /etc/iobackup/jobs
export JOBDIR="/etc/iobackup/jobs"

Если используете клон репозитория, замените на export JOBDIR="/path/to/iobackup/examples".

10) Локальный filesystem backup (smoke)

Файлы: filesystem.local.yaml · YAML.

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/filesystem.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job run filesystem-local

Проверка:

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN run list
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list

11) PostgreSQL backup

Файл: postgres.local.yaml · YAML.

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/postgres.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job run postgres-local

Проверка task (подставьте run_id из вывода run list):

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN run list
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN task list <run_id>

Переменная POSTGRES_BACKUP_PASSWORD должна быть доступна процессу агента (через iobackup-agent.env).

12) MySQL backup

Файл: mysql.local.yaml · YAML.

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/mysql.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job run mysql-local

Аналогично Postgres: MYSQL_BACKUP_PASSWORD в окружении агента.

13) Filesystem → S3 (Timeweb / streaming)

Каталог примеров на сайте.

Файлы:

• filesystem.s3.streaming.yaml · YAML
• filesystem.s3.env.streaming.yaml · YAML (endpoint/region через env)

В iobackup-agent.env должны быть заданы S3_ACCESS_KEY, S3_SECRET_KEY, S3_ENDPOINT, S3_REGION (или только те, что реально читает ваш YAML).

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/filesystem.s3.streaming.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job run filesystem-s3-streaming

Проверка:

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN task list <run_id>
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list

Проверка объектов в bucket (с хоста с aws):

aws s3 ls s3://iobackup/iobackup-tests/filesystem/max-docker/ \
  --recursive \
  --endpoint-url https://s3.twcstorage.ru \
  --region ru-1

14) Vault backup (dev Docker стенд)

Нужны файлы из examples/dev/vault/ репозитория. Поднять стенд:

docker compose -f ./examples/dev/vault/docker-compose.yml up -d
chmod +x ./examples/dev/vault/seed-dev.sh
VAULT_ADDR=http://127.0.0.1:18200 VAULT_TOKEN=root ./examples/dev/vault/seed-dev.sh

Переменная VAULT_TOKEN должна быть видна процессу агента (добавьте в /etc/iobackup/iobackup-agent.env или временно экспортируйте и перезапустите только если так принято политикой — лучше env-файл).

Файл: vault.local.yaml.

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/vault.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN job run vault-local
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list

Остановка стенда:

docker compose -f ./examples/dev/vault/docker-compose.yml down -v

15) OpenLDAP, ClickHouse, Docker Compose источники (dev стенды)

Структура та же: Docker Compose из examples/dev/..., затем job submit/run нужного examples/*.local.yaml.

OpenLDAP:

docker compose -f ./examples/dev/openldap/docker-compose.yml up -d
# OPENLDAP_ADMIN_PASSWORD в env агента
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/openldap.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN job run openldap-local
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list
docker compose -f ./examples/dev/openldap/docker-compose.yml down -v

ClickHouse:

docker compose -f ./examples/dev/clickhouse/docker-compose.yml up -d
chmod +x ./examples/dev/clickhouse/seed-dev.sh
./examples/dev/clickhouse/seed-dev.sh
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/clickhouse.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN job run clickhouse-local
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list
docker compose -f ./examples/dev/clickhouse/docker-compose.yml down -v

Docker Compose как source:

chmod +x ./examples/dev/compose-app/seed-dev.sh
./examples/dev/compose-app/seed-dev.sh
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN \
  job submit "${JOBDIR}/docker-compose.local.yaml"
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN job run docker-compose-local
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list
docker compose -f ./examples/dev/compose-app/docker-compose.yml \
  --project-directory ./examples/dev/compose-app down -v

16) Manifest, логи задач и webhooks

Manifest артефакта

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact list
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN artifact manifest <backup_id>

Лог задачи через HTTP

Переменная run_id / task_id из CLI или API:

curl -sS -H "Authorization: Bearer ${IOBACKUP_API_TOKEN}" \
  "${IOBACKUP_API_BASE}/api/v1/runs/<run_id>/tasks/<task_id>/logs"

Уведомления (webhooks)

iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN notification list
iobackupctl --server "${IOBACKUP_API_BASE}" --token-env IOBACKUP_API_TOKEN notification get <notification_event_id>

Сбой доставки webhook не должен менять финальный результат backup задачи по дизайну продукта (см. webhooks).

17) Полный matrix smoke/e2e (examples/tests)

Скрипт и набор YAML ожидают рабочее дерево репозитория (examples/tests, dev-контейнеры, переменные окружения). Это режим QA/разработки, не обязательный на каждой prod-ноде.

cd /path/to/iobackup
export IOBACKUP_API_TOKEN=...
export POSTGRES_BACKUP_PASSWORD=...
export MYSQL_BACKUP_PASSWORD=...
export OPENLDAP_ADMIN_PASSWORD=...
export VAULT_TOKEN=...
export S3_ACCESS_KEY=...
export S3_SECRET_KEY=...
export S3_ENDPOINT=https://s3.twcstorage.ru
export S3_REGION=ru-1

bash ./examples/tests/run-full-matrix.sh

Артефакты матрицы по умолчанию могут падать под /tmp/iobackups (как задумано в тестах).

18) Диагностика и частые проблемы

Сервис не стартует

sudo systemctl status iobackup-agent.service --no-pager -l
sudo journalctl -u iobackup-agent.service -b --no-pager -n 200

Частые причины:

• отсутствует или не читается /etc/iobackup/iobackup-agent.env;
• ошибка прав на /var/lib/iobackup или /var/log/iobackup;
• указан уже занятый IOBACKUP_LISTEN.

401 / доступ к API

• проверьте IOBACKUP_API_TOKEN в env агента и то же значение у клиента (--token или --token-env);
• клиент должен использовать тот же URL, что и IOBACKUP_LISTEN (за NAT/proxy см. свой маршрут).

«Утилита не найдена» (pg_dump, mysqldump, aws)

• установите пакеты клиента на хост или переключите job на runner.mode: docker (см. job-format-v1).

S3 ошибки подписи / endpoint

• сверьте S3_ENDPOINT, S3_REGION, ключи и поддержку path-style для вашего провайдера (см. s3-destination).

LDAP / Vault / ClickHouse из dev-разделов

• убеждайтесь, что контейнеры подняты и переменные с паролями доступны именно процессу iobackup-agent.

19) Обновление и откат

Рекомендуемый порядок для prod:

1. Установите новый .deb/.rpm (поверх старого) в окно обслуживания.
2. sudo systemctl daemon-reload (если поставили обновлённый unit или drop-in).
3. sudo systemctl restart iobackup-agent.service.
4. Smoke: health, при необходимости GET /api/v1/capabilities / GET /api/v1/agent/facts, затем один контролируемый job run.
5. Мониторинг метрик /metrics (см. operations; cardinality policy — prometheus).

Карта модели и ссылок на документацию: docs/architecture/model-foundation.md.

Откат: установите предыдущую версию пакета тем же менеджером пакетов и перезапустите сервис.

Подробнее о метриках, ретеншене журналов и операционном регламенте — operations.

20) Остановка сервиса

sudo systemctl stop iobackup-agent.service
sudo systemctl disable iobackup-agent.service   # если нужно отключить автозапуск

Данные в /var/lib/iobackup и /var/log/iobackup при этом не удаляются.