UserApp API Reference

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

appfs APIs

The berofix Firmware has several features that can be used by an userapp.


Aside the basic tools provided there are several other to be used by an UserApp:


Several libraries to be used by UserApps are provided by beroFix:


beroFix has a REST like API. It allows the provisioning of most important berofix parameters. More info can be found in the Howto use beroFix API.

beroFix config files

beroFix has a set of config files that contain all the settings for both the berofix OS itself (like Network configuration, cloud configuration and so on), a hardware.conf which stores settings for each berofix module (bri, pri, analog, gsm) and the ISGW config files which store all PSTN, SIP and Routing related settings.

The set of config files can be exchanged with berofix via the following mechanisms:

  • Provisioning (supports http and tftp)
  • beroGUI backup&restore
  • beroCloud backup&restore

The relevant configuration files are:


These files have a ini-style format. Some settings are mandatory, but most have a senseful default value and can be omitted if not needed.

General Configuration

The basic configuration of a beroFix is stored in the file misc.conf. It contains networking, provisioning, beroCloud and other settings. A sample is shown below:


Hardware Configuration

There are several beroFix Line-Interface modules that allow the connection to different PSTN types (ISDN BRI, ISDN PRI, Analog FXS, Analog FXO, GSM). Some of these modules need to be configured, which can be done in the hardware.conf.

Since beroFix has two slots for modules and one PCM interface, the file hardware.conf is parted into three sections:

type= .. 
type= ..

ISGW Configuration

ISGW is the SIP2PSTN routing service, it has several configuration files.


It contains general settings like the logging configuration.


It contains general SIP settings and the SIP accounts.


It contains the ISDN groups and general ISDN settings.


It contains the analog (FXS and FXO) groups and general analog settings.


It contains the gsm groups and general gsm settings.


It contains the routing table (the dialplan).


It contains the causes map, see BeroFix ISDN Cause/SIP Response map for details.


It contains the call progress table, see BeroFix Call Progress Tables for details.

ISGW telnet interface

ISGW has a telnet interface, which can be used to monitor the ISGW status and to enable logging and debugging. The telnet interface is accessable on tcp Port 54322, it displays immediately a command overview with a short description of each command:

[root@berofix3195 ~]# telnet localhost 54322
ISGW Status Monitor
h	:help
i	:isdn state
r	:status of registrations
l	:status of operations
k	:status of operations (compact)
R	:status of incoming registrations
RrX	:release incoming registration at index X
c	:clear screen
v	:set verbosity debug
m	:set verbosity message
V	:show verbosity
ld0	:disable debug logging
ld1	:enable debug logging
lm0	:disable message logging
lm1	:enable message logging
prX	:ISDN port restart(X is port number)
x	:shutdown isgw
n	:change netlog target
t	:toggle netlog on/off
ts	:get netlog status
d	:list dialplan
cc	:print call configuration for call at given index
dc	:print default call configuration
ndc	:print default call configuration with regexp info
verbose	:start verbose dialplan debugging
u	:uptime of isgw
blX	:block/unblock port, is unblocked initially
rd	:reload dialplan
rs	:reload sip peers
bc	:list bchannel objects
ss	:show call statistics
sr	:reset call statistics
ssp	:show port specific call statistics
ccd	:connected call duration
itpX	:set time from isdn active on port X
pcm	:show pcm table
ev_mcid:X	:send MCID Facility on call at indexX
fc	:flush cdr
ll	:show local netlog status
lla	:activate local netlog
lld	:deactivate local netlog
lcpt	:list call progress tables
rcpt	:reload call progress tables
sns	:show numplan call statistics
rns	:reset numplan call statistics
lihX	:list isdn history for call at index X
dti	: test dialplan from isdn
dts	: test dialplan from sip
dta	: test dialplan from analog
dtg	: test dialplan from gsm
lpg	: list port groups
g	: list gsm status
gi	: acquire advanced gsm data
atX:$	: write AT command $ to gsm port X
gop_retrieveX	: retrieve gsm operator list from network on port X
gop_list	: show current gsm operator setting
gop_setX:Y:Z	: set gsm operator on port X to mode Y to Z
bertX	: start bert for call at index X
sbertX	: fetch statistics for call at index X
lbertX	: list statistics for call at index X
cbertX	: list statistics for channel X
pbertX	: set bert test pattern to value X (HEX format)
tbert1	: use custom test pattern for bert
tbert0	: use automatic test pattern for bert
rgc	: reload gsm config
rgpX	: restart gsm port X
poogli0	: power off and on gsm line interface 0
poogli1	: power off and on gsm line interface 1
torture_gsmX:Y	: torture gsm on port X by repeating Y times the initialization routine
slYX	: set sofia log level for module Y to X => Y can be tport,iptsec,nta,stun,nth_client,nth_server,sresolv,nua,soa,nea,default,all
ltdm	: list tdm timeslots
finX	:finish call at index X
finpX	:finish call with pid X
dbg	:toggle debugging on/off
q	:disconnect client

