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.

Tools

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

Libraries

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

http-API

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:

misc.conf
hardware.conf 
isgw.conf
isgw.sip
isgw.isdn
isgw.analog
isgw.gsm
isgw.dialplan
isgw.cpt
isgw.causes

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:

[general]
ntphost=ntp0.fau.de
timezone=-1
root-version=2
lan-iface=eth0
lan-ipaddr=192.168.0.2
lan-netmask=255.255.255.0
lan-gateway=192.168.0.1
lan-nameserver=192.168.0.1
lan-dhcp=0
msp-iface=eth1
msp-ipaddr=auto
app-image=appfs-2.2.tar.gz
app-status=running
lan-mtu=1500
use-boot-prov=
tftp-host=
tftp-url=
provisioning-option=
vlan-enable=0
vlan-id=
routing=
snmp-enabled=
cloud_enable=1
cloud_key=1234567890abcdef
vlan-prio=
userapp-enabled=
beroAvahi-enabled=
summer_winter_time=1
bnfos-ipaddr=
bnfos-mac=
bnfos-intv=
bnfos-hb-on-boot=
http_acl=0.0.0.0/0
sip_acl=0.0.0.0/0
rtp_acl=0.0.0.0/0
bfdetect_acl=0.0.0.0/0
ssh_acl=127.0.0.1/32
telnet_acl=192.168.0.0/24
admin-pass=1234567890abcdef1234567890abcdef:f2
admin-user=admin
sessions-disable=0 

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:

[lif0]
type= .. 
...
[lif1]
type= ..
...
[pcm]
type=pcm
master=..

ISGW Configuration

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

isgw.conf

It contains general settings like the logging configuration.

isgw.sip

It contains general SIP settings and the SIP accounts.

isgw.isdn

It contains the ISDN groups and general ISDN settings.

isgw.analog

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

isgw.gsm

It contains the gsm groups and general gsm settings.

isgw.dialplan

It contains the routing table (the dialplan).

isgw.causes

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

isgw.cpt

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:

  date=01/01/1970,00:00:00+00
  num=1234567890
  from=mail@mail.net
  port=1
  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.

Cron

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.

Zeroconf

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:

host=example.local
ipaddr=192.168.0.1
port=9
service=example [00:00:00:00:00:00]
type=_workstation._tcp
domain=local

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:

<remote_share><TABULATOR><local_mountpoint><TABULATOR><type><TABULATOR><mount_options><NEWLINE>


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

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


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

192.168.0.2:/path/to/share	/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.

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.

Example:

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

/apps/playback/

In the apps directory we can create a subfolder:

/apps/playback/etc/asterisk

which contains 2 files:

/apps/playback/etc/asterisk/sip.conf
/apps/playback/etc/asterisk/extensions.conf

The sip.conf contains:

[bf]
type=friend
host=localhost
context=playback

and the extensions.conf:

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

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

webti

TO BE DONE