About Bordeaux

Bordeaux is a voice application server for IP telephony networks. Bordeaux began with GNU Bayonne and ideas I had for creating real-time non-blocking carrier scalable general purpose telephony servers using GNU/Linux. Many of the architectural advances made in GNU Bayonne were ahead of common practices back then, and some still remain so today. This is why I am introducing Bordeaux using modern software practices as a micro-services capable Bayonne replacement without support for legacy telephony networks.

Loadable driver modules are used to adopt Bordeaux to the needs of particular VoIP phone systems. A generic driver can be used with most SIP based phone services. The coventry driver is specifically adapted for use with a coventry call server. There may be a driver made for H323 to use with GNU Gatekeeper, and a driver specifically for IMS carrier uses. Classic telephony hardware, which GNU Bayonne originally had extensive direct support for, will be used thru thru network enabled VoIP gateways such as Bristol instead.

Traditional Installation

Bordeaux requires eXosip2 version 5.3.0 or later and either openssl or libressl to build drivers for and run SIP based deployments. The OpenH323 stack will be used to build GNU Gakekeeper driver support. Bordeaux normally operates as a service and if the systemd support library is present at build time then support for the systemd notify socket may also be added.

Installation should only be attempted with cmake release builds. The preferred cmake build type for live installations is cmake -D CMAKE_BUILD_TYPE=RelWithDebugInfo .. This retains debug symbols in release builds which many gnu/linux packaging systems then strip off and separately generate a debug package.

Many paths are set by cmake configuration for release builds, and these can be overriden using CMAKE -D... . overrides. Some of these are listed with the --version option, so you can always find what paths a given bordeaux binary has been built for to use. Fully static releases can be made on Alpine Linux bound to a single driver. Otherwise drivers are loaded at runtime.

When installing a non-static build of Bordeaux, header files are installed. This allows drivers to be developed and compiled separately from Bordeaux itself. Unlike some, we export the posix symbol space of the Bordeaux server directly, rather than using an intermediary shared library to support plugins. This is something I started long ago with Bayonne. This means symbol references and supporting code is not PIC, as happens in a shared library.

Testing Bordeaux

When cmake -DCMAKE_BUILD_TYPE=Debug . is used to produce a Debug build it can be executed directly for testing from the server build directory; no further install is required. The debug build uses the config file found in the test/ directory, and a test/custom.conf file can be added with configuration overrides for local developer testing. Testing scripts, prompts, and libexec telephony lambdas may also be placed in the test/ directory.

There is a test target which builds and executes a debug server. The server also includes a built-in regression test. This can be executed with just server/bordeaux, and verbose levels can be used. Technically this is the same as server/bordeaux -g test, and uses the special test driver (drivers/test/) which has a suite of regression tests.

If you have coventry setup, it is easy to test and see Bordeaux operate using debug level 4 on both servers. You might use a command like ./server/bordeaux -d coventry -vvvv after building. The default test script is named after the driver, so you can create a simple test/coventry.scr to get started like:

@ring
    sleep 8     # sleep 2 rings...
    answer
    sleep 8
    exit

And a test/custom.conf like:

[server]
media = 192.168.1.20

[coventry]
route = localhost
extension = 89
password = XXX
dialplan = 10
port = 5054

Distribution tarballs

The dist target is used to make detached tarballs with sources. This can be used to make packages for gnu/linux distributions and bsd ports, such as for arch, debian, alpine, redhat, etc. If the CMakeLists.txt refers to an already tagged release version, it will re-create the source tarball of that release at the time it was tagged. The master branch is usually ahead of the last release, so any new work will create a tarball based on your last git commit.

Detached tarballs can be used to configure and build this software without git, such as on a ci builder. It should not be used to make local changes outside of git, and cannot produce add

Participation and Documentation

Basic documentation is found as markdown files. An installation guide for various GNU/Linux distributions and BSD systems may also be added. A scripting guide for Bordeaux's call processing language, and a guide for writing telephony lambdas will also be included. Developer documentation can be generated from source file headers using Doxygen. Bordeaux relevant documentation may also be found in other projects that may use it to provide voice application services.

A more complete overview of participation is provided in CONTRIBUTING.md. This project uses cmake, and c++17 for core server development. We use the ctest framework for unit testing and gcovr for coverage reports. Bordeaux can be built with gcc or clang and can be tested on just about any posix platform, including bsd systems and even potentially MacOS, not just GNU/Linux.

In addition to producing testable debug builds the project can also be built for running unit tests. This is enabled by default for debug builds. To produce coverage reports you can cmake a debug build with -DCOVERAGE_TYPE=gcov set. You can then use the make the "coverage" target and produce coverage reports with gcovr or lcov. The "lint" target will validate code using cppcheck.

The easiest way to begin participation is installing doxygen and graphviz, and then building the ``docgen'' target. This produces browsable code documentation and provides quick access to project resources, such as the issue tracker, project boards, pull requests, milestones, the project development wiki, etc. Finally, https://doc.gnutelephony.org/bordeaux offers documentation built from the latest release tag.

Support

Support is offered thru https://git.gnutelephony.org/bordeaux/issues. When entering a new support issue, please mark it part of the support project. I also have dyfet@jabber.org. I may maintain system packaging for some GNU/Linux distributions, including Arch and Debian. I also have my own build infrastructure for Alpine Linux using ProduceIt, and I publish apk binary packages thru https://public.tychosoft.com/alpine. In the future maybe other means of support will become possible.