Howto Provisioning berofix via TFTP/HTTP

From berofix - professional SIP gateway
Jump to: navigation, search

berofix TFTP/HTTP configuration

This howto will describe how to provioning a berofix device over tftp/http host without using the berofix GUI. In the first step the config files are explained. In the next step the http-API is explained.

You can use the tftp way and the berofix GUI at the same time, but be aware when you do "activate" in the GUI the local config files are written by the GUI and will be overwritten by the tftp way either after a reboot or after you've explicitly requested to re-read the config files via tftp.

Be aware meanwhile there are 2 Firmware Verions. Check the API Changelog for Firmware Version 2.

Config Files

These are the files which are necessary for the remote configuration via TFTP or HTTP.

V1

  • conf-update.conf
  • firmware-update.conf
  • isdn.conf
  • isgw.isdn
  • isgw.conf
  • isgw.sip
  • isgw.dialplan
  • isgw.causes (optional)
  • misc.conf (optional)


You can seperate these files in 3 Categories: Control, Hardware and ISGW.

Control

conf-update.conf

This is the first file berofix is looking for, before an tftp "config" download is started. You can control in this file from the tftp-server site if a the config files should be downloaded or not. The "conf-update.conf has the following mandantory value:

CONF_DOWNLOAD=yes [yes|no]

firmware-update.conf

This is the first file berofix is looking for, before a "firmware" upgrade via TFTP is started. You can control in this file from the tftp-server site, if the firmware upgrade should be started. The "firmware-update.conf" has the following mandantory values:

FIRMWARE_DOWNLOAD=yes [yes|no]
FIRMWARE_INSTALL=yes [yes|no]
FIRMWARE_FILE=appfs-1.12rc5.tar.gz [firmware file name]

Hardware

isdn.conf

The isdn.conf files configures the mandatory Hardware parameters for the LineInterfaces. In the GUI this files is mostly represented by the menu point "Hardware". Be Aware: every Lineinterface Section must be given even if you have only 1 lininterface present.

# lifx - is the LineInterface section. x can be 0 or 1 for LineInterface 0 or 1. All configuration values which belongs to this LineInterface are below this section.
[lif0]
# type - is the LineInterface Type. Possible is [bf4S0,bf1E1,bf2E1].This value is mandatory
type=bf2E1
# master - set the Bridging and Clock behaviour on a berofix card.
# For instance if master on the lif0 is set to 1 and on lif1 to 0, Hardware Bridging will be activated
# between the two LineInterfaces. If you set master to 1 on both LineInterfaces Hardware Bridging
# will be deactivated. This value is mandatory
master=1
# clock - is the port number on where the berofix should recieves his clock from. This value is mandatory
clock=1
# ntteSW - configures the software protocol mode for the port. Possible values are [te|nt].
# It is an comma separated list for each port. This value is mandantory.
ntteSW=te,te

[lif1]
type=bf4S0
master=0
clock=0
ntteSW=te,nt,nt,te
# ntteHW - configures the hardware protocol mode for each BRI port(the PinOut). Possible values are [te|nt].
# It is an comma separated list for each port. This value is mandatory for bf4S0 LineInterfaces.
ntteHW=te,nt,nt,te
# termination - set the linetermination of each BRI port. Possible values are [0|1].
# 1=enable and 0=disable the linetermination. It is an comma separated list for each port.
# This value is mandatory for bf4S0 LineInterfaces.
termination=0,1,0,1
# ptp - sets PMP(PointtoMultiPoint) or PTP(PointToPoint) on a BRI Port. Possible values are [0|1].
# 1=PTP and 0=PMP. It is an comma separated list for each port. This value is mandatory for bf4S0 LineInterfaces.
ptp=1,0,1,0
# portswitch - special flag to use all 4 RJ45 if you use a single bf4S0 module together with a bf4S0Bridge.
# Possible values are [0|1]. 1=enable and 0=disable. This value is mandatory for bf4S0 LineInterfaces.
# This feature is only usable with berofix Hardware > Rev.1.8.
portswitch=0

# pcm - this section is currently not implemented.
[pcm]
type=pcm
master=yes

ISGW

The ISGW related Config files are generally written in a .ini style, the only exception is made by the isgw.dialplan file.

In the files isgw.sip, isgw.isdn and isgw.dialplan you can make use of the Dynamic Config string Parameter. Normal Paramters are used like:

$parameter = $value

The Config string on the other hand is used like:

config = $parameter1=$value1,$parameter2=$value2,...,$parameterN=$valueN

You can set different call-specific parameters like "ec=1/0" (echocancel enabled or not), "bearer_cap=SPEECH/..." and codecs in the config string. As you can use the config string in the isgw.dialplan you can modify each call seperately with different config strings.

A full list of config-string parameters is given below (this list can be given by the "dc" command in the telnet interface):

