DRAFT 1

Introduction
------------

Bayonne differs signficently from ACS in the way platform specific
telephony API's are integrated.  In ACS, a platform specific server must
be compiled and installed.  In Bayonne, a single (unified) server image
is used, and all telephony API's appear as loadable modules.  Furthermore,
Bayonne differs in that the server can be ran under "user" privilege, at
least for most telephony API's, while ACS actually required root
permission to execute.

These differences are substantial enough that the very concept of
configuration and deployment of Bayonne differs signficently from ACS.
This document is not meant to highlight those differences, but to identify
issues and configuration options relevant to each driver and telephony
vendor that is supported in Bayonne.

Drivers
-------

A "supported" Bayonne telephony device is managed through a plugin
"driver".  This "driver" is defined as a shared object module with an
extension of ".ivr".  Drivers (and other Bayonne "plugin" resources) are
found either in /usr/lib/bayonne or /usr/libexec/bayonne depending on the
host operating system.

In addition to telephony device "drivers", there are plugins for
"integration" services.  These typically are used for switch integration,
such as the Bayonne "SMDI" module.  Other modules offer extended
call logging capabilities, network integration, VoIP stacks modified to
operate as runtime loadable modules, and script language extensions.  

While all other forms of drivers and plugins are optional, Bayonne
requires at minimum a telephony device and API "driver" (.ivr) to be
selected for Bayonne to execute.  Furthermore, at present only one such
driver can be selected and made active in any running instance of the
Bayonne server.

The primary telephony driver API is selected in the [paths] section of the
/etc/bayonne.conf file.  The name of the driver to load is specified
directly, in the form "driver=drivername", such as "driver=phonedev".  A
matching "phonedev.ivr" plugin is then loaded when the bayonne server is
started.

The remaining sections of this document will cover the various driver and
plugin modules currently supported by Bayonne, as well as vendor specific
issues.

PHONEDEV.IVR
------------

The phonedev.ivr driver is used to support operating systems such as
GNU/Linux which make use of kernel mode "native" telephony drivers
commonly found under "/dev/phone".  This driver supports interaction with
kernel telephony "phone" devices through the application of a known set of
ioctl calls and the use of "event" notification through the exception bit
of the select() call.

The phonedev module does try to treat phone devices in a fully vendor
neutral manner.  "/dev/phone" device drivers from different vendors can be
loaded and mixed in kernel memory under separate device nodes, and the
phonedev.ivr module will accept such a mixed vendor environment as well as
query /dev/phone devices for specific features and capabilities that will
be supported on each instance in Bayonne.

Furthermore, in that Bayonne executes in "user" mode, the bayonne server
will only open and access "phone" devices that are actually made available
to the current user id that bayonne is running under.  This means that if
one wants to use, for example, three QuickNet "linejack" cards with
Bayonne for servicing incoming calls (say /dev/phone1-4), and yet preserve
a QuickNet "phonejack" card for "private" use (say with gnomephone or
speakfreely), then one can simply set the ownership of the linejack cards
to match the user id Bayonne will run under, and preserve the phonejack
(/dev/phone0) as owned under a different user id (say the userid of the
workstation user who wishes to use speakfreely).

Finally, the phonedev.ivr can be used in multiple instances of the Bayonne
server.  Hence, one can run different "application servers" by starting
multiple instances of Bayonne under different user id's.  Different sets
of "/dev/phone" devices can be marked as owned by each of the expected
server user id's, and each server will then operate only with the
"/dev/phone" devices that user id has been granted access to.

One should never start more than one instance of Bayonne under the same
effective user id.  Also, when using user permissions to partition
"/dev/phone" devices between multiple instances of Bayonne, these device
nodes must never be marked with shared group "write" permission, otherwise
the device may be accessed under multiple images.

When starting the server under the "root" user, one may find additional
problems.  Bayonne will change itself from root to a new effective user
id once started.  Due to a bug in the Quicknet cards, the /dev/phone
device must be closed and re-opened between each telephone call.  Hence
while root, /dev/phone will initially open, but once the server is
running /dev/phone devices may no longer work unless they are given
r/w access permissions under the effective user id the server is now
running under.  By default this will be the effective user id of the
"mail" account, although it can be changed in [server].

The "phonedev.ivr" uses service threads to service event queues for
driving the call processor of each of the open "/dev/phone" devices.
The total number of such devices that will be supported is indicated in
the [phone] section of /etc/bayonne using the "devices =" keyword.  The
default value is currently "16".  The maximum value that may be specified
is "240".  As each device represents an individual telephone line, it is
possible some cards may support multiple "/dev/phone" nodes from a single
card.  This value thus represents the total "port" capacity that will be
tested for rather than the total number of cards that may be supported in
a single chassis.

Normally only one or at most two service threads are needed, and these can
be selected using the [thread] service = keyword option as described in
the bayonne.conf man page.  Generally the service threads should run
either at or a higher priority than Bayonne itself.  The phonedev.ivr can
support a maximum of 240 device nodes (sufficient for 10 T-1 spans or 8
E-1 spans), hence, in a very high capacity "/dev/phone" based SMP server
one might wish to select 4 or even 8 service threads.

At the time of this writing, only the QuickNet cards are known to be using
"/dev/phone" drivers under Linux.  However, the Voicetronix multi-port
analog telephony cards will likely soon also use "/dev/phone" based Linux 
kernel modules.  It has been assumed a maximum of 16 QuickNet cards can be
installed in a single cabinet.  It is possible to also have up to 16
Voicetronix cards in a single cabinet, with each card servicing 4 analog
telephone lines, for a total capacity of 64 ports.

VPB4.IVR
--------

PIKA.IVR
--------
