Установка Wimark One - HA

Предустановка

Для установки платформы Wimark One необходимо 2 сервера с предустановленной ОС на базе Linux.
В случае L2 связности - схема Intra DC, в случае L3 связности - Inter DC.

Для корректной работы ПО и для подключения ТД в Firewall необходимо открыть следующие порты:

TCP: 80 / 443 (DST) - для управления через WEB-интерфейс;
UDP: 500 / 4500 (DST) - для туннеля IPSec между ТД и платформой (ТД подключается по ipsec);
TCP: 8080 / 8443 (DST) - для портала авторизации пользователей (для Portal модуля);
TCP: 1883 (DST) - для подключения ТД без туннеля (MQTT)
Убедится, что TCP: 30001 и 30003 - открыты (MongoDB)

Далее необходимо выполнить следующие действия на двух машинах:

Включить Forwarding трафика (sysctl):

echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.conf
echo "net.ipv4.ip_nonlocal_bind = 1" >> /etc/sysctl.conf # sysctl -p

Выполнить настройку перенаправления трафика:

iptables -P FORWARD ACCEPT

Установить пакет keepalived:

sudo apt update && sudo apt install keepalived

Настроить канал между серверами и выделить отдельный адрес из подсети для VIP

VIP - виртуальный IP.

Используется keepalived. К этому адресу должны будут подключаться ТД, и по данному IP всегда будет доступен Master/Active сервер.

Установка Docker

Для установки Docker необходимы права суперпользователя/root

Войти под пользователем root следующей командой:

sudo su

2. Установить Docker на сервер:

curl -sSl https://get.docker.com | sh

Можно выполнить установку через apt-репозиторий. Далее, в качестве примера, приведена установка через apt-репозиторий для Ubuntu 22.04.

Обновить список для актуализации установочных пакетов:

sudo apt-get update

2. Установить набор пакетов, который необходим для доступа к репозиторию docker:

sudo apt-get install ca-certificates curl gnupg

3. Добавить GPG-key для работы с официальным репозиторием Docker:

sudo install -m 0755 -d /etc/apt/keyrings 
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | 
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg

4. Добавить официальный репозиторий Docker в локальный список (копировать эту команду необходимо полностью):

echo \
 "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
 $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. Обновить список и установить пакеты и запустить Docker:

sudo apt-get update 
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin 
systemctl start docker

При необходимости установки каким-либо другим способом, либо на другую ОС, на сайте https://docs.docker.com/engine/install/ есть подробные инструкции для установки.

Настройка беспарольного доступа между серверами

ВАЖНО! Это необходимо выполнить на двух машинах!

Необходимо создать нового пользователя - one

adduser one

2. Добавить пользователя one в суперпользователей:

sudo usermod -a -G sudo one

3. Войти в систему под этим пользователем:

su one

4. Сгенерировать ssh ключ:

ssh-keygen -t rsa

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

Запрос о введении кодовой фразы можно пропустить (может помешать автоматизации некоторых процессов).

Далее в выводе указывается место, где хранятся ID и открытый ключ.

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 1.png

Рисунок 1 - Пример вывода команды ssh-keygen

5. Скопировать ssh-ключ на указанный сервер:

ssh-copy-id one@{IP}

{IP} - IP сервера, куда будет скопирован ключ.

После завершения, следует убедиться, что действительно получилось сделать беспарольный доступ между двумя серверами.
Для этого необходимо под пользователем one с одного сервера подключиться ко второму.
Тоже самое и со второго сервера на первый.
ssh one@{IP}

Если при подключении запрос пароля не поступил, то всё работает правильно.

Настройка /etc/hosts для работы БД

Необходимо настроить /etc/hosts таким образом, чтобы резолвились хосты для работы базы данных.

ВАЖНО! Это необходимо выполнить на двух машинах!

Войти в режим редактирования файла /etc/hosts:

sudo nano /etc/hosts

CTRL + S - сохранить изменения в файле.

CTRL + X - выйти из редактора.

Выполнить настройки:

# Настройки для 1-й машины:
127.0.0.1 localhost mongo-rs-1 
{IP-2} mongo-rs-2 
{VIP} mongo-rs-3 

# Настройки для 2-й машины: 
127.0.0.1 localhost mongo-rs-2 
{IP-1} mongo-rs-1 
{VIP} mongo-rs-3

{IP-1/2} - адрес машины.

{VIP} - виртуальный IP, используемый сервисом keepalived.

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 2.png

Рисунок 2 - Пример настроенного файла /etc/hosts

Установка ПО Wimark One

