Project

General

Profile

Readme 093 » History » Version 1

Jörg Ebeling, 08/14/2021 09:52 PM

1 1 Jörg Ebeling
# LDAP-2-CardDAV Phone Book Gateway (l2cpbg)
2
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.  Synchronize your CardDAV Server, to a small local database cache
27
2.  Wait and answer for LDAP requests from your voice phone(s)
28
29
## Features
30
31
-   Query your CardDAV address book(s) by entering the alphabetic
32
    letters (or parts of the telephone number) in your (LDAP capable)
33
    phone (and dial one of the matching numbers).
34
-   Reverse lookup inbound calls and display matching contact
35
    informations on the phone.
36
-   Work with local formatted (non- E.164) CardDAV entered phone numbers
37
    like: '040-123456' or '001 807 1234567' as well as '+49 (0)40
38
    1234567-8' = no need to format the phone numbers of your CardDAV contacts in a special notation.
39
-   Supports internal (extension) phone numbers.
40
-   Support dial prefix for external line.
41
-   Support short internal extension numbers.
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
By default it will look for a configuration file in the following places (in the
49
given order):
50
51
1.  ./l2cpbg.conf
52
2.  /etc/l2cpbg.conf
53
3.  /usr/local/etc/l2cpbg.conf
54
4.  \<exec directory\>/l2cpbg.conf
55
56
It will write to a small local database directory (defaults to 'os.TempDir()/l2cpbg.db').
57
58
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.
59
60
## Installation
61
62
### Linux Debian ".deb" packages
63
64
`dpkg -i l2cpbg_<version>_<architecture>.deb` to install the package.
65
66
- A sample configuration get places at `/etc/l2cpbg.conf`.  
67
- Initial startup will fail due to wrong/missing settings in config section `[dav]`!  
68
- Adapt at least `[ldap]`, `[ldap.bind]`, `[dav]` as well as `[location]` sections (in /etc/l2cpbg.conf) to your need.
69
- Once done, restart l2cpbg by `systemctrl restart l2cpbg` and check startup by `systemctrl status l2cpbg`.  
70
- The full log can be read by `journalctl -u l2cpbg`.  
71
- To watch the actual/live logging, use `journalctl -fu l2cpbg`.
72
73
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.
74
75
### Linux binary "tar.gz" packages ("systemd" Systems)
76
77
1. Extract binary i.e. to /usr/local/bin: `sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /usr/local/bin/ l2cpbg`
78
2. Extract config file, i.e. to /etc: `sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /etc/ l2cpbg.conf`
79
3. Adapt config section `[ldap]`, `[ldap.bind]`, `[dav]` as well as `[location]` to your need.
80
4. Do a first foreground start via `l2cpbg` and check terminal output for any issues. \<Ctrl-c\>, edit config and start `l2cpbg` till terminal output is okay.
81
5. If terminal output is okay and everything work as expected. \<Ctrl-c\> to stop forground process.
82
6. Install L2CPBG as service/daemon via `sudo l2cpbg --service=install`. You should see a single "... 'install' succeed" message.
83
7. Now that L2CPBG got installed as a service/daemon you can use `sudo systemctrl start|stop|restart l2cpbg`. When booting next, L2CPBG should get started automatically and log output to systemd journal.
84
8. The full log can be read by `journalctl -u l2cpbg`.  
85
9. To watch the actual/live logging, use `journalctl -fu l2cpbg`.
86
87
Adapt your phone(s) to point their "LDAP Directory" lookup requests to l2cpbg with the settings you defined in /etc/l2cpbg.conf.
88
89
Uninstalling the service/daemon is simply done by `sudo l2cpbg --service=uninstall`
90
91
### Linux binary "tar.gz" packages ("SysV" Systems)
92
93
1. Extract binary i.e. to /usr/local/bin: `sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /usr/local/bin/ l2cpbg`
94
2. Extract config file, i.e. to /etc: `sudo tar xvf l2cpbg_0.9.2_linux-amd64.tgz -C /etc/ l2cpbg.conf`
95
3. Adapt config section `[ldap]`, `[ldap.bind]`, `[dav]` as well as `[location]` to your need.
96
4. Do a first foreground start via `l2cpbg` and check terminal output for any issues. \<Ctrl-c\>, edit config and start `l2cpbg` till terminal output is okay.
97
5. If terminal output is okay and everything work as expected. \<Ctrl-c\> to stop forground process.
98
6. Install L2CPBG as service/daemon via `sudo l2cpbg --service=install`. You should see a single "... 'install' succeed" message.
99
7. Now that L2CPBG got installed as a service/daemon you can use `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.
100
101
Adapt your phone(s) to point their "LDAP Directory" lookup requests to l2cpbg with the settings you defined in /etc/l2cpbg.conf.
102
103
Uninstalling the service/daemon is simply done by `sudo l2cpbg --service=uninstall`
104
105
### MacOS "pkg" package ("launchd" System)
106
107
The package (pkg) installer does the following:
108
109
- Extract the L2CPBG package to '/opt/l2cpbg'.
110
- Place a l2cpbg command symlink into '/usr/local/bin' (which is in PATH), so that you're able to call the gateway binary 'l2cpbg' independent of your working directory.
111
- A sample l2cpbg configuration file get places in `/usr/local/etc/l2cpbg.conf`.
112
113
After installation, initial startup would fail due to wrong/missing settings in config section `[dav]`!
114
115
1. Edit config by opening '/usr/local/etc/l2cpbg.conf' i.e. with TextEdit `open -a TextEdit /usr/local/etc/l2cpbg.conf`
116
2. Adapt at least `[ldap]`, `[ldap.bind]`, `[dav]` as well as your `[location]` sections to your need.  When done, don't forget to save!
117
3. Do a first foreground start via `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.
118
4. If terminal output is okay and everything work as expected. \<Ctrl-c\> (abort l2cpbg) to stop forground process.
119
5. Install L2CPBG as service/daemon via `sudo l2cpbg --service=install`. You should see a single "... 'install' succeed" message.
120
6. Now that L2CPBG got installed as a service/daemon you can use `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.
121
122
Adapt your phone(s) to point their "LDAP Directory" lookup requests to l2cpbg with the settings you defined in /usr/local/etc/l2cpbg.conf.
123
124
Uninstalling the service/daemon is simply done by `sudo l2cpbg --service=uninstall`
125
126
Uninstalling the whole package is done by `sudo /opt/l2cpbg/uninstall.sh`
127
128
### Windows binary "zip" packages
129
130
1. Extract content of zip package to your preferred location, i.e. `C:\Program Files\LDAP2CardDAV-Gateway`. Take attention that the 32-bit version should be installted (by convention) somewhere under `C:\Program Files (x86)`!
131
2. Run "notepad" as Administrator, open `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!
132
3. Now it's time to try a first start of the Gateway. Run a "Command" shell as Administrator and change to the installation directory, i.e. `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.
133
4. If terminal output is okay and everything work as expected. \<Ctrl-c\> to stop forground process.
134
5. Install L2CPBG as service/daemon via `l2cpbg.exe --service=install`. You should see a single "... 'install' succeed" message.
135
7. Now that L2CPBG got installed as a service you can use `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.
136
137
Uninstalling the service/daemon is simply done by `l2cpbg.exe --service=uninstall`
138
139
## Configfile syntax
140
141
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!
142
143
Following a quick minimal sample:
144
```
145
# Comments get started with a hash character
146
147
#
148
# The Gateway will act as LDAP Server, listening
149
# for requests from your phone(s).
150
#
151
[ldap]
152
  host      = "0.0.0.0"
