Перейти к содержанию

Резервное копирование через BMWCLIENT

Назначение документа

В документе описаны возможности резеревного копирования Облака. Резервное копирование выполняется через BMWCLIENT.

Документ нужен администраторам организации.

См. также: Резервное копирование почты, календарей, профилей пользователей и адресных книг

Что такое BMWCLIENT?

BMWCLIENT — это клиент для выполнения запросов к gRPC API. Основные функции клиента: резервное копирование и восстановление почтового ящика, облака, календарей, профилей пользователей и адресных книг.

Шаг 1. Предварительные настройки

Чтобы выполнять запросы к bmwclient, нужно добавить перечень IP и подсетей в веб-интерфейсе установщика:

  1. Откройте веб-интерфейс установщика http://server-adress:8888.

  2. Перейдите на вкладку Настройки → Настройки компонентов → Ограничение доступа к доменам.

    deployer_2

  3. Затем кликните по домену bmw.server-adress и нажмите кнопку редактировать deployer_2.

  4. Включите опцию Ограничить доступ к домену.

  5. Добавьте IP и подсети, под которыми разрешено обращаться к bmwclient'у. Чтобы разрешить всем IP и подсетям обращаться к bmwclient'у, добавьте IP-адрес 0.0.0.0/0. По умолчанию доступ к домену bmw.server-adress запрещен всем IP/подсетям.

    deployer_2

  6. Кликните по кнопке Сохранить.

  7. Перейдите к списку машин и включите опцию «Не показывать завершённые».

  8. Запустите следующие шаги:

    deployer_2

Примечание

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

Запросы к bmwclient'у можно будет выполнять, исходя из настроек IP и подсетей.

Шаг 2. Получить токен для выполнения запросов

  1. Перейдите на страницу biz.<сompany_domain> и авторизуйтесь в панели администратора.
  2. Перейдите по URL-адресу https://biz.<mail_domain>/oper/

  3. В меню слева выберите пункт Токены, на странице нажмите Добавить.

    image_1

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

    deployer_2

  5. Нажмите Добавить. Отобразится окно со сгенерированным токеном.

Внимание

Обязательно скопируйте и сохраните значение в поле «Токен:», его можно увидеть только один раз в отображаемом окне.

deployer_2

Авторизационный токен передаётся при каждом запросе к bmwclient'у.

Шаг 3. Скачать BMWCLIENT

  1. Перейдите на страницу biz.<сompany_domain> и авторизуйтесь в панели администратора.

  2. Перейдите по URL-адресу https://biz.<mail_domain>/oper/

  3. В меню слева выберите пункт Клиент и скачайте клиент, кликнув по bmwclient.

    get_client

Работа с bmwclient'ом происходит в командной строке (терминале). По умолчанию клиент скачивается в папку «Загрузки»/«Downloads».

console_start

Запуск клиента для Windows

Чтобы начать работу с bmwclient'ом под ОС Windows, не требуется дополнительных настроек и действий, достаточно шагов, выполненных выше.

Запуск клиента для Linux

Чтобы начать работать с bmwclient под ОС Linux, в терминале, в директории с bmwclient'ом, нужно запустить следующую команду:

chmod +x bmwclient

Запуск клиента для OS X

Чтобы начать работать с bmwclient под OS X, нужно выполнить следующие действия:

  1. В терминале, в директории с bmwclient'ом, нужно запустить последовательно команды:

    chmod +x bmwclient
./bmwclient -help

  2. Кликните «Отменить» во всплывающем уведомлении:

    deployer_2

  3. Откройте «Системные настройки» и перейдите в раздел «Конфиденциальность и безопасность» на вашем компьютере.

  4. Кликните по кнопке Все равно разрешить для приложения bmwclient:

    mac_os_2

  5. В терминале снова запустите команду ./bmwclient -help.

  6. Кликните «Открыть» во всплывающем уведомлении:

    deployer_2

