Chan_SCCP-[4.0.1_STABLE]
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
How to Setup

This contains detailed instructions about setting up chan_sccp.

How to setup Chan_SCCP

How to use the config file

Please check out ./conf/sccp.conf for all possible sccp configuration parameters. This new config file uses standard asterisk templating to keep your config file shorter and easier to manager. For an untemplated version check-out ./conf/sccp_simple.conf

Setting Protocol

An important part in the config file is setting up the protocol version to match you phone firmware. During phone registration you can see the version of the protocol the phone supports and the version setup in the sccp.conf file. Please try to match them as closely as possible

Currently chan_sccp-b supports the following protocol versions:

  • 3-10
  • 10
  • 11 : for example matched by cisco 7960
  • 15 : matched by 7911
  • 16
  • 17 : matched by the 7970 and 7975 's

Sample config files

Make sure you pay attention to the CONTEXT used in the config file, it must match your dialplan. We have currently specified "sccp" as the default context, you will either have to add the sccp context to your dialplan in the correct locations or change the default sccp context to something that matches your dialplan.

Also check the deny/permit entries to make sure they cover your network/devices and check if the bindaddr is actually reachable from the addresses you have permitted to connect.

When using hinted speeddials it is important to provide the necessary hints in your dialplan by simply adding something like "exten => 98021,hint,SCCP/98021" in the 'default' context (or possibly "from-internal" for FreePBX users). You will have to use the same context when definining the speeddial button below. You can also create these hints in a seperate context called hints for example

[hints]
exten => 98021,hint,SCCP/98021

That way you can refer to them in a button definition like (notice the context used to create hints in the dialplan, must match the context specified in the button definition)

button = speeddial,Phone 2 Line 1, 98021, 98021@hints

Monitoring non-SCCP devices is possible by reviewing the hint status in the Asterisk CLI using the "core show hints" command. Anything that generates a hint can be monitored using the buttons. The following states are recognized: .... Custom state processing (see Asterisk documentation for more information) is also possible using this methodology.

(For more information about hints check How to to use Hints here)

