[SR-Users] [newbie] questions

[Alex Balashov]

All right, fair enough.  I realise that this list has left you with 
little useful takeaways thus far, and, upon further reflection, that 
does seem a little unfair, given the amount of effort and thought that 
went into your post.

In due recognition of that, let me _try_ to tackle some of the more 
"low-hanging fruit" here, bearing in mind everything I've had to say 
about the practicality of the scope of your questions.

See below:

On 01/30/2012 12:00 PM, Me wrote:

> External calls (going out, i.e. outbound) are routed externally to our
> registrar, using a single separate voip account, via eth1<->eth0 or
> tun0<->eth0.
>
> As I am now looking to replace our proxy, I looked at Kamailio, but
> was soon completely overwhelmed by it (no offence intended, it was
> just too much to take at first). I would appreciate if any of you
> could give me a hand, or at least point me in the right direction,
> with the following issues:

It is understandable that you were overwhelmed.  It is a relatively 
low-level, idiosyncratic software product, with its own programmatic 
route script language for configuration, and many associated, 
idiosyncratic APIs and conventions.  The overall flow of the route 
script mimics aspects of the SIP state machine, and is tied to SIP 
message processing.  You can think of Kamailio as something like an 
SDK on top of a proxy core.  So, for starters, a fairly robust 
understanding of SIP protocol mechanics is required.

As much as efforts have been made to make it more user-friendly, it is 
something that really has little out-of-the-box functionality suitable 
for all but the most generic of implementation scenarios.

Roughly speaking, the stock configuration file is, to some extent by 
convention and to some extent by necessity, organised into three parts:

1. Global configuration values.
2. Module loading & module-specific parameters.
3. Routes.

Routes are like functions or subroutines. They are activated when a 
SIP message is processed.  The canonical route is a request route, so 
it is fired when a SIP request is received (initial or 
sequential/in-dialog).  There are other types of routes for SIP 
message types other than requests, like replies, and also for certain 
conditions that inhere in Kamailio's design, such as failure routes 
(for >= 3xx failure replies), event routes (functionality-specific 
callbacks), etc.

At the bare minimum, to do any routing, you need the single mandatory 
request route, which has no name:

    route {
       ...
    }

All SIP requests pass through this main request route.

You can delegate functionality into other routes which can be called 
from the main request route, e.g.

    route {
       ...

       route(X);
    }

    route[X] {
       ...
    }

All other types of routes are pretty much optional, and not essential 
to a "quick start" or getting going.

The root of all documentation is here:

    http://www.kamailio.org/dokuwiki/doku.php

There are several components to the documentation tree:

- Core cookbook: core functionality, including route types, global 
configuration values, variables, primitives, operators, etc.

- Modules: http://www.kamailio.org/docs/modules/3.2.x/

Modules are optionally loadable and provide all non-core 
functionality.  Note that some components of Kamailio are technically 
modular, but in practice, are essential to almost any commonplace use 
of it, so they can be regarded as core.  These include: rr, xlog, tm, 
pv, sl.  Your best guide for this aspect of things is the stock config 
file.

- Pseudovariables & selects: these are variables which are populated 
by Kamailio automatically to expose SIP message attributes.  Most of 
these are immutable (read-only), while a few, such as the request URI 
($ru), are mutable, so you can actually assign values to them.

- Transformations: these are mostly string-related operations that can 
be performed on variables of all kinds (user variables and 
pseudovariables), e.g.

    $(ru{s.len}) -- get the length of the request URI string.

...

Your best bet is to take the stock configuration file and tweak it to 
your liking.  I encourage you to conserve the sanity checking and 
request handling boilerplate you see at the top of the main request 
route, as that is stuff you are going to want in virtually any 
imaginable scenario.  In particular, don't make the common rookie 
mistake of deleting the

    if(has_totag()) {
       ...

       if(loose_route()) {
          ...
       } else {
          ...
       }
    }

section.  Sequential (in-dialog) requests with a preset route set 
(i.e. Route header) must be routed differently than initial requests; 
  routing then manually is poor form.

> I presume I could configure Kamailio to listen on more than one
> interface and act as a proxy. How do I do that, so that it listens on
> all 3 interfaces and proxies requests in the following way:

