ser-howto.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [

<!--Include general SER documentation entities -->
<!ENTITY % serentities SYSTEM "../ser_entities.sgml">
%serentities;

]>

<book>
    <bookinfo>
	<title>&ser; HOWTO</title>
	<authorgroup>
	    <author>
		<firstname>Dan</firstname>
		<surname>Austin</surname>
	    </author>
	    <editor>
		<firstname>Nils</firstname>
		<surname>Ohlmeier</surname>
		<address>
		    <email>[e-mail]</email>
		</address>
	    </editor>
	</authorgroup>
	<copyright>
	    <year>2002-2003</year>
	    <holder>NSI Ltd.</holder>
	</copyright>
    </bookinfo>
    <toc></toc>
    
    <chapter>
	<title>Introduction</title>
	<section>
	    <title>Revision</title>
	    <itemizedlist>
		<listitem>
		    <para>
			Version 0.1      12/02/2002      Dan Austin
		    </para>
		</listitem>
		<listitem>
		    <para>
			Version 0.2      12/03/2002      Dan Austin
		    </para>
		</listitem>
		<listitem>
		    <para>
			Version 1.0      12/06/2002      Dan Austin
		    </para>
		</listitem>
		<listitem>
		    <para>
			Version 1.1      12/16/2002      Dan Austin
		    </para>
		</listitem>
		<listitem>
		    <para>
			Version 2.0      10/04/2003      NSI Ltd.
		    </para>
		</listitem>
	    </itemizedlist>
	    <para>
		This document is a result of a merge of two documents <ulink
		    url="http://www.fitawi.com/ser-Howto.html"></ulink> and <ulink
		    url="http://cvs.berlios.de/cgi-bin/viewcvs.cgi/*checkout*/ser/sip_router/INSTALL?rev=ser_0_8_10&amp;content-type=text/plain"></ulink>
		with some add-ons, made by NSI team.
	    </para>
	</section>
	<section>
	    <title>Why &ser;</title>
	    <para>
		&ser; is an open-source project that aims to make available a fully functional and
		scalable Session Initiated Protocol server. Call processing is described with a
		concise scripting language that offers the flexibility of regular expressions and
		the ability to interface with 3rd party applications for the purposes of call
		accounting and authorization.
	    </para>
	</section>
	<section>
	    <title>Where to get &ser;</title>
	    <para>
		&ser is available for download from <ulink
		    url="ftp://ftp.berlios.de/pub/ser"></ulink>
	    </para>
	    <para>
		The newest release may be found in the folder /latest
	    </para>
	</section>
    </chapter>
    <chapter>
	<title>Installation</title>
	<section>
	    <title>Installation Notes</title>
	    <para>
		Supported architectures:
	    </para>
	    <itemizedlist>
		<listitem>
		    <para>
			Linux/i386
		    </para>
		</listitem>
			<listitem>
		    <para>
			Linux/armv4l
		    </para>
		</listitem>
		<listitem>
		    <para>
			FreeBSD/i386
		    </para>
		</listitem>
		<listitem>
		    <para>
			OpenBSD/i386
		    </para>
		</listitem>
		<listitem>
		    <para>
			Solaris/sparc64
		    </para>
		</listitem>
		<listitem>
		    <para>
			NetBSD/sparc64
		    </para>
		</listitem>
	    </itemizedlist>
	    <para>
		(For other architectures the Makefiles might need to be edited) There are various
		configuration options defined in the Makefile and Makefile.defs.
	    </para>
	</section>
	<section>
	    <title>Requirements</title>
	    <itemizedlist>
		<listitem>
		    <para>
			gcc or icc : gcc &gt;= 2.9x; &gt;=3.1 recommended (it will work with older version
			but it might require some options tweaking for best performance)
		    </para>
		</listitem>
		<listitem>
		    <para>
			bison or yacc (Berkley yacc)
		    </para>
		</listitem>
		<listitem>
		    <para>
			flex
		    </para>
		</listitem>
		<listitem>
		    <para>
			<acronym>GNU</acronym> make (on Linux this is the standard
			<quote>make</quote>, on FreeBSD and Solaris is called <quote>gmake</quote>)
		    </para>
		</listitem>
		<listitem>
		    <para>
			sed and tr (used in the make files)
		    </para>
		</listitem>
		<listitem>
		    <para>
			<acronym>GNU</acronym> tar (<quote>gtar</quote> on Solaris) and gzip if you
			want <quote>make tar</quote> to work.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<acronym>GNU</acronym> install or <acronym>BSD install (on Solaris
			<quote>ginstall</quote>) if you want <quote>make install</quote>,
			<quote>make bin</quote>, <quote>make sunpkg</quote> to work.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<quote>mysql</quote> if you need MySQL support.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<quote>Apache (httpd)</quote> if you want serweb support
		</para>
		</listitem>
		<listitem>
		    <para>
			<quote>PHP, MySQL-PHP</quote> for serweb support
		    </para>
		</listitem>
		<listitem>
		    <para>
			libmysqlclient & libz (zlib) if you want mysql support (the mysql module)
		    </para>
		</listitem>
		<listitem>
		    <para>
			libexpat if you want the jabber gateway support (the jabber module)
		    </para>
		</listitem>
	    </itemizedlist>
	    <para>
		Installing &ser; on a RedHat Linux distribution for example, is a simple matter of
		unzipping the downloaded file and using your favorite package manager.
	    </para>
	</section>
	<section>
	    <title>Install the package</title>
	    <para>
		Example:
	    </para>
	    <screen>
		/root&gt;rpm -i ser-08.11-1.i386.rpm
	    </screen>
	    <para>
		Packages for other popular distributions are available, and can be installed using
		the appropriate package manager for that distribution.
	    </para>
	    <para>
		On many platforms you can start the service with:
	    </para>
	    <screen>
		/etc/init.d/ser start
	    </screen>
	    <para>
		RedHat systems will use:
	    </para>
	    <screen>
		/etc/rc.d/init.d/ser start
	    </screen>
	    <para>
		You now have a functioning &sip; server, but what can you do with it?  At this point
		not very much. With an &sip; client, such as Microsoft MSN Messenger 4.6, you can
		register with the server, send Instant Messages to other logged on clients of the
		same server, and even have voice conversations with them.
	    </para>
	    <para>
		That sounds pretty good, but maybe you'd like to add a little more security, or make
		you server accessible to others.
	    </para>
	</section>
	<section>
	    <title>Serctl Utility</title>
	    <para>
		To do so, first set the environment variable SIP_DOMAIN to your domain name, e.g.,
		in Bourne shell (bash), call:
	    </para>
	    <screen>
		export SIP_DOMAIN=<quote>foo.bar</quote>
	    </screen>
	    <para>
		If you wont the system to created this variable automatically, you need to add the
		line
	    </para>
	    <screen format="linespecific">
