2.1. What is it?

OpenH323 is an open source implementation of the H.323 protocol suite. As such, it can directly interoperate with Microsoft NetMeeting. At the time of this writing (October 2000), OpenH323 is still early in its development cycle; buggy and in flux, but useful.

OpenH323 consists of several C++ libraries and some C++ client programs.

The most useful client programs are:

OpenH323 presently (October 2000) supports audio codecs G.711, G.723.1, LPC-10, and GSM 06.10, as well as video codec H.261.

2.2. Why is it needed?

OpenH323 is needed only if you want to make audio/video connections with NetMeeting clients directly from your Linux system. It is not needed to provide LDAP directory service to NetMeeting clients.

2.3. Where to get it?

The main site is http://www.openh323.org/ and contains links to a download page, mirror sites, mailing lists, and other resources.

OhPhone, OpenAM, and PSTNgw are available as part of the standard distribution, in both source and executable formats. forwarder and openmcu are presently (December 2000) only available from the CVS archive, as modules named "forwarder" and "openmcu".

2.4. Installation

For OhPhone, OpenAM, and PSTNgw, download the executables. If you want to build from source, perhaps because you need forwarder or openmcu, you'll need the source code to the programs, as well as to the pwlib and openh323 libraries. Compilation instructions are available on the openh323 website.

2.5. Gatekeepers

OpenH323 doesn't provide any gatekeepers itself, but several are under construction based on its libraries. As of the end of 2000, most of them are actively under development and quite primitive. I haven't used any of them myself, but you want may to examine the following links:

• OpenGatekeeper

• OpenH323 Gatekeeper

• OpenGatekeeper H323 Proxy

3.1. What is it?

Each NetMeeting client can register with an LDAP server and has a directory window that lists other NetMeeting clients registered with the same server. The NetMeeting directory kit is an extension to the OpenLDAP server that provides directory service to NetMeeting clients.

3.2. Why is it needed?

While NetMeeting can connect directly to another H.323 device by specifying an IP address or DNS name, normally you'll want to use an LDAP directory server. Using an LDAP server lets users see a directory listing of available destinations, and is required if you need to resolve aliases, for example if you want to serve multiple H.323 destinations from a single IP address. A directory server isn't required to connect directly from Linux to a NetMeeting client; use OpenH323 for this.

The NetMeeting client violates the LDAP protocol in several ways, so you'll have problems if you try using a standard LDAP server. The NetMeeting directory kit corrects for these problems and allows an OpenLDAP server to be used for NetMeeting directory service.

3.3. How it works

                 Block diagram of NetMeeting directory kit

___________________         _______    __________________        ______________
|    LDAP server  | request |      |   |   LDAP server  | request|            |
|                 | <-------| Perl |<--|                | <------| NetMeeting |
| on private port |         |script|   | on public port |        |  client    |
|  (i.e, 2345)    |-------> |      |-->|     389        |------->|            |
|                 | reply   --------   |                |  reply --------------
|                 |                    |                |      
-------------------                    ------------------

The directory server consists of a 'master' LDAP server to receive requests, a Perl script to correctly interpret the Microsoft NetMeeting requests and, after interrogation of a 'hidden' LDAP server, formats the results in a way that the NetMeeting client can understand. OpenLDAP's 'shell backend' is used to call the Perl script. A custom schema is also required. The script presently handles all of the above problems, with the exception of timing out entries, which it doesn't do.

3.4. Where to get the software

First of all you need to get the OpenLDAP software.

Pre-built OpenLDAP software (i.e, RPMs) won't work unless configured with support for the shell backend.

You can download OpenLDAP from the main site located at ftp://ftp.OpenLDAP.org/pub/OpenLDAP/openldap-release/ or any mirror. I've successfully used OpenLDAP 2.0.7.

The NetMeeting directory kit is available from http://www.freesoft.org/software/NetMeeting/download.