You just bind it to all three interfaces with multiple 'listen' 
parameters, e.g.

    listen=udp:xxx.xxx.xxx.xxx:5060
    listen=udp:yyy.yyy.yyy.yyy:5060
    listen=udp:zzz.zzz.zzz.zzz:5060

If you want to have Kamailio take its best shot at guessing which 
interface to route out of, set

    mhomed=1.

If you want to guide this process manually, just modify the $fs 
pseudovariable prior to relaying a message, or use 
force_send_socket(), e.g.

    $fs = "udp:xxx.xxx.xxx.xxx:5060";

    # This will go out of the xxx.xxx.xxx.xxx:5060 socket.

    if(!t_relay()) {
       sl_reply_error();
       exit;
    }

> - calls made to <userX>@ourdomain.net to be routed internally via eth1
> (internal net) or tun0 (private vpn);
> - calls made to anybody else to be routed externally via eth0 (public)
> using the separate "public" sip account with our external registrar;
> - calls made to the public sip account (from outside - the "public")
> need to be routed to a "nominated" internall account (say
> <user0>@ourdomain.net);
> - all other (internal) calls need to be routed depending on which
> interface this account has been registered/logged in - either the
> internal net (eth1) or the private vpn (tun0 - the smartphones).

You can get the destination domain of a request by accessing the 
request URI attributes, e.g.

    $ru - the whole request URI.
    $rU - the user part of the request URI.
    $rd - the domain part of the request URI.
    $rp - the port part of the request URI.

e.g.

    if($rd == "ourdomain.net")
       route(INTERNAL_ROUTE);

Getting Kamailio to act as a UAC to register with an external 
registrar is a little complex, since Kamailio is a proxy, and proxies 
are not UACs, so they are not capable, at least, as a formal matter, 
of initiating requests or registering to anything.  However, Kamailio 
has this functionality hacked in, in the form of its 'uac' module:

    http://www.kamailio.org/docs/modules/3.2.x/modules_k/uac.html

In particular, there is a 'uacreg' table you can use to get it to 
initiate and maintain registrations with an external SIP provider. 
But this is a rather involved topic.

> Obviously, calls need to be received (and routed properly) from all 3
> interfaces.
>
> Is all of this possible with Kamailio?

In principle, yes.

There are complications you will encounter along the way, particularly 
if you want Kamailio to stay in the signaling path of sequential 
(in-dialog) requests, which you would do using by inserting the 
Record-Route header using the 'rr' module's record_route() function. 
Multiple interfaces require careful handling.

If you don't care about the proxy seeing BYEs or reinvites, your life 
will be much simpler in a multihomed scenario.

> I looked at other alternatives, but I got very confused there as well
> - I couldn't figure out what exactly is the difference between, say,
> OpenSER, Kamailio, OpenSIPS and SIP-Router even? What is the best
> software to use in order to achieve the above setup?

This is a complex and somewhat politically charged topic, but in 
general, the lineage is something like this:

    OpenSER
      |
      |
      |
      |
   Kamailio
      |   \
      |    \
      |     \
      |   OpenSIPS
      |
  Kamailio+sip-router

SER is the common ancestor to this entire technology stack.  OpenSER 
is the open-source variant that appeared in 2005.  In 2008, its name 
was changed to Kamailio due to trademark-related issues, and at about 
the same time, OpenSIPS was forked from it.  OpenSIPS is considered a 
rogue fork around here, and by this point has diverged significantly. 
  I don't know that this list is the best place to get an opinion on 
the possible benefits of using OpenSIPS, but I can tell you that most 
of the people involved in managing the hitherto joint OpenSER project 
stayed with the Kamailio effort and, in my opinion, it has a lot more 
industry power and ecosystem behind it.

The sip-router project is an initiative that resulted in the 
recombination of Kamailio with the original SER, to leverage the best 
of both worlds.  You can think of sip-router as a "kernel" and 
Kamailio as a particular packaging/distribution of it.  For all 
practical purposes, they are the same thing, as far as you should be 
concerned.  In other words, Kamailio has sip-router underneath.

-- Alex

-- 
Alex Balashov - Principal
Evariste Systems LLC
260 Peachtree Street NW
Suite 2200
Atlanta, GA 30303
Tel: +1-678-954-0670
Fax: +1-404-961-1892
Web: http://www.evaristesys.com/, http://www.alexbalashov.com/