admin documentation refurbished -- quite many changes, don't want me to

list all of them

COPYING

@@ -1,3 +1,4 @@
+
 -------------------------------------------------------------------------
 IMPORTANT NOTES
 
@@ -19,7 +20,7 @@ IMPORTANT NOTES
     for a detailed explanation)
 
 3) Note that the GPL bellow is copyrighted by the Free Software Foundation,
-   but the ser software is copyrighted by iptel.org.
+   but the ser software is copyrighted by FhG
 
 
 -------------------------------------------------------------------------
@@ -81,7 +82,7 @@ patent must be licensed for everyone's free use or not licensed at all.
 
   The precise terms and conditions for copying, distribution and
 modification follow.
-
+
 		    GNU GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
@@ -136,7 +137,7 @@ above, provided that you also meet all of these conditions:
     License.  (Exception: if the Program itself is interactive but
     does not normally print such an announcement, your work based on
     the Program is not required to print an announcement.)
-
+
 These requirements apply to the modified work as a whole.  If
 identifiable sections of that work are not derived from the Program,
 and can be reasonably considered independent and separate works in
@@ -194,7 +195,7 @@ access to copy from a designated place, then offering equivalent
 access to copy the source code from the same place counts as
 distribution of the source code, even though third parties are not
 compelled to copy the source along with the object code.
-
+
   4. You may not copy, modify, sublicense, or distribute the Program
 except as expressly provided under this License.  Any attempt
 otherwise to copy, modify, sublicense or distribute the Program is
@@ -251,7 +252,7 @@ impose that choice.
 
 This section is intended to make thoroughly clear what is believed to
 be a consequence of the rest of this License.
-
+
   8. If the distribution and/or use of the Program is restricted in
 certain countries either by patents or by copyrighted interfaces, the
 original copyright holder who places the Program under this License
@@ -304,63 +305,3 @@ PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGES.
 
 		     END OF TERMS AND CONDITIONS
-
-	    How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-    Gnomovision version 69, Copyright (C) year  name of author
-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary.  Here is a sample; alter the names:
-
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
-  <signature of Ty Coon>, 1 April 1989
-  Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs.  If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
-Public License instead of this License.

examples/acc.cfg

@@ -0,0 +1,56 @@
+#
+# $Id$
+#
+# example: accounting calls to nummerical destinations
+#
+
+# ------------------ module loading ----------------------------------
+
+loadmodule "modules/tm/tm.so"
+loadmodule "modules/acc/acc.so"
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/maxfwd/maxfwd.so"
+
+# ----------------- setting module-specific parameters ---------------
+
+# -- acc params --
+# set the reporting log level
+modparam("acc", "log_level", 1)
+# number of flag, which will be used for accounting; if a message is
+# labeled with this flag, its completion status will be reported
+modparam("acc", "acc_flag", 1 )
+
+# -------------------------  request routing logic -------------------
+
+# main routing logic
+
+route{
+
+	/* ********* ROUTINE CHECKS  ********************************** */
+
+	# filter too old messages
+	if (!mf_process_maxfwd_header("10")) {
+		log("LOG: Too many hops\n");
+		sl_send_reply("483","Too Many Hops");
+		break;
+	};
+	if (len_gt( max_len )) {
+		sl_send_reply("513", "Wow -- Message too large");
+		break;
+	};
+
+	# nummerical destinations will be labeled for accounting, others not
+	if (uri=~"sip:\+?[0-9]+@") {
+		setflag(1);
+	};
+
+	# forward the request statefuly now; (we need *stateful* forwarding,
+	# because the stateful mode correlates requests with replies and
+	# drops retranmissions; otherwise, we would have to report on
+	# every single message received)
+	if (!t_relay()) {
+		sl_reply_error(); 
+		break; 
+	};
+
+}

examples/exec.cfg

@@ -5,20 +5,10 @@
 # which rewrites URIs using an exernal utility
 #
 
-# ----------- global configuration parameters ------------------------
-
-debug=4
-fork=no
-log_stderror=yes	# (cmd line: -E)
-check_via=no # (cmd. line: -v)
-dns=no # (cmd. line: -r)
-syn_branch=1
-reply_to_via=0
-
 # ------------------ module loading ----------------------------------
 
-loadmodule "/usr/lib/ser/modules/sl.so"
-loadmodule "/usr/lib/ser/modules/exec.so"
+loadmodule "modules/exec/exec.so"
+loadmodule "modules/sl/sl.so"
 
 # -------------------------  request routing logic -------------------
 
