3. Установка и использование

Для работы microporter необходимо наличие библиотек libmedia, libjsonrpc, libjson.

libmedia - библиотека для работы с UDP/TCP сокетами, разрабатывается вместе с microporter.

microporter, а также все необходимые библиотеки совместимых версий, поставляются в виде установочных deb-пакетов и устанавливаются утилитой dpkg. См. Где взять.

Для запуска используется init.d скрипт: /etc/init.d/microporter, доступные аргументы:

$ /etc/init.d/microporter
Usage: /etc/init.d/microporter {start|stop|restart|force-reload|reload}

Файлы логов по-умолчанию сохраняются в /var/log/microporter/microporter.log, включена ротация логов через logrotate.d

3.1 Где взять

Для всех
Скачать необходимые инсталляционные пакеты можно в официальном техническом сообществе Microimpuls по ссылке http://forum.micro.im/ в разделе “Дистрибутивы и обновления ПО”.
Для инженеров Microimpuls
При установке ПО на сервер через систему оркестровки все необходимые установочные пакеты актуальных версий скачиваются из репозитория автоматически.

3.2 Конфигурация

Файл конфигурации находится в /etc/microporter/microporter.conf, задаётся в формате JSON. Пример:

{
    "log-syslog": false,
    "log-facility": 0,
    "log-path": "/var/log/microporter/microporter.log",
    "log-verbose-level": 3,
    "log-foreground": false,
    "statefile": "/etc/microporter/microporter.state",
    "json-rpc-enabled": true,
    "json-rpc-listen-host": "0.0.0.0",
    "json-rpc-listen-port": 8089,
    "streaming-enabled": true,
    "priority": 0,
    "adaptive-delays-enabled": true,
    "rebuffering-enabled": true,
    "ts-processing-enabled": false,
    "write-aux-enabled": false,
    "backup-src": "",
    "read-cycle-delay": 250, // usec, affects performance / bitrate stability
    "input-buffer-duration": 3000, // msec
    "input-buffer-max-duration": 3000, // msec
    "input-buffer-max-size": 48 // mb
    "output-buffer-max-size": 48 // mb
    "socket-read-buffer-size": 0, // b, 0 - system default (SO_RCVBUF)
    "socket-write-buffer-size": 0, // b, 0 - system default (SO_SNDBUF)
    "license-owner": "Demo",
    "license-streams-limit": 20,
    "license-code": "1452c-527c0-8cbfe-74f10-15f5a",
    "streams": [
        {
            "name": "Dummy channel",
            "enabled": true,
            "src": "239.152.2.1 1234 multicast udp",
            "dst": "198.51.100.15 2001 unicast tcp",
            "backup-src": "",
            "payload-size": 1316, // b
            "ttl": 32,
            "input-buffer-duration": 3000, // msec
            "input-buffer-max-duration": 3000, // msec
            "input-buffer-max-size": 48, // mb
            "output-buffer-max-size": 48, // mb
            "socket-read-buffer-size": 0, // b, 0 - system default (SO_RCVBUF)
            "socket-write-buffer-size": 0 // b, 0 - system default (SO_SNDBUF)
        }
    ],
    "ranges": [
        {
            "name": "Dummy range",
            "enabled": true,
            "src-from": "239.152.2.1 1234 multicast udp",
            "src-to": "239.152.2.10 1234 multicast udp",
            "dst-from": "198.51.100.15 2001 unicast tcp",
            "dst-to": "198.51.100.15 2010 unicast tcp",
        }
    ]
}

Описание параметров

log-syslog bool
Использовать ли службу syslogd для записи логов в /var/log/syslog. Не рекомендуется включать при интенсивном логировании.
log-facility int
Тег в syslog.
log-path str
Путь до лог-файла для логирования напрямую без syslogd.
log-verbose-level int
Уровень логирования от 0 до 9, 9 - максимальный DEBUG уровень.
log-foreground bool
Вывод лога в stdout.
statefile str
Путь к файлу состояний процесса microporter. Если задан, то в этот файл будет сохраняться состояние активности потоков, которое может быть изменено через JSON RPC API. При перезапуске microporter’а состояния потоков будут восстановлены из файла состояний. Благодаря этому механизму можно динамически подключать или отключать необходимые потоки, не изменяя основную конфигурацию. Внимание! Если задана опция statefile, то при первоначальном запуске microporter все потоки будут в неактивном состоянии, чтобы запустить их, необходимо будет выполнить команду start_stream через JSON RPC API.
json-rpc-enabled bool
Включает интерфейс JSON RPC API. Через этот API без перезапуска microporter отдельные потоки могут быть приостановлены, переведены на резервный источник или перезапущены.
json-rpc-listen-host str
Адрес интерфейса для ожидания входящих подключений к JSON RPC API. Значение “0.0.0.0” означает слушать на всех интерфейсах.
json-rpc-listen-port int
Номер порта TCP для JSON RPC API, по-умолчанию 8089.
streaming-enabled bool
Глобальный флаг, если true - доставка включена, false - выключена.
priority int
Приоритет процесса в ОС, 0 - автоматический приоритет по выбору ОС. Не рекомендуется использовать высокий приоритет при большом количестве анализируемых потоков.
adaptive-delays-enabled bool
Включает режим адаптивного буфера. Данный режим используется для расширенного контроля за входящим битрейтом видеопотока в условиях нестабильной линии. Может вносить PCR задержки в поток.
rebuffering-enabled bool
При включении данного режима система будет производить перебуферизацию потока каждый раз в случае опустошения буфера.
ts-processing-enabled bool
Включает режим анализа и выравнивания TS-фреймов. При активировании данного режима система будет анализировать входящий Transport Stream поток, обнаруживать ошибки и, по-возможности, выстраивать правильный порядок и выровненный битрейт пакетов.
write-aux-enabled bool
Включает режим записи aux-файлов при выводе потока в файл. aux-файлы необходимы для сохранения информации о таймингах пакетов, для последующего стриминга потока из файла без необходимости анализа TS-фреймов.
read-cycle-delay int

