# &adminguide;

## Overview

The time needed when writing a new OpenSIPS module unfortunately is quite high, while the options provided by the configuration file are limited to the features implemented in the modules.

With this Perl module, you can easily implement your own OpenSIPS extensions in Perl. This allows for simple access to the full world of CPAN modules. SIP URI rewriting could be implemented based on regular expressions; accessing arbitrary data backends, e.g. LDAP or Berkeley DB files, is now extremely simple.

## Installing the module

This Perl module is loaded in opensips.cfg (just like all the other modules) with loadmodule("/path/to/perl.so");.

For the Perl module to compile, you need a reasonably recent version of perl (tested with 5.8.8) linked dynamically. It is strongly advised to use a threaded version. The default binary packages from your favorite Linux distribution should work fine.

Cross compilation is supported by the Makefile. You need to set the environment variables PERLLDOPTS, PERLCCOPTS and TYPEMAP to values similar to the output of

    PERLLDOPTS: perl -MExtUtils::Embed -e ldopts
    PERLCCOPTS: perl -MExtUtils::Embed -e ccopts
    TYPEMAP:    echo "`perl -MConfig -e 'print $Config{installprivlib}'`/ExtUtils/typemap"

The exact position of your (precompiled!) perl libraries depends on the setup of your environment.

## Using the module

The Perl module has two interfaces: The perl side, and the OpenSIPS side. Once a Perl function is defined and loaded via the module parameters (see below), it may be called in OpenSIPS's configuration at an arbitary point. E.g., you could write a function "ldap_alias" in Perl, and then execute

    ...
    if (perl_exec("ldap_alias")) {
    	...
    }
    ...

just as you would have done with the current alias_db module.

The functions you can use are listed in the "Exported Functions" section below.

On the Perl side, there are a number of functions that let you read and modify the current SIP message, such as the RURI or the message flags. An introduction to the Perl interface and the full reference documentation can be found below.

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- The "sl" module is needed for sending replies uppon fatal errors. All other modules can be accessed from the Perl module, though.

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; with this module loaded:

- Perl 5.8.x or later

Additionally, a number of perl modules should be installed. The OpenSIPS::LDAPUtils package relies on Net::LDAP to be installed. One of the sample scripts needs IPC::Shareable

This module has been developed and tested with Perl 5.8.8, but should work with any 5.8.x release. Compilation is possible with 5.6.x, but its behavior is unsupported. Earlier versions do not work.

On current Debian systems, at least the following packages should be installed:

- perl

- perl-base

- perl-modules

- libperl5.8

- libperl-dev

- libnet-ldap-perl

- libipc-shareable-perl

It was reported that other Debian-style distributions (such as Ubuntu) need the same packages.

On SuSE systems, at least the following packages should be installed:

- perl

- perl-ldap

- IPC::Shareable perl module from CPAN

Although SuSE delivers a lot of perl modules, others may have to be fetched from CPAN. Consider using the program cpan2rpm - which, in turn, is available on CPAN. It creates RPM files from CPAN.

## Exported Parameters

### `filename` (string)

This is the file name of your script. This may be set once only, but it may include an arbitary number of functions and use as many Perl module as necessary.

May not be empty!

#### Set `filename` parameter

    ...
    modparam("perl", "filename", "/home/john/opensips/myperl.pl")
    ...

### `modpath` (string)

The path to the Perl modules included (OpenSIPS.pm et.al). It is not absolutely crucial to set this path, as you may install the Modules in Perl's standard path, or update the %INC variable from within your script. Using this module parameter is the standard behavior, though.

#### Set `modpath` parameter

    ...
    modparam("perl", "modpath", "/usr/local/lib/opensips/perl/")
    ...

## Exported Functions

### `perl_exec_simple(func, [param])`

Calls a perl function without passing it the current SIP message. May be used for very simple simple requests that do not have to fiddle with the message themselves, but rather return information values about the environment.

The first parameter is the function to be called. An arbitrary string may optionally be passed as a parameter.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE.

#### `perl_exec_simple()` usage

    ...
    if (method=="INVITE") {
    	perl_exec_simple("dosomething", "on invite messages");
    };
    ...

### `perl_exec(func, [param])`

Calls a perl function with passing it the current SIP message. The SIP message is reflected by a Perl module that gives you access to the information in the current SIP message (OpenSIPS::Message).

The first parameter is the function to be called. An arbitrary string may be passed as a parameter.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE.

#### `perl_exec()` usage

    ...
    if (perl_exec("ldapalias")) {
    	...
    };
    ...