@@ -32,17 +22,11 @@ route{
 		break;
 	};
 
-	# obsoleted
-	#ext_rewriteuri("echo sip:[email protected]; echo >/dev/null");
-	#break;
-
 	# first dump the message to a file using cat command
 	exec_msg("printenv SRCIP > /tmp/exectest.txt; cat >> /tmp/exectest.txt");
 	# and then rewrite URI using external utility
 	# note that the last echo command trashes input parameter
 	if (exec_uri("echo sip:[email protected];echo sip:[email protected];echo>/dev/null")) {
-
-	#if (exec_uri("/tmp/sh.sh")) {
 		sl_send_reply("300", "Redirect");
 	} else {
 		sl_reply_error();

examples/onr.cfg

@@ -2,33 +2,25 @@
 # $Id$
 #
 # example script showing both types of forking;
-# incoming message is foked in parallel to
+# incoming message is forked in parallel to
 # 'nobody' and 'parallel', if no positive reply
 # appears with final_response timer, nonsense
 # is retried (serial forking); than, destination
 # 'foo' is given last chance
 
-# ----------- global configuration parameters ------------------------
-
-debug=3
-fork=no
-log_stderror=yes	# (cmd line: -E)
-check_via=no # (cmd. line: -v)
-dns=no # (cmd. line: -r)
-syn_branch=1
-reply_to_via=0
-
-
 # ------------------ module loading ----------------------------------
 
-loadmodule "/usr/lib/ser/modules/sl.so"
-loadmodule "/usr/lib/ser/modules/tm.so"
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/tm/tm.so"
 
 # ----------------- setting module-specific parameters ---------------
 
 # -- tm params --
+# set time for which ser will be waiting for a final response;
+# fr_inv_timer sets value for INVITE transactions, fr_timer
+# for all others
+modparam("tm", "fr_inv_timer", 15 )
 modparam("tm", "fr_timer", 10 )
-modparam("tm", "fr_inv_timer", 5 )
 
 # -------------------------  request routing logic -------------------
 
@@ -41,27 +33,29 @@ route{
 		sl_send_reply("200", "ok");
 		break;
 	};
-	# print a message if a call was missed
+	# try these two destinations first in parallel; the second
+	# destination is targeted to sink port -- that will make ser
+	# wait until timer hits
 	seturi("sip:[email protected]");
-	/* parallel branch to sink port -- that will make it
-	   wait until timer hits
-	*/
 	append_branch("sip:[email protected]:9");
+	# if we do not get a positive reply, continue at reply_route[1]
 	t_on_negative("1");
-	# start parallel forking to nobody and wer.xmla	
-	log(1,"about to relay\n");
+	# forward the request to all destinations in destination set now 
 	t_relay();
 }
 
 reply_route[1] {
-	rewriteuri("sip:[email protected]");
-	append_branch();
+	# forwarding failed -- try again at another destination 
+	append_branch("sip:[email protected]");
 	log(1,"first redirection\n");
+	# if this alternative destination fails too, proceed to reply_route[2] 
 	t_on_negative("2");
 }
 
 reply_route[2] {
-	rewriteuri("sip:[email protected]");
+	# try out the last resort destination
+	append_branch("sip:[email protected]");
 	log(1, "second redirection\n");
-	append_branch();
+	# we no more call t_on_negative here; if this destination
+	# fails too, transaction will complete
 }

examples/pstn.cfg

