<?xml version="1.0" encoding="koi8-r"?>
<book lang="ru">
  <bookinfo>
    <title>Firecast</title>
    <author>
      <firstname>Andrey</firstname><surname>Vasilkin</surname>
    </author>
    <author>
      <firstname>gemini</firstname>
    </author>
    <copyright><year>2008</year><holder>Andrey Vasilkin</holder></copyright>
  </bookinfo>
  <chapter>
    <title>Введение</title>
    <section>
      <title>Что такое Firecast?</title>
      <para>
        Firecast представляет собой сервер аудиопотоков форматов
        Ogg Vorbis или MP3. Слушатели подключаются к серверу,
        используя различное мультимедийное программное обеспечение.
	Для воспроизведения аудиопотоков по сети могут быть
	использованы многие популярные аудио-плееры.
      </para>
      <para>
        Firecast является бесплатным программным обеспечением с
        открытым исходным кодом. Могут использоваться сопутствующие
        продукты как с открытым исходным кодом (такие как
        <ulink url="http://digi.os2.snc.ru/eng/firecast">fires-PM123 filter plug-in</ulink>     
        для плеера
        <ulink url="http://glass.ptv.ru/software/english/pm123.html">PM123</ulink>,
        <ulink url="http://www.icecast.org/ices.php">ices0/ices2</ulink>,
        shout из проекта
        <ulink url="http://www.icecast.org/">icecast.org</ulink>),
        так и коммерческие продукты (например, бесплатный 
        <ulink url="http://www.shoutcast.com/download/broadcast.phtml">SHOUTcast DSP Plug-in</ulink>
        для Winamp).
      </para>
      <para>
        Для передачи данных от сервера к клиентам используется
        http-протокол и, обычно, tcp/ip порт 8000. Для работы с
        "источниками" (см. далее) в некоторых случаях используется
        дополнительный порт 8001. Эти tcp/ip порты должны быть
        доступны сетевым клиентам. Данные значения являются
        общепринятыми, но не обязательными (могут изменяться).
      </para>
    </section>
    <section>
      <title>Области применения</title>
      <para>
        Firecast может использоваться для вещания неограниченного
        числа аудиопотоков в Интернет или в локальных сетях.
        Например, Вы можете дать возможность друзьям слышать то,
        что проигрывает Ваш программный плеер. В локальных сетях
        организаций могут вещаться музыкальные потоки, местные
        объявления и т.п. Радиостанции, кроме вещания в эфире, могут
        открывать вещание через Интернет. Данное программное
        обеспечение пригодно как для домашних пользователей, так и
        для различных сфер бизнеса.
      </para>
    </section>
    <section>
      <title>О проекте</title>
      <para>
        Данный проект родился как альтернатива широкоизвестному и
        распространённому Icecast2. От Icecast2 взяты основные
        принципы работы. Почему появился Firecast, его плюсы:
        <itemizedlist>
          <listitem>
            более низкие требования к системным ресурсам на основных
            целевых платформах
            (<ulink url="http://www.ecomstation.ru/">eComStation</ulink>
            / OS/2, Windows);
          </listitem>
          <listitem>
            удобный веб-интерфейс управления сервером, не требуется
            редактировать какие-либо файлы конфигурации (однако,
            возможность конфигурирования путём прямого изменения
            конфигурационного файла имеется);
          </listitem>
          <listitem>
            изменение конфигурации без остановки сервера;
          </listitem>
          <listitem>
            поддержка виртуальных web-хостов.
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Что отсутствует в Firecast на данный момент:
        <itemizedlist>
          <listitem>
            поддержка Ogg-потоков кроме Vorbis (возможно, какие-то
            форматы будут работать -- не проверялось);
          </listitem>
          <listitem>
            автоматическое подключение клиентов к потокам других
            источников в случае разрыва соединения с источником потока;
          </listitem>
          <listitem>
            поддержка каталога радиостанций (Directory of Icecast streams).
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Firecast не следует рассматривать как конкурента Icecast2, который
        является общепризнанным решением в области сетевого вещания и имеет
        б<emphasis>о</emphasis>льшую функциональность, но сложнее в
        настройке и эксплуатации для обычного пользователя.
      </para>
    </section>
    <section>
      <title>Легальность</title>
      <para>
        Необходимо обратить внимание на законность распространения
        материала (музыкальных произведений и пр.) с использованием
        описанных здесь программных продуктов. Если предполагается
        вещание вне личного локального компьютера, следует
        обратиться к действующему законодательству для уточнения
        условий распространения материалов описанными способами.
      </para>
    </section>
  </chapter>
  <chapter>
    <title>Подготовка к работе</title>
    <section>
      <title>Как это работает</title>
      <para>
        Применяется классическая 3х-компонентная схема сетевого
        вещания: источники (кодировщики) создают потоки, например,
        на основе статических файлов, либо аналогового аудиосигнала
        путём упаковки в нужный формат и передают на сервер Firecast.
        Сервер, в свою очередь, передаёт копии потоков клиентам
        (слушателям).
      </para>
      <para>
        В качестве источника может использоваться как встраеваемый
        модуль к программе-плееру
        (<ulink url="http://www.shoutcast.com/download/broadcast.phtml">SHOUTcast DSP Plug-in</ulink>
        для Winamp в Windows или
        <ulink url="http://digi.os2.snc.ru/eng/firecast">fires-PM123 filter plug-in</ulink>
        для
        <ulink url="http://glass.ptv.ru/software/english/pm123.html">PM123</ulink>
        в
        <ulink url="http://www.ecomstation.ru/">eComStation</ulink>
        и OS/2) так и отдельные программы
        (<ulink url="http://www.icecast.org/ices.php">ices0</ulink>,
        <ulink url="http://www.icecast.org/ices.php">ices2</ulink>,
        shout и т.п.).
      </para>
      <para>
        Через один сервер Firecast могут транслироваться потоки от
        множества источников. Каждому источнику назначается так
        называемая точка монтирования. Точки монтирования
        указываются либо самими источниками (если они работают по
        протоколу http, такие как Ices0, Ices2, fires-PM123 filter
        plug-in), либо назначаются сервером на основе конфигурации
        (для таких как shout, SHOUTcast DSP Plug-in, в этом случае
        имя точки монтирования привязывается к номеру порта). Точки
        монтирования отражаются в адресах потоков, например, для
        имён точек монтирования <filename>mystream</filename> и
        <filename>radio.ogg</filename> соответственно:
        <filename>http://localhost:8000/mystream</filename> ,
        <filename>http://localhost:8000/radio.ogg</filename> .
        Для потоков в формате Ogg Vorbis документация Icecast2
        рекомендует выбирать имена точек монтирования,
        заканчивающиеся на ".ogg"
      </para>
      <para>
        Принимать поток с сервера для воспроизведения можно одним
        из многих плееров, умеющих работать с потоками, такими как
        Windows Media Player, Winamp для Windows; XMMS для FreeBSD
        и Linux;
        <ulink url="http://glass.ptv.ru/software/english/pm123.html">PM123</ulink>
        ,
        <ulink url="http://dink.org/z/">Z!</ulink> для
        <ulink url="http://www.ecomstation.ru/">eComStation</ulink> и OS/2.
      </para>
    </section>
    <section>
      <title>Установка</title>
      <para>
        Выполните установку из установочного файла, либо распакуйте
        zip-архив в любую директорию, в зависимости от того, в каком
        виде вы получили пакет Firecast. Запустите выполнимый файл
        Firecast (если этого ещё не сделал инсталлятор).
      </para>
      <para>
        Теперь Firecast готов к настройке через web-интерфейс.
        Откройте адрес 
        <ulink url="http://localhost:8000/">http://localhost:8000/</ulink> .
      </para>
    </section>
  </chapter>
  <chapter>
    <title>Настройка</title>
    <section>
      <title>Доступ администратора</title>
      <para>
        Перед Вами web-интерфейс управления Firecast. Первым делом,
        необходимо принять меры безопасности и сменить имя/пароль
        администратора; для этого перейдите в раздел
        <command>Administrator</command>
        и на запрос браузера введите имя пользователя "admin" и
        пароль "password" (без кавычек). Кроме имени/пароля
        администратора здесь же можно задать списки доступа для
        администратора, уровень детализации журнала событий и
        количество последних записей, хранимых в журнале событий.
      </para>
      <section id="ACLs" xreflabel="списки доступа">
        <title>Сприски доступа</title>
        <para>
          Эти списки используются в нескольких разделах конфигурации
          и представляют из себя правила доступа клиентов на
          основании их ip-адресов. Каждое правило разрешает
          (<replaceable>allow</replaceable>) или запрещает
          (<replaceable>deny</replaceable>) доступ с указанных адресов.
          Адреса задаются в виде адрес/маска или адрес/n, где n -
          количество бит маски, например:
          <variablelist>
            <varlistentry>
              <term>deny 192.168.1.10/255.255.255.255</term>
              <listitem>запретить доступ с адреса 192.168.1.10</listitem>
            </varlistentry>
            <varlistentry>
              <term>allow 192.168.1.0/255.255.255.0</term>
              <listitem>разрешить доступ со всех остальных адресов сети 192.168.1</listitem>
            </varlistentry>
            <varlistentry>
              <term>deny 0/0</term>
              <listitem>запретить всем остальным</listitem>
            </varlistentry>
          </variablelist>
        </para>
        <para>
          Правила просматриваются с начала списка. Когда тестируемый
          адрес совпадает с указанным в правиле (является частью
          указанной сети), принимается решение - разрешить соединение
          <replaceable>allow</replaceable> или запретить
          <replaceable>deny</replaceable>.
          Если список правил пуст, то любой адрес считается разрешённым.
          Если список не пуст и тестируемый адрес не соответствует ни
          одному правилу, он считается запрещённым.
        </para>
      </section>
    </section>
    <section>
      <title>Порты</title>
      <para>
        По умолчанию Firecast будет использовать для подключения
        источников и клиентов tcp/ip порт 8000 на всех сетевых
        интерфейсах.
        Это традиционное значение порта для потокового радио. Кроме
        того, сервер будет работать в режиме совместимости с
        источниками работающими по протоколу shoutcast, при этом
        используется ещё один дополнительный порт, значение которого
        больше основного на еденицу (т.е. по умолчанию 8001).
      </para>
      <para>
        Все эти параметры изменяются в разделе <command>General</command>
        web-интерфейса конфигуратора. Здесь Вы можете задать несколько
        портов, на которых будут приниматься соединения, и ограничить их
        действие только одним из имеющихся сетевых интерфейсов/адресов
        (указав локальный ip-адрес интерфейса).
        Для портов, работающих в режиме совместимости shout,
        необходимо назначать точки монтирования, т.к. источники,
        работающие по этому протоколу, не могут сами указывать точки
        монтирования.
      </para>
    </section>
    <section>
      <title>Хосты (виртуальные web-серверы)</title>
      <para>
        Если сервер имеет несколько псевдонимов в доменной системе
        имён (DNS) и/или несколько ip-адресов, т.е. может
        откликаться на разные адреса, Вы можете организовать
        несколько виртуальных хостов. Смысл разделения на
        виртуальные хосты в том, что при обращении к одному серверу
        с использованием разных адресов выдаётся разная информация.
        Например, у вашего сервера в локальной сети в DNS прописан
        основной адрес (запись A) mainserv и псевдоним (запись
        CNAME) radioserv. Второй адрес может быть использован для
        создания виртуального хоста, т.е. Firecast при обращении к
        нему по адресу  radioserv будет выдавать не свой
        web-интерфейс, а документы из указанного локального пути
        (например, web-страницу сетевой радиостанции).
      </para>
      <para>
        Кроме статических файлов, хранящихся на сервере и доступных
        через http-протокол, имеется ряд динамических данных,
        которые формируются во время работы и имеют адреса
        http://любое_имя_сервера/ресурс, это:
        <itemizedlist>
          <listitem>
            точки монтирования
          </listitem>
          <listitem>
            m3u-файлы точек монтирования, вида
            http://.../точка_монтирования.m3u
          </listitem>
          <listitem>
            ресурсы, использующиеся источниками для обновления мета-информации:
            <itemizedlist>
              <listitem>
                /admin/metadata
              </listitem>
              <listitem>
                /admin.cgi
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            ресурсы администрирования:
            <itemizedlist>
              <listitem>
                /admin/source
              </listitem>
              <listitem>
                /admin/sources
              </listitem>
              <listitem>
                /admin/source-info
              </listitem>
              <listitem>
                /admin/sources-info
              </listitem>
              <listitem>
                /admin/templates
              </listitem>
              <listitem>
                /admin/hosts
              </listitem>
              <listitem>
                /admin/general
              </listitem>
              <listitem>
                /admin/admin
              </listitem>
              <listitem>
                /admin/log
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            сводный плей-лист сервера /listen.pls
          </listitem>
        </itemizedlist>
        Надо отметить, что все эти динамические ресурсы будут доступны
        по любому из имён виртуальных серверов, файлы с совпадающими
        именами будут недоступны.
      </para>
      <para>
        Управляются виртуальные хосты на странице
        <command>Web-hosts</command> конфигуратора. Здесь для каждого
        создаваемого хоста задаются:
        <itemizedlist>
          <listitem>
            локальный путь к документам хоста;
          </listitem>
          <listitem>
            имена виртуального хоста (на которые он откликается,
            ip-адреса и/или символические имена);
          </listitem>
          <listitem>
            имена индексных файлов (обычно
            <filename>index.html</filename>), т.е.
            дописываемые к адресам без указанного конечного файла.
            Например, если в параметрах виртуального сервера указан
            индексный файл
            <filename>index.html</filename>, то адрес
            <command>http://myhost:8000/</command> будет эквивалентен
            <command>http://myhost:8000/index.html</command>;
          </listitem>
          <listitem>
            <xref linkend="ACLs" /> к хостам.
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Виртуальный хост без заданного имени "откликается" на любое
        имя. При поступлении запроса и поиске соответствующего
        виртуального хоста список просматривается в том порядке,
        какой отображается в конфигураторе. Это значит, что хост
        без указанного имени имеет смысл иметь только один, и только
        вконце списка.
      </para>
    </section>
    <section id="templates" xreflabel="шаблоны">
      <title>Шаблоны источников</title>
      <para>
        Для организации нового аудиопотока на сервере он должен
        быть некоторым образом заранее описан: задан пароль для
        источника, описаны ограничения на доступ, максимальное
        число клиентов (слушателей), заданы информационные
        параметры потока.
      </para>
      <para>
        Происходит это следующим образом:
        <orderedlist>
          <listitem>
            <para>
              При подключении источника просматривается список
              шаблонов, описывающих допустимые на сервере Firecast
              потоки, в порядке, заданном администратором при
              конфигурировании. Источник привязывается к шаблону по маске
              имени точки монтирования в которой могут использоваться
              символы '*', '?' и списки символов. Например, шаблон с
              маской имени точки монтирования "my*radio-?" будет применён
              к потокам точек монтирования "my-first-radio-1",
              "myradio-2" и т.п.
              <tip>
                <variablelist>
                  <varlistentry>
                    <term>'*'</term>
                    <listitem>означает любую последовательность символов (включая пустую)</listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>'?'</term>
                    <listitem>означает любой одиночный символ</listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>[список]</term>
                    <listitem>соответствует любому символу из заданного списка</listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>[!список] или [^список]</term>
                    <listitem>соответствует любому символу не из заданного списка.</listitem>
                  </varlistentry>
                </variablelist>
                <para>
                  Например, список символов может иметь вид [0-9a-zA-Z], что
                  означает
                  <quote>любой символ латинского алфавита или цифра</quote>. Для
                  задания любого из символов "[]*?!^-\" перед ним ставится '\'.
                </para>
              </tip>
            </para>
          </listitem>
          <listitem>
            <para>
              Когда шаблон найден, проверяется корректность пароля,
              переданного источником по заданному в шаблоне. Если пароль
              неверный, соединение разрывается.
            </para>
          </listitem>
          <listitem>
            <para>
              На сервере создаётся новый поток с запрошенной точкой
              монтирования, согласно шаблону добавляются или заменяются
              его информационные поля. Теперь клиенты могут подключаться
              к новому потоку.
            </para>
          </listitem>
        </orderedlist>
      </para>
      <para>
        Описываются шаблоны в разделе <command>Templates</command>
        web-интерфейса Firecast. После установки сервера создаётся
        один шаблон с маской имени точки монтирования "*" (т.е. он
        будет применён для любого потока) и паролем "password".
      </para>
      <para>
        Шаблон может быть запрещён (переключатель 
        <option>denied</option>). т.е. соединения с источниками,
        подключающимися с подходящими по маске именами точек
        монтирования, будут немедленно разрываться.
      </para>
      <para>
        Можно скрыть потоки (переключатель <option>hidden</option>).
        Такие потоки не будут отображаться в плей-листе и списке
        потоков <command>Status</command>.
      </para>
      <para>
        При разрыве соединения с источником все клиенты принудительно
        отключаются и точка монтирования источника перестаёт
        существовать.
	Однако, отключение клиентов и уничтожение точки монтирования
        может быть отложено. В этот период времени, с момента разрыва
        соединения с источником и фактического признания сервером
        firecast факта отключения источника, у источника есть
        возможность восстановить соединение (подключиться повторно) и
        продолжить вещание.
        Время ожидания восстановления соединения задаётся параметром
        <option>Keep alive</option> в секундах (от 0 до 300).
      </para>
      <para>
        Из соображений безопасности для источников возможно
        указание списка доступа: соединения с источниками,
        подключающимися с подходящими по маске именами точек
        монтирования, но не проходящими список доступа, будут
        немедленно разрываться. Такой же список доступа может быть
        задан и для клиентов. Следует обратить внимание, что пустые
        списки подразумевают прохождение любого адреса
        источника/клиента.
      </para>
    </section>
    <section>
      <title>Ретрансляция</title>
      <para>
        Ретрансляция позволяет серверу firecast передавать своим клиентам
        потоки с других различных серверов.
        В этом случае сервер firecast выступает в роли клиента для других
        серверов, считывает с них заданные потоки и передаёт копии этих
        потоков своим клиентам.
        Данная функция может быть очень полезна для организации передачи
        данных через различные шлюзы и экономии трафика:
        сервер в локальной сети может принимать по <emphasis>одному</emphasis>
        заданному потоку из внешней сети и тиражировать их клинтам своей сети.
      </para>
      <para>
        Направления (ретранслируемые потоки) описываются в разделе
        <command>Relays</command> web-интерфейса Firecast. Может быть задано
        любое количество направлений, каждое из которых описывается всего
        тремя параметрами:
        точка монтирования (<option>Mount point</option>), адрес потока
        (<option>Source location</option>) -
        прямая ссылка или ссылка на m3u-описатель и переключателем
        "постоянного потока" (<option>Nailed-up</option>). Последний параметр
        указывает, что поток будет считываться непрерывно. Если ретранслируемый
        поток не является "постоянным", то сервер будет устанавливать
        соединение с сервером-источником потока (т.е. сервером с которого
        ретранслируется поток) только в том случае,
        если появляются локальные клиенты и разрывать соединение при отключении
        последнего клиента. Т.е. не "постоянные потоки" заметно
        экономят трафик, если значительную часть времени клиенты отсутствуют,
        но требуют некоторого времени (как правило, всего несколько секунд) на
        установку связи с сервером-источником потока при подключении первого
        клиента.
      </para>
      <para>
        Для точек монтирования, создаваемых при ретрансляции должны быть
        описаны <xref linkend="templates" /> так же, как и для точек
        монтирования источников.
        Поля шаблонов "password" в данном случае не используются.
      </para>
    </section>
    <section>
      <title>Файл конфигурации</title>
      <para>
        Все настройки Firecast хранятся в файле конфигурации
        <filename>config.xml</filename>. При изменении
        параметров этот файл переименовывается в
        <filename>config.BAK</filename>, а новая конфигурация
        записывается в <filename>config.xml</filename>.
      </para>
      <para>
        Если при запуске файл конфигурации не обнаружен, то
        создаётся базовая конфигурация с начальными
        установками и сохраняется в <filename>config.xml</filename>.
      </para>
      <para>
        Задавая имя/пароль/списки доступа администратора, изменяя
        настройки виртуальных хостов, нужно проявлять осторожность,
        т.к. в результате непродуманных действий легко потерять
        контроль над сервером. Но, в любом случае, можно остановить
        сервер Firecast и внести изменения непосредственно в файл
        конфигурации <filename>config.xml</filename>.
      </para>
      <para>
        В самом худшем случае, можно остановить сервер, удалить файл
        конфигурации <filename>config.xml</filename> и снова запустить
        сервер. Будет создана базовая конфигурация с начальными
        установками.
      </para>
    </section>
  </chapter>
  <chapter>
    <title>Заключение</title>
    <para>
      О последних версиях Firecast можно узнать на домашней странице проекта
      <ulink url="http://digi.os2.snc.ru/eng/firecast">http://digi.os2.snc.ru/eng/firecast</ulink>
    </para>
    <para>
      Если Вы желаете помочь проекту, пишите на адрес
      <email>digi@os2.snc.ru</email>.
      Чем можно помочь:
      <itemizedlist>
        <listitem>
          перевод данной документации на другие языки;
        </listitem>
        <listitem>
          адаптация на новых платформах;
        </listitem>
        <listitem>
          проинформировать об обнаруженной ошибке в работе программы;
        </listitem>
        <listitem>
          информационная поддержка на публичных ресурсах;
        </listitem>
        <listitem>
          поддержать проект добровольным вознаграждением.
        </listitem>
      </itemizedlist>
    </para>
  </chapter>
</book>
