jabber_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.3 $</revnumber>
		<date>$Date: 2005/10/27 17:57:25 $</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>