Version 1.06

СОДЕРЖАНИЕ

КОРОТКО О ПРОЕКТЕ

App::MBUtiny - готовое решение для работы с резервными копиями ваших сайтов, баз данных и просто данных на жестком диске. App::MBUtiny создан как продолжение развития двух ранних проектов - mbu и mbutiny.

ВОЗМОЖНОСТИ

ЗАВИСИМОСТИ

Перед началом установки, Вам необходимо проверить наличие следующих пакетов, установленных в Вашей системе где будет "работать" App::MBUtiny:

Если Вы планируете использовать коллектор, то для работы потребуется наличие WEB сервера Apache 2.2 или выше. Сервер должен быть настроен на выполнение CGI (perl) скриптов.

УСТАНОВКА

Установка выполняется двумя путями. Первый - автоматизированный; второй - ручной.

В автоматизированном режиме для установки достаточно выполнить команду:

# cpan install App::MBUtiny

или (для ActivePerl):

# ppm install App-MBUtiny

В ручном режиме Вам потребуется выполнить следующий набор операций:

Скачать дистрибутив с CPAN или официальный релиз с сайта SourceForge:

Разархивировать полученный архив, и перейти в извлеченную папку с помощью консоли

Находясь в извлеченной папке выполнить последовательно следующие команды:

# perl Makefile.PL
# make
# make test
# make install

В процессе установки система предложит установить необходимые модули (пакеты), зависимых модулей не так много и большая часть уже установлена на Вашей системе.

ИНИЦИАЛИЗАЦИЯ

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

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

Для инициализации следует выполнить следующую команду:

# mbutiny config

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

# mbutiny -c /my/config/files/mbutiny.conf config

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

КОНФИГУРАЦИЯ

Большое внимание следует уделить конфигурации. Именно правильное настроенное приложение гарантирует корректную работу всего приложения.

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

extra/arc.conf
extra/collector.conf
extra/sendmail.conf
hosts/host-foo.conf.sample
collector.cgi.sample
mbutiny.conf

Главным конфигурационным файлом является файл mbutiny.conf. Он содержит глобальные определения и определяет какие дополнительные файлы будут прочитаны и использоваться. Файл collector.cgi.sample содержит в себе пример скрипта коллектора (о нем будет сказано в разделе КОЛЛЕКТОР). Сам коллектор для своей работы использует единственный конфигурационный файл extra/collector.conf. Файл extra/arc.conf содержит определения для запуска внешних архиваторов; extra/sendmail.conf содержит определения для отправки электронной почты по умолчанию. Файл hosts/host-foo.conf.sample является своим образом образцом того, как выглядит работающий хост.

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

mbutiny.conf

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

LogEnable   on
LogEnable   off

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

LogLevel warning

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

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

В случае запуска программы mbutiny с параметром -l помимо файла mbutiny.log будет записываться файл системного лога - mbutiny_debug.log. Данный файл нужен для детальной отладки работы зависимых компонентов App::MBUtiny.

BUday    3

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

BUweek   3

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

BUmonth  3

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

SendReport      yes
SendReport      no

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

SendErrorReport yes
SendErrorReport no

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

extra/sendmail.conf

Файл содержит блок определений <SendMail>...</SendMail> с определеними для отправки отчета по электронной почте. Названия директив соответствуют полям протокола SMTP, за исключением следующих полей:

TestMail    test@example.com

Директива заставляет отправлять отчет на адрес test@example.com в случае запуска приложения с ключом -t

ErrorMail   error@example.com

Директива застравляет отправлять отчет об ошибках на адрес error@example.com в случае установленной директивы SendErrorReport yes

Sendmail   /usr/sbin/sendmail
Flags      -t

Директива Sendmail определяет альтернативное SMTP приложение, отправлющее письмо. Запуск приложения проходит с ключом -t, определенного директивной Flags

SMTP       192.168.0.1
SMTPuser   user
SMTPpass   password

Данные директивы определяют параметры соединения с SMTP сервером для отправки сообщения. Параметр SMTPuser и SMTPpass необязательны.

<Attach>...</Attach>

Блок (а их может быть указано несколько) определяет файл, который следует включить в отчет

extra/arc.conf

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

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

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

