Project

General

Profile

Readme 080 » History » Version 3

Jörg Ebeling, 07/24/2020 12:56 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 comfortable LDAP directory look-up like:
8
9
  - Directory search by alphabet letters
10
  - Reverse lookup for inbound calls
11
  - Reverse lookup by entering parts or the phone number
12
13
Unfortunately, most of the 'smaller' companies (i guess companies beyond 100 employee) don't have an 'enterprise' LDAP directory, much less than private persons.
14
15
Most of such companies do have something like a cloud address book, often based on WebDAV / CardDAV (i.e. Nextcloud, Ownlcoud, ...).
16
17
This is, where this Gateway might make your live easier (hopefully).
18
19
If this program get started on some kind of hardware (Windows, Mac, Linux, ???), it will do the following:
20
21 2 Jörg Ebeling
1.  Query your CardDAV (Nextcloud, Owncloud, ...) Server for relevant entries, and cache them to a small local database
22 1 Jörg Ebeling
2.  Wait and answer for LDAP requests from your voice phone(s)
23
24
## Features
25
26
  - 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).
27
  - Reverse lookup inbound calls and display matching contact informations on the phone.
28
  - Work with human formatted (non- E.164) CardDAV entered phone numbers like: '040-123456' or '001 807 1234567' as well as '+49 (0)40 1234567-8'.
29
  - Support of internal phone numbers.
30
31
## Usage
32
33
You need some kind of 24/7 machine where this gateway live. Windows, Linux, Mac, (ARMx might come later if someone is interested).
34
35
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'.
36
37
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.
38
39
It will look for a configuration file in the following places (in the given order):
40
41
1.  ./.l2cpbgrc (or in it's parents)
42
2.  $HOME/.l2cpbgrc
43
3.  $HOME/.config/l2cpbg
44
4.  /etc/l2cpbgrc
45
5.  and some more uncommon places
46
47
It will write to a small local database (defaults to './l2cpbg-db.json').
48
49
## Configfile syntax
50
51
The config file syntax is 'ini' based. Following a quick minimal sample:
52
53
```
54
; Comments get started with a semicolon
55
;
56
; The Gateway will act/listen as LDAP Server with the following settings
57
;
58
[ldap]
59
  host      = 0.0.0.0
60
  ;port      = 1389
61
  base      = dc=example, dc=com
62
63
[ldap.bind]
64
  dn   = cn=pbx
65
  pass = your-password
66
67
[dav]
68
  server       = https://cloudserver.example.com/remote.php/dav
69
  user         = cloud-login-name
70
  pass         = cloud-login-password
71
  ;addressbooks = regular-expression-of-lookup-adressbook
72
  syncinterval = 5      ; Minutes
73
74
;[dav.map]
75
;  tel = TEL
76
77
[location]
78
  int           = 1
79
  area          = 807
80
  maxarealength = 7
81
  language      = en
82
  ;maxintlength = 3
83
  ;extdialprefix = 0,   ; External dial prefix if called number > maxintlength
84
85
[log]
86
  conslevel    = verbose   ; Console log level. Might be one of silly, debug, verbose, info, warn or error
87
  ;filename     = ./l2cpbg.log
88
  ;filelevel    = info      ; File log level. Might be one of silly, debug, verbose, info, warn or error
89
```
90
91
### Config file description
92
93
#### \[ldap\] = LDAP Server settings
94
95
`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.  
96
`port` : Port to listen for LDAP requests. Defaults to port 1389. You normally don't need to change this.  
97
`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'.
98
99
#### \[ldap.bind\] = LDAP auth settings
100
101
`dn` : Distinguish name. Name, how the phone has to log into/authorize to the gateway.  
102
`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.
103
104
#### \[dav\] = WebDav/CardDav server settings
105
106
`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!  
107
`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.  
108
`pass` : Related user password.  
109
`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).
110
111
#### \[dav.map\] = CardDav mapping
112
113
`tel` : CardDAV attribute which contain the phone numbers. Normally (and by default) 'TEL'.
114
115
#### \[location\] = Local area settings
116
117
`int` : International area code (1 = North America, ..., 44 = United Kingdom, 49 = Germany, ...) of your location.  
118
`area` : Local area code without leading 0 (20 = London (UK), 40 = Hamburg (DE), ...).  
119
`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.  
120
`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1\_alpha-2) country code (i.e. US, GB, DE, ...).  
121
`maxintlength` : Maximum length of internal phone numbers. These numbers don't get harmonized or E.164 converted.  
122
`extdialprefix` : External dial prefix for getting an external line. Get prefixed before the phone number if target number length \> `maxintlength`
123
124
#### \[log\] = Screen & file logging
125
126
`conslevel` : Console log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to verbose.  
127
`filename` : Log messages to this file. Might contain '%DATE%' with will be replaced by YYYYMMDD. Defaults to empty = no log file.  
128
`filelevel` : File log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to info
129
130
The log levels are organized as follows:
131
132
`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!  
133
`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!  
134
`verbose` : Logs everything which might be interesting during use. Not only results, also when something get started, detailed results and such things.  
135
`info` : This is the most usual log level. Logs only stuff which is relevant.  
136
`warn` : Logs stuff which doesn't behave as expected. Not critical (generic functionality should be okay) but should be noticed/checked.  
137
`error` : Something essential/critical happened. Functionality is limited or aborted at all.
138
139
#### \[db\] = Internal database
140
141
`filename` : Filename where to store the internal database. Defaults to './l2cpbg-db.json'.
142
143
#### \[ldap.map...\] = LDAP/CardDav mapping
144
145
Every LDAP attribute which is used within a phone(s) filter or response, need to have a corresponding CardDav mapping.  
146
This get done as follows:  
147
First you need to define a separate block for the LDAP attribute in the following syntax:
148
149
```
150
[ldap.map.<ldap attribute name (case sensitive)>]
151
```
152
153
  
