This section describes how to install, enable and use an UserApp. You might also want to read the baf README which can also be found in the baf-repository.

Contents

• 1 Install an UserApp

• 2 Enable UserApps

• 3 First Steps

• 4 Partitions on the beroFix

• 5 beroFix OS System Hooks

  • 5.1 Init Hook

  • 5.2 GUI Hook

  • 5.3 API Reference

• 6 I need Application XY running on berofix

Install an UserApp

An UserApp can either installed through the beroGUI or the beroCloud. To install it through the GUI just open the Firmware Update page and install it like a regular beroFix AppFS.

Enable UserApps

UserApps are not enabled by default, even though they can be installed, they won't be useable until they've been enabled. To enable UserApp support, the option Userappfs Support has to be enabled on the Provisioning page.

After it is enabled a new configuration option appears which is named reset admin password. This can be used to set the admin password to "admin". After that you can login to your beroFix using ssh. The login-credentials are admin:admin.

Advise: A more sofisticated interface to configure UserApps can be found at <ip_of_your_berofix>/userapp/. Several settings regarding UserAppFS, like the password for the user admin, can be changed on this page.

First Steps

If logging in using SSH, a simple directory-structure can be found inside the home-directory /home/admin.

While the directories setup and www are not important here, the directory apps contains the installed apps. Multiple applications can be installed side-by-side (up to eight), so a typical listing of the directory will look like:

There is a symlink pointing from /apps to /home/admin/apps to keep paths short.

Partitions on the beroFix

When the command mount is entered, a list of all mounted partitions is shown. The most important ones for the UserApps are:

Every app is stored on the partition /home/admin/ which is mounted read-only to avoid potential corruptness of the filesystem, as writing to the flash is slow and a possible loss of power during a write is likely to cause it.

Configuration files are to be stored in the subdirectory etc/ of each UserApp, which is actually a symlink pointing to:

NOTE: Make sure to always use the command sync after you've written something to /usr/conf/.

Logfile are to be written to the subdirectory var/log/ of your UserApp. As the var/ directory is actually a symlink to /tmp/userapp/, logfiles will be stored in the RAM. If logfiles are to be kept, they should be stored on a remote server.

beroFix OS System Hooks

beroFix OS provides system hooks to let UserApps start services on system start-up, provide an own GUI and mount remote shares.

Init Hook

The system initialisation process of beroFix works in three stages. At first the init-process starts the basic services provided by the RootFS. If this is finished, the services provided by the AppFS are started. And in the end the start-script for the UserApps searches through installed apps and starts services defined here.

1. init

   1. RootFS Services

   2. AppFS start-script

      • AppFS Services

   3. UserAppFS start-script

      • UserApp_1 Services

      • ...

      • UserApp_n Services

Init-scripts for UserApps are called from an init-script called S91userapp under the context of the user admin in alphabetical order. These scripts are called with parameter start on startup, after an UserApp has been installed or when UserApps are to be enabled. They are called with parameter stop on shutdown, before an UserApp is installed or when UserApps are to be disabled.

The init-scripts for UserApps are to be written in the same style regular Unix/Linux init-scripts are written in. They should be able to be called with the parameters start, stop and restart to ensure that UserApps react properly to specific events. Example init-scripts can be found in template/init/S00example and template/init/S00cronexample. These scripts can be used as draft, but should be renamed as they are not packed by baf.

An UserApp can have several start-scripts, they will be called in alphabetical order on start-up and in reversed order on shutdown.

Make sure the stop-routine of your script enforces the ending of the process started by the start-routine to avoid unwanted parallel running instances of services provided by your UserApp.

GUI Hook

UserApps can provide their own web-interface. It is accessable through the APPS menu and by opening the URL http://<ip_of_berofix>/userapp/<app_name>/ in a browser. The root-directory of an apps web-interface is /apps/<app_name>/www/. If this directory contains a file named index.php, it will be displayed.

A basic example of an index.php can be found in template/www/. It also shows how to use beroFix' session-management, so that the configuration-page of an app is protected by the password used for accessing beroGUI.

TIP: creating a php-script with the code shown below will display version and capabilities of the php-variant used when called in a browser:

NOTE: If a capability needed for an UserApp is not available on beroFix, it's most likely possible to add it through php-modules. Feel free to contact us if a specific module is required.

API Reference

The berofix Firmware has several features that can be used by an userapp, these features and how they can be used by an userapp are explained here:

UserApp API Reference

I need Application XY running on berofix

If you have special need for an application that should run on berofix, for example: freeswitch, yate, tftpd or others, don't hesitate to contact us. It is likely that we can offer you a cross-compiled binary that runs on berofix.