KROS-GATE
Шлюз КРОС
Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!

________________


Общие сведения
==============

Программное обеспечение (далее - ПО) KROS-GATE представляет собой сервер, 
предназначенный для приема входного потока сообщений в формате протоколов ПК4 и 
ПК5 по TCP или UDP протоколу, преобразования его в поток в формате Surgard и 
передачи по протоколу TCP на внешний приемник.

С целью минимизации потребляемых ресурсов ПО не имеет оконного интерфейса, а все 
настройки выполняются модификацией конфигурационный файлов с помощью любого 
текстового редактора, поддерживающего кодировку UTF-8.

Технические требования
======================

Для работы ПО KROS-GATE необходим

* Компьютер, подключенный к сети Internet,
* Операционная система Linux x64 или MS Windows x64,
* Минимум 2 ГБ оперативной памяти,
* Минимум 32 ГБ дискового пространства.

На компьютере должна быть установлена Java Runtime Edition (JRE) x64 версии не 
ниже 8.

Описание состава пакета
=======================

ПО KROS-GATE поставляется в виде набора файлов, содержащего все необходимые 
средства для установки, запуска в качестве сервера, управления и настройки. 

Файлы:
* kros-gate.jar - основное приложение
* kros-gate.sh - служебное приложение для установки и запуска ПО под Linux
* service-install.sh - программа установки ПО под Linux
* service-uninstall.sh - программа удаления ПО из системы Linux
* prunsrv.exe - служебное приложение для установки и запуска ПО под MS Windows 
* service-install.cmd - программа установки ПО под MS Windows
* service-uninstall.cmd - программа удаления ПО из системы MS Windows
* *.key - файл ключа лицензии, генерируемый индивидуально для каждого 
  статического IP адреса, на котором будет работать сервер. Может быть получен 
  позже.
* version.txt - текстовый файл содержащий номер версии ПО
* whatsnew.txt - текстовый файл содержащий сведения об изменениях в поставляемой 
  версии ПО

Папки:
* conf - сюда будут помещены файлы конфигурации. Изначально папка содержит файл 
  keystroke.jks предназначенный для поддержки SSL протокола.
* lib - (может отсутствовать) файлы библиотек, необходимых для работы ПО.
* logs - сюда будут помещаться отладочные протоколы в процессе работы ПО под 
  MS Windows. При работе под Linux протоколы располагаются в папке 
  /var/log/kros-gate.



________________




Развертывание и запуск
======================

Предполагается, что перед началом развертывания были подтверждены технические 
требования к компьютеру, на компьютере установлена совместимая 64-битная 
операционная система и Java Runtime Edition (JRE) версии не ниже 8.

Linux
=====

На примере Debian/Ubuntu/Mint

Установка
---------

Для установки под Linux необходимо обладать root правами, либо состоять в группе 
sudo (sudoers).

Если дистрибутив ПО получен в виде zip архива - необходимо его распаковать в 
любую подходящую папку. Убедитесь что скрипты service-install.sh и 
service-uninstall.sh имеют разрешение на запуск (744).  Если нет - выполните 
команду:

  $ chmod +x service*.sh

Запускаем скрипт service-install.sh. Скрипт осуществляет следующие действия:

1. Копирует необходимый набор файлов в рабочую папку /opt/kros-gate,
2. Создает папку /var/log/kros-gate и настраивает ПО для записи файлов 
   протоколов работы в эту папку,
3. Создает файл управления сервисом /etc/init.d/kros-gate


Регистрация
-----------

Для работы ПО его необходимо зарегистрировать на сервере лицензирования. Это 
делается один единственный раз при первой установке ПО и требует выхода в 
интернет по HTTP (порт TCP 80). Осуществляется однократное соединение на 
единственный адрес jupiter8.ru.

Если Вы не получали лицензионный ключ, то в процессе регистрации Вы получите 
временную пробную лицензию для Вашего внешнего IP адреса с полным функционалом, 
но с ограниченным сроком (обычно 30 дней) и количеством приборов (обычно 10 
приборов) для возможности тестирования.

Если у Вас есть лицензионный ключ для вашего IP адреса или доменного имени 
(текстовый файл с расширением .key) - перед регистрацией необходимо поместить 
его в папку установки ПО (в нашем случае /opt/kros-gate).

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

  $ sudo /etc/init.d/kros-gate register

ПО выведет на экран результат процесса регистрации:

  KrosGate, Version 2.3.45.34
  Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!
  Определен адрес для контроля лицензии: 5.17.161.234
  Соединение с сервером лицензирования...
  Проверка файла лицензии 2017-06-08-122028-5.17.161.234.key...
  Лицензия 2017-06-08-122028-5.17.161.234.key принята сервером лицензирования
  Тариф: Базовый, 0.0 руб/мес, 250 приборов, 3 охр. орг. [RCUdpPK4Jupiter, RCTcpPK4Jupiter, RCGsmModem, RCArmGZ, RCArmSK, RCArmUpdater, TRArmSK, TRCsvWriter, TRRawSender]
  Тарифная опция: SurGard, 0.0 руб/мес [RCTcpSurgard, RCTcpSurgardDecID, TRTcpSurgard, TRTcpSurgardV4, TRF1Com, TRF1ComImei]
  Тарифная опция: Тревожная кнопка, 0.0 руб/мес [RCAlarmButton, TRUmkaWatch, TRUmkaWatch]
  Тарифная опция: Личный кабинет, 0.0 руб/мес [RCCustomerAccount, TRCustomerAccount]
  Тарифная опция: SMPP, 0.0 руб/мес [TRSmsSMPP]
  Тарифная опция: Зеркалирование, 0.0 руб/мес [RCTcpEPPS, RCUdpEPPS, TRTcpEPPS]
  Регистрация прошла успешно. Активный UDP порт: 10000
  Регистрация версии сервера...
  Регистрация версии сервера завершена

