From aa316a3eca42121aca81bc36cdf4b74acf8af998 Mon Sep 17 00:00:00 2001 From: ge Date: Sun, 15 May 2022 11:41:15 +0300 Subject: [PATCH] feat: Update man --- docs/baf.1.rst | 270 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 209 insertions(+), 61 deletions(-) diff --git a/docs/baf.1.rst b/docs/baf.1.rst index d038f1f..3b03964 100644 --- a/docs/baf.1.rst +++ b/docs/baf.1.rst @@ -2,66 +2,60 @@ baf === ----------------------------------- -backup automation micro-framework. ----------------------------------- +--------------------------- +backup files and databases. +--------------------------- +:Author: ge :Copyright: \(C) 2022, ge , GPLv3+ +:Date: 2022 May 15 :Manual section: 1 +:Version: baf 0.0.1 Синопсис -------- -``baf`` [options] [] +``baf`` [-cvlhV] FILE.. Описание -------- -Baf это утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание полных резервных копий файлов и баз данных MySQL и PostgreSQL, но функционал может быть расширен в сценариях при помощи пользовательских функций. +Baf (Backup Automation Micro-framework) - это расширяемая утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание резервных копий файлов с помощью ``tar`` и дампов баз данных MySQL/MariaDB и PostgreSQL. Опции ----- --h, --help print help text and exit. --v, --version print version and exit. +-c, --config config file. +-v, --verbose verbose output. +-l, --log-file log file. +-h, --help print this help messagea and exit. +-V, --version print version and exit. -Основы ------- +Быстрый старт +------------- -Baf это седство для полного резервного копирования и может быть использован как микро-фреймворк для написания сценариев резервного копирования. +Baf можно рассматривать как небольшой фреймворк или библиотеку для создания сценариев резервного копирования. Baf не реализует собственный язык сценариев, а полагается на Bash. В любом варианте применения утилита требует написания сценария для выполнения бэкапа. -Baf не реализует собственный язык сценариев, а полагается на Bash. В любом варианте применения Baf требует написания сценария для выполнения бэкапа. - -В сценариях можно использовать переменные и функции. Сценарий импортируется Baf с помощью команды `source` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS). +В сценариях можно использовать переменные и функции. Сценарий импортируется в основной скрипт с помощью команды ``source`` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS). Простейший сценарий резервного копирования выглядит следующим образом:: sources=('file:/home/user') targets=('file:/var/backup') -Здесь массивы `sources` и `targets` определяют точки (`points`) резервного копирования — источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает Baf. Вот некоторые особенности точек: +Здесь массивы `sources` и `targets` определяют точки или поинты (`points`) резервного копирования — источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает Baf. Вот некоторые особенности поинтов: -- Все точки указываются в формате URI (см. RFC 3986). Описание URI также есть в этой документации ниже.ы -- Точки могут указывать как на локальные (размещённые на текущей машине), так и на удалённые (размещённые на удалённой машине) ресурсы. +- Все поинты указываются в формате URI. Описание URI также есть в этой документации ниже. +- Поинты могут указывать как на локальные (размещённые на текущей машине), так и на удалённые (размещённые на удалённой машине) ресурсы. - Можно указать как несколько источников, так и несколько назначений. Для выполнения бэкапа директорий или отдельных файлов применяется схема URI `file`. В схеме `file` нельзя указать директорию, размещённую на удалённом хранилище (за исключением случая, когда удалённое хранилище примонтировано как файловая система), для этого используйте другие схемы. В примере выше будет выполнена резервная копия локальной директории /home/user в другую локальную директорию /var/backup. Поскольку в сценарии из примера нет ничего, кроме указания точек `sources` и `targets`, бэкап будет выполнен с параметрами по умолчанию: директория /home/user будет заархивирована с помощью утилиты ``tar``\(1), архив будет сжат с помощью утилиты ``gzip``\(1) и помещён в директорию /var/backup. Имя архива будет сложено из строки:: - ${name_prefix}${name}_%Y%m%d-%H%M${file_ext} + ${name_prefix}${name}_${name_date_fmt}${name_ext} -Здесь: +Описание переменных см. в разделе ПЕРЕМЕННЫЕ. Пример имени файла:: - ``${name_prefix}`` - Переменная, значение которой соответствует имени файла сценария (без расширения). - - ``${name}`` - Имя архивируемой директории/файла (``basename``\(1)). - - ``%Y%m%d-%H%M`` - Дата, интерпретируемая утилитой ``date``\(1). - - ``${file_ext}`` - Расширение имени файла, соответствующее формату архива. По умолчанию ".tar.gz". + example.sh_example_20220515-0953.tar.gz Обзор URI --------- @@ -70,7 +64,7 @@ Baf не реализует собственный язык сценариев, scheme:[//[username[:password]@]hostname[:port]]/[path]?[query]#[fragment] -Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация отдельных ситуаций может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта. +Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация в отдельных ситуациях может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта. На текущий момент компоненты `query` и `fragment` не используются. Примеры URI для массива `sources`:: @@ -86,7 +80,7 @@ Baf не реализует собственный язык сценариев, rsync://backup_user@192.168.3.12:2022/backups s3://my_bucket -Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. +Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. См. примеры кодирования строки на разных языках программирования ниже. Python 2:: @@ -102,7 +96,6 @@ Perl 5:: Поддерживаемые протоколы и схемы URI ------------------------------------ - Схемы, которые могут быть использованы как sources `````````````````````````````````````````````````` @@ -111,51 +104,65 @@ file file:/var/www/html file:///home/jhon/cool_stuff.txt + + Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса. + + См. также ``backup_files()`` mysql URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат:: mysql://[username[:password]@]hostname[:port]/database - С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``. + С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``. + + См. также ``backup_mysql()`` postgres - Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением ".psql.gz". + Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением .psql.gz. + + См. также ``backup_postgres()`` sqlite Схема для баз данных SQLite. Ничем не отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл. + + См. также ``backup_sqlite()`` Схемы, которые могут быть использованы как targets `````````````````````````````````````````````````` file - См. описание выше. В контексте `targets` указывает директорию для сохранения архивов с файлами и базами данных. + В контексте `targets` указывает директорию для сохранения бэкапов. В массиве `targets` обязательно должен быть хотя бы один поинт со схемой `file`. Этот поинт будет использован как основной и сохранён в переменные ``__main_target`` (содержит URI) и ``__main_target_path`` (path). Если в массиве присутствует несколько поинтов со схемой `file`, то в качестве основного будет выбран первый по порядку поинт. Все бэкапы первоначально будут сохраняться в директорию ``__main_target_path`` и затем копироваться в другой таргет с помощью соответствующего обработчика. В случае копировани из одной директории в другую используется утилита ``cp``\(1). + + Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно. + + См. также ``transfer_files()`` ftp - Для выполнения загрузки файлов на удалённый FTP-сервер используется утилита GNU ``ftp``\(1). + Не реализовано. sftp - OpenSSH File Transfer Protocol. + Не реализовано. rsync - Rsync. + Не реализовано. s3 - Amazon S3 or any S3-compatible storage. + Не реализовано. swift - OpenStack Swift. + Не реализовано. sj - Storj DCS. + Не реализовано. dav, davs - WebDAV. + Не реализовано. Создание резервных копий ------------------------ -Baf предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. Baf также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено в Baf по умолчанию. +Baf предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. Baf также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup()``, ``process_sources()``, ``process_targets()``. Базовая концепция строится на том, что существует несколько точек источников и несколько точек назначения. Создаётся резервная копия источника и копируется в точку назначения. @@ -174,11 +181,6 @@ Baf предполагает, что для всех резервных копи Здесь будут созданы архивы файлов и базы данных и сохранены в локальную директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории /var/backup не будут удалены или перемещены. Если добавить дополнительную точку назначения, то файлы из /var/backup будут скопированы и туда. Обратите внимание, что Baf не выполняет повторного создания архивов для каждой точки назначения — архивы создаются один раз и далее распространяются по всем указанным назначениям. Если в массиве `targets` имеется несколько точек назначения со схемой `file`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные. -Потребление ресурсов --------------------- - -Избегайте указания в одном сценарии точек назначения, которые ведут на примонтированный к локальной машине сетевой диск и другое удалённое хранилище одновременно. В таком случае архивы будут создаваться сразу на сетевом диске, что может существенно замедлить скорость их создания. Также при копировании файлов в другое удалённое хранилище будет выполняться двойная работа по сети, что тоже будет очень медленным. - Резервное копирование на удалённое хранилище -------------------------------------------- FTP @@ -201,29 +203,175 @@ WebDAV `````` Переменные ---------- -Baf условно разделяет переменные на "внутренние" ("защищённые") и "общие". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "общими". -Общие переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи общих переменных — в обоих случаях есть риск что-то поломать. +Baf условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными". -``__log_file`` - Путь до файла лога. +Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать. -``__main_target`` - Главный `target` для хранения локальных резервных копий. Эта переменная содержит первый по порядку URI со схемой `file` из массива `targets`. Директория (`path`) из этой точки используется в качестве буфферной, если в `targets` указаны дополнительные точки. +``backups`` + Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`. -``__source_handler`` - Содержит имя функции, которая будет обрабатывать URI из `sources`. + Умолчание: () -``__target_handler`` - Аналогично ``__source_target``, но для `targets`. +``errors`` + Массив с текстами ошибок. Заполняется функцией ``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). + + Умолчание: -acf + +``tar_compression`` + Работа этой фичи базируется на ``tar --auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже. + + ======================== ================ ======== + Значение tar_compression Расширение файла Утилита + ======================== ================ ======== + gzip, gz .tar.gz gzip + tgz .tgz gzip + taz .taz gzip + compress, Z .tar.Z compress + taZ .taZ compress + bzip2, bz2 .tar.bz2 bzip2 + tz2 .tz2 bzip2 + tbz2 .tbz2 bzip2 + tbz .tbz bzip2 + lzip, lz .tar.lz lzip + lzma .tar.lzma lzma + tlz .tlz lzma + lzop, lzo .tar.lzo lzop + xz .tar.xz xz + zstd, zst .tar.zst zstd + tzst .tzst zstd + ======================== ================ ======== + + Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``. Функции ------- + +``backup`` + Пользовательская функция резервного копирования. Если она задана в скрипте, то вызывается вместо ``builtin_backup()``. + +``backup_files URI`` + Архивация файлов с помощью ``tar``. + +``backup_mysql URI`` + Не реализовано. + +``backup_postgres URI`` + Не реализовано. + +``backup_sqlite URI`` + Не реализовано. + +``builtin_backup`` + Встроенная функция, запускает резервное копирвоание. Вызывает функции ``process_source()`` и ``process_target()``. + +``err [-eao] MESSAGE`` + Печатает сообщение об ошибке MESSAGE на экран и в лог и выполняет обработку ошибок. + + -e Выйти из скрипта с кодом выхода 1. + -a Добавить сообщение MESSAGE в массив ``errors``. + -o Вызвать функцию ``on_error()``. + +``finalise`` + Пользовательская функция. Если задана, то запускается после функции ``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``. Рекомендуется для использования в качестве враппера для команд правильное выполнение которых важно. + +``is_installed COMMAND`` + Проверяет установлена ли программа COMMAND. + +``is_function_set FUNCTION`` + Проверяет задана ли функция FUNCTION. + +``log [-p] MESSAGE`` + Печатает лог в файл ``__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``. + +``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`` + Не реализовано. + Использование функций в сценариях --------------------------------- -See also --------- +Примеры +------- +См. также +--------- -``bash``\(1), ``tar``\(1), ``date``\(1), ``mysqldump``\(1), ``pg_dump``\(1) +``bash``\(1), ``tar``\(1), ``cp``\(1), ``date``\(1), ``mysqldump``\(1), ``pg_dump``\(1) RFC 3986 https://datatracker.ietf.org/doc/html/rfc3986