This guide was created to assist those trying to build and install the second edition of GNU Bayonne (to be referred to as GNU Bayonne 2) for the first time. GNU Bayonne 2 is a large and complex package, which can involve both hardware and software, as well as a number of additional software packages, each of which my need to be configured to successfully deploy a running server.
GNU Bayonne 2 itself is licensed as free software under the GNU General Public License. This means the source for this complete package is made available to the user, and the user is given specific rights to use and modify the sources provided – rights which are often denied in proprietary packages. GNU Bayonne itself depends on other parts of the GNU system, such as GNU Common C++ and GNU oSIP, which are also licensed as free software. This guide does not try to explain how to fully exercise these rights, but simply how to configure and install GNU Bayonne 2 as distributed through the GNU Project.
GNU Bayonne 2 is a fully portable server, which may be used under a large number of different 32 and 64 bit operating systems, and is not bound to any machine architecture. Hence, GNU Bayonne 2 may be used with machines that have Sparc, PowerPC, S/370 chips, or other architectures equally as well as on Intel-based commodity PC hardware. While GNU Bayonne 2 is very portable, this manual only tries to cover installation on POSIX operating systems, such as GNU/Linux, xBSD, Solaris, or MacOS X. The information here is not directly relevant to other platforms which GNU Bayonne 2 may also support, such as Microsoft Windows, QNX, or specialized realtime and embedded systems. Installation instructions specific to Microsoft Windows will be covered in a special guide which will accompany the GNU Telephony CAPE installer.
While GNU Bayonne 2 is a very large and complex service, it is built and installed in a manner that is no different from other GNU packages. GNU Bayonne 2 uses a “configure” script that is generated from Autoconf and uses Automake to generate Makefiles. This section will cover the basics to get you started, while the remaining sections will help you in building GNU Bayonne 2, based on specific configurations and platforms.
GNU Bayonne 2 differs from most software packages and services one may deploy on GNU/Linux systems in one key respect: to be useful, it may require computer telephony hardware. This hardware can take many forms, and comes in different telephone voice line capacities, as well as support for many different types and forms of telephone circuit interconnection. Bayonne may also be used for simply testing a soundcard, and can be used without physical hardware as an IP telephony application server. Most commonly, we assume GNU Bayonne 2 will be used as a voice application server that sits behind an existing telephone switch, such as an enterprise PBX system or an IP voice gateway. However, GNU Bayonne 2 can also be connected and used with the public telephone network directly.
Given these wide ranges of uses, all of which may depend on specific hardware products, with their own characteristics and capabilities, you'll first have to decide how, and for what purpose, GNU Bayonne 2 will be used for. Then, if you are building a traditional wired telephony application server, you will have to choose which vendor's hardware will be used with it, based on the intended deployment and on the capability or suitability of the various computer telephony hardware products which GNU Bayonne 2 supports.
If you already know how you intend to use GNU Bayonne 2, and already have the optional computer telephony hardware that you plan to use, it is strongly suggested that you skip ahead to the subsection of this manual that describes your hardware before going through the next few sections. In the hardware section (4), you will find information on what steps must be done to configure and install the drivers and/or libraries that come with your given hardware. These steps must often be done BEFORE you begin installation of GNU Bayonne 2 itself.
If you have not selected your computer telephony hardware yet, check the different hardware sections. You will get a good idea of what products, from each vendor, are supported by GNU Bayonne 2 and might meet your needs. However, we do not recommend any one hardware solution from any specific vendor over comparable solutions from other vendors. There is neither product reviews nor comparisons in the hardware section, just information on known issues of compatibility, configuration, and installation.
Once you have installed your computer telephony hardware and/or support for IP voice protocol stacks, and have verified that it is functional, as outlined in the relevant sections, you should proceed to the following section on building the server.
One of the first things you should do is create a “bayonne” user and
group account. The bayonne user account is the user account
that the Bayonne server will run under when started by “root”. This
can be created as a system account using something like
“adduser -r bayonne”. The bayonne group is used so that you can assign the
device nodes of your computer telephony hardware under group permission
with rw access under “bayonne”, and then assign individual user
accounts you may wish to access your computer telephony cards under to
the bayonne group.
You do not need a user or group named “bayonne” for this
purpose; you could run Bayonne under the same group and user id that
Apache uses, for example. The group and user that Bayonne runs under
are set in the file /etc/bayonne/server.conf. This setting may be
changed from its default
of “bayonne”, or left blank, in which case the server, when started
under root, will remain running under root. However, it is generally
advised to remove root permission from Bayonne in case of possible
security issues in the code.
The other reason to use a group assignment of “bayonne” and to
associate user accounts with the group is that Bayonne creates control
and data files that may be accessed under group “bayonne”. Hence,
if you want to administer your running Bayonne server that is started by
root, you can selectively enable other user accounts to do so by adding
them to the bayonne group, rather than having to do a su or login to
the bayonne user.
Before you can build and use GNU Bayonne 2, you must build and install GNU Common C++ 2, GNU ccAudio 2, and GNU ccScript 3. These packages are also part of the GNU system, and may be downloaded from https://ftp.gnu.org/ or any GNU mirror site. If you are using the Bayonne SIP driver, you will also need GNU ccRTP, oSIP, and eXosip. The following table provides links to your nearest mirror site.
| Package | Download area |
|---|---|
| GNU Common C++ 2 | https://ftpmirror.gnu.org/commoncpp/ |
| GNU ccAudio 2 | https://ftpmirror.gnu.org/ccaudio/ |
| GNU ccScript 3 | https://ftpmirror.gnu.org/ccscript/ |
| GNU ccRTP | https://ftpmirror.gnu.org/ccrtpp/ |
| oSIP | https://ftpmirror.gnu.org/osip/ |
| eXosip | https://download.sv.nongnu.org/releases/exosip/ |
| GNU Bayonne | https://ftpmirror.gnu.org/bayonne/ |
The first package you should download and build is GNU Common C++ 2. The other packages will not build unless it is installed.
After downloading GNU Common C++, you can unpack it with:
tar -zxvf commoncpp2-{VERSION}.tar.gz
Substitute VERSION with the version of your package.
To install GNU Common C++, enter the commoncpp2 directory you have unpacked
to, and run the “configure” script. For GNU/Linux systems, this script
can be run simply with ./configure. The default installation directory
is /usr/local. If you wish to install GNU Common to
/usr, then enter “./configure --prefix=/usr”. Once configure
completes, simply run make install.
Next, you should download the current versions of GNU ccScript 3 and GNU
ccAudio 2 (ccscript3 and ccaudio2). Unpack each package as above (2.3.1), and run the
configure script with the same options you selected when building GNU
Common C++ 2 (if any). Then simply run make install.
If you are going to use SIP, then you should download the current version of
GNU ccRTP. Unpack it as above, and run the configure script from the ccrtp
directory with the same options you selected when building GNU Common C++ 2
(if any). Then simply run make install.
Depending on your platform and needs, it will be useful to pre-install a
number of other packages. For GSM audio processing in ccAudio 2 and
Bayonne, you will want to install libgsm and its dev package (typically
“apt-get install libgsm1-dev” on Debian-based systems). For ODBC
database connectivity in ccScript 3 and Bayonne, you will want to install
unixODBC (typically “apt-get install unixodbc-dev” on Debian systems).
To generate class documentation, you will want Doxygen installed. For
creating Bayonne's PDF manuals you will need pdfLaTeX, as found in the
teTeX extras package. [In 2017, this package is part of the normal TeX
distribution (texlive-base in Debian).]
At this point, if you plan to use specific computer telephony hardware, then you should also have installed any device drivers, header files, and link libraries that were part of, or required by the computer telephony hardware you will be using. If you are using a CAPI-based computer telephony card under GNU/Linux, then your distribution may already include the CAPI library needed for building GNU Bayonne, and you need not have anything else installed. Many non-CAPI cards include link libraries and drivers that must be present for the card to work and to be controlled by external programs. Please follow the notes in the different hardware sections, based on your hardware, and make sure your hardware is working correctly before you download and install Bayonne.
You may now download the current version of GNU Bayonne 2 (bayonne2). Unpack it as before, then enter the package directory and run the configure script. The Bayonne configure can be passed a number of options that control what features will be enabled or disabled. These can be used to tailor the server image for specific applications where only a selected set of GNU Bayonne's features and capabilities are required. How to tailor GNU Bayonne 2 is explained in section 2.4.
If you do not wish to tailor GNU Bayonne 2 – and in most cases it is
unecessary to do so, then you can simply run the configure script as
is with default options. The configure script will test to see what
computer telephony support exists on your machine, and will then build GNU
Bayonne with drivers for whatever computer telephony support it has found.
You may then run make to compile GNU Bayonne 2. Before you perform
make install, review the section on installing your new server
(3).
It is important to make sure the libraries required for your computer telephony hardware are present first, because Bayonne's configure script automatically detects which computer telephony card libraries are present, and selects which computer telephony drivers GNU Bayonne 2 will be built with. If Bayonne is installed before your computer telephony hardware and libraries, then it will likely fail to use your hardware since it did not detect it at configure time. However, you can always re-run the configure script in the package to enable GNU Bayonne 2 to build drivers for your card if you change hardware or forget to install your hardware first.
There are a number of compile-time options that can be selected by the configure script, and are part of both GNU Bayonne 2 and GNU Common C++. These options are specified through configure because they are options that must be selected before the package has been compiled, and cannot be altered except by re-compiling Bayonne. Many compile-time options relate to disabling specific features that you may choose not to use, and thereby result in a smaller executable image. Some compile-time options enable specific features or support, depending on which optional package is installed.
A number of options are offered in GNU Common C++ to reduce its memory
footprint. If you only intend to use it with Bayonne,
then these options disable features which Bayonne does not use,
though other applications might. The most useful of these include the
--without-compression option which removes libz support, the
--without-ipv6 option which removes IPV6 socket support, the
--without-libxml2 option which removes GNOME libxml2, and the
--without-exceptions option which removes C++ exception-checking
overhead.
GNU Bayonne 2 only uses libccgnu2 from GNU Common C++ 2. With an optimized build of GNU Common C++, and by selectively installing modules, it should be possible to deploy Bayonne on GNU/Debian systems with 8 megs of RAM or less. Future versions of GNU Common C++ may also offer an alternate “embedded” compile-time configure profile which will further reduce memory requirements by eliminating dependency on libstdc++.
Currently, Bayonne 2 is packaged with a special module which can be
loaded to enable SunRPC support. As I found SunRPC is broken on some
platforms, this is not enabled by default; you can access it
with the --enable-sunrpc option in the Bayonne configure script.
As the service is a runtime loadable plugin, and comes with a number of
stand-alone binaries, in the future this may be made available as a
separate package that will be named bayonnerpc.
GNU Bayonne 2 also offers the --disable-libexec option for its
configure script. This option, when used, removes support from
Bayonne to run external applications. This option is only recommended
for systems with tight resource constraints, or when building servers
for pre-bundled and dedicated applications.
Another option that is important is --with-voices=xxx. This can be
used to select libraries from which languages will be installed. By
default, a generic voice language system for English is installed.
To get Russian and French added, for example, one would use
“--with-voices="ru fr"”. Alternately, all of the languages found in a
given distribution can be installed with --enable-voices.
An important configure and compile-time option is --disable-testing.
This is used to disable support for build-directory execution testing, as well as
other command-line features and options that would not be used in a
dedicated production environment. The result is a smaller, simpler
runtime production server.
Other compile-time options may be offered in the future. Most options are now configured at runtime by selecting which modules will be loaded into your Bayonne server.
A few GNU/Linux distributions include pre-compiled and pre-packaged
versions of GNU Bayonne. On these systems, all you may need to do is select the
Bayonne package and install it. From that point, all dependencies will
often be installed automatically for you. For example, in a Debian
system, it may be possible to do an “apt-get install bayonne2”. I
have considered making separate repositories supporting some distros I
commonly use, but none have been set up as yet.
When installing pre-compiled copies of GNU Bayonne 2, these pre-built packages will only have support for whatever telephony hardware was available and detected on the machine that the package was originally built on. This may mean a pre-compiled Bayonne package will not work with your computer telephony hardware even if the hardware is listed as fully supported under Bayonne, simply because the machine used to build the pre-packaged distribution of GNU Bayonne 2 did not have the link libraries for your hardware installed on it.
A simple solution is to rebuild GNU Bayonne 2 on your local machine from the source package supplied by your GNU/Linux vendor after installing your computer telephony hardware. By building a new binary package from the source package, you will have a new binary package which should include support for your hardware. You can then install your newly generated binary package and have it maintained by your package management system.
GNU Bayonne 2 and each of its dependent packages also include their own
.spec files, and you can use these to locally create RPM packages for
your own production environment. This can be done by using the -tb
option to have rpmbuild create a binary package from a .tar.gz. When
you do this, or rebuild the GNU Bayonne 2 package as explained above, however,
you are restricted to the compile-time configuration options that the
packager originally defined. You can still modify these
options in the Bayonne .spec file and build installable binary packages
tailored for your environment.
[This part was rewritten in 2017 to reflect changes that happened since 2005: the source code has moved from CVS to other version control systems (VCS), and the latest versions of Bayonne depend on uCommon instead of Common C++.]
The source code of each package is available on Savannah servers, in one or several repositories that are listed on the project's web page:
| Package | Project's web page |
|---|---|
| GNU [u]Common C++ | https://savannah.gnu.org/projects/commoncpp |
| GNU ccScript | https://savannah.gnu.org/projects/ccscript |
| GNU ccAudio 2 | https://savannah.gnu.org/projects/ccaudio |
| GNU ccRTP | https://savannah.gnu.org/projects/ccrtpp |
| oSIP | https://savannah.gnu.org/projects/osip |
| eXosip | https://savannah.gnu.org/projects/exosip |
| GNU Bayonne | https://savannah.gnu.org/projects/bayonne |
You will find explanations on how to check out or clone a given repository by following the link to the “Source Code Manager” of the repository, in the “Development Tools” section of the project page.
As explained in section 2.3 (Building from released source packages), GNU Common C++ (or its successor uCommon) should be installed first, then GNU ccScript, GNU ccAudio 2 (and optionally GNU ccRTP, oSIP and eXosip), then finally GNU Bayonne.
The main difference with released packages is that you will have to generate
the configure scripts by running a special command from the root of the
working directory: ./reconfig for older versions, and
./autogen.sh for recent ones. Then you can run ./configure,
make, and finally make install.
With a local clone or checkout of the repository, you can update your
installation through the version control system itself. For example,
git pull from your bayonne directory will download the latest
changes. You should then run ./autogen.sh, ./configure, and
make install as you did originally. Of course, you should update the
commoncpp directory first.
You can also use the VCS to create patches for GNU Bayonne 2 or any of
its dependencies. For example, you can use git diff to create the
patches you want to submit to the Bayonne mailing list
<bayonne-devel@gnu.org>. Don't forget to run git pull before
you start each work session!
When building Bayonne from source, somewhere between performing make
(to compile Bayonne) and make install, there are a number of things you
can do to determine that your newly compiled server is functional.
After compiling your new server, you can immediately test it to see if it is functional without having to do any further configuration. Bayonne can execute directly from the working directory you are building from, using a special test mode. This test mode can also allow you to determine if your hardware or IP voice driver configuration is actually working and operates correctly with Bayonne, even before Bayonne itself has been installed for production use.
GNU Bayonne test mode is activated by passing the --test option
when running the server. You can run the server and test applications
delivered with GNU Bayonne without installing the server, using
--test. There is also a server test directory (called tests)
which contains test scripts you can run to test various driver features.
You should cd to this directory and look at the various script files
present here. They each contain comments which explain what they test
and what you can expect when you run one.
To run a given test script with a driver, you can execute the shell
script testit from this directory. To run the DTMF test script with the
soundcard driver, for example, you would execute ./testit dtmf.scr.
This basically runs “../server/bayonne --test soundcard dtmf.scr”.
With the soundcard driver, the server will startup in test mode, and
“wait” for an incoming call. This can be simulated by pressing the
space bar. The soundcard driver is useful because you can use the
keyboard to simulate DTMF input, and get a basic idea of server
functionality very easily.
You can use test scripts to test any driver from this directory before
installation. For example, to run the same test application for the
dialogic driver, you can enter “../server/bayonne --test dialogic test.scr”
from the tests directory. The server will start up in test mode and
offer test.scr to the next incoming call received on your dialogic card.
Another useful option for testing the server from the build directory
is --debug. You would normally use this in place of the --test option,
as in, for example, “../server/bayonne --debug dialogic test.scr”. When
used in debug mode, the server will fall into the GDB runtime debugger if
it crashes. This can then be used to examine and debug the server.
Once Bayonne is installed, you will have to at minimum edit config files
to indicate which driver you want the server to run when it is started.
The simplest way to do this is to edit the /etc/sysconfig/bayonne file and
set the DRIVER= line to specify the driver you are using. You may wish to
set your default language and voice library settings in this file as well.
The actual location of the “bayonne” driver and base configuration file
will vary based on your operating system and distribution. For example, on
typical GNU/Linux systems that are based on the RedHat distribution, you find
/etc/sysconfig/bayonne. This same file may be /etc/conf.d/bayonne on
a typical Debian or Gentoo GNU/Linux system. On FreeBSD, this will be found
as /etc/defaults/bayonne.conf. In addition, there is a directory,
/etc/bayonne, which will hold all the configuration files used by the
server after it is started.
The Bayonne server itself is normally run as a daemon process, and may
be started from your system initialization scripts using the
bayonne.init script. This script is supported under chkconfig, and
“chkconfig bayonne on” will enable Bayonne services to run
the next time your system is booted. You may also start the service
immediately by invoking the startup script with the command
“/etc/rc.d/init.d/bayonne.init start”.
Once you have the server installed and running, you will want to look at
the administration guide. The admin guide includes information on how to
schedule inbound calls with the scheduler file, and all of the many things
found in the /etc/bayonne directory. That information is beyond the scope of
this manual.
Generally Bayonne is most widely tested and deployed on GNU/Linux. If the target machine can compile GNU Bayonne 2, it will generally run fine. GNU Bayonne 2 is not dependent on kernels, glibc versions, or gcc. GNU Bayonne 2 uses threading extensively, but supports both older Linux pthread support and the new NPTL threading found in 2.6 kernels (and early Fedora releases) just as well. Any modern GNU/Linux distribution should work fine, as well as most older distributions, including Debian Woody, RedHat 6.x and later, etc.
What you will find if you choose to use H323 support, is that recent OpenH323 releases may only compile or work correctly on certain GNU/Linux distributions. Also, the distributions of OpenH323 included in many GNU/Linux distributions predate 12.1 and will often not build correctly with GNU Bayonne. When this happens, it is generally recommended that you do NOT install the pre-packaged version of OpenH323 that came with your GNU/Linux distribution, but rather build and install OpenH323 from a current release tarball found on https://www.h323plus.org/.
Similarly, many of the computer telephony cards supported under GNU/Linux either come with binary drivers, or drivers that only compile with specific kernel or glibc releases. These may also restrict your choice of distributions further.
GNU/Bayonne attempts to be compliant with FHS in the layout and use of system directories. This means if you know FHS or are using a LSB-compliant GNU/Linux distribution, then GNU Bayonne will by default install things consistent in locations generally consistent with LSB & FHS as other packages do.
GNU Bayonne is also aware of the split between Debian-based GNU/Linux
distributions, and so-called “RedHat”-based ones. On the latter, GNU
Bayonne installs its master system config file as
/etc/sysconfig/bayonne, and its init script under /etc/rc.d/init.d. On
a Debian-based system, the master system config file is found under
/etc/conf.d/bayonne, and the init script is under /etc/init.d.
Generally, I have tested GNU Bayonne 2 GNU/Linux support on non-x86 hardware. GNU Bayonne 2 audio processing is endian-aware and it does compile on other common GNU/Linux target architectures such as PPC, S/390, etc. Availablility of computer telephony hardware usable on some of these targets may limit the ways GNU Bayonne 2 may be used on them, but for a pure IP voice server, any of these alternative platforms should prove workable and may offer some distinct advantages.
GNU Bayonne 2 works fine under recent versions of MacOS X. Many of the issues identified for GNU/Linux and BSD systems apply to Bayonne under OS X as well. However, the only driver fully usable at this time is the SIP driver. If more recent versions of openH323 can successfully compile under OS X, it may be possible to use the Bayonne H323 driver as well. The soundcard driver will not be usable until OS X audio support is fully completed in ccAudio2.
Building and using GNU Bayonne 2 under BSD is no different than using a GNU/Linux distribution. GNU Bayonne 2 supports FreeBSD threads and re-entrant libraries and generally behaves best under newer versions of BSD distributions (FreeBSD 5.3, OpenBSD 3.6, NetBSD 2.0, or later) which fully support native threads and SMP. However, there are issues. First, there is a lack of supported computer telephony hardware available on FreeBSD. This limitation will largely restrict one to using SIP or H323. The OSS-testing sound driver plugin does also work on FreeBSD, although there are some quirks in its behavior on some BSD systems.
When building GNU Bayonne 2 on FreeBSD, many GNU/Linux-specific
characteristics are retained, including the use of FHS file system
layout. However, the GNU Bayonne 2 master config file is stored where
expected for FreeBSD, i.e. under /etc/defaults/bayonne.conf.
In the future we will offer a bayonnerc init script.
In theory at least, GNU Bayonne 2 should be able to compile and install under Sun Solaris, and make use of Solaris threading. In fact, any Unix target supported by POSIX threads (pthread, with or without SunOS extensions) should be able to be used, including such systems as IBM AIX, HP/UX, etc. In the case of HP/UX, GNU Bayonne 2 will likely be compiled by the HP C++ compiler. In practice, none of these platforms have been tested by me directly, although there have been reports of people successfully building GNU Bayonne 2 under Solaris for use with the Solaris port of the QuickNet LTAPI driver. If you have success with these platforms, or have specific patches to offer to make them work, I would be interested in knowing about this. It may also be true that GNU Bayonne 2 might happen to compile and/or run under UnixWare, although no effort has been made to establish this and no effort will be made to support that platform.
This would be covered in a separate manual to be included in the future with the CAPE installer.
To support very large port densities under GNU Bayonne 2, it is generally recommended to use SMP systems. GNU Bayonne 2 is already fully threaded and optimized for SMP use, although it can be tuned further to optmize SMP performance. In particular, some drivers offer the option of setting the number of parallel dispatch threads, with the default being just “1”. These values should be increased in the appropriate config files for true SMP systems.
On many SMP-aware operating systems, memory allocation is still often singular, and this can lead to unnecessary lock delays. On AIX, this can be tuned by selecting multiple heaps, and this is the preferred method to use for GNU Bayonne 2 on that platform. Using a special SMP-optimized memory allocation library, such as “libhoard” is also recommended.
When a GNU Bayonne 2 server is started, it will install support for a particular family of computer telephony hardware or IP telephony stack. This family is installed at runtime through a DSO plugin. When a driver for a given family of hardware is selected, this generally means that one or more computer telephony boards of that product family may be used.
Some GNU Bayonne 2 frameworks support multiple driver plugins and the use of multiple families of computer telephony cards in one running instance. This means you can, for example, install both SIP and Voicetronix hardware in the same machine, and have both running together in the same instance of the GNU Bayonne 2 framework. You may also be able to have different vendor cards on the same server if you start multiple instances of GNU Bayonne, with each instance started with a separate driver plugin. The default Bayonne application server only supports loading a single driver type into a running instance. Some alternative servers built on the framework will offer loading of multiple drivers to meet specific needs.
Many of the GNU Bayonne 2 drivers can not only support multiple boards of a given hardware family, but may also support mixing different types of boards from a given family of hardware together in a single running image. For example, one can use any combination of one or more supported analog and digital telephony cards from Intel/Dialogic with the Bayonne Intel/Dialogic driver in GNU Bayonne 2.
Some GNU Bayonne 2 driver plugins may only support one type of card installed in a given running instance of the server. The current GNU Bayonne 2 Voicetronix driver, for example, supports the use of either Voicetronix OpenSwitch12 or OpenLine4 cards, but not the use of both of these cards together in the same server. The exact limitations and range of hardware support are detailed in the subsection on each hardware family.
First, you will need to install a modern distribution of OpenH323.
This may be found at https://www.h323plus.org/. A version of OpenH323 > 12.0
and PWLib >= 0.5 should work. Earlier versions will not. You can compile
and install each of these packages with make install to the default
directory, and Bayonne will be able to find and use your OpenH323
configuration. It may be able to use other kinds of installation
configurations as well.
Because there is no reliable means to auto-detect which version of OpenH323
is installed, and the entire Bayonne build process will halt if
an older and unsupported version is found, OpenH323 support and
auto-detection is now disabled by default in the Bayonne configure
script. You will need to use “./configure --enable-openh323” to
explicitly activate it. Since various versions of OpenH323, source
builds, and pre-packaged distros of OpenH323 all use different methods
for locating and configuring installation paths for OpenH323 libraries
and includes, the auto-detect code found in the configure script may not be
sufficient; two extra configure options also exist:
--with-pwlibdir=path, and --with-openh323dir=path.
If you do all these things, and all the prerequisites are met, GNU
Bayonne should compile. When using the --enable-openh323 option
during the “configure” process, you will want to look for the line:
“checking for openh323 libraries... found. If this appears in
the output of configure, then probably everything is fine.
While current OpenH323 support is built around the standard OpenH323 distribution, Bayonne 2 will soon migrate to use Opal. From Opal we will also adapt IAX2 and perhaps an alternate SIP driver.
[The location of the source code was updated in 2017.]
oSIP2 and eXosip can be downloaded from https://ftpmirror.gnu.org/osip/ and https://download.savannah.nongnu.org/releases/exosip/, respectively.
You can also retrieve the development sources from Savannah as explained under “Building from development sources”.
Next, go into the osip directory, and run the ./autogen.sh command.
This will build the configure script. Now you can run ./configure,
followed by make install.
Once oSIP2 is installed, go into the exosip directory, and run ./autogen.sh
there. When you run configure, do so as “./configure --disable-josua”.
Now you should be able to do a make install.
Finally, go (back) to the bayonne directory, and perform the configure and
build steps there (2.3.4).
GNU Bayonne 2 has been tested successfully with both Analog and Digital span voice processing cards from Intel. One or more Intel/Dialogic cards may be placed in a given server and used directly. Intel/Dialogic cards of different types may also be mixed together.
When multiple cards are used in a GNU Bayonne 2 server, it is necessary to interconnect the SC-bus cables accross all of your cards. GNU Bayonne also requires sufficient voice processing resources to be available for all the ports you wish to accept calls on concurrently. Voice processing can be shared between different cards over the SC-bus directly.
GNU Bayonne 2 supports a single driver for Intel/Dialogic hardware based on Intel/Dialogic Global Call services. This driver supports both analog cards and single or multi-span T1/E1 cards used on PRI circuits, and provides support for DM3 voice cards as well as older lines of Intel/Dialogic hardware. This driver can work with older releases of Intel/Dialogic runtime systems, but it is recommended that the latest, 5.1 (SP1) be applied and used under GNU/Linux with GNU Bayonne 2.
The driver supports automatic detection of your Intel/Dialogic hardware,
and requires minimal configuration options in GNU Bayonne 2 using a
single [dialogic] section in /etc/bayonne/drivers.conf. You are required
to install a Dialogic driver/SDK kit.
The next section is meant to simplify the installation process for System Release 5.1 with Service Pack 1 (SP1) for GNU/Linux, with a separate section on DM3-based hardware. DM3-based cards can be used with the GNU Bayonne 2 Intel/Dialogic driver.
Before beginning the installation, it's crucially important to know what hardware you have and to verify that it's supported by this release. The list of supported hardware is in the Release Guide. Read it; know it. Furthermore, GNU Bayonne 2 requires that, whatever combination of hardware you use, sufficient voice resources are present. This means that if you use non-DSP span termination cards, you may need to also have SC-bus DSP resource cards in your system for a working configuration.
Basically, there are 2 different hardware families of Intel/Dialogic hardware – Springware and DM3. The Springware family has been around for a long time and includes everything from 2-port analog cards up through dual-span cards with 48 ports. The DM3 family begins at 48 ports per board and goes up from there.
The easiest way to tell the difference is to look at the model name on the card bracket sticker. All DM3 hardware will have a model name that starts with DM/ while Springware model names will start with plain D/ (or MSI/ for the MSI cards). For instance, a Springware card might have a model name of D/480JCT-2T1 while a DM3 card might have a model name like DM/V480A-2T1. You get the drift.
There is an excellent FAQ which describes how to install the Intel/Dialogic runtime for GNU/Linux already, and I will not repeat this here. The key point, however, is that the current release of their driver requires the LiS streams package, and Intel/Dialogic recommends using LiS 2.13.16. Moreover, the driver and SDK are only certified for use with either RedHat 7.2 GNU/Linux with the 2.4.9-13 (or greater) kernel update, or RedHat 7.3 GNU/Linux with the 2.4.18-5 (or greater) kernel update RPM.
My own experience with the Intel Dialogic SDK's have suggested that it is far better to actually use LiS 2.14.6 or later, which are more stable than the deprecated and unsupported 2.13 beta series for LiS. Also, it has been said that any GNU/Linux distribution that is somewhat similar to these RedHat releases may also work fine with a little extra work, including Debian (Woody?) and several Mandrake releases. However, you may try those at your own risk of a failed SDK install.
If you are installing DM3 hardware, please be aware that the configuration
and installation of the SDK for this hardware requires some extra steps.
In any case, if the installation is successful, you will be able to start
your dialogic runtime environment by running “/etc/rc.d/init.d/dialogic start”.
If you try this, you have the hardware installed, and it initially
fails, sometimes it helps to simply reboot the machine after installing
their SDK.
Assuming the startup completes normally, your next step is to test your Intel/Dialogic hardware and SDK configuration. This is important to do before you try configuring and using GNU Bayonne 2 if you are inexperienced with Intel/Dialogic hardware. Very often we find many questions come up on the mailing list that are not Bayonne issues at all, and which could have been resolved simply by doing these tests before trying to get Bayonne to work with your configuration.
The best/only way to test DM3 hardware is via the few DM3-capable demo
programs that are included;
/usr/dialogic/demos/gc_demos/gc_basic_call_model, essentially.
You can run the test as follows:
# cd /usr/dialogic/demos/gc_demos
# vi gc_basic_call_model.cfg
# Edit this file to reflect the boards/channels/protocols
# to be tested. If you don't get this setup right, it
# won't work!!
# ./gc_basic_call_model
If you get an error from gc_Start(), reboot the system. There are some
library dependencies that get resolved at boot time.
The software furnished for testing Springware hardware is much broader and
is really dependent on your hardware. Specifically, analog vs. digital,
ISDN vs. robbed-bit, etc. However, you can (and should, actually) use
the afore-mentioned gc_basic_call_model program, which has the
advantage of working with all hardware and all protocols.
Other programs are also available:
pansr, which works with analog and robbed-bit T1 with immediate start
protocol. It's located in /usr/dialogic/demos/dx_demos. The source code
is there and you should take a look at the command-line options as they
need to be set right or, surprise!, it won't work.
isdiag, a great PRI ISDN testing program in /usr/dialogic/bin.
sampletest, a stripped-down version of isdiag, which is
located in /usr/dialogic/demos/cc_demos.
If you cannot get Bayonne to run with your Springware hardware, please, first test that your system is really working, that your carrier spans are really configured correctly, etc., and try these programs before requesting help on the Bayonne mailing list.
In order to fully utilize all of GC, you'll need to download the latest protocol package. So, if you are using the GlobalCall driver, you may as well get that now. [In 2017, this package is obsolete. It used to be available from http://support.dialogic.com/releases/protocols/GCProtocols30/index.htm.]
We assume that, at the time of GNU Bayonne 2 release, the Bayonne
GlobalCall driver will support full auto-detection of Intel/Dialogic
cards. However, you still need to specify the protocols that are being
used by digital span cards as part of the [dialogic] section of
/etc/bayonne/drivers.conf. To understand how this works, we should
review how Intel/Dialogic names line protocols.
The Voicetronix driver supports two types of Analog DSP computer telephony cards (OpenLine4 and OpenSwitch12) made by Voicetronix (http://www.voicetronix.com.au). Both cards use the same driver, which may be downloaded directly from the Voicetronix site.
Download the latest driver, something like
vpb-driver-2.2.24.tar.gz. Untar it to a directory, such as, say,
/usr/src/vpb. Enter the directory you have unpacked the driver in and
perform a “make OSTYPE=linux”. This will build the Voicetronix card
driver for your machine.
The first problem you will find is that the Voicetronix driver requires
the Linux kernel sources to be installed on your machine. You must
install these, and then perform a “make menuconfig” in your Linux source
directory to ensure there is at least a default build configuration.
Assuming you do this, and then return to compile the Voicetronix driver
again, you will find that, on at least some GNU/Linux distributions, it
will still not compile. This is because most current 2.4-based systems
assume that the kernel sources are referenced through /usr/src/linux-2.4,
and the Voicetronix driver simply assumes /usr/src/linux. What I typically
do is modify Voicetronix Makefile so that the kernel include path matches
up correctly for current distributions. You can do this, or just create
an extra symlink under /usr/src/linux.
Assuming you are able to compile the source, you should then perform a
“make OSTYPE=linux install”. This will install the kernel driver
modules, an include file, and a link library. Unfortunately, the vpb
package chooses to install the vpb link library (libvpb.a) under
/usr/local/lib, and the include file (vpbapi.h) under /usr/include. I
suggest moving both either to /usr or to /usr/local, as Bayonne may fail
to find or properly build Voicetronix support, depending on what prefix it
is configured for, if these are mixed up this way.
Next, you will need to install the Voicetronix kernel modules. This can be
done with the insmod command. If you have OpenLine4 cards, then you need
only perform an “insmod vpb”. If you have the OpenSwitch12 card, you
will also need to perform an “insmod vpbhp”. These drivers will be
shown in the kernel, and you will need to find out what major device
numbers they are using from /proc/devices.
Once you determine the major device numbers, you must create device nodes.
If the vpb device is “254”, for example, you will create 4 device nodes:
“mknod /dev/vpb0-3 c 254 0-3”. You should set the file permissions
for these devices to enable the userid that you will run the Bayonne
server under to access them. Ordinary user accounts can access and use
Voicetronix hardware if you choose appropriate permissions to enable
this. What I typically do is create a separate “bayonne” entry in
/etc/groups, and selectively add specific user accounts to that group. You
can then create your device nodes under the bayonne group and give that
group rw privileges to the device. If you have an OpenSwitch12 card,
you will also need to create a device node for /dev/vpbhp0 using the
device's major number.
If you are using the VoiceTronix OpenSwitch series of cards, you will need
to specify VPB_MODEL=V12PCI in your environment. The current driver
will
autodetect the number of ports and cards you have in your system, but it
will not allow you to mix OpenSwitch and OpenLine cards in the same
machine.
The OpenSwitch12 card is a complete PBX on a single board. This allows you to directly plug analog telephone stations into the card and use them as internal extensions, as well as plug your incoming analog phone lines to it. The OpenSwitch12 is a full-length PCI card. Some tower cases now being made choose to extend drive bays down the entire length of the case. These cases will not accept a full length PCI card and you will not be able to fit an OpenSwitch12 card in them. As with all PBX cards, you need to follow the vendor's instructions to avoid damaging your phone service and your card. Specifically, we would not want to plug a trunk line into a station port.
Another issue you will find with the OpenSwitch12 card is that the card
must operate on a separate and unshared IRQ vector. If you install your
card and insert the vpbhb driver module, you will see in /proc/interrupts
what IRQ your card is using. If it is using an IrQ that is not used by
any other device, then, after inserting the driver, you will see the
number of interrupts incrementing in /proc/interrupts each time you check
it. If this is not happening, but the device is listed, along with any
other device that also is using the same IRQ, then your card will simply
not function.
The simplest way I found to get around this problem was to disable the serial ports, and then use the plug-and-play BIOS to force the PCI slots to use the IRQ range of the serial devices (IRQ 3 and 4). Most motherboard-based resources tend to start from IRQ 10, although other PCI cards will also do this to share IRQ's. Unfortunately, the OpenSwitch12 card does not share.
The card can be configured to operate either as a 12 port analog DSP telephony card, as a card with 4 telephone extensions and 8 phone lines, as a card with 8 telephone extensions and 4 phone lines, or as a card which supports plugging in analog telephones on all 12 ports. This use is configured by a set of onboard jumpers which are labeled on the card. Some of these configurations allow for failover, where, if the card is inactive or the server dies, the first 4 trunk ports are connected to the first 4 analog telephone stations. Here is the common jumper setting:
Standard setup:
JS1, 2, 5, 6 and H1-H16 are jumpered so that Bank A, 0..7 are set as station;
Fail-Over is enabled: H27-34 are jumpered.
Next you will need to make cables for your card. Each of the 3 RJ-45 ports on the back of the Voicetronix card supports 4 telephone lines.Take a look at the connectors on the back of the card. Since you probably have your card in your PC, here is some info on the connectors on the back (labeled on the circuit board J1, J2, and J3):
J1 is furthest from the PCI slot
J2 is in the middle
J3 is closest to the PCI slot
The Readme.OpenSwitch12 document describes the OS12 pinout in the “Port Wiring” section. There it is explained that physical connectors J1 and J2 are Bank A. Connector J3 is bank B. Bank A is always ports 0 through 7, and Bank B is always ports 8 through 11.
J1 = ports 0..3 of Bank A
J2 = ports 4..7 of Bank A
J3 = ports 8..11 of Bank B
Harken back to the jumpering section, and we can safely say that we have jumpered the four ports closest to the PCI slot to be trunk ports (the phone company lines get connected here.)
If the tab of an RJ45 is pointing down (you are looking at the conductor side), and the head is flush against your palm, pin 1 is biologically proximal to your wrist, and pin 8 is distal. That is, pin 8 is away from you.
While soundcards are not actually “computer telephony” hardware, they
can also be used with GNU Bayonne 2. This can be very useful since one
can develop, debug, test, or even to some extent demonstrate common GNU
Bayonne 2 applications without having computer telephony hardware
physically installed on the machine you are using. This is particularly
useful in larger development environments where not every hacker has a
production server with what might be expensive computer telephony
hardware sitting on their desk or available for their exclusive use.
Support for using soundcards is built by default, and Bayonne can be
started with the soundcard driver by passing the --test soundcard option to
the bayonne command.
When GNU Bayonne 2 is used with a soundcard, it will always execute in the foreground rather than as a background daemon. The keyboard will act as a telephone keypad and can be used to simulate DTMF key interactions. The spacebar can be used to start the application you are demoing under the soundcard driver, and the “H” key can be used to simulate a caller hanging up. You can use CONTROL-C or “D” to shutdown Bayonne.
GNU Bayonne 2 uses /dev/dsp to operate the soundcard, and may not work
correctly with some broken soundcards that only support fixed (44.1khz)
sample rates. Otherwise, it should work on any GNU/Linux machine that one
is able to get sound working on. Support exists for soundcard audio on
Microsoft Windows as well. The OS X soundcard support is currently
broken, but this is a ccAudio2 library issue.
The following table summarizes the computer telephony hardware supported
by GNU Bayonne, and the names of drivers used. These names are used
during server startup when passed to the Bayonne server as
“--test name” or “--load name”. They may also be entered
in the /etc/sysconfig/bayonne file.
| Name | Driver | Summary |
|---|---|---|
| capi20 | Capi Driver | Driver for CAPI-2.0-compliant BRI & PRI cards |
| globalcall | Intel/Dialogic analog | Span cards under GlobalCall driver |
| soundcard | OSS Sound Driver | Soundcard driver for testing |
| voicetronix | Voicetronix Driver | OL4 and OS12 telephony cards |
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The text of the license is available at https://gnu.org/licenses/old-licenses/fdl-1.2.html.