Возможности BMWCLIENT и примеры запросов

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

  • -server — доменное имя для запросов в BMWCLIENT, например bmw.on-premise.ru.
  • -tls — использует ли сервер шифрование (https). Флаг принимает два значения: true или false. По умолчанию считается, что шифрование используется.
  • -method — метод, который необходимо вызвать в gRPC API.
  • -token — токен для авторизации запросов к gRPC API, полученный на шаге 1.

Опционально можно задавать следующие параметры:

  • -maxMessageSizeMB — максимальный размер сообщения передаваемый по gRPC. Значение по умолчанию: 128 МБ.
  • -skipVersionCheck — сравнивать ли версии клиента и сервера. Значение по умолчанию: false.
  • -timeout — принимает значение в секундах, нужно использовать на случай медленного соединения или, если запросы не выполняются с ошибкой timeout.

Получить список пользователей, файлы которых были изменены после указанного времени

Выполните следующую команду:

./bmwclient -server bmw.%domain% -tls=false -method cloudUsers -token %token% -startts %start_timestamp%

Пример запроса:

./bmwclient -server bmw.domain1.on-premise.ru \
  -method cloudUsers -token JleaQ8dNU0UBX6oaugaWmJ12vaaFp9Sa \
  -skipVersionCheck=true -startts 1695204000

-startts — дата и время изменения файлов у пользователей. Передается в формате UNIX timestamp.

Результат:

[INFO]: 2023/09/20 14:46:01 backend address is: bmw.domain1.on-premise.ru:443,
method is: cloudUsers
[INFO]: 2023/12/07 14:03:16 test_login_qdqm0ext@domain1.on-premise.ru
[INFO]: 2023/12/07 14:03:16 test_login_kjymg1yn@domain2.on-premise.ru
[INFO]: 2023/12/07 14:03:16 test_login_asyqg1ge@domain2.on-premise.ru
[INFO]: 2023/12/07 14:03:16 test_login_z0ohfzsc@domain2.on-premise.ru
[INFO]: 2023/12/07 14:03:16 test_login_aetdr5x9@domain3.on-premise.ru
[INFO]: 2023/12/07 14:03:16 test_login_2ixphpmh@domain4.on-premise.ru

Получить структуру файлов в облаке

Выполните следующую команду:

./bmwclient -server bmw.%domain% -method cloudBackup \
  -token %token% -email %email%

-email — email адрес почтового ящика, для которого выполняется запрос структуры.

Пример запроса:

./bmwclient -server bmw.domain1.on-premise.ru -method cloudBackup \
  -domain wm2.on-premise.ru -token JleaQ8dNU0UBX6oaugaWmJ12vaaFp9Sa \
  -email n.gruzdev@wm2.on-premise.ru

Результат:

[INFO]: 2023/09/27 14:13:56 backend address is: bmw.domain1.on-premise.ru:443,
method is: cloudBackup
[INFO]: tree:{info:{type:4 bizprj:2199023255553 ownerid:1000011 quota:2147483648} vfs:{name:"/" mode:2 list:{name:"Календарь" nodeid:"\x03\x00\x00\x00C\xc53d^b\xc4H\xad\xacН" mode:4098 list:{name:"1 (4).txt" mtime:1683124497 nodeid:"L\x00\x00\x00C\xc53d^b\xc4H\xad\xacН" mode:4097 size:9 hash:"Test info\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"}
}} acls:{treeid:"623432346630303030303030"}} path:"/recovered_data" lock:3

Создать полную резервную копию облака

Чтобы создать полную резервную копию файлов в облаке для конкретного пользователя и сохранить результат в директорию, нужно выполнить следующую команду:

./bmwclient -server bmw.%domain% -method cloudBackup -token %token% \
  -email %email% -savePath backups -zip -save
  • -email — email-адрес почтового ящика, для которого снимается резервная копия.
  • -savePath — путь на диске, куда необходимо сохранить резервную копию облака.
  • -save — сохранить результат резервного копирования на диск в директорию, без сжатия.
  • -zip — сжать в zip-архив результаты резервного копирования и сохранить на диск.

