L2CPBG

# LDAP-2-CardDAV Phone Book Gateway (l2cpbg)

An LDAP to CardDav (1 way read) Phone Book Gateway.

## Use case

Most modern (business) voice phones have the capability to do

comfortable LDAP directory look-up like:

-   Directory search by alphabet letters

-   Reverse lookup for in- or out-bound calls

-   Reverse lookup by entering parts or the phone number

Unfortunately, most of the 'smaller' companies (i guess companies beyond

100 employee) don't have an 'enterprise' LDAP directory, much less than

private persons.

Most of such companies do have something like a cloud address book,

often based on WebDAV / CardDAV (i.e. Nextcloud, Ownlcoud, Baïkal,

Daylite, ...).

This is, where this Gateway might make your live easier.

If this program get started on some kind of hardware (Windows, macOS or Linux), it will do the following:

1.  Query your CardDAV Server for relevant entries, and cache them to a

    small local database

2.  Wait and answer for LDAP requests from your voice phone(s)

## Features

-   Query your CardDAV address book(s) by entering the alphabetic

    letters (or parts of the telephone number) in your (LDAP capable)

    phone (and dial one of the matching numbers).

-   Reverse lookup inbound calls and display matching contact

    informations on the phone.

-   Work with local formatted (non- E.164) CardDAV entered phone numbers

    like: '040-123456' or '001 807 1234567' as well as '+49 (0)40

    1234567-8' = no need to enter your phone numbers within your CardDAV server in a special notation.

-   Supports internal (extension) phone numbers.

-   Support dial prefix for external line.

## Usage

You need some kind of 24/7 machine where this gateway live. Windows PC,

Linux, macOS, Raspberry or the like.

By default it will look for a configuration file in the following places (in the

given order):

1.  ./l2cpbg.conf

2.  /etc/l2cpbg.conf

It will write to a small local database directory (defaults to '/tmp/l2cpbg.db').

At the moment there's no "Admin GUI" or something like it. But for miminimal infos like "uptime", "license", "number of search requests" as well as "number of sent result records" you might send the l2cpbg process a `SIGHUP` signal and check the logs afterwards.

## Installaton

### Linux Debian ".deb" packages

`dpkg -i l2cpbg-<version>_<architecture>.deb` to install the package.

A sample configuration get places at `/etc/l2cpbg.conf`.

Initial startup will fail due to wrong/missing settings in config section `[dav]`!

Adapt at least `[ldap]`, `[ldap.bind]`, `[dav]` as well as `[location]` sections (in /etc/l2cpbg.conf) to your need.

Once done, restart l2cpbg by `systemctrl restart l2cpbg` and check startup by `systemctrl status l2cpbg`.

The full log can be read by `journalctl -u l2cpbg`.

To watch the actual/live logging, use `journalctl -fu l2cpbg`.

If l2cpbg started up, adapt your phone(s) to point their "LDAP Directory" lookup requests to l2cpbg with the settings you defined in /etc/l2cpbg.conf.

### Binary only "tar.gz" or ".zip" packages

No installation required. Only a simple executable and a configuration file.

Copy the binary `l2cpbg` wherever your like. For Linux, a common/good place would be `/usr/local/bin`.

Same with the `l2cpbg.conf` file. For Linux, a common/good place would be `/etc`.

The l2cpbg binary doesn't has a "daemonize" option, so it always runs in foreground. If you require to log off out of your machine, run it i.e. via 'screen' or check/adapt the systemd script from one of my ".deb" packages, to your needs.

## ~~Hotkeys~~

~~There are some hotkeys available on the console.~~

~~Hotkey  Description~~

## Configfile syntax

Since version 0.9.0 the config file syntax has changed from 'ini' to 'toml'. Not a big deal, but you need to adapt some entries. Mainly strings have to be entered within quotes!

Following a quick minimal sample:

```

# Comments get started with a hash character

#

# The Gateway will act as LDAP Server, listening

# for requests from your phone(s).

#

[ldap]

  host      = "0.0.0.0"

  #port     = 1389

  base      = "dc=example, dc=com"

[ldap.bind]

  dn   = "cn=pbx"

  pass = "your-password"

#

# Your CardDAV server where this Gateway get the contacts from

#

[dav]

  server       = "https://cloudserver.example.com/remote.php/dav"

  user         = "cloud-login-name"

  pass         = "cloud-login-password"

[location]

  int           = 1     # Your international code. 1 = US, 49 = Germany, ...

  area          = 807   # Your local area code (without a leading 0)

  maxarealength = 7

  country       = "EN"

```

