Skip to content

freeipa asterisk

Jump to bottom
lorissantamaria edited this page Oct 31, 2012 · 10 revisions
Clone this wiki locally

freeipa-asterisk

Overview

Asterisk is an extremely flexible IP Telephony server, compatible with SIP, IAX, SCCP, H323 and other types of telephony devices. It's configuration is generally done via config files, sometimes managed by web applications like freePBX or asteriskGUI but it can also be configured via a Database or a LDAP server, a mode called Realtime Asterisk.

IP telephony in an organization usually is composed of sites, like buildings or campuses, where telephony devices like IP phones or softphones register and talk to a common registration server which in this case is an Asterisk server or a cluster of Asterisk servers in an active/active or active/passive cluster. Registration servers in different sites talk to each other thru trunks which can be SIP trunks or traditional T1 or E1 lines.

Some of the policy and configuration parameters for IP telephony in an organization is company wide (for example the requirement of encrypting communications), some other part is site specific, like the name of the registration server(s), and the rest is device specific, like the device name and its password. Some of the device specific policy may override the global configuration, because not all endpoints support all of the required features like encryption.

The most commonly used web applications for configuring Asterisk work great with a single server but fail completely at providing a global policy or even a site-specific policy. They are ideal for a very small organization with one IP telephony server but quickly become an unmanageable mess as one adds additional servers.

Enter freeIPA: "FreeIPA is an integrated security information management solution combining Linux (Fedora), 389 (formerly known as Fedora Directory Server), MIT Kerberos, NTP, DNS. It consists of a web interface and command-line administration tools". For our use-case it is a great framework for managing the LDAP object required by Realtime Asterisk.

One interesting feature of the *389 Directory Server is Class of Service (CoS) which allow some LDAP objects to have attribute values based on a template definition. The LDAP object may have its own attribute value, but if it is not present it will show the virtual attribute value as defined by the CoS templates.

For a more complete explaination of Asterisk and LDAP integration you may read this article, and the realtime chapter of the Asterisk Book.

Other useful readings are the freeIPA guide and the Extending freeIPA guide.

Objectives

Write a freeIPA plugin to manage the configuration of Realtime Asterisk. This plugin should be generally useful so it may be accepted as a Fedora and EPEL package.

Realtime Asterisk may provide for a LDAP based configuration of Asterisk, and this configuration may hold SIP peer definition, IAX peer definitions, Voicemail Mailboxes definitions, Dialplan definitions and even general config files values. In this initial version we will manage SIP and IAX peers and dialplan definitions.

In the case of SIP and IAX peers the administrator will be able to define a global policy, which could be overridden with per site and per device directives.

The plugin will include also some sample Asterisk configuration files to help the administrator to quickly integrate Asterisk and freeIPA.

Schema

We will use a slightly modified version of the standard Asterisk 1.8 schema. We added an asteriskSiteDefaults objectClass, which may hold most of the attribute values of the common Asterisk LDAP objects: Asterisk LDAP schema

DIT

Under the base directory object the plugin will create a cn=asterisk container, and under that the containers for storing the different Asterisk configuration objects:

dn: cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: asterisk

dn: cn=sip,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: sip

dn: cn=iax,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: iax

dn: cn=dialplan,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: dialplan

dn: cn=vm,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: vm

dn: cn=config,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: config

dn: cn=sites,cn=asterisk,$SUFFIX
objectClass: top
objectClass: nsContainer
cn: sites

CoS Templates entries

The plugin will create a CoS template for the global policy with some useful default values:

dn: cn=global_config,cn=asterisk,$SUFFIX
objectClass: top
objectClass: asteriskSiteDefaults
objectClass: cosTemplate
cn: global_config
cosPriority: 999
astAccountCanReinvite: yes
astAccountDTMFMode: info
astAccountNAT: no
astAccountQualify: yes
astAccountTransport: tcp,udp
astAccountAllowedCodec: alaw,ulaw,gsm
astAccountType: friend
astAccountVideoSupport: yes
astAccountHost: dynamic
astAccountContext: default

The plugin will also create an initial site which will also serve as a template for all SIP and IAX devices belonging to the site:

dn: cn=default_site,cn=sites,cn=asterisk,$SUFFIX
objectClass: top
objectClass: organizationalUnit
objectClass: asteriskSiteDefaults
objectClass: cosTemplate
cosPriority: 10
ou: default_site
cn: default_site
astAccountRegistrationServer: asterisk.acme.com