@@ -0,0 +1,141 @@
+#
+# $Id$
+#
+# example: ser configured as PSTN gateway guard; PSTN gateway is located
+# at 192.168.0.10
+#
+
+# ------------------ module loading ----------------------------------
+
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/tm/tm.so"
+loadmodule "modules/acc/acc.so"
+loadmodule "modules/rr/rr.so"
+loadmodule "modules/maxfwd/maxfwd.so"
+loadmodule "modules/mysql/mysql.so"
+loadmodule "modules/auth/auth.so"
+
+# ----------------- setting module-specific parameters ---------------
+
+modparam("auth", "db_url","sql://ser:heslo@localhost/ser")
+modparam("auth", "calculate_ha1", yes)
+modparam("auth", "password_column", "password")
+
+# -- acc params --
+modparam("acc", "log_level", 1)
+# that is the flag for which we will account -- don't forget to
+# set the same one :-)
+modparam("acc", "acc_flag", 1 )
+
+# -------------------------  request routing logic -------------------
+
+# main routing logic
+
+route{
+
+	/* ********* ROUTINE CHECKS  ********************************** */
+
+	# filter too old messages
+	if (!mf_process_maxfwd_header("10")) {
+		log("LOG: Too many hops\n");
+		sl_send_reply("483","Too Many Hops");
+		break;
+	};
+	if (len_gt( max_len )) {
+		sl_send_reply("513", "Wow -- Message too large");
+		break;
+	};
+
+	/* ********* RR ********************************** */
+
+	/* Do strict routing if route headers present */
+	rewriteFromRoute();
+	/* record-route INVITEs -- all subsequent requests must visit us */
+	if (method=="INVITE") {
+		addRecordRoute();
+	};
+
+	# now check if it really is a PSTN destination which should be handled
+	# by our gateway; if not, and the request is an invitation, drop it --
+	# we cannot terminate it in PSTN; relay non-INVITE requests -- it may
+	# be for example BYEs sent by gateway to call originator
+	if (!uri=~"sip:\+?[0-9]+@.*") {
+		if (method=="INVITE") {
+			sl_send_reply("403", "Call cannot be served here");
+		} else {
+			forward(uri:host, uri:port);
+		};
+		break;
+	}; 
+
+	# account completed transactions via syslog
+	setflag(1);
+
+	# free call destinations ... no authentication needed
+	if ( is_user_in("Request-URI", "free-pstn")  /* free destinations */
+			|  uri=~"sip:[79][0-9][0-9][0-9]@.*"  /* local PBX */
+			| uri=~"sip:98[0-9][0-9][0-9][0-9]") {
+		log("free call");
+	} else if (src_ip==192.168.0.10) {
+		# our gateway doesn't support digest authentication;
+		# verify that a request is coming from it by source
+		# address
+		log("gateway-originated request");
+	} else {
+		# in all other cases, we need to check the request against
+		# access control lists; first of all, verify request
+		# originator's identity
+
+		if (!proxy_authorize(	"gateway" /* realm */,
+				"subscriber" /* table name */))  {
+			proxy_challenge( "gateway" /* realm */, "0" /* no qop */ );
+			break;
+		};
+
+		# authorize only for INVITEs -- RR/Contact may result in weird
+		# things showing up in d-uri that would break our logic; our
+		# major concern is INVITE which causes PSTN costs 
+
+		if (method=="INVITE") {
+
+			# does the authenticated user have a permission for local
+			# calls (destinations beginning with a single zero)? 
+			# (i.e., is he in the "local" group?)
+			if (uri=~"sip:0[1-9][0-9]+@.*") {
+				if (!is_in_group("local")) {
+					sl_send_reply("403", "No permission for local calls"); 
+					break;
+				};
+			# the same for long-distance (destinations begin with two zeros")
+			} else if (uri=~"sip:00[1-9][0-9]+@.*") {
+				if (!is_in_group("ld")) {
+					sl_send_reply("403", " no permission for LD ");
+					break;
+				};
+			# the same for international calls (three zeros)
+			} else if (uri=~"sip:000[1-9][0-9]+@.*") {
+				if (!is_in_group("int")) {
+					sl_send_reply("403", "International permissions needed");
+					break;
+				};
+			# everything else (e.g., interplanetary calls) is denied
+			} else {
+				sl_send_reply("403", "Forbidden");
+				break;
+			};
+
+		}; # INVITE to authorized PSTN
+
+	}; # authorized PSTN
+
+	# if you have passed through all the checks, let your call go to GW!
+
+	rewritehostport("192.168.0.10:5060");
+
+	# forward the request now
+	if (!t_relay()) {
+		sl_reply_error(); 
+		break; 
+	};
+
+}

examples/redirect.cfg

@@ -4,19 +4,9 @@
 # this example shows use of ser as stateless redirect server
 #
 
-# ----------- global configuration parameters ------------------------
-
-debug=3
-fork=no
-log_stderror=yes	# (cmd line: -E)
-check_via=no # (cmd. line: -v)
-dns=no # (cmd. line: -r)
-syn_branch=1
-reply_to_via=0
-
 # ------------------ module loading ----------------------------------
 
-loadmodule "/usr/lib/ser/modules/sl.so"
+loadmodule "modules/sl/sl.so"
 
 
 # -------------------------  request routing logic -------------------
@@ -30,8 +20,11 @@ route{
 		sl_send_reply("200", "ok");
 		break;
 	};
-	append_branch("sip:[email protected]:9");
+	# rewrite current URI, which is always part of destination ser
+	rewriteuri("sip:[email protected]:9");
+	# append one more URI to the destination ser
 	append_branch("sip:[email protected]:9");
