UserApp API Reference
- 1 appfs APIs
- 2 Example UserApps
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:
- busybox, set of different unix commands and scripting environment, http://busybox.net/
- lighttpd, httpd server, http://www.lighttpd.net/
- php5, server side scripting language, http://www.php.net/
- sqlite2, sql database management system, http://www.sqlite.org/
- ssh, remote access server/client, http://www.openssh.com/
- beroAvahi, zeroconf daemon to publish and browse services on the network
- net-snmp, simple network management protocol daemon (http://net-snmp.sourceforge.net/)
Several libraries to be used by UserApps are provided by beroFix:
- openssl, SSL/TLS library and tools, http://www.openssl.org/
- curl, http-client library an tools, http://curl.haxx.se/
- avahi, zeroconf library and tools, http://www.avahi.org/
- net-snmp, SNMP library and tools, http://net-snmp.sourceforge.net/
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.
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
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 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:
date=01/01/1970,00:00:00+00 num=1234567890 email@example.com 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.
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:
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 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:
//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
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.
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:
[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 ;-)
TO BE DONE