Необходимо загрузить дистрибутив Wimark One на сервера, где планируется установка ПО.

ВАЖНО! Это необходимо выполнить на двух машинах!

Загрузить дистрибутив Wimark One на сервер (при наличии доступа в Интернет):

wget https://storage.wimark.com/api/public/dl/XZqjHaJe \
 -O /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run 
sudo chmod +x /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run

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

# Команды для 1-й машины: 
sudo FIRST_IP={IP-1} SECOND_IP={IP-2} VIP={VIP} NEIGHBOR_IP={IP-2} bash /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run 

# Команды для 2-й машины: 
sudo FIRST_IP={IP-1} SECOND_IP={IP-2} VIP={VIP} NEIGHBOR_IP={IP-1} bash /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run

/tmp/ - каталог в котором хранятся временные файлы. Файлы удаляются спустя определенное время и после перезагрузки сервера.

{IP-1/2} - адрес машины.

{VIP} - виртуальный IP используемый сервисом keepalived.

https://storage.wimark.com/api/public/dl/XZqjHaJe - пример ссылки на прошивку.

WiMark-ha-1.11.0-2023-10-30-qtech-installer.run - пример имени файла, может отличаться в зависимости от сборки и версии ПО.

Во время установки будет предложено заполнить FQDN (рисунок 3).

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 3.png

Рисунок 3 - Запрос FQDN

Следует указать FQDN. Если FQDN использоваться не будет, то можно указать любое доменное имя, например: one.mydomain.com.

FQDN (Fully Qualified Domain Name) полное доменное имя определяющее узел в сети Интернет (имя домена, на которое будет реагировать веб-сервер).

После установки основных компонентов будет предложено установить SMTP (рисунок 4).

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 4.png

Рисунок 4 - Запрос установки SMTP

Следует указать: y - для запуска установки, N - для отказа от установки.

Simple Mail Transfer Protocol (SMTP) - простой протокол передачи почты, применяемый для пересылки электронных писем с сервера отправителя на сервер получателя.

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 5.png

Рисунок 5 - Пример заполнения установщика SMTP

SMTP_HOST - имя хоста или IP-адрес SMTP-сервера, который будет отправлять сообщения.

SMTP_PORT - номер порта для подключения к SMTP-серверу, по умолчанию 25.

SMTP_USER - логин УЗ для SMTP.

SMTP_PASS - пароль УЗ для SMTP.

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

Настройка keepalived

ВАЖНО! Это необходимо выполнить на двух машинах!

Создать скрипт: /opt/wimark/checker.sh

sudo nano /opt/wimark/checker.sh

CTRL + S - сохранить изменения в файле.

CTRL + X - выйти из редактора.

2. Вставить содержимое в файл:

#!/bin/bash
STATE="$(cat /opt/wimark/ha_state)"
LOG_STR="$(date) $STATE"
WORKDIR="/opt/wimark"
case $STATE in
    "MASTER")
        cd $WORKDIR/master
        bash start.sh
        LOG_STR="$LOG_STR: start master"
        ;;
    "BACKUP")
        cd $WORKDIR/backup
	bash start.sh
        LOG_STR="$LOG_STR: start backup"
        ;;
    "FAULT")
        LOG_STR="$LOG_STR: fault"
        ;;
    *)
        LOG_STR="$LOG_STR: unknown"
        ;;
esac
echo $LOG_STR >> /var/log/wimark-keepalived.log

3. Создать скрипт: /opt/wimark/set_state.sh

sudo nano /opt/wimark/set_state.sh

CTRL + S - сохранить изменения в файле.

CTRL + X - выйти из редактора.

4. Вставить содержимое в файл:

#!/bin/bash
TYPE=$1 NAME=$2 STATE=$3
LOG_STR="$(date) $STATE"
WORKDIR="/opt/wimark"
LOCK_FILE="ha_state"

case $STATE in
    "MASTER")
        echo "$STATE" > $WORKDIR/$LOCK_FILE
        LOG_STR="$LOG_STR: start primary"
        ;;
    "BACKUP")
        echo "$STATE" > $WORKDIR/$LOCK_FILE
	    LOG_STR="$LOG_STR: start secondary"
        ;;
    *)
	    echo "$STATE" > $WORKDIR/$LOCK_FILE
        LOG_STR="$LOG_STR: nothing"
        ;;
esac

5. Сделать эти скрипты исполняемыми:

sudo chmod +x /opt/wimark/checker.sh
sudo chmod +x /opt/wimark/set_state.sh

keepalived.conf для MASTER (первая машина)

sudo nano /etc/keepalived/keepalived.conf