### Config file description (by section)

#### \[ldap\] = LDAP Server settings

`host` : Which IP to listen for LDAP requests. Defaults to "0.0.0.0" = 'Listen on all interfaces'. You've to point your LDAP phone settings to this machines IP/hostname.

`port` : Which port to listen for LDAP requests. Defaults to port 1389. The standard LDAP port is 389, so you need to change your phone to the port you configure here.

`base` : This LDAP's 'base DN'. Choose whatever you want, but use the same settings within your phone's LDAP settings. Defaults to 'dc=example, dc=com'.

#### \[ldap.bind\] = LDAP bind/auth settings

`dn` : Distinguish name. Name, how the phone has to log into/authorize

to the gateway.

`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.

#### \[dav\] = WebDav/CardDav server settings

`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!

`user` : WebDav username with read access to the relevant addressbook which shall be requested for phone book lookups. Might also be a 'shared' address book.

`pass` : Related user password.

`addressbooks` : Optional regular expression string of matchable addressbook(s)

used for phone book lookups. If unsure, enter something. l2cpbg will log

all found address books of the logged in CardDav user during startup and

log them as 'Non-matching' or 'Matching' address book(s).

`syncinterval` : Interval of CardDav sync checks. Given as string with suffix 'm' for minutes, or 'h' as hours. Has to be greater than "2m".

`chunksize` : If an address book get loaded the first time, it get loaded in "chunks of contacts" in this given size. You may increase this value for quicker initial load, but if your CardDAV server answer with an "507 Insufficient Storage" error or similar, you need to lower this value. Default to 200. This option was added in L2CPBG version 0.8.1.

`insecurecert` controls whether a client verifies the server's certificate

chain and host name. If insecurecert is true, crypto/tls accepts any

certificate presented by the server and any host name in that certificate.

In this mode, TLS is susceptible to machine-in-the-middle attacks unless

custom verification is used. This should be used only for testing or in

trusted environments. Defaults to *false*. This option was added in L2CPBG version 0.9.1.

#### \[dav.map\] = CardDav mapping

`tel` : CardDAV attribute which contain phone numbers. Normally (and

by default) 'TEL'. Don't change this, except your really know what you're doing.

#### \[location\] = Local area settings

`int` : International area code (1 = North America, ..., 44 = United

Kingdom, 49 = Germany, ...) of your location.

~~`intPrefix` : Dial prefix for international calls. Mostly "00". Defaults to "00".

ATTENTION: Has to be entered as string like "00".~~

`area` : Local area code without leading 0 (20 = London (UK), 40 =

Hamburg (DE), ...).

`areaPrefix` : Dial prefix for national calls. Mostly "0". Defaults to "0".

ATTENTION: Has to be entered as string like "0". 

`maxarealength` : Longest possible length of a telephone number within

your local area. If a found or received number is shorter or equal, it's

identified as a number without local area code.