Как видно на экране  - ПО определяет внешний IP адрес сервера, проверяет 
актуальность лицензионного ключа и выводит подробности тарифа обслуживания, 
связанного с лицензией.

Пробный запуск
--------------

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

  $ sudo /etc/init.d/kros-gate start

Сервер будет запущен. Для проверки состояния сервера запустите команду:

  $ sudo /etc/init.d/kros-gate status

На экран будет выведена следующая информация:

  kros-gate (pid 27399) is running...
  KrosGate, Version 2.3.45.34
  Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!
  Соединение с сервером...


  Состояние сервера на 03.10.2018 16:37:19


                Лицензия: OOO Элеста, Отдел ПО2
    Дата выдачи лицензии: 08.06.2017 09:20:28
          Дата активации: 08.06.2017 09:20:28
          Дата окончания: 24.10.2044 09:20:28
                   Тариф: Базовый
       Ограничение срока: Без ограничений
Допустимое к-во приборов: 250


          Всего приборов: 0
         Из них на связи: 0
        Входящая очередь: 0 пакетов
       Исходящая очередь: 0 пакетов


        Всего приемников: 2


        Драйвер приемник: UdpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: UDP
                   Порты: 10000


        Драйвер приемник: TcpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: TCP
                   Порты: 10000


                Всего трансляций: 1


              Транслятор: TestBroadcast
                 Активен: true
      Драйвер передатчик: TcpSurgard
          Размер очереди: 0 пакетов
         Последний пакет: 01.01.1970 03:00:00


В данной информации нас больше всего интересуют порты приемников, на которые 
настраиваются приборы. Здесь видно, что для TCP и UDP приемников драйверов 
ППКОП/УОО установлены порты 10000. Скорее всего возникнет необходимость их 
поменять.

Остановим сервер, выполнив команду: 

  $ sudo /etc/init.d/kros-gate stop




Настройки системы
=================

Базовые настройки ПО содержатся в текстовом файле conf/kros.properties. Для его 
редактирования можно использовать любой текстовый редактор, поддерживающий 
кодировку UTF-8, например:

  $ sudo nano /opt/kros-gate/conf/kros.properties


Параметры базовой конфигурации (файл kros.properties)
-----------------------------------------------------

  db.name=jupiter.db
  db.password=jupiter
  db.path=/opt/kros-gate/conf
  db.username=jupiter

Настройки размещения и параметров соединения с оперативной базой данных. 
Изменять не рекомендуется! По умолчанию база данных находится в папке 
/opt/kros-gate/conf. При необходимости (например при увеличении объема больше 
ожидаемого) файл базы данных может быть перенесен. В этом случае здесь 
необходимо указать его новое местоположение. 

  include=devices,broadcast

Подключение внешних файлов конфигурации приборов и трансляторов. 
Изменять не рекомендуется!

  killer.last.start=2018-10-03 16:36:32
  killer.start.at=03:00
  killer.storage.period=1440

Настройки очистки базы данных. Поток данных, получаемых с прибора, для 
обеспечения гарантированной доставки записывается в оперативную базу данных. 
Очистка устаревших записей происходит один раз в сутки в указанное в настройках 
время. За это отвечает параметр killer.start.at. Данные хранятся в течение 
периода, указанного в параметре killer.storage.period (в минутах). Период 
отсчитывается от момента сохранения записи в базу данных. Параметр 
killer.last.start является служебным, служит для расчета времени старта очистки 
и обновляется автоматически после каждого ее запуска.

  receiver.TcpPK4Jupiter.active=true
  receiver.TcpPK4Jupiter.ports=10000
  receiver.UdpPK4Jupiter.active=true
  receiver.UdpPK4Jupiter.ports=10000

Раздел настроек драйверов приемников для приборов ППКОП/УОО (ПК4/ПК5).  Для 
каждого драйвера можно определить его активность и список прослушиваемых 
системой портов. Указанные выше настройки означают что ПО будет ожидать 
соединение от приборов на портах TCP 10000 и UDP 10000.

  receiver.UdpRoot.active=true
  receiver.UdpRoot.auto=true
  receiver.UdpRoot.ports=10000
  receiver.UdpRoot.ssl=false

Настройки служебного драйвера, обеспечивающего основной функционал работы с 
обновлением версии, получения информации о состоянии ПО, работы с лицензиями. 
Изменять не рекомендуется!

  server.log.count=3
  server.log.path=/var/log/kros-gate
  server.log.size=64000000