С версии libmedia & microporter 0.12.1

Задержка цикла чтения входного потока в наносекундах. Значение по умолчанию 250. Чем меньше это значение, тем быстрее microporter читает и анализирует поток, но больше нагружает CPU. Для стабильной передачи высокобитрейтных потоков и сохранения CBR необходимо использовать меньшие значения.

input-buffer-duration int
Длительность буфера входящих данных в миллисекундах для всех потоков по-умолчанию.
input-buffer-max-duration int
Максимальная длительность буфера входящих данных в миллисекундах для всех потоков по-умолчанию. В пределах этого значения буфер будет автоматически подстраиваться, в зависимости от частоты перебуферизаций.
input-buffer-max-size int
Максимальный размер буфера входящих данных в мегабайтах для всех потоков по-умолчанию. При достижении максимума буфер очищается.
output-buffer-max-size int
Максимальный размер буфера исходящих данных в мегабайтах для всех потоков по-умолчанию. При достижении максимума очередь исходящих пакетов очищается.
socket-read-buffer-size int

С версии libmedia && microporter 0.12.1

Размер буфера сокета чтения (опция SO_RCVBUF в Linux) в байтах. Значение по умолчанию 0 - использовать системные значения. Позволяет увеличить буфер TCP-сокета и увеличить TCP Window Size для более плотного задействования канала связи и уменьшения издержек на передачу пакетов подтверждения доставки.

socket-write-buffer-size int

С версии libmedia && microporter 0.12.1

Размер буфера сокета записи (опция SO_RCVBUF в Linux) в байтах. Значение по умолчанию 0 - использовать системные значения.

backup-src uri
Адрес backup-потока. В случае возникновения ситуации, когда для любого из доставляемых/принимаемых видеопотоков нет входящего сигнала, система может переключить трансляцию по данному потоку на резервный поток. см. Формат адреса uri
license-owner str
Имя лицензии. см. Настройка лицензии
license-streams-limit int
Количество потоков, разрешенное лицензией.
license-code str
Лицензионный ключ.
streams list
Список потоков для приема/передачи.
ranges list
В секции описываются диапазоны адресов и портов, для удобной передачи большой группы потоков без отдельного описания каждого потока.

Описание параметров потоков в списке streams

name str
Имя потока. Может быть определено автоматически из TS-потока при включенном режиме ts-processing-enabled.
enabled bool
Флаг активности приема/передачи потока.
src uri
Адрес, на котором ожидается прием потока.
dst uri
Адрес, на который будет отправлен поток.
backup-src uri
Адрес резервного потока, на который будет переключен поток src в случае отсутствия. Переопределяет глобальное значение backup-src.
payload-size int
Размер полезных данных в байтах в одном сетевом пакете. По-умолчанию, значение 1316, соответствует максимальному размеру пакета, который помещается в стандартный MTU 1500. Значение 1316 (7 TS-фреймов по 188 байт) подходит для большинства случаев.
ttl int
Время жизни пакета.
read-cycle-delay int

С версии libmedia & microporter 0.12.1

Задержка цикла чтения входного потока в наносекундах. Значение по умолчанию 250. Переопределяет глобальное значение read-cycle-delay.

input-buffer-duration int
Длительность буфера входящих данных в миллисекундах. Переопределяет глобальное значение input-buffer-duration.
input-buffer-max-duration int
Максимальная длительность буфера входящих данных в миллисекундах. В пределах этого значения буфер будет автоматически подстраиваться, в зависимости от частоты перебуферизаций. Переопределяет глобальное значение input-buffer-max-duration.
input-buffer-max-size int
Максимальный размер буфера входящих данных в мегабайтах. При достижении максимума буфер очищается. Переопределяет глобальное значение input-buffer-max-size.
output-buffer-max-size int
Максимальный размер буфера исходящих данных в мегабайтах. При достижении максимума очередь исходящих пакетов очищается. Переопределяет глобальное значение output-buffer-max-size.
socket-read-buffer-size int