Default call configuration:
[i][ec] Echocancel <0=off,1=0n>                          '1'
[i][ectl] EC tail length <0=8ms,1=16ms,...,15=128ms>     '15'
[i][dnumplan] dnumplan                                   '0'
[i][rnumplan] rnumplan                                   '0'
[i][onumplan] onumplan                                   '0'
[i][cpnnumplan] cpnnumplan                               '0'
[i][unknownprefix] unknownprefix                         
[i][internationalprefix] internationalprefix             '00'
[i][nationalprefix] nationalprefix                       '0'
[i][localprefix] localprefix                             
[i][privateprefix] privateprefix                         
[i][screen] screening                                    '0'
[i][pres] presentation                                   '0'
[i][bearer_cap] bearer capability                        'SPEECH'
[s][ea] Early Audio <0=off,1=0n>                         '1'
[s][t38] T.38 support <0=off,1=on>                       '1'
[s][dtmfmode] DTMF mode <rcf2833, info or inband>        'rfc2833'
[s][codecs] Codecs                                       'pcma'
Default config string:   
 config=ec=1,ea=1,dnumplan=0,rnumplan=0,onumplan0,cpnnumplan=0,unknownprefix=,internationalprefix=00,nationalprefix=0,localprefix=,privateprefix=,t38=1,ectl=15,dtmf=rfc2833,codecs=pcma

isgw.conf

This file is used to configure general settings like the telnet interface port, the udp port range, the syslogserver and the loglevel. The file has a layout like:

[general]
;
;telnet interface where we listen on:
;
statusport=54322
;
;syslog server where we send log messages to
;
logserver=127.0.0.1:54323
;
; enable/disable logging in /tmp directoy on berofix. 
; this helps analyzing error situations, because these logfiles are
; tared together with the coredump in case of a crash. 
;
logging_active=1
;
; which loglevel we have, ranges from 0..9 
; 
loglevel=0
;
;Syslog Facility is one information field associated with a syslog message. It is defined by the syslog protocol.
;It is meant to provide a very rough clue from what part of a system the message originated from. LOCAL_0 to
;LOCAL_7 facilities, are traditionally reserved for administrator and application use.The facility can be very
;helpful to define rules that split messages for example to different log files based on the facility level.
;syslog_facility=[16-23] local0-local7
;
syslog_facility=16

isgw.sip

The isgw.sip file contains sip specific settings like Proxy definitions and Registrations. In beroFix you can define several outbound proxies with names and settings. These proxy definitions can later be used in the dialplan to make outbound calls by reference of the given name.

The isgw.sip file contains the following imporant settings:

[general]
;
;bind address and port where we listen for SIP Messages
;
sip_address=sip:0.0.0.0:5060
;
; which udp ports we use in our SDP offers, you can provide ranges like 5100-5500 
;
udpports=5000-5059,5062-6000
;
; External IP Address. Used when behind a Natted Gateway.
;
; General form:
; externip=<IP-Address>[,ic=1][,rc=1]
; the IP-Address is the IP that is used in the sip headers. if not set, the bind ip address is used. 
; ic=1 means that the external ip is also used in the contact header for outgoing invites
; rc=1 means that the external ip is also used in the contact header for outgoing registers
;
externip=
;
;sip_over_tcp=[0|1] activates sip over tcp. default is sip_over_tcp=0, which means sip over udp.
;
sip_over_tcp=[0|1]
;
;SIP Registration interval regrefresh=[time in seconds] regrefresh=60 means berofix will reregister at the registar
;every 60 seconds.
regreresh=60
;
;
; proxies and registrars are defined in sperate sections:
;
[test-proxy]
; 
;address of the proxy
;
address = 172.20.0.1
;
;type can be proxy/registrar/both
;
type = proxy
;
;username which we use to authenticate our calls (should be the same like the proxy-section name in [..] ) 
;
user = test
; 
;secret which we use to authenticate our calls. 
;
secret = test
;
; general config String for this proxy
;
config = ea=1,t38=1,dtmfmode=rfc2833

; must be present
default=0

isgw.isdn

In this file you need to create ISDN Groups. Only Ports in ISDN groups are initialized and can be used by ISGW. The file is devided in a general and in the group sections.

