[SR-Dev] git:master: doc: config migration

[Andrei Pelinescu-Onciul]

Module: sip-router
Branch: master
Commit: 9227fc8228064b789eaf66e939b8009333be1be0
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=9227fc8228064b789eaf66e939b8009333be1be0

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date:   Wed May  6 17:57:25 2009 +0200

doc: config migration

Added a config migration guide for ser 2.1 to sip-router.
The kamailio part is empty for now.

---

 NEWS                     |    3 +
 doc/config_migration.txt |  115 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 0 deletions(-)

diff --git a/NEWS b/NEWS
index 460d70c..b831a2f 100644
--- a/NEWS
+++ b/NEWS
@@ -42,6 +42,9 @@ core:
       strempty(expr) - returns true if expr evaluates to the empty
                        string (equivalent to expr=="").
     e.g.: if (defined $v && !strempty($v)) $len=strlen($v);
+  - msg:len max_len comparison obsoleted and removed (it did not make any
+    sense, msg:len > max_len was always false, use something like 
+    4096 or 16384 in its place).
   - module search path support: loadpath takes now a list of directories
     separated by ':'. The list is searched in-order. For each directory d
     $d/${module_name}.so and $d/${module_name}/${module_name}.so are tried.
diff --git a/doc/config_migration.txt b/doc/config_migration.txt
new file mode 100644
index 0000000..d55510c
--- /dev/null
+++ b/doc/config_migration.txt
@@ -0,0 +1,115 @@
+# $Id$
+#
+# History:
+# --------
+# 2009-05-06  created by andrei
+
+=============================================================
+= Config migration guide from ser or kamailio to sip-router =
+=============================================================
+
+
+ser 2.1 config migration
+========================
+
+1. Avps, selects and strings in if or other expressions
+
+The most important change is the different way in which avp and select are
+evaluated in boolean expressions (if ()).
+In ser "if ($v){}" or "if (@select){}" were true if the avp or select were
+"defined" and if their value was non-empty (!= "").
+In sip-router this changed: the ifs will be true if the avp or select are
+non-empty and they evaluate to a non-zero number. The catch is that a
+non-numeric string evaluates to 0 (e.g. "abc" evaluates to 0, "123" evaluates
+to 123, "" to 0, "0" to 0).
+Something like "if($v)" should be used only if $v is supposed to have a numeric
+value. "if (@select)" should not be used in general (it's probably not what you
+want).
+
+The equivalent sip-router checks are:
+
+instead of if ($v) use if ($v != "")
+instead of if (!$v) use if ($v == "") or if (strempty($v)).
+instead of if (@select) use if (@select != "")
+instead of if (!@select) use if (@select == "") or if (strempty(@select)).
+
+If the test is for value existence, then if ($v) can be replaced with
+ if (defined $v).
+
+E.g.:
+replace
+	if (! $f.did)
+with
+	if (strempty($f.did))
+
+replace
+	if (method=="INVITE" && !@to.tag)
+with
+	if (method=="INVITE" && strempty(@to.tag))
+
+replace
+	if ($f.did && ! $t.did)
+with
+	if ($f.did != ""  && $t.did == "")
+
+replace
+	if (@to.tag)
+with
+	if (@to.tag != "")
+
+
+2. Module path
+
+While in ser there was only a single directory holding the modules, now there
+are 3: modules (for common modules), modules_s (for ser modules) and modules_k
+(for kamailio modules).
+The easiest way to migrate a ser config is to add:
+
+	loadpath "/usr/lib/ser/modules:/usr/lib/ser/modules_s"
+
+at the beginning (before any loadmodule command).
+This will set the module search path to first look into the common modules and
+if not found in the ser modules.
+
+Make sure that all the loadmodule commands do not include the path to the
+module or the .so extension (or else they won't make use of the loadpath).
+E.g.:
+replace
+	loadmodule "/usr/lib/ser/modules/tm.so"
+with
+	loadmodule "tm"
+
+
+3. Module names
+
+Some of the modules changed their name (usually after being merged with the
+kamailio ones).
+The most common changes are mysql -> db_mysql and postgres -> db_postgres.
+
+E.g.:
+replace
+	loadmodule "mysql"
+with
+	loadmodule "db_mysql"
+
+
+4. msg:len and max_len
+
+max_len was removed. All the comparisons of msg:len with max_len must be
+changed to use a number (e.g. 4096 or 16384) instead of max_len.
+Comparing with max_len didn't make sense anyway since max_len was the size of
+the internal receive buffer on UDP. You could never exceed it, unless you were
+using TCP configured in a non-standard way.
+
+E.g.:
+replace
+	if (msg:len >= max_len)
+with
+	if (msg:len >= 4096)
+
+
+
+kamailio config migration
+=========================
+
+[TODO: probably most of the things from the ser section apply too]