FILE     -- Полное имя файла с путем
FILENAME -- Только имя файлов архивов
DIRSRC   -- Каталог поиска имен файлов
DIRIN    -- = DIRSRC
DIRDST   -- Каталог для исзвлечения содержимого архивов
DIROUT   -- = DIRDST
LIST     -- Список файлов в архиве, через пробел

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

FILE     -- Полное имя выходного файла архива с путем
DIRSRC   -- Каталог поиска имен файлов и подкаталогов для сжатия
DIRIN    -- = DIRSRC
LIST     -- Список файлов для сжатия, через пробел

Для примера можно рассмотреть блок работы с архиватором tar

<Arc tgz> # Начало именованной секции. Имя, как правило, это расширение файлов архива
    type       tar                       # Тип архива, его версия имени
    ext        tgz                       # Расширение файлов архива
    create     tar -zcpf [FILE] [LIST]   # Команда для создания архива
    extract    tar -zxpf [FILE] [DIRDST] # Команда для извлечения файлов из архива
    list       tar -ztf [FILE]           # Команда для получения списка файлов в архиве
    nocompress tar -cpf [FILE]           # Команда для упаковки файлов без сжатия
</Arc>

extra/collector.conf

Файл содержит блок определений для сервера коллектора <Collector>...</Collector>

Сервер коллектора подробно рассматривается в разделе КОЛЛЕКТОР.

Блок <Collector>...</Collector> содержит определения для соединения с БД (блок <DBI>...</DBI>) и необязательную директиву DataDir.

DataDir   "/var/data/mbutiny"

Директива содержит путь для хранения файлов резервных копий (HTTP хранилища). По умолчанию - корневой катлог сервера коллектора (DOCUMENT_ROOT)

hosts/host-*.conf

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

Enable      yes
Enable      no

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

SendReport  no
SendErrorReport yes

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

ArcName     zip

Имя секции <Arc>...</Arc> файла extra/arc.conf. По умолчанию определены архивы с именами: tar, tgz, gz, zip, bz2, rar. По умолчанию ArcName принимает значение tar - архиватор Tape ARchive (TAR)

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 использует значения из одноименных глобальных определений.

SHA1sum     yes
MD5sum      yes

По завершению операции сжатия объектов происходит подсчет контрольных сумм SHA1 и MD5. Данные сумы желательно использовать для контроля качества прохождения бэкапов и восстановления, а также при работе с коллектором.

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>
    URI         https://user:password@collector.example.com/collector.cgi
    #User       user # Optional. See URI
    #Password   password # Optional. See URI
    #TimeOut    180
</Collector>

Данная секция определяет коллектор. Таких секций может быть несколько в рамках данного хоста. Здесь URI - Адрес (URI) до хранилища (коллектора). Логин и пароль HTTP авторизации указывается либо в теле URI, либо отдельно, если этого требует безопасность. 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
    FTPhost     ftp.example.com
    FTPdir      mbutiny/foo
    FTPuser     user
    FTPpassword password
    Set         Passive 1
    Comment     FTP said blah-blah-blah for collector # Optional for collector
</FTP>

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

<HTTP>
    FixUP       on
    URI         https://user:password@collector.example.com/collector.cgi
    #User       user # Optional. See URI
    #Password   password # Optional. See URI
    Comment     HTTP said blah-blah-blah for collector # Optional for collector
    #TimeOut    180
</HTTP>

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

НАЧАЛО РАБОТЫ

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

# mbutiny -h

Общий синтаксис команды mbutiny таков:

# mbutiny [OPTIONS] [COMMANDS [ARGS]]

Существует ряд ключевых опций команды:

-D DATADIR

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

-c CONFFILE
--config=CONFFILE

Ключ заставляет программу использовать в качестве конфигурационного файла CONFFILE. По умолчанию используется системный путь к файлу mbutiny.conf.

-v

Ключ позволяет видеть на экране результат работы программы mbutiny. Для более детальной информации можно воспользоваться дополнительным ключом -d.

Помимо опций доступен ряд команд:

test [HOSTs]

Команда позволяет выполнять тестирование указанных хостов. Если названия хостов опущены, то произойдёт тестирование всех хостов, определнных в соответствующих конфигурационных файлах.

[backup [HOSTs]]

Команда позволяет выполнить резервное копирование указанных хостов. Если названия хостов опущены, то произойдёт тестирование всех хостов, определнных в соответствующих конфигурационных файлах. следует заметить, что команда backup является командой по умолчанию для программы mbutiny.

