Configuration Files

The /etc/flumotion directory contains a managers directory and a workers directory, which should both contain XML files. These files may be in sub-directories and may be split up into separate XML files. See the Managers and Workers section of the Architecture chapter.

The Manager's Configuration

The managers directory typically contains a sub-directory for each manager (usually only one), containing a planet.xml file. This file contains an XML node for the planet. This in turn contains nodes for the Planet's manager, atmosphere and flow, which themselves contain component nodes.

[Note] Note

Alternatively, the manager, flow and atmosphere nodes may be in separate XML files, also with parent planet nodes. These files will then be merged at runtime by Flumotion, without changing the files. This can make the configuration clearer.

In the manager node, you can specify the manager's hostname and the port number and transport protocol that it should use, but you can usually just use the defaults. You should always use the default ssl transport protocol, for secure connections, unless you are running Flumotion on an embedded device with very restricted resources.

By specifying localhost for the manager's hostname, you can also restrict access to workers that are running on the same computer, though this would rarely be appropriate for a real Flumotion system.

Components

Each component XML node specifies the component name and type, which worker process it should belong to, and what feeding component it should receive data from, along with the specific properties for the component type.

See also the Components section of the Architecture chapter and the Components Reference section.

Eaters and Feeds

Each flow component, apart from producers (and apart from non-flow components such as bouncers), receives data from one or more other components. This data stream is called a Feed. The eater node specifies the name of the upstream component that feeds data to the component, in the child feed node. When the feeding component has more than one output (also known as a Feeder), the specific output must be named by placing it after the component name, separated by a colon. For instance, <eater><feed>firewire-producer:audio</feed></eater>.

Version

The component node's version attribute is optional. You might use this to specify the exact version of Flumotion that you are using, if you are using a component whose available properties are likely to change in a future version of Flumotion If you try to use the XML configuration file with another version of Flumotion then you will see a warning in the log files and in the administration UI.

Flumotion also uses this version number to help it adapt when using a newer version of Flumotion, choosing to interpret the configuration as it would have been interpreted by the earlier version of Flumotion. However, you should eventually update the configuration for the new properties supported by the component.

Project

The component node's project attribute is optional, defaulting to "flumotion". This specifies the set of components from which the component is available, with "flumotion" being the core set. To use a component from an additional set, you should specify the name of that set for the project attribute.

Additional components are available from the following sets:

flumotion-bouncer

Additional Bouncer components.

flumotion-flash

Components for Flash video streaming.

flumotion-windowsmedia

Components for WindowsMedia streaming.

Plugs

Plugs allow extra features to be added to components. Each component may have certain sockets which allow the component to use appropriate plugs. Likewise, each plug is compatible with a particular socket.

For instance, see the Logging section, or the Limiting Bandwidth section.

Logging

Many components can output log files to disk. This is useful for troubleshooting, monitoring, or billing.

For instance, this example specifies an apachelogger plug for the Logger socket of a http-server component, and specifies the logfile property for that plug.

<component name="http-server-one"
           type="http-server"
  ...
  <plugs>
    <plug socket="flumotion.component.plugs.loggers.Logger"
          type="requestlogger-file">
      <property name="logfile">/tmp/flumotion-one.log</property>
    </plug>
  </plugs>
  ...
</component>

Inspecting Components and Plugs

You can discover information about a component type, including the list of Feeders that it provides, and the properties that you can set, and the sockets that it has, by using the flumotion-inspect command. This command can also provide information about a plug.

For instance, flumotion-inspect firewire-producer.For instance:


$ flumotion-inspect firewire-producer

Component:
  firewire-producer
  Produce feeds from a Firewire/DV device.

Source:
  flumotion.component.producers.firewire.firewire
  in flumotion/component/producers/firewire

Eaters:
  (None)

Feeders:
  audio
  video
  dv

Features:
  admin/gtk: admin_gtk.py:GUIClass
  component: firewire.py:Firewire
  wizard: wizard_gtk.py:FireWireWizardPlugin

