Context Navigation

Kam3cfg

This page describes kam3cfg which is kamailio config generator. This project was founded on Cesnet by its VoIP team. We are hosting this project to improve development and to embed it into OpenPhonyx.

Abstract

Writing config for kamailio is not simple procedure. It takes long time to achieve needed results. There are some common configs which can be found and used, mostly from examples directory. But this does not fit all our needs. Sometime example is too complex and is hard to change only for specific scenario. Sometime it is too simple and does not fit all features. We wanted to create some tool, which will generate needed config file based on input parameters. So anybody can change parameters and features and generate its own config. Generated config should be editable and some parameters can be changed after generation. Many users awaiting similar tool, and many organizations do not use kamailio because of big config complexity. So we made this tool.

Licence

Entire project is available under GPLv3 license.

Features

We achieved most of needed features. Even if there is still too much work (especialy in global template file), generated results are good enaugh. For debug purposes, we created macro xlog, which will log all messages with same prefix and suffix. It is good thing because all xlog lines will changes automaticaly by runing kam3cfg again with other paeameters. Anybody can change suffix and prefix to fit his needs. In normal situation, this would be very complex, because there can be many xlog lines in script. Even more, some macros are changing automaticaly based on used modules. For example, there is another way how to find if destination uri is local (either using domains in db or directly into script). Kam3cfg solves this kind of states. Kam3cfg can generate wide range of kamailio configs:

Scalable into different kind of environments. From smallest SIP proxy up to big one with external databases.
Secure ss much as possible, it mean sanitize, ratelimit, header checks etc.
Modular
Unlimited
Readable by human even if config is generated by our tool
LDAP to be able to directly ask LDAP server for values (names, extensions, passwords, ..)
ENUM to ask ENUM for internal or external routing. Trees are hightly configurable.
AUTH is configured directly from kam3cfg (usernames and passwords in script) or external (db). In external auth, kam3cfg does not take care about data.
Location table should be stored either in RAM or in DB
NAT setting is configurable. Some users need it, while other hate. But for real production, it is needed.
RTP proxy - we are able to proxy all traffic through kamailio if it will be needed (similary to NAT, but for selected IPs)

Download

Use OpenPhonyx svn repository to get kam3cfg. It is here: svn://open.phonyx.eu/src/kam3cfg/ . Until stable release, this is cleanest way how to get latest code. But there is possibility to download (maybe outdated) package: http://mirror.opf.slu.cz/kam3cfg.tgz

Testing

Yes, we need to test our script. You are welcome! Download source code and use it by yourself! If you find some bug, please use OpenPhonyx contribute rules.

Usage

Extract kam3cfg into some directory (or download from svn) and run directly ./kam3cfg.php . It will gives you brief help. Kam3cfg has many parameters and explaining all of them is beyond scope of this document. Some parameters can have multiple values. Unfortunately, Console_Getopt module cannot read same multiple parameters, so we use delimiter '^{' to split it to multiple values. Even more, all multiple values can be read from file if it starts with '@'. If you want to see all parameters, run}

$ ./kam3cfg.php --help
$ ./kam3cfg.php --longhelp

or see below. To see specific option help, run

$ ./kam3cfg.php --help-option optionname
$ ./kam3cfg.php --help with-ldap

If you use enough parameters (at least local-domains), kamailio.cfg will be outputed into stdout.

Examples

Yes, it is hard to understand without examples. Here it is.

Simple SBC forcing as RTP proxy

./kam3cfg.php \
  --local-ips 192.168.1.0/24^192.168.3.0/24 \
  --local-domains local.edu^sip.local.edu \
  --local-prefixes '123/556/sip:gw:5060' \
  --force-rtp \
  --listen \
    udp:192.168.1.1:5060^tls:192.168.1.1:5061 \
 > /etc/kamailio/kamailio.cfg

Simple SBC with NAT traversal

./kam3cfg.php \
  --local-domains @domains.txt \
  --local-prefixes @prefixes.txt \
  --with-nat \
  --listen udp:192.168.1.1:5060 \
 > /etc/kamailio/kamailio.cfg

Simple SBC with ENUM routing

