Realtime Configuration - chan-sccp/chan-sccp GitHub Wiki

Saving the configuration in some kind of online storage like postgresql, mysql or ldap instead of a file, that is what asterisk calls a realtime configuration. Because the settings can be recalled in realtime. If you have compiled you asterisk server with support for postgresql, mysql or sqlite(3), then you can store the line and device configuration in one of these databases. Underneath you will find setup examples for all of these databases.

There are several advantages to using a realtime setup, namely:

  • Easier maintenance of devices, lines and buttonconfigurations
  • No need to use sccp reload, when only one or two devices have changed
  • Changes to the device/line configuration will automatically be pickup up when a device (re-)registers

Realtime Commands

  • sccp reload force
  • sccp reload device SEP0012345676
  • sccp reload line 1111
  • sccp reset SEP0012345676
  • sccp restart SEP0012345676

NOTE: If you're using a modern version of sccp_manager, it will automatically set up the Realtime Database for you. The information below this line is meant for anyone using an older version, (or not running sccp_manager).

SCCP Setup

Before following the information below, do check out the ./conf directory in the source distribution, it will contain exact example files tailored to the version you are using. These might be a better fit than the example presented below.

To use realtime entries the only thing you need in the sccp.conf [general] sections is:

[general]
....
devicetable=sccpdevice           ; note these are the default values for these two entries, so you can just leave them out.
linetable=sccpline
....

Referring to the entries in /etc/asterisk/extconfig.conf, not the actual table names in the database.

DB Specific Setup

Postgresql

Edit /etc/asterisk/res_pgsql.conf

[general]
; 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)
;dbhost=10.11.12.13
;dbport=5432
dbsock = /tmp 
requirements = warn ; Needs to be specified since asterisk 1.8, cannot be left out

[myastdb]
dbname = asterisk
dbuser = asterisk
dbpass = password

Read ./conf/postgresql.sql into your pre-created postgresql database

psql asterisk < conf/postgres.sql

Which will result in 3 tables:

  • sccpdevice
  • sccpline
  • buttonconfig

And and view called:

  • sccpdeviceconfig

You will need to check and update the permissions to read / update tables if you are using a particular username / password to connect to the database, for example:

