About Coventry

Coventry is a simple to setup IP telephony server for residential gateways and small office users. Coventry interconnects SIP users and devices with advanced voice, messaging, and facility automation services. Coventry would be used either stand-alone, such as off-grid facilities or boats, or connected thru upstream adapters to a carrier provider, a residential apartment complex switch, a SIP trunking provider, etc.

Other potential uses include remote property management, connecting security services, and general home automation. Coventry is meant to be runnable on gnu/linux servers and routers or in a container. My preferred installation target is a dedicated 32 bit arm device running Alpine Linux. A 2 digit local dialing plan and a maximum of 80 locally connected sip devices are supported.

When used as a residential ip telephony gateway Coventry may not include dedicated operator consoles or application services. Simple common residential style ringing would be used for external calls. A local sip application or media server like Bordeaux could be added to Coventry. Otherwise application services would likely be externally hosted. External connections such as to the PSTN would also typically be handled thru an upstream adapter.

Coventry originally was a small stand-alone gnu sipwitch VoIP wifi access point for use on early Raspberry Pi's first deployed in 2013. A few were made for residential use at the time, and I also used it when speaking at conferences. The Coventry codebase has no common code with gnu sipwitch, but it does use ideas from the development of SipWitchQt, including a simplified threaded event driven actor messaging system and shared pointer objects to avoid lock contention, but does so using only the c++17 standard library.

Traditional Installation

Coventry requires eXosip2 version 5.3.0 or later and either openssl or libressl to build and run. A typical "install" target is created to support local installation. This should include an example config file. On openrc systems this may install an init script. A logrotate config can also be added. All running directories that may be required are either made by "install" or created when the service executes. Execution in daemon mode is done by the init script. The coventry.conf file (or custom.conf) should be edited for any sip extensions you wish to use.

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 coventry binary has been built for to use. Fully static releases can be built on Alpine Linux.

Testing Coventry

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 such as with ./server/coventry -vvvv, 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.

The test target runs a unit test framework. At the moment this only verifies some of the header libraries. It may be extended to support component level unit testing in the future.

A simple test/custom.conf to test your server might look like:

[server]
algorithm = md5
expires = 2m

[20]
name = dyfet
display = David Sugar
password = XXX

[89]
name = bordeaux
display = Bordeaux
password = XXX
lines = 20

For clients, the user id used for authentication is the same as the extension number, and Coventry should be in the default route or set as default proxy.

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 additional tarballs itself. The dist target only works with a git clone.

Participation and Documentation

Basic documentation is provided as markdown files. User operation, server admin, and configuration should be similarly added here. An installation guide for various GNU/Linux distributions and BSD systems may also be added. Developer documentation can be generated from source file headers using Doxygen and the ``docgen'' target. Documentation generated from the latest release tag is found at https://doc.gnutelephony.org/coventry.

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

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.

I chose to focus on Alpine Linux for deployment on low end arm devices since it includes pre-packaged support for SIP device provisioning integrated with their web front-end. This should make it easier to create complete stand-alone residential deployments. Coventry has no restrictions on it's deployment or uses, and I do welcome participation, patches, and testing on any platform it can be adapted for and ran on, including BSD systems. However it is possible my initial project documentation will be very Alpine focused.

Support

Support is offered thru https://git.gnutelephony.org/coventry/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.