./kam3cfg.php \
  --local-domains local.edu^sip.local.edu \
  --with-enum \
  --enum-suffixes e164.localnet.edu^e164.arpa. \
  --listen udp:192.168.1.1:5060 \
 > /etc/kamailio/kamailio.cfg

LDAP, multidomain, TLS, ENUM and NAT support

This is more complex scenario where we will use external databases. We will use local domains 'local.edu' and 'sip.local.edu'. We will enable standard NAT suport for RFC addresses. Next, we will utilize LDAP server as authentication backend. Destination uri is checked against LDAP server, so extension has to exist in LDAP to be accessible (achieved by ldapaliases-uri filter). This is very usefull setup for multiPBX environment, where central config is in LDAP server. Entire user and extension management is in LDAP server. Even more, we can map LDAP attributes to avps (see ldap-attrmap). So kamailio can get almost any variable and use it. For example, sets identification string from LDAP based on phone number. To use LDAP, you have to create /etc/kamailio/ldap.ini and enter your local LDAP server parameters there. Kam3cfg will not do this for you. See ldap module manual for more informations.

./kam3cfg.php \
  --local-domains local.edu^sip.local.edu \
  --with-nat \
  --with-enum \
  --with-ldap \
  --with-ldapaliases \
  --ldapauth-uri 'ldap://ldap/o=su?cn,radiuspassword?sub?(|(cn=$au)(tollfreephonenumber=$fU))' \
  --ldapaliases-uri 'ldap://ldap/o=su?cn,tollfreephonenumber?sub?(tollfreephonenumber=$fU)' \
  --ldap-attrmap 'cn=s:username^radiuspassword=s:password^displayname=s:displayname' \
  --enum-suffixes e164.localnet.edu^e164.arpa^nrenum.net^e164.org \
  --listen udp:192.168.1.1:5060^tls:192.168.1.1:5061 \
  --with-tls \
  --tls-key '/etc/kamailio/key.pem' \
  --tls-certificate '/etc/kamailio/cert.pem' \
 > /etc/kamailio/kamailio.cfg

LongHelp?

Here you can find entire longhelp too:

Usage: 
Parameter: parameter
  Multiple: multiple
  Default: 'default'
  Description: help

Parameter: --help
  Multiple: 
  Default: ''
  Description: Help

Parameter: -h
  Multiple: 
  Default: ''
  Description: Help

Parameter: --longhelp
  Multiple: 
  Default: ''
  Description: Longer help

Parameter: --help-option option
  Multiple: 
  Default: ''
  Description: Help to specific option

Parameter: --with-debug
  Multiple: 0
  Default: '1'
  Description: Enable kamailio debuging via xlog (level 0,1,2,3)

Parameter: --xlog-suffix
  Multiple: 0
  Default: ' [level=%s, from $si:$sp ($pr), rm=$rm, au=$au, fU=$fU,tU=$tU]'
  Description: xlog suffix to put on each log line

Parameter: --xlog-prefix
  Multiple: 0
  Default: 'none'
  Description: xlog prefix to put on each log line

Parameter: --modules-dir
  Multiple: 0
  Default: '/usr/lib/kamailio/modules_k/:/usr/lib/kamailio/modules/'
  Description: Set modules directory

Parameter: --local-domains
  Multiple: 1
  Default: 'none'
  Description: Local SIP domains

Parameter: --with-dbdomains
  Multiple: 0
  Default: 'none'
  Description: Local SIP domain in DB module

Parameter: --local-ips
  Multiple: 1
  Default: 'none'
  Description: Local IP addresses

Parameter: --force-rtp
  Multiple: 0
  Default: 'none'
  Description: Force all RTPs from local IPs through our proxy (like NAT)

Parameter: --listen
  Multiple: 1
  Default: 'none'
  Description: Listen on this interfaces

Parameter: --enum-suffixes
  Multiple: 1
  Default: 'e164.arpa.'
  Description: Enum suffixes

Parameter: --with-enum
  Multiple: 0
  Default: 'none'
  Description: Enable ENUM support

Parameter: --flags
  Multiple: 1
  Default: 'array (   'acc' => 1,   'missed' => 2,   'transfailed' => 3,   'nated' => 5,   'localdfrom' => 6,   'localauth' => 7,   'localdto' => 8,   'topstn' => 9,   'remotetrusted' => 10,   'localpfrom' => 11,   'localpto' => 12, )'
  Description: 