Флаги -save и -zip взаимоисключающие, их нельзя использовать вместе в одном запросе.

Пример запроса с параметром -save:

./bmwclient -server bmw.domain1.on-premise.ru -method cloudBackup \
  -token JleaQ8dNU0UBX6oaugaWmJ12vaaFp9Sa -email n.gruzdev@wm2.on-premise.ru \
  -save -savePath ./backups

В примере, в параметре -savePath, указан путь относительно папки, в которой находится bmwclient.

Результат:

[INFO]: 2023/09/20 18:25:42 backend address is: bmw.domain1.on-premise.ru:443,
method is: cloudBackup

Результат резервного копирования в папке backups/n.gruzdev@wm2.on-premise.ru-1702027656. Где 1702027656 — это дата бэкапа в формате UNIX timestamp.

-save -byFolders

Пример запроса с параметрами -zip:

./bmwclient -server bmw.domain1.on-premise.ru -method cloudBackup \
  -token JleaQ8dNU0UBX6oaugaWmJ12vaaFp9Sa -email n.gruzdev@wm2.on-premise.ru \
  -zip -savePath ./backups

Результат:

[INFO]: 2023/09/20 18:25:42 backend address is: bmw.domain1.on-premise.ru:443,
method is: cloudBackup

Единственное отличие от бэкапа с параметром -save — содержимое папки сжимается в архив.

Содержимое бэкапа

В папке с бэкапом всегда сохраняются файлы:

  • tree.json — здесь отражена структура файлов в облаке. Структура файлов представляется в виде плоского дерева.
  • tree.info.json — метаданные дерева.
  • publics.json — здесь находятся данные об общих папках.
  • Файлы находящиеся в облаке.

При этом одинаковые файлы сохраняются один раз, а в файле tree.json содержится ссылка на этот файл.

Пример файла tree.info.json:

{
  "type": 4,
  "bizprj": 123,
  "ownerid": 456,
  "quota": 5368709120
}
  • "type" — Тип дерева. Возможные значения:
    • 0 — дерево обычного пользователя.
    • 1 — общедоступное дерево обычного пользователя.
    • 4 — дерево бизнес-пользователя.
    • 5 — общедоступное дерево бизнес-пользователя.
  • "bizprj" — идентификатор бизнес-проекта которому принадлежит дерево, используется для деревьев с типом 4 и 5.
  • "ownerid" — ID владельца дерева.
  • "quota" — максимальный размер хранилища пользователя.

Пример файла publics.json:

{
  "email": "n.gruzdev@wm2.on-premise.ru",
  "ctime": 1724651727,
  "extra": "{\"v\":2}",
  "publics": [
    {
      "id": "esEn/x1p2X3uLt",
      "extid": "/Календарь",
      "ctime": 1724651727,
      "flags": 6,
      "extra": "{}"
    }
  ]
}
  • "extid" — путь до общей папки в дереве пользователя.
  • "ctime" внутри поля "publics" — дата создания общей папки.
  • "flags" и "extra" — служебные флаги и поля.

tree.json содержит объекты двух типов:

  • Папки. В поле childs находятся ссылки на вложенные в нее папки и файлы.
  • Файлы. В поле nodeid находится идентификатор папки, к которой принадлежит файл.

Пример файла tree.json:

