====== UDPXY ======


===== Общая информация =====

udpxy - серверное приложение (daemon) для передачи данных из сетевого потока мультикаст канала (вещаемого по UDP) в HTTP соединение запрашивающего клиента.

Домашняя страница проекта: http://www.udpxy.com/

Форум проекта: http://www.udpxy.com/forum

Обсуждение на форуме по кинетикам: http://forum.zyxmon.org/topic73-udpxy-na-keenetic.html


===== Установка и настройка =====

Пакет устанавливается комадой

  opkg install udpxy
  
Скрипт (авто)запуска в папке ''/media/DISK_A1/system/etc/init.d/K26udpxy''. Измените первую букву ''K'' на букву ''S'' для автозапуска. Отредактируйте скрипт под свои нужды. Для PPPoE соединений без IP (Pure PPPoe) следует раскомментировать строку, присваивающую ip интерфейсу ''eth2.2''. В скрипте производится выгрузка модуля ядра ''igmpsn.ko'', после этого просмотр мультикаста на компьютерах невозможен. В некоторых случаях можно обойтись и без выгрузки этого модуля. В большинстве случаев без выгрузки ''igmpsn.ko'' работать udpxy не будет. Часто нужно "подкрутить" в скрипте параметры запуска демона - например, размер буфера (параметр ''-B'') и другие.