Properties:
     framerate: type fraction, optional
                The framerate (in fps) 
          guid: type string, optional
                The GUID of the device (a hexadecimal like 0xhhhhhhhhhhhhhhhh)
        height: type int, optional
                The height to scale to
     is-square: type bool, optional
                Whether to scale to a 1:1 pixel aspect ratio
  scaled-width: type int, optional
                The width to scale to before correcting
         width: type int, optional
                The final width, including correction

Clocking:
  Needs synchronisation: True
  Clock priority: 160

Sockets:

        

Repeaters

A repeater component can avoid excessive use of network bandwidth. For instance, if both a http-streamer and disk-consumer component on a remote computer should use the same ogg-muxer component as their feeding component, an intermediate repeater component on the remote machine can be used as the feeding component instead. This means that the data is sent over the network only once, to the repeater component.

The Manager Bouncer

The manager node contains just one special component, for the manager-bouncer, which controls access to the manager from the worker processes.

Because there is currently only one supported type of Manager Bouncer, the type attribute must be htpasswdcrypt-bouncer.

For the htpasswdcrypt-bouncer, the user name and crypted password can be provided via a property node, setting the data property. For instance, this example shows the default username of "user" with the default password of "test"

<component name="manager-bouncer" type="htpasswdcrypt-bouncer">
  <property name="data">user:PSfNpHTkpTx1M</property>
</component>

Alternatively, you may use an external file, by providing the file path as the value of a file property node. For instance,

<component name="manager-bouncer" type="htpasswdcrypt-bouncer">
  <property name="file">/etc/flumotion/managers/default/htpasswd</property>
</component>

See the htpasswdcrypt-bouncer reference section.

The workers must specify one of these user name and password combination when logging into the manager. See the Remote Workers Configuration section.

[Note] Note

You can create the credentials, including the crypted password, using the htpasswd command, as provided by the Apache web server package.

For example, to create a file containing credentials for username “someone” and password “s3kr3t”, type this command in a terminal:

htpasswd -d -c passwords someone

The program will ask you to type the password twice:

New password:
Re-type new password:
Adding password for user someone

Check the generated file by typing cat passwords which will show: [1]

someone:5jKUrPB0Xbzos

Note that, while it is possible to specify passwords on the command line when creating this file, by using the -p option, this is bad for security reasons. The command line is visible to anyone logged in to the machine, as well as recorded in the shell's history.

Other Bouncers

All Flumotion systems should have a Manager Bouncer, as described in the Manager Bouncer section. Some systems may require additional bouncers, for instance to restrict access to the streamer component to certain users or IP addresses. These bouncer components should be declared in the atmosphere node rather than the flow node.

For instance, you might add a htpasswdcrypt-bouncer component to the atmosphere like so:

<planet>
  <atmosphere>
    <component name="streamer-bouncer" project="flumotion"
               type="htpasswdcrypt-bouncer"
               version="0.5.2.1" worker="localhost">
    <property name="data"><testuser:Z5WEs3ezyz0E2>
      </property>
    </component>
  </atmosphere>

You could then simply specify this bouncer as a property for the streamer components's node, causing the user's web browser or player to prompt the user for a username and password. For instance:

<component name="http-audio" project="flumotion"
               type="http-streamer" version="0.5.2.1" worker="localhost">
...
  <property name="bouncer">streamer-bouncer</property">

See the Manager Bouncer section for instructions to create the htpasswd string. You may instead specify a filename as a property, allowing you to update the list of allowed users and passwords from a different system.

There is also an ip-bouncer Bouncer that can allow or deny ranges of IP addresses instead of demanding a password.

Example

This example was exported from Flumotion's Configuration Assistant after choosing the test audio and video inputs. A node for the manager was then added.

Example File

