Installing and configuring Zaptel

Zaptel driver

Prerequisites

To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method):

sudo apt-get install zlib1g-dev libssl-dev bison debhelper

Specifically the last one (debhelper) can bring a whole slew of extra packages with it, a.o. build-essential, po-debconf, liburi-perl and patch, just to name a few.

Debian version of Zaptel

Next up is to get the zaptel source code, as is delivered with Debian Lenny. Note, however, that as of march 2009, this driver has a little bug in the ztdummy driver that prevents the driver to compile under a 2.6.28 kernel. If you have a custom kernel (i.e. not the Debian stock kernel) then skip down to the next section! For plain Debian Lenny:

sudo apt-get install zaptel-source

If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. module-assistant).

Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!
Debian has placed the source file package in /usr/src, and it's named zaptel.tar.bz2. Normally you would think about unpacking it with sudo tar xjvf and get going with the code that's in it. HOWEVER Debian has a really cool utility called the module-assistant. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones.

We start from the beginning:

• boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so
• as root, run module-assistant prepare. This checks the availability of your kernel source header files, creates a symlink /usr/src/linux that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. build-essentials).
• Then, again as root, run module-assistant auto-install zaptel (or abbreviate it to m-a a-i zaptel). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel.
• Some howto's now instruct you to run update-modules, but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either...
• If you have hardware installed, you now run genzaptelconf -svdM. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update /etc/modules, and finally create your hardware config file /etc/zaptel.conf; it probably will give you a nice error message too about not being able to write in the /etc/asterisk directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): genzaptelconf -svdM -c nl. The output is pretty clear in what the command finds, and what it does with that information.
• You may want to now edit the configuration file that's created for the channels. The configuration file should be /etc/zaptel.conf, and its contents could look like the file given below. However, you rarely need to edit this file by hand: genzaptelconf can handle this bit usually better than we can.

# Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER)
fxols=1
fxols=2
fxsks=3
# channel 4, WCTDM/0/3, no module.

# Global data

loadzone        = us
defaultzone     = us

• If you wish, you can create directory /etc/asterisk, and run the genzaptelconf again; that way you can see the zapata-channels.conf file that is created as well.
• If you now reboot (into the same kernel), then the dmesg command should confirm the presence of your Zaptel drivers with a short section like this:

Zapata Telephony Interface Registered on major 196
Zaptel Version: 1.4.11
Zaptel Echo Canceller: MG2

Furthermore, you can find lines like these, if you have hardware installed:

ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21
Port 1: Installed -- AUTO FXS/DPO
Port 2: Installed -- AUTO FXS/DPO
Port 3: Installed -- AUTO FXO (FCC mode)
Port 4: Not installed
VPM100: Not Present
Found a Wildcard TDM: Wildcard TDM410P (4 modules)

Digium Zaptel driver for your custom kernel

In March 2009 I decided to upgrade my custom-configured vanilla kernel from 2.6.27.5 to 2.6.28.9. After that, I found I couldn't compile the Debian Zaptel driver, because of an error in the compilation of ztdummy. The error looked something like this:

  CC [M]  /usr/src/modules/zaptel/kernel/ztdummy.o
/usr/src/modules/zaptel/kernel/ztdummy.c: In function 'ztdummy_hr_int':
/usr/src/modules/zaptel/kernel/ztdummy.c:203: error: 'struct hrtimer'
has no member named 'expires'
make[4]: *** [/usr/src/modules/zaptel/kernel/ztdummy.o] Error 1
make[3]: *** [_module_/usr/src/modules/zaptel/kernel] Error 2
make[3]: Leaving directory `/usr/src/linux-2.6.28'
make[2]: *** [modules] Error 2
make[2]: Leaving directory `/usr/src/modules/zaptel'
make[1]: *** [binary-modules] Error 2
make[1]: Leaving directory `/usr/src/modules/zaptel'
make: *** [kdist_build] Error 2

The solution to this was either to:

• go back to a 2.6.27 kernel (I didn't want to),
• get my hands on an updated Debian Zaptel package that was not released yet (zaptel 1:1.4.11~dfsg-4) (couldn't get it),
• find a way to patch the Debian Zaptel source code (couldn't figure out how),
• or use the latest Digium Zaptel driver from their website.

It turned out that even the latest Zaptel driver from Digium (version 1.4.12.1) couldn't compile because of this error. But after a while I found this solution: I downloaded the latest SVN snapshot from the Digium website (back then release r4636), instead of the tarball with the latest stable release (revision r4504), and manually compiled and installed that. The way to do that is (with only a little explanation):

# Get Subversion, and make sure we have three necessary packages
apt-get install subversion
apt-get install build-essential libnewt-dev libusb-dev
# Go to /usr/src and get the 1.4 branch for Zaptel from Digium, in
# the right revision
cd /usr/src
svn co --revision 4692 http://svn.digium.com/svn/zaptel/branches/1.4
mv 1.4 zaptel.r4692
# go in the source directory, and compile
cd zaptel.r4692
./install_prereq test
./install_prereq install
./configure
make
make install
# Make a configuration (only if it doesn't exist already!)
make config
# Now load the drivers
modprobe zaptel
modprobe wctdm24xxp
# Of course the last driver is specific to my TDM410p
# Check if it worked
ztcfg -vvv

Furthermore, in december 2009 I switched to kernel 2.6.32.2, and for that I needed subversion release 4692. To find info on the latest Zaptel commits, look at the archives of the zaptel-commits mailing list.

Zaptel tools

Next up, if you haven't yet done so during the preceding step, you now need to install the zaptel userland tools (v1.4.11 under Debian 5.0), which will in turn require fxload and libtonezone1. Installation is simply performed by

sudo apt-get install zaptel fxload libtonezone1

After installation, the zaptel driver checks for the existance of /etc/zaptel.conf. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message

zaptel : /etc/zaptel.conf fails test for exists and readable

This is in fact a friendly reminder that you first have to create this file, before you try to load the driver.

libpri installation

Asterisk needs the libpri package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named libpri1.0:

apt-get install libpri1.0