Red Hat Magazine

JBoss Drools how-to: Tuning Guvnor, part 2

Jaroslaw Kijanowski — Thu, 14 Aug 2008 22:34:10 +0000

Guvnor is the business rules management system in Drools 5. When you deploy it out of the box, you get an unsecured web application that stores data in Jackrabbit’s embedded Derby database.

This two-part article explains how to tune Guvnor deployed on JBoss Application Server 4.2.3. (If you missed the first half of the series, catch up in our archives.)This means that we will use the container’s configuration files and security infrastructure. This installment covers enabling password validation based on an OpenLDAP server, moving from the default data repository, and enabling SSL for better security.

Use OpenLDAP as a user repository
Use MySQL as a data repository
Enable SSL
How to use a secured Guvnor package
Summary

Use OpenLDAP as a user repository

There are several reasons why you would want to use an LDAP directory instead of a clear text file — security, provisioning, and reuseability are just a few. First of all, we need a directory. OpenLDAP will do for this example. Download and extract the bits from the OpenLDAP home page. In this example, I’ve used openldap-2.3.39.tgz. Next, go to the directory where you’ve extracted the installation files and perform following steps:

$ mkdir -p /data/openldap-2.3.39
$ ./configure --prefix=/data/openldap-2.3.39
$ make depend
$ make
$ make install

For more detailed instructions, look at the INSTALL file or the OpenLDAP Administrator’s Guide.

The next instructions will configure our directory and create a tree which looks like this:

Fig 2.1 tree

We need to initialize the LDAP server and provide data like the root suffix, directory manager, and password. We also want to enable SSL like so:

$ mkdir /data/openldap-2.3.39/ssl
$ openssl req -newkey rsa:1024 -x509 -nodes -out /data/openldap-2.3.39/ssl/server.pem -keyout /data/openldap-2.3.39/ssl/server.pem -days 365
Generating a 1024 bit RSA private key
....++++++
................++++++
writing new private key to 'server.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:EU
State or Province Name (full name) [Berkshire]:Mazovia
Locality Name (eg, city) [Newbury]:Warsaw
Organization Name (eg, company) [My Company Ltd]:Kijanowski
Organizational Unit Name (eg, section) []:Guvnor
Common Name (eg, your name or your server's hostname) []:localhost
Email Address []:a@a.a

Since this is a self-signed certificate we will need to add it to the client’s (JBoss AS) truststore.

$ openssl
OpenSSL> x509 -inform PEM -outform DER -in /data/openldap-2.3.39/ssl/server.pem -out /data/openldap-2.3.39/ssl/server.der
OpenSSL> exit

$ keytool -import -file /data/openldap-2.3.39/ssl/server.der -keystore $JBOSS_SERVER/conf/ldap.truststore

Enter keystore password:  qwerty
Owner: EMAILADDRESS=a@a.a, CN=localhost, OU=Guvnor, O=Kijanowski, L=Warsaw, ST=Mazovia, C=EU
Issuer: EMAILADDRESS=a@a.a, CN=localhost, OU=Guvnor, O=Kijanowski, L=Warsaw, ST=Mazovia, C=EU
Serial number: d8537a079c5eed59
Valid from: Wed Jul 16 18:35:50 CEST 2008 until: Thu Jul 16 18:35:50 CEST 2009
Certificate fingerprints:
         MD5:  25:C5:88:7B:D4:88:02:46:F1:EF:0D:6B:D6:EE:1F:A7
         SHA1: 57:B8:F4:25:77:F0:12:BD:B2:2E:DD:7D:CE:09:D2:D4:96:56:BC:26
Trust this certificate? [no]:  yes
Certificate was added to keystore

To enable the new truststore, edit $JBOSS_SERVER/deploy/properties-service.xml and add following lines:


    javax.net.ssl.trustStore=/data/jboss-4.2.3.GA/server//conf/ldap.truststore
    javax.net.ssl.trustStorePassword=qwerty

Now edit the file /data/openldap-2.3.39/etc/openldap/slapd.conf:

include         /data/openldap-2.3.39/etc/openldap/schema/core.schema
include         /data/openldap-2.3.39/etc/openldap/schema/cosine.schema
include         /data/openldap-2.3.39/etc/openldap/schema/inetorgperson.schema

pidfile         /data/openldap-2.3.39/var/run/slapd.pid
argsfile        /data/openldap-2.3.39/var/run/slapd.args

database        bdb
suffix          "dc=kijanowski,dc=eu"
rootdn          "cn=DirManager,dc=kijanowski,dc=eu"
rootpw          secret
directory       /data/openldap-2.3.39/var/openldap-data
index   objectClass     eq

TLSCipherSuite HIGH:MEDIUM:-SSLv2
TLSCACertificateFile /data/openldap-2.3.39/ssl/server.pem
TLSCertificateFile /data/openldap-2.3.39/ssl/server.pem
TLSCertificateKeyFile /data/openldap-2.3.39/ssl/server.pem
TLSVerifyClient never

The rootpw attribute should be changed from ’secret’ to:

$ /data/openldap-2.3.39/sbin/slappasswd -s admin123

where ‘admin123′ is the new directory manager’s password. For better performance, you can create a config file for the backend database or copy the sample configuration file like so:

$ cp /data/openldap-2.3.39/var/openldap-data/DB_CONFIG.example /data/openldap-2.3.39/var/openldap-data/DB_CONFIG

To start the server with a customized listener, run:

$ /data/openldap-2.3.39/libexec/slapd -h ldaps://localhost:16636

You can make sure your LDAP server is up and running (listening) by running:

$ netstat -an|grep 16636
tcp        0      0 127.0.0.1:16636             0.0.0.0:*                   LISTEN

To create tree like the one shown above, we need to add the following myorg.ldif file:

dn: dc=kijanowski,dc=eu
objectclass: top
objectclass: dcObject
objectclass: organization
dc: kijanowski
o: kijanowski

dn: o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: organization
o: guvnor

dn: ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: organizationalUnit
ou: People

dn: uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: uidObject
objectclass: person
objectClass: inetOrgPerson
uid: admin
cn: Guvnor Admin
sn: Administrator
userPassword: {SSHA}ZGUjbzh0wN0JoWxIAcZfFXpV5MIu/gZw

dn: uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: uidObject
objectclass: person
objectClass: inetOrgPerson
uid: user1
cn: Regular User
sn: Regular
userPassword: {SSHA}Gcif1SlGPu2vHrtoLGYlKXbKBytJiVVF

dn: ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: organizationalUnit
ou: Roles

dn: cn=admin,ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: groupOfNames
cn: admin
description: the GuvnorAdmin group
member: uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu

dn: cn=regular,ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: groupOfNames
cn: regular
description: the Guvnor Regular group
member: uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu

The passwords for admin and user1 are ‘9uvn04′ and ‘user1′ (respectively) and were generated with slappasswd. To add this ldif to our directory, we will use an ldap client application called ldapadd. First we need to update its configuration to be able to talk over SSL. Edit the file /data/openldap-2.3.39/etc/openldap/ldap.conf and add following line:

TLS_REQCERT allow

This will prevent us from getting errors like these:

client side:
ldap_initialize( ldaps://localhost:16636 )
ldap_bind: Can't contact LDAP server (-1)
        additional info: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

server side:
TLS trace: SSL3 alert read:fatal:unknown CA
TLS trace: SSL_accept:failed in SSLv3 read client certificate A
TLS: can't accept.
TLS: error:14094418:SSL routines:SSL3_READ_BYTES:tlsv1 alert unknown ca s3_pkt.c:1057
connection_read(11): TLS accept failure error=-1 id=4, closing
connection_closing: readying conn=4 sd=11 for close
connection_close: conn=4 sd=11

Now we can add the ldif file to our directory:

$ /data/openldap-2.3.39/bin/ldapadd -x -D "cn=DirManager,dc=kijanowski,dc=eu" -H ldaps://localhost:16636 -w admin123 -f myorg.ldif

adding new entry "dc=kijanowski,dc=eu"
adding new entry "o=guvnor,dc=kijanowski,dc=eu"
adding new entry "ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "ou=Roles,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "cn=admin,ou=Roles,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "cn=regular,ou=Roles,o=guvnor,dc=kijanowski,dc=eu"

The last step is to configure JAAS in $JBOSS_SERVER/conf/login-config.xml. Replace the previous file based login module with this one:


    
        
            ldaps://localhost:16636
            ssl
            cn=DirManager,dc=kijanowski,dc=eu
            admin123

            ou=People,o=guvnor,dc=kijanowski,dc=eu
            (uid={0})

            ou=Roles,o=guvnor,dc=kijanowski,dc=eu
            (member={1})
            cn

            -1
            ONELEVEL_SCOPE

Now restart JBoss AS and try to login as admin with password 9uvn04. The application server will talk with the OpenLDAP server over SSL. If you want to shutdown the OpenLDAP server you need to determine its PID and interrupt it by sending the process a SIGINT signal:

$ kill -INT `cat /data/openldap-2.3.39/var/run/slapd.pid`

Use MySQL as a data repository

Jackrabbit has been chosen as a Java Content Repository (JCR) implementation. By default, it uses the Derby database as a backend. You may want to switch to a database you are more familiar with, and can regularly back up and properly tune. If you have already used the file-based repository and don’t want to loose all your assets, export them. After MySQL is up and running, import them back. To export your current repository, go to the ‘Administration’ menu on the left side, expand ‘Admin,’ choose ‘Import/Export,’ and click on ‘Export’:

Fig 2.2 export

Shut down the server and set up MySQL as your new repository. First, download MySQL and extract it. I will use the community server 5.0.51a standard, extracted to /data/mysql-5.0.51. As root, perform the following steps. (For more details, have a look at the INSTALL-BINARY file):

$ /usr/sbin/groupadd mysql5
$ /usr/sbin/useradd -g mysql5 mysql5
$ cd /data/mysql-5.0.51
$ chown -R mysql5 .
$ chgrp -R mysql5 .
$ /data/mysql-5.0.51/scripts/mysql_install_db --user=mysql5

$ chown -R root .
$ chown -R mysql5 data

# now start MySQL
$ /data/mysql-5.0.51/bin/mysqld_safe --user=mysql5 &

# and create a password for root
$ /data/mysql-5.0.51/bin/mysqladmin -u root password mysqladminpwd
To shutdown the MySQL server run:
$ /data/mysql-5.0.51/bin/mysqladmin -u root shutdown -p
Logout as root and log in to MySQL to create a user and database for Guvnor:
$ /data/mysql-5.0.51/bin/mysql -u root -p
mysql> create database guvnor;
Query OK, 1 row affected (0.00 sec)

mysql> grant all privileges on guvnor.* to 'guvnor-user'@'localhost' identified by 'guvnor-pwd';
Query OK, 0 rows affected (0.00 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.00 sec)

Now the DB side is complete.

Edit the $GUVNOR/WEB-INF/components.xml file and provide a path to where you would like to keep the repository configuration files. You can leave the default value–which is the JBoss Application Server’s bin directory–however it is recommended to provide a location that is regularly backed up. Under the ‘repositoryConfiguration’ component add:

/data/GuvnorRepo/

This last step creates a repository.xml file. It is created by default when running Guvnor the first time and is placed into the AS bin directory. This file configures the data repository. We would like to use MySQL, so we will create /data/GuvnorRepo/repository.xml:

As you see we’re using the com.mysql.jdbc.Driver, so we need to provide it. Download the mysql java connector from MySQL, unzip it, and copy the JAR file to $JBOSS_SERVER/lib. (I’m using mysql-connector-java-5.1.6.)

Now you can start the app server. If you have exported your assets, just go to the ‘Administration’ menu, expand ‘Admin,’ choose ‘Import/Export,’ and import your xml file. Please note that you have to unzip your exported xml file before you can upload it.

Enable SSL

The last tweak is enabling SSL. It not only provides security, but also ensures the transmitted data hasn’t been modified. This is strictly a server-side task.

First, we need a certificate. Please note that as the “first and last name” you have to provide the fully qualified domain name of the host. For testing purposes you can use localhost like so:

$ keytool -genkey -alias guvnor -keyalg RSA -keystore $JBOSS_SERVER/conf/guvnor.keystore -validity 365

Enter keystore password:  guvnorkspwd
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  My Department
What is the name of your organization?
  [Unknown]:  My Company
What is the name of your City or Locality?
  [Unknown]:  My City
What is the name of your State or Province?
  [Unknown]:  My State
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=My Name, OU=My Department, O=My Company, L=My City, ST=My State, C=US correct?
  [no]:  yes

Enter key password for 
        (RETURN if same as keystore password):

Now we can enable an SSL connector. Edit the file $JBOSS_SERVER/deploy/jboss-web.deployer/server.xml like so:

Restart your JBoss Application Server. Guvnor should be available at https://localhost:8443/drools-guvnor.

How to use a secured Guvnor package

The last part of this article shows how you can access a drools package from Guvnor in a secure way. This is very straight forward if you use certificates signed by trusted authorities. In our test environment, it’s a little bit more complicated since we use self-signed certificates.

First create a package and deploy it. I’ll use the package we made during the quick introduction. This package is available under https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST. Replace the url attribute with the new value in Guvnor.properties:

url=https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST

One would expect that running the Drools application should end successfully, however this is not the case:

RuleAgent(default) INFO (Wed Jul 23 20:38:03 CEST 2008): Configuring with newInstance=false, secondsToRefresh=-1
RuleAgent(default) INFO (Wed Jul 23 20:38:03 CEST 2008): Configuring package provider : URLScanner monitoring URLs:  https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST
RuleAgent(default) WARNING (Wed Jul 23 20:38:04 CEST 2008): Was an error contacting https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST. Reponse header: {}
RuleAgent(default) EXCEPTION (Wed Jul 23 20:38:04 CEST 2008): Was unable to reach server.. Stack trace should follow.
java.io.IOException: Was unable to reach server.
        at org.drools.agent.URLScanner.hasChanged(URLScanner.java:149)
        at org.drools.agent.URLScanner.getChangeSet(URLScanner.java:113)
        at org.drools.agent.URLScanner.loadPackageChanges(URLScanner.java:90)
        at org.drools.agent.RuleAgent.checkForChanges(RuleAgent.java:341)
        at org.drools.agent.RuleAgent.refreshRuleBase(RuleAgent.java:300)
        at org.drools.agent.RuleAgent.configure(RuleAgent.java:285)
        at org.drools.agent.RuleAgent.init(RuleAgent.java:209)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:177)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:149)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:217)
        at kijanowski.eu.GuvnorTest.main(GuvnorTest.java:12)
