boring_backup/docs/boring-backup.ru.1.rst

: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