Project

General

Profile

Readme 090 » History » Version 3

Jörg Ebeling, 03/22/2021 12:22 AM

1 2 Jörg Ebeling
# LDAP-2-CardDAV Phone Book Gateway (l2cpbg)
2 1 Jörg Ebeling
3
An LDAP to CardDav (1 way read) Phone Book Gateway.
4
5
## Use case
6
7
Most modern (business) voice phones have the capability to do
8
comfortable LDAP directory look-up like:
9
10
-   Directory search by alphabet letters
11
-   Reverse lookup for in- or out-bound calls
12
-   Reverse lookup by entering parts or the phone number
13
14
Unfortunately, most of the 'smaller' companies (i guess companies beyond
15
100 employee) don't have an 'enterprise' LDAP directory, much less than
16
private persons.
17
18
Most of such companies do have something like a cloud address book,
19
often based on WebDAV / CardDAV (i.e. Nextcloud, Ownlcoud, Baïkal,
20
Daylite, ...).
21
22
This is, where this Gateway might make your live easier.
23
24
If this program get started on some kind of hardware (Windows, macOS or Linux), it will do the following:
25
26
1.  Query your CardDAV Server for relevant entries, and cache them to a
27
    small local database
28
2.  Wait and answer for LDAP requests from your voice phone(s)
29
30
## Features
31
32
-   Query your CardDAV address book(s) by entering the alphabetic
33
    letters (or parts of the telephone number) in your (LDAP capable)
34
    phone (and dial one of the matching numbers).
35
-   Reverse lookup inbound calls and display matching contact
36
    informations on the phone.
37
-   Work with local formatted (non- E.164) CardDAV entered phone numbers
38
    like: '040-123456' or '001 807 1234567' as well as '+49 (0)40
39
    1234567-8' = no need to enter your phone numbers within your CardDAV server in a special notation.