restore [HOSTs] [DATE]

Команда позволяет выполннить скачиваение и разархивирование последнего созданной резервной копии для указанных хостов (или всех, если хосты не указаны). Параметр DATE задает дату, в формате YYYY.MM.DD или DD.MM.YYYY для восставноления. Если файла резервной копии для указанной даты нет, то берется ближйшая резервная копия к этой дате, но не позже указанной. По окончании работы программа выведет на экран путь, по которому можно будет получить восстановленные данные. Данную команду не рекомендуется запускать в автоматическом режиме.

checkup [HOSTs] [DATE]

С помощью данной команды можно получить статус выполненных за указанные сутки резервных копий. Параметр DATE задает дату, в формате YYYY.MM.DD или DD.MM.YYYY для выполнения запроса статистики. Если дата не задана, то по умолчанию используется текущая дата. Статистика запрашивается с 0 часов 0 минут 0 секунд указанных суток по текущее время. Список хостов задает программе опрделения тех обязательных хостов, которые она должна загрузить для определения секций используемых коллекторов, а также для дополнительного анализа на наличие файлов резервных копий хостов на данных коллекторах. По умолчанию используется весь набор хостов, доступный программе.

ПРОМЫШЛЕННОЕ ИСПОЛЬЗОВАНИЕ

После отладки работы программы смело можно приступать к настройке программы для выполнения в автоматическом режиме. Для этого существует несколько способов и один из активно применяемый - cron.

Вот таким образом может выглядеть задача по выполнению резервного копирования всех хостов:

0 2 * * * /usr/bin/mbutiny >/dev/null 2>>/var/log/mbutiny-error.log

Задача говорит, что необходимо выполнить резервное копирование всех хостов строго в 2 часа ночи

Следующий пример демонстрирует то, как можно "разнести" хосты по времени:

0 2 * * * /usr/bin/mbutiny backup foo >/dev/null 2>>/var/log/mbutiny-error.log
0 3 * * * /usr/bin/mbutiny backup bar >/dev/null 2>>/var/log/mbutiny-error.log
0 4 * * * /usr/bin/mbutiny backup baz >/dev/null 2>>/var/log/mbutiny-error.log

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

Всю отладочную информацию об ошибках, можно наблюдать в файле /var/log/mbutiny-error.log

КОЛЛЕКТОР

Коллектор это часть App::MBUtiny. Интерфейсом является CGI сценарий, пример которого размещен в файле collector.cgi.sample:

#!/usr/bin/perl -w
use strict;

use WWW::MLite;
my $mlite = new WWW::MLite(
    prefix  => 'collector',
    name    => 'Collector',
    module  => 'App::MBUtiny::Collector',
    config_file => '/path/to/mbutiny/extra/collector.conf',
    register => ['App::MBUtiny::Collector::Root'],
);
$mlite->show;

Данный скрипт использует в своей работе технологию WWW::MLite, обеспечивающую связь между сервером и агентом App::MBUtiny. Взаимодействие происходит по протоколу HTTP.

Помимо простого CGI сценария существует интеграция с проектом App::MonM. App::MonM анализирует, если есть установленный модуль App::MBUtiny, то он пытается построить соответвующий грид по данным коллекторов.

Коллектор предоставляет API. API предусматривает обмен данными исключительно в формате XML. Коллектор использует конфигурационную информацию из указанного файла, например extra/collector.conf После редактирования этого конфигурационного файла администратор должен скорректирвоать и путь до него в CGI скрипте collector.cgi указав местоположение существующего и настроенного файла, например, указать следующий путь, чаще всего используемый на операционных системах Linux:

/etc/mbutiny/extra/collector.conf

Установка коллектора

Коллектор устанавливается в пять этапов:

  1. Установка и инициализация App::MBUtiny по правилам, рассмотреннымм в соответствующих разделах данного документа. См. выше
  2. Создание "базы данных" и таблицы mbutiny
  3. Правка конфигурационного файла collector.conf
  4. Создание сценария collector.cgi с указанием пути расположения конфигурационного файла collector.conf
  5. Настройка прав доступа к коллектору

Этап 2 предусматривает выбор подходящей реляционной БД, например, MySQL. После выбора типа СУБД необходимо создать соответствующую "пустую" БД или использовать уже имеющуюся. Важное замечание: БД должна поддерживать кодировку UTF8!