ВАЖНО! Переменные в данном файле необходимо заполнить самостоятельно.

Необходимо изменить:

{VIP} - виртуальный IP для keepalived
{PASSWORD} - пароль.
{INTERFACE} - интерфейс соединяющий 2 машины между собой.

global_defs {
    script_user root
    #enable_script_security
}

# Имя VRRP - WIM1
vrrp_instance WIM1 {

    # Имя интерфейса на котором работает VRRP: eth0 
    # ПОМЕНЯТЬ ИМЯ ИНТЕРФЕЙСА НА ТОТ, КОТОРЫМ СОЕДЕНИНЫ МАШИНЫ!!!
    interface {INTERFACE} 

    # Изначальное состояние текущей машины: MASTER или BACKUP
    state MASTER

    # уникального сегмента VRRP
    # Если в вашей сети уже используется VRRP, то проверьте, чтобы ID был уникальным (должен совпадать с backup!)
    virtual_router_id 120

    # preempt - Всегда назначать MASTER ту машину, которая имеет более высокий приоритет (если возможно)
    # nopreempt - Не изменять состояние после выхода из аварийного состояния
    # nopreempt

    garp_master_delay 1
    priority 200
    advert_int 1

    # Метод аутентификации и пароль (пароль может содержать максимум 8 символов)
    authentication {
        auth_type PASS
        auth_pass {PASSWORD}
    }

    # Виртуальный IP (VIP)
    virtual_ipaddress {
        # ПОМЕНЯТЬ IP И ИМЯ ИНТЕРФЕЙСА НА ТЕ, КОТОРЫЕ БЫЛИ УКАЗАННЫ КАК VIP ПРИ УСТАНОВКЕ!!!
        {VIP}/24 dev {INTERFACE} 
    }

    # Скрипт, который будет запускаться при изменении STATE - НЕ ТРОГАТЬ!
    notify /opt/wimark/set_state.sh
}

keepalived.conf для BACKUP (вторая машина)

sudo nano /etc/keepalived/keepalived.conf

ВАЖНО! Переменные в данном файле необходимо заполнить самостоятельно.

Необходимо изменить:

{VIP} - виртуальный IP для keepalived
{PASSWORD} - пароль.
{INTERFACE} - интерфейс соединяющий 2 машины между собой.

global_defs {
    script_user root
    #enable_script_security
}

# Имя VRRP - WIM2
vrrp_instance WIM2 {

    # Имя интерфейса на котором работает VRRP: eth0
    # ПОМЕНЯТЬ ИМЯ ИНТЕРФЕЙСА НА ТОТ, КОТОРЫМ СОЕДЕНИНЫ МАШИНЫ!!!
    interface {INTERFACE}

    # Изначальное состояние текущей машины: MASTER или BACKUP
    state BACKUP

    # ID уникального сегмента VRRP
    # Если в вашей сети уже используется VRRP, то проверьте, чтобы ID был уникальным (должен совпадать с master!)
    virtual_router_id 120

    # preempt - Всегда назначать MASTER ту машину, которая имеет более высокий приоритет (если возможно)
    # nopreempt - Не изменять состояние после выхода из аварийного состояния
    # nopreempt

    garp_master_delay 1
    priority 200
    advert_int 1

    # Метод аутентификации и пароль (пароль может содержать максимум 8 символов)
    authentication {
        auth_type PASS
        auth_pass {PASSWORD}
    }

    # Виртуальный IP (VIP)
    virtual_ipaddress {
        # ПОМЕНЯТЬ IP И ИМЯ ИНТЕРФЕЙСА НА ТЕ, КОТОРЫЕ БЫЛИ УКАЗАННЫ КАК VIP ПРИ УСТАНОВКЕ!!!
        {VIP}/24 dev {INTERFACE} 
    }

    # Скрипт, который будет запускаться при изменении STATE - НЕ ТРОГАТЬ!
    notify /opt/wimark/set_state.sh
}

Запуск платформы

Запустить платформу через скрипты:

# Для 1-й машины - MASTER
cd /opt/wimark/master/; sudo bash start.sh

# Для 2-й машины - BACKUP
cd /opt/wimark/backup/; sudo bash start.sh

2. Создать crontab для периодического запуска checker

ВАЖНО! Это необходимо выполнить на двух машинах!

3. Открыть список задач cron для пользователя root:

sudo crontab -u root -e

Если будет выбор редактора для редактирования, то выбрать редактор nano (1).

CTRL + S - сохранить изменения в файле.

CTRL + X - выйти из редактора.

4. Записать в список задачи для запуска - /opt/wimark/checker.sh