export SIP_DOMAIN=<quote>foo.bar</quote>
</screen>
	    <para>
		in the end of file /etc/profile.
	    </para>
	    <para>
		If you are using other than 'localhost' mysql server for maintaining subscriber
		database, change the variable 'SQL_HOST' to the proper host name in the serctl
		script.
	    </para>
	    <para>
		Run the serctl utility
	    </para>
	    <screen>
		/usr/sbin/serctl monitor
	    </screen>
	    <para>
		If you installed from a tar.gz or Solaris package:
	    </para>
	    <screen format="linespecific">
/usr/local/sbin/serctl monitor
 </screen>
	</section>
	<section>
	    <title>DNS SVR Resource Records</title>
	    <para>
		It is important that your &sip; clients can connect to your server for purposes of
		registration and call control.  You might even want to have a redundant server to
		handle calls if your primary server is unavailable.
	    </para>
	    <para>
		These requirements can be meet by using <acronym>DNS</acronym>
		<acronym>SVR</acronym> Resource Records, available in BIND 8.X and up releases.
	    </para>
	    <para>
		The format for a <acronym>SVR RR</acronym> is this:
	    </para>
	    <screen format="linespecific">
_service._protocol        SVR Priority Weight     Port hostname
</screen>
	    <para>
		In this case we want to establish an entry for our primary &sip; server,
		gateway.mydomain.com, that will listen on &udp; port 5060.  The entry will look like
		this:
	    </para>
	    <screen format="linespecific">
_sip._udp         SRV     0  0   5060  gateway.mydomain.com
</screen>
	    <para>
		Placement of the new resource record is important.  Here is a sample zone file:
		</para>
		<para>
		<screen format="linespecific">