Параметры настройки протоколирования. В процессе работы ПО записывает подробный 
протокол, который может оказаться незаменим при сбоях, восстановлении данных, 
поиске причин неисправностей. При продолжительной работе размер файлов 
протоколов может возрасти до недопустимого значения. Для решения этой проблемы 
предназначены эти параметры. Значение server.log.size определяет максимальный 
размер одного файла протокола. Если размер превышает ограничение будет создана 
резервная копия текущего файла протокола, его размер будет обнулен. Параметр 
server.log.count определяет количество одновременно хранимых резервных копий. 
При создании очередной копии при превышении ограничения количества самая старая 
копия будет удалена. Параметр server.log.path определяет место хранения файлов 
протокола.

  server.threads.max.udp=1000
  server.udp.buffersize=8192

Служебные параметры оптимизации работы с UDP соединениями. Изменять не 
рекомендуется!

  transmitter.TcpSurgard.active=true
  transmitter.TcpSurgardV4.active=true

Базовые параметры драйверов передатчиков. Определяют активность драйверов в 
системе. Если запретить какой-то из драйверов, то трансляторы, настроенные на 
работу с ним, запускаться не будут. Подробнее см. раздел по настройке 
трансляции.



Параметры трансляции (файл broadcast.properties)
------------------------------------------------

Если в системе не создано ни одного транслятора, то данные, поступающие от 
приборов, будут просто записываться в базу данных. Для передачи данных во 
внешнюю систему необходимо настроить параметры транслятора. 

Настройки трансляторов должны располагаться в файле conf/broadcast.properties 
который может быть открыт любым текстовым редактором: 

  $ sudo nano /opt/kros-gate/conf/kros.properties

Трансляторов может быть несколько. Различаются они своими условными именами. 
Принадлежность параметра тому или иному транслятору определяется префиксом 
заголовка. Например параметры

  broadcast.TestBroadcast.active=true
  broadcast.TestBroadcast.active.transmitter=TcpSurgard

относятся к транслятору с именем TestBroadcast. Параметры 

  broadcast.CoolestThing.connect.port=30000
  broadcast.CoolestThing.context.connect.address=192.168.1.88

относятся к транслятору с именем CoolestThing.


Параметры файла broadcast.properties:

  broadcast.TestBroadcast.active=true
  broadcast.TestBroadcast.active.transmitter=TcpSurgard

Активация транслятора и задание для него драйвера передатчика. В случае 
изменения параметра active на false транслятор останется в системе, но для него 
не будут поступать данные в очередь на передачу. Параметр active.transmitter 
задает используемый для трансляции драйвер передатчик. Количество и состав 
списка доступных драйверов зависит от конкретного комплекта поставки. В базовый 
комплект входят два драйвера для трансляции данных в формате Surgard - 
TcpSurgard (стандартный базовый протокол) и TcpSurgardV4 (протокол 4-й версии с 
идентификацией по IMEI).

  broadcast.TestBroadcast.context.connect.address=192.168.1.88
  broadcast.TestBroadcast.context.connect.port=30000
  broadcast.TestBroadcast.context.connect.ssl=false
  broadcast.TestBroadcast.context.connect.timeout=120000
  broadcast.TestBroadcast.context.connect.pingPeriod=10

Настройки соединения с внешней системой. Раздел, как видно, имеет префикс имени 
параметра connect. Для трансляторов Surgard предусмотрены следующие параметры:

* address - IP адрес приемника для TCP соединения,
* port - порт приемника для TCP соединения,
* ssl - переключатель режима SSL шифрования,
* timeout - таймаут соединения и ожидания данных для TCP протокола,
* pingPeriod - периодичность отправки PING пакетов принимающей стороне.

  broadcast.TestBroadcast.context.options.decimal=false
  broadcast.TestBroadcast.context.options.ignoreErrors=false
  broadcast.TestBroadcast.context.options.test=true

Параметры транслятора:

* decimal - определяет формат представления идентификатора прибора при 
  формировании пакета для передачи. true - идентификатор преобразуется к 
  десятичному формату, false - к шестнадцатеричному.
* ignoreErrors - способ реакции на ошибки. false - в случае возникновения ошибки 
  передачи пакет будет возвращено в очередь и попытки будут повторяться до 
  успешной отправки, true - после неудачной отправки пакет будет удален из 
  очереди.
* test - тестовый режим. Имитация полноценной работы транслятора без попыток 
  реального подключения к внешнему приемнику.

  broadcast.TestBroadcast.context.event.10121=false,E121,Тревога, принуждение
  broadcast.TestBroadcast.context.event.10122=false,E122,Тихая тревога
  broadcast.TestBroadcast.context.event.10123=false,E123,Тревога ШС
  broadcast.TestBroadcast.context.event.10137=false,E137,Взлом

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


broadcast.TestBroadcast.context.event.10141=false,E141,Обрыв ШС
          _____________               _____ _____ ____ ________
                |                       |     |    |     |
                |                       |     |    |     +- Текст сообщения
                |                       |     |    +- Код сообщения Surgard
                |                       |     +- Признак блокировки
                |                       +- Внутренний код сообщения
                +----------------- Наименование трансляции


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



Параметры приборов (файл devices.properties)
--------------------------------------------