После создания БД требуется создать пустую таблиwe под имненем mbutiny. Можно использовать и другое имя, но придётся прописать его в конфигурационном файле collector.conf в директиве Table секции DBI.

Для создания таблички используйте DDL размещенный в заголовке файла-примера collector.conf, который был сгенерирован при инициализации App::MBUtiny.

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

Этап 4 указывает на необходимость создания сценария collector.cgi. Для этого требуется наличие уже установленного сервера Apache с подготовленным виртуальным хостом. В указанное место на диске размещаем файл коллектора и прописываем права доступа к нему.

Права доступа легко ограничить используя файл конфигурации .htaccess, который может содержать следующие инструкции, организующие файловую авторизацию HTTP:

<Files collector.cgi>
    AuthName "App::MBUtiny file authorization for access to collector"
    AuthType Basic

    AuthGroupFile /var/www/mbutiny.example.com/.htgroups
    AuthUserFile  /var/www/mbutiny.example.com/.htpasswd

    Require valid-user
    #Require username
    Require group collector
</Files>

Файлы .htgroups и .htpasswd соддержат объявления групп и пользователей, соответственно.

После успешного выполнения вышесказанного следует проверить работоспособность коллектора в ручном режиме. Для этого в строку браузера нужно ввести путь до файла CGI сценария используя параметр check. Например:

https://mbutiny.example.com/collector.cgi?action=check

При этом в окне браузера должен отобразиться XML документ с тегом status со значением 1:

<status>1</status>

Более подробную информацию о формате см. в разделе API.

Если ошибок не выявлено то это означает что установка и настройка коллектора выполнена успешно.

Пример резервного копирования сервера коллектора

Ниже предлагается пример того, как с помощью mbutiny выполнить резервное копирование самого коллектора на удаленное FTP хранилище и на локальный коллектор. Для примера использовалась операционная система CentOS. Все наименования хостов, логины и пароли вымышленные. Файл носит имя host-mbutiny.example.com.conf и расположен в каталоге /etc/mbutiny/hosts

<Host mbutiny.example.com>
    Enable          yes
    SendReport      no
    SendErrorReport yes
    ArcName         tgz
    SHA1sum         yes
    MD5sum          yes

    # Triggers
    Trigger mysqldump -f -h localhost -u user --port=3306 --password=password \
            --add-drop-table --default-character-set=utf8 \
            --databases mbutiny > /home/mbutiny/mbutiny.sql

    # Objects
    Object /etc
    Object /home/mbutiny/mbutiny.sql

    # Collector definitions (Can be defined by several sections)
    <Collector>
        URI         http://user:password@mbutiny.example.com/collector.cgi
        Comment     "(LOCAL) Configuration and databases on mbutiny.example.com"
        #TimeOut    180
    </Collector>

    # Local storage
    <Local>
        Localdir    /home/mbutiny/local
    </Local>

    # FTP storage (Can be defined by several sections)
    <FTP>
        FixUP       on
        FTPhost     192.168.92.88
        FTPdir      mbutiny/mbutiny.example.com
        FTPuser     bu
        FTPpassword asdfghjkl
        Comment     "(FTP) Configuration and databases on mbutiny.example.com"
    </FTP>

    # HTTP storage (Can be defined by several sections)
    <HTTP>
        FixUP       on
        URI         http://user:password@mbutiny.example.com/collector.cgi
        Comment     "(HTTP) Configuration and databases on mbutiny.example.com"
        TimeOut     600
    </HTTP>
</Host>

API

Как уже упоминалось в разделе КОЛЛЕКТОР взаимодействие между агентом (роль которого выполняет приложение mbutiny) и сервером коллектора (далее коллектор) выполняется по протоколу HTTP используя формат обмена данных - XML. Сервер коллектора отвечает на POST запросы принимая параметры во входном XML, а отвечает выходным XML документом. Но есть одно исключение, когда ответ коллектором возвращается агенту в формате с MIME типом application/octet-stream. Этим исключением является обработчик download, заставляющий коллектор возвращать двоичные данные файла для записи на диск на стороне агента. Более подробно об этой исключительной ситуации будет рассказано в разделе download.

