ge/boring_backup
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

feat: Update man

Browse Source
This commit is contained in:
ge 2022-05-15 11:41:15 +03:00
parent c37ee0de66
commit aa316a3eca
1 changed files with 209 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

270
docs/baf.1.rst
View File

@ -2,66 +2,60 @@
baf baf
=== ===
---------------------------------- ---------------------------
backup automation micro-framework. backup files and databases.
---------------------------------- ---------------------------
:Author: ge
:Copyright: \(C) 2022, ge <https://nixhacks.net/>, GPLv3+ :Copyright: \(C) 2022, ge <https://nixhacks.net/>, GPLv3+
:Date: 2022 May 15
:Manual section: 1 :Manual section: 1
:Version: baf 0.0.1
Синопсис Синопсис
-------- --------
``baf`` [options] [<arguments>] ``baf`` [-cvlhV] FILE..
Описание Описание
-------- --------
Baf это утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание полных резервных копий файлов и баз данных MySQL и PostgreSQL, но функционал может быть расширен в сценариях при помощи пользовательских функций. Baf (Backup Automation Micro-framework) - это расширяемая утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание резервных копий файлов с помощью ``tar`` и дампов баз данных MySQL/MariaDB и PostgreSQL.
Опции Опции
----- -----
-h, --help print help text and exit. -c, --config config file.
-v, --version print version and exit. -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 требует написания сценария для выполнения бэкапа. В сценариях можно использовать переменные и функции. Сценарий импортируется в основной скрипт с помощью команды ``source`` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
В сценариях можно использовать переменные и функции. Сценарий импортируется Baf с помощью команды `source` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
Простейший сценарий резервного копирования выглядит следующим образом:: Простейший сценарий резервного копирования выглядит следующим образом::
sources=('file:/home/user') sources=('file:/home/user')
targets=('file:/var/backup') 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. Имя архива будет сложено из строки:: Для выполнения бэкапа директорий или отдельных файлов применяется схема 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}`` example.sh_example_20220515-0953.tar.gz
Переменная, значение которой соответствует имени файла сценария (без расширения).
``${name}``
Имя архивируемой директории/файла (``basename``\(1)).
``%Y%m%d-%H%M``
Дата, интерпретируемая утилитой ``date``\(1).
``${file_ext}``
Расширение имени файла, соответствующее формату архива. По умолчанию ".tar.gz".
Обзор URI Обзор URI
--------- ---------
@ -70,7 +64,7 @@ Baf не реализует собственный язык сценариев,
scheme:[//[username[:password]@]hostname[:port]]/[path]?[query]#[fragment] 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`:: Примеры URI для массива `sources`::
@ -86,7 +80,7 @@ Baf не реализует собственный язык сценариев,
rsync://backup_user@192.168.3.12:2022/backups rsync://backup_user@192.168.3.12:2022/backups
s3://my_bucket s3://my_bucket
Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. См. примеры кодирования строки на разных языках программирования ниже.
Python 2:: Python 2::
@ -102,7 +96,6 @@ Perl 5::
Поддерживаемые протоколы и схемы URI Поддерживаемые протоколы и схемы URI
------------------------------------ ------------------------------------
Схемы, которые могут быть использованы как sources Схемы, которые могут быть использованы как sources
`````````````````````````````````````````````````` ``````````````````````````````````````````````````
@ -111,51 +104,65 @@ file
file:/var/www/html file:/var/www/html
file:///home/jhon/cool_stuff.txt file:///home/jhon/cool_stuff.txt
Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса.
См. также ``backup_files()``
mysql mysql
URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат:: URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат::
mysql://[username[:password]@]hostname[:port]/database mysql://[username[:password]@]hostname[:port]/database
С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``. С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``.
См. также ``backup_mysql()``
postgres postgres
Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением ".psql.gz". Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением .psql.gz.
См. также ``backup_postgres()``
sqlite sqlite
Схема для баз данных SQLite. Ничем не отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл. Схема для баз данных SQLite. Ничем не отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл.
См. также ``backup_sqlite()``
Схемы, которые могут быть использованы как targets Схемы, которые могут быть использованы как targets
`````````````````````````````````````````````````` ``````````````````````````````````````````````````
file file
См. описание выше. В контексте `targets` указывает директорию для сохранения архивов с файлами и базами данных. В контексте `targets` указывает директорию для сохранения бэкапов. В массиве `targets` обязательно должен быть хотя бы один поинт со схемой `file`. Этот поинт будет использован как основной и сохранён в переменные ``__main_target`` (содержит URI) и ``__main_target_path`` (path). Если в массиве присутствует несколько поинтов со схемой `file`, то в качестве основного будет выбран первый по порядку поинт. Все бэкапы первоначально будут сохраняться в директорию ``__main_target_path`` и затем копироваться в другой таргет с помощью соответствующего обработчика. В случае копировани из одной директории в другую используется утилита ``cp``\(1).
Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно.
См. также ``transfer_files()``
ftp ftp
Для выполнения загрузки файлов на удалённый FTP-сервер используется утилита GNU ``ftp``\(1). Не реализовано.
sftp sftp
OpenSSH File Transfer Protocol. Не реализовано.
rsync rsync
Rsync. Не реализовано.
s3 s3
Amazon S3 or any S3-compatible storage. Не реализовано.
swift swift
OpenStack Swift. Не реализовано.
sj sj
Storj DCS. Не реализовано.
dav, davs 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`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные. Здесь будут созданы архивы файлов и базы данных и сохранены в локальную директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории /var/backup не будут удалены или перемещены. Если добавить дополнительную точку назначения, то файлы из /var/backup будут скопированы и туда. Обратите внимание, что Baf не выполняет повторного создания архивов для каждой точки назначения — архивы создаются один раз и далее распространяются по всем указанным назначениям. Если в массиве `targets` имеется несколько точек назначения со схемой `file`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные.
Потребление ресурсов
--------------------
Избегайте указания в одном сценарии точек назначения, которые ведут на примонтированный к локальной машине сетевой диск и другое удалённое хранилище одновременно. В таком случае архивы будут создаваться сразу на сетевом диске, что может существенно замедлить скорость их создания. Также при копировании файлов в другое удалённое хранилище будет выполняться двойная работа по сети, что тоже будет очень медленным.
Резервное копирование на удалённое хранилище Резервное копирование на удалённое хранилище
-------------------------------------------- --------------------------------------------
FTP FTP
@ -201,29 +203,175 @@ WebDAV
`````` ``````
Переменные Переменные
---------- ----------
Baf условно разделяет переменные на "внутренние" ("защищённые") и "общие". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "общими".
Общие переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи общих переменных — в обоих случаях есть риск что-то поломать. Baf условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными".
``__log_file`` Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать.
Путь до файла лога.
``__main_target`` ``backups``
Главный `target` для хранения локальных резервных копий. Эта переменная содержит первый по порядку URI со схемой `file` из массива `targets`. Директория (`path`) из этой точки используется в качестве буфферной, если в `targets` указаны дополнительные точки. Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`.
``__source_handler`` Умолчание: ()
Содержит имя функции, которая будет обрабатывать URI из `sources`.
``__target_handler`` ``errors``
Аналогично ``__source_target``, но для `targets`. Массив с текстами ошибок. Заполняется функцией ``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 RFC 3986 https://datatracker.ietf.org/doc/html/rfc3986