An LDAP to CardDav (1 way read) Phone Book Gateway.
Most modern (business) voice phones have the capability to do comfortable LDAP directory look-up like:
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, Synology Contacts, …).
This is, where this Gateway might make your live easier.
If this program (daemon/service) get started on some kind of hardware (Windows, macOS, Linux, Raspberry or the like), it will do the following:
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):
It will write to a small local database directory (defaults to ‘os.TempDir()/l2cpbg.db’).
At the moment there’s no “Admin GUI”. But for miminimal infos like
“uptime”, “license”, “number of search requests”, “number of sent result
records”, as well as immediate CardDAV-Server sync trigger, you might
send the l2cpbg process a SIGHUP
signal and check the logs
afterwards.
You might be also interested in the output of
l2cpbg --help
.
Version | max. phones 1 | Version blaming in Phone Display | max. LDAP requests/h | max. phonebook entries 2 | Gold features 3 | Price/€ 4 |
---|---|---|---|---|---|---|
Free | 2 | ✓ | 12 | 100 | ✗ | 0,00 |
Max3 | 3 | ✗ | unlimited | 500 | ✗ | 29,00 |
Max5 | 5 | ✗ | unlimited | 1000 | ✗ | 49,00 |
Max10 | 10 | ✗ | unlimited | 2000 | ✗ | 79,00 |
Pro10 | 10 | ✗ | unlimited | unlimited | ✓ | 149,00 |
Pro50 | 50 | ✗ | unlimited | unlimited | ✓ | 299,00 |
Enterprise | unlimited | ✗ | unlimited | unlimited | ✓ | 499,00 |
Before deciding to buy a license, please ensure that L2CPBG work as expected with all your phones and your CardDAV server. If you can’t test it because of a free limitations, or any other reason, don’t hesitate to ask for a 60 day evaluation license. Simply drop me a mail to projects@shbe.net with your real name.
dpkg -i l2cpbg_<version>_<architecture>.deb
to install the package.
/etc/l2cpbg.conf
.[dav]
![ldap]
, [ldap.bind]
,
[dav]
as well as [location]
sections (in
/etc/l2cpbg.conf) to your need.systemctrl restart l2cpbg
and check startup by systemctrl status l2cpbg
.journalctl -u l2cpbg
.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.
sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /usr/local/bin/ l2cpbg
sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /etc/ l2cpbg.conf
[ldap]
, [ldap.bind]
,
[dav]
as well as [location]
to your need.l2cpbg
and check
terminal output for any issues. <Ctrl-c>, edit config and start
l2cpbg
till terminal output is okay.sudo l2cpbg --service=install
. You should see a single “…
‘install’ succeed” message.sudo systemctrl start|stop|restart l2cpbg
. When booting
next, L2CPBG should get started automatically and log output to systemd
journal.journalctl -u l2cpbg
.journalctl -fu l2cpbg
.Adapt your phone(s) to point their “LDAP Directory” lookup requests to l2cpbg with the settings you defined in /etc/l2cpbg.conf.
Uninstalling the service/daemon is simply done by
sudo l2cpbg --service=uninstall
sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /usr/local/bin/ l2cpbg
sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /etc/ l2cpbg.conf
[ldap]
, [ldap.bind]
,
[dav]
as well as [location]
to your need.l2cpbg
and check
terminal output for any issues. <Ctrl-c>, edit config and start
l2cpbg
till terminal output is okay.sudo l2cpbg --service=install
. You should see a single “…
‘install’ succeed” message.sudo service l2cpbg start|stop|restart
. When booting next
time, L2CPBG should get started automatically and log output get send to
/var/log/l2cpbg.err|log.Adapt your phone(s) to point their “LDAP Directory” lookup requests to l2cpbg with the settings you defined in /etc/l2cpbg.conf.
Uninstalling the service/daemon is simply done by
sudo l2cpbg --service=uninstall
If you already have l2cpbg versiom 0.9.2 installed, you need to
deactivate your old l2cpbg instance via
l2cpbg --service=stop
and
l2cpbg --service=uninstall
, before
installing the new version. After installing the new version, activate
it again (via l2cpbg --service=install
and
l2cpbg --service=start
)
The package (pkg) installer does the following:
/usr/local/etc/l2cpbg.conf
.After installation, initial startup would fail due to wrong/missing
settings in config section [dav]
!
open -a TextEdit /usr/local/etc/l2cpbg.conf
[ldap]
, [ldap.bind]
,
[dav]
as well as your [location]
sections to
your need. When done, don’t forget to save!l2cpbg
in Terminal, and
check terminal output for any issues. <Ctrl-c> (abort l2cpbg),
edit config and start l2cpbg
again, till terminal output is
okay.sudo l2cpbg --service=install
. You should see a single “…
‘install’ succeed” message.sudo l2cpbg --service=start|stop|restart
. When booting next
time, L2CPBG should get started automatically and log output is send to
/usr/local/var/log/l2cpbg.log.Adapt your phone(s) to point their “LDAP Directory” lookup requests to l2cpbg with the settings you defined in /usr/local/etc/l2cpbg.conf.
Uninstalling the service/daemon is simply done by
sudo l2cpbg --service=uninstall
Uninstalling the whole package is done by
sudo /opt/l2cpbg/uninstall.sh
C:\Program Files\LDAP2CardDAV-Gateway
. Take attention
that the 32-bit version should be installted (by convention) somewhere
under C:\Program Files (x86)
!C:\Program Files\LDAP2CardDAV-Gateway\l2cpbg.conf
within
Notepad, and adapt config section [ldap]
,
[ldap.bind]
, [dav]
as well as
[location]
to your need. When done, don’t forget to
save!cd C:\Program Files\LDAP2CardDAV-Gateway
, start it in
foreground by l2cpbg.exe
and check terminal output for any
issues. <Ctrl-c>, edit config and start l2cpbg.exe
till terminal output is okay.l2cpbg.exe --service=install
. You should see a single “…
‘install’ succeed” message.l2cpbg.exe --service=start|stop|restart
. After ’start’ed as
service, log entries can be viewed by Windows Event Viewer (eventvwr).
When booting next time, L2CPBG should get started automatically.Uninstalling the service/daemon is simply done by
l2cpbg.exe --service=uninstall
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"
#pass = "[AES256]encrypted-cloud-login-password" # Please see command line option '--encryptPassword'
[location]
int = 1 # Your international code. 1 = US, 49 = Germany, ...
area = 807 # Your local area code (without a leading 0)
maxarealength = 7
country = "EN"
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’.
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.
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. If you don’t like to store
your CardDAV-Server password in clear-text here, you’ve also the
possibility to use the AES-256 encrypted variant of the password here.
Please check l2cpbg’s command line option --encryptPassword
(see l2cpbg --help
). If you already stored the encrypted
password variant here, you can also check/validate it with command line
option --testDavPassword
.
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).
mergeas
: Optional multi CardDAV/account feature. Merge
the configured CardDAV server section as ou=<mergeas string> LDAP
organisation unit. With this config option you’ve the possibility to
merge multiple CardDAV server or accounts either into a single ‘merged’
LDAP addressbook, or in separate ones. However you like. When importing
them into separate ones, you’ve the possibility to choose them within
you phone via the BaseDN option. By this you’ve i.e. the possibility to
import a company wide phonebook, as well as a (or multiple) private
one(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.
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), …).
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 CardDAV or incoming number is
shorter or equal, it’s identified as a number within your local
area.
country
: Two-letter 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.
prettifyNoAreaInSameArea
: Strip local area code from
destination number when located in same area. Boolean true|false,
defaults to true.
prettifyRemoveSpaces
: Boolean (true|false) which will
remove all spaces from a prettified phone number. Defaults to false.
extdialprefix
: Optional external dial prefix for
getting an external line. Get prefixed before the phone number if
outgoing number length > maxintlength
level
: Log level. Might be one of “trace”, “debug”,
“info”, “warn”, “error” or “fatal”. 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! When started as Windows-Service,
‘trace’ messages doesn’t get send to windows event console.
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! When started as
Windows-Service, ‘debug’ messages doesn’t get send to windows event
console.
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.
fatal
: Game over.
directory
: An own directory where to store the internal
database. Defaults to ‘os.TempDir()/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 the default location. 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, manually need to made
owned by l2cpbg via
chown -R l2cpbg:l2cpbg /your/db/directory
! Otherwise the DB
process will fail on missing read/write permissions!
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
: Case insensitive regular expression (RE2
syntax) of including relevant CardDav types or Apple addressbook
label (Apple Adressbook extension: X-ABLabel).
etypes
: Case insensitive 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.
Here’s a configuration sample of a Gigaset N510 IP PRO: 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.
At first, you need to know that Mitel’s LDAP implementation is a little bit different than the one from the other phones. While the other phones always do a live request to the LDAP server when searching for a contact or phone number, Mitel does 36 initial “give me all contacts” for “sn=0, 1, …, a, b, …, z*” once it boot, or during configured schedule (but not more often than once a day?!).
So, once Mitel loaded all contacts, it handles all searches internally. Also reverse-lookup searches for incoming calls get handled internally. This in turn means, that most of L2CPBG’s number prettyfying might disturb i.e. Mitels reverse lookup logic. Because of this, you better should disable the relevant prettyfying via L2CPBG’s config entries:
[location]
prettifyNoAreaInSameArea = false
prettifyRemoveSpaces = true
This will result in more ugly phone numbers within the directory, but probably give better results for Mitel-internal reverse lookup searches.
Next:
Mitel’s LDAP directory configuration can’t be done within the Phone’s or Web GUI. Instead of, it need to be done within the provisioning file(s) startup.cfg, <model>.cfg and/or <MAC>.cfg (please check your Mitel documentation how to provision).
Following the required Mitel provisioning entries, based on L2CPBG’s default config. Don’t forget to adapt if you changed these within your L2CPBG’s config:
# General LDAP Settings:
ldap enabled: 1
ldap name: CardDAV
ldap server: cn=phone:your-password@<L2CPBG's IP>:1389
ldap base dn: dc=example, dc=com
ldap search scope: subtree
# Reverse Lookup:
# For best results, use num of local phone number digit + number of area code digits, but not higher than 9
# Example:
# You complete local phone number is: +49 8421 12345
# Your local phone number is 5 nums long + area code length is 4 = 9
directory digits match: 9
# LDAP Attribute definitions
# (required because they seem to have no defaults)
ldap cn attribute: cn
ldap first name attribute list: givenName
ldap last name attribute list: sn
ldap company attribute list: company
ldap job title attribute list: title
ldap business street attribute list: street
ldap business city attribute list: l
ldap business state attribute list: st
ldap business postal code attribute list: postalCode
ldap business country attribute list: c
ldap home street attribute list: homeStreet
ldap home city attribute list: homeCity
ldap home state attribute list: homeState
ldap home postal code attribute list: homePostalCode
ldap home country attribute list: homeCountry
ldap business phone 1 attribute list: telephoneNumber
ldap home phone 1 attribute list: homePhone
ldap mobile phone attribute list: mobile
ldap business fax attribute list: facsimileTelephoneNumber
ldap email 1 attribute list: mail
ldap email 2 attribute list: homeMail
Reboot your phone and when it seem to be ready, wait further 2 to 3 minutes till it start to request all LDAP Addresses from L2CPBG’s LDAP Server (see L2CPBG’s log, journal or event messaages).
Go to the phone’s web GUI and define a ‘Directory’ key (Left menue: Operation / Softkeys and XML)
Another configuration sample of a Yealink SIP-T52S: 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.
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.
There might be special configuration requirements like different CardDAV Server/Phonebook combinations/permissions, or multi-locations requirements which can’t yet configured in L2CPBG.
For such special cases, you might start multiple L2CPBG instances. Each with his own configuration or even with the more comfortable merge/overlay configuration loading.
Imagine: You already have a standard instance running, like described within the Installation section. But now you’ve a special requirement like a office branch (which has access through your office VPN to your L2CPBG server) for which you need other [location] settings.
--instance-suffix
functionality might solve this for
you!
Do the following to configure and install a new instance:
l2cpbg.exe --instance-suffix=foo --service=start|stop|restart
like during normal install (except the additional parameter
–instance-suffix=foo)When dealing with the configuration of multi-instances, you will
heavily benefit from L2CPBG’s possibility to do merge/overlay config
loading, which is not more than loading each subsequent config on top of
the previous one. By this you’ll have i.e. your main configuration in
l2cpbg.conf whereas your l2cpbg-foo.conf contains only the two or three
config changes you’re interested in. Then, by adding
--config=<your config directory>/l2cpbg.conf,<your config directory>/l2cpbg-foo.conf
as l2cpbg command option, it’s done.
L2CPBG was tested with:
For getting help or discussing l2cpbg, please browse the L2CPBG Forum or check/open the Tickets area.