+	# redirect now
 	sl_send_reply("300", "Redirect");
 }
 

examples/replicate.cfg

@@ -0,0 +1,72 @@
+#
+# $Id$
+#
+# demo script showing how to set-up usrloc replication
+#
+
+# ----------- global configuration parameters ------------------------
+
+debug=3          # debug level (cmd line: -dddddddddd)
+fork=no
+log_stderror=yes # (cmd line: -E)
+
+# ------------------ module loading ----------------------------------
+
+loadmodule "modules/mysql/mysql.so"
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/tm/tm.so"
+loadmodule "modules/maxfwd/maxfwd.so"
+loadmodule "modules/usrloc/usrloc.so"
+loadmodule "modules/registrar/registrar.so"
+loadmodule "modules/auth/auth.so"
+
+# ----------------- setting module-specific parameters ---------------
+
+# digest generation secret; use the same in backup server;
+# also, make sure that the backup server has sync'ed time
+modparam("auth", "secret", "alsdkhglaksdhfkloiwr")
+
+# -------------------------  request routing logic -------------------
+
+# main routing logic
+
+route{
+
+	# initial sanity checks -- messages with
+	# max_forwars==0, or excessively long requests
+	if (!mf_process_maxfwd_header("10")) {
+		sl_send_reply("483","Too Many Hops");
+		break;
+	};
+	if (len_gt( max_len )) {
+		sl_send_reply("513", "Message too big");
+		break;
+	};
+
+	# if the request is for other domain use UsrLoc
+	# (in case, it does not work, use the following command
+	# with proper names and addresses in it)
+	if (uri==myself) {
+
+		if (method=="REGISTER") {
+
+			# verify credentials
+			if (!www_authorize("foo.bar", "subscriber")) {
+				www_challenge("foo.bar", "0");
+				break;
+			};
+
+			# if ok, update contacts and ...
+			save("location");
+			# ... if this REGISTER is not a replica from our
+			# peer server, replicate to the peer server
+			if (!src_ip==backup.foo.bar) {
+				t_replicate("backup.foo.bar", "5060");
+			};
+			break;
+		};
+		# do whatever else appropriate for your domain
+		log("non-REGISTER\n");
+	};
+}
+

examples/uas.cfg

@@ -8,25 +8,10 @@
 # (e.g., it retransmits replies on request
 # retransmissions)
 
-# ----------- global configuration parameters ------------------------
-
-debug=3
-fork=no
-log_stderror=yes	# (cmd line: -E)
-check_via=yes     # (cmd. line: -v)
-dns=0           # (cmd. line: -r)
-rev_dns=0      # (cmd. line: -R)
-reply_to_via=no
-
-
 # ------------------ module loading ----------------------------------
 
-loadmodule "/usr/lib/ser/modules/sl.so"
-loadmodule "/usr/lib/ser/modules/tm.so"
-
-# ----------------- setting module-specific parameters ---------------
-
-# -- usrloc params --
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/tm/tm.so"
 
 
 # -------------------------  request routing logic -------------------
@@ -38,34 +23,27 @@ route{
 	if (method=="REGISTER") {
 		log("REGISTER");
 		sl_send_reply("200", "ok");
-		#t_replicate("localhost", "9");
 		break;
 	};
-	# print a message if a call was missed
 
-	if ( t_newtran())
-    {
-		if (method=="ACK") {
-			log("oops--ACK to a non-existent transaction");
-			drop;
-		};
-		log("New Transaction Arrived\n");
-        # do what you want to do as a sever
-		if (uri=~"a@") {
-			if (!t_reply("409", "Bizzar Error")) {
-				sl_reply_error();
-			};
-		} else if (uri=~"b@") {
-			if (!t_reply("979", "You did not expect this did you")) {
-				sl_reply_error();
-			};
-		} else {
-			if (!t_reply("699", "I don't want to chat with you")) {
-				sl_reply_error();
-			};
-		} ;
-    } else {
+	# create transaction state; abort if error occured
+	if ( !t_newtran()) {
 		sl_reply_error();
+		break;
 	};
+
+	# the following log will be only printed on receipt of 
+	# a new message; retranmissions are absorbed by t_newtran
+	log(1, "New Transaction Arrived\n");
+       	# do what you want to do as a sever...
+	if (uri=~"a@") {
+		if (!t_reply("409", "Bizzar Error")) {
+			sl_reply_error();
+		};
+	} else {
+		if (!t_reply("699", "I don't want to chat with you")) {
+			sl_reply_error();
+		};
+    	};
 }