You need Perl 5, available from http://www.perl.org, but already included in all common Linux distributions. You will also need the Net::LDAP module from the Perl CPAN archive, which can be downloaded and installed directly from Perl:

[root@y2k baccala]# perl -MCPAN -e shell

cpan shell -- CPAN exploration and modules installation (v1.58)
ReadLine support enabled

cpan> install Net::LDAP

... much output omitted ...

  /usr/bin/make install -- OK

cpan>

If you've never used CPAN before, you will be prompted first with a series of configuration questions. Once CPAN is configured, the Net::LDAP module will be downloaded, compiled, and installed automatically.

3.5. Installation

Building OpenLDAP will require approximately 60 MB of free disk space. Untar OpenLDAP and configure it.

Be sure to specify the shell backend function "--enable-shell"

I also recommend specifying "--disable-debug" to prevent OpenLDAP from exiting if an assertion fails.

bash$ ./configure --enable-shell --disable-debug
      

Now build and install it with:

bash$ make

... much output omitted ...

bash# make install
      

It will normally install under /usr/local:

Once OpenLDAP has been installed, next install the NetMeeting directory kit. Untar ndk.tgz. It contains these files:

Copy netmeeting.perl to the /usr/local/libexec directory, netmeeting.schema to the /usr/local/etc/openldap/schema directory, and copy both slapd.conf and slapd2.conf to the /usr/local/etc/openldap directory.

Be sure to use core.schema.patch to patch openldap's core schema in the /usr/local/etc/openldap/schema directory:

bash$ cd /usr/local/etc/openldap/schema
bash$ ls
corba.schema   inetorgperson.schema  misc.schema        nis.schema
core.schema    java.schema           nadf.schema        openldap.schema
cosine.schema  krb5-kdc.schema       netmeeting.schema
bash$ cp core.schema core.schema.bak
bash$ patch core.schema < ~/core.schema.patch
      

Create the directory /usr/local/var/openldap-netmeeting to store the LDAP database, and make it world writable.

Especially if you're using directories from the samples, edit slapd.conf and slapd2.conf and verify their configuration settings.

You will need to run two copies of slapd. One uses slapd.conf and must be started as root, since it binds to port 389. The -u option can be specified to cause slapd to chown to an unprivileged user after binding the port (a wise precaution). The other slapd uses slapd2.conf, binds to an unprivileged port, and only needs sufficient privilege to write the database directory.

bash# /usr/local/libexec/slapd -f /usr/local/etc/openldap/slapd.conf -u nobody
bash$ /usr/local/libexec/slapd -h ldap://localhost:2345/ -f /usr/local/etc/openldap/slapd2.conf
      

You now have to initialize the slave database with a single entry. This is only done once, by running the initialize script included in the kit. The "rootdn" and "rootpw" entries are in the slave config file to allow access for the initialization script, and must match the -D and -w options in the script. Once you've initialized the database with a single parent entry, you can comment out the "rootdn" and "rootpw" lines from slapd2.conf, though this is not critical.

The server should now be up and running. For systems with /etc/rc.d/ style initialization scripts (like RedHat), the slapd.rc is provided to automate the starting and stopping of the slapds.

3.6. Server Security

As shown above, I run both slapds as an unprivileged user, minimizing the possibility of compromised security due to a bug in either the server software or the Perl script. Of course, this requires the database directory to be world writable so that the unprivileged slave server can update it. This isn't as glaring a hole as it might first appear, since the NetMeeting clients themselves use no authentication. Thus, even if the database directory were better protected, anyone on a local or remote host could use LDAP client programs to delete or modify any of the database entries.

3.7. LDAP issues with Windows 2000

Recent NetMeeting releases initially attempt to connect to the LDAP directory server on port 1002. As described in a TechNet chat,

Prior to Windows 2000, an ILS server would listen on port 389 for NetMeeting clients. When an ILS server is set up on a Windows 2000 machine, it will default to port 1002.

3.8. Interoperation with other LDAP service