Для осуществеления API вызова необходимо создать POST (в редких случаях GET) запрос, где первым параметром должен быть объект (имя обработчика), а вторым - XML тело запроса. Общий вид запроса выглядит примерно следующим образом:

	http://SITE:PORT/collector.cgi?action=ИМЯ_ОБРАБОТЧИКА&request=XML_ДОКУМЕНТ
	https://SITE:PORT/collector.cgi?action=ИМЯ_ОБРАБОТЧИКА&request=XML_ДОКУМЕНТ

Если не указан ни один параметр, то предпологается вызов обработчика с именем default. Далее будет рассмотрен каждый обработчик детально.

Формат входного документа XML, передаваемого в параметре request имеет вид:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <object>
        ИМЯ_ОБРАБОТЧИКА
    </object>
    <data>
        ТЕГИ_ДАННЫХ
    </data>
</request>

Здесь тег <object>...</object> содержит имя обработчика, повторяемый параметром action. Нужно это для четкого сопостановления и во избежании ошибок стороны агента. Тег <data>...</data> содержит набор данных, переданных обработчику от агента.

Формат выходного документа, который генерирует сервер коллектора, имеет вид:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        ТЕГИ_ДАННЫХ
    </data>
    <debug_time>0.531</debug_time>
    <error>
        ТЕКСТ_ОШИБКИ
    </error>
    <object>
        ИМЯ_ОБРАБОТЧИКА
    </object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>
        СТАТУС_ОПЕРАЦИИ
    </status>
</response>

Как видно из примеров, тег-оболочка для запроса носит имя request, когда как тег для ответа называется response. Тег <object>...</object> говорит о том, на какой обработчик был дан ответ, или каким переназначенным обработчиком был дан ответ. Тег <data>...</data> содержит набор данных, переданных агенту от обработчика. Тег <status>...</status> может принимать два значения: 0 - в случае возникших ошибок; 1 - В случае если операция прошла успешно и обработчик выполнил необходимые действия без ошибок. Если возникли какие-либо ошибки, то их текст передаётся в теге <error>...</error>. Дополнительные теги <debug_time>...</debug_time>, <query_string>...</query_string>, <remote_addr>...</remote_addr> содержат информацию прикладного значения. debug_time - время в секундах, которое понадобилось для выполнения хадачи обработчика. query_string - параметры пришедшие на вход, если они были указаны. remote_addr - IP адрес агента, вызвавшего обработчик.

default

Обработчик default отвечает на неизвестные или неподдерживаемые запросы. Пример ответа обработчика default:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data></data>
    <debug_time>0.056</debug_time>
    <error>Неверно указан обработчик. Список доступных обработчиков доступен через операцию
        check</error>
    <object>default</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>0</status>
</response>

Как видно из примера, агенту вернулась ошибка с текстом и статус в значении 0. При этом никаких данны передано не было.

check

Получение состояния готовности коллектора. Обработчик возвращает состояние готовности коллектора к приему других запросов. Этот обработчик следует вызывать до выполнения каких-либо действий с коллектором. Ниже приведен негативный и позитивные результаты ответа обработчика:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <object>check</object>
</request>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data></data>
    <debug_time>0.531</debug_time>
    <error>ERR: 2005; ERRSTR: Unknown MySQL server host 'mysql.example.com' (11001);
        STATE: HY000</error>
    <object>check</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>0</status>
</response>

 

<?xml version="1.0" encoding="utf-8"?>
<request>
  <object>check</object>
</request>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <action>check</action>
        <action>upload</action>
        <action>fixup</action>
        <action>status</action>
        <action>list</action>
        <action>info</action>
        <action>download</action>
        <action>delete</action>
        <dir>data</dir>
        <message>Ok</message>
    </data>
    <debug_time>0.125</debug_time>
    <error></error>
    <object>check</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

При успешном выполнении обработчика колектор вернет в теге <data>...</data> список поддерживаемых обработчиков.

upload

Обработчик представляет собой интерфейс для загрузки файлов резервных копий - аплоадить бэкапы. Это единственный обработчик принимающий данные в типе кодирования данных (MIME) multipart/form-data. Все остальные случаи не используют multipart/form-data для передачи данных коллектору.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <comment>blah-blah-blah</comment>
        <file>test1-2014-09-05.zip</file>
        <host>test1</host>
        <md5>229f51f8257e5200f5942fa210b2b4c5</md5>
        <sha1>ecf0cc7fb25a57025a20ba42161cd215d585f3af</sha1>
    </data>
    <object>upload</object>
