~ctrlproxy/ctrlproxy/trunk

<ctrlproxy:module name="socket"

        xmlns:ctrlproxy="http://ctrlproxy.vernstok.nl/common">

        <modulemeta>

                <description>Support for IPv4, IPv6 and pipes</description>

                <version>0.1</version>

                <author>Jelmer Vernooij</author>

                <homepage>http://jelmer.vernstok.nl/ctrlproxy/</homepage>

                <requires>SSL(optional)</requires>

        </modulemeta>

 

        <description>

                <para>This module provides support for connecting to remote 

                servers using IPv4, IPv6 and unix pipes, as well 

                as listening for client connections using these connection 

                types.</para>

 

                <para>As this module is currently the only module providing 

                connection support, it is essential for basic use of 

                ctrlproxy.</para>

 

                <para>Connecting or listening using SSL over IPv4 or IPv6 

                is supported when a SSL library was found at configure time.</para>

 

                <para>When acting as a SSL server (e.g. waiting for connections from 

                        clients and communicating with them using SSL), ctrlproxy 

                        needs to have a certificate file and a private key file. 

                        This can be generated using the <filename>mksslcert.sh</filename>

                        script distributed with ctrlproxy.</para>

        </description>

 

        <configuration>

                <element name="sslkeyfile">

                        <description>Name of file to load private SSL key from. Only required when acting as a server</description>

                </element>

 

                <element name="sslcertfile">

                        <description>Name of file to load certificate from. Only required when acting as a server</description>

                </element>

        </configuration>

 

        <section>

                <title>Configuration</title>

 

                <para>After this module is loaded, the following three new elements are supported in &lt;listen&gt; and &lt;servers&gt;:</para>

 

                <simplelist>

                <member>ipv4</member>

                <member>ipv6</member>

                <member>pipe</member>

                </simplelist>

 

                <para>ipv4 and ipv6 support the following attributes:</para>

                <variablelist>

                        <varlistentry><term>ssl</term>

                        <listitem><para>Enable SSL</para></listitem>

                        </varlistentry>

 

                        <varlistentry><term>host</term>

                        <listitem><para>Host name or IP address to connect to.

                        </para></listitem></varlistentry>

 

                        <varlistentry><term>port</term>

                        <listitem><para>Port to connect to or listen on.</para></listitem>

                        </varlistentry>

                </variablelist>

 

                <para>When connecting, the pipe element can contain one member 

                element &lt;path&gt; and several &lt;arg&gt; elements. These 

                should contain a program with arguments to execute.</para>

 

                <para>In listen mode, a file attribute (attribute, not element!) should be specified, containing the file name of the unix socket to create. If no file name is specified, one will be generated.</para>

 

        </section>

 

        <example>

                <![CDATA[

                <ctrlproxy>

                        <plugins>

                                <plugin autoload="1" file="socket">

                                        <sslcertfile>ctrlproxy.pem</sslcertfile>

                                        <sslkeyfile>ctrlproxy.pem</sslkeyfile>

                                </plugin>

                        </plugins>

                        <networks>

                                <network name="BEE">

                                        <servers>

                                                <pipe>

                                                        <path>/usr/sbin/bitlbee</path>

                                                </pipe>

                                                <ipv4 host="localhost"/>

                                        </servers>

                                        <listen>

                                                <ipv4 ssl="1" port="6667"/>

                                </network>

                                <network name="DSR">

                                        <servers>

                                                <ipv6 host="irc.ipv6.distributed.net"/>

                                                <ipv4 host="irc.distributed.net" port="994" ssl="1"/>

                                        </servers>

                                        <listen>

                                                <ipv4 port="6668"/>

                                                <ipv6 port="6669" ssl="1"/>

                                        </listen>

                                </network>

                        </networks>

                </ctrlproxy>

        ]]>

        </example>

</ctrlproxy:module>