boring-backup можно рассматривать как фреймворк или библиотеку для создания сценариев резервного копирования. Сценарии должны содержать валидный код на Bash. Сценарий импортируется в основной скрипт с помощью команды ``source`` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
Здесь массивы `sources` и `targets` определяют точки, они же поинты (`points`) резервного копирования: источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает boring-backup. Вот некоторые особенности поинтов:
Для выполнения бэкапа директорий или отдельных файлов применяется схема URI `file`. В схеме `file` нельзя указать директорию, размещённую на удалённом хранилище (за исключением случая, когда удалённое хранилище примонтировано как файловая система), для этого используйте другие схемы. В примере выше будет выполнена резервная копия локальной директории /home/user в другую локальную директорию /var/backup. Поскольку в сценарии из примера нет ничего, кроме указания точек `sources` и `targets`, бэкап будет выполнен с параметрами по умолчанию: директория /home/user будет заархивирована с помощью утилиты ``tar``\(1) и помещён в директорию /var/backup. Имя архива будет сложено из строки::
Источники (`sources`) и назначения (`targets`) должны быть указаны в виде URI. Это позовляет наглядно в одной сроке видеть весь набор данных. Парсер реализует поддержку следующего синтаксиса URI::
Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация в отдельных ситуациях может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта. На текущий момент компоненты `query` и `fragment` не используются.
Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. См. примеры кодирования строки на разных языках программирования ниже.
Может содержать путь к локальному файлу или директории. Файлы архивируются при помощи ``tar`` и по умолчанию не сжимаются. Cжатие архива может быть включено через переменную `compression`. Примеры::
Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса.
С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL. Файл по умолчанию не сжимается, но сжатие может быть включено через переменную `compression`.
Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1) с расширением .psql. Файл по умолчанию не сжимается, но сжатие может быть включено через переменную `compression`.
В контексте `targets` указывает директорию для сохранения бэкапов. В массиве `targets` обязательно должен быть хотя бы один поинт со схемой `file`. Этот поинт будет использован как основной и сохранён в переменные ``__main_target`` (содержит URI) и ``__main_target_path`` (содержит компонент URI path). Если в массиве присутствует несколько поинтов со схемой `file`, то в качестве основного будет выбран первый по порядку поинт. Все бэкапы первоначально будут сохраняться в директорию ``__main_target_path`` и затем копироваться в другой таргет с помощью соответствующего обработчика. В случае копировани из одной директории в другую используется утилита ``cp``\(1).
Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно.
boring-backup предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. boring-backup также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup``, ``process_sources``, ``process_targets``.
Базовая концепция строится на том, что существует несколько источников и несколько точек назначения. Создаётся резервная копия источника и копируется в точку назначения.
Для всех источников в сценарии выполняется локальная резервная копия. После этого локальная копия переносится в удалённые точки назначения, если они заданы. Копирование локального бэкапа будет осуществлёно столько раз, сколько точек назначения задано. В каждом сценарии обязательно должен быть задан хотя бы один источник и одна точка назначения. При этом в списке точек назначения обязательно должна присутствовать точка со схемой `file`. Именно в неё будут сохранены архивы.
Здесь будут созданы архивы файлов и базы данных и сохранены в локальную директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории /var/backup не будут удалены или перемещены. Если добавить дополнительную точку назначения, то файлы из /var/backup будут скопированы и туда. Обратите внимание, что boring-backup не выполняет повторного создания архивов для каждой точки назначения — архивы создаются один раз и далее распространяются по всем указанным назначениям. Если в массиве `targets` имеется несколько точек назначения со схемой `file`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные.
``boring-backup`` условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными".
Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать.
``backups``
Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`.
В контексте ``tar`` работа этой фичи базируется на опции ``tar````--auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже. Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``. Если переменная пуста или не задана, то сжатие будет отключено.
Печатает полученное имя файла в STDOUT. Имя является выводом команды ``date`` и строки ``${prefix}${name}${date_fmt}${name_ext}``. См. переменные ``name_prefix``, ``name``, ``name_date_fmt``, ``name_ext``.
Функция выполняет команду COMMAND и в случае ненулевого кода выхода вызывает ``err()``с ключами ``-eao``. Ошибка при выполнении COMMAND приведёт к вызову функции ``on_error``. Рекомендуется для использования в качестве обёртки для команд правильное выполнение которых критично.
Печатает лог в файл ``__log_file`` (лог задаётся опцией --log-file) и на экран, если указана опция ``-p``. Формат даты в логе можно изменить с помощью переменной ``log_date_fmt``.
``on_error``
Пользовательская функция для обработки ошибок. Если задана, то запускается при обработке ошибки в функции ``err``с опцией ``-o``.
``parse_uri URI``
Парсер URI. Задаёт переменные ``scheme``, ``username``, ``password``, ``hostname``, ``port``, ``path``, ``query``, ``fragment`` и выполняет декодинг пароля, если он закодирован в percent code.
``prepare``
Пользовательская функция. Если задана, то запускается до функции ``backup`` или ``builtin_backup``.
``process_source URI``
На основе схемы запускает соответсвующую функцию-обработчик.
``process_target URI``
На основе схемы запускает соответсвующую функцию-обработчик.
``source_script FILE``
Выполняет ``source`` пользовательского скрипта и проверяет его корректность. Проверяется синтаксис Bash, наличие непустых массивов `sources` и `targets`, наличие поинта `file` в `targets`. Во вспомогательной функции ``validate_targets`` задаются значения переменных ``__main_target`` и ``__main_target_path``.
