Hack 89. Build an H.323 Gatekeeper Using OpenH323
H.323 is a VoIP signaling protocol that predates SIP by five or six years, but its use in commercial telephony and desktop conferencing apps (NetMeeting, for instance) is widespread.
OpenH323 is an open source implementation of the H.323 signaling protocol suite, managed by Quicknet Technologies, the same company that makes the Internet Phone Jack line of analog interface cards. OpenH323 is distributed in binary and source code forms for both Linux and Windows, though a crafty hacker should be able to get it running on a BSD-ish OS, too.
This project will allow a Microsoft NetMeeting H.323 softphone and an OpenH323 OhPhone softphone to place calls through an H.323 gatekeeper running on a Linux computer. In this example, I'll use Microsoft NetMeeting on Windows XP and OhPhone on Mac OS X.
Although OpenH323 provides a framework of tools for developing H.323 servers and endpoints, it also natively implements a complete H.323 gateway, MCU, and endpoint. Here's a partial list of software packages that accompany OpenH323:
Each requires the base distributions of OpenH323 and its prerequisite, PWLib, a project-specific class library.
7.3.1. Installing OpenH323
A Pentium III clocked at 600 MHz should be sufficient to handle the role of a small-scale H.323 gatekeeper. The PC should be running Linux (though H.323 is also Windows compatible) and can be the same PC that runs Asterisk, if you like.
The best place to get OpenH323 is from its maintainer's web site, http://www.openh323.org/code.html. Compiling all of these elements is straightforward on Linux. (If you want to run OpenH323 on Windows, use the precompiled executables. The instructions I'm providing are for Linux.)
First, download and install PWLib. Save pwlib_1.5.2.tar.gz (or the filename appropriate for the version you download) to /root as the root user. Then, unzip and untar it:
# tar xvzf pwlib_1.5.2.tar.gz
Now, you'll need to set some environment variables so that the OpenH323 software knows where to find the PWLib libraries:
# PWLIBDIR=$HOME/pwlib # export PWLIBDIR # OPENH323DIR=$HOME/openh323 # export OPENH323DIR # LD_LIBRARY_PATH=$PWLIBDIR/lib:$OPENH323DIR/lib # export LD_LIBRARY_PAT
If you plan to make this H.323 setup permanent, you should add the preceding environment variable commands to .bash_profile in /root. Now, build the PWLib distribution by using make:
# cd $PWLIBDIR # ./configure # make opt # make install
Next, download the main OpenH323 file to /root. Then, unzip and untar it, substituting the filename that's appropriate for the version you download:
# tar xvzf openh323_1.12.2.tar.gz
Now, build OpenH323:
# cd $OPENH323DIR # ./configure # make opt # make install
The developers recommend a 128 MB swap partition to complete the build error-free. This need is minimized if you have enough physical RAM; 256 MB of physical RAM should be plenty. This build could run for 30 minutes or more, so enjoy a delicious beverage.
7.3.2. Set Up the GNU Gatekeeper
Once the OpenH323 build is finished, you need to download and compile the OpenH323 Gatekeeper (gnugk) software. Don't confuse this with the opengk software that comes as a part of the OpenH323 distribution. This gatekeeper comes from a different source altogether but is built using the same libraries as opengk. The big difference is that gnugk is a much more complete implementation of a gatekeeper, and opengk is a reference example and is not very useful yet.
First, download and save the gnugk source code from http://www.gnugk.org/h323download.html into /root. It will be named gnugk-2.0.8.tgz or something similar. After the download is finished, build the gnugk package:
# tar xvzf gnugk-2.0.8.tgz # cd openh323gk # make opt
Now, issuing the gnugk command will launch the gnugk gatekeeper. If you receive an error indicating shared libraries cannot be located, make sure you've got those environment path variables set in your login profile. If you run into compiler errors, try grabbing the x86 Linux executable from the gnugk site. Regardless of whether you compile it yourself, copy the contents of the package's bin directory into /usr/sbin and the contents of its etc directory into /etc, as follows:
# cd openh323gk # cp bin/* /usr/sbin # cp etc/gnugk.ini /etc
To install a sample config file that allows any endpoint to register with the gatekeeper, copy etc/proxy.ini also:
# cp etc/proxy.ini /etc
proxy.ini is far more permissive than the default configuration file, and it will allow you to register unauthenticated (i.e., passwordless) endpoints. Now, you can run gnugk with the config file in /etc by issuing the following:
# gnugk c /etc/gnugk.ini
7.3.3. Register an H.323 Softphone Using OhPhoneX
If you're using a Windows PC, chances are you already have Microsoft NetMeeting. This is a very capable softphone, and it works well with OpenH323. In fact, the next section describes how to set it up.
But since the OpenH323 project produces a phone, too, we'll use it. That phone is called OhPhone, and it's distributed as an executable for Linux, Windows (http://www.openh323.org/), and Mac (http://xmeeting.sourceforge.net/).
These examples use screen grabs from the Mac OS X version. The Linux and Windows versions have only a text-based UI, but for those platforms, GnomeMeeting and MS NetMeeting make great alternatives.
The first thing you'll need to do with OhPhoneX is access its Preferences menu option. The Gatekeeper tab of the Preferences window will allow you to specify a gatekeeper, username, password, alias, and E.164 address (phone number), as shown in Figure 7-1.
In Figure 7-1, the address of the gatekeeper is 10.1.1.10. The ID is a superficial, freeform ID used like caller ID. The User Alias/ID is required only if gnugk is configured for authenticating registration attempts. The password field is optional; its use is policy-dependent, as gnugk accepts blank passwords. Finally, the E.164 number is the phone number to which the endpoint is registering and, ultimately, the phone number that will be used to route calls to this softphone. Be sure to check the "Use gatekeeper" check box, too.
When you close the Preferences window, click the Start Phone button and then click the Console button. You'll see whether the softphone's registration attempt with the H.323 gatekeeper was successful. The console log of OhPhoneX, shown in Figure 7-2, contains the details of the registration attempt.
Now, if you register a second softphone from a second PC, you can call back and forth between them using the gatekeeper as the E.164 alias translator. This works the same way with H.323 hardphones. Callers dial the E.164 digits, and the gatekeeper provides the E.164 "resolution" that allows the software in the phone to do its H.225, H.245, and RTP signaling to facilitate the call.
Figure 7-1. OhPhoneX's Preferences window has all the options an H.323 endpoint could possibly need to register with a gatekeeper
Once a call is in progress, the Connection Stats window shows the status of the call in excellent detail, as in Figure 7-3.
7.3.4. Register an H.323 Endpoint Using NetMeeting
Microsoft NetMeeting is an H.323 softphone application that comes packaged with Windows Me, 2000, and XP. To run it on XP, however, you'll have to perform a slight hack to activate it. Select Start Menu Run, type conf, and click OK. Then, select "Put a shortcut to NetMeeting on my desktop in the wizard that follows. Once this is done, NetMeeting is activated on Windows XP just as it would normally be on Windows 2000.
To configure NetMeeting to register with the gatekeeper, inside NetMeeting click Tools Options. This will display the Options dialog, where you can click the Advanced Calling button. The Advanced Calling Options dialog box will appear, as in Figure 7-4. Check the boxes next to "Use a gatekeeper to place calls and "Log on using my phone number." In the "Phone number" field, enter the address of the gatekeeper, as well as the E.164 address you'd like to use.
Figure 7-2. OhPhoneX's console log can help you troubleshoot the registration process
Figure 7-3. OhPhoneX's Connection Statistics window tells you which codec your call has selected and how much bandwidth it's using
Figure 7-4. The NetMeeting Advanced Calling Options dialog box allows you to configure gatekeeper registration
Microsoft NetMeeting is a very worthwhile H.323 softphone, and it's quite customizable. It allows video calling as well as audio calling, and it has a built-in T.120 whiteboard and instant-messaging (text chat) applications. You can tweak the codec-selection preferences by choosing Audio from the Options dialog and then clicking Advanced. The codec-selection dialog is shown in Figure 7-5. If you're really looking to restrict codec selection, most compliant gatekeepers allow you to do it centrally.
7.3.5. Make the Call
Once both phones are registered with the gatekeeper, you can call between them using their E.164 numbers, since they're on the same zone. Now, if you like, download OpenAM from the OpenH323 project to set up an H.323-based personal message recorder.
Figure 7-5. NetMeeting ships with a selection of five codecs, including G.711 (uLaw/aLaw) and G.726 (ADPCM)