From e25d506e913add2dba30f8793a8a7a552b60003d Mon Sep 17 00:00:00 2001 From: ge Date: Sat, 13 Aug 2022 19:29:42 +0300 Subject: [PATCH] feat: format manpage --- docs/boring-backup.1.rst | 219 +++++++++++++++++++++++++++++---------- 1 file changed, 162 insertions(+), 57 deletions(-) diff --git a/docs/boring-backup.1.rst b/docs/boring-backup.1.rst index d7aadc0..6cc3277 100644 --- a/docs/boring-backup.1.rst +++ b/docs/boring-backup.1.rst @@ -1,16 +1,11 @@ -============= -boring-backup -============= - ---------------------------- -backup files and databases. ---------------------------- - +:Title: boring-backup +:Title upper: BORING-BACKUP +:Subtitle: backup files and databases :Author: ge :Copyright: \(C) 2022, ge , GPLv3+ :Date: 2022 May 15 :Manual section: 1 -:Version: baf 0.0.1 +:Version: boring-backup 0.1.0 Синопсис -------- @@ -20,7 +15,8 @@ backup files and databases. Описание -------- -boring-backup - это расширяемая утилита для резервного копирования на основе сценариев Bash. +boring-backup - это расширяемая утилита для резервного копирования на основе +сценариев Bash. Опции ----- @@ -35,20 +31,36 @@ boring-backup - это расширяемая утилита для резерв Быстрый старт ------------- -boring-backup можно рассматривать как фреймворк или библиотеку для создания сценариев резервного копирования. Сценарии должны содержать валидный код на Bash. Сценарий импортируется в основной скрипт с помощью команды ``source`` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS). +boring-backup можно рассматривать как фреймворк или библиотеку для создания +сценариев резервного копирования. Сценарии должны содержать валидный код на +Bash. Сценарий импортируется в основной скрипт с помощью команды ``source`` +(см. ``bash``\(1) п. SHELL BUILTIN COMMANDS). Простейший сценарий резервного копирования выглядит следующим образом:: - sources=('file:/home/user') - targets=('file:/var/backup') + sources=(file:/home/user) + targets=(file:/var/backup) -Здесь массивы `sources` и `targets` определяют точки, они же поинты (`points`) резервного копирования: источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает boring-backup. Вот некоторые особенности поинтов: +Здесь массивы `sources` и `targets` определяют точки, они же поинты (`points`) +резервного копирования: источники (`sources`) и назначения (`targets`). Это +основные сущности, с которыми работает boring-backup. Вот некоторые особенности +поинтов: - Все поинты указываются в формате URI. -- Поинты могут указывать как на локальные (размещённые на текущей машине), так и на удалённые (размещённые на удалённой машине) ресурсы. +- Поинты могут указывать как на локальные (размещённые на текущей машине), так + и на удалённые (размещённые на удалённой машине) ресурсы. - Можно указать как несколько источников, так и несколько назначений. -Для выполнения бэкапа директорий или отдельных файлов применяется схема URI `file`. В схеме `file` нельзя указать директорию, размещённую на удалённом хранилище (за исключением случая, когда удалённое хранилище примонтировано как файловая система), для этого используйте другие схемы. В примере выше будет выполнена резервная копия локальной директории /home/user в другую локальную директорию /var/backup. Поскольку в сценарии из примера нет ничего, кроме указания точек `sources` и `targets`, бэкап будет выполнен с параметрами по умолчанию: директория /home/user будет заархивирована с помощью утилиты ``tar``\(1) и помещён в директорию /var/backup. Имя архива будет сложено из строки:: +Для выполнения бэкапа директорий или отдельных файлов применяется схема URI +`file`. В схеме `file` нельзя указать директорию, размещённую на удалённом +хранилище (за исключением случая, когда удалённое хранилище примонтировано как +файловая система), для этого используйте другие схемы. В примере выше будет +выполнена резервная копия локальной директории /home/user в другую локальную +директорию /var/backup. Поскольку в сценарии из примера нет ничего, кроме +указания точек `sources` и `targets`, бэкап будет выполнен с параметрами по +умолчанию: директория /home/user будет заархивирована с помощью утилиты +``tar``\(1) и помещён в директорию /var/backup. Имя архива будет сложено по +шаблону:: ${name_prefix}${name}${name_date_fmt}${name_suffix}${name_ext} @@ -59,11 +71,20 @@ boring-backup можно рассматривать как фреймворк и Обзор URI --------- -Источники (`sources`) и назначения (`targets`) должны быть указаны в виде URI. Это позовляет наглядно в одной сроке видеть весь набор данных. Парсер реализует поддержку следующего синтаксиса URI:: +Источники (`sources`) и назначения (`targets`) должны быть указаны в виде +URI. Это позовляет наглядно в одной сроке видеть весь набор данных. Парсер +реализует поддержку следующего синтаксиса URI:: scheme:[//[username[:password]@]hostname[:port]]/[path]?[query]#[fragment] -Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация в отдельных ситуациях может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта. На текущий момент компоненты `query` и `fragment` не используются. +Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части +URI происходит верно, но интерпретация в отдельных ситуациях может отличаться. +См. примеры URI и реузультаты их интерпретации парсером в файле +`tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые +приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение +логики парсера необходимо, вы можете прислать правки в pull-реквесте или +завести feature-реквест в репозитории проекта. На текущий момент компоненты +`query` и `fragment` не используются. Примеры URI для массива `sources`:: @@ -79,19 +100,23 @@ boring-backup можно рассматривать как фреймворк и rsync://backup_user@192.168.3.12:2022/backups s3://my_bucket -Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. См. примеры кодирования строки на разных языках программирования ниже. +Пароли содержащие специальные символы недопустимые в URI (включая пробелы) +необходимо закодировать в percent code. См. примеры кодирования строки на +разных языках программирования ниже. Python 2:: - python2 -c "import urllib, sys; print urllib.quote(sys.argv[1], safe='')" 'PA$$WORD' + python2 -c "import urllib, sys; \ + print urllib.quote(sys.argv[1], safe='')" 'p@$$w0rd' Python 3:: - python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" 'PA$$WORD' + python3 -c "import urllib.parse, sys; \ + print(urllib.parse.quote(sys.argv[1], safe=''))" 'p@$$w0rd' Perl 5:: - echo 'PA$$WORD' | perl -MURI::Escape -wlne 'print uri_escape $_' + echo 'p@$$w0rd' | perl -MURI::Escape -wlne 'print uri_escape $_' Поддерживаемые протоколы и схемы URI ------------------------------------ @@ -99,13 +124,17 @@ Perl 5:: `````````````````````````````````````````````````` file - Может содержать путь к локальному файлу или директории. Файлы архивируются при помощи ``tar`` и по умолчанию не сжимаются. Cжатие архива может быть включено через переменную `compression`. Примеры:: + Может содержать путь к локальному файлу или директории. Файлы + архивируются при помощи ``tar`` и по умолчанию не сжимаются. Cжатие + архива может быть включено через переменную `compression`. Примеры:: /var/www/www-root/data file:/var/www/html file:///home/jhon/cool_stuff.txt - Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса. + Не используйте двойной слэш для этой схемы, используйте один или три + слэша. Двойной слэш означает наличие компонента Authority, это приводит + к неверной интерпретации адреса. См. также ``handler::tar`` @@ -114,17 +143,22 @@ mysql mysql://[username[:password]@]hostname[:port]/database - С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL. Файл по умолчанию не сжимается, но сжатие может быть включено через переменную `compression`. + С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL. Файл + по умолчанию не сжимается, но сжатие может быть включено через переменную + `compression`. См. также ``handler::mysqldump`` postgres - Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1) с расширением .psql. Файл по умолчанию не сжимается, но сжатие может быть включено через переменную `compression`. + Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется + ``pg_dump``\(1) с расширением .psql. Файл по умолчанию не сжимается, но + сжатие может быть включено через переменную `compression`. См. также ``handler::pg_dump`` sqlite - Схема для баз данных SQLite. Мало отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл. + Схема для баз данных SQLite. Мало отличается от `file`, добавлена для + наглядного обозначения, что источником является БД SQLite, а не иной файл. См. также ``handler::sqlite`` @@ -132,9 +166,21 @@ sqlite `````````````````````````````````````````````````` file - В контексте `targets` указывает директорию для сохранения бэкапов. В массиве `targets` обязательно должен быть хотя бы один поинт со схемой `file`. Этот поинт будет использован как основной и сохранён в переменные ``__main_target`` (содержит URI) и ``__main_target_path`` (содержит компонент URI path). Если в массиве присутствует несколько поинтов со схемой `file`, то в качестве основного будет выбран первый по порядку поинт. Все бэкапы первоначально будут сохраняться в директорию ``__main_target_path`` и затем копироваться в другой таргет с помощью соответствующего обработчика. В случае копировани из одной директории в другую используется утилита ``cp``\(1). + В контексте `targets` указывает директорию для сохранения бэкапов. В + массиве `targets` обязательно должен быть хотя бы один поинт со схемой + `file`. Этот поинт будет использован как основной и сохранён в переменные + ``__main_target`` (содержит URI) и ``__main_target_path`` (содержит + компонент URI path). Если в массиве присутствует несколько поинтов со + схемой `file`, то в качестве основного будет выбран первый по порядку + поинт. Все бэкапы первоначально будут сохраняться в директорию + ``__main_target_path`` и затем копироваться в другой таргет с помощью + соответствующего обработчика. В случае копировани из одной директории в + другую используется утилита ``cp``\(1). - Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно. + Избегайте указания в одном сценарии таргетов, которые ведут одновременно на + примонтированный к локальной машине сетевой диск и другое удалённое + хранилище. В таком случае архивы будут создаваться на сетевом диске и далее + снова копироваться по сети, что будет очень медленно. См. также ``handler::cp`` @@ -162,24 +208,48 @@ dav, davs Создание резервных копий ------------------------ -boring-backup предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. boring-backup также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup``, ``process_sources``, ``process_targets``. +boring-backup предполагает, что для всех резервных копий необходимо создавать +архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда +хватало дискового пространства для создания новых архивов. boring-backup также +не удаляет старые архивы и вам также надо позаботиться об удалении устаревших +резервных копий. Изменить это поведение можно с помощью пользовательских +функций в сценариях. В этом разделе речь пойдёт о поведении, которое +установлено по умолчанию. См. функции ``builtin_backup``, ``process_sources``, +``process_targets``. -Базовая концепция строится на том, что существует несколько источников и несколько точек назначения. Создаётся резервная копия источника и копируется в точку назначения. +Базовая концепция строится на том, что существует несколько источников и +несколько точек назначения. Создаётся резервная копия источника и копируется в +точку назначения. -Для всех источников в сценарии выполняется локальная резервная копия. После этого локальная копия переносится в удалённые точки назначения, если они заданы. Копирование локального бэкапа будет осуществлёно столько раз, сколько точек назначения задано. В каждом сценарии обязательно должен быть задан хотя бы один источник и одна точка назначения. При этом в списке точек назначения обязательно должна присутствовать точка со схемой `file`. Именно в неё будут сохранены архивы. +Для всех источников в сценарии выполняется локальная резервная копия. После +этого локальная копия переносится в удалённые точки назначения, если они +заданы. Копирование локального бэкапа будет осуществлёно столько раз, сколько +точек назначения задано. В каждом сценарии обязательно должен быть задан хотя +бы один источник и одна точка назначения. При этом в списке точек назначения +обязательно должна присутствовать точка со схемой `file`. Именно в неё будут +сохранены архивы. Например, имеется следующий сценарий:: sources=( - 'mysql://wordpress:1jobrRRjtLYs@localhost/wordpress' - 'file:///var/www/wordpress' + mysql://wordpress:1jobrRRjtLYs@localhost/wordpress + file:///var/www/wordpress ) targets=( - 'file:///var/backup' - 'ftp://jhon:%24t%D0%AFo%7C%5C%7C6@[fe80::5054:ff:fe24:382]:2021/backups/' + file:///var/backup + ftp://jhon:%24t%D0%AFo%7C%5C%7C6@[fe80::5054:ff:fe24:382]:2021/backups/ ) -Здесь будут созданы архивы файлов и базы данных и сохранены в локальную директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории /var/backup не будут удалены или перемещены. Если добавить дополнительную точку назначения, то файлы из /var/backup будут скопированы и туда. Обратите внимание, что boring-backup не выполняет повторного создания архивов для каждой точки назначения — архивы создаются один раз и далее распространяются по всем указанным назначениям. Если в массиве `targets` имеется несколько точек назначения со схемой `file`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные. +Здесь будут созданы архивы файлов и базы данных и сохранены в локальную +директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на +сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории +/var/backup не будут удалены или перемещены. Если добавить дополнительную точку +назначения, то файлы из /var/backup будут скопированы и туда. Обратите +внимание, что boring-backup не выполняет повторного создания архивов для каждой +точки назначения — архивы создаются один раз и далее распространяются по всем +указанным назначениям. Если в массиве `targets` имеется несколько точек +назначения со схемой `file`, то архивы будут сохранены в первую по порядку +точку, а затем скопированы оттуда в остальные. Резервное копирование на удалённое хранилище -------------------------------------------- @@ -204,12 +274,21 @@ WebDAV Переменные ---------- -``boring-backup`` условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными". +``boring-backup`` условно разделяет переменные на "внутренние" ("защищённые") и +"обычные". К "защищённым" переменным относятся все перемеменные, имена которых +начинаются с двух знаков подчёркивания, например: ``__main_target``. Все +остальные переменные считаются "обычными". -Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать. +Обычные переменные могут быть перезаписаны в пользовательском скрипте. +Защищённые переменные технически ничем от них не отличаются, однако не нужно +переопределять такие переменные в пользовательском скрипте, так как это может +привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень +внимательно нужно относится к перезаписи обычных переменных — в обоих случаях +есть риск что-то поломать. ``backups`` - Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`. + Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. + Заполняется функциями-обработчиками `sources`. | Тип: массив | Умолчание: () @@ -233,7 +312,8 @@ WebDAV | Умолчание: имя_скрипта\_ ``name`` - Соответствует имени архивируемой директории/файла полученного из `path` с помощью утилиты ``basename``\(1). + Соответствует имени архивируемой директории/файла полученного из `path` с + помощью утилиты ``basename``\(1). | Тип: строка | Умолчание: нет @@ -245,8 +325,9 @@ WebDAV | Умолчание: _%Y%m%d ``name_suffix`` - Суффикс, добавляемый к имени файла перед расширением. Строка интерпретируется утилитой ``date``. - + Суффикс, добавляемый к имени файла перед расширением. Строка + интерпретируется утилитой ``date``. + | Тип: строка | Умолчание: -%H%M @@ -269,8 +350,12 @@ WebDAV | Умолчание: нет ``compression`` - В контексте ``tar`` работа этой фичи базируется на опции ``tar`` ``--auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже. Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``. Если переменная пуста или не задана, то сжатие будет отключено. - + В контексте ``tar`` работа этой фичи базируется на опции ``tar`` + ``--auto-compress``. Переменная может принимать значения, в соответствии с + табилцей ниже. Если переменная имеет значение, отличное от перечисленныых, + то будет использован ``gzip``. Если переменная пуста или не задана, то + сжатие будет отключено. + | Тип: строка | Умолчание: нет @@ -299,26 +384,35 @@ WebDAV ------- ``backup`` - Пользовательская функция резервного копирования. Если она задана в скрипте, то вызывается вместо ``builtin_backup``. + Пользовательская функция резервного копирования. Если она задана в скрипте, + то вызывается вместо ``builtin_backup``. ``builtin_backup`` - Встроенная функция, запускает резервное копирвоание. Вызывает функции ``process_source`` и ``process_target``. + Встроенная функция, запускает резервное копирвоание. Вызывает функции + ``process_source`` и ``process_target``. ``err [-eao] MESSAGE`` - Печатает сообщение об ошибке MESSAGE на экран и в лог и выполняет обработку ошибок. + Печатает сообщение об ошибке MESSAGE на экран и в лог и выполняет обработку + ошибок. -e Выйти из скрипта с кодом выхода 1. -a Добавить сообщение MESSAGE в массив ``errors``. -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``. + Печатает полученное имя файла в STDOUT. Имя является выводом команды + ``date`` и строки ``${prefix}${name}${date_fmt}${name_ext}``. + См. переменные ``name_prefix``, ``name``, ``name_date_fmt``, ``name_ext``. ``try COMMAND`` - Функция выполняет команду COMMAND и в случае ненулевого кода выхода вызывает ``err()`` с ключами ``-eao``. Ошибка при выполнении COMMAND приведёт к вызову функции ``on_error``. Рекомендуется для использования в качестве обёртки для команд правильное выполнение которых критично. + Функция выполняет команду COMMAND и в случае ненулевого кода выхода + вызывает ``err()`` с ключами ``-eao``. Ошибка при выполнении COMMAND + приведёт к вызову функции ``on_error``. Рекомендуется для использования в + качестве обёртки для команд правильное выполнение которых критично. ``handler::tar URI`` Архивация файлов с помощью ``tar``. @@ -366,16 +460,22 @@ WebDAV Проверяет задана ли функция FUNCTION. ``log [-p] MESSAGE`` - Печатает лог в файл ``__log_file`` (лог задаётся опцией --log-file) и на экран, если указана опция ``-p``. Формат даты в логе можно изменить с помощью переменной ``log_date_fmt``. + Печатает лог в файл ``__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. + Парсер URI. Задаёт переменные ``scheme``, ``username``, ``password``, + ``hostname``, ``port``, ``path``, ``query``, ``fragment`` и выполняет + декодинг пароля, если он закодирован в percent code. ``prepare`` - Пользовательская функция. Если задана, то запускается до функции ``backup`` или ``builtin_backup``. + Пользовательская функция. Если задана, то запускается до функции ``backup`` + или ``builtin_backup``. ``process_source URI`` На основе схемы запускает соответсвующую функцию-обработчик. @@ -384,7 +484,11 @@ WebDAV На основе схемы запускает соответсвующую функцию-обработчик. ``source_script FILE`` - Выполняет ``source`` пользовательского скрипта и проверяет его корректность. Проверяется синтаксис Bash, наличие непустых массивов `sources` и `targets`, наличие поинта `file` в `targets`. Во вспомогательной функции ``validate_targets`` задаются значения переменных ``__main_target`` и ``__main_target_path``. + Выполняет ``source`` пользовательского скрипта и проверяет его + корректность. Проверяется синтаксис Bash, наличие непустых массивов + `sources` и `targets`, наличие поинта `file` в `targets`. Во + вспомогательной функции ``validate_targets`` задаются значения переменных + ``__main_target`` и ``__main_target_path``. Использование функций в сценариях --------------------------------- @@ -399,6 +503,7 @@ WebDAV См. также --------- -``bash``\(1), ``tar``\(1), ``cp``\(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