The only required attribute for the site will be astAccountRegistrationServer which will indicate the address of the registration server for the site. Note that a site may have multiple registration server in various forms of load balancing or failover configuration all sharing the same name with the use of DNS SRV records.

Please note that the site template has a lower coSPriority value, thus ensuring that the values defined at the site level will override the global values.

CoS definition entries

The plugin will create the CoS definitions required to assign the CoS template values for the LDAP objects. Here are shown CoS definitions for SIP devices, similar ones are defined por IAX devices.

For the global policy we use a Pointer CoS definition:

dn: cn=globalSipCoS,cn=sip,cn=asterisk,$SUFFIX
objectclass: top 
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=global_config,cn=asterisk,$SUFFIX
cosAttribute: astAccountAllowOverlap
cosAttribute: astAccountCallLimit
cosAttribute: astAccountCanReinvite
cosAttribute: astAccountDTMFMode
cosAttribute: astAccountDeny
cosAttribute: astAccountDisallowedCodec
cosAttribute: astAccountAllowedCodec
cosAttribute: astAccountAMAFlags
cosAttribute: astAccountFromDomain
cosAttribute: astAccountIgnoreSDPVersion
cosAttribute: astAccountLanguage
cosAttribute: astAccountMusicOnHold
cosAttribute: astAccountNAT
cosAttribute: astAccountPermit
cosAttribute: astAccountQualify
cosAttribute: astAccountRTPHoldTimeout
cosAttribute: astAccountRTPTimeout
cosAttribute: astAccountTransport
cosAttribute: astAccountType
cosAttribute: astAccountVideoSupport
cosAttribute: astVoicemailOptions
cosAttribute: astVoicemailTimestamp
cosAttribute: astVoicemailContext
cosAttribute: astAccountEncryption
cosAttribute: astAccountHost
cosAttribute: astAccountContext
cosAttribute: astAccountRegistrationContext
cosAttribute: astAccountSubscribeContext
cosAttribute: astAccountRegistrationServer

For the site policy we will use a Classic CoS definition, using the ou attribute as the cosSpecifier:

dn: cn=siteSipCoS,cn=sip,cn=asterisk,$SUFFIX
objectclass: top 
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=sites,cn=asterisk,$SUFFIX
cosSpecifier: ou
cosAttribute: astAccountAllowOverlap
cosAttribute: astAccountAMAFlags
cosAttribute: astAccountCallLimit
cosAttribute: astAccountCanReinvite
cosAttribute: astAccountDTMFMode
cosAttribute: astAccountDeny
cosAttribute: astAccountDisallowedCodec
cosAttribute: astAccountAllowedCodec
cosAttribute: astAccountFromDomain
cosAttribute: astAccountIgnoreSDPVersion
cosAttribute: astAccountLanguage
cosAttribute: astAccountMusicOnHold
cosAttribute: astAccountNAT
cosAttribute: astAccountPermit
cosAttribute: astAccountQualify
cosAttribute: astAccountRTPHoldTimeout
cosAttribute: astAccountRTPTimeout
cosAttribute: astAccountTransport
cosAttribute: astAccountType
cosAttribute: astAccountVideoSupport
cosAttribute: astVoicemailOptions
cosAttribute: astVoicemailTimestamp
cosAttribute: astVoicemailContext
cosAttribute: astAccountEncryption
cosAttribute: astAccountHost
cosAttribute: astAccountContext
cosAttribute: astAccountRegistrationContext
cosAttribute: astAccountSubscribeContext
cosAttribute: astAccountRegistrationServer

Managing SIP users with LDAP commands

To add a SIP user we can use the following LDIF:

dn: cn=101,cn=sip,cn=asterisk,$SUFFIX
objectClass: top
objectClass: asteriskSIPUser
objectClass: ieee802device
objectClass: bootableDevice
cn: 101
description: Loris
astAccountCallerID: Loris <101>
astAccountSecret: o86fyFGJF
astAccountContext: default
ou: default_site

Thanks to the CoS templates, on a LDAP search, which can be done with the filter (&(cn=101)(objectClass=asteriskSIPUser)(ou=default_site)) the object will show the attribute values inherited from the global and site policies:

