microporter - документация для ПО в составе решения Microimpuls Video Transporter

Содержание:

1. Описание

microporter - программное обеспечение сервера Microimpuls Video Transporter, предназначенное для доставки видеопотоков через Интернет, используя специализированный протокол передачи данных, который базируется на TCP или UDP транспорте. Применяются алгоритмы буферизации и выравнивания Transport Stream потоков для обеспечения стабильной доставки в условиях нестабильной линии связи.

Кроме того, решение может быть использовано как UDP to TCP рефлектор, или для UDP to UDP трансляции multicast или unicast адресации в рамках локальной сети, позволяя стабилизировать и выравнивать по PCR TS-поток, а также обеспечивая возможность резервирования.

2. Системные требования

microporter предназначен для работы в ОС Linux Debian 64-битной версии и подобных дистрибутивах, по-умолчанию поставляется версия для архитектуры amd64.

Внимание! ПО microporter не предназначено для работы на виртуальной машине по причине негарантированной стабильности работы виртуального сетевого адаптера.

Требования к аппаратному обеспечению, исходя из принимаемого/передающегося объема трафика:

Процессор 1 ядро 2.4Ghz+ на каждые 200Mbps трафика
Оперативная память 1GB на каждые 200Mbps трафика
Сетевая карта карта с Enterprise чипом Intel, имеющая несколько очередей для входящих пакетов (multiple Rx queues)

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>

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

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

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

Примеры:

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

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

Лицензионный ключ генерируется на основании уникального идентификатора сервера и привязывается к его аппаратной и программной конфигурации, а также к значениям параметров 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.

A. Описание JSON-RPC API

A.1 Описание методов JSON-RPC API

get_stream_list

Получает список потоков.

Возвращает список объектов со следующими полями:

Название Тип Описание
id int Номер потока
name str Имя потока
input-service-name str Сервисное имя потока
enabled bool true, если поток активен
src str Адрес источника потока
backup-src str Адрес резервного источника потока
dst str Адрес, на который отправляется поток
input-buffer-filling float Заполнение буфера входящих данных в процентах
offset-buffer-filling float Заполнение буфера исходящих данных в процентах
input-buffer-duration int Длительность буфера входящих данных в миллисекундах по-умолчанию
input-buffer-max-duration int Максимальная длительность буфера входящих данных в миллисекундах
input-buffer-max-size int Максимальный размер буфера входящих данных в байтах
input-buffer-current-duration int Текущая длительность буфера входящих данных в миллисекундах
input-buffer-current-length int Количество порций данных в буфере исходящих данных
input-buffer-current-size int Размер буфера входящих данных в байтах
output-buffer-max-size int Максимальный размер буфера исходящих данных в МиБ
output-buffer-current-length int Количество порций данных в буфере исходящих данных
output-buffer-current-size int Текущий размер буфера исходящих данных в байтах
uptime int Время непрерывной работы в секундах
bitrate int Текущий битрейт в байтах в секунду
state str Статус потока

Возможные значения поля state:

  • NOT_STREAMING;
  • STREAMING;
  • NO_INPUT;
  • SEND_ERROR;
  • REBUFFERING;
  • FORCED_BACKUP.

start_streaming

Запускает передачу потока.

Параметры:

  • id - номер потока, тип int.

Возвращает строку с результатом вызова метода. Возможные значения:

  • success;
  • bad stream id;
  • too big stream id.

stop_streaming

Останавливает передачу потока.

Параметры:

  • id - номер потока, тип int.

Возвращает строку с результатом вызова метода. Возможные значения:

  • success;
  • bad stream id;
  • too big stream id.

reboot_streaming

Перезапускает передачу потока.

Параметры:

  • id - номер потока, тип int.

Возвращает строку с результатом вызова метода. Возможные значения:

  • success;
  • bad stream id;
  • too big stream id.

rebuffering

Очищает буфер потока.

Параметры:

  • id - номер потока, тип int.

Возвращает строку с результатом вызова метода. Возможные значения:

  • success;
  • bad stream id;
  • stream not initialized;
  • too big stream id.

switch_to_backup

Переключает источник потока на резервный и обратно.

Параметры:

  • id - номер потока, тип int.

Возвращает строку с результатом вызова метода. Возможные значения:

  • success;
  • bad stream id;
  • stream not initialized;
  • too big stream id.

get_statistics

Получает статистику работы microporter.

Возвращает объект со следующими полями:

Название Тип Описание
pid int PID процесса microporter
streams-count int Общее количество видеопотоков
running-count int Количество запущенных видеопотоков
threads-count int Количество запущенных вычислительных потоков в процессе microporter
buffers-mem-usage int Количество ОЗУ, потребляемое буферами в МиБ
mem-usage int Количество ОЗУ, потребляемое процессом microporter в МиБ
cpu-usage float Загрузка CPU процессом microporter и процессами видеопотоков
uptime int Время непрерывной работы процесса microporter в секундах
bitrate int Суммарный битрейт всех запущенных видеопотоков

get_config

Запрашивает конфигурацию в виде JSON-объекта.

Коды ошибок:

Код Описание
201 Файл конфигурации не задан
224 Ошибка чтения файла конфигурации

set_config

Изменяет и применяет конфигурацию.

Параметры:

Название Тип Описание Обязательный Ограничения
config obj Конфигурация в виде JSON-объекта Да  

Возвращаемое значение всегда равно “success”.

Коды ошибок:

Код Описание
100 Отсутствует объект params
101 Пропущен параметр config
109 Некорректная кофигурация
220 Ошибка резервного копирования файла конфигурации
221 Ошибка записи конфигурации
222 Ошибка применения новой конфигурации, предыдущая восстановлена из резервной копии
223 Ошибка применения новой конфигурации и восстановления предыдущей из резервной копии

is_alive

Заглушка метода оценки доступности и загруженности видеосервера.

Возвращает объект со следующими полями:

Название Тип Описание
is_alive bool Всегда равно true
score float Оценка загруженности сервера, всегда равна 0.0

B. Решение проблем и рекомендации

B.1 Нестабильный битрейт и ошибки CC Error

Что делать, если битрейт потоков на выходе сильно отличается от битрейта на входе, или возникают ошибки CC Error на нестабильных потоках?

Включите режим ts-processing-enabled, а также повысьте приоритет процесса microporter через изменение опции priority в файле конфигурации. Изменение приоритета следует начинать с 1 и затем проверять результат.

Также ошибки CC Error и нестабильный битрейт потока может быть следствием слишком большой задержки чтения пакетов - опция read-cycle-delay. Не рекомендуется использовать значения более 500 нсек.

Также причиной нестабильности потоков может быть общая перегружнность сервера, недостаточная пропускная способность линии связи, слишком большой уровень потерь пакетов и джиттера, или некачественные аппаратные компоненты сервера. см. Системные требования

B.2 Рекомендуемые параметры ядра

Изменения нужно вносить в файл /etc/sysctl.conf:

kernel.shmmax = 2473822720
kernel.shmall = 4097152000
net.core.rmem_default = 262144
net.core.rmem_max = 8388608
net.core.wmem_default = 262144
net.core.wmem_max = 8388608

Затем выполнить команду для применения изменений:

sysctl -p