=encoding utf-8

=head1 NAME

mbutiny - утилита резервного копирования ваших сайтов и других элементов файловой системы

=head1 CONFIGURATION

Перед конфигурацией следует пройти процедуру инициализации, она достаточно проста:

    # sudo mbutiny configure

Процесс инициализации активирует работу приложения mbutiny (далее просто mbutiny). Это приложение
является интерфейсом системной оболочки и предоставляет доступ к функциональным
возможностям модуля App::MBUtiny.

В процессе инициализации будут созданы необходимые директории и конфигурационные файлы.

Если Вы желаете устанавливать конфигурационные файлы в свой каталог, то следует запустить
инициализатор с ключем -c /my/path/for/mbutiny.conf:

    # sudo mbutiny -c -c /my/path/for/mbutiny.conf configure

Данная инструкция "развернет" конфигурационные файлы в каталоге /my/path/for/

Главным конфигурационным файлом является файл mbutiny.conf. Он содержит глобальные определения и
определяет какие дополнительные файлы будут прочитаны и использоваться. Файл collector.cgi.sample
содержит в себе пример скрипта коллектора (о нем см. раздел L<App::MBUtiny/COLLECTOR>).

Файлы hosts/*.conf содержат определения хостов MBUtiny. Файл hosts/foo.conf.sample
является своим образом образцом того, как выглядит работающий хост.

Хост - это условный термин, определящий набор правил резервного копирования объявленных объектов.
Файл хоста состоит из отдельных опредлений и блоков (секций). Некоторые блоки могут быть указаны
в количестве более чем один, об этом будет сказано ниже.

Объекты - это файлы и папки, которые будут подвержены резервному копированию

=head2 mbutiny.conf

Как уже упоминалось выше, файл mbutiny.conf содержит глобальные определения.

    BUday    3

BUday определяет количество ежедневных архивов. Это количество хранимых последних ежедневных архивов

    BUweek   3

BUweek определяет количество еженедельных архивов. Это Количество хранимых последних еженедельных
архивов. Еженедельными архивами считаются те ежедневные архивы, которые были созданы в воскресенье.

    BUmonth  3

BUmonth определяет количество ежемесячных архивов. Это Количество хранимых последних ежемесячных
архивов. Ежемесячными архивами считаются те ежедневные архивы, которые были созданы первого числа
каждого месяца.

    Require foo bar baz quux

Require директива задает список имен хостов, являющимся обязательным (ожидаемых) для проверки с помощью
команды получения отчета - mbutiny report

По умолчанию обязательные хосты не определены и по ним не будет формироваться отчет

    LogEnable   on
    LogEnable   off

Директива позволяет включить или выключить логирование процессов mbutiny. По умолчанию - off

    LogLevel warning

Директива определяет уровень отладки. Существует следующий набор уровней отладки: debug, info,
notice, warning, error, crit, alert, emerg, fatal, except. По умолчанию используется значение debug

    LogFile /var/log/mbutiny.log

По умолчанию всю отладочную информацию mbutiny записывает в syslog, но есть возможноть использовать в качетсве лога
файл mbutiny.log системного каталога журнальных файлов

Следует учесть, что для записи данных в лог необходимо наличие ключа -l в командной строке запуска mbutiny

    SendReport      yes
    SendReport      no

Директива SendReport указывает, что после выполнения операций резервного копирования и тестирования
необходимо отправить детальный отчет на адрес электронной почты, определенный в секции <SendMail>

    SendErrorReport yes
    SendErrorReport no

Данная директива заставляет отправлять отчеты о работе только в момент возникновения каких либо
ошибок, связанным с некорректной работой процесса резервного копирования или тестирования.
По умолчанию - no

    <SendMail>
      ...
    </SendMail>

Настройки программы отправки почты выполняются в секции SendMail. Эта секция содержит адрес адресата и отправителя,
а также иные параметры почты

    <Arc>
        ext         .tar.gz
        create      tar -cpf \"[NAME].tar\" [LIST]
        append      tar -rpf \"[NAME].tar\" [LIST]
        postprocess gzip \"[NAME].tar\"
        extract     tar -zxpf \"[FILE]\" -C \"[DIRDST]\"
    </Arc>

Секция работы с архивами. Подробное описание см. в модуле L<CTK>.

В этой секции определяются основные настройки работы с архивами, каждое значение любого параметра
обрабатывается единым механизмом обработки маски. Ключи в маске могут быть использованы следующие:

Для случая сжатия файлов используется следеющий набор ключей:

    NAME     -- Имя архива (без расширения)
    FILE     -- Имя архива (с расширением)
    EXT      -- Расширение архива
    LIST     -- Список файлов для сжатия, через пробел

Для случая извлечения файлов из арива:

    FILE     -- Имя архива (с расширением)
    DIRDST   -- Каталог для исзвлечения содержимого архивов
    DIROUT   -- = DIRDST

Работа с коллектором определяется множетвом секций Collector:

    <Collector>
        URL         https://user:password@collector.example.com/collector.cgi
        Comment     Collector said blah-blah-blah # Optional for collector
        TimeOut    180
    </Collector>

Блок содержит URL коллектора, комментария для сохранения на нем и таймаутом операций с коллектором

Этот блок может быть определен как в этом файле, так и в файлах определения хостов

    # MySQL example:
    <DBI>
        DSN "DBI:mysql:database=mbutiny;host=mysql.example.com"
        User username
        Password password
        Set RaiseError          0
        Set PrintError          0
        Set mysql_enable_utf8   1
    </DBI>

Секция DBI определяет настройки для соединения с базой данных локального коллектора

Поддерживаются базы: MySQL, PostgreSQL, SQLite, Oracle и некоторые другие SQL базы данных

=head2 hosts/foo.conf

Файлы каталога host/*.conf содержат определения дла хостов. Каждый файл *.conf должен
определяться блоком <Host name>...</Host>. Где name - уникальное имя хоста. Имя хоста принято
выбирать таким образом, чтобы оно подсказывало на тот тип и группу объектов, которые подверглись
резервному копированию. Помимо этого уникальность обеспечивает стабильность работы коллектора, если
Вы используете его для работы.

    Enable      yes
    Enable      no

Включение или выключение хоста. Аттрибут влияет на обработку хоста. Если атрибут установлен, то
обработка хоста выполнится, иначе хост игнорируется. По умолчанию хост игнорируется. Но следует
заметить, что наличие в секции <Host name>...</Host> директивы Enable обязательно! Иначе, возможны
ошибки в обработке других хостов.

    SendReport  no
    SendErrorReport yes

Директивы управляют отправкой отчетов в рамках данного хоста. Данные для отправки берутся из
внутренней секции <SendMail>...</SendMail> или, если не указана данная внутренняя секция, из
файла mbutiny.conf, описанного выше.

    ArcMask [HOST]-[YEAR]-[MONTH]-[DAY][EXT]

Маска файлов архивов. ArcMask указывает на то, по какому формату (маске) хранить архив
результативного бэкапа. Маски файлов могут иметь сложный вид, но по умолчанию используется маска
вида: [HOST]-[YEAR]-[MONTH]-[DAY][EXT]

Ключи маски могут быть использованы следующие:

    DEFAULT  -- Значение соответствующее формату [HOST]-[YEAR]-[MONTH]-[DAY][EXT]
    HOST     -- Имя секции хоста
    YEAR     -- Год создания архива
    MONTH    -- Месяц создания архива
    DAY      -- День создания архива
    EXT      -- Расширение файла архива
    TYPE     -- Тип архива

Настоятельно советуем выбирать маску таким образом, чтобы при строковом сравнении даты создания
файлов были "выровнены" относительно дат, определенные ключами. Это условние исключит возможные
проблемы при автоматическом определении последне-созданных архивов. По умолчанию в качестве
разделителей полей маски используется знак тире. когда как в практике зачастую применяется следующая
маска: [HOST].[YEAR][MONTH][DAY].[EXT]
Но несмотря на это мы рекомендуем использовать маску по умолчанию, вида:

    ArcMask [DEFAULT]

Параметры количеств хранимых архивов BUday, BUweek и BUmonth были описаны в файле глобальных
определений mbutiny.conf. По умолчанию используются следующие предустановленные значения:

    BUday       3
    BUweek      3
    BUmonth     3

В случае, если данные директивы будут опущены, то программа mbutiny использует значения из
одноименных глобальных определений.

    Trigger mkdir /tmp/test
    Trigger echo foo > /tmp/test/foo.txt

Триггеры. Это команды, выполняющиеся до того как будет сформирован конечный список обрабатываемых
объекстов (файлов и папок). Триггеры выполняются один за другим, но порядок их выполнения является
неопределнным. Для соблюдения требуемого порядкя следует использовать сложные команды или выносить
их в отдельные внешние скрипты.

    Trigger mysqldump -f -h mysql.host.com -u user --port=3306 --password=password \
            --add-drop-table --default-character-set=utf8 \
            --databases databasename > /tmp/test/databasename.sql

Данный пример иллюстрирует то как можно получать объект для резервного копирования в виде дампа
небольшой базы данных. Это и есть способ резервного копирования баз данных.

    Object /tmp/test/foo.txt
    Object /tmp/test/databasename.sql

или

    Object /tmp/test

Директива Object указывает, какие файлы и папки необходимо архивировать для создания резервной
копии.

    <Exclude "exclude_sample">
         # Отсюда берутся сами исходные файлы. Директива может быть только одна
         Object /usr/local/etc

         # Опционально. Сюда копируются объекты для дальнейшего сжатия. Директива не обязательна
         Target /tmp/test_exclude_sample

         # Относительные пути файлов и папок которые НЕ СЛЕДУЕТ кописаровать в каталог Target
         Exclude bar.txt
         Exclude baz.txt
    </Exclude>

Секции эксклюзивного копирования объектов, Их может быть задано несколько. Секции позволяют
копировать файлы и папки каталога указанного в директиве Object в целевой каталог определенный
с поощью директивы Target. Копирование происходит всей структуры исходного каталога в целевой
каталог исключая объекты, указанные во внутренних директивах Exclude. Данный способ создания
объектов требует дополнительного свободного места на диске.

Следует заметить, что значение директивы Target будет автоматически добавлено в список объектов
что не обеспечивают триггеры. Для каждого триггера (см. описание выше) нужно указывать свой объект
с помощью директивы Object, как это иллюстрируется в приведнном примере. Говоря о примере, следует
прокоментировать: первым шагом создается каталог /tmp/test, затем в каталог /tmp/test пишется
файл foo.txt с содержимым foo. Для того, чтобы сделать резервную копию файла /tmp/test/foo.txt
необходимо указать в качестве объекта либо сам файл /tmp/test/foo.txt либо всю папку /tmp/test.
Таким образом происходит связка триггеров с объектами.

    <Collector>
        URL        https://user:password@collector.example.com/mbutiny
        Comment    "My comment"
        TimeOut    180
    </Collector>

Данная секция определяет коллектор. Таких секций может быть несколько в рамках данного хоста.
Здесь URL - Адрес до хранилища (коллектора). Логин и пароль HTTP авторизации указывается
в теле URL. TimeOut - Таймаут. По умолчанию 180 секунд.

    <Local>
        FixUP       off
        Localdir    C:\\Temp\\mbutimy-local1
        Localdir    C:\\Temp\\mbutimy-local2
        #Comment    Local said blah-blah-blah for collector # Optional for collector
    </Local>

Секций <Local>...</Local> может быть несколько. Секция определяет
параметры локального хранилища, это хранилище не является надежным, если его точка монтирования не
является внешней относительно данного сервера. Секция <Local>...</Local> содержит следующие директивы:

Localdir - папка локального хранилища. Именно в нее будут помещены результативные архивы
(резервные копии). Данных директив Localdir может быть несколько, тогда произойдёт копирование
бэкапа в различные локальные хранилища.

FixUP - Указывает выполнять фиксацию результата работы на коллекторе. может быть значение on или off

Comment - Комментарий для коллектора. Полезен для мониторинга и отладки. Настоятельно рекомендуем
не оставлять данную директиву пустой.

    <FTP>
        FixUP       on
        URL         ftp://user:password@example.com:21/path/to/backup/dir1
        URL         ftp://user:password@example.com:21/path/to/backup/dir2
        Set         Passive 1
        Set         Debug 1
        Comment     FTP storage said blah-blah-blah # Optional for collector
    </FTP>

Секция <FTP>...</FTP> определяет параметры удаленного FTP-хранилища. <FTP> секций может быть
несколько в рамках данного хоста. В этом случае выполнится работа над каждым из указанных
FTP-хранилищ. Директивы URL - определяют расположения хранилищ, когда как директивы FixUP и Comment
аналогичны по значению секции <Local>...</Local>. Директива Set устанавливает атрибуты соединения FTP

    <HTTP>
        FixUP      on
        URL        https://user:password@collector.example.com/mbuserver
        Comment    HTTP said blah-blah-blah for collector # Optional for collector
        TimeOut    180
    </HTTP>

Секция <HTTP>...</HTTP> определяет параметры удаленного HTTP-хранилища. Секций <HTTP> может быть
несколько. В этом случае выполнится работа над каждым HTTP-хранилищем. Не следует путать с
коллектором, секция <HTTP>...</HTTP> определяет отдельный канал для "заливки" файлов, когда как
коллектор регистрирует результат заливки. Хотя как правило и коллектор и хранилище HTTP находятся на
одном физическом сервере. URL - Адрес до хранилища (как и коллектора). FixUP - Указывает
выполнять фиксацию результата работы на коллекторе. Может аналогично FTP и Local секциям принимать
значения on или off. Следует учитывать, что параметры для коллектора фиксапа задаются отдельной
секцией самого коллектора, т.к. файлы могут хранится на одном коллекторе а данные о статусе на
другом. TimeOut - таймаут. По умолчанию 180 секунд. Следует задавать если размер бэкапа существенно
большой, и файл не успевает пройти за дефолтное значение параметра.

    <SFTP>
        FixUP       on
        URL         sftp://user@example.com:22/path/to/backup/dir1
        URL         sftp://user@example.com:22/path/to/backup/dir2
        Set         key_path  /path/to/private/file.key
        Comment     SFTP storage said blah-blah-blah # Optional for collector
    </SFTP>

Секция <SFTP>...</SFTP> определяет параметры удаленного SFTP-хранилища. Секций <SFTP> может быть
несколько. В этом случае выполнится работа над каждым SFTP-хранилищем. Значения директив секции
аналогичны директивам секции <FTP>

    <Command>
        FixUP       on
        test        "test -d ./mbucmd  && ls -1 ./mbucmd || mkdir ./mbucmd"
        put         "cp [FILE] ./mbucmd/[NAME]"
        get         "cp ./mbucmd/[NAME] [FILE]"
        del         "test -e ./mbucmd/[NAME] && unlink ./mbucmd/[NAME] || true"
        list        "ls -1 ./mbucmd"
        comment     Command storage said blah-blah-blah # Optional for collector
    </Command>

<Command> секция определяет особый вид хранилищей - командный. Этот тип подразумевает выполнение
системной команды для выполнения функций хранилища. Секций <Command> может быть
несколько. В этом случае выполнится работа над каждым Command-хранилищем.

=head1 HISTORY

See C<Changes> file

=head1 DEPENDENCIES

L<CTK>

=head1 TO DO

See C<TODO> file

=head1 BUGS

* none noted

=head1 SEE ALSO

L<App::MBUtiny>

=head1 AUTHOR

Serż Minus (Sergey Lepenkov) L<http://www.serzik.com> E<lt>abalama@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 1998-2019 D&D Corporation. All Rights Reserved

=head1 LICENSE

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See C<LICENSE> file and L<https://dev.perl.org/licenses/>

=cut