The instructions above assume that your LDAP server is only being used for NetMeeting directory service. Yet what if you want to use a single server for both NetMeeting directory service and other LDAP service? Only one server can be bound to port 389, but OpenLDAP allows multiple database sections to be specified in its configuration file, each serving different parts of the LDAP namespace. NetMeeting uses only the "objectClass=RTPerson" subtree, so as long as you avoid this subtree, you can configure additional database sections to serve other subtrees with other databases. The biggest problem you are likely to encounter is the custom NetMeeting schema, which conflicts slightly with the standard schema. Since the NetMeeting schema is more liberal than the standard schema, I'd suggest commenting out the conflicting parts of the standard schema. NetMeeting clients won't work with the standard schema. See the LDAP RFCs and the OpenLDAP documentation for more information about configuring LDAP servers.

4.1. Direct Connection

You can use OpenH323's ohphone program to connect directly to a NetMeeting client. Specify the -n option to indicate that you're not using a gatekeeper, and either the DNS name or IP address of the NetMeeting client:

bash$ ohphone -n 208.130.48.22
      

You can also start ohphone to receive incoming calls from NetMeeting clients:

bash$ ohphone -n
      

See the ohphone documentation for more information on its additional features, including video conferencing, codec selection, and auto-answer.

4.2. Directory Operation

Make sure you have an LDAP server running the NetMeeting directory kit, as described above.

On the NetMeeting client, select the Tools -> Options menu item to display a configuration dialog. Under the "General" (NetMeeting 3) or "Calling" (NetMeeting 2) tab, there will be a section for "Directory Settings". Here you can enter the IP address or DNS name of the server. The client will then attach to the server and register itself either automatically, if the "Log on to directory server when NetMeeting starts" checkbox is selected. You can also log on to the directory server manually, by selecting Call -> Log on .

If the user selects Call -> Directory , a directory window will be displayed showing all users registered on the LDAP server. Double-clicking on one of the names will initiate a connection to that user.

Querying the NetMeeting LDAP server from Linux can be done, but is tricky because the client's IP address is stored in decimal, and I don't mean dotted decimal. For example, the IP address 63.216.69.197 is stored as 3309688895. Here's some Perl code to convert back and forth from the NetMeeting IP address format:

# Convert $addr (IP address or DNS name) to a NetMeeting decimal IP address

use Socket;
$bytestring = inet_aton($addr);
if (defined $bytestring) {
    ($sipaddress) = unpack('V', $bytestring);
} else {
    die "Can't resolve $addr\n";
}

# Convert $sipaddress (from a NetMeeting LDAP server) into dotted decimal form

$packedipaddr = pack 'V', $sipaddress;
$ipaddress = join '.', unpack('C4',$packedipaddr);

Included with the NetMeeting directory kit is nmdirectory, a simple Perl/Tk script to query a NetMeeting LDAP server and display the clients registered with it. It's very primitive, and doesn't work well with large databases, but provides a rudimentary example of how to interpret search results from a NetMeeting LDAP server.

4.3. Linking From A Web Page

Microsoft Internet Explorer understands URLs with a "callto:" scheme that specify NetMeeting destinations in one of two forms. When a link with a "callto:" URL is selected, Internet Explorer runs NetMeeting and directs it to connect to the specified destination.

The first URL form, "callto:destination", where 'destination' is either an IP address or a DNS name, causes NetMeeting to open an H.323 connection to port 1720 on 'destination'. Use this form to connect directly to another NetMeeting or OpenH323 client.

The second URL form, "callto:server/alias", causes a directory lookup on LDAP server 'server', searching for a CN attribute of 'alias'. Assuming a match is found, a connection is made to the IP address specified in the entry's sipAddress attribute. NetMeeting clients, by default, register their user's E-mail addresses in the CN attribute. Use this form to perform a directory lookup based on E-mail address.

4.4. Permanent Directory Entries

