$Id: README 50 2014-09-03 12:24:39Z abalama $ App::MBUtiny v1.03 and later This document written in Windows-1251 charset ============================================= КОРОТКО О ПРОЕКТЕ ----------------- App::MBUtiny - готовое решение для работы с резервными копиями ваших сайтов, баз данных и просто данных на жестком диске. App::MBUtiny создан как продолжение развития двух ранних проектов - mbu и mbutiny. ВОЗМОЖНОСТИ ----------- - Резервное копирование веб-сайтов (контент) и отдельных файлов/папок - Резервное копирование небольших баз данных - Запуск внешних скриптов и команд для последуюшего резервного копирования результата их работы - Хранение резервных копий одновременно на локальных дисках, или удаленных FTP/HTTP хранилищах - Быстрая настройка путем простого редактирования конфигурационных файлов - Установка проекта средствами CPAN или в ручном режиме через make install ЗАВИСИМОСТИ ----------- Перед началом установки, Вам необходимо проверить наличие следующих пакетов, установленных в Вашей системе где будет "работать" App::MBUtiny: - gcc последней версии - perl v5.10 или выше (рекомендуется не ниже v5.12) - libwww (p5-libwww / perl-libwww) - libnet - zlib Если Вы планируете использовать коллектор, то для работы потребуется наличие WEB сервера Apache 2.2 или выше. Сервер должен быть настроен на выполнение CGI (perl) скриптов. УСТАНОВКА --------- Установка выполняется двумя путями. Первый - автоматизированный; второй - ручной. В автоматизированном режиме для установки достаточно выполнить команду: # cpan install App::MBUtiny или (для ActivePerl): # ppm install App-MBUtiny В ручном режиме Вам потребуется выполнить следующий набор операций: - Скачать дистрибутив с CPAN или официальный релиз с сайта SourceForge: https://metacpan.org/pod/App::MBUtiny http://search.cpan.org/~abalama/ https://sourceforge.net/projects/app-mbutiny/ - Разархивировать полученный архив, и перейти в извлеченную папку с помощью консоли - Находясь в извлеченной папке выполнить последовательно следующие команды: 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 ~~~~~~~~~~~~~~~~~~~ Файл содержит блок определений ... с определеними для отправки отчета по электронной почте. Названия директив соответствуют полям протокола 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 необязательны. ... Блок (а их может быть указано несколько) определяет файл, который следует включить в отчет extra/arc.conf ~~~~~~~~~~~~~~ Секция работы с архивами. Подробное описание см. в модуле CTK. В этой секции определяются основные настройки работы с архивами, каждое значение любого параметра обрабатывается единым механизмом обработки маски. Ключи в маске могут быть использованы следующие: Для случая извлечения файлов из арива: FILE -- Полное имя файла с путем FILENAME -- Только имя файлов архивов DIRSRC -- Каталог поиска имен файлов DIRIN -- = DIRSRC DIRDST -- Каталог для исзвлечения содержимого архивов DIROUT -- = DIRDST LIST -- Список файлов в архиве, через пробел Для случая сжатия файлов используется следеющий набор ключей: FILE -- Полное имя выходного файла архива с путем DIRSRC -- Каталог поиска имен файлов и подкаталогов для сжатия DIRIN -- = DIRSRC LIST -- Список файлов для сжатия, через пробел Для примера можно рассмотреть блок работы с архиватором tar # Начало именованной секции. Имя, как правило, это расширение файлов архива type tar # Тип архива, его версия имени ext tgz # Расширение файлов архива create tar -zcpf [FILE] [LIST] # Команда для создания архива extract tar -zxpf [FILE] [DIRDST] # Команда для извлечения файлов из архива list tar -ztf [FILE] # Команда для получения списка файлов в архиве nocompress tar -cpf [FILE] # Команда для упаковки файлов без сжатия extra/collector.conf ~~~~~~~~~~~~~~~~~~~~ Файл содержит блок определений для сервера коллектора ... Сервер коллектора подробно рассматривается в разделе КОЛЛЕКТОР. Блок ... содержит определения для соединения с БД (блок ...) и необязательную директиву DataDir. DataDir "/var/data/mbutiny" Директива содержит путь для хранения файлов резервных копий (HTTP хранилища). По умолчанию - корневой катлог сервера коллектора (DOCUMENT_ROOT) hosts/host-*.conf ~~~~~~~~~~~~~~~~~ Файлы с маской host-*.conf содержат определения дла хостов. Каждый файл host-*.conf должен определяться блоком .... Где name - уникальное имя хоста. Имя хоста принято выбирать таким образом, чтобы оно подсказывало на тот тип и группу объектов, которые подверглись резервному копированию. Помимо этого уникальность обеспечивает стабильность работы коллектора, если Вы используете его для работы. Enable yes Enable no Включение или выключение хоста. Аттрибут влияет на обработку хоста. Если атрибут установлен, то обработка хоста выполнится, иначе хост игнорируется. По умолчанию хост игнорируется. Но следует заметить, что наличие в секции ... директивы Enable обязательно! Иначе, возможны ошибки в обработке других хостов. SendReport no SendErrorReport yes Директивы управляют отправкой отчетов в рамках данного хоста. Данные для отправки берутся из внутренней секции ... или, если не указана данная внутренняя секция, из файла extra/sendmail.conf, описанного выше. ArcName zip Имя секции ... файла 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 указывает, какие файлы и папки необходимо архивировать для создания резервной копии. # Отсюда берутся сами исходные файлы. Директива может быть только одна Object /usr/local/etc # Опционально. Сюда копируются объекты для дальнейшего сжатия. Директива не обязательна Target /tmp/test_exclude_sample # Относительные пути файлов и папок которые НЕ СЛЕДУЕТ кописаровать в каталог Target Exclude bar.txt Exclude baz.txt Секции эксклюзивного копирования объектов, Их может быть задано несколько. Секции позволяют копировать файлы и папки каталога указанного в директиве Object в целевой каталог определенный с поощью директивы Target. Копирование происходит всей структуры исходного каталога в целевой каталог исключая объекты, указанные во внутренних директивах Exclude. Данный способ создания объектов требует дополнительного свободного места на диске. Следует заметить, что значение директивы Target будет автоматически добавлено в список объектов что не обеспечивают триггеры. Для каждого триггера (см. описание выше) нужно указывать свой объект с помощью директивы Object, как это иллюстрируется в приведнном примере. Говоря о примере, следует прокоментировать: первым шагом создается каталог /tmp/test, затем в каталог /tmp/test пишется файл foo.txt с содержимым foo. Для того, чтобы сделать резервную копию файла /tmp/test/foo.txt необходимо указать в качестве объекта либо сам файл /tmp/test/foo.txt либо всю папку /tmp/test. Таким образом происходит связка триггеров с объектами. URI https://user:password@collector.example.com/collector.cgi #User user # Optional. See URI #Password password # Optional. See URI #TimeOut 180 Данная секция определяет коллектор. Таких секций может быть несколько в рамках данного хоста. Здесь URI - Адрес (URI) до хранилища (коллектора). Логин и пароль HTTP авторизации указывается либо в теле URI, либо отдельно, если этого требует безопасность. TimeOut - Таймаут. По умолчанию 180 секунд. FixUP off Localdir C:\\Temp\\mbutimy-local1 Localdir C:\\Temp\\mbutimy-local2 #Comment Local said blah-blah-blah for collector # Optional for collector Секция ... может быть только одна в рамках данного хоста. Секция определяет параметры локального хранилища, это хранилище не является надежным, если его точка монтирования не является внешней относительно данного аппаратного устройства (сервера, компьютера, хранилища, маршрутизатора и т.д.). Секция ... содержит следующие директивы: Localdir - папка локального хранилища. Именно в нее будут помещены результативные архивы (резервные копии). Данных директив Localdir может быть несколько, тогда произойдёт копирование бэкапа в различные локальные хранилища. FixUP - Указывает выполнять фиксацию результата работы на коллекторе. может быть значение on или off Comment - Комментарий для коллектора. Полезен для мониторинга и отладки. Настоятельно рекомендуем не оставлять данную директиву пустой. FixUP on FTPhost ftp.example.com FTPdir mbutiny/foo FTPuser user FTPpassword password Comment FTP said blah-blah-blah for collector # Optional for collector Секция ... определяет параметры удаленного FTP-хранилища. секций может быть несколько в рамках данного хоста. В этом случае выполнится работа над каждым из указанных FTP-хранилищ. Директивы секции - FTPhost, FTPdir, FTPuser и FTPpassword - определяют непосредственный коннект к FTP-хранилищу, когда как директивы FixUP и Comment аналогичны по значению секции ... 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 находятся на одном физическом сервере. 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 для восставноления. Если файла резервной копии для указанной даты нет, то берется ближйшая резервная копия к этой дате, но не позже указанной. По окончании работы программа выведет на экран путь, по которому можно будет получить восстановленные данные. Данную команду не рекомендуется запускать в автоматическом режиме. ПРОМЫШЛЕННОЕ ИСПОЛЬЗОВАНИЕ -------------------------- После отладки работы программы смело можно приступать к настройке программы для выполнения в автоматическом режиме. Для этого существует несколько способов и один из активно применяемый - 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 сценария существует интеграция с проектом MonM. MonM анализирует, если есть установленный модуль App::MBUtiny, то он пытается построить соответвующий грид по данным коллектора. Коллектор предоставляет API. Обмен данными - происходит исключительно в формате XML. Коллектор использует конфигурационную информацию из указанного файла, например extra/collector.conf. Администратор должен скорректирвоать этот путь в CGI скрипте. Например, указать путь: /etc/mbutiny/extra/collector.conf Основные функции коллектора (тезисы): - [check] Получение состояния готовности коллектора - [upload] Аплоадить бэкапы. После аплоадинга возвращается статус операции, путь и #ID заведенной записи бэкапа. Входные данные передаются как POST запрос. Используется HTTP POST multipart механизм передачи данных между агентом и коллектором. В качестве параметров должны выступать: - URL/URI (https://user:password@site.com/path/) - user = , если из соображений security нельзя передавать в URL - password = , если из соображений security нельзя передавать в URL (- action = upload -- необязательный параметр) - host = имя хоста - file = имя файла - data = данные передаваемые из сжатого файла - sha1 = SHA1 для проверки (необязательный параметр) - md5 = MD5 для проверки (необязательный параметр) - . . . = . . . ! user и password уходят в стандартную авторизацию если это требует сервер - [fixup] Выполнять фиксирование пройденных резервных копирований. Если была заливка на текущий коллектор то используется переданный параметр #ID. В противном случае запись не заводится, а модифицируется имеющаяся. После фиксации возвращается стaтус операции и #ID заведенной (измененной) записи. Фуксация выставляет дату start/ Входные данные передаются как POST запрос, параметры помещаются в XML! В качестве параметров должны выступать: - ID - Date stamp - Agent host (кто делает бэкап) - Agent IP - Agent section name - Server host (куда делается бэкап) - Server IP (берется из заголовков настройки или nslookup утилитлй как на CBWI) - Status of operation (1=OK/0=ERROR) - Date start - Date finish - File name - File size - File MD5 sum - File SHA1 sum - Comment (из секции конфигурация по хосту Comment) - Message (проставляется в момент фиксапа, содержит поле сообщения статуса операции (error) с данным файлом или (message) при успешном обращении к коллектору) Далее эти данные отображаются на WEB интерфейсе MonM - [list] Список бэкапов type=1 (имён файлов на коллекторе) для данного хоста - [delete] Удалить бэкап (по его имени на коллекторе). При этом происходит удаление физического файла с типом type=1 из списка ... и все type=0 из списка ... если в секциях стоит признак FixUp on. Удаление в базе происходит путём установкой date_finish = NOW(). Удаление происходит по имени файла. - [info] Получить информацию о бэкапе (по его имени файла). Доступно также со стороны monm - [download] Скачать бэкап (по его имени файла). Доступно также со стороны monm Дополнительные функции коллектора, написанные для monm: - [status] Получить состояние по данному (или всем) хосту и имени файлу. Также возможно получение статуса (по хосту и) дате. По умоланию - текущей дате. Без аргументов вернутся состояние всех бкапов прошедших за текущую дату. API --- Coming soon... __END__