* * * * * bash /opt/wimark/checker.sh
* * * * * sleep 10 && bash /opt/wimark/checker.sh
* * * * * sleep 20 && bash /opt/wimark/checker.sh
* * * * * sleep 30 && bash /opt/wimark/checker.sh
* * * * * sleep 40 && bash /opt/wimark/checker.sh
* * * * * sleep 50 && bash /opt/wimark/checker.sh

5. Сохранить изменения и проверить:

sudo crontab -u root -l

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 6.png

Рисунок 6 - Пример готового crontab

6. Перезапустить keepalived:

ВАЖНО! Это необходимо выполнить на двух машинах!

При первом запуске контейнеры на MASTER машине не будут корректно работать до тех пор, пока не запустятся контейнеры на BACKUP машине.

service keepalived restart

Проверка работоспособности

Для контроля работоспособности Wimark One пользователю следует перейти на web интерфейс платформы. При успешном завершении установки отобразится форма авторизации в соответствии с рисунком 7.

Логин/пароль по умолчанию: wimark/wimark

Документация Wimark > Wimark One: установка и обновление на свои сервера (HA)_1.11 > 1-1.png

Рисунок 7 - Форма авторизации

Обновление Wimark One - HA

Процесс обновления Wimark One представляет собой: удаление старых компонентов и установку новой версии платформы.
Если нет необходимости в переносе старых данных (статистики, SSID, настроек ТД и т.д.), то необходимо только удалить старую версию платформы, а затем установить новую версию в соответствии с инструкцией.

Создание резервных копий

Перед созданием резервной копии БД необходимо убедиться в том, что на сервере достаточно свободного места.
Для создания резервной копии платформы Wimark One рекомендуется иметь минимум 6G свободного места.

Есть два варианта создания резервной копии БД: полное и частичное.
При создании частичной резервной копии копируется только конфигурация (локации, настройки), лицензионный ключ и static файлы. Использование данного метода значительно ускоряет сам процесс восстановления БД и уменьшает размер резервной копии БД.

При создании полной резервной копии БД копируются все данные, т.е. статистика, конфигурация, static, ключ и т.д. Использование данного метода гарантирует полное копирование данных, но значительно замедляет процесс восстановление БД, и сама резервная копия БД занимает довольно много места.

Создания полной резервной копии

Создать резервную копию БД:

Достаточно выполнить только на одной машине!

docker exec -it  $(docker ps | grep 'one-mongo-1\|one-mongo-ha-1' | \
 awk '{ print $1;}') mongodump --port 30001 --db=test --gzip --archive=/tmp/backup_wimark.gz

Failed: error creating intents to dump: error getting collections for database test: (NotPrimaryOrSecondary) node is not in primary or recovering state

БД должна быть PRIMARY, данное состояние может не совпадать с MASTER/BACKUP самой машины.
Поэтому при получении данной ошибки, следует повторить этот шаг на другой машине.

Если имя контейнера с MongoDB отличается от того, что указано в команде, то можно использовать docker ps для поиска нужного контейнера.

2. Создать папку для резервной копии:

sudo mkdir /opt/wimark_backup/

3. Копировать архив с резервной копией БД из контейнера в систему:

docker cp $(docker ps | grep 'one-mongo-1\|one-mongo-ha-1' | \
 awk '{ print $1;}'):/tmp/backup_wimark.gz /opt/wimark_backup/

4. Создать резервную копию static файлов, которые находятся в папке /opt/wimark/static:

cp -r /opt/wimark/static /opt/wimark_backup/static

Если версия Wimark One ниже 1.10, то файлы будут находится каталоге /usr/share/wimark/static

Создание частичной резервной копии

Создать резервную копию БД без коллекций со статистикой:

docker exec -it $(docker ps | grep 'one-mongo-1\|one-mongo-ha-1' | \
 awk '{ print $1;}') bash
mongodump --port 30001 --db=test --excludeCollection=bss_stat_info \
 --excludeCollection=client_stat_info --excludeCollection=client_stats \
 --excludeCollection=cpe_stat_info --excludeCollection=stats \
 --excludeCollection=wlan_stat_info --gzip --archive=/tmp/backup_wimark.gz; exit

Failed: error creating intents to dump: error getting collections for database test: (NotPrimaryOrSecondary) node is not in primary or recovering state

БД должна быть PRIMARY, данное состояние может не совпадать с MASTER/BACKUP самой машины.
Поэтому при получении данной ошибки, следует повторить этот шаг на другой машине.

2. Копировать архив с резервной копией БД из контейнера в систему:

