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'.

  - 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, Linux, macOS, (ARMx might come later if someone is interested in).

In this early 'beta' version, it runs in foreground. So, if you require to log off out of your machine, run it i.e. via 'screen'.

No installation required. Only a simple executable. Place it wherever your like. But I advice to start it as normal (non-root, non-administrative) user.

It will look for a configuration file in the following places (in the given order):

1.  ./.l2cpbgrc (or in it's parents)

2.  $HOME/.l2cpbgrc

3.  $HOME/.config/l2cpbg

4.  /etc/l2cpbgrc

5.  and some more uncommon places

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

## Hotkeys

There are some hotkeys available on the console.

| Hotkey | Description                                                             |

| ------ | ----------------------------------------------------------------------- |

| H or ? | Quick hotkey help list                                                  |

| L      | License info                                                            |

| S      | Sync with CardDAV server (instead of waiting for the next syncinterval) |

| U      | Uptime info                                                             |

| V      | Version info                                                            |

## Configfile syntax

The config file syntax is 'ini' based. Following a quick minimal sample:

```

; Comments get started with a semicolon

;

; The Gateway will act/listen as LDAP Server with the following settings

;

[ldap]

  host      = 0.0.0.0

  ;port      = 1389

  base      = dc=example, dc=com

[ldap.bind]

  dn   = cn=pbx

  pass = your-password

[dav]

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

  user         = cloud-login-name

  pass         = cloud-login-password

  ;addressbooks = regular-expression-of-lookup-adressbook

  syncinterval = 5      ; Minutes

[location]

  int           = 1

  area          = 807

  maxarealength = 7

  language      = en

  ;maxintlength = 3

  ;extdialprefix = 0,   ; External dial prefix if called number > maxintlength

[log]

  conslevel    = verbose   ; Console log level. Might be one of silly, debug, verbose, info, warn or error

  ;filename     = ./l2cpbg.<notextile>%</notextile>DATE<notextile>%</notextile>.log    ; Might contain a '<notextile>%</notextile>DATE<notextile>%</notextile>' placeholder

  ;filelevel    = info      ; File log level. Might be one of silly, debug, verbose, info, warn or error

```

### Config file description

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

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

`port` : Port to listen for LDAP requests. Defaults to port 1389. You normally don't need to change this.  

`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 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 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 in minutes, has to be greater than 2.  

`chunksize` : If an address book get loaded the first time (after L2CPBG start), 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" or similar, you need to lower this value. Default to 200. This option was added in L2CPBG version 0.8.1.

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

`tel` : CardDAV attribute which contain the phone numbers. Normally (and by default) 'TEL'.

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

`int` : International area code (1 = North America, ..., 44 = United Kingdom, 49 = Germany, ...) of your location.  

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

`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 prefix.  

`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.  

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

#### \[log\] = Screen & file logging

`conslevel` : Console log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to verbose.  

`filelevel` : File log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to info

The log levels are organized as follows:

`silly` : 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!  

`verbose` : Logs everything which might be interesting during use. Not only results, also when something get started, detailed results and such things.  

`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.

`filename` : Log messages to this file. Might contain a '%DATE%' placeholder which get replaced by the current date in 'YYYYMMDD' format. Defaults to empty = no log file.  

`filemaxsize` : Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number. Defaults to 10m.  

`filedatepattern` : A string representing the date format to be used for rotating (and the %DATE% placeholder. The meta characters used in this string will dictate the frequency of the file rotation. For example, if your filedatepattern is simply 'HH' you will end up with 24 log files that are picked up and appended to every day. Defaults to YYYYMMDD.  

`filemaxarchive` : Maximum number of archived logs to keep. This can be a number (\>1) of files or number of days. If using days, add 'd' as the suffix. Defaults to 10.  

`fileziparchive` : Boolean (true|false) to define whether or not to gzip archived log files. Defaults to true.

#### \[db\] = Internal database

`filename` : Filename where to store the internal database. Defaults to './l2cpbg-db.json'.

#### \[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.  

This 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 may define the following optional settings:

`types` : Regular expression of 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 the 'config.sample' 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 <span style="color: #d97a3a;">Server Address</span> point to the machine where this gateway lives, as well as <span style="color: #d97a3a;">Serverport</span>, <span style="color: #d97a3a;">BaseDN</span>, <span style="color: #d97a3a;">Common User Name</span> and <span style="color: #d97a3a;">Common Password</span> 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 <span style="color: #d97a3a;">Server Address</span> point to the machine where this gateway lives, as well as <span style="color: #d97a3a;">Port</span>, <span style="color: #d97a3a;">Base</span>, <span style="color: #d97a3a;">User Name</span> and <span style="color: #d97a3a;">Password</span> 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=*%*))

```

as 'LDAP name filter' did the trick for working name searches.

## Compatibility

This early version is currently only 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

  - 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

      - [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 <span style="color: #f00;">it should not be used in an untrusted network!</span>

  - 'Basic Authentication' over 'HTTPS' will work (for sure), but not with self signed certificates

## To-Do

I already have a couple of To-Do's on my list. Following a (priority ordered) list. Feel free to drop me your wishes [[#support]].

1.  Persistent DB storage

2.  Daemonize (run in background/as service)

## 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.