`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (i.e. US, GB, DE, ...).

`maxintlength` : Maximum length of internal phone numbers. These numbers

don't get harmonized or E.164 converted.

`prettifyNums` : By default phone numbers loaded from CardDAV get prettified in two ways:

At first, if a CardDAV number is stored in international format, but you live in the same country, the international part get removed.

At second, the number get formatted in (spaced or braced) number groups as it's common in your country.

You can disable this prettifying by setting the value to false.

`extdialprefix` : Optional external dial prefix for getting an external line. Get prefixed before the phone number if outgoing number length \> `maxintlength`

#### [log] = Logging

`level` : Log level. Might be one of "trace", "debug", "info", "warn", "error" or "panic". Defaults to "info".

The log levels are organized as follows:

`trace` : This is the most verbose log level. It logs simply everything.

Never use it in production environment as it might produce an awful amount of log entries!

`debug` : Logs a lot internal stuff, probably interesting when searching

a solution for an issue. Should not be used in production environment as

it produce also a lot log entries!

`info` : This is the most usual log level. Logs only stuff which is relevant.

`warn` : Logs stuff which doesn't behave as expected. Not critical (generic functionality should be okay) but should be noticed/checked.

`error` : Something essential/critical happened. Functionality is limited or aborted at all.

`panic` : Game over.

#### [db] = Internal database

`directory` : An own directory where to store the internal database. Defaults to '/tmp/l2cpbg.db' which is not very useful on Linux based systems as it normally get cleaned after each reboot.

Choose yourself where to store the database.

If you've a small CardDAV server with <= 200 contacts, let the DB in /tmp.

An initial sync of 200 contacts (after a reboot) will be quickly done.

Not much storage space is needed. An CardDAV server with approx. 4 thousand contacts, take about 10 MByte storage.

ATTENTION: If you use one of the .deb packages, the binary get started as user l2cpbg.

Thus, the given directory here, manually need to made owned by l2cpbg via `chown -R l2cpbg:l2cpbg /your/db/directory`!

Otherwise the DB process miss read/write permissions and will fail!

#### [ldap.map...] = LDAP/CardDav mapping

Every LDAP attribute which is used within a phone(s) filter or response,

need to have a corresponding CardDav mapping which get done as follows:

First you need to define a separate block for the LDAP attribute in the

following syntax: `[ldap.map.<ldap attribute name (case sensitive)>]`

Within such a LDAP mapping block you have to define:

`dav` : Corresponding CardDav field/attribute name.

and optional define the following settings:

`itypes` : Regular expression (RE2 syntax) of including relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).

`etypes` : Regular expression (RE2 syntax) of **excluding** relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).

`index` : Zero based index in the case of a multi-value CardDav field.

For an overview of the predefined/default LDAP/CardDav mappings, take a

look into 'l2cpbg.sample.conf' file.

## Phone configuration

### Gigaset

Here's a configuration sample of a Gigaset N510 IP PRO:

![Gigaset N510 IP PRO settings sample for L2CPBG 0.7.0](https://projects.shbe.net/attachments/download/19/config_gigaset-n510-ip-pro_v070_de.jpg "Gigaset N510 IP PRO settings sample for L2CPBG 0.7.0")

Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Serverport')

'BaseDN', 'Common User Name' and 'Common Password' get filled with the same values as defined in your L2CPG config file.

### Yealink

Another configuration sample of a Yealink SIP-T52S:

![Yealink SIP-T52S settings sample for L2CPBG 0.7.0](https://projects.shbe.net/attachments/download/18/config_yealink-t52s_fw7084_v070_en.jpg "Yealink SIP-T52S settings sample for L2CPBG 0.7.0")

Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Port').

'Base', 'User Name' and 'Password' get filled with the same values as defined in your L2CPG config file.

### Snom

The LDAP configuration of Snom phones look similar to the ones of

Gigaset or Yealink.

But a user reported that entering `(|(cn=*%*)(sn=*%*)(givenName=*%*)(company=*%*))` within 'LDAP name filter' did the trick for working name searches.

## Compatibility

This software is/was tested with:

-   CardDAV Server:

    -   [Baïkal](https://sabre.io/baikal/) version 0.7.x

    -   [Daylite](https://www.marketcircle.com/)

    -   [Nextcloud](https://nextcloud.com/) version 13, 15, 16, 18 & 20

-   Phone Extensions:

    -   [Gigaset](https://www.gigasetpro.com/) N510 IP PRO, 670 IP Pro

    -   [Grandstream](http://www.grandstream.com/) GXP2170

    -   [Snom](https://www.snom.com/) 300, D315, D335

    -   [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W

-   Gateway Host OS:

    -   [Debian](https://www.debian.org/) Stretch 9.x, Buster 10.x (running at amd64 as well as ARMv7)

    -   [Gentoo](https://www.gentoo.org) amd64

    -   [macOS](https://www.apple.com/macos/) ™ Sierra 10.12.6

    -   [Ubuntu](https://ubuntu.com/) 20.04 (Focal Fossa)

## Limitations and Known Issues

There are already some known issues!!! Not sure which will get fixed, might depend on how much people are interested in.

-   The internal LDAP Server doesn't support LDAPS (encrypted LDAP

    communication) at the moment. Therefore 

    **it should not be used in an untrusted network!**

## Support & getting help

For getting help or discussing l2cpbg, please browse the [L2CPBG

Forum](https://projects.shbe.net/projects/l2cpbg/boards) or check/open

the [Tickets](https://projects.shbe.net/projects/l2cpbg/issues) area.