;=========================================================================================
;
; general definitions
;
; (Don't use this version, take one from the conf samples directory !!!!)
;
;=========================================================================================
[general]
servername = Asterisk
keepalive = 60
debug = core,event,device,channel
context = sccp
dateFormat = D.M.Y
bindaddr = 0.0.0.0
port = 2000
disallow=all
allow=alaw
allow=ulaw
allow=g729
firstdigittimeout = 16
digittimeout = 8
autoanswer_ring_time = 1
autoanswer_tone = 0x32
remotehangup_tone = 0x32
transfer_tone = 0
callwaiting_tone = 0x2d
musicclass=default
language=en
deny=0.0.0.0/0.0.0.0
permit=192.168.1.0/255.255.255.0
dnd = on
sccp_tos = 0x68
sccp_cos = 4
audio_tos = 0xB8
audio_cos = 6
video_tos = 0x88
video_cos = 5
echocancel = on
silencesuppression = off
private = on
callanswerorder=oldestfirst
meetme = on
meetme = qxd
protocol = 11
regcontext ; context used for dundi dialplan registration
hotline_enabled=yes ; can devices without configuration register
hotline_context=default ; context for hotline
hotline_extension=111 ; extension will be dialed on offHook
;=========================================================================================
;
; actual definitions
;
;=========================================================================================
[SEP001122334455]
description = Phone Number One
addon = 7914
devicetype = 7940
park = off
button = speeddial,Helpdesk, 98112, 98112@hints ; Add SpeedDial to Helpdesk (verify that you have the hints context correctly set [\ref nf_hints])
button = line, 98011 ; Assign Line 98011 to Device
button = empty ; Assign an Empty Button
button = line, 98012 ; Assign Line 98012 to Device
button = speeddial,Phone 2 Line 1, 98021, 98021@hints ; Add SpeedDial to Phone Number Two Line 1 (Notice the context needs to be the same as where the hint is defined in your dialplan)
cfwdall = off
type = device
keepalive = 60
tzoffset = +2
transfer = on
park = on
cfwdall = off
cfwdbusy = off
cfwdnoanswer = off
pickupexten = off
pickupcontext = sccp
pickupmodeanswer = on
dtmfmode = inband
imageversion = P00405000700
deny=0.0.0.0/0.0.0.0
permit=192.168.1.5/255.255.255.255
dnd = on
nat=on
directrtp=on
earlyrtp = none
private = on
mwilamp = on
mwioncall = off
meetme = on
meetmeopts = qd
setvar=testvar=value
cfwdall = on
[98011]
id = 1000
type = line
pin = 1234
label = Phone 1 Line 1
description = Line 98011
mailbox = 10011
cid_name = MY CID
cid_num = 98011
accountcode=79011
callgroup=1,3-4
pickupgroup=1,3-5
;amaflags =
context = sccp
incominglimit = 2
transfer = on
vmnum = 600
meetmenum = 700
trnsfvm = 1000
secondary_dialtone_digits = 9
secondary_dialtone_tone = 0x22
musicclass=default
language=en
audio_tos = 0xB8
audio_cos = 6
video_tos = 0x88
video_cos = 5
echocancel = on
meetme = on
meetme = qxd
regexten = 98011
silencesuppression = off
setvar=testvar2=my value
[98012]
id = 1001
type = line
pin = 4356
label = Phone 1 Line 2
description = Line 98012
mailbox = 10012
cid_name = MY LINE 2
cid_num = 98012
accountcode=79002
callgroup=1,4-9
pickupgroup=1,3-9
echocancel = off
context = sccp
incominglimit = 2
transfer = on
vmnum = 600
meetmenum = 700
trnsfvm = 1000
secondary_dialtone_digits = 9
secondary_dialtone_tone = 0x22
musicclass=default
language=en
audio_tos = 0xB8
audio_cos = 6
video_tos = 0x88
video_cos = 5
echocancel = on
silencesuppression = off
silencesuppression = on
[SEP002244668800]
description = Phone Number Two
devicetype = 7960
park = off
button = speeddial,Helpdesk, 98112 ; Add SpeedDial to Helpdesk (without hint)
button = line, 98021
button= feature,Private Call,privacy,callpresent ;set channel variable SKINNY_PRIVATE to 1 if feature is enabled
button= feature,DND Busy,DND,busy ;set dnd status to busy
button= feature,DND Silent,DND,silent ;set dnd status to silent
button= feature,Record calls,monitor ;record calls using automon (asterisk >= 1.6 only)
button= feature,call forward to *54,cfwdAll,*54 ;forward all calls to *54
button = speeddial,Phone 1 Line 1, 98011, 98011@hints
button = speeddial,Phone 1 Line 2, 98012, 98012@hints
type = device
keepalive = 60
tzoffset = +2
transfer = on
park = on
cfwdall = off
cfwdbusy = off
cfwdnoanswer = off
pickupexten = off
pickupcontext = sccp
pickupmodeanswer = on
dtmfmode = inband
imageversion = P00405000700
deny=0.0.0.0/0.0.0.0
permit=192.168.1.5/255.255.255.255
dnd = on
nat=on
directrtp=on
earlyrtp = none
private = on
mwilamp = on
mwioncall = off
setvar=testvar=value
cfwdall = on
[98021]
id = 1000
type = line
pin = 1234
label = Phone 2 Line 1
description = Line 98021
mailbox = 10021
cid_name = MY CID
cid_num = 98021
accountcode=79021
callgroup=1,3-4
pickupgroup=1,3-5
context = sccp
incominglimit = 2
transfer = on
vmnum = 600
meetmenum = 700
trnsfvm = 1000
secondary_dialtone_digits = 9
secondary_dialtone_tone = 0x22
musicclass=default
language=en
echocancel = on
silencesuppression = off
setvar=testvar2=my value
[softkeyset]
type=softkeyset
onhook = redial,newcall,cfwdall,dnd
connected = hold,endcall,park,select,cfwdall,cfwdbusy,idivert
onhold = resume,newcall,endcall,transfer,confrn,select,dirtrfr,idivert
ringin = answer,endcall,idivert
offhook = redial,endcall,private,cfwdall,cfwdbusy,pickup,gpickup,meetme,barge
conntrans = hold,endcall,transfer,confrn,park,select,dirtrfr,cfwdall,cfwdbusy
digitsfoll = back,endcall
connconf = hold,endcall,join
ringout = endcall,transfer,cfwdall,idivert
offhookfeat = redial,endcall
onhint = pickup,barge

For more config samples look in the conf directory in the root of the project. Here you will find sccp.conf, sccp_simple.conf and sccp_short.conf

How to load the Chan_SCCP

The chan_sccp module can be loaded using the following lines in asterisk module.conf:

noload => chan_skinny.so
load => chan_sccp.so

the skinny module is not allowed to be loaded, is it conflicts with chan_sccp.

A valid sccp.conf configfile has to be available in the asterisk configuration directory.

How to use RealTime Database

MySQL

Asterisk setup

Up till Asterisk 1.6

/etc/asterisk/res_mysql.conf or /etc/asterisk/res_config_mysql.conf:

[general] ; use general in extconfig.conf and the database name
;dbhost = 10.11.12.13
;dbport = 3306
dbsock = /var/lib/mysql/mysql.sock ; Either use dbsock or dbhost/dbport combination.
; dbsock is preferred when the database is on the local machine
; The location of mysql.sock may vary from system to system (please check)
[asterisk]
dbname = asterisk
dbuser = asterisk
dbpass = asterisk_password

From Asterisk 10 and up

/etc/asterisk/res_config_mysql.conf:

[general]
;dbhost = 10.11.12.13
;dbport = 3306
dbsock = /var/lib/mysql/mysql.sock ; Either use dbsock or dbhost/dbport combination.
; dbsock is preferred when the database is on the local machine
; The location of mysql.sock may vary from system to system (please check)
requirements=warn ; Needs to be specified since asterisk 1.8, cannot be left out
[asterisk]
dbname = asterisk
dbuser = asterisk
dbpass = asterisk_password

MySQL 4.0

Read trunk/conf/mysql-v4.sql into your mysql 4.0 database

mysql -p asterisk < conf/mysql-v4.sql

(To upgrade from a previous database version checkout trunk/conf/database_updates)

MySQL 5.0

Starting with mysql version 5.0 you can also use trunk/conf/mysql-v5.sql, here you have a seperate buttonconfig table

mysql -p asterisk < conf/mysql-v5.sql

(To upgrade from a previous database version checkout trunk/conf/database_updates)

PostgreSQL

Asterisk setup

[general]
;dbhost=10.11.12.13
;dbport=5432
dbsock = /tmp ; Either use dbsock or dbhost/dbport combination.
; dbsock is preferred when the database is on the local machine
; The location of postgresql socket may vary from system to system (please check)
requirements=warn ; Needs to be specified since asterisk 1.8, cannot be left out
[asterisk]
dbname=asterisk
dbuser=asterisk
dbpass=password

Buttons are configured in a seperate table called buttonconfig:

postgresql asterisk < conf/postgresql.sql

Chan_SCCP Configuration for Realtime

Add the following lines to the sccp.conf file

devicetable=sccpdevice ; datebasetable for devices
linetable=sccpline ; datebasetable for lines

/etc/asterisk/extconfig.conf: for mysql v4:

[settings]
sccpdevice => mysql,asterisk,sccpdevices
sccpline => mysql,asterisk,sccplines

for mysql v5:

[settings]
sccpdevice => mysql,asterisk,sccpdeviceconfig ; make use of the sccpdeviceconfig view instead of sccpdevice
sccpline => mysql,asterisk,sccpline

or for postgresql:

[settings]
sccpdevice => pgsql,asterisk,sccpdevices
sccpline => pgsql,asterisk,sccplines

Loading information into the tables

Connect to the dabase

insert into sccpdevices (type,description,tzoffset,dtmfmode,mwilamp,mwioncall,pickupexten,pickupmodeanswer,privacy,name) values ("7975","My 1st Phone",0,"on","on","on","on","on","full","SEP010102030404");
insert into sccplines (id,pin,label,description,context,incominglimit,transfer,mailbox,vmnum,cid_name,cid_num,trnsfvm,secondairy_dialtone_digits,secondairy_dialtone_tone,musicclass,language,accountcode,audio_tos,audio_cos,video_tos,video_cos,echocancel,silencesuppression,callgroup,pickupgroup,amaflags,setvar,name) VALUES(121,212,"Line 121","Line 121",internal,2,on,121,88121,"My Name",121,89121,10,"0x22","default","en",121,"0xB8",6,"0x88",5,"on","off","1,3-5","3-5","","",121);
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",1,"line",121,);
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",2,"speeddial","friend","122,122@hints");
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",3,"feature","dnd","busy");
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",4,"feature","cfwdbusy","122");

Using Realtime Database

Devices / Lines and Buttonconfigs are now loaded from the database. If you add a device to the sccpdevice table it will automatically be read during the device registration fase. No need to unload/load the chan_sccp module.

When you change any information in the database for a specific device which you want to reset to update it's status. You can use the standard asterisk realtime function to reload information

realtime load sccpdevice name SEP010102030404
or
realtime load sccpline name 123
sccp reset SEP010102030404
or
sccp restart SEP010102030404

Setting up a DHCP Server

dhcpd.conf:

option cisco-tftp code 150 = array of ip-address;
subnet 192.168.100.0 netmask 255.255.255.0 {
range 192.168.100.128 192.168.100.200;
default-lease-time 86400;
max-lease-time 172800;
option domain-name-servers 192.168.100.2;
option routers 192.168.100.1;
}
host phone1 {
hardware ethernet 00:0c:ce:3a:88:ca;
fixed-address 192.168.100.100;
option cisco-tftp 192.168.100.2;
}

What does a Sample SEP[MacAddr].cnf.xml Look Like

We have added a couple of example files in the directory conf/tftp conf/tftp/XMLDefault.cnf.xml_797x conf/tftp/XMLDefault.cnf.xml_796x conf/tftp/XMLDefault.cnf.xml_791x

You can choose one of these files and adapt it to your network/devices. You can then copy the file to your tftp-server and rename the file to XMLDefault.cnf.xml. If you like you can make soft links/shortcuts to this file for every device you have in the form of SEP[macaddr].cnf.xml files. For devices with specific settings you can copy your XMLDefault.cnf.xml file to a new SEP[macaddr].cnf.xml file and set the specific settings for this device.

Dialplan Sample

How to Dial an SCCP Phone from your dialplan

Dial(SCCP/998,120)

How to Dial an SCCP Phone with a different ring

Dial(SCCP/198/ringer=inside,120)

ringer= values:

  • outside
  • inside
  • feature
  • silent
  • urgent

Dial a line and have the phone Auto Answer

The Dial Command consist of the Channel type, Extension(Number), Options and Timeout. They can either be seperated by slash or comma. Dial(ChannelType/Extension/Options/Timeout)

Dial(SCCP/9291/aa=1w, 120)

aa= values:

  • 1w: 1way. MIC is oFF
  • 2w: 2ways. MIC is ON
  • 1wb: 1way and reject cause: busy
  • 1wu: 1way and reject cause: unavailable
  • 1wc: 1way and reject cause: congestion
  • 2wb: 2way and reject cause: busy
  • 2wu: 2way and reject cause: unavailable
  • 2wc: 2way and reject cause: congestion

Hot to change the firmware to SCCP

  • Copy the SCCP Firmware to your tftp directory
  • Set the Firmware version in OS79XX.TXT. It should containt only on line, like this:
    P00308010100
  • Set the XMLDefault.cnf.xml to should contain every used device and it firmware. It should look like this:
    <Default>
    <callManagerGroup>
    <members>
    <member priority="0">
    <callManager>
    <ports>
    <ethernetPhonePort>2000</ethernetPhonePort>
    </ports>
    <processNodeName>10.31.150.1</processNodeName>
    </callManager>
    </member>
    </members>
    </callManagerGroup>
    <loadInformation6 model="IP Phone 7910">SCCP11.8-5-2S</loadInformation6>
    <loadInformation6 model="IP Phone 7911">SCCP11.8-5-2S</loadInformation6>
    <loadInformation124 model="Addon 7914">S00105000300</loadInformation124>
    <loadInformation9 model="IP Phone 7935"></loadInformation9>
    <loadInformation8 model="IP Phone 7940">P00308010100</loadInformation8>
    <loadInformation7 model="IP Phone 7960">P00308010100</loadInformation7>
    <loadInformation20000 model="IP Phone 7905"></loadInformation20000>
    <loadInformation30008 model="IP Phone 7902"></loadInformation30008>
    <loadInformation30007 model="IP Phone 7912"></loadInformation30007>
    </Default>

For more information check out :
http://www.cisco.com/en/US/products/hw/phones/ps379/products_tech_note09186a0080094584.shtml http://www.cisco.com/en/US/docs/voice_ip_comm/cucme/command/reference/cmeallht.pdf http://www.cisco.com/en/US/docs/voice_ip_comm/cucme/admin/configuration/guide/cmelabel.html

Asterisk Clustering and DUNDi Lookup

DUNDi is a peer-to-peer system for locating Internet Gateways to telephony services. Unlike traditional centralized services (such as the remarkably simple and concise ENUM standard), DUNDi is fully distributed with no centralized authority whatsoever.

DUNDI Configuration

If regcontext is specified in sccp.conf chan-sccp-b will dynamically create and destroy a NoOp priority 1 extension for a given peer/line which registers with the server. If the context is not specified in extension.conf, then it will be dynamically created when an chan-sccp-b agent registers.

Example sccp.conf:

[general]
regcontext=sccpregistration

Once the phones, in this example 98011 and 98012 register with your asterisk server1, a context of [sccpregistration] appears and the "show dialplan" command at the asterisk CLI> will produce:

server1*CLI> dialplan show sccpregistration
[ Context 'sccpregistration' created by 'SCCP' ]
'98011' => 1. Noop(98011) [SCCP]
'98011@1' => 1. Noop(98099) [SCCP]
-= 2 extensions (2 priorities) in 1 context. =-

This gives this PBX a dedicated context that we can map DUNDi lookup requests to. When a DUNDi lookup requests location information for extension 98011, this PBX will reply "yes, the extension is active here and this is the contact address".

We do not have to insert a [sccpregistration] in the extensions.conf because it will be created automatically as soon as the first line/extension registration occurs.

DUNDI Configuration

In this example we will use IAX2 to make DUNDi Switch connections. There are a lot of ways to set this up, so please check the DUNDi documentation. We use a simple context in iax.conf which is common for all PBX servers, like this:

iax.conf:

[priv]
type=friend
dbsecret=dundi/secret
context=incomingdundi

In the DUNDi [mappings] section, we specify what [context] in extensions.conf we want to allow DUNDi request access to. This is how the cluster sees any available SCCP Agents in the [sccpregistration] context on this PBX.

dundi.conf
[mappings]
priv => sccpregistration,0,IAX2,priv:${SECRET}@10.10.10.10.1/${NUMBER},nopartial]