154
Within such a LDAP mapping block you have to define:
155
156
`dav` : Corresponding CardDav field/attribute name.
157
158
and may define the following optional settings:
159
160
`types` : Regular expression of relevant CardDav types.
161
162
`index` : Zero based index in the case of a multi-value CardDav field.
163
164
For an overview of the predefined/default LDAP/CardDav mappings, take a look into the 'config.sample' file.
165
166
## Phone configuration
167
168
### Gigaset
169
170
Here's a configuration sample of a Gigaset N510 IP PRO:  
171
![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")  
172
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.
173
174
### Yealink
175
176
Another configuration sample of a Yealink SIP-T52S:  
177
![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")  
178
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.
179
180 3 Jörg Ebeling
### Snom
181
182
The LDAP configuration of Snom phones look similar to the ones of Gigaset or Yealink.  
183
But a user reported that entering
184
185
```
186
(|(cn=*%*)(sn=*%*)(givenName=*%*)(company=*%*))
187
```
188
189
as 'LDAP name filter' did the trick for working name searches.
190
191 1 Jörg Ebeling
## Compatibility
192
193
This early version is currently only tested with:
194
195
  - CardDAV Server:
196
      - [Nextcloud](https://nextcloud.com/) version 13, 15 & 16
197
  - Phone Extensions:
198
      - [Gigaset](https://www.gigasetpro.com/) N510 IP PRO
199
      - [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W
200
  - Gateway Host OS:
201
      - [Debian](https://www.debian.org/) Stretch 9.x, Buster 10.x
202
      - [macOS](https://www.apple.com/macos/) ™ Sierra 10.12.6
203
204
## Limitations and Known Issues
205
206
There are already some known issues!!! Not sure which will get fixed, might depend on how much people are interested in.
207
208
  - 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>
209
  - The CardDAV Server [HTTP-Authentication](https://de.wikipedia.org/wiki/HTTP-Authentifizierung) is currently restricted to 'Basic Authentication'. No 'Digest Access Authentication' like required i.e. for [Daylite](https://www.marketcircle.com).
210
  - 'Basic Authentication' over 'HTTPS' will work (for sure), but without detailed certificate checking.
211
  - ~~In this first 0.7.x version, there's no cacheing layer anymore (as in the previous versions). This might result in LDAP timeouts if your CardDav server is to slow or laggy. If you get hit by this limitation, drop me a short note, so that I'll give it priority.~~
212
213
## To-Do
214
215
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]].
216
217
1.  Implement Apple's addressbook extension for Apple specific telephone number X-Attributes
218
2.  ~~Implement a new cacheing layer for quicker LDAP lookups~~
219
3.  Daemonize (run in background/as service)
220
221
## Support & getting help
222
223
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.
Go to top