Exception in thread "main" java.lang.NullPointerException
        at org.drools.agent.RuleAgent.refreshRuleBase(RuleAgent.java:301)
        at org.drools.agent.RuleAgent.configure(RuleAgent.java:285)
        at org.drools.agent.RuleAgent.init(RuleAgent.java:209)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:177)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:149)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:217)
        at kijanowski.eu.GuvnorTest.main(GuvnorTest.java:12)

If you navigate with your browser to this URL, you will be asked to accept the non-signed certificate. In case of our test application, we need to trust the server by importing its public key to our (temporary) local keystore:

$ mkdir /data/ssl

# export the public key
$ keytool -export -alias guvnor -keystore $JBOSS_SERVER/conf/guvnor.keystore -file /data/ssl/out.cert

# you don't have to provide a password
Enter keystore password:  

*****************  WARNING WARNING WARNING  *****************
* The integrity of the information stored in your keystore  *
* has NOT been verified!  In order to verify its integrity, *
* you must provide your keystore password.                  *
*****************  WARNING WARNING WARNING  *****************

Certificate stored in file 

# import this key to a local truststore
$ keytool -import -alias guvnor -file /data/ssl/out.cert -keystore /data/ssl/myKS

Enter keystore password:  qwerty
Owner: CN=localhost, OU=My Department, O=My Company, L=My City, ST=My State, C=US
Issuer: CN=localhost, OU=My Department, O=My Company, L=My City, ST=My State, C=US
Serial number: 48862cb6
Valid from: Tue Jul 22 20:53:42 CEST 2008 until: Wed Jul 22 20:53:42 CEST 2009
Certificate fingerprints:
         MD5:  81:FD:97:97:12:E7:2B:94:DA:62:35:11:2C:2B:4E:2B
         SHA1: 7E:B1:36:F4:C9:F9:45:5A:98:F2:F1:46:F6:58:E6:0D:81:46:EC:B5
Trust this certificate? [no]:  yes
Certificate was added to keystore

Now we have a keystore with a server’s key that we trust. To use this keystore, just start the drools application with the following property:

-Djavax.net.ssl.trustStore=/data/ssl/myKS

In Eclipse, click on GuvnorTest.java. From the menu Run -> Open Run Dialog and then add this property to the VM arguments:

Fig 2.3 eclipse

Now your Drools application runs in a secure environment.

Summary

This article has shown how you can upgrade your BRMS, which should only be deployed out-of-the-box for testing purposes. For a multiuser environment with mission-critical applications, Guvnor should be tuned. Have a look at this blog post, the JSSE Reference Guide or the key tool docs page for more details about the tools we used. For LDAP browsing I recommend this user-friendly and light-weight tool.

Open source telephony: a Fedora-based VoIP server with Asterisk

W. Michael Petullo — Thu, 24 Jul 2008 22:37:47 +0000

Voice over Internet Protocol (VoIP) has emerged as a popular technology for modern voice communications. Many organizations have replaced their analog or proprietary digital telephone systems with VoIP-based solutions. This allows the consolidation of telephone services into an existing IP infrastructure. In addition, using IP to host voice services lets the organization leverage existing expertise–while retaining all of the network’s management advantages. Though not without its disadvantages, VoIP provides a compelling option to those looking for a telephone solution.

This article will present a simple VoIP solution using Asterisk, an open source private branch exchange (PBX) product. It will show you how to install Asterisk, configure it using its LDAP backend, and connect to it using the Ekiga software VoIP client and a Cisco 7900 Series VoIP telephone to make calls.

Prerequisites

Important note about Asterisk:

Asterisk 1.6 Beta 10 has not yet been released. This version will fix a bug in Asterisk’s realtime LDAP code that causes the server to crash. In the meantime, one may compile the upcoming realtime LDAP module and install it for use with Fedora’s packages. In order to do this, follow the following instructions after installing the Fedora Asterisk packages:

Execute “yum install openldap-devel”
Download the Asterisk 1.6 Beta 9 source from http://www.asterisk.org/ and extract it.
Enter the resulting asterisk-1.6.0-beta9 directory.
Apply the patch available at http://www.flyn.org/patches/asterisk-1.6.0-beta9-crashfix/asterisk-1.6.0-beta9-crashfix.patch.gz by downloading it and executing “gunzip -c PATH-TO-PATCH.gz | patch -p1″ from within the asterisk-1.6.0-beta9 directory.
Execute “./configure –prefix=/usr –sysconf=/etc”
Execute “make res”
Execute “cp res/res_config_ldap.so /usr/lib/asterisk/modules/”

There are a few prerequisites to discuss before covering the configuration of Asterisk. First, my instructions assume that you have already installed Fedora 9. Second, you must have an existing LDAP server. The LDAP schema I use in this article is compatible with Fedora Directory Server. I recommend using the FreeIPA system to manage FDS. Fedora 9 provides packages for both FDS (fedora-ds-base) and FreeIPA (ipa-server). Finally, the machine hosting Asterisk must allow incoming UDP connections to ports 5060 (Session Initiation Protocol) and 69 (TFTP) to pass through its firewall.

