From f779aa82b55936175810a4ebad7cf5d86c556b8b Mon Sep 17 00:00:00 2001 From: ge Date: Tue, 7 Jun 2022 22:04:57 +0300 Subject: [PATCH] feat: Update manual --- docs/boring-backup.1.rst | 136 +++++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 62 deletions(-) diff --git a/docs/boring-backup.1.rst b/docs/boring-backup.1.rst index 66d8698..0930b39 100644 --- a/docs/boring-backup.1.rst +++ b/docs/boring-backup.1.rst @@ -107,7 +107,7 @@ file Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса. - См. также ``backup_files()`` + См. также ``handler::tar`` mysql URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат:: @@ -116,17 +116,17 @@ mysql С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``. - См. также ``backup_mysql()`` + См. также ``handler::mysqldump`` postgres Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением .psql.gz. - См. также ``backup_postgres()`` + См. также ``handler::pg_dump`` sqlite Схема для баз данных SQLite. Ничем не отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл. - См. также ``backup_sqlite()`` + См. также ``handler::sqlite`` Схемы, которые могут быть использованы как targets `````````````````````````````````````````````````` @@ -136,7 +136,7 @@ file Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно. - См. также ``transfer_files()`` + См. также ``handler::cp`` ftp Не реализовано. @@ -162,7 +162,7 @@ dav, davs Создание резервных копий ------------------------ -boring-backup предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. boring-backup также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup()``, ``process_sources()``, ``process_targets()``. +boring-backup предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. boring-backup также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup``, ``process_sources``, ``process_targets``. Базовая концепция строится на том, что существует несколько точек источников и несколько точек назначения. Создаётся резервная копия источника и копируется в точку назначения. @@ -204,52 +204,66 @@ WebDAV Переменные ---------- -boring-backup условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными". +``boring-backup`` условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными". Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать. ``backups`` Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`. + Тип: массив Умолчание: () ``errors`` - Массив с текстами ошибок. Заполняется функцией ``err()`` с опцией ``-a``. + Массив с текстами ошибок. Заполняется функцией ``err`` с опцией ``-a``. + Тип: массив Умолчание: () ``log_date_fmt`` Формат даты в логе. См. ``date``\(1). + Тип: строка Умолчание: %d/%b/%Y:%H:%M:%S %z ``name_prefix`` Префикс имени файла. Может быть задан в скрипте. + Тип: строка Умолчание: имя_скрипта\_ ``name`` Соответствует имени архивируемой директории/файла полученного из `path` с помощью утилиты ``basename``\(1). + Тип: строка Умолчание: нет ``name_date_fmt`` Дата, интерпретируемая утилитой ``date``\(1). + Тип: строка Умолчание: _%Y%m%d-%H%M ``name_ext`` Расширение имени файла, соответствующее формату архива. + Тип: строка Умолчание: .tar.gz ``tar_options`` - Опции ``tar``\(1). + Опции ``tar``. См. ``tar``\(1). + Тип: строка Умолчание: -acf -``tar_compression`` - Работа этой фичи базируется на ``tar --auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже. +``tar_exclude`` + Список имён для опции ``tar`` ``--exclude``. + + Тип: массив + Умолчание: нет + +``compression`` + В контексте ``tar`` работа этой фичи базируется на опции ``tar`` ``--auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже. Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``. ======================== ================ ======== Значение tar_compression Расширение файла Утилита @@ -272,28 +286,14 @@ boring-backup условно разделяет переменные на "вн tzst .tzst zstd ======================== ================ ======== - Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``. - Функции ------- ``backup`` - Пользовательская функция резервного копирования. Если она задана в скрипте, то вызывается вместо ``builtin_backup()``. - -``backup_files URI`` - Архивация файлов с помощью ``tar``. - -``backup_mysql URI`` - Не реализовано. - -``backup_postgres URI`` - Не реализовано. - -``backup_sqlite URI`` - Не реализовано. + Пользовательская функция резервного копирования. Если она задана в скрипте, то вызывается вместо ``builtin_backup``. ``builtin_backup`` - Встроенная функция, запускает резервное копирвоание. Вызывает функции ``process_source()`` и ``process_target()``. + Встроенная функция, запускает резервное копирвоание. Вызывает функции ``process_source`` и ``process_target``. ``err [-eao] MESSAGE`` Печатает сообщение об ошибке MESSAGE на экран и в лог и выполняет обработку ошибок. @@ -303,13 +303,52 @@ boring-backup условно разделяет переменные на "вн -o Вызвать функцию ``on_error()``. ``finalise`` - Пользовательская функция. Если задана, то запускается после функции ``backup()`` или ``builtin_backup()``. + Пользовательская функция. Если задана, то запускается после функции ``backup`` или ``builtin_backup()``. ``gen_backup_name FILE_EXT`` Печатает полученное имя файла в STDOUT. Имя является выводом команды ``date`` и строки ``${prefix}${name}${date_fmt}${name_ext}``. См. переменные ``name_prefix``, ``name``, ``name_date_fmt``, ``name_ext``. ``try COMMAND`` - Функция выполняет команду COMMAND и в случае ненулевого кода выхода вызывает ``err() -eao``. Рекомендуется для использования в качестве враппера для команд правильное выполнение которых важно. + Функция выполняет команду COMMAND и в случае ненулевого кода выхода вызывает ``err()`` с ключами ``-eao``. Рекомендуется для использования в качестве обёртки для команд правильное выполнение которых критично. + +``handler::tar URI`` + Архивация файлов с помощью ``tar``. + +``handler::mysqldump URI`` + Не реализовано. + +``handler::pg_dump URI`` + Не реализовано. + +``handler::sqlite URI`` + Не реализовано. + +``handler::cp URI`` + Копирует файлы в новое назначение с помощью ``cp``. + +``handler::ftp URI`` + Не реализовано. + +``handler::sftp URI`` + Не реализовано. + +``handler::rsync URI`` + Не реализовано. + +``handler::s3 URI`` + Не реализовано. + +``handler::sj URI`` + Не реализовано. + +``handler::swift URI`` + Не реализовано. + +``handler::dav URI`` + Не реализовано. + +``handler::davs URI`` + Не реализовано. ``is_installed COMMAND`` Проверяет установлена ли программа COMMAND. @@ -321,56 +360,29 @@ boring-backup условно разделяет переменные на "вн Печатает лог в файл ``__log_file`` (лог задаётся опцией --log-file) и на экран, если указана опция ``-p``. Формат даты в логе можно изменить с помощью переменной ``log_date_fmt``. ``on_error`` - Пользовательская функция для обработки ошибок. Если задана, то запускается при обработке ошибки в функции ``err()`` с опцией ``-o``. + Пользовательская функция для обработки ошибок. Если задана, то запускается при обработке ошибки в функции ``err`` с опцией ``-o``. ``parse_uri URI`` Парсер URI. Задаёт переменные ``scheme``, ``username``, ``password``, ``hostname``, ``port``, ``path``, ``query``, ``fragment`` и выполняет декодинг пароля, если он закодирован в percent code. ``prepare`` - Пользовательская функция. Если задана, то запускается до функции ``backup()`` или ``builtin_backup()``. + Пользовательская функция. Если задана, то запускается до функции ``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``. - -``transfer_files URI`` - Копирует файлы в новое назначение с помощью ``cp``. - -``transfer_ftp URI`` - Не реализовано. - -``transfer_sftp URI`` - Не реализовано. - -``transfer_rsync URI`` - Не реализовано. - -``transfer_s3 URI`` - Не реализовано. - -``transfer_sj URI`` - Не реализовано. - -``transfer_swift URI`` - Не реализовано. - -``transfer_dav URI`` - Не реализовано. - -``transfer_davs URI`` - Не реализовано. + Выполняет ``source`` пользовательского скрипта и проверяет его корректность. Проверяется синтаксис Bash, наличие непустых массивов `sources` и `targets`, наличие поинта `file` в `targets`. Во вспомогательной функции ``validate_targets`` задаются значения переменных ``__main_target`` и ``__main_target_path``. Использование функций в сценариях --------------------------------- Переменные окружения -------------------- -``BBLIB`` +``LIBRARY`` Путь до библиотеки функций boring-backup. Примеры