; zone 'mydomain.com'   last serial 1998071308
$ORIGIN com.
mydomain  86400           IN      SOA     gateway.mydomain.com. postmaster.mydomain.com. (
                                        1998111908 ; Serial
                                        36000 ; Refresh
                                        900 ; Retry
                                        36000 ; Expire
                                        28800 ); Minimum
                IN      NS              gateway.mydomain.com.
                IN      NS              ns3.backupdomain.com.
                IN      MX              1 gateway.mydomain.com.
                IN      A               192.168.0.1

;If we place the SRV record above the next line it fails to load
$ORIGIN fitawi.com.
_sip._udp               SRV  0 0  5060  gateway.mydomain.com.
gateway         IN      A               192.168.0.1
www             IN      CNAME           gateway.mydomain.com.
</screen>
	    </para>
	    <para>
		After reloading your zone file you can verify that the entry is working by using dig.
	    </para>
	    <screen format="linespecific">
dig -t SRV _sip._udp.mydomain.com
</screen>
	    <para>
		The results should look something like this:
	    </para>
	    <para>
		<screen format="linespecific">
; &lt;&lt;&gt;&gt; DiG 9.1.0 &lt;&lt;&gt;&gt; -t SRV _sip._udp.mydomain.com
;; global options:  printcmd
;; Got answer:
;; -&gt;&gt;HEADER&lt;&lt;- opcode: QUERY, status: NOERROR, id: 32654
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 1

;; QUESTION SECTION:
;_sip._udp.mydomain.com.          IN      SRV

;; ANSWER SECTION:
_sip._udp.mydomain.com.   86400   IN   SRV   0 0 5060 gateway.mydomain.com.

;; AUTHORITY SECTION:
mydomain.com.             86400   IN      NS      ns3.elsewhere.com.
mydomain..com             86400   IN      NS      gateway. mydomain.com.

;; ADDITIONAL SECTION:
gateway. mydomain.com.     86400   IN      A       192.168.0.150

;; Query time: 6 msec
;; SERVER: 192.168.0.150#53(192.168.0.150)
;; WHEN: Tue Dec  3 08:34:17 2002
;; MSG SIZE  rcvd: 132
</screen>
	    </para>
	</section>
	<section>
	    <title>Adding a database for client information</title>
	    <para>
		By leveraging a MySQL database, we can provide support for user credentials, and
		keeping track of where the clients are logged on during server restarts.
	    </para>
	</section>
	<section>
	    <title>MySQL setup</title>
	    <para>
		To install support for a MySQL database you will need to download the package
		ser-mysql, which is available from the same download location that you retrieved
		&ser;. This package has scripts to create the required database and establish
		permissions for the accounts needed.  A recent release of MySQL is recommended.
		Earlier versions may have problems with the syntax required to set permissions on
		the database.
	    </para>
	    <para>
		If you do not already have a copy of MySQL installed, download it from your <ulink
		url="http://www.mysql.com"></ulink>
	    </para>
	    <para>
		Once you have MySQL installed and started, execute
	    </para>
	    <screen format="linespecific">
/usr/sbin/ser_mysql.sh
</screen>
	    <para>
		You can verify that the database has been created, and correct permissions assigned
		by using the mysql management tool and these steps:
	    </para>
	    <para>
		<screen format="linespecific">
Mysql&gt; select * from user;
| Host               | User  | Password         | Select_priv | Insert_priv | Update_priv | Delete_priv | Create_priv | Drop_priv | Reload_priv | Shutdown_priv | Process_priv | File_priv | Grant_priv | References_priv | Index_priv | Alter_priv |
| %                  | ser   | 4e633cf914a735a0 | N           | N           | N           | N           | N           | N         | N           | N             | N            | N         | N          | N               | N          | N          |
| localhost          | ser   | 4e633cf914a735a0 | Y           | Y           | Y           | Y           | Y           | Y         | Y           | Y             | Y            | Y         | N          | Y               | Y          | Y          |
| %                  | serro | 7cb73a267cb7bd5f | N           | N           | N           | N           | N           | N         | N           | N             | N            | N         | N          | N               | N          | N          |
| localhost          | serro | 7cb73a267cb7bd5f | Y           | N           | N           | N           | N           | N         | N           | N             | N            | N         | N          | N               | N          | N          |
</screen>
	    </para>
	    <para>
		The above results show that the two user, ser and serro, have been created and
		granted the permissions needed to access the database. Note that in the above
		example the permissions have been modified to deny access to these accounts from any
		system(%) other than local host.
	    </para>
	    <para>
		<screen format="linespecific">
