Логирование и обработка ошибок в bash-скриптах

Задача и общий подход

Материал посвящён теме «Логирование и обработка ошибок в bash-скриптах» с акцентом на сопровождению, обновлению и откату.

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

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

Как устроена схема

cron подходит для простого расписания, systemd timer даёт зависимости, журнал и состояние запуска. cloud-init выполняет первичную настройку, но тоже должен быть идемпотентным.

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

Подготовка перед изменениями

Подготовительный этап снижает риск потерять доступ и смешать несколько причин одной неисправности.

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

Что должно получиться

После выполнения руководства по теме «Логирование и обработка ошибок в bash-скриптах» результат должен быть измеримым:

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

Пошаговая настройка

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

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
log() { printf '%s %s\n' "$(date --iso-8601=seconds)" "$*"; }
trap 'log "ERROR line=$LINENO"' ERR

command -v nginx >/dev/null 2>&1 || { echo 'nginx not installed' >&2; exit 1; }

[Unit]
Description=IIAdmin maintenance job

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/iiadmin-maintenance
User=root

[Unit]
Description=Run IIAdmin maintenance daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

systemd-analyze verify /etc/systemd/system/iiadmin-maintenance.service /etc/systemd/system/iiadmin-maintenance.timer
systemctl list-timers --all

Имена доменов, адреса, порты и пути в примерах условные. Перед выполнением замените их фактическими значениями.

Проверка результата

Проверка должна охватывать конфигурацию, процесс, listener и реальный запрос.

• повторный запуск безопасен
• ошибка даёт ненулевой код
• секреты не в журнале
• запуск виден в journalctl
• пропущенное расписание обработано

systemctl is-active SERVICE
systemctl status SERVICE --no-pager
journalctl -u SERVICE -n 80 --no-pager
ss -lntup

Типичные ошибки

Чаще всего восстановление усложняют следующие действия:

• перезапуск службы до проверки синтаксиса
• удаление рабочей конфигурации до успешного запуска новой
• игнорирование различий правил IPv4 и IPv6
• проверка только локального подключения без внешнего теста
• использование устаревшей команды без проверки версии пакета
• изменение нескольких компонентов одной командой без промежуточных тестов

Диагностика, если не заработало

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

1. Подтвердите симптом точной командой и запишите время.
2. Проверьте конфигурацию штатным тестом.
3. Проверьте процесс и последние записи журнала.
4. Убедитесь, что нужный адрес и порт слушаются.
5. Сравните локальный запрос с запросом извне.
6. Только затем проверяйте firewall, DNS и маршрут.
7. Меняйте одну переменную и повторяйте тот же тест.

Для темы «Логирование и обработка ошибок в bash-скриптах» важно не путать открытый firewall с запущенным сервисом: правило доступа не создаёт listener, а активный процесс не гарантирует доступность извне.

Безопасность

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

• ограничивайте административный доступ доверенными IP или VPN
• используйте принцип минимально необходимых прав
• не храните секреты в публикуемых конфигурациях и журналах
• закрывайте временные порты после завершения теста
• выдавайте файлам конфигурации минимальные права

Откат изменений

Откат выполняется в обратном порядке и с теми же проверками, что использовались после настройки.

1. disable timer
2. остановить service
3. вернуть скрипт
4. daemon-reload
5. запустить вручную в тестовом режиме

Не удаляйте неудачную конфигурацию до выяснения причины: она полезна для diff и разбора инцидента.

Дальнейшее сопровождение

Рабочая конфигурация со временем устаревает и требует контроля.

• проверяйте журналы ошибок и их размер
• контролируйте таймеры, сертификаты и автоматические задания
• документируйте нестандартные пути и зависимости
• периодически выполняйте тестовое восстановление
• храните резервную копию вне VPS

Контрольный список

Перед тем как считать тему «Логирование и обработка ошибок в bash-скриптах» закрытой, пройдите список:

Что дополнительно сверить в документации

При подготовке материала были сопоставлены разделы русскоязычной документации. Для углублённой проверки полезно изучить:

• Создать виртуальную машину с пользовательским скриптом конфигурации
• Создание виртуальной машины с пользовательским скриптом конфигурации Создание виртуальной машины с пользовательским скриптом конфигурации
• Примеры Примеры
• Была ли статья полезна?
• Модуль ngx_http_log_module

Границы задачи: Логирование и обработка ошибок в bash-скриптах

В этой статье рассматривается именно задача «Логирование и обработка ошибок в bash-скриптах», а не полная установка всех компонентов категории «Автоматизация». Перед началом перечислите файлы, процессы, порты и внешние зависимости, которые реально входят в изменение.

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

Побочные эффекты и соседние компоненты

Изменение по теме «Логирование и обработка ошибок в bash-скриптах» может затронуть соседние части схемы: права файлов, DNS, firewall, reverse proxy, сертификаты, автоматические задания или порядок запуска. До работы перечислите эти связи и выберите по одной короткой проверке для каждой критичной зависимости.

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

Результаты регрессионной проверки записывайте теми же командами, которые использовались до изменения. Это делает сравнение объективным и помогает быстро доказать, что соседний компонент не пострадал.

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

Повторяемость и контроль состояния

Автоматизация должна сначала определить текущее состояние и выполнять только недостающие действия. Повторный запуск обязан завершаться тем же результатом без дублирования.

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

Идемпотентность административного сценария

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

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

if ! grep -qxF 'desired line' /etc/example.conf; then
  printf '%s\n' 'desired line' >> /etc/example.conf
fi

Источники и документация

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

• Yandex Compute Cloud | Создать виртуальную машину с пользовательским скриптом конфигурации
• Модуль ngx_http_log_module