</request>

Тег <comment>...</comment> содержит комментарий для фиксации коллектором. <file>...</file> содержит имя файла передаваемое серверу. <host>...</host> содержит имя хоста, выполняющего загрузку. <md5>...</md5> и <sha1>...<.sha1> содержат контрольные суммы передаваемого файла. Эти два тега не являются обязательныеми, как и тег <comment>...</comment>. Сами данные следует передавать в POST параметре с именем data, закодированные согласно правилам кодирования multipart/form-data.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <id>422</id>
        <message>Uploading sucess</message>
        <path>data\test1\test1-2014-09-05.zip</path>
    </data>
    <debug_time>0.142</debug_time>
    <error></error>
    <object>upload</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

После загрузки файла резервной копии возвращается статус операции, путь записи файла на стороне коллектора и #ID заведенной записи бэкапа в БД. Помимо этого возвращается сообщение для агента в теге <message>...</message>.

fixup

После аплоадинга и в случаях необходимости фиксировать состояния выполнения передачи файлов резервных копий различным хранилищам, следует вызывать обработчик fixup, передавая параметры в зависимости рода хранилища. Если коллектором и хранилищем HTTP является один и тот же сервер, то передается тег <id>...</id>, содержащий ID только что загруженного файла (см. обработчик upload). Тег <status>...</status> должен содержать значение статуса: 1 - загрузка прошла успешно; 0 - загрузка прошла с ошибками. Тег <type>1</type> должен передаваться со значеним 1, это заставляет коллектор не создавать новую запись в БД а использовать уже имеющуюся, созданную при загрузке. Помимо этого передаётся комментарий и сообщение в соответствующих тегах.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <id>422</id>
        <comment>blah-blah-blah</comment>
        <message>Uploading sucess: test1-2014-09-05.zip ... </message>
        <status>1</status>
        <type>1</type>
    </data>
    <object>fixup</object>
</request>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <id>422</id>
        <message>Fixing sucess. The data successfully inserted to table of database</message>
    </data>
    <debug_time>0.125</debug_time>
    <error></error>
    <object>fixup</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

Далее слеудет рассмотреть случай обычного фиксапа, типа = 0.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <comment>local said blah-blah-blah</comment>
        <file>test1-2014-09-05.zip</file>
        <host>test1</host>
        <md5>229f51f8257e5200f5942fa210b2b4c5</md5>
        <message>Files successfully stored to LOCAL directoy ... </message>
        <sha1>ecf0cc7fb25a57025a20ba42161cd215d585f3af</sha1>
        <size>131616</size>
        <status>1</status>
        <type>0</type>
    </data>
    <object>fixup</object>
</request>

Здесь тег <size>...</size> содержит значение размера файла резервной копии, остальные поля идентичные обработчику upload и fixup для случая рассмотренного выше.

list

Обработчик позволяет получить список загруженных файлов резервных копий на HTTP хранилище по имени хоста.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <host>test1</host>
    </data>
    <object>list</object>
</request>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <list>test1-2014-08-27.zip</list>
        <list>test1-2014-08-28.zip</list>
        <list>test1-2014-08-29.zip</list>
        <list>test1-2014-09-01.zip</list>
        <list>test1-2014-09-03.zip</list>
        <list>test1-2014-09-05.zip</list>
        <message>Spisok failov dlia khosta uspieshno poluchien</message>
    </data>
    <debug_time>0.119</debug_time>
    <error></error>
    <object>list</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

В качестве входного тега выступает <host>...</host> содержащий имя хоста для которого необходимо получить список файлов. На выходе, в тегах <list>...</list>, можно увидеть имена файлов резервных копий.

delete

Данный обработчик призван удалять файлы с хранилища HTTP и фиксировать процесс удаления.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <file>test1-2014-08-27.zip</file>
        <host>test1</host>
    </data>
<object>delete</object>
</request>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <id>35</id>
        <message>Fail uspieshno udalien</message>
    </data>
    <debug_time>0.149</debug_time>
    <error></error>
    <object>delete</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

На вход передается имя файла и имя хоста в соответствующих тегах <file>...</file> и <host>...</host>

info

Получение подробной информации о файле.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <file>test1-2014-09-05.zip</file>
        <host>test1</host>
    </data>
    <object>info</object>
</request>