Short Messages Spool

If a GSM-module is installed, berofix provides a directory structure to send and receive SMS. It is located in /tmp/sms/ and contains three spools in/ for received messages, out/ for messages to be sent and failout for messages that have failed to be send.

The format for messages sent / received is defined as follows:

  msg=Hello, World.
  This is a test.

To send a message, all parameters have to be set. Even though in most cases the field from is not neccessary, it then should be set to none. While all other parameters are one-liners, the field msg can span over several lines, depending on how the message was formated. For this reason it has to be the last field, as the body of a message is read until <EOF>.

Received messages and those which have been failed to be sent have to be processed frequently as the cleanup-routine removes one hour old messages every hour.

The naming-scheme for messages is:

  • /tmp/sms/out/: name can be chosen freely; should not contain spaces or special-chars; has to end with .sms
  • /tmp/sms/failout/: subfolder with freely chosen name; should not contain spaces or special-chars; has to contain a file named message and a file named message.log
  • /tmp/sms/in/: incoming messages are created by ISGW, messages are named in the range of 000.sms to 999.sms.

Logfiles, PIDs and Spools

The directory /apps/<appname>/var is a symlink pointing to /tmp/userapp. It should be used to store logfiles, PIDs and spools, therefore it has three subdirectories log, run and spool.

The contents of the /tmp directory is deleted every reboot cycle since it is just a ramdisk. Even though, an app should keep control over the size of its logfiles to keep as little space as possible occupied by them.


A crontab file has to be created in /usr/conf/cron. It has to be named admin (the user in which context UserApps are run). The file template/init/S00cronexample shows how entries are to be added and or removed from this file.


Services announced on the network via zeroconf (called UPnP in Microsoft Windows and Bonjour in Apple MacOS X) are browseable in the directory /tmp/beroAvahi/. Each service-type is represented by a directory which contains textfiles representing information about the host they're representing.

An example for a published _workstation._tcp service:

service=example [00:00:00:00:00:00]

If given by the publishing host, a field for additionally provided data is also given. It is named data and contains a semicolon-separated list of data.

To publish a service, an app needs to call the script /usr/local/sbin/beroAvahi-update-service as the examples given below show:

Add a service:

beroAvahi-update-service add exampleservice _exampleservice._udp 9000 "add_data1=abc;add_data2=def;"

Remove a service:

beroAvahi-update-service rem exampleservice _exampleservice._udp 9000 "add_data1=abc;add_data2=def;"

Update a service:

beroAvahi-update-service upd exampleservice _exampleservice._udp 9000 "add_data1=abc;add_data2=def;"

To use zeroconf, the service beroAvahi needs to be enabled. This can be achieved by enabling the option Zeroconf Support found under Networking preferences.

Remote Filesystems

Remote filesystem can be mounted beneath the directory-structure of an UserApp. Supported are the Common Internet Filesystem (CIFS) and the Network Filesystem (NFS). To mount a remote share, an app needs to create a file named fstab in the etc/ directory.

The format of this file is similar to the format of the regular fstab-files found on Unix, yet there are a few differences. So, the basic rule for creating entries in the fstab-file is:


To mount a CIFS share, the entry should look like:

//	/mnt/cifs	cifs	username=user,password=pwd

To mount a NFS share, the entry should look like:	/mnt/nfs	nfs	nolock

Tabulators between options are non-optional, and while the mount-options are optional, it is advisable to always set the option nolock when mounting NFS-shares. Otherwise it will take a lot of time until mounting the share is complete.

The local mountpoint has to exist (it will not be created automatically) and has to be beneath the root of the UserApp, but not the whole path has to be written. So if a remote share is to be mounted in /apps/my_app/mnt the local mountpoint has to be defined as /mnt.

A sample fstab can be found under template/setup/.

Remote shares defined here should be available before the UserApp is started as they will be mounted before the apps start-scripts are run and unmounted after the completion of the stop-scripts.

Example UserApps

There are some sample apps available. One example is the asterisk UserApp which provides additional hooks, so that other apps can make use of asterisk.


If installed, the asterisk app is located in /apps/asterisk. On startup, asterisk does not only load its own configuration files but also searches if other UserApps contain asterisk configuration files and, if they do, evaluates them.

To make use of asterisk's functionality, providing asterisk configuration in the proper place is all that is needed to be done. This way an UserApp does not need to bring its own asterisk binaries and modules.


Let's say we create a Playback app, called "playback" it will be located under:


In the apps directory we can create a subfolder:


which contains 2 files:


The sip.conf contains:


and the extensions.conf:

exten => _X.,1,Playback(tt-monkeys)

an incoming call will now receive the tt-monkeys message ;-)