<?xml version='1.0'?>
<!--
Copyright © 2008-2011, Diego "Flameeyes" Pettenò <flameeyes@gmail.com>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this generator; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-->
<article xmlns="http://docbook.org/ns/docbook"
         xmlns:xl="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0" xml:lang="en">
  <info>
    <title>feng.conf</title>

    <authorgroup>
      <author>
        <personname>
          <firstname>Luca</firstname>
          <surname>Barbato</surname>
        </personname>

        <affiliation>
          <orgname>LScube Project</orgname>
        </affiliation>

        <email>lu_zero@lscube.org</email>
      </author>

      <author>
        <personname>
          <firstname>Diego Elio</firstname>
          <surname>Pettenò</surname>
        </personname>

        <affiliation>
          <orgname>LScube Project</orgname>
        </affiliation>

        <email>flameeyes@lscube.org</email>
      </author>
    </authorgroup>

    <copyright>
      <year>2011</year>
      <holder>LScube Developers</holder>
    </copyright>
  </info>

  <section>
    <title>Reference</title>

    <refentry>
      <info>
        <date>February 2011</date>
        <productname>LScube</productname>
      </info>

      <refmeta>
        <refentrytitle>feng.conf</refentrytitle>
        <manvolnum>5</manvolnum>
      </refmeta>

      <refnamediv>
        <refname>feng.conf</refname>
        <refpurpose>
          Configuration file for <citerefentry><refentrytitle>feng</refentrytitle><manvolnum>1</manvolnum></citerefentry>
        </refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <synopsis><filename>feng.conf</filename></synopsis>

        <synopsis>
<command>options {</command>
    <command>username "</command><replaceable>user</replaceable><command>";</command>
    <command>groupname "</command><replaceable>group</replaceable><command>";</command>
    <command>log-level</command> <replaceable>level</replaceable><command>;</command>
    <command>error-log</command> <command>"</command><replaceable>error-log-path</replaceable><command>"</command> | <command>"syslog"</command> | <command>"stderr";</command>
    <command>buffered-frames</command> <replaceable>amount</replaceable><command>;</command>
<command>};</command>

<command>socket {</command>
    <command>listen-on "</command><replaceable>host</replaceable> | <replaceable>address</replaceable><command>";</command>
    <command>port "</command><replaceable>port number</replaceable> | <replaceable>port name</replaceable><command>";</command>
    <command>ipv6</command> <replaceable>true</replaceable> | <replaceable>false</replaceable><command>;</command>
    <command>sctp</command> <replaceable>true</replaceable> | <replaceable>false</replaceable><command>;</command>
    <command>sctp-streams </command><replaceable>amount</replaceable><command>;</command>
<command>};</command> ...