For the rest of the DUNDi implementation in a clustered environment please check out:

Troubles using VOIP and SCCP through a Firewall (NAT)

What is this NAT and why does this cause problems with VOIP, RTP and sound ?

In addition, the way in which conventional VoIP protocols are designed is also posing a problem to VoIP traffic passing through NAT. Conventional VoIP protocols only deal with the signalling of a telephone connection. The audio traffic is handled by another protocol and to make matters worse, the port on which the audio traffic is sent is random. The NAT router may be able to handle the signalling traffic, but it has no way of knowing that the audio traffic is related to the signalling and should hence be passed to the same device the signalling traffic is passed to. As a result, the audio traffic is not translated properly between the address spaces.

At first, for both the calling and the called party everything will appear just fine. The called party will see the calling party's Caller ID and the telephone will ring while the calling party will hear a ringing feedback tone at the other end. When the called party picks up the telephone, both the ringing and the associated ringing feedback tone at the other end will stop as one would expect. However, the calling party will not hear the called party (one way audio) and the called party may not hear the calling party either (no audio).

The issue of NAT Traversal is a major problem for the widespread deployment of VOIP. Yet, the issue is non-trivial and there are no simple solutions. In general terms there are two ways to deal with this problem:

  • Don't use NAT, i.e. public ip-addresses for a your phone (not a solution)
  • Build a tunnel between the networks that need to communicate with each other, No NAT Required over the tunnel.
  • Put Asterisk on the Firewall and make it the go-between / proxy. See next point. (For SCCP: set directrtp=off in your config).
  • Use a Firewall Connection Tracking Plugin which records outgoing VOIP Connections and Maps there return RTP connections. For example for iptables this plugin is called: nf_nat_sip.ko or nf_nat_h323.ko. At this moment in time we do not have a version for sccp, yet. (But for SIP and H323 it works very well).