dn: cn=101,cn=sip,cn=asterisk,dc=lgs,dc=com,dc=ve
objectClass: top
objectClass: asteriskSIPUser
objectClass: ieee802device
objectClass: bootableDevice
objectClass: asteriskExtension
cn: 101
description: Loris
astAccountCallerID: Loris <101>
astAccountSecret: o86fyFGJF
astAccountContext: default
ou: default_site
astAccountCanReinvite: yes
astAccountDTMFMode: info
astAccountNAT: no
astAccountQualify: yes
astAccountRegistrationServer: asterisk.acme.com
astAccountTransport: tcp,udp
astAccountType: friend
astAccountVideoSupport: yes
astAccountAllowedCodec: alaw,ulaw,gsm
astAccountHost: dynamic

Managing SIP users with IPA commands

To modify the global policy:

ipa astconfig-mod --dtmfmode=rfc2833

To add a site:

ipa astsite-add headquarter --reg_server=sip.acme.com

To modify a per-site policy:

ipa astsite-mod headquarter --dtmfmode=info

To add a sip device:

ipa astsip-add 101 --site=headquarter --description=Loris --secret=87fg3y

To modify a sip device parameter:

ipa astsip-mod 101 --nat=yes

About the Endpoint Manager

In a IP telephony environment the endpoints (IP phones and softphones) are tipically configured in a centralized fashion via a set of configuration files distributed via TFTP or HTTP. The program that generates those configuration files is called the Endpoint Manager. While not part of the freeipa-asterisk plugin the endpoint manager needs to obtain the data necessary to create endpoint configuration files from the LDAP directory, so it is important that we store all needed information.

The endpoint manager needs at least the following information:

  • The endpoint username (phone number)
  • The endpoint password
  • The name of the registration server
  • The endpoint MAC address
  • The endpoint brand
  • The endpoint model

The attribute to use in the device's SIP or IAX LDAP object are cn, astAccountSecret, astAccountRegistrationServer and macAddress. For brand and model we could use o and serialNumber.

Dialplan

The Dialplan is the set of instructions that are executed by Asterisk every time a user dials a number. Like any program it is expressed by text instructions and it is better suited for distribution via a system like puppet. However some parts of it are very repetitive and can be stored in the LDAP server. If an organization has several thousands SIP devices most of the dialplan will consist in executing the same pattern for every one of them.

A dialplan instruction is composed of the following parts:

  • A context, basically the name of the set of instructions it belongs to
  • An extension, which is the number dialed
  • A priority, that indicates the order of execution of multiple instructions for the same extension
  • An application to be executed
  • The application parameters

In our multi-site Asterisk configuration architecture we are adding the name of the site this instruction belongs to.

Adding a dialplan instruction with LDAP commands

dn: cn=2001-1,cn=extensions,cn=asterisk,$SUFFIX
cn: 2001-1
objectClass: top
objectClass: asteriskExtension
objectClass: applicationProcess
ou: default_site
astContext: users
astExtension: 2001
astPriority: 1
astApplication: Dial
astApplicationData: SIP/2001,20

Managing dialplan with IPA commands

Adding a dialplan instruction:

ipa astextension-add name=2001-1 --site=default_site \\
    --extension=2001 --priority=1 \\
    --application=Dial --data="SIP/2001,20"

Deleting a dialplan instruction:

ipa astextension-del 2001-1

Finding all instructions for a specific extension:

ipa astextension-find --extension=2001  --site=default_site

Automatically create dialplan instructions

While most of the dialplan is very organization specific, there is something that is common for most organizations: you need to add some instruction for every SIP or IAX device added. freeipa-asterisk can optionally add these instructions based on an administrator supplied template.

Enable per-site automatic extension creation

ipa astsite-mod headquarter --auto-extension-creation=TRUE

Define default extension values

ipa astsite-mod headquarter \\
    --auto-extension-params="ext-local,1,Dial,$TECH/$NAME,20" \\
    --auto-extension-params="ext-local,2,Hangup," \\
    --auto-extension-params="ext-local,hint,$TECH/$NAME,"

In the --auto-extension-params option the fields are separated by commas. The first field is the context in which the extension will be created, the second is the extension priority, the third is the application to executed and the rest of the field are the application parameters. There MUST be at least four fields even tough the last one may be blank

The $NAME variable will be substituted by the corresponding "user" name, and the $TECH variable will be substituted by the user's tech.

NOTE: deleting a user won't remove the automatically created extensions.