Система принимает соединение от любых приборов, работающих по протоколу ПК4 или 
ПК5. Если на момент соединения прибор не зарегистрирован в базе данных то 
создается новая запись о приборе, его конфигурации и состоянии. Кроме того 
идентификационная информация сохраняется в файле devices.properties. Запись о 
приборе в этом файле имеет следующую структуру:


device.1111-1111-1111=234,0101010101010101010101010101010101010101010101010101010101010101
       ______________ ___ ________________________________________________________________
              |        |                              |
              |        |                              +------ Ключ шифрования
              |        +------------- Идентификатор прибора для пакета Surgard
              +---------------- Идентификатор в конфигурации прибора


Для модификации доступны Идентификатор для пакета Surgard и Ключ шифрования.

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

Ключ шифрования представляет собой 32-байтное значение, используемое для 
шифрования пакетов ПК4 и доступное для изменений в конфигураторе прибора. 
Для вновь подключаемых приборов предполагается значение ключа шифрования 
устанавливаемое при производстве прибора по умолчанию - 01010101… 
Необходимость изменения значения ключа в файле devices.properties может 
возникнуть в двух случаях:

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

ВНИМАНИЕ! Длина строки ключа шифрования должна быть ровно 64 символа и содержать 
только символы 16-го представления числа - 0..9,A,B,C,D,E,F.


Пример быстрой настройки транслятора ПК4 -> Surgard
===================================================

Предположим что ПО KROS-GATE корректно установлено, зарегистрировано и был 
произведен первый пробный запуск. К серверу не подключено ни одного прибора, 
трансляция не осуществляется ни на один внешний источник.


Настройка трансляции
--------------------

Предположим, в системе существует сервер стороннего производителя, который 
принимает данные в формате Surgard по протоколу TCP, расположенный по адресу 
локальной сети 192.168.1.99 и имеющий открытый порт 3300. Сервер может принимать 
все сообщения кроме E307 (Неизвестное сообщение, внутренний код 10307). Кроме 
того, событие Взлом (внутренний код 10137, код Surgard E137) должно быть 
преобразовано для него в код E138.

Останавливаем KROS-GATE командой:

  $ sudo /etc/init.d/kros-gate stop

Открываем  файл broadcasts.properties и корректируем в нем нужные строки. 
Включаем режим реального соединения (по умолчанию в трансляторе включен 
тестовый режим):

  broadcast.TestBroadcast.context.options.test=false


Задаем целевой адрес для трансляции с кодовым именем TestBroadcast:

  broadcast.TestBroadcast.context.connect.address=192.168.1.99

Задаем номер порта для соединения:

  broadcast.TestBroadcast.context.connect.port=3300

Корректируем таблицу преобразования потока данных:

  broadcast.TestBroadcast.context.event.10307=true,E307,Неизвестное сообщение
  ...
  broadcast.TestBroadcast.context.event.10137=false,E138,Взлом

Убеждаемся что принимающая сторона ожидает соединения и запускаем KROS-GATE:

  $ sudo /etc/init.d/kros-gate start

Даже при отсутствии данных от приборов при успешном соединении система должна 
начать отправлять PING пакеты принимающей стороне. Проверяем содержимое файла 
протокола /var/log/kros-gate/tr-TcpSurgard.log

  2018-10-04 17:22:09,103 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:12,104 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:14,105 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:16,106 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:18,107 [DEBUG] localhost:30000: PING Packet delivered

Мы видим сообщения о подтверждении успешной доставки PING пакетов.

Транслятор настраивается один раз и при положительном результате в дальнейшем 
обслуживании не нуждается.



Подключение нового прибора
--------------------------

Предположим внешний IP адрес нашего сервера 123.456.7.8, порт UDP 10000 доступен 
извне и сервер готов принимать соединения от приборов. 

С помощью конфигуратора устанавливаем в приборе параметры соединения (адрес 
123.456.7.8, порт 10000), запоминаем его идентификатор ID6 (например 
1234-5678-9012) и убеждаемся что ключ шифрования сброшен в значение по 
умолчанию - 01010101… 

Включаем прибор, дожидаемся на нем индикации подтверждения соединения, проверяем 
содержимое файла devices.properties:

  device.1234-5678-9012=1,0101010101010101010101010101010101010101010101010101010101010101

Видим, что прибор подключился к системе и получил идентификатор из базы данных 
со значением 1. Регистрируем прибор с таким идентификатором в принимающей 
системе и проверяем прохождение потока данных.

Изменяем ключ шифрования. Для этого останавливаем KROS-GATE и меняем значение 
ключа в файле devices.properties на свое:

  device.1234-5678-9012=1,01074E8501010101018CC4010101010101010101010101010323233101010101

Сохраняем файл и запускаем KROS-GATE. Проверяем прохождение потока данных на 
принимающей системе.


Подключение работающего прибора
-------------------------------

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

Прибор с неизвестным системе ключом шифрования не сможет подключиться и 
автоматически зарегистрироваться. Поэтому зарегистрируем его вручную. 
Останавливаем KROS-GATE, открываем файл devices.properties и добавляем строку:

  device.1234-5678-9012=753,01074E8501010101018CC4010101010101010101010101010323233101010101

Сохраняем файл и запускаем KROS-GATE. Проверяем прохождение потока данных на 
принимающей системе.

________________





MS Windows
===========

На примере MS Windows 10

Установка
---------