40
-   Supports internal (extension) phone numbers.
41
-   Support dial prefix for external line.
42
43
## Usage
44
45
You need some kind of 24/7 machine where this gateway live. Windows PC,
46
Linux, macOS, Raspberry or the like.
47
48
In this early 'beta' version, it runs in foreground. So, if you require
49
to log off out of your machine, run it i.e. via 'screen'.
50
51
No installation required. Only a simple executable an a configuration file. Place it wherever you like, but I advice to start it as normal (non-root/non-administrative) user.
52
53
By default it will look for a configuration file in the following places (in the
54
given order):
55
56
1.  ./l2cpbg.conf
57
2.  /etc/l2cpbg.conf
58
59
It will write to a small local database directory (defaults to '/tmp/l2cpbg.db').
60
61
## ~~Hotkeys~~
62
63
~~There are some hotkeys available on the console.~~
64
65
~~Hotkey  Description~~
66
67 3 Jörg Ebeling
## Configfile syntax
68 1 Jörg Ebeling
69
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!
70
71
Following a quick minimal sample:
72
```
73
# Comments get started with a hash character
74
75
#
76
# The Gateway will act as LDAP Server, listening
77
# for requests from your phone(s).
78
#
79
[ldap]
80
  host      = "0.0.0.0"
81
  #port     = 1389
82
  base      = "dc=example, dc=com"
83
84
[ldap.bind]
85
  dn   = "cn=pbx"
86
  pass = "your-password"
87
88
#
89
# Your CardDAV server where this Gateway get the contacts from
90
#
91
[dav]
92
  server       = "https://cloudserver.example.com/remote.php/dav"
93
  user         = "cloud-login-name"
94
  pass         = "cloud-login-password"
95
96
[location]
97
  int           = 1     # Your international code. 1 = US, 49 = Germany, ...
98
  area          = 807   # Your local area code (without a leading 0)
99
  maxarealength = 7
100
  country       = "EN"
101
```
102
103
### Config file description (by section)
104
105
#### \[ldap\] = LDAP Server settings
106
107
`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.
108
109
`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.
110
111
`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'.
112
113
#### \[ldap.bind\] = LDAP bind/auth settings
114
115
`dn` : Distinguish name. Name, how the phone has to log into/authorize
116
to the gateway.
117
118
`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.
119
120
#### \[dav\] = WebDav/CardDav server settings
121
122
`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!
123
124
`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.
125
126
`pass` : Related user password.
127
128
`addressbooks` : Optional regular expression string of matchable addressbook(s)
129
used for phone book lookups. If unsure, enter something. l2cpbg will log
130
all found address books of the logged in CardDav user during startup and
131
log them as 'Non-matching' or 'Matching' address book(s).
132
133
`syncinterval` : Interval of CardDav sync checks. Given as string with suffix 'm' for minutes, or 'h' as hours. Has to be greater than "2m".
134
135
`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.
136
137
#### \[dav.map\] = CardDav mapping
138
139
`tel` : CardDAV attribute which contain phone numbers. Normally (and
140
by default) 'TEL'. Don't change this, except your really know what you're doing.
141
142
#### \[location\] = Local area settings
143
144
`int` : International area code (1 = North America, ..., 44 = United
145
Kingdom, 49 = Germany, ...) of your location.
146
147
`area` : Local area code without leading 0 (20 = London (UK), 40 =
148
Hamburg (DE), ...).
149
150
`maxarealength` : Longest possible length of a telephone number within
151
your local area. If a found or received number is shorter or equal, it's
152
identified as a number without local area prefix.
153
154
`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (i.e. US, GB, DE, ...).
155
156
`maxintlength` : Maximum length of internal phone numbers. These numbers
157
don't get harmonized or E.164 converted.
158
159
`extdialprefix` : Optional external dial prefix for getting an external line. Get prefixed before the phone number if outgoing number length \> `maxintlength`
160
161
#### \[log\] = Logging
162
163
`level` : Log level. Might be one of "trace", "debug", "info", "warn", "error" or "panic". Defaults to "info".
164
165
The log levels are organized as follows:
166
167
`trace` : This is the most verbose log level. It logs simply everything.
168
Never use it in production environment as it might produce an awful amount of log entries!
169
170
`debug` : Logs a lot internal stuff, probably interesting when searching
171
a solution for an issue. Should not be used in production environment as
172
it produce also a lot log entries!
173
174
`info` : This is the most usual log level. Logs only stuff which is relevant.
175
176
`warn` : Logs stuff which doesn't behave as expected. Not critical (generic functionality should be okay) but should be noticed/checked.
177
178
`error` : Something essential/critical happened. Functionality is limited or aborted at all.
179
180
`panic` : Game over.
181
182
#### \[db\] = Internal database
183
184
`directory` : An own directory where to store the internal database. Defaults to
185
'/tmp/l2cpbg.db' which is not very usefull on Linux based systems as it normally get cleaned after each reboot. Choose yourself where to store the database. Not much storage space needed. An CardDAV server with approx. 4 thousand contacts, take about 10 MByte storage.
186
187
#### \[ldap.map...\] = LDAP/CardDav mapping
188
189
Every LDAP attribute which is used within a phone(s) filter or response,
190
need to have a corresponding CardDav mapping which get done as follows:
191
192
First you need to define a separate block for the LDAP attribute in the
193
following syntax: `[ldap.map.<ldap attribute name (case sensitive)>]`
194
Within such a LDAP mapping block you have to define:
195
196
`dav` : Corresponding CardDav field/attribute name.
197
198
and optional define the following settings:
199
200
`itypes` : Regular expression (RE2 syntax) of including relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).
201
202
`etypes` : Regular expression (RE2 syntax) of **excluding** relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).
203
204
`index` : Zero based index in the case of a multi-value CardDav field.
205
206
For an overview of the predefined/default LDAP/CardDav mappings, take a
207
look into 'l2cpbg.sample.conf' file.
208
209
## Phone configuration
210
211
### Gigaset
212
213
Here's a configuration sample of a Gigaset N510 IP PRO:
214
![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")
215
Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Serverport')
216
217
'BaseDN', 'Common User Name' and 'Common Password' get filled with the same values as defined in your L2CPG config file.
218
219
### Yealink
220
221
Another configuration sample of a Yealink SIP-T52S:
222
![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")
223
Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Port').
224
225
'Base', 'User Name' and 'Password' get filled with the same values as defined in your L2CPG config file.
226
227
### Snom
228
229
The LDAP configuration of Snom phones look similar to the ones of
230
Gigaset or Yealink.
231
But a user reported that entering `(|(cn=*%*)(sn=*%*)(givenName=*%*)(company=*%*))` within 'LDAP name filter' did the trick for working name searches.
232
233
## Compatibility
234
235
This version is tested with:
236
237
-   CardDAV Server:
238
    -   [Baïkal](https://sabre.io/baikal/) version 0.7.x
239
    -   [Daylite](https://www.marketcircle.com/)
240
    -   [Nextcloud](https://nextcloud.com/) version 13, 15, 16, 18 & 20
241
-   Phone Extensions:
242
    -   [Gigaset](https://www.gigasetpro.com/) N510 IP PRO, 670 IP Pro
243
    -   [Grandstream](http://www.grandstream.com/) GXP2170
244
    -   [Snom](https://www.snom.com/) 300, D315, D335
245
    -   [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W
246
-   Gateway Host OS:
247
    -   [Debian](https://www.debian.org/) Stretch 9.x, Buster 10.x (running at amd64 as well as ARMv7)
248
    -   [macOS](https://www.apple.com/macos/) ™ Sierra 10.12.6
249
    -   [Ubuntu](https://ubuntu.com/) 20.04 (Focal Fossa)
250
251
## Limitations and Known Issues
252
253
There are already some known issues!!! Not sure which will get fixed, might depend on how much people are interested in.
254
255
-   The internal LDAP Server doesn't support LDAPS (encrypted LDAP
256
    communication) at the moment. Therefore 
257
    **it should not be used in an untrusted network!**
258
-   'Basic Authentication' over 'HTTPS' will work (for sure), but probably not
259
    with self signed certificates
260
261
## Support & getting help
262
263
For getting help or discussing l2cpbg, please browse the [L2CPBG
264
Forum](https://projects.shbe.net/projects/l2cpbg/boards) or check/open
265
the [Tickets](https://projects.shbe.net/projects/l2cpbg/issues) area.
Go to top