;
[general]
;if time_from_isdn is set to a valid port [1,2,3,....], berofix will try to get the system time from this port and
;disable getting time via ntp. time_from_isdn=0 will will active ntp. Note time_from_isdn will only refresh the
;system time during the first inbound call that was answered.
;
time_from_isdn=[port]
;
; the group names are set as section names. These can be referenced in the dialplan
;
[test]
;
; the isdn ports which are in the group. If you have 2 Lineinterfaces the ports of the second Lineinterface do 
; NOT start again with 1, they simply count on.
;
ports = 1,2
;
; method for searching a free channel in this group, the options are:
; standard, roundrobin, random 
;
chansel = standard
;
; Config string with parameters for this ISDN Group 
;
config = ec=0,ectl=8,dnumplan=0,rnumplan=0,onumplan=0,cpnnumplan=0,unknownprefix=
;
; which tone set should be used. tones=[de|us|fr......]
; 
tones = de
;
; set this to "yes" if you want to skip the overlap_dial_timer for incoming ISDN Calls. The SIP proxy needs
; to support overlapdialing. overlap_dialing=[0|1] 0=no, 1=yes
;
overlap_dialing = 0
;
; Set this to the amount of seconds which we wait for new incoming digits after an incoming ISDN call
;
overlap_dial_timeout = 5
;
; When the incoming ISDN Call had no digits at all (like from an ISDN Phone which goes offhook) we 
; wait the configured time (in seconds) for the first digit.
;
overlap_dial_timeout_empty_dad = 15
; Activate QSIG support. QSIG=[0|1] 0=no, 1=yes
;
qsig=0

isgw.dialplan

The dialplan is the only config files that differs regarding the style. It is not a .ini based file, there are no sections at all. The first row of the file is reserved for the column headers followed by the dialplan rows. Every line is a seperate dialplan entry and each line has 9 Config Fields which need to be seperated by single tabs and ends with a Linefeed (!! also the last one !!). The Line looks like:

;From <TAB> To <TAB> FromID <TAB> ToID <TAB> Destination <TAB> NewDestination <TAB> Source <TAB> NewSource <TAB> Config

The Fields mean:

From            - can be SIP or ISDN
To              - can be SIP or ISDN but must be different than From
FromID          - If From is ISDN FromID can either contain an ISDN Port or 
                        an ISDN Group Name. If you want to refer to an ISDN Group Name you need to 
                        prefix the name with a "g:". If you have for example a group like "test-s0" in 
                        your isgw.isdn, then you can refer to it with "g:test-s0" 
                        If From is SIP you can set an IP Address here. The IP Address can also 
                        be specified as a regular expression, to match Address Ranges or simply anything also.
ToID            - In the ISDN case ToID can be an ISDN Port or an ISDN Group (with g: prefix). In the
                        SIP Case it can be an IP Address or a Proxy Name (with a p: prefix). 
Destination     - A regular expression rule must be given. Tokens in "(..)" can be referenced in 
                        NewDestination
NewDestination  - Can contain any String, \1 is replaced by the first Token in Destination, \2 
                        is replaced by the second token and so on.
Source          - A  regular expression rule must be given. Tokens in "(..)" can be referenced in 
                        NewSource
NewSource       - Can contain any String, \1 is replaced by the first Token in Source, \2 
                        is replaced by the second token and so on.
Config          - Contains a config string which does apply to the call which matches this dialplan rule.


A Simple Dialplan Configuration which allows sending and Receiving calls from a "test-proxy" and a "test-s0" Proxy and ISDN Group with 2 Dialplan rules is given below:

; sip to isdn - matches calls coming from sip going to isdn
; (.*) - regular expression which matches any IP Address
; g:test-S0 - the ISDN Group with the name test-S0 
; (.*) - matches any dialed number 
; \1 - the same number which matched above should be dialed in the isdn outbound call 
; (.*) - matches any callerdid
; \1 - the same callerid which matched above should be used in the isdn outbound call
; ec=1 - the config string says that echocancelation should be enabled when this rule matches
sip	isdn	(.*)	g:test-S0	(.*)	\1	(.*)	\1	ec=1

; isdn to sip - matches calls coming from isdn going to sip
; g:test-S0 - Matches calls coming from ports from the isdn group test-S0
; p:test-proxy - The call should be sent to the proxy defined as "test-proxy"
; (.*) - matches any dialed number 
; \1 - the same number which matched above should be dialed in the isdn outbound call 
; (.*) - matches any callerdid
; \1 - the same callerid which matched above should be used in the isdn outbound call
; ec=1 - the config string says that echocancelation should be enabled when this rule matches
isdn	sip	g:test-S0	p:test-proxy	(.*)	\1	(.*)	\1	ec=1

The berofix API

The beroFix API can be accessed by using the URL (the standard username:password are "admin:admin"):

http://berofix/app/api/beroFix.php

Under the above mentioned URL you will find a documentation about the API hwo to use it and an overview about the commands.

Bf Provisioning API.png

Commands have always the following schema: ?cmd=[command]&data=[key1]=[value1]:[key2]=[value2]...

You can easily access the API from a console with "wget". If for example you want to read which lineinterfaces are present on your beroFix card you can issue the following command in a shell

wget -O-  --user=admin --password=admin http://berofix/app/api/beroFix.php?cmd=getlif 2>/dev/null


The cmd=help explains all the commands and parameters.

More details on the berofix API can be found here: Howto use beroFix API