next_inactive up previous Bayonne User Manual Anders Dahnielson 2001-04-13 Contents * [1]Contents * [2]General Information About Bayonne + [3]What Is Bayonne + [4]How you can help + [5]About This Manual + [6]History of Bayonne + [7]The Name * [8]Bayonne Licensing and Support + [9]Licensing Policy + [10]Commercial Support * [11]System Architecture + [12]Introduction * [13]Hardware Support + [14]Dialogic + [15]Pika + [16]VoiceTronix + [17]Quicknet + [18]Aculab * [19]Drivers + [20]Introduction + [21]Drivers + [22]PHONEDEV.IVR + [23]VPB.IVR + [24]PIKA.IVR + [25]DIALOGIC.IVR + [26]ACULAB.IVR * [27]Installing Bayonne (Basics) + [28]How to Get Bayonne + [29]Supported Operating Systems + [30]Installation Layouts + [31]Configuring + [32]Compiling * [33]Installing Bayonne (Advanced Topics) + [34]Compilers and Options + [35]Compiling For Multiple Architectures + [36]Optional Features + [37]Specifying the System Type + [38]Sharing Defaults + [39]Operation Controls * [40]Scripting Language + [41]Introduction + [42]Events + [43]Symbol Notation + [44]Basic Commands + [45]Bayonne Server Commands + [46]Optional Commands * [47]Phrasebook Rules + [48]Introduction + [49]English * [50]TGI Services + [51]Introduction * [52]Wrapper + [53]Introduction + [54]Using Bayonne with an existing site + [55]Running Bayonne seperate from your web server + [56]More on running web services on a Bayonne server + [57]Corba and other future services * [58]About this document ... General Information About Bayonne What Is Bayonne Bayonne, the telecommunications application server of the GNU project, will offer a free, scalable, media independent software environment for development and deployment of telephony solutions for use with current and next generation telephone networks. Bayonne already offers a fully distributed application server for use today with multi-line telephony cards from many vendors under free operating systems. To speed development and simplify deployment of custom applications, Bayonne offers it's own native script interpreter which may be directly extended thru modular DSO plugins and TGI based applications. TGI, "Telephony Gateway Interface", allows Bayonne to be easily integrated with other system resources, such as web servers, databases, and other application servers using standard and familiar tools that are well understood such as Perl, TCL, and Python. Bayonne can be used today most completely under GNU/Linux with an ever wider selection of telephony hardware. Bayonne has also been built under, and can be used with, FreeBSD and the new Voicetronix API. Bayonne is highly portable and will compile under most multi-threaded POSIX operating systems, including Solaris and Unixware. As Bayonne's telephony hardware and next generation media support broadens, support for functional deployment under operating systems beyond GNU/Linux will continue to increase. How you can help There are many ways you can contribute to Bayonne even if you do not code. We need people to help with languages and building of multi-lingual voice libraries, people to help with testing, with documentation, and even with the new web site. If you wish to help Bayonne, feel free to send email to dyfet@gnu.org About This Manual This manual was put together by Anders Dahnielson . However most of the text are taken from different Bayonne documents published separatly. This manual is an atempt to get a clear overview of the Bayonne Telephony Server. History of Bayonne While Bayonne remains in continual development, it is based on ACS which is usable today. I originally started the ACS project as a GPL licensed multi-line voice telephony server, with the goal to be the most flexible and advanced telephony voice messaging server available. The final milestone release of Bayonne will be referred to as Bayonne 0.6.0, and will depreciate the ACS code base. With Milestone #5, Bayonne now supports FreeBSD in addition to GNU/Linux (and possibly Solaris). 0.5.0 is the first release which demonstratebly works under FreeBSD and also happens to support the Voicetronix 4 port analog DSP card which will be used as the core of Bayonne VoIP development in coming weeks. In addition, support for Aculab and Dialogic hardware has been initiated, though it is not yet complete. The fourth Bayonne milestone featured many changes, starting with international support and the new french language vocabulary. There are many less visible changes that effect and expand the scope of DSO capabilities for the Bayonne server as well as greatly improve stability of the server. With 0.4.2, expanded support for initiating dialout sessions has been added along with preliminary support for locating streams and the dialogic sdk. The 3rd milestone release of Bayonne is being made available from ftp://www.voxilla.org/pub/bayonne immediately. This release represents both a more rigerously tested server, and a "usable" or "deployable" server. An audio library has been recorded for use with the new phrasebook system, and some documentation has been drafted. Many features have also been clarified and greatly expanded upon for better use in deployable servers. A lot of bugs were also found and fixed between 0.2.1 and 0.3. In particular a number of new issues were identified for both QuickNet and Pika hardware. In the case of QuickNet cards, it was found to be nessisary to do a full close/reopen of the /dev/phone devices to reset the card otherwise they stop responding between calls, and this was done in 0.2. When the server is started as root, the /dev/phone devices are initially opened under root, but then the server reduces its privilege to "mail" and can no longer re-open /dev/phone. In 0.3, the server now resets file ownership of /dev/phone devices. The Name Some have asked why the package name was changed. I felt there are several reasons for doing this. First, I have received numerous complaints over the use of the name ACS in that it is similar to Al's Circuit Simulator and several other common packages. Also, I had originally wanted a name that was more than a 3 letter acronym. Bayonne is taken from the name of the Bayonne "bridge", and represents the idea of this package as a bridge between the computer and telephony worlds. Finally, I wanted to bring across the idea that Bayonne is different than a "1.x" or "2.0" derived release of ACS. Bayonne Licensing and Support Licensing Policy GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software-to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19yy name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items-whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License. Commercial Support Commercial support and products based on both ACS and Bayonne are already available from several sources. Open Source Telecom OST offers commercial support for ACS and Bayonne software deployment, a complete line of turnkey IVR servers based on ACS, and discounts on telephony hardware for use with ACS. URL: [59]http://www.ostel.com TekLab TekLab has offered production support for deployment of ACS solutions since the first widely used releases of ACS. URL: [60]http://www.teklab.com MySite Sweden AB Swedish portal and consulting company that offers custombuilt solutions deploying Bayonne. URL: [61]http://www.mysite.se System Architecture Introduction Has yet to be written... Hardware Support Dialogic Bayonne supports the Dialogic 5.0 runtime release under GNU/Linux. It may also support Solaris Dialogic runtime, but this has not been tested. To date analog cards, such as the D/41x and EPCI cards work fine. Digital (T1) span card support is being worked on. Pika Pika Inline GT and Daytona cards operate with Bayonne under GNU/Linux using the latest MonteCarlo API. More information may be found here. VoiceTronix Voicetronix provides 4 port analog DSP cards with a GPL licensed API. The Voicetronix driver can be used with both GNU/Linux and FreeBSD. Quicknet Quicknet and generic /dev/phone based Linux (and possibly FreeBSD) devices are currently supported. Aculab In active development. Drivers 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 in /usr/lib/bayonne/version/, such as /usr/lib/bayonne/0.4.4/. 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. When Bayonne is "configured" (by running ./configure) it will detect what telephony API's have been installed on the host system. If it fails to find the files associated with a given telephony API, then that API will be excluded from Bayonne. If you later add a telephony API, you will need to remove config.cache and then re-run "./configure" before Bayonne will recognize and build drivers for it. 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. VPB.IVR The vpb.ivr driver supports Voicetronix's 4 port analog DSP card. These cards use a "user mode" library, libvpb2, which must be installed before Bayonne is configured. This driver will work for both GNU/Linux and FreeBSD systems. It will work for any target platform that the libvpb2 library supports in the future. The vpb.ivr module requires that Bayonne is started under "root". This is nessisary for Bayonne to access io ports under both the Linux kernel and FreeBSD. Once started, Bayonne will reduce itself to the effective user privilege specified in the [server] section of bayonne.conf. The [vpb] section of Bayonne must be configured properly before you attempt to start it. This includes the base address of the "first" card (in 0x3x0 range) and the total number of cards in the system. Bayonne assumes all Voicetronix cards will be in sequenctial addresses, and hence, if you define the first card as 0x340, and specify two cards, the second card must be set for 0x350. Multiple instances of Bayonne can be started so long as each instance uses a different set of cards. A seperate service thread is started in Bayonne for each Voicetronix card. This service thread performs all event dispatch and may be tuned for process priority scheduling and by scheduling policy for optimal performance. It is possible to have up to 16 Voicetronix cards in a single PC, for a total capacity of 64 analog telephony ports. PIKA.IVR The pika.ivr driver is used inconjunction with the Pika MonteCarlo SDK to support Pika analog telephone cards under GNU/Linux. This SDK has been made available for RedHat 6.x based systems as a RPM package which must be installed before Bayonne is "configured". The pika.ivr module can be ran from "user mode" and does not require the user to be "root". This is accomplished by making /usr/pika readable to a given user, and by setting permissions on /dev/pikadsp and /dev/pikacti device nodes to permit user level access. The ivr module supports all Pika trunk cards currently supported under GNU/Linux with the MonteCarlo SDK. These include the 4 port "InLine" series of hardware, as well as the 12 and 24 port analog DSP Daytona cards, as well as the non-DSP versions of these cards. No station side cards are currently supported, however. In addition to "DSP" cards, the pika.ivr implimentation on Bayonne supports fully "dynamic" resource assignment and can work with non-DSP cards that are mixed with DSP cards, or with systems designed with blocking factors due to less DSP resources of a given type being available than physical ports. The pika.ivr takes full advantage of MonteCarlo MVIP bus support to locate and connect DSP resources to ports on a as needed demand basis anywhere on a given host. The Pika implimentation also supports DSP based audio conferencing and mixing of multiple audio channels. This is done with the standard Pika conferencing API. Only one instance of Bayonne may be executed with the Pika DSP module running. The API uses a single global configuration and cannot dole out partial access to Pika cards to different processes. If more than one instance is started, it may lock up the whole system. DIALOGIC.IVR First, before you can use Dialogic support, you must install the Dialogic UNIX SDK for your platform. Bayonne is designed "generically" for the standard UNIX SDK, and will work with it under both Solaris and UnixWare, as well as under GNU/Linux. When using GNU/Linux, you must also install the LiS streams package. The dialogic.ivr module has been developed to autodetect Dialogic resources at startup. It should detect both analog and digital telephony devices, and will support both with the same ivr driver module, even if both types of devices are mixed on the same system. As of release 0.5.15 only analog support has been completed, but digital support should follow very quickly. The dialogic.ivr analyses and assigns ALL dialogic devices that it finds at startup. Hence, only one instance of Bayonne may be executed on any given server. The current implimentation does "static" assignment of DSP resources at startup, and requires that sufficient vox ports exist for all digital telephony interfaces found in the system. This means one cannot use plain DTI cards unless one has sufficient sc bus voice resource cards also available. This may change in future releases. ACULAB.IVR The aculab driver is in early development. It is based on the Aculab PRI and BRI span cards with Prosody support. You must install the Aculab call, voice, and switch modules and libraries before building Bayonne Aculab support. At the moment I assume that root permission is required to access the Aculab, though this may be incorrect. The aculab module does automatic card timeslot assignment and will detect and allocate aculab timeslot and card resources during startup. In that all devices are allocated at startup, only one instance of Bayonne can be executed on a single server. A single service thread is maintained for event dispatch, and a service thread is available for each telephone port. This may change later on. There is an active workgroup working on aculab support, and the mailing list for this can be found at bayonne-aculab@lists.sourceforge.net. Installing Bayonne (Basics) How to Get Bayonne You can download Bayonne either via our site http://www.bayonne.cx or directly from ftp://www.voxilla.org/pub/bayonne After download you can unpack it with: tar -zxvf bayonne-VERSION.tar.gz Substitute VERSION with the version of your package. This will unpack the Bayonne distribution in a new directory with the same name as the package. Supported Operating Systems With Milestone #5, Bayonne now supports FreeBSD in addition to GNU/Linux (and possibly Solaris). Installation Layouts System Directories System directories are installed by the distribution of the Bayonne package itself. While they can include application specific files that are placed there later, this is generally not recommended except as noted. /usr/share/aaprompts{/voice} Bayonne supplied default prompt library. These include phrasebook prompts and anything else found useful to distribute with Bayonne itself. User application voice libraries should never be installed here. /usr/share/altprompts{/voice} Maybe optionally created for single product turnkey servers. This directory is generally referenced by prompts, as in "play myprompt". /usr/share/aascripts Default system scripts supplied with Bayonne. These include test scripts and any simple applications supplied entirely with Bayonne. Turnkey applications may place script files here, though it is not generally recommended except for turnkey product servers. /usr/share/aawrappers This is a special directory to hold user supplied executables that will be executed thru the bayonne_wrapper program. These programs are generally initiated under the apache user id and converted to the bayonne user id by bayonne_wrapper. /usr/libexec/tgi This is the default directory for Bayonne supplied TGI applications. Bayonne distributions will in time add a number of useful tgi libexec files. User supplied TGI applications must also be installed here, as these run under the Bayonne server's user id. /usr/lib/bayonne/{version}/ This is the install directory for all loadable modules and plugins. There is only one directory, and DSO's are assumed to be compiled against a specific Bayonne version. User created DSO's should be installed here. VAR Directories /var/bayonne is used to host all modifyable files, both as distributed with Bayonne, and for user applications. Any reference to a partial path with at least two components will refer to here. /var/bayonne/tmp A place to record temporary files /var/bayonne/save A save filespace for serialized classes. /var/bayonne/prompts Used by the play and record script. /var/bayonne/maps Used for loadable map files. HOME Directories Bayonne itself has a home directory and user id, starting fairly recently. This is typically found as /home/bayonne. A simple "adduser -r bayonne" will create the Bayonne user. The Bayonne server itself runs under the bayonne group when started under root, and tgi executables (and wrappers) will execute with the unpriviledged bayonne user id. /home/bayonne/apps Starting with 0.5.20, this is now the prefered base prefix for installing new Bayonne applications. /home/bayonne/php A prefix for php include and drop files. /home/bayonne/admin A working directory for plugin php admin forms. /home/bayonne/html The primary document root for Bayonne integrated web applications. These are typically execute using an Apache server running under the "bayonne" user id rather than the nobody or http user. This is used for applications that include web services like unified messaging. Other kinds of Bayonne apps might integrate with an existing web application by using bayonne_wrappers instead. "Click-to-dial" typically uses wrappers rather than a seperate apache server. APPS Directories Starting with 0.5.20, /home/bayonne/apps has become a standard prefix for installing applications. A number of directories exist for this purpose, and a number of special requirements are needed to use this fully. /home/bayonne/apps/aascripts User supplied application scripts are installed here. /home/bayonne/apps/{APP}/{%voice} Each application gets it's own private voice library, which is also fully multi-lingual. For a script file to refer to it's APP prompt directory, it must use APP:: notation in play commands. For example, to play the voice mail intro prompt, one might use: "play VMS::intro". This will then play from "/home/bayonne/apps/VMS/UsEngM/intro.au". This allows one to refer to both default prompts supplied in bayonne and application specific prompts installed locally. User HOME Directories When starting Bayonne under an ordinary user id, Bayonne will use the local user's home directory rather than /home/bayonne and /var/run, for various things. These are stored under /.bayonne. This has not been changed in awhile, and is only useful if one either always runs bayonne unpriviledged, or if one is starting multiple instances for different users. /.bayonnerc Can be used to override some things found in /etc/bayonne.conf. /.bayonne{.ctrl,.nodes,.mixers} Local user priviledged versions of /var/run files. /.bayonne/schedule.conf User's private scheduler. /.bayonne/tgi User's private tgi directory when non-priviledged Bayonne is ran. /.bayonne/aascripts User's private scripts. /.bayonne/aaprompts/{%voice} User's private "" prompt path. Hence, a play myprompt" should go to here. /.bayonne/aaprompts/APPS/{%voice} When not running under a priviledged user id, the Bayonne application specific working directory will be located in the user's home rather than in /home/bayonne/apps. Hence, a "play myapp::intro" will go to " /.bayonne/aaprompts/myapp/UsEngM/intro.au" Configuring The 'configure' shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a `Makefile' in each directory of the package. It may also create one or more `.h' files containing system-dependent definitions. Finally, it creates a shell script `config.status' that you can run in the future to recreate the current configuration, a file `config.cache' that saves the results of its tests to speed up reconfiguring, and a file `config.log' containing compiler output (useful mainly for debugging `configure'). Change to the directory where the sources was unpacked and type the following to run 'configure': ./configure Running `configure' takes awhile. While running, it prints some messages telling which features it is checking for. By default, Bayonnewill attempt to build and install all of the telephony servers supported in the distribution. Since most often only a specific set of servers to support specific vendor telephony hardware you have available are needed, there are ways to select and remove vendor specific server implementations through configure. The advantage of doing this is a shorter compile time and the elimination of distractions from errors in building uneeded API trees. The "-without-pike" option removes all Pika Monte Carlo related, modules, and libraries from the build tree. The "-without-phonedev" option removes all GNU/Linux /dev/phone support. If you're using `csh' on an old version of System V, you might need to type `sh ./configure' instead to prevent `csh' from trying to execute `configure' itself. If you need to do unusual things to compile the package, please try to figure out how `configure' could check whether to do them, and mail diffs or instructions to the address given in the `README' so they can be considered for the next release. If at some point `config.cache' contains results you don't want to keep, you may remove or edit it. Compiling After you hav configured the package you need to compile it. Type the following to to compile the package: make To make sure everything went ok. Type the following to run any self-tests that come with the package: make check To install the programs and any data files and documentation type: make install You can remove the program binaries and object files from the source code directory by typing: make clean To also remove the files that `configure' created (so you can compile the package for a different kind of computer), type `make distclean'. There is also a 'make maintainer-clean' target, but that is intended mainly for the package's developers. If you use it, you may have to get all sorts of other programs in order to regenerate files that came with the distribution. Installing Bayonne (Advanced Topics) Compilers and Options Some systems require unusual options for compilation or linking that the `configure' script does not know about. You can give `configure' initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this: CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure Or on systems that have the `env' program, you can do it like this: env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure Compiling For Multiple Architectures You can compile the package for more than one kind of computer at the same time, by placing the object files for each architecture in their own directory. To do this, you must use a version of `make' that supports the `VPATH' variable, such as GNU `make'. `cd' to the directory where you want the object files and executables to go and run the `configure' script. `configure' automatically checks for the source code in the directory that `configure' is in and in `..'. If you have to use a `make' that does not supports the `VPATH' variable, you have to compile the package for one architecture at a time in the source code directory. After you have installed the package for one architecture, use `make distclean' before reconfiguring for another architecture. Optional Features Some packages pay attention to `-enable-FEATURE' options to `configure', where FEATURE indicates an optional part of the package. They may also pay attention to `-with-PACKAGE' options, where PACKAGE is something like `gnu-as' or `x' (for the X Window System). The `README' should mention any `-enable-' and `-with-' options that the package recognizes. For packages that use the X Window System, `configure' can usually find the X include and library files automatically, but if it doesn't, you can use the `configure' options `-x-includes=DIR' and `-x-libraries=DIR' to specify their locations. Specifying the System Type There may be some features `configure' can not figure out automatically, but needs to determine by the type of host the package will run on. Usually `configure' can figure that out, but if it prints a message saying it can not guess the host type, give it the `-host=TYPE' option. TYPE can either be a short name for the system type, such as `sun4', or a canonical name with three fields: CPU-COMPANY-SYSTEM See the file `config.sub' for the possible values of each field. If `config.sub' isn't included in this package, then this package doesn't need to know the host type. If you are building compiler tools for cross-compiling, you can also use the `-target=TYPE' option to select the type of system they will produce code for and the `-build=TYPE' option to select the type of system on which you are compiling the package. Sharing Defaults If you want to set default values for `configure' scripts to share, you can create a site shell script called `config.site' that gives default values for variables like `CC', `cache_file', and `prefix'. `configure' looks for `PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' if it exists. Or, you can set the `CONFIG_SITE' environment variable to the location of the site script. A warning: not all `configure' scripts look for a site script. Operation Controls `configure' recognizes the following options to control how it operates. -cache-file=FILE Use and save the results of the tests in FILE instead of `./config.cache'. Set FILE to `/dev/null' to disable caching, for debugging `configure'. -help Print a summary of the options to `configure', and exit. -quiet -silent -q Do not print messages saying which checks are being made. To suppress all normal output, redirect it to `/dev/null' (any error messages will still be shown). -srcdir=DIR Look for the package's source code in directory DIR. Usually `configure' can determine that directory automatically. -version Print the version of Autoconf used to generate the `configure' script, and exit. `configure' also accepts some other, not widely useful, options. Scripting Language Introduction With the Bayonne package a brand new scripting system, ccscript, has been introduced. ccscript differs in a number of fundimental ways from other scripting systems in that it is designed for single-step timed execution from a callback event thread. ccscript is therefore a scripting interpreter that models and controls the behavior of near realtime sequenced state-event engines such as the Bayonne server. ccscript itself offers a programming model that is easy to embed in C++, that is fully thread safe, and that can be extended thru C++ class inheritence. It also offers extremely low call overhead, and has a two phase compile/memory resident runtime environment. Finally, ccscript allows direct runtime reloading of script images without displacing currently executing scripts. In the case of Bayonne, we extend ccscript to support telephony functions of the server. The main server offers extensions to the core ccscript language, and each driver can also bind it's own driver specific commands. In some cases plugins other than drivers will also bind extensions to the script interpreter. When the server is started, or when a new "compile" request is made, the server builds the core memory script image. While runtime replacement will happen in a live Bayonne server, it will only occur when a "compile" request is made thru the fifo interface. Each script is composed of three parts; an event flag as appropriate, a script command statement, and script command arguments. Events The event flag is used to notify where a branch point for a given event occurs while the current script is executing. Events can be receipt of DTMF digits in a menu, a call disconnecting, etc. The script will immediately branch to an event handler designated line when in the "top" part of the script, but will not repeably branch from one event handler to another; most event handlers will block while an event handler is active. The exception to this rule is hangup and error events. These cannot be blocked, and will always execute except from within the event handlers for hangup and/or error themselves. Event handlers can be thought of as being like "soft" signals. In addition to marking script locations, the script "event mask" for the current line can also be modified. When the event mask is modified, that script statement may be set to ignore or process an event that may occur. The following event identifiers are considered "standard" for Bayonne: identifier default description ^hangup or ^exit detach the calling party has disconnected ^error advance a script error is being reported ^dtmf - any unclaimed dtmf events ^timeout advance timed operation timed out ^0 to ^9, ^a to ^d - dtmf digits ^pound or ^star - dtmf "#" or "*" key hit ^dialtone - dialtone heard on line ^busytone - busytone heard on line ^signal detach notify while waiting for other trunk ^part or ^cancel detach conference/join disconnect Symbol Notation ccscript recognizes three kinds of symbols; constant "values", %variables, and @indirection. A %variable has content that is alterable. Some %variables are automatically initialized for each and every telephone call, while others may be freely created by scripts themselves. A fourth class of symbol exists only at compile time, $defined symbols are substituted when the script file is compiled, and usually reduce to a simple constant, though variables can be named for the compiler. All constants are defined in the [script] section of bayonne.conf. The following variables are commonly defined: %id id, timeslot, or trunk device number %error last error message %date current date %time current time %session.id global call identifier %session.digits currently collected dtmf digits in the digit buffer %session.count count of number of digits collected %session.starttime time of call starting %session.startdate date of call starting %session.duration current call duration %session.callerid identity of calling party %session.calledid identity of how they called us %session.home initial script invoked %session.schedule script that was scheduled %pstn.dnid did number if available %pstn.clid ani or caller id number if available %pstn.name caller name if passed in callerid %pstn.redirect if origin is a telco redirect %pstn.ringid if distinctive ringing is available %pstn.infodigits if telco infodigits were passed to us %pstn.rings number of rings so far %policy.name name of policy for this session %policy.member nth member of this policy %policy.* various policy variables. %application.language current language in effect (default = "english") %application.voice current voice library in effect (default = "UsEngM") %application.name name of application grouping %audio.volume volume level in 0-100 for play and record. %audio.extension default audio file extension (.au, .wav, etc) %audio.format default audio format (ulaw, alaw, g721, etc) %audio.annotation annotation of last played or for recorded file %audio.played samples played from played file %audio.recorded samples recorded to record file %audio.created date played file was created %audio.timeout timeout in a play wait %audio.trim minimal number of samples to trim at end of file %server.ports total ports on bayonne server %server.version version of bayonne server %server.software software identifier; "bayonne" %server.driver which driver we are running %server.node node id of our server In addition, DSO based functions will create variables for storing results under the name of the function call, and the DSO lookup module will create a %lookup object to contain lookup results. Also, server initiated scripts can pass and initialize variable arguments. Basic Commands There are a number of commands that are part of the core ccscript library itself, and these are documented here. set %var values... set var=value ... set[.min|.max] %var values... Set a variable to a known value. Can also set multiple variables. Can also set a variable to the minimum or maximum value of a set of values. clear %var ... Clear (empty) one or more variables. It does not de-allocate. init %var values... init var=value ... init[.min|.max] %var values... Initialize a new system variable with default values. If the variable already exists, it is skipped. Optionally multiple variables may be initialized at one. Can also init a variable to a minimum or maximum value of a set of values. const %var values... const var=value ... Set a constant which may not be altered later. Alternately multiple constants may be initialized. size space %var... Pre-allocate "space" bytes for the following variables. select value match label [..match-label pairs] [var=val...] Select is used to branch to a new script based on matching a value or variable to a list of possible values. For each match, a different script or event handler may be selected. Options include "select.prefix" to match string prefixes, "select.suffix" to match by tailing values only, "select.length" to match by length, and "select.value" to match by numeric value. If a branch is found, an optional list of variables can be conditionally set. today[.date|.time|.unix] Creates a numeric variable as a date, time, or unix time stamp and gives it an initial value based on the current date and time. inc[.day|.hour|.min|.sec] Increment a variable, perhaps with a specified offset, otherwise by "1". Inc is aware of "time" units and can adjust dates by number of days, or times by hours, minutes, or seconds. dec[.day|.hour|.min.sec] Decrement a variable, perhaps with a specified offset, otherwise by "1". Dec is aware of "time" unites and can adjust dates by number of days, or times by hours, minutes, or seconds. goto value [var=value ...] Goto a named script or event handler in a script. If the goto is successful, an optional list of variables can be conditionally set. try values... [var=value ...] Attempt to goto one or more labels. If the label is not found in an existing script, the next one in the list will be tried. If any branch attempt is successful, then optionally variables may also be set. gosub value [var=value ...] call value Call a named script or event handler as a subroutine. If the call is successful, an optional list of variables can be conditionally set. load[.get|.post] timeout url [variables] Invoke a URL thru the plugin XML parser. This internally creates a special script set. Either the get or post method may be used, and an optional set of variables may be specified for the method. return Return from a gosub. pop Pop a gosub off the stack. if value op value label [var=value ...] Used to test two values or variables against each other and branch when the expression is found true. There are both "string" equity and "value" equity operations, as well as substring tests, etc. Optionally a set of variables can be initialized based on the conditional branch. for %var values... Assign %var to a list of values within a loop. foreach[.offset] %var %packed Assign %var from items found in a packed list. An optional offset can be used to skip the first n items. tryeach[.offset] %packed [var=value ...] Attempt to branch to a script based on the values held in a packed list. Each item will be tried in term, starting from the offset if one is specified. If a branch point exists an optional list of variables may be conditionally initialized. do [value op value] Start of a loop. Can optionally have a conditional test (see if). loop [value op value] Continuation of a for or do loop. Can optionally have a conditional test (see if). continue [value op value] Continue a loop immediately. Can optionally have a conditional test (see if). break [value op value] Break out of a loop. Can optionally have a conditional test (see if). slog[.info|.err|.crit|.debug message... Port a message to the system log as a SYSLOG message. The logging level can be specified as part of the command. exit Terminate script interpreter. Bayonne Server Commands The Bayonne server adds a number of additional ccscript commands: hangup This is the same as exit, though it can be "trapped" with a hangup handler. function name [args] Used to invoke a function from a DSO loaded module. The result of the function will be stored in a variable named %name, based on the function name invoked. alog message... Post a message immediately into the audit log. cdr message... Declaire a CDR record which will be written to the audit log when the call terminates. import %var ...vars Import a variable value from "global" name space. Normally each Bayonne trunk has it's own private name space. export %var ..vars Export one or more variables into the "global" name space.' debug message.. Send a message to the debuging monitor. sleep timeout [rings] Sleep a specified number of seconds. Can also sleep until the specified number of rings have occurred. sync timeout [rings] Wait for a specific number of seconds from the time the call was initiated. This is a time synchronized form of "sleep". A specific number of rings can also be waited for. pack %var values... Form comma seperated content in a packed %var. unpack[.offset] %var targets Unpack a comman seperated variable object into seperate variables. Sometimes operations like "lookup" will return a list of values or data fields. packed char Allows one to specify an alternate delimiter for packing and unpacking data fields. once label Within a single script, once is gaurenteed to only goto a new script (like a goto) "once". on trap label Allows one to test for a previously blocked signal and see if it had occured. If the signal had occured, then the branch will be taken. answer [rings [ringtime]] Answer the line if it has not been answered yet. Optionally wait for a specified number of rings before answering, and allow a maximum inter-ring timeout before considering that ringing has "stopped". If the rings are stopped before the count has been reached, then the call is treated as a hangup (abandon). collect digits [timeout [term [ignore]]] Collect up to a specified number of DTMF digits from the user. A interdigit timeout is normally specified. In addition, certain digits can be listed as "terminating" digits (terminate input), and others can be "ignored". flash offtime ontime Flash the line a specified number of milliseconds (offtime) and then wait for ontime. If dialtone occurs, then may be used as a branch. play[.any|.all|.one|.tmp] audiofile(s) Play one or more audio files in sequence to the user. Bayonne supports raw samples, ".au" samples, and ".wav" files. Different telephony cards support different codec's, so it's best to use ulaw/alaw files if you expect to use them on any Bayonne server. Optionally one can play any of the messages found, or only the first message found, or a temp file which is then erased after play. record[.append] audiofile [timelimit [abort]] Record user audio to a file, up to a specified time limit, and support optional abort digits (DTMF). Optionally one can append to an existing file. dial number [..more digits] Dial the specified telephone number. A "F" may be used to flash the line, and a "W" to specify a wait for dialtone. dtmf digits [...more digits] Generate DTMF digits, like with dial, but do not perform call progress analysis. transfer number [..more digits] Dial the specified telephone number and then exit. This is in effect a "blind" transfer/call release, and should use appropriate digits to achieve this effect. hold Put a call on hold and release the trunk. Script can be restarted by a hold-recall from the pbx, for example... pause milliseconds A short script pause. map[.prefix|.suffix|.absolute] mapname keyvalue [prefix..] lookup a key value in a named map table. Optionally strip off a "prefix" from the keyvalue before searching if the prefix value is found. When the key is found in the map table, the specified script is executed with map variables set. Suffix mapping can be used to reduce a route by the reverse order digits. request expires group script [parms] post a request for processing by a named trunk group. This request will be processed by an idle port in the specified group, or when such a port becomes available. The expiration allows requests to become "stale" afer a certain timeperiod if never processed due to no available ports. start offset script [parms] start a script on another trunk port as offset from the current port %id. Hence "start 1 test" starts script test on the port next to the current one, for example. Normally, a large offset like "start 24 test" might be used to start a script on the next T span. Start differs from request in that it starts the script immediately, and if the script cannot be started, it returns an immediate êrror. libexec[.once|.play] timeout program [query-parms] Execute an external application or system script file thru the Bayonne TGI service. This can be used to run perl scripts, shell scripts, etc. A timeout specifies how long to wait for the program to complete. A timeout of 0 can be used for starting "detached" commands. Optionaly one can set libexec to execute only one instance within a given script, or use .play to run an external tgi that will generate an audio file which will then be played and removed automatically when the tgi exits. speak[.any|.all] phrasebook-rules words... Used to impliment phrasebook rules based prompt generation. See PROMPTS.TXT. tone tone-name [duration-msec [repeat]] This can be used to emit tones defined from the bayonne.conf file. has keyword label Perform a branch operation if a specified keyword exists (as in a test for a bound module). missing keyword label Perform a branch operation if a specified keyword is missing. schedule name or * Select alternate scheduling "name" to be in effect or use "*" to clear. signal trunk [msg] Send a signal to a trunk in a wait state such as joinable. idle timeout Set idle timeout value. read %var... read.from script Read data lines embedded in a script into a set of variables. One can also specify the script to start reading from. data values... Embed data for a read statement in a script. gather %packed member Gather a packed list of the names of all scripts that contain a specific or named ::member script. This can be used to determine what scripts or apps are present and to generate a menu based on that at runtime. swap %var1 %var2 Swap two variables. alias %var %newvar Alias a variable so that every reference to %var will automatically goto %newvar. dirname %var Much like the shell dirname, to extract a directory name from a path. basename %var [extensions...] Reduce a variable to a simple base filename, and strip any of the optionally listed extensions from it. fullpath %var fullpath If %var is a partial pathname, then merge it with the passed path to form a complete pathname. insert[.offset|.end] %var values... This can be used to insert new digit values into a string either at the start, or a specific offset. delete[.offset|.end] %var patterns... This is used to strip patterns of digits either from the start or a specific offset in, a digit string. If a given pattern is found, it is removed. chop[.offset|.end] %var count... This is used to chop out a specific count of digits from within a string. trim[.offset|.end] %var count.. This is used to trim leading and trailing digits outside of the range of count and offset specified. It's the inverse of chop. Optional Commands Some commands are only implimented by specific drivers. The missing and has functions could be used to test if your driver supports a specific feature or function. The following may exist: join trunk duration Join a joinable trunk for a specified duration. wait duration Indicate we are joinable for a specified duration. rtp address portnbr [portbind] Connect a telephony port to a RTP session directly. duplex recordfile [playfiles...] Simultaneous play and record. enter id Join a TDM conference resource. leave Leave the currently joined conference. detect timeout Perform call progress detection for a specified timeout. Phrasebook Rules Introduction Bayonne is provided with a standard "prompt" library which supports prompts for letters and numbers as needed by the "phrasebook" rules based phrase parser. The phrasebook uses named rules based on the current language in effect, as held in "%language" in ccscript. Phrase rules can be placed in bayonne.conf proper under the appropriate language and in application specific conf files as found in /etc/bayonne.d. English "rules" are found under section [english] in the .conf files, for example. Phrasebook prompts are used to build prompts that are effected by content. Lets take the example of a phrase like "you have ... message(s) waiting". In english this phrase has several possibilities. Depending on the quantity involved, you may wish to use a singular or plural form of message. You may wish to substitute the word "no" for a zero quantity. In Bayonne phrasebook, we may define this as follows: in your script command: speak &msgswaiting %msgcount no msgwaiting msgswaiting We would then define under [english] something like: msgswaiting = youhave &number &zero &singular &plural This assumes you have the following prompt files defined for your application: youhave.au "you have" no.au "no" msgwaiting.au "message waiting" msgswaiting.au "messages waiting" The system will apply the remaining rules based on the content of %msgcount. In this sense, phrasebook defined rules act as a kind of "printf" ruleset. You can also apply rules inline, though they become less generic for multilingual systems. The assumption is that the base rules can be placed in the [...] language area, and that often the same voice prompts can be used for different effect under different target languages. The speaking of numbers itself is held in the default Bayonne distribution, though the default prompt list can also be replaced with your own. Rules can also appear "within" your statement, though this generally makes them non-flexible for different languages. Speaking of currency "values" have specific phrasebook rules. Currency values are also subject to the "&zero" rule, so for example: balance=youhave &cy &zero remaining and using: speak &balance %balance nomoney can use the alternate "no monay" .au prompt rather than saying "0 dollars". English The following default phasebook rules are or will be defined for english: &number speak a number unless zero &unit speak a number as units; zero spoken &order speak a "order", as in 1st, 2nd, 3rd, etc. &skip skip next word if spoken number was zero. &ingore always ignore the next word (needed to match multilingual). &use always use the next word (needed to match multilingual). &spell spell the word or speak individual digits of a number. &zero substitute a word if value is zero else skip. &single substitute word if last number spoken was 1. &plural substitute word if last number spoken was not 1. &date speak a date. &day speak only day of the week of a date. &time speak a time. &primary speak primary currency value (dollar(s) and cent(s)) &local speak local currency &duration speak hours, minutes, and seconds, for duration values. &cy speak default currency (either primary, local, or both) Number Prompts 0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 30, 40, 50, 60, 70, 80, 90, hundred, thousand, million, billion, point Order Prompts 1st, 2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th, 11th, 12th, 13th, 14th, 15th, 16th, 17th, 18th, 19th, 20th, 30th, 40th, 50th, 60th, 70th, 80th, 90th Date/Time Prompts sunday, monday, tuesday, wednasday, thursday, friday, saturday january, february, march, april, may, june, july, august, septermber, october, november, december am, pm Currency Prompts dollar, dollars, cent, cents, and, or TGI Services Introduction Has yet to be written... Wrapper Introduction So, you want to integrate Bayonne with the Web? There are numerous reasons for wanting to do this. Perhaps you are building a unified messaging server with Bayonne, or are trying to build a "click to dial" front end for a Bayonne call agent server or as a compliment to online customer service. While on the surface these may sound similar, they actually are not at all in operation or implimentation. Using Bayonne with an existing site Starting with 0.5.15, a new Bayonne executable, the "wrapper", was introduced. This is typically used to bridge between a web server, typically running under user id "nobody" or "http", and a Bayonne server, typically running under user id "bayonne". The wrapper (bayonne_wrapper) acts as a simple "sudo" facility, where you specify which scripts the bayonne wrapper will be permitted to execute based on the original requestors "user id". This is done in the [wrappers] section of Bayonne.conf. Basically one enters the user id and a list of permitted scripts. This list of permitted scripts always execute from /usr(/local)/share/bayonne/aawrappers. Bayonne_wrapper itself runs as a setuid executable, and the scripts or shell commands found in aawrappers are given the user id of the Bayonne server. These scripts also receive useful information in their environment space that is similar to "TGI", but without port specific information. In particular, a wrapper initiated image receives the server software and version information (BAYONNE_SOFTWARE, BAYONNE_PROTOCOL, BAYONNE_PLATFORM), the token seperator to use for fifo control (BAYONNE_TOKEN), the Bayonne node id (BAYONNE_NODE), and the location of the Bayonne fifo and control files (BAYONNE_CONTROL). In addition, the defined trunk group policies are passed as "BAYONNE_POLICIES". No "PORT_xxx" symbols are passed since the wrapper script is not nessisarly executing on behalf of a specific and dedicated port resource. NOTE: These symbols were originally named "SERVER_" in bayonne_wrapper, but were changed to "BAYONNE_" starting with 0.5.17 to avoid conflicts with CGI initiated scripts. A web server or any other application can use wrapper to invoke executables in aawrappers that manipulate the Bayonne server in a controlled and secure fashion. A wrapper can be invoked thru a CGI and then receive both the web server's CGI state information, and the Bayonne symbol set. A CGI executed wrapper of course can send html back thru stdout to form a web page for the user. Starting with "0.5.17", Bayonne wrappers can also be used to execute scripts that require interpreters in a fairly direct fashion. For example, if we have a "webdial.cgi" script written in perl, you will be able to specify as the first line of your script file: #!/usr/bin/bayonne_wrapper -perl This will re-execute the script with the perl interpreter under the specified user id of Bayonne. Similarly, one can then use -bash for /bin/bash, and others for other common shells and interpreters. This provides a simple and direct means to integrate cgi operation with a Bayonne server. In fact, one could use the alias map of apache or other web servers to map the aawrappers directory under a "/bayonne" url as a convenient means to access commonly used wrappers in this way, and in the future some scripts will be provided in the default distribution of Bayonne for this purpose. Running Bayonne seperate from your web server When you have an existing site, you may not wish to run web servers on Bayonne themselves. You might have a e-commerce "site" you wish to add Bayonne to provide some service, but this need not mean that you install Bayonne on your web server farm, or that Bayonne need even run a publically accessible web server of it's own that has seperate or additional security issues. Bayonne_wrappers support the use of "ssh" to invoke a bayonne wrapper application on a Bayonne server from a remote machine. This is done by placing a truncated /etc/bayonne.conf file which indicates the node name of the Bayonne server it should contact, and the wrapper permissions to use. The "bayonne_wrapper" will assume to automatically use ssh if the /usr/share/aawrappers directory is not found on the local machine. On the remote (web server) machine, you will need to create a bayonne "user id". This user id should contain a .ssh/config "entry" with the same name as the Bayonne "node" id in the local /etc/bayonne.conf file, and should list the hostname to actually contact. You will also need a passwordless ssh key to use between the Bayonne server and the web server. This will allow the bayonne_wrapper to automatically hop between the machines. The bayonne_wrapper can be symlinked or placed in the web server's cgi directory under the name you will execute the program in "aawrapper" on the Bayonne server under. Hence, you would take bayonne_wrapper, call it for example "webdial.cgi", and place it on the cgi directory of your web server. Since there is no local aawrappers directory, it will initiate a ssh to the Bayonne box and then execute the "real" webdial.cgi from the aawrappers directory there. SSH does not automatically preserve environment state variables. While bayonne_wrapper has supported ssh for awhile, it is only with 0.5.17 and above does it now preserves key CGI environment variables when it hops between the local and remote machine. More on running web services on a Bayonne server While wrappers do allow one to execute Bayonne in conjunction with a web server, this is not nessisarly the most efficient manner to do this. A higher demand application might suffer from the performance hit of executing cgi. However, there is one other option currently available. Certainly one can execute and access Bayonne resources directly if one places a web server on a machine running Bayonne and then has it execute under the same user id that Bayonne does. This allows one to use one of the various highly efficient "mod_xxx" intepreters (like mod_php or mod_perl) to build a web integrated Bayonne service rather than requiring cgi wrappers everywhere. Incidently, Bayonne can of course alternately be executed under the same user id as the web server. Which one to change probably depends on your actual need. You can of course also run multiple web server deamons, and have one of them execute under Bayonne's user id. Corba and other future services In the future we are looking at using Corba. Corba would eliminate the use of ssh and the difference in operations between a local web cgi or server application invoking services on a locally resident copy of Bayonne vs a copy running on a remote server. The Corba interface for Bayonne will be in the form of a plugin which accesses Bayonne server resources as a "whole". Hence, one would have a client object that represents a Bayonne server which can be directly manipulated thru Corba IDL invoked methods rather than thru control files and fifo's. Of course, not all languages have commonly used Orb's, and I am not sure if there even is one for php, for example. Still, a Bayonne "orb" interface would provide a direct means of controlling the server as a whole. For the desktop user, and to telephony enable desktop applications, like pop-up screens when calls come in, or dialing names from an address book, TOSI will be used, and Bayonne will offer a TOSI server for desktop applications to access using the TOSI interface library definition. I do not know if TOSI will also ever be used for the purposes of Web integration, but it is not impossible. About this document ... Bayonne User Manual This document was generated using the [62]LaTeX2HTML translator Version 99.2beta8 (1.42) Copyright © 1993, 1994, 1995, 1996, [63]Nikos Drakos, Computer Based Learning Unit, University of Leeds. Copyright © 1997, 1998, 1999, [64]Ross Moore, Mathematics Department, Macquarie University, Sydney. The command line arguments were: latex2html -nosubdir -split 0 manual.tex The translation was initiated by David Sugar on 2001-04-21 _________________________________________________________________ next_inactive up previous David Sugar 2001-04-21 References 1. file://localhost/home/dyfet/src/bayonne/doc/manual.html 2. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00020000000000000000 3. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00021000000000000000 4. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00022000000000000000 5. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00023000000000000000 6. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00024000000000000000 7. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00025000000000000000 8. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00030000000000000000 9. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00031000000000000000 10. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00032000000000000000 11. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00040000000000000000 12. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00041000000000000000 13. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00050000000000000000 14. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00051000000000000000 15. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00052000000000000000 16. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00053000000000000000 17. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00054000000000000000 18. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00055000000000000000 19. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00060000000000000000 20. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00061000000000000000 21. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00062000000000000000 22. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00063000000000000000 23. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00064000000000000000 24. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00065000000000000000 25. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00066000000000000000 26. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00067000000000000000 27. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00070000000000000000 28. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00071000000000000000 29. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00072000000000000000 30. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00073000000000000000 31. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00074000000000000000 32. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00075000000000000000 33. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00080000000000000000 34. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00081000000000000000 35. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00082000000000000000 36. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00083000000000000000 37. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00084000000000000000 38. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00085000000000000000 39. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00086000000000000000 40. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00090000000000000000 41. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00091000000000000000 42. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00092000000000000000 43. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00093000000000000000 44. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00094000000000000000 45. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00095000000000000000 46. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION00096000000000000000 47. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000100000000000000000 48. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000101000000000000000 49. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000102000000000000000 50. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000110000000000000000 51. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000111000000000000000 52. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000120000000000000000 53. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000121000000000000000 54. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000122000000000000000 55. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000123000000000000000 56. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000124000000000000000 57. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000125000000000000000 58. file://localhost/home/dyfet/src/bayonne/doc/manual.html#SECTION000130000000000000000 59. http://www.ostel.com/ 60. http://www.teklab.com/ 61. http://www.mysite.se/ 62. http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/ 63. http://cbl.leeds.ac.uk/nikos/personal.html 64. http://www.maths.mq.edu.au/~ross/