PI_HTTP module

Admin Guide

Overview

This module provides an HTTP provisioning interface for OpenSIPS. It is using the OpenSIPS’s internal database API to provide a simple way of manipulating records inside OpenSIPS’s tables. The module offers:

• ability to connect to multiple/different databases through OpenSIPS’s db API; (all OpenSIPS’s databases are supported);
• ability to perform data input validation through OpenSIPS API;
• ability to reconfigure the interface layout on the fly by reloading the config from the xml framework via mi command interface.

Note

When provisioning tables using db_text, any change made to a db_text table will not be reflected on the actual text file. In order to force a write out to the disk of the cached tables, the db_text mi command dbt_dump must be used.

Usage

The layout of the provisionning interface is controlled via an external xml file (see the framework parameter). An example of a framework xml file is provided inside the examples directory of the pi_http module. A simple framework file can be generated by the opensipsdbctl command:

opensipsdbctl pframework create

The generated framework will be saved inside OpenSIPS’s config directory as pi_framework_sample. The list of configurable tables will be based on the STANDARD_MODULES and EXTRA_MODULES vars from opensipsctlrc file.

Framework

The xml framework file is organized in three distinctive blocks:

• database connection definition block
• table definition block
• command definition block

Database connection definition block

Each connection to a particular database must be defined here with a unique database connection id. The connection parameters are defined following the db_url param pattern for all OpenSIPS modules that are using a database.

Supported databases:

• berkeley
• flatstore
• http
• mysql
• oracle
• postgres
• text
• unixodbc
• virtual

Table definition block

Each table managed through the OpenSIPS provisioning interface must be defined here with a unique table id. For each table, the database connection id must be specified. Each table must list all columns that will be managed by the OpenSIPS provisioning interface. Each column must have a unique field name and a type. Each column may have a validation tag for validating input data.

Supported column types:

• DB_INT

• DB_BIGINT

• DB_DOUBLE

• DB_STRING

• DB_STR

• DB_DATETIME

  Note

  Input field must be provided in ‘YEAR-MM-DD HH:MM:SS’ format.

• DB_BLOB

• DB_BITMAP

Supported validation methods:

• IPV4 - represents an IPv4 address
• URI - represents a SIP URI
• URI_IPV4HOST - represents a SIP URI with an IPV4 as a host
• P_HOST_PORT - represents [proto:]host[:port]
• P_IPV4_PORT - represents [proto:]IPv4[:port]

Command definition block

Multiple provisioning commands can be grouped together. Each group can have multiple commands. Each command definition in a group must have the table id of the table that is operating on along with the command type to be performed.

The command type can have up to three type of column parameters:

• clause columns
• query columns
• order by columns

Each column parameter must define the name(s) of the column(s) (must match a field name in the description table identified by the table id). A column can accept a list of imposed values. Each imposed value will have an id that will be displayed on the web interface and the actual value that will be used for db operations. Clause columns must define operators. Here’s the list of supported operators: ’<’, ’>’, ’=’, ’<=’, ’>=’, ’!=’.

Supported database command types:

• DB_QUERY - performs an SQL query and supports three type of columns:

  • clause: 0 or more columns
  • query: 1 column
  • order: 0 or 1 column

• DB_INSERT - performs an SQL insert and supports one type of column:

  • query: 1 or more columns

• DB_DELETE - performs an SQL delete and supports one type of column:

  • clause: 1 or more columns

• DB_UPDATE - performs an SQL update and supports two type of columns:

  • clause: 0 or more columns
  • query: 1 or more columns

• DB_REPLACE - performs an SQL replace and supports one type of column:

  • query: 1 or more columns

Please note that some databases have a restricted set of database command types.

To-do

Features to be added in the future:

• full subscriber provisionning with automatic ha1/ha1b fields.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• httpd module.

External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

• libxml2

Exported Parameters

pi_http_root(string)

Specifies the root path for pi HTTP requests. The link to the OpenSIPS provisioning web interface must be constructed using the following patern: http://[opensips_IP]:[opensips_mi_port]/[pi_http_root]

The default value is “pi”.

Set pi_http_root parameter

...
modparam("pi_http", "pi_http_root", "opensips_pi")
...

framework(string)

Specifies the full path for xml framework descriptor.

There’s no default value. This parameter is mandatory.

Set framework parameter

...
modparam("pi_http", "framework", "/usr/local/etc/opensips/pi_framework.xml")
...

pi_http_method(integrer)

Specifies the HTTP request method to be used:

• 0 - use GET HTTP request
• 1 - use POST HTTP request

The default value is 0.

Set pi_http_method parameter

...
modparam("pi_http", "pi_http_method", 1)
...

Exported MI Functions

pi_reload_tbls_and_cmds

Reloads the layout of the provisioning interface from the framework file.

Name: pi_reload_tbls_and_cmds

Parameters: none

MI FIFO Command Format:

:pi_reload_tbls_and_cmds:_reply_fifo_file_
_empty_line_

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Ovidiu Sas (@ovidiusas)	66	27	4060	188
2.	Stefan Darius (@dariusstefan)	11	5	376	75
3.	Vlad Paiu (@vladpaiu)	4	2	5	2
4.	Razvan Crainea (@razvancrainea)	3	1	2	2
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	3	1	1	1

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Jun 2026 - Jun 2026
3.	Ovidiu Sas (@ovidiusas)	Oct 2012 - Mar 2014
4.	Vlad Paiu (@vladpaiu)	May 2013 - May 2013
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	Jan 2013 - Jan 2013

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Ovidiu Sas (@ovidiusas), Bogdan-Andrei Iancu (@bogdan-iancu).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0