grant select, insert, update, delete on *.* to 'asterisk';`

Edit /etc/asterisk/extconfig.conf so that it will contain these entries:

[settings]
;
;
; [alias] => [driver],[dbsection],[dbtablename]
sccpdevice => pgsql,myastdb,sccpdeviceconfig               ; Please note use the '=>' instead of '='
sccpline => pgsql,myastdb,sccpline

Notice that sccpdevice is connected to the sccpdeviceconfig view, not the sccpdevice table. This view returns the aggregate of sccpdevice and buttonconfig.

Mysql

Depending on your asterisk version you will have to edit /etc/asterisk/res_config_mysql.conf(ast1.8+) or /etc/asterisk/res_mysql.conf(ast1.6):

[general]
; 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)

;dbhost = 10.11.12.13
;dbport = 3306
dbsock = /var/lib/mysql/mysql.sock 

[myastdb]
dbname = asterisk
dbuser = asterisk
dbpass = asterisk_password

Read ./conf/mysql-v5.sql into your pre-created mysql 5.x database

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

Which will result in 3 tables:

  • sccpdevice
  • sccpline
  • buttonconfig

And and view called:

  • sccpdeviceconfig

Edit /etc/asterisk/extconfig.conf so that it will contain these entries:

[settings]
;
;
; [alias] => [driver],[dbsection],[dbtablename]
sccpdevice => mysql,myastdb,sccpdeviceconfig                  ; Please note use the '=>' instead of '='
sccpline => mysql,myastdb,sccpline

Notice that sccpdevice is connected to the sccpdeviceconfig view, not the sccpdevice table. This view returns the aggregate of sccpdevice and buttonconfig.

Important: if you change anything in the structure of the sccpdevice or buttonconfig table, that view needs to be updated by recreating it.

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

Sqlite

(Also check ./conf/sqlite3.sql)

Edit /etc/asterisk/res_config_sqlite3.conf

[myastdb]
dbfile => /var/lib/asterisk/realtime.sqlite3                 ; Please note use the '=>' to indicate a path
batch = 1000

Read ./conf/sqlite3.sql into your sqlite 3.x database

sqlite3 /var/lib/asterisk/realtime.sqlite3 < conf/sqlite3.sql

If this database did not already exist, it will be created on the fly. This will result in 3 tables:

  • sccpdevice
  • sccpline
  • buttonconfig

And and view called:

  • sccpdeviceconfig

Edit /etc/asterisk/extconfig.conf so that it will contain these entries:

[settings]
;
;
; [alias] => [driver],[dbsection],[dbtablename]
sccpdevice => sqlite3,myastdb,sccpdeviceconfig             ; Please note use the '=>' instead of '='
sccpline => sqlite3,myastdb,sccpline

Notice that sccpdevice is connected to the sccpdeviceconfig view, not the sccpdevice table. This view returns the aggregate of sccpdevice and buttonconfig.

Clarification of extconfig.conf terms

  • The 'alias' is what chan-sccp (sccp.conf) used to look up where to find the realtime table.
  • The 'driver' tells asterisk (extconfig) which driver should be used to access the database. This also determines which res_config_xxxx file is used.
  • The 'dbsection' refers to the section name within the res_config_xxxx file. Note, This MUST match from res_config_xxxx
  • The 'dbtablename' is the name within the database that should be associated with this alias.

Table Extensibility

The sql files used above contain a possible sample database that you can use. You are however free to add/remove fields that exist in sccp.conf.annotated. Any of them are potential candidates to be included in the sccpdevice and sccpline tables.

[Optional] Loading information into the tables

This step is only required when moving an existing install to a realtime configuration. If you're starting from scratch, you can skip it.

Connect to your database (Please adapt to the database being used):

insert into sccpdevices (type,description,tzoffset,mwilamp,mwioncall,pickupexten,pickupmodeanswer,privacy,name) values ("7975","My 1st Phone",0,"outofband","on","on","on","on","full","SEP010102030404");

insert into sccplines (pin,label,description,context,incominglimit,transfer,mailbox,vmnum,cid_name,cid_num,trnsfvm,secondary_dialtone_digits,secondary_dialtone_tone,musicclass,language,accountcode,audio_tos,audio_cos,video_tos,video_cos,echocancel,silencesuppression,callgroup,pickupgroup,amaflags,setvar,name) VALUES("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",0,"line",121,'121-linelabel');  
-- buttonconfig.device='SEP010102030404' points at sccpdevice.name='SEP010102030404'
-- buttonconfig.instance starts at 0
-- buttonconfig.type should be one of 'line', 'speeddial', 'service', 'feature', 'empty', following the same order as button entries in sccp.conf
-- buttonconfig.name=121 points at sccpline.name==121

insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",1,"speeddial","friend","122,122@hints");
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",2,"feature","dnd","busy");
insert into buttonconfig (device,instance,type,name,options) VALUES("SEP010102030404",3,"feature","cfwdbusy","122");

Post-install testing:

You can query the database directly by connecting to it an issuing the following commands:

SELECT * FROM sccpdevice;
SELECT * FROM sccpline;
SELECT * FROM buttonconfig;
SELECT * FROM sccpdeviceconfig;

If you've loaded data into the tables, make sure the last query contains the buttons you defined in a comma seperated field called 'button'.

You can also try realtime queries from within the Asterisk CLI:

realtime load sccpdevice name SEP01010203040
realtime load sccpline name 123

If both of these queries reflect the sccpdeviceconfig and sccpline views/tables from the database, then you a ready to check if an sccpdevice can register with the chan_sccp module.

Please note: only Registered devices and it's lines will show up in CLI commands like 'sccp show devices', 'sccp show lines' etc. So you will have to hookup a device to test your realtime configuration.

sccpdeviceconfig View

Note that if you change/add/remove any columns from the sccpdevice table (alter table), you will have to drop and recreate the sccpdeviceconfig view for it to pick up the new/altered columns. If you do not do this, you will not see any of the new fields within chan-sccp-b.

Relationships between the tables

buttonconfig.device -> sccpdevice.name buttonconfig.name -> sccpline.name (in case buttonconfig.type==line) sccpdeviceconfig.id -> device.id sccpdeviceconfig.button -> concatenation of buttonconfig entries for this device.