510 lines
24 KiB
ReStructuredText
510 lines
24 KiB
ReStructuredText
:Title: boring-backup
|
||
:Title upper: BORING-BACKUP
|
||
:Subtitle: backup files and databases
|
||
:Author: ge
|
||
:Copyright: \(C) 2022, ge <https://nixhacks.net/>, GPLv3+
|
||
:Date: 2022 May 15
|
||
:Manual section: 1
|
||
:Version: boring-backup 0.1.0
|
||
|
||
Синопсис
|
||
--------
|
||
|
||
``boring-backup`` [-cvlphV] FILES..
|
||
|
||
Описание
|
||
--------
|
||
|
||
boring-backup - это расширяемая утилита для резервного копирования на основе
|
||
сценариев Bash.
|
||
|
||
Опции
|
||
-----
|
||
|
||
-c, --config config file.
|
||
-v, --verbose verbose output.
|
||
-l, --log-file log file.
|
||
-p, --pid-file PID file.
|
||
-h, --help print this help messagea and exit.
|
||
-V, --version print version and exit.
|
||
|
||
Быстрый старт
|
||
-------------
|
||
|
||
boring-backup можно рассматривать как фреймворк или библиотеку для создания
|
||
сценариев резервного копирования. Сценарии должны содержать валидный код на
|
||
Bash. Сценарий импортируется в основной скрипт с помощью команды ``source``
|
||
(см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
|
||
|
||
Простейший сценарий резервного копирования выглядит следующим образом::
|
||
|
||
sources=(file:/home/user)
|
||
targets=(file:/var/backup)
|
||
|
||
Здесь массивы `sources` и `targets` определяют точки, они же поинты (`points`)
|
||
резервного копирования: источники (`sources`) и назначения (`targets`). Это
|
||
основные сущности, с которыми работает boring-backup. Вот некоторые особенности
|
||
поинтов:
|
||
|
||
- Все поинты указываются в формате URI.
|
||
- Поинты могут указывать как на локальные (размещённые на текущей машине), так
|
||
и на удалённые (размещённые на удалённой машине) ресурсы.
|
||
- Можно указать как несколько источников, так и несколько назначений.
|
||
|
||
Для выполнения бэкапа директорий или отдельных файлов применяется схема 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}
|
||
|
||
Описание переменных см. в разделе ПЕРЕМЕННЫЕ. Пример имени файла::
|
||
|
||
example.sh_example_2022.05.15-0953.tar
|
||
|
||
Обзор 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 для массива `sources`::
|
||
|
||
mysql://wordpress:1jobrRRjtLYs@localhost/wordpress
|
||
postgres://django:9%3F2%3D%40gHW@localhost:5432:/django
|
||
sqlite:///var/www/app/data/database.db
|
||
file:///var/www/html/
|
||
|
||
Примеры URI для `targets`::
|
||
|
||
file:/var/backup
|
||
ftp://jhon:%24t%D0%AFo%7C%5C%7C6@[fe80::5054:ff:fe24:382]:2021/backups/
|
||
rsync://backup_user@192.168.3.12:2022/backups
|
||
s3://my_bucket
|
||
|
||
Пароли содержащие специальные символы недопустимые в URI (включая пробелы)
|
||
необходимо закодировать в percent code. См. примеры кодирования строки на
|
||
разных языках программирования ниже.
|
||
|
||
Python 2::
|
||
|
||
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=''))" 'p@$$w0rd'
|
||
|
||
Perl 5::
|
||
|
||
echo 'p@$$w0rd' | perl -MURI::Escape -wlne 'print uri_escape $_'
|
||
|
||
Поддерживаемые протоколы и схемы URI
|
||
------------------------------------
|
||
Схемы, которые могут быть использованы как sources
|
||
``````````````````````````````````````````````````
|
||
|
||
file
|
||
Может содержать путь к локальному файлу или директории. Файлы
|
||
архивируются при помощи ``tar`` и по умолчанию не сжимаются. Cжатие
|
||
архива может быть включено через переменную `compression`. Примеры::
|
||
|
||
/var/www/www-root/data
|
||
file:/var/www/html
|
||
file:///home/jhon/cool_stuff.txt
|
||
|
||
Не используйте двойной слэш для этой схемы, используйте один или три
|
||
слэша. Двойной слэш означает наличие компонента Authority, это приводит
|
||
к неверной интерпретации адреса.
|
||
|
||
См. также ``handler::tar``
|
||
|
||
mysql
|
||
URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат::
|
||
|
||
mysql://[username[:password]@]hostname[:port]/database
|
||
|
||
С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL. Файл
|
||
по умолчанию не сжимается, но сжатие может быть включено через переменную
|
||
`compression`.
|
||
|
||
См. также ``handler::mysqldump``
|
||
|
||
postgres
|
||
Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется
|
||
``pg_dump``\(1) с расширением .psql. Файл по умолчанию не сжимается, но
|
||
сжатие может быть включено через переменную `compression`.
|
||
|
||
См. также ``handler::pg_dump``
|
||
|
||
sqlite
|
||
Схема для баз данных SQLite. Мало отличается от `file`, добавлена для
|
||
наглядного обозначения, что источником является БД SQLite, а не иной файл.
|
||
|
||
См. также ``handler::sqlite``
|
||
|
||
Схемы, которые могут быть использованы как targets
|
||
``````````````````````````````````````````````````
|
||
|
||
file
|
||
В контексте `targets` указывает директорию для сохранения бэкапов. В
|
||
массиве `targets` обязательно должен быть хотя бы один поинт со схемой
|
||
`file`. Этот поинт будет использован как основной и сохранён в переменные
|
||
``__main_target`` (содержит URI) и ``__main_target_path`` (содержит
|
||
компонент URI path). Если в массиве присутствует несколько поинтов со
|
||
схемой `file`, то в качестве основного будет выбран первый по порядку
|
||
поинт. Все бэкапы первоначально будут сохраняться в директорию
|
||
``__main_target_path`` и затем копироваться в другой таргет с помощью
|
||
соответствующего обработчика. В случае копировани из одной директории в
|
||
другую используется утилита ``cp``\(1).
|
||
|
||
Избегайте указания в одном сценарии таргетов, которые ведут одновременно на
|
||
примонтированный к локальной машине сетевой диск и другое удалённое
|
||
хранилище. В таком случае архивы будут создаваться на сетевом диске и далее
|
||
снова копироваться по сети, что будет очень медленно.
|
||
|
||
См. также ``handler::cp``
|
||
|
||
ftp
|
||
Не реализовано.
|
||
|
||
sftp
|
||
Не реализовано.
|
||
|
||
rsync
|
||
Не реализовано.
|
||
|
||
s3
|
||
Не реализовано.
|
||
|
||
swift
|
||
Не реализовано.
|
||
|
||
sj
|
||
Не реализовано.
|
||
|
||
dav, davs
|
||
Не реализовано.
|
||
|
||
Создание резервных копий
|
||
------------------------
|
||
|
||
boring-backup предполагает, что для всех резервных копий необходимо создавать
|
||
архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда
|
||
хватало дискового пространства для создания новых архивов. boring-backup также
|
||
не удаляет старые архивы и вам также надо позаботиться об удалении устаревших
|
||
резервных копий. Изменить это поведение можно с помощью пользовательских
|
||
функций в сценариях. В этом разделе речь пойдёт о поведении, которое
|
||
установлено по умолчанию. См. функции ``builtin_backup``, ``process_sources``,
|
||
``process_targets``.
|
||
|
||
Базовая концепция строится на том, что существует несколько источников и
|
||
несколько точек назначения. Создаётся резервная копия источника и копируется в
|
||
точку назначения.
|
||
|
||
Для всех источников в сценарии выполняется локальная резервная копия. После
|
||
этого локальная копия переносится в удалённые точки назначения, если они
|
||
заданы. Копирование локального бэкапа будет осуществлёно столько раз, сколько
|
||
точек назначения задано. В каждом сценарии обязательно должен быть задан хотя
|
||
бы один источник и одна точка назначения. При этом в списке точек назначения
|
||
обязательно должна присутствовать точка со схемой `file`. Именно в неё будут
|
||
сохранены архивы.
|
||
|
||
Например, имеется следующий сценарий::
|
||
|
||
sources=(
|
||
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/
|
||
)
|
||
|
||
Здесь будут созданы архивы файлов и базы данных и сохранены в локальную
|
||
директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на
|
||
сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории
|
||
/var/backup не будут удалены или перемещены. Если добавить дополнительную точку
|
||
назначения, то файлы из /var/backup будут скопированы и туда. Обратите
|
||
внимание, что boring-backup не выполняет повторного создания архивов для каждой
|
||
точки назначения — архивы создаются один раз и далее распространяются по всем
|
||
указанным назначениям. Если в массиве `targets` имеется несколько точек
|
||
назначения со схемой `file`, то архивы будут сохранены в первую по порядку
|
||
точку, а затем скопированы оттуда в остальные.
|
||
|
||
Резервное копирование на удалённое хранилище
|
||
--------------------------------------------
|
||
FTP
|
||
```
|
||
SFTP
|
||
````
|
||
Rsync over SSH
|
||
``````````````
|
||
Rsync with rsyncd
|
||
`````````````````
|
||
Amazon S3
|
||
`````````
|
||
S3 compatible storage
|
||
`````````````````````
|
||
OpenStack Swift
|
||
```````````````
|
||
Storj DCS
|
||
`````````
|
||
WebDAV
|
||
``````
|
||
Переменные
|
||
----------
|
||
|
||
``boring-backup`` условно разделяет переменные на "внутренние" ("защищённые") и
|
||
"обычные". К "защищённым" переменным относятся все перемеменные, имена которых
|
||
начинаются с двух знаков подчёркивания, например: ``__main_target``. Все
|
||
остальные переменные считаются "обычными".
|
||
|
||
Обычные переменные могут быть перезаписаны в пользовательском скрипте.
|
||
Защищённые переменные технически ничем от них не отличаются, однако не нужно
|
||
переопределять такие переменные в пользовательском скрипте, так как это может
|
||
привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень
|
||
внимательно нужно относится к перезаписи обычных переменных — в обоих случаях
|
||
есть риск что-то поломать.
|
||
|
||
``backups``
|
||
Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам.
|
||
Заполняется функциями-обработчиками `sources`.
|
||
|
||
| Тип: массив
|
||
| Умолчание: ()
|
||
|
||
``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
|
||
|
||
``name_suffix``
|
||
Суффикс, добавляемый к имени файла перед расширением. Строка
|
||
интерпретируется утилитой ``date``.
|
||
|
||
| Тип: строка
|
||
| Умолчание: -%H%M
|
||
|
||
``name_ext``
|
||
Расширение имени файла, соответствующее формату архива.
|
||
|
||
| Тип: строка
|
||
| Умолчание: .tar.gz
|
||
|
||
``tar_options``
|
||
Опции ``tar``. См. ``tar``\(1).
|
||
|
||
| Тип: строка
|
||
| Умолчание: -acf
|
||
|
||
``tar_exclude``
|
||
Список имён для опции ``tar`` ``--exclude``.
|
||
|
||
| Тип: массив
|
||
| Умолчание: нет
|
||
|
||
``compression``
|
||
В контексте ``tar`` работа этой фичи базируется на опции ``tar``
|
||
``--auto-compress``. Переменная может принимать значения, в соответствии с
|
||
табилцей ниже. Если переменная имеет значение, отличное от перечисленныых,
|
||
то будет использован ``gzip``. Если переменная пуста или не задана, то
|
||
сжатие будет отключено.
|
||
|
||
| Тип: строка
|
||
| Умолчание: нет
|
||
|
||
==================== ================ ========
|
||
Значение 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
|
||
==================== ================ ========
|
||
|
||
Функции
|
||
-------
|
||
|
||
``backup``
|
||
Пользовательская функция резервного копирования. Если она задана в скрипте,
|
||
то вызывается вместо ``builtin_backup``.
|
||
|
||
``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``. Ошибка при выполнении COMMAND
|
||
приведёт к вызову функции ``on_error``. Рекомендуется для использования в
|
||
качестве обёртки для команд правильное выполнение которых критично.
|
||
|
||
``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.
|
||
|
||
``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``.
|
||
|
||
Использование функций в сценариях
|
||
---------------------------------
|
||
Переменные окружения
|
||
--------------------
|
||
|
||
``LIBRARY``
|
||
Путь до библиотеки функций boring-backup.
|
||
|
||
Примеры
|
||
-------
|
||
См. также
|
||
---------
|
||
|
||
``bash``\(1), ``tar``\(1), ``cp``\(1), ``date``\(1), ``mysqldump``\(1),
|
||
``pg_dump``\(1)
|
||
|
||
RFC 3986 https://datatracker.ietf.org/doc/html/rfc3986
|