mysql&gt; connect ser;
Connection id:    294
Current database: ser

mysql> show tables;
+-----------------+
| Tables_in_ser   |
+-----------------+
| acc             |
| active_sessions |
| aliases         |
| config          |
| event           |
| grp             |
| location        |
| missed_calls    |
| pending         |
| phonebook       |
| reserved        |
| silo            |
| subscriber      |
| version         |
+-----------------+
14 rows in set (0.00 sec)

mysql&gt; select * from subscriber;
| phplib_id                        | USERNAME | PASSWORD | FIRST_NAME | LAST_NAME | PHONE        | EMAIL_ADDRESS              | DATETIME_CREATED    | DATETIME_MODIFIED   | confirmation                     | flag | SendNotification | Greeting | HA1                              | REALM      | ha1b                             | perms | allow_find | timezone            |
| 4cefa7a4d3c8c2dbf6328520bd873a19 | admin     | heslo | first        | admin    | 557-8469     | [e-mail]      | 2002-12-02 19:20:41 | 2002-12-02 20:29:46 | 80e0f273b2067d40277b49ff842bb9e3 | o    |                  |          | c79a8f8f08596baa84bb02c88884426d | iptel.org | f322c94b8b2fbe557d43ab3ac9e05b3a | admin | 1          | America/Los_Angeles |
		</screen>
	    </para>
	    <para>
		This last query shows that you have one user account defined and it has
		administrator privileges.
	    </para>
	    <para>
		We'll need to add another account to be the administrator for your realm, which we
		will do after the next section.
	    </para>
	</section>
    </chapter>
    <chapter>
	<title>Configuration</title>
	<section>
	    <title>Modify &ser; configuration</title>
	    <para>
		Now that we have a working MySQL database, we need to modify the configuration file
		for ser, located on a RedHat, installed in /etc/ser/ser.cfg.  The following changes
		need to be made:
	    </para>
	    <para>
		To enable support for the new MySQL database we need to load the appropriate module.
		That is accomplished by uncomment this line:
	    </para>
	    <screen format="linespecific">
loadmodule "/usr/lib/ser/modules/mysql.so
</screen>
	    <para>
		Next we need to set &ser; to use the database and write changes instead of just
		caching them in memory. This is done by means of commenting this line:
	    </para>
	    <screen format="linespecific">
modparam ("usrloc", "db_mode",  0)
</screen>
	    <para>
		And uncomment this line:
	    </para>
	    <screen format="linespecific">
modparam ("usrloc", "db_mode", 2)
</screen>
	    <para>
		Note on db_modes:
	    </para>
	    <para>
		<itemizedlist>
		    <listitem>
			<para>
			    Mode 0
			</para>
			<para>
			    Disables writes to the database.  Contact information will not be
			    preserved if the server is restarted.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    Mode 1
			</para>
			<para>
			    Writes all changes to the database immediately. Contact information is
			    saved to the database immediately.  This can slow the response to
			    clients as they connect.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    Mode 2
			</para>
			<para>
			    Periodically writes contact information to the database based in the in
			    memory cache.
			</para>
		    </listitem>
		</itemizedlist>
	    </para>
	    <para>
		To enable digest authentication we additionally need to uncomment the following two lines:
	    </para>
	    <screen format="linespecific">
loadmodule "/usr/lib/ser/modules/auth.so"
loadmodule "/usr/lib/ser/modules/auth_db.so"
</screen>
	    <para>
		We have the option of storing passwords in our database in plain text.  This allows
		for password recovery and makes the initial setup and testing easier.  To enable
		this feature uncomment these lines:
	    </para>
	    <screen format="linespecific">
modparam (<quote>auth_db</quote>, <quote>calculate_ha1</quote>, yes)
modparam (<quote>auth_db</quote>, <quote>password_column</quote>, <quote>password</quote>)
</screen>
	    <para>
		These lines work together. The first tells &ser; to generate a hash based on
		username, password and realm. The second tells &ser; where to look for the plain-text
		password in the database.
	    </para>
	    <para>
		Uncomment these lines and change all instances of iptel.org to your domain
	    </para>
	    <para>
		<screen format="linespecific">
if (!www_authorize("mydomain.com", "subscriber")) {
        www_challenge("mydomain.com", "0");
        break;