===== Руководство пользователя пакета udpxy =====
(перепечатка с оф. сайта - http://www.udpxy.com/umanual-ru.html)

Данное руководство составлено с целью разъяснить принципы и основные алгоритмы работы приложений, входящих в состав пакета udpxy (в настоящее время эти приложения: udpxy, udpxrec). Руководство также ставит своей целью более подробно описать значение параметров командной строки и дать примеры их использования.

==== Приложение udpxy ====

udpxy - серверное приложение, обладающее при определённым образом заданных параметрах атрибутами UNIX daemon-а. Основная задача udpxy заключается в передаче данных, считанных из мультикаст-канала (рассылающего данные подписчикам по протоколу UDP), в клиентское соединение, работающее в протоколе TCP. Таким образом, клиент, не имея возможности работать с протоколом UDP, может послать запрос udpxy, установить TCP соединение и работать с данными, полученными из указанного (в изначальном запросе) мультикаст-канала.

Основным сценарием использования udpxy является воспроизведение видео или аудио потоков, транслирующихся в локальной сети. Не все видео и аудио плееры (приложения) поддерживают считывание информации непосредственно из мультикаст-канала, но большинство обладает возможностью читать видео- или аудио-поток через HTTP запрос (по протоколу TCP). Клиент - плеер - посылает HTTP (GET) запрос udpxy в виде URL с параметрами, идентифицирующими источник данных (адрес и порт мультикаст-канала); udpxy "подписывается" на соответствующий канал и начинает считывать из него данные, которые затем передаются (по установленному TCP соединению) клиенту. Приём и передача данных происходят в цикле до тех пор, пока одна из сторон не прервёт соединение: источник перестанет передавать данные или же клиент со своей стороны прекратит их приём.

Примечание: приложение считает соединение прерванным и том случае, если оно не может выполнить операцию чтения или записи по данному соединению в течении заданного периода времени - "тайм-аута". Тайм-аут для чтения устанавливается по умолчанию в 5 (пять) секунд, но может быть установлен извне через значение (в секундах) переменной среды UDPXY_RCV_TMOUT.

==== Протоколы передачи и форматы данных ====

В настоящее время udpxy поддерживает следующие протоколы передачи аудио- и видео-данных:

  * TS (MPEG-TS)
  * RTP (MPEG-TS через RTP)

Приложение идентифицирует поток по первому полученному сообщению. Тип потока определяет дальнейший способ обработки данных: в случае TS никакой дополнительной обработки не производится; если же данные передаются по RTP, udpxy "конвертирует" поток в TS (вычленяя из RTP пакетов данные MPEG-TS). Таким образом, во всех случаях клиенту выдаётся поток в формате TS. В случае, если udpxy не может идентифицировать тип потока, выдаётся ошибка и соединение с клиентом закрывается.

==== HTTP запросы к udpxy ====

1. Запрос на соединение:

%%http://{address}:{port}/{protocol}/{channel_addr}:{channel_port}%% , где:

%%{address}%%, %%{port}%% - адрес и порт, на которых udpxy отслеживает ("слушает") запросы клиентов (см. параметры командной строки ''-a'' и ''-p'');

%%{protocol} ::= udp | rtp%% - формат потока; при указании RTP udpxy будет сразу считать протоколом передаваемого потока RTP, при указании UDP udpxy самостоятельно попытается определить протокол;

%%{channel_addr}%% - IP адрес (мультикаст-) канала данных;

%%{channel_port}%% - порт канала данных;

2. Статус приложения:

%%http://{address}:{port}/status%% - по данной команде udpxy возвращает клиенту (HTML) страницу статуса приложения, отображающую в том числе статус клиентов и статистику скорости передачи данных клиентов (см. опцию ''-S'').

3. Перезапуск:

%%http://{address}:{port}/restart%% - по данной команде udpxy осуществляет перезапуск: закрывает соединения со всеми клиентами и переходит в состояние ожидания запросов.

==== Параметры командной строки udpxy ====

''-v'' - включить режим детального вывода в журнал %%[%%выключен по умолчанию%%]%%

При включённом режиме детального вывода приложение будет выводить в журнал (см. параметр ''-l'') отладочную информацию. Важно: вывод отладочной информации невозможен для исполняемых файлов udpxy, собранных в режиме lean. (Режим указан при запуске приложения без параметров сразу после номера сборки, например: udpxy 1.0_Chipmunk (build 8) standard, где режим сборки - "standard".

''-S'' - передавать статистику о клиентских соединениях [по умолчанию - не передавать]

Приложение будет накапливать и отображать (по HTTP-интерфейсу при запросе status) данные о средней скорости чтения и записи данных на потоках клиентов. Например, при наличии трёх клиентов, страница статуса udpxy покажет среднюю пропускную способность (в килобайтах в секунду) для каждого из клиентов.

''-T'' - в случае запуска администратором (root) не пытаться работать в режиме сервера [по умолчанию - работать в режиме сервера (daemon), если процесс запущен пользователем с административными правами].

При запуске непривилегированным пользователем udpxy будет работать в окне терминала и реагировать на интерактивные команды терминальной сессии, такие как выход в фоновый режим, прерывание по ''Ctrl-C'' и т.д. При запуске администратором (root) или пользователем с привилегиями администратора (0 == $EUID) приложение по умолчанию попытается работать в режиме сервера (daemon). Задействовав переключатель ''-T'', пользователь может заставить udpxy при запуске администратором (root) работать с текущим терминалом.

''-a'' - указать адрес (IPv4) или имя интерфейса для (HTTP) запросов к приложению %%[%%0.0.0.0 - по умолчанию%%]%%.

''-p'' - указать TCP порт для (HTTP) запросов к приложению (обязательный параметр).

''-m'' - указать адрес (IPv4) или имя интерфейса мультикаст-каналов %%[%%0.0.0.0 - по умолчанию%%]%%.

''-с'' - максимальное количество клиентов, обслуживаемых одновременно %%[%%см. подсказку при запуске%%]%%.

udpxy способно обслуживать не более обозначенного количества клиентов одновременно; приложение не даст установить соединение в превышение указанной квоты. Переопределив константу ''MAX_CLIENT_COUNT'' (в файле uopt.h), udpxy может быть скомпилировано с иным потолком соединений.

''-l'' - записывать журнал приложения в указанный файл %%[%%по умолчанию - stderr%%]%%.

udpxy будет вести запись журнала в указанный файл; записи будут добавляться или же файл будет создан заново. В случае, если приложение будет запущено пользователем с правами администратора в режиме детального вывода (параметр -v), но файл не будет указан, udpxy выдаст ошибку.

''-B'' - указать размер буфера для входящих данных %%[%%см. подсказку при запуске%%]%%.

Параметр заставляет udpxy накапливать входящие данные в буфере указанного размера прежде, чем передать их в соединение клиента. Данные читаются порциями, обозначаемыми как "сообщения" (messages). Таким образом, до тех пор, пока буфер указанного размера не будет заполнен должным количеством сообщений (определяемым параметром ''-R'') или же (с момента получения первого пакета) не пройдёт время, обозначенное параметром ''-H'', данные не будут переданы клиенту.

''-R'' - указать максимальное количество сообщений, накапливаемых в буфере %%[%%см. подсказку при запуске%%]%%.

Параметр определяет, сколько сообщений должно быть в буфере прежде, чем он будет отправлен клиенту. Значение %%"1"%% (единица) ограничивают буфер одним сообщением, что означает, что все приходящие данные сразу же отправляются клиенту, и накапливания не происходит. Значение %%"-1"%% (минус единица) снимают ограничение с буфера: сообщения накапливаются до полного насыщения буфера. (В этом случае udpxy прерывает накопление, если в буфере осталось меньше места, чем то, что занимает последняя считанная запись.)

Примечание: при достаточно низкой скорости чтения входного потока и значительном размере буфера, клиент может посчитать время простоя (когда ему не поступают данные) чрезмерным и закрыть соединение или же отказывать в приёме сообщения. (В этом случае в журнале отладки можно видеть периодически появляющиеся записи: "write_buf: write: Resource temporarily unavailable").

''-H'' - указать максимальное время (в секундах) накопления сообщений в буфере (см. параметры ''-B'', ''-R'') %%[%%см. подсказку при запуске%%]%%.

Приложение засекает время "прибытия" первого пакета (из серии), записываемого в буфер. После чтения каждого пакета, разница во времени сравнивается с указанной (в секундах) величиной: если пройденное время превышает заданный промежуток, накопленные в буфере данные передаются клиенту. Данное значение может быть также установлено с помощью переменной среды ''UDPXY_DHOLD_TMOUT''.

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

''-n'' - смещение приоритета приложения ("nice value").

''-M'' - периодически возобновлять подписку на мультикаст-канал %%[%%по умолчанию - 0 (секунд), т.е. не возобновлять%%]%%.

Установка данного параметра в значение ''N'', отличное от нуля, заставляет приложение возобновлять подписку на мультикаст-канал(ы) клиента каждые ''N'' секунд.