Note:: In general, the LDAP database is optional. All configurations may be stored in flat files on the Asterisk server’s disk. However, I have chosen to store my Asterisk users and extensions in an LDAP database. This is beneficial for organizations that wish to consolidate user information in LDAP. In addition, Asterisk’s realtime LDAP backend is new to 1.6. I hope to help fill the gap in existing documentation with this article.

Install the Asterisk components by executing the command yum install asterisk asterisk-ldap asterisk-alsa asterisk-voicemail asterisk-voicemail-plain. In order to configure a Cisco 7900 Series VoIP telephone, you will also need to execute yum install tftp-server, have an existing DHCP server (the one on an inexpensive wireless router will work fine) and a copy of Cisco’s Session Initiation Protocol (SIP) software for the phone.

Note:: Depending on how you buy a Cisco telephone, you may need to purchase the rights to Cisco’s SIP software. Cisco telephones are typically sold with support for the proprietary SCCP protocol. In order to use the telephone with SIP, one must load a SIP flash image onto the telephone. This image may not have been included in the original telephone purchase. One way to obtain a license for the software is to purchase a Cisco SmartNet support package. Support for a 7900 Series telephone costs less than $10 and should be available from the vendor that sold you the telephone. I will cover installing the SIP software later in the article.

The Fedora project does not yet package Asterisk’s audio files because their copyright holder has not yet assigned a license to them (see Red Hat Bugzilla bug #428832). These audio files are required to implement features like an echo test and voicemail. Fortunately, it is quite simple to install them. Visit the Asterisk website and download the latest Asterisk 1.6 series release. Inside the Asterisk archive is another, sounds/asterisk-core-sounds-en-gsm-1.4.11.tar.gz. Extract this archive file into /usr/share/asterisk/sounds.

Configuring the Asterisk PBX

The Asterisk PBX has many features and is very flexible. In this section, I will focus on configuring four things: the SIP module, the extensions module, the external configuration engine, and the realtime LDAP backend. Once Asterisk is configured, I will demonstrate how to add SIP users and extensions to your LDAP database.

Asterisk provides a module to support the SIP protocol. SIP is used to set up and tear down a VoIP phone call. Though individual SIP users will be stored in an LDAP database, some global parameters will exist in the following configuration file. Save this configuration as /etc/asterisk/sip.conf:

[general]
videosupport=yes
allow=all
bindaddr=0.0.0.0
realm=example.com

videosupport: Enable support for video streaming.
allow: List of CODEC’s to allow.
bindaddr: IP address of the device to bind to. 0.0.0.0 ensures that Asterisk will listen on all available network devices.
realm: The authentication realm.

We will now move on to define extensions. In many cases, an extension is simply a telephone number that will be associated with a SIP user. Individual extensions, like SIP users, will be stored in an
LDAP database. However, as with the SIP configuration, global parameters will be configured in a file,
/etc/asterisk/extensions.conf. The following example supports the LDAP entries I will use in this article:

[users]
switch => Realtime/@

[demo]
switch => Realtime/@

[default]
include => users
include => demo

This example defines three contexts: default, users, and demo. The line switch => Realtime/@ states that the extensions in a context will be defined using one of Asterisk’s realtime back-ends (in our case, LDAP). Each individual extension will be assigned to one of these contexts. As a collection of available extensions, contexts determine what happens when a user dials a phone number.

Asterisk’s external configuration engines are activated in /etc/asterisk/extconfig.conf. The following example configures Asterisk to pull SIP and extension information using its real-time LDAP back-end:

[settings]
sipusers => ldap,"dc=example,dc=com",sip
sippeers => ldap,"dc=example,dc=com",sip
extensions => ldap,"dc=example,dc=com",extensions

This example causes Asterisk to activate its real-time LDAP back-end look for SIP users, SIP peers, and extensions in the LDAP database. In addition, the base DN used for queries is specified.

Note:: All of the examples in this article will use dc=example,dc=com as the LDAP database’s base DN. This should be replaced with your organization’s base DN.

The final configuration file we will write configures Asterisk’s real-time LDAP back-end and should be saved as /etc/asterisk/res_ldap.conf.

[_general]
url=ldaps://ldap.example.com:636
protocol=3
basedn="dc=example,dc=com"
user=cn=Directory Manager
pass=LDAP-PASSWORD

[config]
additionalFilter=(objectClass=AstConfig)
filename = AstConfigFilename
category = AstConfigCategory
variable_name = AstConfigVariableName
variable_value = AstConfigVariableValue
cat_metric = AstConfigCategoryMetric
commented = AstConfigCommented

[extensions]
context  =  AstContext
exten  =  AstExtension
priority = AstPriority
app = AstApplication
appdata = AstApplicationData
additionalFilter=(objectClass=AsteriskExtension)

[sip]
name = cn
amaflags = AstAccountAMAFlags
callgroup = AstAccountCallGroup
callerid = AstAccountCallerID
canreinvite = AstAccountCanReinvite
context = AstAccountContext
dtmfmode = AstAccountDTMFMode
fromuser = AstAccountFromUser
fromdomain = AstAccountFromDomain
fullcontact = AstAccountFullContact
host = AstAccountHost
ipaddr = AstAccountIPAddress
insecure = AstAccountInsecure
mailbox = AstAccountMailbox
md5secret = AstAccountRealmedPassword
nat = AstAccountNAT
deny = AstAccountDeny
permit = AstAccountPermit
pickupgroup = AstAccountPickupGroup
port = AstAccountPort
qualify = AstAccountQualify
restrictcid = AstAccountRestrictCID
rtptimeout = AstAccountRTPTimeout
rtpholdtimeout = AstAccountRTPHoldTimeout
type = AstAccountType
disallow = AstAccountDisallowedCodec
allow = AstAccountAllowedCodec
MusicOnHold = AstAccountMusicOnHold
regseconds = AstAccountExpirationTimestamp
regcontext = AstAccountRegistrationContext
regexten = AstAccountRegistrationExten
CanCallForward = AstAccountCanCallForward
defaultuser = AstAccountDefaultUser
regserver = AstAccountRegistrationServer
additionalFilter = (objectClass=AsteriskSIPUser)

The config, extensions, and sip sections of this file map Asterisk configuration options to LDAP attributes and do not need to be customized. The _general section contains the following options:

url: The URL pointing to the organization’s LDAP server. The example above uses LDAP over SSL on port 636.
protocol: The LDAP version to use.
basedn: The base DN used for queries.
user: The name of the LDAP administrator. Directory Manager is the name used by the Fedora Directory Server.
pass: The LDAP directory manager’s password.

Configuring LDAP

With the exception of actual users and extensions, our simple Asterisk installation is fully configured. We will now finish our installation by adding users and extensions to our LDAP database. First, we need to install an Asterisk schema for LDAP at /etc/dirsrv/slapd-DOMAIN/schema/99asterisk.ldif. After the schema has been installed, restart FDS using service dirsrv restart.

dn: cn=schema
#
attributeTypes: (
  NAME 'AstContext'
  DESC 'Asterisk Context'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstExtension'
  DESC 'Asterisk Extension'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstPriority'
  DESC 'Asterisk Priority'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstApplication'
  DESC 'Asterisk Application'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstApplicationData'
  DESC 'Asterisk Application Data'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountAMAFlags'
  DESC 'Asterisk Account AMA Flags'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountCallerID'
  DESC 'Asterisk Account CallerID'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountContext'
  DESC 'Asterisk Account Context'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountMailbox'
  DESC 'Asterisk Account Mailbox'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstMD5secret'
  DESC 'Asterisk Account MD5 Secret'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountDeny'
  DESC 'Asterisk Account Deny'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountPermit'
  DESC 'Asterisk Account Permit'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountQualify'
  DESC 'Asterisk Account Qualify'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountType'
  DESC 'Asterisk Account Type'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountDisallowedCodec'
  DESC 'Asterisk Account Disallowed Codec'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountExpirationTimestamp'
  DESC 'Asterisk Account Allowed Codec'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRegistrationContext'
  DESC 'Asterisk Account AMA Flags'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRegistrationExten'
  DESC 'Asterisk Account AMA Flags'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountNoTransfer'
  DESC 'Asterisk Account AMA Flags'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountCallGroup'
  DESC 'Asterisk Account Call Group'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountCanReinvite'
  DESC 'Asterisk Account Can Reinvite'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountDTMFMode'
  DESC 'Asterisk Account DTMF Flags'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountFromUser'
  DESC 'Asterisk Account From User'
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountFromDomain'
  DESC 'Asterisk Account From Domain'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountFullContact'
  DESC 'Asterisk Account Full Contact'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountHost'
  DESC 'Asterisk Account Host'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountInsecure'
  DESC 'Asterisk Account Insecure'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountNAT'
  DESC 'Asterisk Account NAT'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountPickupGroup'
  DESC 'Asterisk Account PickupGroup'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountPort'
  DESC 'Asterisk Account Port'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRestrictCID'
  DESC 'Asterisk Restrict CallerID'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRTPTimeout'
  DESC 'Asterisk RTP Timeout'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRTPHoldTimeout'
  DESC 'Asterisk RTP Hold Timeout'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRealmedPassword'
  DESC 'Asterisk RTP Hold Timeout'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountAllowedCodec'
  DESC 'Asterisk Account Allowed Codec'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountMusicOnHold'
  DESC 'Asterisk Account Allowed Codec'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountCanCallForward'
  DESC 'Asterisk Can CAll Forward'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountSecret'
  DESC 'Asterisk Can CAll Forward'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountName'
  DESC 'Asterisk Account Username'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigFilename'
  DESC 'Asterisk LDAP Configuration Filename'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigCategory'
  DESC 'Asterisk LDAP Configuration Category'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigCategoryMetric'
  DESC 'Asterisk LDAP Configuration Category Metric'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigVariableName'
  DESC 'Asterisk LDAP Configuration Variable Name'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigVariableValue'
  DESC 'Asterisk LDAP Configuration Variable Value'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstConfigCommented'
  DESC 'Asterisk LDAP Configuration Commented'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountIPAddress'
  DESC 'Asterisk Account IP Address'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountDefaultUser'
  DESC 'Asterisk Account Default User'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstAccountRegistrationServer'
  DESC 'Asterisk Account Registration Server'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
objectClasses: (
  NAME 'AsteriskExtension'
  DESC 'PBX Extension Information for Asterisk'
  SUP top
  AUXILIARY
  MUST cn
  MAY ( AstContext $ AstExtension $ AstPriority $ AstApplication
      $ AstApplicationData )
  )
#
objectClasses: (
  NAME 'AsteriskIAXUser'
  DESC 'IAX2 User information for Asterisk'
  SUP AsteriskExtension
  AUXILIARY
  MUST cn
  MAY ( AstAccountAMAFlags $ AstAccountCallerID $ AstAccountContext
      $ AstAccountFullContact $ AstAccountHost $ AstAccountMailbox $ AstMD5secret
      $ AstAccountDeny $ AstAccountPermit $ AstAccountPort $ AstAccountQualify
      $ AstAccountType $ AstAccountDisallowedCodec $ AstAccountExpirationTimestamp
      $ AstAccountRegistrationContext$ AstAccountRegistrationExten
      $ AstAccountNoTransfer $ AstAccountName )
  )
#
objectClasses: (
  NAME 'AsteriskSIPUser'
  DESC 'SIP User information for Asterisk'
  SUP AsteriskExtension
  AUXILIARY
  MUST cn
  MAY ( AstAccountAMAFlags $ AstAccountCallGroup $ AstAccountCallerID
      $ AstAccountCanReinvite $ AstAccountContext $ AstAccountDefaultUser
      $ AstAccountDTMFMode $ AstAccountFromUser $ AstAccountFromDomain
      $ AstAccountFullContact $ AstAccountHost $ AstAccountInsecure
      $ AstAccountIPAddress $ AstAccountMailbox $ AstAccountRealmedPassword
      $ AstAccountNAT $ AstAccountDeny $ AstAccountPermit $ AstAccountPickupGroup
      $ AstAccountPort $ AstAccountQualify $ AstAccountRestrictCID
      $ AstAccountRTPTimeout $ AstAccountRTPHoldTimeout $ AstAccountType
      $ AstAccountDisallowedCodec $ AstAccountAllowedCodec $ AstAccountMusicOnHold
      $ AstAccountExpirationTimestamp $ AstAccountRegistrationContext
      $ AstAccountRegistrationExten $ AstAccountRegistrationServer
      $ AstAccountCanCallForward $ AstAccountSecret $ AstAccountName )
  )
#
objectClasses: (
  NAME 'AsteriskConfig'
  DESC 'Asterisk configuration Information'
  SUP top
  AUXILIARY
  MUST cn
  MAY ( AstConfigFilename $ AstConfigCategory $ AstConfigCategoryMetric
      $ AstConfigVariableName $ AstConfigVariableValue $ AstConfigCommented )
  )

We may now create two SIP users, one for our Ekiga installation and the other for our Cisco telephone. If you write the following LDIF into a file, you may load it into the LDAP database using ldapadd -x -D "cn=Directory Manager" -W -f PATH-TO-LDIF.

dn: ou=sippeers,dc=example,dc=com
ou: sippeers
objectClass: top
objectClass: organizationalUnit

dn: cn=user1,ou=sippeers,dc=example,dc=com
objectClass: top
objectClass: AsteriskSIPUser
cn: user1
AstAccountCallerID: 2001
AstAccountHost: dynamic
AstAccountRealmedPassword: {MD5}a94775781e5bb7d3e4ec047c56f0acc5
AstAccountContext: default
AstAccountType: friend

dn: cn=user2,ou=sippeers,dc=example,dc=com
objectClass: top
objectClass: AsteriskSIPUser
cn: user2
AstAccountCallerID: 2002
AstAccountHost: dynamic
AstAccountRealmedPassword: {MD5}3c7806fa6e6c3416d57f2de223cdea5d
AstAccountContext: default
AstAccountType: friend

The example above defines a minimal SIP user. The attributes used are:

cn: The SIP user’s account name.
AstAccountCallerID: The user’s caller ID information.
AstAccountHost: The user’s host. The dynamic keyword allows a user’s telephone to dynamically register its IP address by logging into Asterisk.
AstAccountRealmedPassword: The account’s password. The hash of a user’s password may be generated by executing echo -n "SIPUSER:example.com:PASSWORD" | md5sum
AstAccountContext: The context this user will exist in. This determines which extension context applies to this user. Extension contexts were defined in extensions.conf.
AstAccountType: Defines the type of client. Asterisk sends calls to peers (i.e., a SIP provider). The user type may place calls only. Friends are both peers and users.

Once a user is defined, one may test Asterisk. Start the Asterisk service by executing service asterisk start as root. Execute an Asterisk shell using the command asterisk -rv. At Asterisk’s prompt, execute sip show peer user1 load. Asterisk should print all of the information for user1.

Once you have defined a user, you may start writing your dial plan. First, we will associate a phone number with each user. Use ldapadd to add the following to your LDAP database:

dn: ou=extensions,dc=example,dc=com
ou: extensions
objectClass: top
objectClass: organizationalUnit

dn: cn=2001-1,ou=extensions,dc=example,dc=com
cn: 2001-1
objectClass: top
objectClass: AsteriskExtension
AstContext: users
AstExtension: 2001
AstPriority: 1
AstApplication: Dial
AstApplicationData: SIP/user1,20

dn: cn=2002-1,ou=extensions,dc=example,dc=com
cn: 2002-1
objectClass: top
objectClass: AsteriskExtension
AstContext: users
AstExtension: 2002
AstPriority: 1
AstApplication: Dial
AstApplicationData: SIP/user2,20

AstContext: The context in which this extension exists.
AstExtension: The extension ID (e.g., what you dial to reach this extension).
AstPriority: Each extension can execute several commands when it receives a call. The priority determines the order in which commands are executed.
AstApplication: The command to execute when the extension receives a call. The command Dial connects to another Asterisk user.
AstApplicationData: Arguments, separated with commas (without spaces), and passed to a command. The Dial has two arguments. The first is the user that the call will be connected to. The second is the number of seconds to wait before quitting.

In order to facilitate testing our installation, we will define the following additional extension. This extension executes three commands to implement an echo test that may be reached by dialing ‘600.’

dn: cn=600-1,ou=extensions,dc=example,dc=com
cn: 600-1
objectClass: top
objectClass: AsteriskExtension
AstContext: demo
AstExtension: 600
AstPriority: 1
AstApplication: Playback
AstApplicationData: demo-echotest

dn: cn=600-2,ou=extensions,dc=example,dc=com
cn: 600-2
objectClass: top
objectClass: AsteriskExtension
AstContext: demo
AstExtension: 600
AstPriority: 2
AstApplication: Echo

dn: cn=600-3,ou=extensions,dc=example,dc=com
cn: 600-3
objectClass: top
objectClass: AsteriskExtension
AstContext: demo
AstExtension: 600
AstPriority: 3
AstApplication: Playback
AstApplicationData: demo-echodone

After schema edits, FDS must be restarted using service dirsrv restart.

The basic Asterisk configuration is now complete. Restart the Asterisk service using service asterisk restart.

Configuring the Ekiga VoIP client

Ekiga is a software VoIP application that supports SIP. Its configuration is straightforward. The first time Ekiga is executed by a user, it provides a wizard that allows one to configure the user’s full name,
ekiga.net account (this is not required for the purpose of this article), connection type, audio devices, and video devices. Once the software is configured, setup a SIP account by clicking on Edit→Accounts and selecting add. Figure 1 displays an account configured for our SIP user identified as user1.

Figure 1. Ekiga Account Configuration

After an account is set up, it must be activated. Figure 2 shows that the account I just configured is displayed in Ekiga’s list. Click the checkbox to activate the account.

Figure 2. Ekiga Account Activation

Figure 3 shows Ekiga’s main interface window. Here, you can see how many accounts have been registered. In order to test your configuration, make a SIP connection to extension 600 and perform an echo test.

Figure 3. Ekiga Primary Interface

Configuring a Cisco VoIP telephone

As mentioned before, using a Cisco phone to connect to Asterisk using SIP requires Cisco’s SIP software. When a Cisco 7900 Series telephone boots, it will try to configure itself using TFTP. We will place some firmware and configuration files on our server so that the phone will boot properly for our installation.

In order to enable TFTP on the Asterisk server, edit /etc/xinetd.d/tftp and set disable to no. The TFTP daemon is configured on Fedora to serve files out of /var/lib/tftpboot. After you have modified its configuration, restart xinetd with the command service xinetd restart. Cisco’s SIP software package provides the files P0S3-08-2-00.sb2, P0S3-08-2-00.sbn and P0S3-08-2-00.loads. Copy these files to /var/lib/tftpboot.

Note:: The filenames used by your Cisco firmware may be slightly different. Cisco’s naming convention is P0S3-xxx-y-zz, where x is the major version, y is the minor version, and z is the subversion. P0S3 indicates SIP firmware, P003 indicates SCCP firmware, and P0M3 indicates MGCP firmware.

When booting SIP firmware, the telephone will look for three configuration files: OS79XX.TXT, SIPDefault.cnf, and SIPMAC-ADDRESS.cnf. These files should also
be placed in /var/lib/tftpboot.

OS79XX.TXT contains one line: the firmware version to load. Mine contains P0S3-08-2-00.

SIPDefault.cnf contains configurations common to all SIP telephones. The following example lists the image version and the address of our Asterisk server, and instructs the telephones to register with Asterisk:

image_version: P0S3-08-2-00 ;
proxy1_address: 192.168.0.10 ;
proxy_register: "1" ;

Per-telephone configurations are stored in a file named after the telephone’s MAC address. The telephone’s MAC address may be found in its configuration menu. This configuration will correspond with the SIP information found in LDAP and should be saved as SIPMAC-ADDRESS.cnf:

line1_name : user2
line1_authname : user2
line1_password : PLAINTEXT-PASSWORD

The first step in preparing the telephone is to clear any existing configuration. This may be done by pressing **# settings 3 to access an unlocked Network
Configuration menu. Here, find the Erase Configuration menu item and select it. Restart the phone and return to the Network Configuration menu. Ensure DHCP Enabled is set. Reboot the phone.

The phone will pull its network configuration from DHCP and should now respond to pings. Return to the Network Configuration menu and deactivate DHCP. Select the TFTP Server 1 option and set it to your Asterisk / TFTP server. Do not disable DHCP or manually set a TFTP server if your DHCP server provides your TFTP server’s IP address. Reboot the telephone and it should load the SIP software and configuration. As the phone boots, you may see it request files using TFTP by watching the Asterisk server’s /var/log/messages log.

Once the telephone boots, test its configuration by dialing 600. This will execute an echo test. After the echo test, you may make a Cisco telephone to Ekiga call by dialing 2001.

Configuring voicemail

In this section, we will cover configuring Asterisk to provide a voicemail system. The configuration process is similar to that of SIP users and extensions, so this should also serve to reinforce the techniques covered in those sections. We will configure the voicemail module, the external
configuration engine, and the real-time LDAP back-end. After the configuration files are setup, we will add information to the LDAP database.

/etc/asterisk/voicemail.conf is similar to sip.conf and
extensions.conf. This file configures the voicemail module. As with SIP users and extensions, we will configure global parameters in a file, leaving extension-specific parameters to be configured in LDAP:

[general]
searchcontexts=yes

Add the following line to /etc/asterisk/extconfig.conf in order to activate the real-time LDAP back-end for voicemail:

voicemail => ldap,"dc=example,dc=com",voicemail

Map Asterisk voicemail configuration options to LDAP attributes by adding the following to /etc/asterisk/res_ldap.conf:

[voicemail]
context = AstVMContext
mailbox = AstVMMailbox
password = AstVMPassword
fullname = AstVMFullname
email = AstVMEmail
pager = AstVMPager
tz = AstVMTz
attach = AstVMAttach
saycid = AstVMSaycid
dialout = AstVMDialout
callback = AstVMCallback
review = AstVMReview
operator = AstVMOperator
envelope = AstVMEnvelope
sayduration = AstVMSayduration
saydurationm = AstVMSaydurationm
sendvoicemail = AstVMSendvoicemail
delete = AstVMDelete
nextaftercmd = AstVMNextastercmd
forcename = AstVMForcename
forcegreetings = AstVMForcegreetings
hidefromdir = AstVMHidefromdir
stamp = AstVMStamp
additionalFilter = (objectClass=AsteriskVoicemail)

Now we will move to updating our LDAP database. First, we must add to the LDAP schema that we installed earlier. The following will add support for the attributes required to provide basic voicemail:

attributeTypes: (
  NAME 'AstVMMailbox'
  DESC 'Asterisk Voicemail Mailbox'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstVMPassword'
  DESC 'Asterisk Voicemail Password'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstVMFullname'
  DESC 'Asterisk Voicemail Fullname'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
attributeTypes: (
  NAME 'AstVMEmail'
  DESC 'Asterisk Voicemail Email'
  EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
  )
#
objectClasses: (
  NAME 'AsteriskVoicemail'
  DESC 'Voicemail information for Asterisk'
  SUP top
  MUST cn
  MAY ( AstContext $ AstVMMailbox $ AstVMPassword $ AstVMFullname
      $ AstVMEmail )
  )

Add the following LDIF to the LDAP database using ldapadd in order to add voicemail support for the extensions 2001 and 2002:

dn: ou=voicemail,dc=example,dc=com
ou: voicemail
objectClass: top
objectClass: organizationalUnit

dn: cn=2001,ou=voicemail,dc=example,dc=com
cn: 2001
objectClass: top
objectClass: AsteriskVoicemail
AstContext: users
AstVMMailbox: 2001
AstVMPassword: 1234
AstVMFullname: User 1
AstVMEmail: user1@example.org

dn: cn=2002,ou=voicemail,dc=example,dc=com
cn: 2002
objectClass: top
objectClass: AsteriskVoicemail
AstContext: users
AstVMMailbox: 2002
AstVMPassword: 1234
AstVMFullname: User 2
AstVMEmail: user2@example.org

dn: cn=2000-1,ou=extensions,dc=example,dc=com
cn: 2000-1
objectClass: top
objectClass: AsteriskExtension
AstContext: users
AstExtension: 2000
AstPriority: 1
AstApplication: Voicemailmain

dn: cn=2001-2,ou=extensions,dc=example,dc=com
cn: 2001-2
objectClass: top
objectClass: AsteriskExtension
AstContext: users
AstExtension: 2001
AstPriority: 2
AstApplication: Voicemail
AstApplicationData: 2001,u

dn: cn=2002-2,ou=extensions,dc=example,dc=com
cn: 2002-2
objectClass: top
objectClass: AsteriskExtension
AstContext: users
AstExtension: 2002
AstPriority: 2
AstApplication: Voicemail
AstApplicationData: 2002,u

The second entry defines a mailbox for extension 2001. It uses the following options:

AstContext: The context in which this mailbox exists.
AstVMMailbox: The extension that this mailbox corresponds to.
AstVMPassword: The password used to access the mailbox.
AstVMFullname: The full name of the mailbox owner.
AstVMEmail: The mailbox owner’s email address.

Entity four defines an extension, 2000, that will provide access to the voicemail system when dialed.

Entity five adds a command to extension 2001 that executes the Voicemail and provides access to the voicemail system. This command will execute if the Dial command defined earlier is not answered within 20 seconds.

To test the voicemail system, use Ekiga to dial 2002. If you don’t answer the call on the other end, then you should be directed to Asterisk’s voicemail system. To listen to new voicemail, dial 2000.

Conclusion

This article demonstrated how to install Asterisk on a Fedora system and configure SIP users, extensions, and voicemail. We installed all user data into an LDAP database in order to keep it consolidated.

Asterisk has far too many features to cover in one article. The VoIP Wiki has a section dedicated to Asterisk and is a great place to learn more. The VoIP Wiki covers topics such as hooking Asterisk up to the standard public-switched telephone network using direct inward dialing and automatically emailing voicemail messages to users. You can even find information on how to route calls to a user based on his Jabber presence. Clearly, Asterisk is capable of a wide range of applications. And, perhaps best of all, it’s entirely open source!

NetworkManager: Secret weapon for the Linux road warrior

Kyle Gonzales — Tue, 22 Jul 2008 22:21:19 +0000

For years I have envied how easy my Windows- and Mac-based peers had it when traveling with their laptops. They connect to hotspots with ease, get online while I was still logging into root and running some tools. It just wasn’t fair. I wanted an integrated easy-to-use tool that did not require bringing up a shell or logging into root.

I now have that tool in NetworkManager. In this article I will explain what NetworkManager is, what capabilities exist in the tool (in both Fedora and Red Hat Enterprise Linux), and what you can do to extend it to give you more control over your system than before.

What is NetworkManager?

NetworkManager is a software utility that allows a desktop user to manage wired, wireless, modem, WWAN/3G, and VPN network connectivity from a single source. It does not require root access or manual editing of configuration files.

NetworkManager started as a Gnome project and initially appeared in Fedora. It is now supported on multiple desktop environments (Gnome, KDE, Xfce, etc.) and in multiple distributions (Fedora, SuSE, Ubuntu, Gentoo, Debian, etc.). NetworkManager uses dbus and hal to provide network status updates to other desktop applications, allowing them to alter their operation based on this information. For instance, if NetworkManager shows the network is offline, then apps like Evolution and Pidgin will put themselves into offline mode andwait for the network to come online.

How is the NetworkManager software deployed on the system?

NetworkManager is deployed in two parts. The first part is the NetworkManager daemon, which is found in the package NetworkManager. This daemon should be set to start while the system is booting. This can be accomplished by entering the following command as root:

    # /sbin/chkconfig NetworkManager on

You can also start NetworkManager manually by entering the following command as root:

    # /sbin/service NetworkManager start

The second part is the user client, which normally takes the form of an applet. This applet (nm-applet) can be found in the NetworkManager-gnome package, and should be part of the basic Gnome desktop installation. You will not need to add this applet to your desktop. Gnome will add the nm-applet control to the Notification Area applet when the NetworkManager daemon is active.

How does NetworkManager work?

For the user, most everything will be done via the NetworkManager applet. Exactly what needs to be done depends on the type of networking the user needs to activate.

Wired network

If the system the user is logged into is on a wired network (Ethernet), the user does not need to do anything. NetworkManager will look for the link on the network port. When the link is active, it will bring up the interface and then ask for network information via DHCP.

Wireless Network

If the user is trying to connect via wireless, NetworkManager is especially helpful. As long as the wireless device is active, NetworkManager will scan for available networks and will attempt to connect to the last network you connected to that it can see. If the network it is trying to connect to is a secure network (using WEP, WPA, WPA2, or LEAP) it will request the appropriate security information. Once the information is entered, NetworkManager will try to store this information into the GNOME keyring manager.

To connect to a different network than the one that NetworkManager chooses, simply click on the applet and choose a different wireless network.

WWAN network (3G/EVDO/HSDPA/RTTx1/EDGE)

With the release of NetworkManager 0.70, users can now choose WWAN networking. Most of these cards require activation in Windows, but NetworkManager can handle the auto-configuration some cards need for use under Linux. Other cards may still require some minimal account information to activate and use.

If the card is plugged in when NetworkManager starts, it will be autodetected and an attempt to auto-configure the card will be made when you request a connection to the network. If auto-configuration is successful, the user can then just select the card in the applet menu and connect.

VPN connectivity

Once a successful network connection has been made, the user can also use NetworkManager to activate a VPN connection. Currently, there are modules providing support for OpenVPN and Cisco (via vpnc) VPN connectivity.

The VPN connection will be configured, activated, and deactivated via the applet. Username, password, group passwords, and other information can be stored in the GNOME keyring manager, or the user can choose to be prompted to enter some—or all—of the information at each login.

What else can NetworkManager do?

Beside managing your network connectivity, NetworkManager has another key feature. NetworkManager can run scripts when there is a network state change on any interface, using the network interface and the up/down state as variables. In prior releases, this functionality was provided by a separate daemon called NetworkManagerDispatcher. As of NetworkManager 0.70 in Fedora 9, this functionality is now integrated into NetworkManager itself.

In Bash scripts written for NetworkManager, the variable $1 equals the interface whose state has changed and triggered the script. Variable $2 equals the state of the interface (up or down). No other variables are needed.

Let’s take a look at one of the scripts that is included with Fedora 9:

# cat /etc/NetworkManager/dispatcher.d/05-netfs

#!/bin/sh

export LC_ALL=C

if [ "$2" = "down" ]; then
        /sbin/ip route ls | grep -q ^default || {
                [ -f /var/lock/subsys/netfs ] && /etc/rc.d/init.d/netfs stop
        }
fi

if [ "$2" = "up" ]; then
        /sbin/ip -o route show dev "$1" | grep -q '^default' && {
                /sbin/chkconfig netfs && /etc/rc.d/init.d/netfs start
        }
fi

When an interface comes up and adds itself as the default route, the script starts the netfs service. This script also stops the netfs service when an interface goes down and no default route remains. Effectively, this will mount your NFS and CIFS shares when you have access to the network, and will unmount those same shares when the network goes down. Using this script as an example, you can easily write your own scripts to run various commands as the network state changes.

How can I best use NetworkManager in the field?

Now that you have a good idea of how NetworkManager works and what it can do, let’s talk about how to best use NetworkManager in the field. Now that you have NetworkManager managing your network connectivity, make sure your network interfaces are not trying to start on boot. Nothing is more annoying than having your laptop tell you that your wired network is not available when you are sitting on a plane. If you are using NetworkManager 0.70 (currently in Fedora 9), you should also disable the network service itself, as it may conflict with NetworkManager.

You can go further, writing NetworkManager scripts to activate various services only when they are needed. Many of the init scripts in Linux make the assumption that your system is a server or a workstation with continuous access to the network. Things like ntp, cups, sshd, even rhnsd do not need to be running while you have no network connectivity. These services can be disabled, set to run only when NetworkManager starts them via a custom script on a network state change.

Using the previously posted script as a guide, a script to manage sshd might look like this:

# cat /etc/NetworkManager/dispatcher.d/10-sshd

#!/bin/sh
#
# Start and stop sshd based on network availability using NetworkManager
#

export LC_ALL=C

if [ "$2" = "down" ]; then
        /sbin/ip route ls | grep -q ^default || {
                [ -f /var/lock/subsys/sshd ] && /etc/rc.d/init.d/sshd stop
        }
fi

if [ "$2" = "up" ]; then
        /sbin/ip -o route show dev "$1" | grep -q '^default' && {
                /sbin/chkconfig sshd && /etc/rc.d/init.d/sshd start
        }
fi

You could substitute “rhnsd” or “cups” for “sshd”, and the script should work equally well for those tasks..

If you are a administrator tasked with managing Red Hat or Fedora systems of remote employees, the scripting functionality can be even more handy. You can write a script that looks for the activation of the VPN interface then sends an email letting you know the system is online. You could have the system check in with a Satellite server located within your firewall, installing updates you previously scheduled for it. The possible uses here are many.

The student is now the master

No longer do I envy my Windows-based peers and their easy mobile connectivity. NetworkManager is constantly impressing me, adding functionality and allowing me to be more efficient on the road. This Swiss Army knife of Linux networking gives me the control I need over my connectivity whether at home, coffee house, or airport. Now that you know what NetworkManager is, how it works, and how best to use it, try it out of your own system. I trust you will find NetworkManager works as well for you as it did for me.

More information

JBoss Drools meets Hibernate

Jaroslaw Kijanowski — Fri, 11 Jul 2008 20:31:36 +0000

Jaroslaw is a JBoss QA Engineer based in Poland, and recently published an introduction to Drools that he kindly shared with us. This second piece covers Drools (or JBoss Rules), the open source business rules engine… in this case combining it with Hibernate.

This article is presented here in its entirety (with a trackback). The original can be found on Jaroslaw’s site. This article is also available in German and Polish.

Justification:

Drools evaluates facts which are present in the working memory. But could it also reason over data stored in a relational database? This feature would extend Drools’ range of applicability and since this is an often asked question in the mailing list, it’s worth to know the answer which sounds: “of course Drools can!”

Abstract:

Hibernate, one of the most favorite ORM tools, allows to handle data stored in a relational database. This article will describe how one can access a Hibernate session from inside the rule engine. I will use PostgreSQL as a data source. Besides that I will create two classes, Game and Player, having a many-to-many relationship.

Creating a new Drools project
Class files
Hibernate
Drools
How does it work?
Results
Summary

Creating a new Drools project

You still don’t have installed the Drools 4.0.7 Eclipse Workbench? Just have a look at this article: “Rules fall from your eyes”.

Menu File -> New -> Project -> Drools - > Rule Project -> Next. Provide the project’s name, drools-hibernate-demo, and click on Next, to uncheck the example files

Class files

Create a package “eu.kijanowski.drools.hibernate” in the src/main/java directory. We will use two class files, Player.java and Game.java. They have a many-tom-many relationship, since one player can own many games and one game can be owned by many players ;)

Class Game.java

package eu.kijanowski.drools.hibernate;

import java.io.Serializable;
import java.util.HashSet;
import java.util.Set;

public class Game implements Serializable {
	private static final long serialVersionUID = 1L;
	private Long id = null;
	private String name;
	private double price;
	private int levels;
	private Set players = new HashSet();

	public Game() {
	}

	public Game(String name, double price, int levels) {
		this.name = name;
		this.price = price;
		this.levels = levels;
	}

	public Long getId() {
		return id;
	}

	@SuppressWarnings("unused")
	private void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public double getPrice() {
		return price;
	}

	public void setPrice(double price) {
		this.price = price;
	}

	public int getLevels() {
		return levels;
	}

	public void setLevels(int levels) {
		this.levels = levels;
	}

	public Set getPlayers() {
		return players;
	}

	public void setPlayers(Set players) {
		this.players = players;
	}

	public String toString() {
		return name + " with " + levels + " levels for " + price;
	}
}

Class Player.java

package eu.kijanowski.drools.hibernate;

import java.io.Serializable;
import java.util.HashSet;
import java.util.Set;

public class Player implements Serializable {
	private static final long serialVersionUID = 1L;
	private Long id;
	private String name;
	private int age;
	private Set games = new HashSet();

	public Player() {
	}

	public Player(String name, int age, HashSet games) {
		this.name = name;
		this.age = age;
		this.games = games;
	}

	public Long getId() {
		return id;
	}

	@SuppressWarnings("unused")
	private void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public Set getGames() {
		return games;
	}

	public void setGames(Set games) {
		this.games = games;
	}

	public String toString() {
		return name;
	}
}

Hibernate

Without going into details, download the binaries, Hibernate Core 3.2.6 and extract the archive.

In our project create a directory called lib and copy over following files:

hibernate-3.2.6.GA/lib/antlr-2.7.6.jar
hibernate-3.2.6.GA/lib/asm.jar
hibernate-3.2.6.GA/lib/cglib-2.1.3.jar
hibernate-3.2.6.GA/lib/commons-collections-2.1.1.jar
hibernate-3.2.6.GA/lib/commons-logging-1.0.4.jar
hibernate-3.2.6.GA/lib/dom4j-1.6.1.jar
hibernate-3.2.6.GA/hibernate3.jar
hibernate-3.2.6.GA/lib/jta.jar

Now we have to add these libraries to the “build path”: from the menu choose Project -> Properties -> Java Build Path -> Libraries and then Add External JARs and navigate to the project’s lib directory. Mark all files and click OK.

It’s time to configure Hibernate. In the src/main/java directory create a file called hibernate.cfg.xml:



 

     
         org.postgresql.Driver
         jdbc:postgresql://localhost/droolsdb
         droolsuser

         
         1
         org.hibernate.dialect.PostgreSQLDialect
         org.hibernate.transaction.JDBCTransactionFactory

         thread
         org.hibernate.cache.NoCacheProvider
         true
         create

As you see, we’re going to use the org.postgresql.Driver class, hence we need to add another library to our project. From the PostgreSQL home page we can download the required driver. I’m using 8.2-508 JDBC 3. Don’t forget to add it to the Java Build Path, like we did with the hibernate library.

It’s time to download and start PostgreSQL and create a user and schema.

/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data>logfile 2>&1 &
/usr/local/pgsql/bin/createuser -h 127.0.0.1 -p 5432 -U postgres -s -d -R droolsuser
/usr/local/pgsql/bin/createdb -h 127.0.0.1 -p 5432 -U postgres -O droolsuser droolsdb

The last step is mapping - this is connecting the world of Java objects with the world of relations (tabels). Create model.hbm.xml in the eu.kijanowski.drools.hibernate package:




	
		

			
				player_id_seq
			
		
		

		

		
			
			
		

	

	
		
			
				game_id_seq

Drools

We’re almost there. We olny have to create the rule file and a testing class which will start our example. But how are we going to use Hibernate in our application? Well, in our testing class we will create a Hibernate session and provide it to the rule engine’s working memory as a constant global value. This allows us to access the database from inside the rule file. Next we will create a query and access the result’s objects using the keyword “from”. Let’s do this:

Class DroolsHibernateTest.java

package eu.kijanowski.drools.hibernate;

import java.io.InputStreamReader;
import java.io.Reader;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import org.drools.RuleBase;
import org.drools.RuleBaseFactory;
import org.drools.WorkingMemory;
import org.drools.compiler.PackageBuilder;
import org.drools.rule.Package;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.cfg.Configuration;

public class DroolsHibernateTest {

	private final static SessionFactory factory;
	static {
		Configuration cfg = new Configuration().configure();
		factory = cfg.buildSessionFactory();
	}

	public static final void main(String[] args) {
		try {

			Game g1 = new Game("BF2", 39.99, 5);
			Game g2 = new Game("AoE3", 129.99, 45);
			Game g3 = new Game("BF3", 139.99, 15);

			HashSet games1 = new HashSet();
			games1.add(g1);
			games1.add(g2);
			games1.add(g3);
			HashSet games2 = new HashSet();
			games2.add(g1);
			games2.add(g3);

			Player p1 = new Player("jarek", 26, games1);
			Player p2 = new Player("ewelina", 25, games2);

			System.out.println(p1.getGames());
			System.out.println(p2.getGames());

			/* open a Hibernate session and persist data */
			Session session = factory.openSession();
			Transaction tx = session.beginTransaction();
			session.save(p1);
			session.save(p2);
			tx.commit();
			session.close();

			/* Let's verify the persisted data */
			session = factory.openSession();
			tx = session.beginTransaction();

			List players = session.createCriteria(Player.class).list();
			System.out.println(players.size() + " player(s) found:");
			for (Iterator iter = players.iterator(); iter.hasNext();) {
				Player player = (Player) iter.next();
				System.out.println(player.getName() + " has following games: "
						+ player.getGames());
			}
			tx.commit();
			session.close();

			// load up the rulebase
			RuleBase ruleBase = readRule();
			WorkingMemory workingMemory = ruleBase.newStatefulSession();

			/* pass a hibernate session to the working memory as a global */
			session = factory.openSession();
			workingMemory.setGlobal("hibernateSession", session);

			workingMemory.fireAllRules();
			session.close();

		} catch (Throwable t) {
			t.printStackTrace();
		}
	}

	private static RuleBase readRule() throws Exception {
		// read in the source
		Reader source = new InputStreamReader(DroolsHibernateTest.class
				.getResourceAsStream("/Demo.drl"));

		PackageBuilder builder = new PackageBuilder();

		// this will parse and compile in one step
		builder.addPackageFromDrl(source);

		// get the compiled package (which is serializable)
		Package pkg = builder.getPackage();

		// add the package to a rulebase (deploy the rule package).
		RuleBase ruleBase = RuleBaseFactory.newRuleBase();
		ruleBase.addPackage(pkg);
		return ruleBase;
	}

}

The rule file can be created using the drools plug-in. Just click on the src/main/rules directory and from the menu File -> New -> Other… click Drools -> Rule Resource:

Demo.drl

package eu.kijanowski.drools.hibernate

global org.hibernate.Session hibernateSession;

rule "hibernate_from"
	when
		game:Game() from hibernateSession.createQuery("select games from Player p where p.age >= :age").setProperties( {"age" : 18 }).list()
	then
		System.out.println("The game "+game.getName() +"is owned by "+game.getPlayers());
end

How does it work?

Let’s have a look at the global keyword in the rule file. This allows us to provide the rule engine with constants and variables from outside. Potential usecases are:

return results back to the application
access services, like Hibernate, JMS, file writers, email senders, etc.

What’s worth to know is that you should never change a global, when you use it in the condition part (LHS) of a rule. Moreover globals are not designed to share any data between rules, this can be done via facts living in the working memory.

The condition element from allows to access data from other sources than the working memory. These can be Collectins, Maps and results coming from called methods. In our scenario we’ve created a query and received a list of games.

Results

After running our example (Run as -> Java Application) the console will show:

Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment 

INFO: Hibernate 3.2.6
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment 
INFO: hibernate.properties not found
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment buildBytecodeProvider
INFO: Bytecode provider name : cglib
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment 
INFO: using JDK 1.4 java.sql.Timestamp handling
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Configuration configure
INFO: configuring from resource: /hibernate.cfg.xml
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Configuration getConfigurationInputStream
INFO: Configuration resource: /hibernate.cfg.xml
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.Configuration addResource
INFO: Reading mappings from resource : eu/kijanowski/drools/hibernate/model.hbm.xml
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindRootPersistentClassCommonValues
INFO: Mapping class: eu.kijanowski.drools.hibernate.Player -> PLAYERS
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindCollection
INFO: Mapping collection: eu.kijanowski.drools.hibernate.Player.games -> PLAYERS_GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindRootPersistentClassCommonValues
INFO: Mapping class: eu.kijanowski.drools.hibernate.Game -> GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindCollection
INFO: Mapping collection: eu.kijanowski.drools.hibernate.Game.players -> PLAYERS_GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.Configuration doConfigure
INFO: Configured SessionFactory: null
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: Using Hibernate built-in connection pool (not for production use!)
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: Hibernate connection pool size: 1
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: autocommit mode: false
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: using driver: org.postgresql.Driver at URL: jdbc:postgresql://localhost/droolsdb
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: connection properties: {user=droolsuser, password=****}
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: RDBMS: PostgreSQL, version: 8.2.5
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC driver: PostgreSQL Native Driver, version: PostgreSQL 8.2 JDBC3 with SSL (build 508)
Jun 14, 2008 8:58:12 AM org.hibernate.dialect.Dialect 

INFO: Using dialect: org.hibernate.dialect.PostgreSQLDialect
Jun 14, 2008 8:58:12 AM org.hibernate.transaction.TransactionFactoryFactory buildTransactionFactory
INFO: Transaction strategy: org.hibernate.transaction.JDBCTransactionFactory
Jun 14, 2008 8:58:12 AM org.hibernate.transaction.TransactionManagerLookupFactory getTransactionManagerLookup
INFO: No TransactionManagerLookup configured (in JTA environment, use of read-write or transactional second-level cache is not recommended)
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Automatic flush during beforeCompletion(): disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Automatic session close at end of transaction: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC batch size: 15
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC batch updates for versioned data: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Scrollable result sets: enabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC3 getGeneratedKeys(): disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Connection release mode: auto
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Default batch fetch size: 1
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Generate SQL with comments: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Order SQL updates by primary key: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Order SQL inserts for batching: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory createQueryTranslatorFactory
INFO: Query translator: org.hibernate.hql.ast.ASTQueryTranslatorFactory
Jun 14, 2008 8:58:12 AM org.hibernate.hql.ast.ASTQueryTranslatorFactory 
INFO: Using ASTQueryTranslatorFactory
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Query language substitutions: {}
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JPA-QL strict compliance: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Second-level cache: enabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Query cache: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory createCacheProvider
INFO: Cache provider: org.hibernate.cache.NoCacheProvider
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Optimize cache for minimal puts: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Structured second-level cache entries: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Echoing all SQL to stdout
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Statistics: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Deleted entity synthetic identifier rollback: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Default entity-mode: pojo
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Named query checking : enabled
Jun 14, 2008 8:58:12 AM org.hibernate.impl.SessionFactoryImpl 
INFO: building session factory
Jun 14, 2008 8:58:12 AM org.hibernate.impl.SessionFactoryObjectFactory addInstance
INFO: Not binding factory to JNDI, no JNDI name configured
Jun 14, 2008 8:58:12 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: Running hbm2ddl schema export
Jun 14, 2008 8:58:12 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: exporting generated schema to database
Jun 14, 2008 8:58:13 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: schema export complete
[BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99, AoE3 with 45 levels for 129.99]
[BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select nextval ('player_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('player_id_seq')
Hibernate: insert into PLAYERS (NAME, AGE, PLAYER_ID) values (?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into PLAYERS (NAME, AGE, PLAYER_ID) values (?, ?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: select this_.PLAYER_ID as PLAYER1_0_0_, this_.NAME as NAME0_0_, this_.AGE as AGE0_0_ from PLAYERS this_
2 player(s) found:
Hibernate: select games0_.PLAYER_ID as PLAYER1_1_, games0_.GAME_ID as GAME2_1_, game1_.GAME_ID as GAME1_2_0_, game1_.NAME as NAME2_0_, game1_.PRICE as PRICE2_0_, game1_.LEVELS as LEVELS2_0_ from PLAYERS_GAMES games0_ left outer join GAMES game1_ on games0_.GAME_ID=game1_.GAME_ID where games0_.PLAYER_ID=?
jarek has following games: [AoE3 with 45 levels for 129.99, BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select games0_.PLAYER_ID as PLAYER1_1_, games0_.GAME_ID as GAME2_1_, game1_.GAME_ID as GAME1_2_0_, game1_.NAME as NAME2_0_, game1_.PRICE as PRICE2_0_, game1_.LEVELS as LEVELS2_0_ from PLAYERS_GAMES games0_ left outer join GAMES game1_ on games0_.GAME_ID=game1_.GAME_ID where games0_.PLAYER_ID=?
ewelina has following games: [BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select game2_.GAME_ID as GAME1_2_, game2_.NAME as NAME2_, game2_.PRICE as PRICE2_, game2_.LEVELS as LEVELS2_ from PLAYERS player0_ inner join PLAYERS_GAMES games1_ on player0_.PLAYER_ID=games1_.PLAYER_ID inner join GAMES game2_ on games1_.GAME_ID=game2_.GAME_ID where player0_.AGE>=?
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game BF2is owned by [jarek, ewelina]
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game BF3is owned by [jarek, ewelina]
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game AoE3is owned by [jarek]
The game BF2is owned by [jarek, ewelina]
The game BF3is owned by [jarek, ewelina]

Summary

This article shows how you can easily integrate Hibernate with the Drools rule engine. This allows you to reason over data, which does not only live in the working memory, but also in an external database.

Introduction to Drools: Rules fall from your eyes

Jaroslaw Kijanowski — Thu, 10 Jul 2008 22:25:55 +0000

One of our long-time writers introduced us to Jaroslaw, a JBoss QA Engineer based in Poland, and mentioned that he’d been working on some documentation we might find interesting. And, boy, do we! This first piece de-mystifies the complex world of rules engines. Whether you call it Drools, or JBoss Rules, or JBoss Drools… you still might want to know what it does and how it functions in your technical environment. (Not to mention that it’s just all kinds of logical and interesting–if you like brainteaser word puzzles or abstract math questions, this qualifies as pleasure reading.)

This article is presented here in its entirety (with a trackback). The original can be found on Jaroslaw’s site. This article is also available in German and Polish.

Justification:

Either you’re a developer, architect or a business analyst, it’s worth to get familiar at least with the first chapter of this article. It contains an introduction into the world of rule engines, which increase the readability of certain applications and make them easier to manage and to maintain. It applies to apps that take decisions, which depend on events or a state of some objects.

Abstract:

This article contains an introduction to rule engines, a description of an installation of Eclipse IDE and a guide how to configure Eclipse with the Drools Workbench plug-in.

A Rule Engine
Drools
Advantages of the Drools rule engine
BRMS
Production rules vs. events
Let’s get started!
What happened?
Summary

A Rule Engine

A rule engine is a piece of software, which having some knowledge is able to perform conclusions. Knowledge and inferences are stored in rules, which are called production rules. In other words, production rules consist of conditions and actions, which are executed when their conditions are true. Besides that there’s a working memory, which stores all objects we may want to use while making a decision. The state of this memory can vary, because actions can add, delete or change existing objects. Moreover rules can get into a conflict. This happens when there are more than one rule which are true, at the same time. Then conflict resolution is provided by the agenda. It arranges the order of actions, which has been selected to be run. The agenda is an important part of a rule engine, because the execution of an action may invalidate a rule and in consequence cancel another action. To sum it up, a rule engine can be presented as follows:

Rule engines perfectly fits to:

calculate a discount of orders based on the amount or price
determine an insurance policy dependent on the age of the driver and the value of the car
make a diagnosis
detect imminence of failure
solve riddles

Drools

One of the open source implementations of a rule engine is Drools. It’s a Java library distributed under the Apache license. It’s available as as a binary and a source download. You can get it and use in your applications for free.

The heart of a rule engine is an inference engine. Its job is to match facts and rules (pattern matching) to make conclusions which ends in running actions. This matching is done by the RETE algorithm, which has been extended by object oriented concepts.

As I already mentioned, knowledge is presented in form of production rules. Knowledge representation, which is a way to provide the rule engine with data, is based on FOL - first order logic. FOL allows to evaluate expressions like 2 + 3 == 5 or customer.age > 17.

The two main parts of a production rule are its condition(s) and action(s):

when
	Customer (age > 17)
	then
	System.out.println("Customer is full age");

The rule above is going to evaluated as true for all those facts, which represents full age customers. A similar sql query would look as follows:

SELECT * from Customers c WHERE c.age > 17

There are two ways to determine the truth of a rule (condition) and run its action in consequence. Forward chaining is driven with facts. Rules are checked, which conditions are true for facts being in the working memory. The process of pattern matching finishes, when there are no more rules left, whose conditions are true. Backward chaining on the other hand is a goal
driven approach. Only those rules are checked, whose actions can be matched with a goal. If that is the case, conditions of that rule are evaluated.

Advantages of the Drools rule engine

separates your application from conditions which control the flow
- rules are stored in separate files
- rules can be modified by different groups of people
- changing rules does not require to recompile or to redeploy the whole application
- putting all rules into one place makes it easier to control or manage the flow of the application
rules can replace complex if - then statements in an easy and readable way
- the rule language is not very difficult to learn
- a plug-in for Eclipse IDE makes it easier to write rules and allows to have a look at the RETE tree
problems are not solved using a complicated algorithm, but via rules, which are easier to read and understand than
code
- with declarative programming you are focused on WHAT you are solving, and not HOW
- a group of problems can be easily solved with rules, where the algorithmic approach may be unusable (too complex, too time consuming, etc)
access to the reasoning process allows you to understand why a particular decisions has been made

Summing up a rule engine should be considered when the solution of a problem seems complex or simply the algorithm contains a lot of it - then or switch statements. Rules should be also taken into account, when logic that drives your application often changes or has to be managed by people who don’t (or shouldn’t) have access to the application itself (to recompile/redeploy it).

BRMS

Drools is not just a rule engine. It provides also an application for managing rules, called Business Rules Management System. It allows to create, modify, delete, branch and persist rules. Moreover it’s possible to assign roles to users and a login mechanism and LDAP integration makes it easy to introduce security. So for example, a business analyst may have access to modify a rule, a developer on the other hand may be able only to read it. A BRMS is a single point of truth.

Production rules vs. events

Production rules consists mainly of conditions (when) and actions (then), e.g. when there’s a customer, who has a driving license for less than 5 years, then offer her an expensive insurance. Other type of rules are events (event condition action). In that case a rule engine looks for event patterns to match registered events. An event may be selling the last item or a breakdown of traffic lights. Another difference is the moment, when actions are executed. In the production rules environment, it’s the developer, who decides, when the rule engine is going to fire all actions. However, when working with events, an action is fired, when the associated event did happen.

Let’s get started!

… and install an IDE. I’ve chosen Eclipse, because it’s good enough and Drools provides a plug-in for writing rules.

Eclipse IDE, Eclipse IDE for Java EE Developers (eclipse-jee-europa-winter-linux-gtk.tar.gz)

After you’ve downloaded it, extract and start Eclipse. From the menu click on Help -> Software Updates -> Find and install… -> Search for new features to install -> New Remote Site…

You can find the URL on the Drools downloads page under “Drools IDE Update Site”. It’s a link to the plug-in. For Drools 4.0.7 Eclipse Workbench for Europa 3.3 it is http://downloads.jboss.com/drools/updatesite3.3/

We choose OK and Finish. Eclipse will show the search results:

Click on Next, accept the license and choose Finish, to start to download the plug-in. After that Eclipse will show another window, where we click on “Install all”. When asked for a restart we click on “Yes”. To verify a successful installation of the plug-in, make sure a new Drools icon showed up in the toolbar.

Let’s have a look at our first Drools application. Click on the Drools “head” and choose “New Rule Project”.

Type a name for the project and click Finish. The Drools plug-in creates a standard layout and provides all the necessary libraries to get started. To run this application click on com.sample.DroolsTest and press “Shift + Alt + X” and then “J”. The console will show th following:

Hello World
	Goodbye cruel world

What happened?

This example has been described in the Drools documentation. I’m not going into detail what’s happening in DroolsTest.java, where the rule engine is initialized and rules are read. The more interesting part is the rule file itself, Sample.drl.

This file has two rules. At the beginning, the working memory contains one object of the class Message, whose fields message and status are set to “Hello World” and “0″. When fireAllRules() is called, all actions are going to be executed. It’s worth to note that conditions of rules are evaluated when an object is added into the working memory. The condition of the rule called “Hello World” is true, because there is an object in the working memory, which is a Message and has a status equal to “0″. Hence actions of this rule are going to be run. As a result, the status and message fields of that Message object are going to be modified. The update() command forces the rule engine to evaluate its rules again. This time the second rule’s condition is true and appropriate actions are executed.

Summary

This short introduction into the world of rule engines and the chosen implementation Drools showed their main characteristics and some potential fields of use. To get more familiar with this software I would suggest to read the Drools documentation.

Red Hat Magazine

JBoss Drools how-to: Tuning Guvnor, part 2

Use OpenLDAP as a user repository

Use MySQL as a data repository

Enable SSL

How to use a secured Guvnor package

Summary

Open source telephony: a Fedora-based VoIP server with Asterisk

Prerequisites

Configuring the Asterisk PBX

Configuring LDAP

Configuring the Ekiga VoIP client

Configuring a Cisco VoIP telephone

Configuring voicemail

Conclusion

NetworkManager: Secret weapon for the Linux road warrior

What is NetworkManager?

How is the NetworkManager software deployed on the system?

How does NetworkManager work?

Wired network

Wireless Network

WWAN network (3G/EVDO/HSDPA/RTTx1/EDGE)

VPN connectivity

What else can NetworkManager do?

How can I best use NetworkManager in the field?

The student is now the master

More information

JBoss Drools meets Hibernate

Justification:

Abstract:

Related articles

Introduction to Drools: Rules fall from your eyes

Justification:

Abstract:

Related articles