С версии libmedia && microporter 0.12.1

Размер буфера сокета чтения (опция SO_RCVBUF в Linux) в байтах. Значение по умолчанию 0 - использовать системные значения. Позволяет увеличить буфер TCP-сокета и увеличить TCP Window Size для более плотного задействования канала связи и уменьшения издержек на передачу пакетов подтверждения доставки. Переопределяет глобальное значение socket-read-buffer-size.

socket-write-buffer-size int

С версии libmedia && microporter 0.12.1

Размер буфера сокета записи (опция SO_RCVBUF в Linux) в байтах. Значение по умолчанию 0 - использовать системные значения. Переопределяет глобальное значение socket-write-buffer-size.

Формат адреса uri

Адрес потока задается в формате:

<ip> <port> <cast_type> <protocol> [<path>]

Доступные cast_type: multicast, unicast, file, http. Доступные protocol: udp, tcp, ts.

При использовании типа file, в качестве ip задаётся путь к директории, а в качестве port имя файла.

Парметр path испольуется только при cast_type http и определяет путь до потока на сервере.

Необязательно совпадение типа потока cast_type на отправителе и на приемнике, в случае различия microporter автоматически преобразует формат.

Примеры:

"239.0.0.1 1234 multicast udp"
"198.51.100.15 2001 unicast tcp"
"/home/storage filename.ts file ts"
"10.0.34.23 8081 http tcp /ch1/"

Настройка лицензии

Лицензионный ключ генерируется на основании уникального идентификатора сервера и привязывается к его аппаратной и программной конфигурации, а также к значениям параметров license-owner и license-streams-limit.

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

Для получения ключа необходимо обратиться к своему менеджеру или отправить письмо на адрес support@microimpuls.com. Запрос должен содержать медиа-код и информацию об имеющемся договоре.

Пример настройки приема и передачи потока

Предположим, передающий сервер расположен в точке A, необходимо передать Multicast-поток с адреса udp://@239.152.1.1:1234 через Интернет на дальнее расстояние в точку B на принимающий сервер с IP-адресом 198.51.100.15 и направить его в локальную сеть точки B в Multicast-поток udp://@239.152.2.1:1234. Будет использоваться передача по TCP Unicast на входящий порт принимающего сервера 2001, с задержкой 3 секунды.

Передающий сервер в точке A:

{
   "name": "Example stream (transmit)",
   "enabled": true,
   "src": "239.152.1.1 1234 multicast udp",
   "dst": "198.51.100.15 2001 unicast tcp",
   "input-buffer-duration": 500
}

Принимающий сервер в точке B:

{
   "name": "Example stream (receive)",
   "enabled": true,
   "src": "0.0.0.0 2001 unicast tcp",
   "dst": "239.152.2.1 1234 multicast udp",
   "input-buffer-duration": 3000
}

3.3 Скрипт для monit

Для слежения за процессами microporter удобно использовать monit, пример скрипта:

check process microporter with pidfile /var/run/microporter.pid
    start program = "/etc/init.d/microporter start" with timeout 60 seconds
    stop program  = "/etc/init.d/microporter stop"
    if cpu > 60% for 2 cycles then alert
    if cpu > 90% for 5 cycles then restart
    if totalmem > 3000.0 MB for 5 cycles then restart
    if 3 restarts within 5 cycles then timeout
    group microporter

3.4 Установка нескольких инстансов microporter

Установка и работа нескольких копий процесса microporter на одном сервере допускается. Для удобства администрирования такого сервера рекомендуется разные конфигурации сохранять в отдельных конфигурационных файлах, при этом именуя конфиг-файл с суффиксом в конце, а также создавать отдельный monit-конфиг и init-скрипт для каждого инстанса.

Пример:

/etc/microporter/microporter.r.conf /etc/init.d/microporter.r
процесс, который будет принимать потоки с другого сервера
/etc/microporter/microporter.s.loca.conf /etc/init.d/microporter.s.loca
процесс, который будет отправлять потоки на сервер в location A
/etc/microporter/microporter.s.locb.conf /etc/init.d/microporter.s.locb
процесс, который будет отправлять потоки на сервер в location B
/etc/microporter/microporter.gw.conf /etc/init.d/microporter.gw
процесс, который будет осуществлять трансляцию адресов в рамках локальной сети

Внутри init-скрипта суффикс можно прописать в переменной SUFFIX, при этом прописывается сам суффикс, для примера выше это .r, .s.loca, .s.locb, .gw.