jabber_user.sgml

sip server服务器

<!-- Module User's Guide -->

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.3 $</revnumber>
		<date>$Date: 2004/08/24 08:58:30 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    This is new version of Jabber module that integrates XODE <acronym>XML</acronym> parser
	    for parsing Jabber messages. That introduces a new module dependency: expat library.
	</para>
	<para>
	    Expat is a common <acronym>XML</acronym> library and is the fastest available for
	    Linux/Unix, the second over all, after msxml library. It is integrated in most of well
	    known Linux distributions.
	</para>
	<section>
	    <title>New Features</title>
	    <itemizedlist>
		<listitem>
		    <para>
			Presence support (see doc/xxjab.cfg for a sample cfg file) (January 2003).
		    </para>
		</listitem>
		<listitem>
		    <para>
			SIP to Jabber conference support (December 2003).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Possibility to manage all kinds of Jabber messages (message/presence/iq)
			(December 2003).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Aliases -- Possibility to set host aliases for addresses (see parameter's
			desc.) (December 2003).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Send received &sip; MESSAGE messages to different &im; networks (Jabber, ICQ,
			MSN, AIM, Yahoo) using a Jabber server (December 2003).
		    </para>
		</listitem>
		<listitem>
		    <para>
			Send incoming Jabber instant messages as &sip; MESSAGE messages.		
		    </para>
		</listitem>
		<listitem>
		    <para>
			Gateways detection -- Ability to see whether an &im; gateway is up or down.			
		    </para>
		</listitem>
	    </itemizedlist>
	</section>
    </section>


    <section>
	<title>Admin's Guide</title>
	<note>
	    <para>
		A more complete guide about SIMPLE2Jabber gateway can be found at &serhomelink;. The
		part below will be removed soon, only the manual from web will be updated.
	    </para>
	</note>
	<para>
	    The Jabber server setup is not a subject of this guide. Check <ulink
		url="http://www.jabber.org">http://www.jabber.org</ulink> for that.
	</para>
	<para>
	    Useful scripts, for creating Jabber Gateway database, or for managing the Jabber
	    accounts form web are located in 'doc' subdirectory of the module.
	</para>
	<para>
	    Main steps of using the Jabber gateway:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    Create the MySQL database.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Setup the local Jabber server.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Set the module parameter values in cfg file of &ser;, load the dependent
		    modules, set up the routing rules for Jabber gateway.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Run &ser;.
		</para>
	    </listitem>
	</itemizedlist>
	<para>
	    The administrator of &ser;/Jabber gateway <emphasis>must</emphasis> inform the users
	    what are the aliases for Jabber/Other &im; networks. Other &im;s could be
	    <acronym>AIM</acronym>, <acronym>ICQ</acronym>, <acronym>MSN</acronym>, Yahoo, and so
	    on.
	</para>
	<para>
	    These aliases depend on the server hostname where runs &ser; and how local Jabber
	    server is setup.
	</para>
	<para>
	    Next is presented a use case. Prologue:
	</para>
	<itemizedlist>
	    <listitem>
		<para>&ser; is running on <quote>server.org</quote>.</para>
	    </listitem>
	    <listitem>
		<para>
		    Local Jabber server is running on <quote>jabsrv.server.org</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Jabber network alias (first part of <quote>jdomain</quote>) is
		    <quote>jabber.server.org</quote>
		</para>
	    </listitem>
	</itemizedlist>
	<para>
	    The aliases for other &im; networks <emphasis>must</emphasis> be the same as
	    <acronym>JID</acronym> set in Jabber configuration file for each &im; transport.
	</para>
	<para>
	    The <acronym>JIDs</acronym> of Jabber transports <emphasis>must</emphasis> start with
	    the name of the network. For <acronym>AIM</acronym>, <acronym>JID</acronym> must start
	    with <quote>aim.</quote>, for <acronym>ICQ</acronym> with <quote>icq</quote> (that
	    because I use icqv7-t), for <acronym>MSN</acronym> with <quote>msn.</quote> and for
	    Yahoo with <quote>yahoo.</quote>. The gateway needs these to find out what transport is
	    working and which not. For our use case these could be like
	    <quote>aim.server.org</quote>, <quote>icq.server.org</quote>,
	    <quote>msn.server.org</quote>, <quote>yahoo.server.org</quote>.
	</para>
	<para>
	    It is indicated to have these aliases in <acronym>DNS</acronym>, thus the client
	    application can resolve the <acronym>DNS</acronym> name. Otherwise there must be set the
	    outbound proxy to &ser; server.
	</para>
	<para>
	    *** Routing rules for Jabber gateway First step is to configure &ser; to recognize
	    messages for Jabber gateway. Look at <quote>doc/xjab.cfg</quote> to see a sample. The
	    idea is to look in messages for destination address and if it contains Jabber alias or
	    other &im; alias, that means the message is for Jabber gateway.
	</para>
	<para>
	    Next step is to find out what means that message for Jabber gateway. It could be a
	    special message what triggers the gateway to take an action or is a simple message which
	    should be delivered to Jabber network (using the method
	    <quote>jab_send_message</quote>).
	</para>
	<para>
	    The special messages are for: 
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    Registering to Jabber server (go online in Jabber network)--here must be called
		    <quote>jab_go_online</quote> method.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Leaving the Jabber network (go offline in Jabber network)--here must be called
		    <quote>jab_go_offline</quote> method.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Joining a Jabber conference room--here must be called <quote>jab_join_jconf</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Leaving a Jabber conference room--here must be called <quote>jab_exit_jconf</quote>.		    
		</para>
	    </listitem>
	</itemizedlist>
	<para>
	    The destination address <emphasis>must</emphasis> follow the following patterns:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    For Jabber network: <quote>username&lt;delim&gt;jabber_server@jabber_alias</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    For Jabber conference: <quote>nickname&lt;delim&gt;room&lt;delim&gt;conference_server@jabber_alias</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    For <acronym>AIM</acronym> network: <quote>aim_username@aim_alias</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    For <acronym>ICQ</acronym> network: <quote>icq_number@icq_alias</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    For <acronym>MSN</acronym> network:
			<quote>msn_username&lt;delim&gt;msn_server@msn_alias</quote>. msn_server can
		    be <quote>msn.com</quote> or <quote>hotmail.com</quote>.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    For YAHOO network: <quote>yahoo_username@yahoo_alias</quote>.
		</para>
	    </listitem>
	</itemizedlist>
	<note>
	    <para>
		<quote>jabber_alias</quote> is the first part of <quote>jdomain</quote>.
	    </para>
	</note>
    </section>
    <section>
	<title>User's Guide</title>
	<para>
	    The user must activate his Jabber account associated with his &sip; id. For each other
	    &im; network on which he wants to send messages, he must set an account for that &im;
	    network. The gateway is not able to create new account in foreign networks, excepting
	    local Jabber server.
	</para>
	<para>
	    When you want to send a message to someone in other &im; network, you must set the
	    destination of the message according with the pattern corresponding to that &im; network
	    (see last part of <quote>Admin guide</quote> chapter).
	</para>
	<para>
	    Sending a message to [e-mail] which is in Jabber network, the
	    destination must be: user&lt;delim&gt;jabber.xxx.org@jabber_alias.
	</para>
	<para>
	    For someone who is in Yahoo network the destination must be:
	    user@yahoo_alias
	</para>
	<note>
	    <para>
		The &ser; administrator have to set the Jabber transports for each &im; network in
		order to be able to send messages to those networks. The alias of each &im; network
		can be found out from &ser; admin.
	    </para>
	    <para>
		You cannot send messages from your &sip; client to your associated Jabber
		account--is something like sending messages to yourself.
	    </para>
	</note>
    </section>

    <section>
	<title>Dependencies</title>
	<section>
	    <title>&ser; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    A database module.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    <emphasis>pa</emphasis> (Optionally) - Presence Agent.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    <emphasis>tm</emphasis> - Transaction Manager.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&ser; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>Expat</emphasis> library.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Exported Parameters</title>
	<section>
	    <title><varname>db_url</varname> (string)</title>
	    <para>
		<acronym>SQL</acronym> &url; of database.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>mysql://root@127.0.0.1/sip_jab</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "db_url", "mysql://username:password@host/sip_jab")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>jaddress</varname> (string)</title>
	    <para>
		&ip; or hostname of Jabber server -- it must be the same as the value from &lt;host&gt;
		tag of Jabber server config file.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>127.0.0.1</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>jaddress</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jabber", "jaddress", "1.2.3.4")
...
</programlisting>
	    </example>
	</section>