<planet name="example-planet">

  <manager name="example-planet-manager">
    <!-- <host>something.somedomain</host> --> 
    <!-- Uses the current hostname if not specified. -->

    <!-- <port>7531</port> -->
    <!-- Uses 7531 for SSL or 8642 for TCP if not specified. -->

    <!-- <transport>ssl</transport> -->
    <!-- Uses ssl if not specified. Otherewise tcp. -->

    <!-- <certificate>default.pem</certificate> -->
    <!-- Uses /etc/flumotion/default.pem if not specified. -->

    <component name="manager-bouncer" type="htpasswdcrypt-bouncer">
      <property name="data">user:PSfNpHTkpTx1M</property>
    </component>
  </manager>

  <atmosphere>
    <component name="http-server-audio-video"
               type="http-server"
               label="http-server-audio-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <property name="porter-username">pycBUhaLQlwt</property>
      <property name="mount-point">/ogg-audio-video/cortado/</property>
      <property name="porter-password">nWbDPQzKKrMa</property>
      <property name="type">slave</property>
      <property name="porter-socket-path">flu-KbVvOp.socket</property>
      <property name="port">8800</property>
      <plugs>
        <plug socket="flumotion.component.plugs.base.ComponentPlug"
              type="component-cortado">
          <property name="has-audio">True</property>
          <property name="buffer-size">40</property>
          <property 
            name="stream-url">http://localhost:8800/ogg-audio-video/</property>
          <property name="framerate">5.0</property>
          <property name="height">240</property>
          <property
  name="codebase">http://localhost:8800/ogg-audio-video/cortado/</property>
          <property name="width">320</property>
          <property name="has-video">True</property>
        </plug>
      </plugs>
    </component>
    
    <component name="porter-http"
               type="porter"
               label="porter-http"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <property name="username">pycBUhaLQlwt</property>
      <property name="socket-path">flu-KbVvOp.socket</property>
      <property name="password">nWbDPQzKKrMa</property>
      <property name="port">8800</property>
    </component>
    
  </atmosphere>
  
  <flow name="default">
    <component name="producer-audio"
               type="audiotest-producer"
               label="producer-audio"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <property name="volume">1.0</property>
      <property name="rate">44100</property>
      <property name="frequency">440</property>
      <clock-master>true</clock-master>
    </component>
    
    <component name="producer-video"
               type="videotest-producer"
               label="producer-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <property name="pattern">0</property>
      <property name="framerate">50/10</property>
      <property name="width">320</property>
      <property name="height">240</property>
      <clock-master>false</clock-master>
    </component>
    
    <component name="overlay-video"
               type="overlay-converter"
               label="overlay-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <eater name="default">
        <feed alias="default">producer-video:default</feed>
      </eater>
      <property name="show-text">True</property>
      <property name="xiph-logo">True</property>
      <property name="text">Flumotion</property>
      <property name="cc-logo">True</property>
      <property name="height">240</property>
      <property name="width">320</property>
      <property name="fluendo-logo">True</property>
      <clock-master>false</clock-master>
    </component>
    
    <component name="encoder-video"
               type="theora-encoder"
               label="encoder-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <eater name="default">
        <feed alias="default">overlay-video:default</feed>
      </eater>
      <property name="keyframe-maxdistance">10</property>
      <property name="sharpness">0</property>
      <property name="quality">16</property>
      <property name="noise-sensitivity">1</property>
      <clock-master>false</clock-master>
    </component>
    
    <component name="encoder-audio"
               type="vorbis-encoder"
               label="encoder-audio"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <eater name="default">
        <feed alias="default">producer-audio:default</feed>
      </eater>
      <property name="bitrate">64000</property>
      <clock-master>false</clock-master>
    </component>
    
    <component name="muxer-audio-video"
               type="ogg-muxer"
               label="muxer-audio-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <eater name="default">
        <feed alias="default">encoder-audio:default</feed>
        <feed alias="default-bis">encoder-video:default</feed>
      </eater>
      <clock-master>false</clock-master>
    </component>
    
    <component name="http-audio-video"
               type="http-streamer"
               label="http-audio-video"
               worker="localhost"
               project="flumotion"
               version="0.5.2.1">
      <eater name="default">
        <feed alias="default">muxer-audio-video:default</feed>
      </eater>
      <property name="porter-username">pycBUhaLQlwt</property>
      <property name="mount-point">/ogg-audio-video/</property>
      <property name="porter-password">nWbDPQzKKrMa</property>
      <property name="type">slave</property>
      <property name="porter-socket-path">flu-KbVvOp.socket</property>
      <property name="burst-on-connect">False</property>
      <clock-master>false</clock-master>
      <plugs>
      </plugs>
    </component>
    
  </flow>