[
  {
    "name": "Календарь",
    "nodeid": "3e2cc7f1f79e6c270855cbf917a254e7",
    "mode": 4098,
    "childs": [
      "492cc7f1f79e6c270855cbf917a254e7",
      "472cc7f1f79e6c270855cbf917a254e7",
      "4a2cc7f1f79e6c270855cbf917a254e7"
    ]
  },
  {
    "name": "1A46632B-.jpeg",
    "mtime": 1708612045,
    "nodeid": "472cc7f1f79e6c270855cbf917a254e7",
    "mode": 4097,
    "size": 138053,
    "hash": "1ad3a8149519d8a8f93390c932324c45234d1257"
  },
    {
    "name": "1B606A7D-.jpeg",
    "mtime": 1708612045,
    "nodeid": "4a2cc7f1f79e6c270855cbf917a254e7",
    "mode": 4097,
    "size": 138053,
    "hash": "1ad3a8149519d8a8f93390c932324c45234d1257"
  },
  {
    "name": "1.txt",
    "mtime": 1708612057,
    "nodeid": "492cc7f1f79e6c270855cbf917a254e7",
    "mode": 4097,
    "size": 9,
    "hash": "7d5e985e0b5fee68b1b688f52632cdbabad9d7aa"
  }
]
  • "name" — название файла/папки;
  • "mtime" — дата последнего обновления;
  • "mode" и "nodeid" — метаданные;
  • "size" — размер файла в битах;
  • "hash" — хэш от содержимого файла.

Внимание

Файлы размером менее 20 байт не сохраняются в папку с бэкапом, а в файле tree.json в поле hash записывается содержимое файла в формате Base64.

Все файлы в этом примере находятся внутри папки Календарь. Также можно заметить, что у файлов 1A46632B-.jpeg и 1B606A7D-.jpeg одинаковое значение в поле hash — значит это одинаковые файлы.

В интерфейсе облака это выглядит так:

disk-exmp

Чтобы сопоставить файл из папки с бэкапом с файлом в tree.json:

  1. Скопируйте значение в поле hash.
  2. Сконвертируйте это значение из Base64 в Hex. Например, с помощью: https://base64.guru/converter/decode/hex.

  3. Полученное значение — это файл в папке.

    hex hex2

Восстановить данные в облаке

Выполните следующую команду:

./bmwclient -server bmw.%domain% -method cloudRestore \
  -token %token% -email %email% -readPath %backups_dir%
  • -email — email-адрес почтового ящика, для которого выполняется восстановление.
  • -readPath — путь до папки или zip-архива, в которой находится копия облака.

Пример запроса:

./bmwclient -server bmw.domain1.on-premise.ru -method cloudRestore \
  -token JleaQ8dNU0UBX6oaugaWmJ12vaaFp9Sa -email n.gruzdev@wm2.on-premise.ru \
  -readPath ./backups/n.gruzdev@wm2.on-premise.ru-1695212742

Результат:

[INFO]: 2023/09/21 10:19:09 backend address is: bmw.domain1.on-premise.ru:443,
 method is: cloudRestore

Результат, если указан путь до zip-архива:

[INFO]: 2023/09/21 10:19:09 backend address is: bmw.domain1.on-premise.ru:443,
 method is: cloudRestore
[INFO]: 2023/12/08 17:09:49 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
tree.json
[INFO]: 2023/12/08 17:09:49 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
ce6b1c9881e86da69491a7fb1ea4ee8389be2bca
[INFO]: 2023/12/08 17:09:49 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
8ac8a3b6100a4b087630df8ec086bd6e96581d86
[INFO]: 2023/12/08 17:09:50 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
f1bd71e8454f37762b84f1ad78edecff59bf1414
[INFO]: 2023/12/08 17:09:50 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
dbb9c3ce2f14e98016cba2e2f37725bc8b97a639
[INFO]: 2023/12/08 17:09:50 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
b4ea03212c7a351c3a23cf6c72df30dec9e7182c
[INFO]: 2023/12/08 17:09:50 unzipping tmp/n.gruzdev@wm2.on-premise.ru-1702027656/
6d132b4b6f452af4a81f88dec65848ba66a11cbc
[INFO]: 2023/12/08 17:09:50 deleted temp directory ./tmp/

Внимание

Если в одной директории с zip-архивом есть папка с таким же названием, то запрос не выполнится — нужно переместить папку:

[FATAL]: 2023/12/08 17:09:37 target directory ./tmp/n.gruzdev@wm2.on-premise.ru-1702027656 is not empty