Если дистрибутив ПО получен в виде zip архива - необходимо его предварительно 
распаковать в любую подходящую папку, например Мои Документы. 

Откройте проводник, выберите папку куда был распакован архив, найдите файл 
service-install (Сценарий Windows), нажмите на нем правую кнопку мыши, выберите 
Запуск от имени администратора.

Будет запущено окно командной строки в котором будет отображен ход установки.

  Установка KrosGate...
  Копирование файлов в "C:\Program Files\kros-gate...
  Копирование управляющего приложения в C:\WINDOWS\system32...
  Установка сервиса kros-gate...
  Установка сервиса kros-gate завершена.
  Используйте команду :
     kros-gate register для регистрации лицензии
     kros-gate start для запуска сервиса
     kros-gate stop для остановки сервиса
  Для продолжения нажмите любую клавишу . . .

Скрипт осуществляет следующие действия:

1. Копирует необходимый набор файлов в основную программную папку 
   \Program Files\kros-gate,
2. Создает файл управления сервисом \Windows\system32\kros-gate.cmd

Для дальнейшей настройки и управления ПО KROS-GATE необходимо запустить окно 
командной строки в режиме администратора. Для этого откройте основное меню 
“пуск” и наберите на клавиатуре CMD. В появившемся окне быстрого поиска выберите 
курсором пункт “Командная строка” и нажмите CTRL-SHIFT-ENTER.

Также можно открыть административное окно командной строки нажав правую кнопку 
мыши на иконке основного меню “пуск” и выбрав пункт Командная строка 
(Администратор) или Windows PowerShell (Администратор).


Регистрация
-----------

Для работы ПО его необходимо зарегистрировать на сервере лицензирования. Это 
делается один единственный раз при первой установке ПО и требует выхода в 
интернет по HTTP (порт TCP 80). Осуществляется однократное соединение на 
единственный адрес jupiter8.ru.

Если Вы не получали лицензионный ключ, то в процессе регистрации Вы получите 
временную пробную лицензию для Вашего внешнего IP адреса с полным функционалом, 
но с ограниченным сроком (обычно 30 дней) и количеством приборов (обычно 10 
приборов) для возможности тестирования.

Если у Вас есть лицензионный ключ для вашего IP адреса или доменного имени 
(текстовый файл с расширением .key) - перед регистрацией необходимо поместить 
его в папку установки ПО (в нашем случае  \Program Files\kros-gate).

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

  PS C:\WINDOWS\system32> kros-gate register

ПО выведет на экран результат процесса регистрации:

  KrosGate, Version 2.3.45.38
  Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!
  Определен адрес для контроля лицензии: 5.17.161.234
  Соединение с сервером лицензирования...
  Проверка файла лицензии 2017-06-08-122028-5.17.161.234.key...
  Лицензия 2017-06-08-122028-5.17.161.234.key принята сервером лицензирования
  Тариф: Базовый, 0.0 руб/мес, 250 приборов, 3 охр. орг. [RCUdpPK4Jupiter, RCTcpPK4Jupiter, RCGsmModem, RCArmGZ, RCArmSK, RCArmUpdater, TRArmSK, TRCsvWriter, TRRawSender]
  Тарифная опция: SurGard, 0.0 руб/мес [RCTcpSurgard, RCTcpSurgardDecID, TRTcpSurgard, TRTcpSurgardV4, TRF1Com, TRF1ComImei]
  Тарифная опция: Тревожная кнопка, 0.0 руб/мес [RCAlarmButton, TRUmkaWatch, TRUmkaWatch]
  Тарифная опция: Личный кабинет, 0.0 руб/мес [RCCustomerAccount, TRCustomerAccount]
  Тарифная опция: SMPP, 0.0 руб/мес [TRSmsSMPP]
  Тарифная опция: Зеркалирование, 0.0 руб/мес [RCTcpEPPS, RCUdpEPPS, TRTcpEPPS]
  Регистрация прошла успешно. Активный UDP порт: 10000
  Регистрация версии сервера...
  Регистрация версии сервера завершена
  Для продолжения нажмите любую клавишу . . .


Как видно на экране  - ПО определяет внешний IP адрес сервера, проверяет 
актуальность лицензионного ключа и выводит подробности тарифа обслуживания, 
связанного с лицензией.


Пробный запуск
--------------

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

  PS C:\WINDOWS\system32> kros-gate start

