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 provisioning interface is controlled via the global pi_framework core parameter. The framework is parsed and managed by the core, independently of this HTTP transport. An example of a framework xml file is provided inside the examples directory of the pi_http module. Use the committed framework files under scripts/pi/ as a starting point and adapt the XML to the modules and database schema in use. The fragment files and final framework can be regenerated with:

make -C db/schema pi_framework

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. The optional db_url_id element selects a connection from the database connection block. If omitted, the framework uses the module’s db_url parameter, or the global db_default_url when the module has no db_url. Use db_url_id for modules whose connector is exposed through a different parameter or for an explicit per-table override. 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 provisioning with automatic ha1/ha1b fields.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• httpd module.

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 pattern: 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")
...

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

The provisioning MI commands are core commands and are available regardless of the transport:

• pi_list lists the modules and commands from the loaded framework.
• pi_reload reloads the framework and reconnects its database connectors.

Parameters: none

opensips-cli -x mi pi_list
opensips-cli -x mi pi_reload

Contributors

By Commit Statistics

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

#	Name	DevScore	Commits	Lines++	Lines—
1.	Ovidiu Sas (@ovidiusas)	74	31	4431	248
2.	Razvan Crainea (@razvancrainea)	69	22	289	2607
3.	Liviu Chircu (@liviuchircu)	15	13	42	59
4.	Stefan Darius (@dariusstefan)	11	5	377	74
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	9	7	46	8
6.	Vlad Patrascu (@rvlad-patrascu)	6	4	22	20
7.	Maksym Sobolyev (@sobomax)	5	3	8	5
8.	Ionut Ionita (@ionutrazvanionita)	4	2	54	29
9.	Vlad Paiu (@vladpaiu)	4	2	5	2
10.	Zero King (@l2dy)	3	1	2	2

All remaining contributors: Ken Rice, Peter Lemenkov (@lemenkov).

(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.	Razvan Crainea (@razvancrainea)	Aug 2015 - Aug 2026
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	Jan 2013 - Jul 2026
3.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
4.	Ken Rice	Sep 2025 - Sep 2025
5.	Liviu Chircu (@liviuchircu)	Mar 2014 - Mar 2024
6.	Maksym Sobolyev (@sobomax)	Oct 2022 - Feb 2023
7.	Zero King (@l2dy)	Mar 2020 - Mar 2020
8.	Vlad Patrascu (@rvlad-patrascu)	May 2017 - Jan 2019
9.	Peter Lemenkov (@lemenkov)	Jun 2018 - Jun 2018
10.	Ionut Ionita (@ionutrazvanionita)	Nov 2015 - Jan 2017

All remaining contributors: Ovidiu Sas (@ovidiusas), Vlad Paiu (@vladpaiu).

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

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu), Peter Lemenkov (@lemenkov), Vlad Patrascu (@rvlad-patrascu), 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