Other works arounds:

  • Use static ip-address on your phones and creates forwards in your firewall for the SCCP port and a block of RTP ports for this phone.
  • Put a SIP-Proxy on the Firewall and reroute the packets. You could use for example : SER (Sip Express Router), SIPProxd or RTPProxy.
  • Use a STUN Server: http://www.voip-info.org/wiki/view/STUN, http://tools.ietf.org/html/draft-ietf-sipping-nat-scenarios-13
  • Find and IAX2 provider instead of SIP. IAX can encapsulate RTP with its packets and therefor traverse NAT without any problems.

You can find more infomation about VOIP and NAT here

Shared Lines

Shared lines are lines used by several devices at the same time providing easy handling of phone calls between them. You can for example hold a line on one device and use resume on another to pick the line up there. Or even steal a line from another device using the Intercept button.

To set up a shared line, you just define the same extension/line number on multiple devices. You can add a suffix or subscriptionId to the extension number to be able to call a specific device using "@" and if you like an extra callerid_name behind ":", like this:

[SEP00000001]
...
button = line, 900@1:Kitchen
...
[SEP00000002]
...
button = line, 900@2:LivingRoom!silent
...

If you now create the relevant entries in your dialplan you can either call 900, 9001, 9002 using this example:

_9XX =>{
Dial(SCCP/${EXTEN});
};
_90XX =>{
Set(extension=${EXTEN:0:3});
Set(suffix=${EXTEN:3:1});
Dial(SCCP/${extension}@${suffix});
};

To add a default suffix to a line (so all device using that line, will also be accessible via the default suffix) you can add "defaultSubscriptionId_number = " to the line definition in sccp.conf.

When "silent" is added to the subscriptionId this line will not ring if the shared line is called, this can be used when a secretary is supposed to handle all incoming calls on a shared line. Only when the extension including the suffix/subscriptionId is called will this line ring.