На вход передается имя файла и имя хоста в соответствующих тегах <file>...</file> и <host>...</host>

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <id>428</id>
        <agent_host>mnsdesktop</agent_host>
        <agent_ip>127.0.0.1</agent_ip>
        <agent_name>test1</agent_name>
        <comment>blah-blah-blah</comment>
        <date_finish></date_finish>
        <date_start>2014-09-05 15:15:14</date_start>
        <datestamp>2014-09-05 15:15:13</datestamp>
        <file_md5>229f51f8257e5200f5942fa210b2b4c5</file_md5>
        <file_name>test1-2014-09-05.zip</file_name>
        <file_sha1>ecf0cc7fb25a57025a20ba42161cd215d585f3af</file_sha1>
        <file_size>131616</file_size>
        <message>Uploading sucess ... </message>
        <server_host>mbutiny.localhost</server_host>
        <server_ip>127.0.0.1</server_ip>
        <status>1</status>
        <type>1</type>
    </data>
    <debug_time>0.115</debug_time>
    <error></error>
    <object>info</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

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

download

Обработчик позволяет скачать файл с коллектора. Контент файла передается вместо XML ответа, как упоминалось выше, это единственный обработчик, возвращающий данные с MIME типом отличном от text/xml

Ответ, получаемый от коллектора двоичный, поэтому все данные необходимо сохранять в режиме "AS IS".

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <file>test1-2014-09-05.zip</file>
        <host>test1</host>
    </data>
    <object>download</object>
</request>

На вход передается имя файла и имя хоста в соответствующих тегах <file>...</file> и <host>...</host>

report

Получение состояния (среза) выполненных или невыполненных резервных копирований для ряда хостов.

Этот обработчик обеспечивает дополнительные функции коллектора, написанные для программы App::MonM. Он позволяет получить состояние (срез) выполненных бэкапов за последние сутки, или сутки, указанные в качетстве аргумента. При проверке состояния учитывается также переданное имя хоста. Если же имя хоста опущено, то произойдет анализ последних резервных копий по всем хостам коллектора.

<?xml version="1.0" encoding="utf-8"?>
<request>
    <data>
        <type>1</type>
        <host>test1</host>
        <date_start>01.09.2014</date_start>
        <date_finish>09.09.2014</date_finish>
    </data>
    <object>report</object>
</request>

На вход подаются необязательные поля: имя хоста, тип и даты - начала периода и окончания периода. Тип определяет какие резервные копии (внешние или внутренние) подвергать выборки: 0 - внешние, 1 - внутренние, 2 - и те и другие. Даты начала и окончания периода задаются в формате DD.MM.YYYY. Если не указать ниодно из полей, то произойдёт выборка отчета за текущие сутки с 00:00:00 по текущее время включительно.

Ответ может быть следующим:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <data>
        <backup>
            <id>460</id>
            <agent_host>mnsdesktop</agent_host>
            <agent_ip>127.0.0.1</agent_ip>
            <agent_name>localhost</agent_name>
            <comment>(HTTP) Configuration and databases on ... </comment>
            <date_start>2014-09-09 04:05:06</date_start>
            <file_md5>96e3596cff90daebd186fac5e478f0af</file_md5>
            <file_name>test1-2014-09-03.zip</file_name>
            <file_sha1>c47b0a6346f0ea3ef791a9fb579eff8b833f5d44</file_sha1>
            <file_size>1198023</file_size>
            <message>Uploading sucess ... </message>
            <n>1</n>
            <server_host>mbutiny.localhost</server_host>
            <server_ip>127.0.0.1</server_ip>
            <status>1</status>
            <type>1</type>
        </backup>
        <message>Список успешно получен</message>
        <number>1</number>
    </data>
    <debug_time>0.116</debug_time>
    <error></error>
    <object>report</object>
    <query_string></query_string>
    <remote_addr>127.0.0.1</remote_addr>
    <status>1</status>
</response>

Секция <backup>...</backup> (а их может быть несколько) содержит данные по резервной копии. Значение тега <number> соответсьвует количеству полученных записей.

AUTHOR

Serż Minus (Lepenkov Sergey) http://www.serzik.com <abalama@cpan.org>

COPYRIGHT

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


$Id: index.shtml 74 2014-09-22 13:12:37Z abalama $

Valid XHTML 1.0 Transitional Valid CSS