NetMeeting clients aren't the only source of LDAP directory entries. In particular, permanent directory entries can be manually inserted into the LDAP server using the OpenLDAP client tools. Assuming the attributes are specified properly, these entries will then appear in NetMeeting directory listings and can be used as targets in "callto:" URLs. This is useful when working with OpenH323 clients that don't register themselves by default with the LDAP server.

To simply creating directory entries, the nmaddentry script is included in the NetMeeting directory kit. Run it without arguments for a usage message. For example, if you've started ohphone on "y2k.freesoft.org", you can register it with the LDAP server on "ils.freesoft.org" using alias "baccala@freesoft.org" like this:

bash$ nmaddentry -h ils.freesoft.org baccala@freesoft.org y2k.freesoft.org
Successfully added cn=baccala@freesoft.org, objectclass=rtperson
bash$
      

This entry will now appear in NetMeeting directory listings and can be addressed as "ils.freesoft.org/baccala@freesoft.org". The entry will automatically timeout after 30 minutes. The -p switch creates a permanent directory listing that won't time out, but this only works on OpenLDAP servers using the NetMeeting directory kit. To remove a permanent entry, use the ldapdelete program included with the OpenLDAP distribution, specifying the LDAP Distinguished Name returned by nmaddentry:

bash$ ldapdelete -h ils.freesoft.org 'cn=baccala@freesoft.org,objectclass=rtperson'
bash$
      

4.5. Serving Multiple Aliases

The attributes registered by a NetMeeting client include 'sport', the TCP port number it listens on for incoming H.323 requests, but since this attribute is never retrieved in search requests, it isn't as useful as it first appears. In fact, NetMeeting always opens H.323 connections to the default port (1720), which raises the question of how to serve multiple aliases from a single IP address.

The key to doing this is the forwarder program, included in the OpenH323 CVS archive. forwarder listens for connections on port 1720, and can be configured to redirect them based on the alias being called. This allows calls for each alias to be sent to a unique port number, where a program like ohphone or openam is listening.

To use aliases, an LDAP directory is required, with an entry for each alias. Each alias entry should specify a 'cn' attribute with the alias name, and a 'sipAddress' attribute with the IP address of the host where forwarder is listening.

I've successfully configured a single host to act as a combination LDAP server (on port 389), forwarder (on port 1720), and ohphone and openam clients on various private port numbers and remote systems.

4.6. Using the Answering Machine

The OpenH323 answering machine, openam, will listen for incoming H.323 connections, play a pre-recorded message, and then record any audio sent to it into a file. It can optionally be configured to run another program at the end of the call, to email the recorded audio, perhaps.

It's usefulness is currently (December 2000) limited by the lack of a gatekeeper program clever enough to redirect calls to it if there's no answer at the main address. Thus, it will only act as an answering machine if the ohphone program is running at the main address, and has been configured to redirect calls to another address, using the --forward-no-answer and --forward-busy options.

4.7. Conference Calls

The openmcu program, in the OpenH323 CVS archive, implements an H.323 Multipoint Control Unit (MCU). Multiple NetMeeting or ohphone clients can connect to the MCU and form a conference call. As of December 2000, the quality and reliability of the connection is problematic, but hopefully this will improve.

4.8. Routing Calls Through NAT

Special support is required on a NAT (IP Masquerade) router to allow H.323 traffic to pass through. If the NAT router is running Linux, two masquerading modules are available:

• http://www.coritel.it/coritel/ip/sofia/nat/nat2/nat2.htm

• http://netmeetingmasq.sourceforge.net/

I have not tested either of these modules.

4.9. Custom Configurations

The server capabilities can be customized by modifying the 'netmeeting.perl' script. For example, calls for stale entries could be redirected to an "forwarder" configured to hand off to "openam" answering machines. Thus, calls to a unavailable user would be answered and recorded for later playback.

As OpenH323's development continues, it's expected that these techniques will become more sophisticated, for example by ringing the user first and only forwarding to an answering machine if there's no answer after a given time. Such functionality would most likely be placed in a gatekeeper.