<?xml version='1.0'?>

<!--

Copyright © 2008-2011, Diego "Flameeyes" Pettenò <[email protected]>

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>[email protected]</email>

</author>

<author>

<personname>

<firstname>Diego Elio</firstname>

<surname>Pettenò</surname>

</personname>

<affiliation>

<orgname>LScube Project</orgname>

</affiliation>

<email>[email protected]</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:

-->