Parameter: --bflags
  Multiple: 1
  Default: 'array (   'sipping' => 7,   'nat' => 6, )'
  Description: 

Parameter: --with-ratelimit
  Multiple: 0
  Default: 'none'
  Description: Enable ratelimit module (choose small,medium or large site)

Parameter: --with-nat
  Multiple: 0
  Default: 'none'
  Description: Enable NAT support

Parameter: --with-presence
  Multiple: 0
  Default: 'none'
  Description: Enable Presence support

Parameter: --presence-server
  Multiple: 0
  Default: 'none'
  Description: Presence server uri (sip:ip:port)

Parameter: --with-acc
  Multiple: 0
  Default: 'none'
  Description: Enable Accounting support

Parameter: --with-accdb
  Multiple: 0
  Default: 'none'
  Description: Enable Accounting to DB support

Parameter: --with-usrlocdb
  Multiple: 0
  Default: 'none'
  Description: Enable Location to DB support

Parameter: --with-usrloc
  Multiple: 0
  Default: 'none'
  Description: Enable Location to RAM support

Parameter: --acc-extra
  Multiple: 0
  Default: 'src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd'
  Description: Acc extra string

Parameter: --local-prefixes
  Multiple: 1
  Default: 'none'
  Description: Local prefixes and  gateways (prefix[[/prepend]/[gw])

Parameter: --global-prefix
  Multiple: 0
  Default: 'none'
  Description: Global prefix to prepend every number (eg. to get international format)

Parameter: --with-authdb
  Multiple: 0
  Default: 'none'
  Description: Enable auth from DB

Parameter: --with-authscript
  Multiple: 0
  Default: 'none'
  Description: Enable auth from script

Parameter: --subscribers
  Multiple: 1
  Default: 'none'
  Description: Local auth data for subscribers hard-drived to config (format user@domain/secret[/authid]

Parameter: --with-ldap
  Multiple: 0
  Default: 'none'
  Description: Enable LDAP support

Parameter: --with-ldapauth
  Multiple: 0
  Default: 'none'
  Description: Enable auth from LDAP

Parameter: --with-ldapavp
  Multiple: 0
  Default: 'none'
  Description: Enable avp load from LDAP

Parameter: --with-ldapaliases
  Multiple: 0
  Default: 'none'
  Description: Enable LDAP to lookup for aliases

Parameter: --ldapauth-uri
  Multiple: 0
  Default: 'ldap://kamldap/dc=com?uid,radiuspassword?sub?(&(uid=$au)(telephonenumber=$fU))'
  Description: LDAP uri for authentication.

Parameter: --ldapaliases-uri
  Multiple: 0
  Default: 'ldap://kamldap/dc=com?uid,telephonenumber?sub?(telephonenumber=$fU)'
  Description: LDAP uri for aliases

Parameter: --ldap-attrmap
  Multiple: 1
  Default: 'uid=s:username,radiusPassword=s:password'
  Description: LDAP user attributes map (ldapattr=avp).

Parameter: --with-mysql
  Multiple: 0
  Default: 'none'
  Description: Enable mysql support

Parameter: --with-pgsql
  Multiple: 0
  Default: 'none'
  Description: Enable postgresql support

Parameter: --with-bdb
  Multiple: 0
  Default: 'none'
  Description: Enable Berkeley DB support

Parameter: --with-tls
  Multiple: 0
  Default: 'none'
  Description: Enable TLS support

Parameter: --tls-certificate
  Multiple: 0
  Default: 'none'
  Description: TLS certificate file

Parameter: --tls-key
  Multiple: 0
  Default: 'none'
  Description: TLS key file

Parameter: --tls-calist
  Multiple: 0
  Default: 'none'
  Description: TLS CA list file

Parameter: --db-uri
  Multiple: 0
  Default: 'mysql://openser:openserrw@localhost/openser'
  Description: SQL DB uri for connect

Note: Multiple options are expected as --multiple-value=aaa\^bbb\^ccc
Note: Multiple options can be redirected from file --multiple-value=@aaa , then you can use one ption per line.

Download in other formats:

Plain Text