This material is work-in-progress ...

Do not follow instructions here until this notice is removed.
(Last edited by Zcrayfish on 20 Dec 2021.)

Overview

This page describes how to install a basic provisioning server for SIP devices based upon Postgresql and the ACF web interface. It is built and tested on Alpine Linux 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4.

This solution is implemented by the acf-provisioning package. acf-provisioning is designed as a generic provisioning service which provides one web interface (ACF) to manage and configure devices and a second web interface to serve configuration files. The design is data-driven by database entries that define classes-of-service and parameters for each device. Configuration files are generated dynamically using the database parameter values and templates. Support for a variety of SIP clients is included by default.

Setup Procedure

1. Configure the machine

Install and configure a basic Alpine Linux server with the ACF web interface.

setup-alpine
setup-acf

2. Install packages

Here are the basic packages for the provisioning functionality:

apk add acf-provisioning acf-postgresql acf-lighttpd

In addition, you can add firmware packages for the SIP devices you want to support (depending on the version of Alpine Linux, some packages may not be available or may be available from the community repository):

apk add acf-provisioning-cisco acf-provisioning-linksys acf-provisioning-polycom acf-provisioning-snom acf-provisioning-algo acf-provisioning-cyberdata

Note: If you are running-from-RAM, it is recommended to mount /var/ to a hard disk to prevent data loss. If you do so, you should fetch the firmware packages, rather than install them. This way, the firmware will not take up RAM for storage. You can use the following command: apk fetch --quiet --stdout acf-provisioning-polycom | tar -C / -zvx

3. Configure Lighttpd

Lighttpd is used to provide the HTTP provisioning interface for the SIP devices. The provisioning package contains a sample configuration that can be used for lighttpd:

mv /etc/lighttpd/lighttpd.conf /etc/lighttpd/lighttpd.conf.orig
ln -s /etc/provisioning/lighttpd.sample.conf /etc/lighttpd/lighttpd.conf

Modify mod_cgi.conf to treat CGI scripts as shell scripts, rather than perl:

sed -i 's~/usr/bin/perl"$~"~' /etc/lighttpd/mod_cgi.conf

Start the server:

/etc/init.d/lighttpd start

4. Start Postgresql

The device parameter details are stored in a Postgresql database. We can use the default configuration, so we just start the service:

/etc/init.d/postgresql start

5. Point your SIP device to the new server for provisioning

Instructions for various manufacturers are included on separate pages:

ACF Web interface

You can now browse to https://IPADDRESS to access the web interface. To log in for administration, use the root user and the system root password (this is the default configuration set up by setup-acf).

Create a Device

acf-provisioning is organized by device, not by SIP URI or extension. Thus, each physical or logical device, such as a phone or soft phone, should have its own device in the provisioning system.

If you have properly configured your SIP device to connect to the network and to the provisioning server, it will have already attempted to make contact with the provisioning server. If that is the case, you can create the device by finding the corresponding request and clicking on Create:

Applications: Provisioning > Requests > Device Request: Create

This will create a device with the proper device class and MAC address and redirect you to modify the device classes-of-service.

Otherwise, you can create a device from scratch using the Create tab:

Applications: Provisioning > Create

Finally, there is an option on newer systems to create devices in bulk using the Bulk Create tab:

Applications: Provisioning > Bulk Create

Classes of Service

Provisioning Classes are used to define groups of parameters and parameter defaults to account for different device types and classes of service. The structure of classes, groups, and parameters are defined in the database, making it flexible and extensible. Class Groups define the different classes of service that may be configured for each device. The Classes define the options for each Class Group and which Parameter Groups would apply to each option. The Parameter Groups then define a group of parameters and corresponding defaults. Finally, the Parameters define all of the details of each parameter, such as type, label, description, global default, and validation.

By default, the system defines two Class Groups - Device Model and Services. The Device Model class group contains several Classes corresponding to a variety of supported SIP devices. Obviously, different device types would support different sets of parameters. The Services class group contains classes for Office/Residential/Public/Hotline Phones. These classes mostly are used to define different default values for features. The existing Class Groups, Classes, Parameter Groups, and Parameters can all be modified through the ACF web interface, or entirely new entries can be created, to customize the system.