docker cp $(docker ps | grep 'one-mongo-1\|one-mongo-ha-1' | \
 awk '{ print $1;}'):/tmp/backup_wimark.gz /opt/wimark_backup/

3. Создать резервную копию static файлов, которые находятся в папке /opt/wimark/static:

cp -r /opt/wimark/static /opt/wimark_backup/static

Обновление ПО и перенос БД

Обновление ПО

Перед удалением старой версии ПО необходимо скопировать скрипты и остановить сервис cron:

ВАЖНО! Это необходимо выполнить на двух машинах!

sudo mkdir /opt/wimark_backup/
cp /opt/wimark/set_state.sh /opt/wimark_backup/set_state.sh
cp /opt/wimark/checker.sh /opt/wimark_backup/checker.sh
sudo service cron stop

2. Затем полностью удалить старую платформу:

sudo su
rm -r /opt/wimark; docker rm -f $(docker ps -qaf "name=one-|master|backup|one_")

Если версия Wimark One ниже 1.10, то файлы будут находится в каталоге /etc/wimark

Если на сервере в docker используется только Wimark One, то можно дополнительно выполнить эту команду:

docker system prune --all --volumes

Данная команда удалит все остановленные контейнеры, “висящие” (неиспользуемые) Docker-образы, неиспользуемые сети и тома. Поэтому следует использовать данную команду только в том случае, если в Docker устанавливалось только ПО Wimark One.

3. Скачать новую версию ПО на сервер и запустить установку:

wget https://storage.wimark.com/api/public/dl/XZqjHaJe \
  -O /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run
sudo chmod +x /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run

4. Для запуска установки необходимо выполнить:

4.1. Запустить установку на 1-й машине:

sudo FIRST_IP={IP-1} SECOND_IP={IP-2} VIP={VIP} NEIGHBOR_IP={IP-2} /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run

4.2. После окончания переустановки, необходимо будет полностью перезагрузить сервер:

reboot

4.3. Запустить установку на 2-й машине:

sudo FIRST_IP={IP-1} SECOND_IP={IP-2} VIP={VIP} NEIGHBOR_IP={IP-1} /tmp/WiMark-ha-1.11.0-2023-10-30-qtech-installer.run

4.4 После окончания переустановки, необходимо будет полностью перезагрузить сервер:

reboot

5. Перенести ранее скопированные скрипты:

cp /opt/wimark_backup/set_state.sh /opt/wimark/set_state.sh
cp /opt/wimark_backup/checker.sh /opt/wimark/checker.sh

/tmp/ - каталог в котором хранятся временные файлы. Файлы удаляются спустя определенное время и после перезагрузки сервера.

{IP-1/2} - адрес машины.

{VIP} - виртуальный IP используемый сервисом keepalived.

https://storage.wimark.com/api/public/dl/XZqjHaJe - пример ссылки на прошивку.

WiMark-ha-1.11.0-2023-10-30-qtech-installer.run - пример имени файла, может отличаться в зависимости от сборки и версии ПО.

6. Запускаем сервис cron:

sudo service cron start

Перенос БД

После того, как платформа завершила инициализацию и полноценно работает, необходимо принудительно остановить контейнер backend на MASTER ноде. Остановить cron для того, чтобы контейнер не смог переподняться по скрипту:

sudo service cron stop

2. Остановить контейнер:

docker stop $(docker ps | grep 'backend-golang-1' | awk '{ print $1;}')

3. Копировать ранее созданную резервную копию БД в контейнер mongo:

docker cp /opt/wimark_backup/backup_wimark.gz $(docker ps | \
 grep 'one-mongo-1\|one-mongo-ha-1' | awk '{ print $1;}'):/tmp/

4. Запустить процесс восстановления из резервной копии:

docker exec -it $(docker ps | grep 'one-mongo-1\|one-mongo-ha-1' | \
 awk '{ print $1;}') mongorestore --port 30001 --drop --nsInclude='test.*' \
 --gzip --archive=/tmp/backup_wimark.gz

--drop - перезаписывает текущие данные в БД.

В зависимости от размеров коллекций и технических характеристик машины, этот процесс может занять от нескольких минут до нескольких часов!

5. Удалить новые и перенести старые файлы static:

rm -r /opt/wimark/static
cp -r /opt/wimark_backup/static /opt/wimark/

6. Запустить контейнер отвечающий за backend:

docker start $(docker ps | docker ps -a | grep 'backend-golang-1' | \
 awk '{ print $12;}')

7. Запускаем сервис cron:

sudo service cron start

Проверить работоспособность платформы в соответствии с разделом Проверка работоспособности