</planet>

The Workers' Configuration

The workers directory typically contains an XML file for the worker that runs on the computer, containing an XML node for the worker. This in turn contains nodes for the manager which the worker should login to, and an authentication node which specifies how this login should be done. You can specify the manager's port and transport protocol, but you can usually just use the defaults.

[Note] Note

The password is written as plaintext in the worker's configuration file but, as long as your worker is using the SSL transport protocol it is not actually passed over the network as cleartext.

The actual list of components for the worker, and the properties for those components, is in the manager's configuration. The manager will tell the worker what components to start, with what properties, after the worker logs in to the manager. This keeps the majority of the configuration on one computer, where the manager runs.

The feederport node specifies an additional range of ports that the worker may use for unencrypted TCP connections, after a challenge/response authentication. For instance a component in the worker may need to communicate with components in other workers, to receive feed data from other components. In some cases the worker may open up UDP ports in this range as well, for instance if a component is a clock master, used for synchronization. Two ports are usually enough.

Example

This is an example of the configuration file for a worker.

Example File

<?xml version="1.0"?>
<worker>
<!--
You can override the name of the worker, which will typically be
hostname:(xmlfilename)
<worker name="default">
-->

    <manager>
<!--
      This specifies what manager to log in to.
      Compare with command-line options.
-->
      <host>somehost.somedomain</host>
      <!-- <port>7531</port> --> 
      <!-- Defaults to 7531 for SSL or 8642 for TCP if not specified. -->

      <!-- <transport>ssl</transport> -->
      <!-- Defaults to ssl if not specified. -->
-
    </manager>

    <authentication type="plaintext">
<!--
      This specifies what authentication to use to log in.
      Compare with command-line options.
-->
      <username>user</username>
      <password>test</password>
    </authentication>

    <feederports>8650-8651</feederports>
    <!-- A small port range for the worker to use as it wants. -->

    <debug>*:4</debug>

</worker>

Setting Up Remote Flumotion Workers

One of the most powerful features of Flumotion is its ability to distribute work over many separate computers. In this section, we cover basic configuration instructions for Flumotion when used in this way.

By default, the installation of Flumotion only allows connections to the manager from the local host, for security reasons. If you want to allow workers or administration clients to log in from other hosts then you should change the authentication settings and remove the host node from the manager's configuration file, usually at /etc/flumotion/managers/default/planet.xml.

You should then tell the Flumotion workers to log into the remote manager by adding the needed configuration in the workers's configuration file, usually at /etc/flumotion/workers/default.xml. When configured for remote connections this file will look something like this:

<worker>
  <manager>
    <host>stream.test.com</host>
    <port>7531</port>
  </manager>

  <authentication type="plaintext">
    <username>user</username>
    <password>test</password>
  </authentication>
</worker>

In this example we have used stream.test.com as the example remote server where the manager is running and we are using the default Flumotion SSL port 7531.

[Note] Note

You could also connect the worker directly from the command line by using this syntax:

flumotion-worker -H stream.test.com -P 7531 -u user -p test.

You can get more information on these and other command line parameters by reading the flumotion-worker man page (type man flumotion-worker) or by running flumotion-worker -h on the command line.



[1] The actual crypted password may of course vary because of how the crypt algorithm works.