Служба будет запущена:

  Запуск службы...
  Имя_службы: kros-gate
        Тип                : 10  WIN32_OWN_PROCESS
        Состояние          : 2  START_PENDING
                                (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
        Код_выхода_Win32   : 0  (0x0)
        Код_выхода_службы  : 0  (0x0)
        Контрольная_точка  : 0x0
        Ожидание           : 0x7d0
        ID_процесса        : 5364
        Флаги              :
  KrosGate, Version 2.3.45.38
  Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!
  Соединение с сервером...


  Состояние сервера на 05.10.2018 15:52:57


                Лицензия: OOO Элеста, Отдел ПО2
    Дата выдачи лицензии: 08.06.2017 09:20:28
          Дата активации: 08.06.2017 09:20:28
          Дата окончания: 24.10.2044 09:20:28
                   Тариф: Базовый
       Ограничение срока: Без ограничений
Допустимое к-во приборов: 250


          Всего приборов: 0
         Из них на связи: 0
        Входящая очередь: 0 пакетов
       Исходящая очередь: 0 пакетов


        Всего приемников: 2


        Драйвер приемник: UdpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: UDP
                   Порты: 10000


        Драйвер приемник: TcpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: TCP
                   Порты: 10000


        Всего трансляций: 1


              Транслятор: TestBroadcast
                 Активен: true
      Драйвер передатчик: TcpSurgard
          Размер очереди: 0 пакетов
         Последний пакет: 01.01.1970 03:00:00


  Для продолжения нажмите любую клавишу . . .


Для проверки состояния сервера запустите команду:

  PS C:\WINDOWS\system32> kros-gate status

На экран будет выведена следующая информация:

  KrosGate, Version 2.3.45.38
  Copyright (C) 2018, ELESTA LLC, Saint-Petersburg, Russia. All rights reserved!
  Соединение с сервером...


  Состояние сервера на 05.10.2018 15:55:24


                Лицензия: OOO Элеста, Отдел ПО2
    Дата выдачи лицензии: 08.06.2017 09:20:28
          Дата активации: 08.06.2017 09:20:28
          Дата окончания: 24.10.2044 09:20:28
                   Тариф: Базовый
       Ограничение срока: Без ограничений
Допустимое к-во приборов: 250


          Всего приборов: 0
         Из них на связи: 0
        Входящая очередь: 0 пакетов
       Исходящая очередь: 0 пакетов


        Всего приемников: 2


        Драйвер приемник: UdpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: UDP
                   Порты: 10000


        Драйвер приемник: TcpPK4Jupiter
                Описание: Драйвер ППКОП/УОО
                   Канал: PK4
                Протокол: TCP
                   Порты: 10000


        Всего трансляций: 1


              Транслятор: TestBroadcast
                 Активен: true
      Драйвер передатчик: TcpSurgard
          Размер очереди: 0 пакетов
         Последний пакет: 01.01.1970 03:00:00


  Для продолжения нажмите любую клавишу . . .

В данной информации нас больше всего интересуют порты приемников, на которые 
настраиваются приборы. Здесь видно, что для TCP и UDP приемников драйверов 
ППКОП/УОО установлены порты 10000. Скорее всего возникнет необходимость их 
поменять.

Остановим сервер, выполнив команду: 

  PS C:\WINDOWS\system32> kros-gate stop





Настройки системы
=================

Базовые настройки ПО содержатся в текстовом файле 
\Program Files\kros-gate\conf\kros.properties. Для его редактирования можно 
использовать любой текстовый редактор, поддерживающий кодировку UTF-8, в крайнем 
случае можно использовать блокнот Windows.


Параметры базовой конфигурации (файл kros.properties)
-----------------------------------------------------

  db.name=jupiter.db
  db.password=jupiter
  db.path=C:\Program Files\kros-gate\conf
  db.username=jupiter

Настройки размещения и параметров соединения с оперативной базой данных. 
Изменять не рекомендуется! По умолчанию база данных находится в папке 
\Program Files\kros-gate\conf. При необходимости (например при увеличении объема 
больше ожидаемого) файл базы данных может быть перенесен в том числе и на другой 
физический либо сетевой диск. В этом случае здесь необходимо указать его новое 
местоположение. 

  include=devices,broadcast

Подключение внешних файлов конфигурации приборов и трансляторов. Изменять не 
рекомендуется!

  killer.last.start=2018-10-03 16:36:32
  killer.start.at=03:00
  killer.storage.period=1440

Настройки очистки базы данных. Поток данных, получаемых с прибора, для 
обеспечения гарантированной доставки записывается в оперативную базу данных. 
Очистка устаревших записей происходит один раз в сутки в указанное в настройках 
время. За это отвечает параметр killer.start.at. Данные хранятся в течение 
периода, указанного в параметре killer.storage.period (в минутах). Период 
отсчитывается от момента сохранения записи в базу данных. Параметр 
killer.last.start является служебным, служит для расчета времени старта очистки 
и обновляется автоматически после каждого ее запуска.

  receiver.TcpPK4Jupiter.active=true
  receiver.TcpPK4Jupiter.ports=10000
  receiver.UdpPK4Jupiter.active=true
  receiver.UdpPK4Jupiter.ports=10000

Раздел настроек драйверов приемников для приборов ППКОП/УОО (ПК4/ПК5).  Для 
каждого драйвера можно определить его активность и список прослушиваемых 
системой портов. Указанные выше настройки означают что ПО будет ожидать 
соединение от приборов на портах TCP 10000 и UDP 10000.

  receiver.UdpRoot.active=true
  receiver.UdpRoot.auto=true
  receiver.UdpRoot.ports=10000
  receiver.UdpRoot.ssl=false

Настройки служебного драйвера, обеспечивающего основной функционал работы с 
обновлением версии, получения информации о состоянии ПО, работы с лицензиями. 
Изменять не рекомендуется!

  server.log.count=3
  server.log.path=C:\Program Files\kros-gate\logs
  server.log.size=64000000

Параметры настройки протоколирования. В процессе работы ПО записывает подробный 
протокол, который может оказаться незаменим при сбоях, восстановлении данных, 
поиске причин неисправностей. При продолжительной работе размер файлов 
протоколов может возрасти до недопустимого значения. Для решения этой проблемы 
предназначены эти параметры. Значение server.log.size определяет максимальный 
размер одного файла протокола. Если размер превышает ограничение будет создана 
резервная копия текущего файла протокола, его размер будет обнулен. Параметр 
server.log.count определяет количество одновременно хранимых резервных копий. 
При создании очередной копии при превышении ограничения количества самая старая 
копия будет удалена. Параметр server.log.path определяет место хранения файлов 
протокола.

  server.threads.max.udp=1000
  server.udp.buffersize=8192

Служебные параметры оптимизации работы с UDP соединениями. Изменять не 
рекомендуется!

  transmitter.TcpSurgard.active=true
  transmitter.TcpSurgardV4.active=true

Базовые параметры драйверов передатчиков. Определяют активность драйверов в 
системе. Если запретить какой-то из драйверов, то трансляторы, настроенные на 
работу с ним, запускаться не будут. Подробнее см. раздел по настройке 
трансляции.


Параметры трансляции (файл broadcast.properties)
------------------------------------------------

Если в системе не создано ни одного транслятора, то данные, поступающие от 
приборов, будут просто записываться в базу данных. Для передачи данных во 
внешнюю систему необходимо настроить параметры транслятора. 

Настройки трансляторов должны располагаться в файле conf/broadcast.properties 
который может быть открыт любым текстовым редактором.

Трансляторов может быть несколько. Различаются они своими условными именами. 
Принадлежность параметра тому или иному транслятору определяется префиксом 
заголовка. Например параметры

  broadcast.TestBroadcast.active=true
  broadcast.TestBroadcast.active.transmitter=TcpSurgard

относятся к транслятору с именем TestBroadcast. Параметры 

  broadcast.CoolestThing.connect.port=30000
  broadcast.CoolestThing.context.connect.address=192.168.1.88

относятся к транслятору с именем CoolestThing.

Параметры файла broadcast.properties:

  broadcast.TestBroadcast.active=true
  broadcast.TestBroadcast.active.transmitter=TcpSurgard

Активация транслятора и задание для него драйвера передатчика. В случае 
изменения параметра active на false транслятор останется в системе, но для него 
не будут поступать данные в очередь на передачу. Параметр active.transmitter 
задает используемый для трансляции драйвер передатчик. Количество и состав 
списка доступных драйверов зависит от конкретного комплекта поставки. В базовый 
комплект входят два драйвера для трансляции данных в формате Surgard - 
TcpSurgard (стандартный базовый протокол) и TcpSurgardV4 (протокол 4-й версии с 
идентификацией по IMEI).

  broadcast.TestBroadcast.context.connect.address=192.168.1.88
  broadcast.TestBroadcast.context.connect.port=30000
  broadcast.TestBroadcast.context.connect.ssl=false
  broadcast.TestBroadcast.context.connect.timeout=120000
  broadcast.TestBroadcast.context.connect.pingPeriod=10

Настройки соединения с внешней системой. Раздел, как видно, имеет префикс имени 
параметра connect. Для трансляторов Surgard предусмотрены следующие параметры:

* address - IP адрес приемника для TCP соединения,
* port - порт приемника для TCP соединения,
* ssl - переключатель режима SSL шифрования,
* timeout - таймаут соединения и ожидания данных для TCP протокола,
* pingPeriod - периодичность отправки PING пакетов принимающей стороне.

  broadcast.TestBroadcast.context.options.decimal=false
  broadcast.TestBroadcast.context.options.ignoreErrors=false
  broadcast.TestBroadcast.context.options.test=true

Параметры транслятора:

* decimal - определяет формат представления идентификатора прибора при 
  формировании пакета для передачи. true - идентификатор преобразуется к 
  десятичному формату, false - к шестнадцатеричному.
* ignoreErrors - способ реакции на ошибки. false - в случае возникновения ошибки 
  передачи пакет будет возвращено в очередь и попытки будут повторяться до 
  успешной отправки, true - после неудачной отправки пакет будет удален из 
  очереди.
* test - тестовый режим. Имитация полноценной работы транслятора без попыток 
  реального подключения к внешнему приемнику.

  broadcast.TestBroadcast.context.event.10121=false,E121,Тревога, принуждение
  broadcast.TestBroadcast.context.event.10122=false,E122,Тихая тревога
  broadcast.TestBroadcast.context.event.10123=false,E123,Тревога ШС
  broadcast.TestBroadcast.context.event.10137=false,E137,Взлом

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

broadcast.TestBroadcast.context.event.10141=false,E141,Обрыв ШС
          _____________               _____ _____ ____ ________
                |                       |     |    |     |
                |                       |     |    |     +- Текст сообщения
                |                       |     |    +- Код сообщения Surgard
                |                       |     +- Признак блокировки
                |                       +- Внутренний код сообщения
                +----------------- Наименование трансляции


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


Параметры приборов (файл devices.properties)
--------------------------------------------

Система принимает соединение от любых приборов, работающих по протоколу ПК4 или 
ПК5. Если на момент соединения прибор не зарегистрирован в базе данных то 
создается новая запись о приборе, его конфигурации и состоянии. Кроме того 
идентификационная информация сохраняется в файле devices.properties. Запись о 
приборе в этом файле имеет следующую структуру:


device.1111-1111-1111=234,0101010101010101010101010101010101010101010101010101010101010101
       ______________ ___ ________________________________________________________________
              |        |                              |
              |        |                              +------ Ключ шифрования
              |        +------------- Идентификатор прибора для пакета Surgard
              +---------------- Идентификатор в конфигурации прибора


Для модификации доступны Идентификатор для пакета Surgard и Ключ шифрования.

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

Ключ шифрования представляет собой 32-байтное значение, используемое для 
шифрования пакетов ПК4 и доступное для изменений в конфигураторе прибора. Для 
вновь подключаемых приборов предполагается значение ключа шифрования 
устанавливаемое при производстве прибора по умолчанию - 01010101… Необходимость 
изменения значения ключа в файле devices.properties может возникнуть в двух 
случаях:

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

ВНИМАНИЕ! Длина строки ключа шифрования должна быть ровно 64 символа и содержать 
только символы 16-го представления числа - 0..9,A,B,C,D,E,F.


Пример быстрой настройки транслятора ПК4 -> Surgard
===================================================

Предположим что ПО KROS-GATE корректно установлено, зарегистрировано и был 
произведен первый пробный запуск. К серверу не подключено ни одного прибора, 
трансляция не осуществляется ни на один внешний источник.


Настройка трансляции
--------------------

Предположим, в системе существует сервер стороннего производителя, который 
принимает данные в формате Surgard по протоколу TCP, расположенный по адресу 
локальной сети 192.168.1.99 и имеющий открытый порт 3300. Сервер может принимать 
все сообщения кроме E307 (Неизвестное сообщение, внутренний код 10307). Кроме 
того, событие Взлом (внутренний код 10137, код Surgard E137) должно быть 
преобразовано для него в код E138.

Останавливаем KROS-GATE командой:

  PS C:\WINDOWS\system32> kros-gate stop

Открываем  файл broadcasts.properties и корректируем в нем нужные строки. 
Включаем режим реального соединения (по умолчанию в трансляторе включен тестовый 
режим):

  broadcast.TestBroadcast.context.options.test=false

Задаем целевой адрес для трансляции с кодовым именем TestBroadcast:

  broadcast.TestBroadcast.context.connect.address=192.168.1.99

Задаем номер порта для соединения:

  broadcast.TestBroadcast.context.connect.port=3300

Корректируем таблицу преобразования потока данных:

  broadcast.TestBroadcast.context.event.10307=true,E307,Неизвестное сообщение
  ...
  broadcast.TestBroadcast.context.event.10137=false,E138,Взлом

Убеждаемся что принимающая сторона ожидает соединения и запускаем KROS-GATE:

  PS C:\WINDOWS\system32> kros-gate start

Даже при отсутствии данных от приборов при успешном соединении система должна 
начать отправлять PING пакеты принимающей стороне. Проверяем содержимое файла 
протокола \Program Files\kros-gate\logs\tr-TcpSurgard.log

  2018-10-04 17:22:09,103 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:12,104 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:14,105 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:16,106 [DEBUG] localhost:30000: PING Packet delivered
  2018-10-04 17:22:18,107 [DEBUG] localhost:30000: PING Packet delivered

Мы видим сообщения о подтверждении успешной доставки PING пакетов.

Транслятор настраивается один раз и при положительном результате в дальнейшем 
обслуживании не нуждается.


Подключение нового прибора
--------------------------

Предположим внешний IP адрес нашего сервера 123.456.7.8, порт UDP 10000 доступен 
извне и сервер готов принимать соединения от приборов. 

С помощью конфигуратора устанавливаем в приборе параметры соединения (адрес 
123.456.7.8, порт 10000), запоминаем его идентификатор ID6 (например 
1234-5678-9012) и убеждаемся что ключ шифрования сброшен в значение по 
умолчанию - 01010101… 

Включаем прибор, дожидаемся на нем индикации подтверждения соединения, проверяем 
содержимое файла devices.properties:

  device.1234-5678-9012=1,0101010101010101010101010101010101010101010101010101010101010101

Видим, что прибор подключился к системе и получил идентификатор из базы данных 
со значением 1. Регистрируем прибор с таким идентификатором в принимающей 
системе и проверяем прохождение потока данных.

Изменяем ключ шифрования. Для этого останавливаем KROS-GATE и меняем значение 
ключа в файле devices.properties на свое:

  device.1234-5678-9012=1,01074E8501010101018CC4010101010101010101010101010323233101010101

Сохраняем файл и запускаем KROS-GATE. Проверяем прохождение потока данных на 
принимающей системе.



Подключение работающего прибора
-------------------------------

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

Прибор с неизвестным системе ключом шифрования не сможет подключиться и 
автоматически зарегистрироваться. Поэтому зарегистрируем его вручную.
Останавливаем KROS-GATE, открываем файл devices.properties и добавляем строку:

  device.1234-5678-9012=753,01074E8501010101018CC4010101010101010101010101010323233101010101

Сохраняем файл и запускаем KROS-GATE. Проверяем прохождение потока данных на 
принимающей системе.



________________

Copyright © 2018, ООО “ЭЛЕСТА”
