---
title: "pi_http Module"
description: "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 AP..."
---

## 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 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 opensips-cli command:


```c
opensips-cli 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 "database_modules" setting of opensips-cli.cfg if present,
		otherwise a default set of configurable tables will be used.


### 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".*


```c title="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.*


```c title="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.*


```c title="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:


```c
opensips-cli -x mi pi_reload_tbls_and_cmds
		
```
<!-- CONTRIBUTORS -->

### License

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