<command>vhost {</command>
    <command>aliases {</command>
        <command>"</command><replaceable>host.name1</replaceable><command>", </command>
        <command>"</command><replaceable>host.name2</replaceable><command>", </command>
        ...
    <command>};</command>
    <command>access-log "</command><replaceable>access-log-path</replaceable><command>"</command> | <command>"syslog"</command> | <command>"stderr";</command>
    <command>twin "</command><replaceable>mirror.host</replaceable><command>";</command>
    <command>document-root "</command><replaceable>document-root-path</replaceable><command>";</command>
    <command>virtuals-root "</command><replaceable>virtuals-root-path</replaceable><command>";</command>
    <command>max-connections </command><replaceable>amount</replaceable><command>;</command>
    <command>dynamic-resource-paths {</command>
        <command>"</command><replaceable>dynamic-path-1</replaceable><command>", </command>
        <command>"</command><replaceable>dynamic-path-2</replaceable><command>", </command>
        ...
    <command>};</command>
<command>};</command> ...
        </synopsis>
      </refsynopsisdiv>

      <refsection>
        <title>Description</title>

        <para>
          The <filename>feng.conf</filename> file is used to configure the basic parameters used by
          <command>feng</command> at runtime.
        </para>

        <para>
          The syntax is for the most part compatible with the ISC syntax used by
          <package>dhcp</package> and <package>bind</package> and as such it should be already of
          common knowledge for more experienced Unix administrators.
        </para>

        <para>
          Strings have to be enclosed in double-quotation marks (<emphasis>""</emphasis>); integers
          doesn't need to. String lists are enclosed in curly braces (<emphasis>{}</emphasis>), and
          contains a series of strings (in quotes) separated by commas.
        </para>
      </refsection>

      <refsection>
        <title>Options</title>

        <para>
          General options, for the daemon or for all the requests alike.
        </para>

        <variablelist>
          <varlistentry>
            <term><command>username</command> <replaceable>"string"</replaceable></term>
            <term><command>groupname</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Name (not number) of Unix user and group <command>feng</command> has to drop
                privileges to when started as root. These values are ignored if the software is not
                started as super user.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>log-level</command> <replaceable>integer</replaceable></term>

            <listitem>
              <para>
                Highest value of messages to output on the logs. <emphasis>TBD</emphasis>
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>error-log</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Destination for the error messages' output; it can be either a file (in a path
                writable by the user running <command>feng</command>), or the special values
                <emphasis>"syslog"</emphasis> (the messages are sent to the system log for the
                <emphasis>feng</emphasis> service) or <emphasis>"stderr"</emphasis> (the message are
                sent to the standard error of the process).
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>buffered-frames</command> <replaceable>integer</replaceable></term>

            <listitem>
              <para>
                <emphasis>TBD</emphasis>
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>Sockets</title>

        <para>
          To make <command>feng</command> listen to a given host and port pair, you should add a
          <command>socket</command> section; you can add as many sections as you need to listen to
          all the host and port pairs that you want.
        </para>

        <variablelist>
          <varlistentry>
            <term><command>listen-on</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Defines the address (or the host) <command>feng</command> will listen to; if you
                provide a hostname, a listening socket will be created for each of the addresses it
                resolves to (compatibly with the protocol settings below). IPv6 addresses do not
                need to be enclosed in square braces. If no <command>listen-on</command> option is
                passed, it defaults to listening on all interfaces.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>port</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Defines the port <command>feng</command> will listen to; you can provide either a
                numeric port, or a mnemonic port name as defined in
                <filename>/etc/services</filename>.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>ipv6</command> <replaceable>boolean</replaceable></term>

            <listitem>
              <para>
                Listen on the host's IPv6 addresses as well as IPv4 ones. For this option to make
                sense, you should have set a compatible <command>listen-on</command> option (or not
                have set it at all).
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>sctp</command> <replaceable>boolean</replaceable></term>

            <listitem>
              <para>
                Listen for SCTP (Stream Control Transmission Protocol) connections as well as TCP
                ones. For this option to make sense, the operating system needs to support SCTP, and
                <command>feng</command> has to be built with support for the protocol.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>sctp-streams</command> <replaceable>integer</replaceable> (1-255)</term>

            <listitem>
              <para>
                Number of streams to reserve for each SCTP connection. As an indication, on a
                complete SCTP permanent connection, one stream is reserved for the control session
                (RTSP), and two streams are assigned per streamed track (RTP and RTCP).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsection>

      <refsection>
        <title>Virtual Hosts</title>

        <para>
          A single listening socket might actually be accessible under more than a single hostname;
          the RTSP protocol allows to handle different requests coming for different hosts to the
          same listening socket. To implement this, <command>feng</command> allows to define virtual
          hosts, with different request settings.
        </para>

        <para>
          You can provide as many <command>vhost</command> section as you need; in case none of the
          given aliases matched, the settings in the first section are used as fallback default.
        </para>

        <important>
          <para>
            As of February 2010, <command>feng</command> only implements vhosts as part of the
            configuration syntax but does not make use of them at runtime. The only settings
            actually used are those of the first <command>vhost</command> section in the file.
          </para>
        </important>

        <variablelist>
          <varlistentry>
            <term><command>aliases</command> <replaceable>{ "string", "list" }</replaceable></term>

            <listitem>
              <para>
                A list of hostnames to be used to refer to the host; no wildcard-matching is
                implemented yet, so the hostnames for which <command>feng</command> will have to
                respond should be listed explicitly.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>access-log</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Destination of the access messages for the requests coming to the virtual host. The
                format used for logging is pretty much the CustomLog used by
                <package>apache</package>, and should be compatible with most statistic analysis
                tools for web servers.
              </para>

              <para>
                It can be either a file (in a path writable by the user running
                <command>feng</command>), or the special values <emphasis>"syslog"</emphasis> (the
                messages are sent to the system log for the <emphasis>feng</emphasis> service) or
                <emphasis>"stderr"</emphasis> (the message are sent to the standard error of the
                process).
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>twin</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Alternative host to redirect clients to if no more streaming slots are available. If
                the server is unable to provide more bandwidth to stream content to the clients
                connecting, it can be told to redirect users to a mirror host. Mirror hosts can be
                chained to provide more than one alternative.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>document-root</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Path to the origin of files to be served for the host, connected to
                <filename>rtsp://host/</filename>. Similarly to a web server's root, no paths above
                that directory will be served, unless linked from within that tree.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>virtuals-root</command> <replaceable>"string"</replaceable></term>

            <listitem>
              <para>
                Path to the origin of description files for virtual resources (as described in
                <citerefentry><refentrytitle>feng.sd2</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
                for content within <filename>rtsp://host/virtual/</filename>.
              </para>

              <para>
                Similarly to a web server's root, no paths above that directory will be served,
                unless linked from within that tree.
              </para>

              <para>
                This is a separate value, that can coincide with the document root, to allow sharing
                document root between RTSP and HTTP servers alike.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>max-connections</command> <replaceable>integer</replaceable></term>

            <listitem>
              <para>
                Maximum number of clients connected for the host before redirecting them to the
                configured <command>twin</command> (if any) or otherwise disconnecting them.
              </para>

              <note>
                <para>
                  This is a misnomer, as it should rather be the maximum number of open sessions
                  before the server is considered full.
                </para>
              </note>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>dynamic-resource-paths</command> <replaceable>{ "string", "list" }</replaceable></term>

            <listitem>
              <para><emphasis>TBD</emphasis></para>
            </listitem>
          </varlistentry>

        </variablelist>
      </refsection>

      <refsection>
        <title>See Also</title>

        <para>
          <citerefentry>
            <refentrytitle>feng</refentrytitle>
            <manvolnum>1</manvolnum>
          </citerefentry>
        </para>

      </refsection>
    </refentry>
  </section>
</article>
<!--
    Local Variables:
    mode: nxml
    mode: auto-fill
    mode: flyspell
    ispell-local-dictionary: "english"
    fill-column: 100
    indent-tabs-mode: nil
    End:
-->