153
  #port     = 1389
154
  base      = "dc=example, dc=com"
155
156
[ldap.bind]
157
  dn   = "cn=pbx"
158
  pass = "your-password"
159
160
#
161
# Your CardDAV server where this Gateway get the contacts from
162
#
163
[dav]
164
  server       = "https://cloudserver.example.com/remote.php/dav"
165
  user         = "cloud-login-name"
166
  pass         = "cloud-login-password"
167
168
[location]
169
  int           = 1     # Your international code. 1 = US, 49 = Germany, ...
170
  area          = 807   # Your local area code (without a leading 0)
171
  maxarealength = 7
172
  country       = "EN"
173
```
174
175
### Config file description (by section)
176
177
#### \[ldap\] = LDAP Server settings
178
179
`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.
180
181
`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.
182
183
`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'.
184
185
#### \[ldap.bind\] = LDAP bind/auth settings
186
187
`dn` : Distinguish name. Name, how the phone has to log into/authorize
188
to the gateway.
189
190
`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.
191
192
#### \[dav\] = WebDav/CardDav server settings
193
194
`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!
195
196
`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.
197
198
`pass` : Related user password.
199
200
`addressbooks` : Optional regular expression string of matchable addressbook(s)
201
used for phone book lookups. If unsure, enter something. l2cpbg will log
202
all found address books of the logged in CardDav user during startup and
203
log them as 'Non-matching' or 'Matching' address book(s).
204
205
`syncinterval` : Interval of CardDav sync checks. Given as string with suffix 'm' for minutes, or 'h' as hours. Has to be greater than "2m".
206
207
`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.
208
209
`insecurecert` controls whether a client verifies the server's certificate
210
chain and host name. If insecurecert is true, crypto/tls accepts any
211
certificate presented by the server and any host name in that certificate.
212
In this mode, TLS is susceptible to machine-in-the-middle attacks unless
213
custom verification is used. This should be used only for testing or in
214
trusted environments. Defaults to *false*. This option was added in L2CPBG version 0.9.1.
215
216
#### \[dav.map\] = CardDav mapping
217
218
`tel` : CardDAV attribute which contain phone numbers. Normally (and
219
by default) 'TEL'. Don't change this, except your really know what you're doing.
220
221
#### \[location\] = Local area settings
222
223
`int` : International area code (1 = North America, ..., 44 = United
224
Kingdom, 49 = Germany, ...) of your location.
225
226
~~`intPrefix` : Dial prefix for international calls. Mostly "00". Defaults to "00".
227
ATTENTION: Has to be entered as string like "00".~~
228
229
`area` : Local area code without leading 0 (20 = London (UK), 40 =
230
Hamburg (DE), ...).
231
232
`areaPrefix` : Dial prefix for national calls. Mostly "0". Defaults to "0".
233
ATTENTION: Has to be entered as string like "0". 
234
235
`maxarealength` : Longest possible length of a telephone number within
236
your local area. If a CardDAV or incoming number is shorter or equal, it's
237
identified as a number within your local area.
238
239
`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (i.e. US, GB, DE, ...).
240
241
`maxintlength` : Maximum length of internal phone numbers. These numbers
242
don't get harmonized or E.164 converted.
243
244
`prettifyNums` : By default phone numbers loaded from CardDAV get prettified in two ways:
245
At first, if a CardDAV number is stored in international format, but you live in the same country, the international part get removed.
246
At second, the number get formatted in (spaced or braced) number groups as it's common in your country.
247
You can disable this prettifying by setting the value to false.
248
249
`extdialprefix` : Optional external dial prefix for getting an external line. Get prefixed before the phone number if outgoing number length \> `maxintlength`
250
251
#### [log] = Logging
252
253
`level` : Log level. Might be one of "trace", "debug", "info", "warn", "error" or "fatal". Defaults to "info".
254
255
The log levels are organized as follows:
256
257
`trace` : This is the most verbose log level. It logs simply everything.
258
Never use it in production environment as it might produce an awful amount of log entries!
259
When started as Windows-Service, 'trace' messages doesn't get send to windows event console.
260
261
`debug` : Logs a lot internal stuff, probably interesting when searching
262
a solution for an issue. Should not be used in production environment as
263
it produce also a lot log entries!
264
When started as Windows-Service, 'debug' messages doesn't get send to windows event console.
265
266
`info` : This is the most usual log level. Logs only stuff which is relevant.
267
268
`warn` : Logs stuff which doesn't behave as expected. Not critical (generic functionality should be okay) but should be noticed/checked.
269
270
`error` : Something essential/critical happened. Functionality is limited or aborted at all.
271
272
`fatal` : Game over.
273
274
#### [db] = Internal database
275
276
`directory` : An own directory where to store the internal database. Defaults to
277
'os.TempDir()/l2cpbg.db' which is not very useful on Linux based systems as it normally get cleaned after each reboot.
278
279
Choose yourself where to store the database.
280
If you've a small CardDAV server with <= 200 contacts, let the DB in the default location.
281
An initial sync of 200 contacts (after a reboot) will be quickly done.
282
Not much storage space is needed. An CardDAV server with approx. 4 thousand contacts, take about 10 MByte storage.
283
284
ATTENTION: If you use one of the .deb packages, the binary get started as user=l2cpbg.
285
Thus, the given directory, manually need to made owned by l2cpbg via
286
`chown -R l2cpbg:l2cpbg /your/db/directory`! Otherwise the DB process will fail on missing read/write permissions!
287
288
#### [ldap.map...] = LDAP/CardDav mapping
289
290
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:
291
292
First you need to define a separate block for the LDAP attribute in the following syntax: `[ldap.map.<ldap attribute name (case sensitive)>]`
293
Within such a LDAP mapping block you have to define:
294
295
`dav` : Corresponding CardDav field/attribute name.
296
297
and optional define the following settings:
298
299
`itypes` : Regular expression (RE2 syntax) of including relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).
300
301
`etypes` : Regular expression (RE2 syntax) of **excluding** relevant CardDav types or *Apple addressbook label* (Apple Adressbook extension: X-ABLabel).
302
303
`index` : Zero based index in the case of a multi-value CardDav field.
304
305
For an overview of the predefined/default LDAP/CardDav mappings, take a
306
look into 'l2cpbg.sample.conf' file.
307
308
## Phone configuration
309
310
### Gigaset
311
312
Here's a configuration sample of a Gigaset N510 IP PRO:
313
![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")
314
Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Serverport')
315
316
'BaseDN', 'Common User Name' and 'Common Password' get filled with the same values as defined in your L2CPG config file.
317
318
### Yealink
319
320
Another configuration sample of a Yealink SIP-T52S:
321
![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")
322
Take attention that 'Server Address' point to the machine where this gateway lives (as well as 'Port').
323
324
'Base', 'User Name' and 'Password' get filled with the same values as defined in your L2CPG config file.
325
326
### Snom
327
328
The LDAP configuration of Snom phones look similar to the ones of
329
Gigaset or Yealink.
330
But a user reported that entering `(|(cn=*%*)(sn=*%*)(givenName=*%*)(company=*%*))` within 'LDAP name filter' did the trick for working name searches.
331
332
## Special features
333
334
### Multi-Instances (currently Windows only, Pro license required)
335
336
There might be special configuration requirements like different CardDAV Server/Phonebook combinations/permissions, or multi-locations requirements which can't yet configured in L2CPBG.
337
338
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.
339
340
Imagine: You already have a standard instance running, like described within the [install](#Windows_binary) 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.
341
342
`--instance-suffix` functionality might solve this for you!
343
344
Do the following to configure and install a new instance:
345
346
1. We need to give the new instance some kind of meaningfull name. In the following we decide for 'foo'
347
2. Copy your l2cpbg.conf file (as described in [install](#Windows_binary)) to l2cpbg-foo.conf, and open it in notepad (or whichever editor your prefer
348
3. Change the [ldap] port to a free port. I.e. from 1389 to 1390
349
4. If you have configured a [db] directory, give the new instance a separate (and exclusive) db directoy. If you don't have a configured [db] directory entry, you can leave it as it is. By default the db get stored at OS.Tempdir()/l2cpbg-\<instance-suffix\>.db
350
5. Change the configuration stuff why you where interested in a separate instance.
351
6. Test your new configuration in foreground (the same way as you did during the normal instance installation see [install](#Windows_binary)
352
7. Once the configuration is good, you can call `l2cpbg.exe --instance-suffix=foo --service=start|stop|restart` like during normal install (except the additional parameter --instance-suffix=foo)
353
354
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. 
355
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.
356
357
## Compatibility
358
359
L2CPBG is tested with:
360
361
-   CardDAV Server:
362
    -   [Baïkal](https://sabre.io/baikal/) version 0.7.x
363
    -   [Daylite](https://www.marketcircle.com/)
364
    -   [Nextcloud](https://nextcloud.com/) version 13, 15, 16, 18 & 20
365
    -   [Synology Contacts](https://www.synology.com/dsm/packages/Contacts)
366
-   Desktop & Mobile Phones:
367
    -   [Gigaset](https://www.gigasetpro.com/) N510 IP PRO, 670 IP Pro
368
    -   [Grandstream](http://www.grandstream.com/) GXP2170
369
    -   [Snom](https://www.snom.com/) 300, D315, D335
370
    -   [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W
371
    -   [Fanvil](https://fanvil.com/) X3U
372
-   Gateway Host OS:
373
    -   [Debian](https://www.debian.org/) Stretch 9.x, Buster 10.x (running at amd64 as well as ARMv7)
374
    -   [Gentoo](https://www.gentoo.org) amd64
375
    -   [macOS](https://www.apple.com/macos/) ™ Sierra 10.12.6
376
    -   [Ubuntu](https://ubuntu.com/) 20.04 (Focal Fossa)
377
    -   [Windows](https://www.microsoft.com/windows) Server 2016, 10
378
379
## Limitations and Known Issues
380
381
-   The internal LDAP Server doesn't support LDAPS (encrypted LDAP
382
    communication) at the moment. Therefore 
383
    **it should not be used in an untrusted network!**
384
    If you're interested to run it in an untrusted network,
385
    please drop me a short note.
386
387
## Support & getting help
388
389
For getting help or discussing l2cpbg, please browse the [L2CPBG
390
Forum](https://projects.shbe.net/projects/l2cpbg/boards) or check/open
391
the [Tickets](https://projects.shbe.net/projects/l2cpbg/issues) area.
Go to top