Project

General

Profile

Readme 060 » History » Version 1

Jörg Ebeling, 04/10/2019 06:25 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
1.  Answer on LDAP requests from your voice phone(s)
22
2.  Ask your CardDAV (Nextcloud, Owncloud, ...) Server for the LDAP requested phone book entry
23
3.  Return the CardDAV query results, back as LDAP results to your phone.
24
25
## Features
26
27
  - 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).
28
  - Reverse lookup inbound calls and display matching contact informations on the phone.
29
  - 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'.
30
  - Reverse lookup of phone numbers, depend on a tiny caching layer and thus a (configurable) sync interval.
31
32
## Usage
33
34
You need some kind of 24/7 machine where this gateway live. Windows, Linux, Mac, (ARMx might come later).
35
36
In this current 'early' or 'beta' version, it runs in foreground. So, if you require to log off out of your machine, run it i.e. via 'screen'.
37
38
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.
39
40
It will look for a configuration file in the following places (in the given order):
41
42
1.  ./.l2cpbgrc (or in it's parents)
43
2.  $HOME/.l2cpbgrc
44
3.  $HOME/.config/l2cpbg
45
4.  /etc/l2cpbgrc
46
5.  and some more uncommon places
47
48
## Config file syntax
49
50
The config file syntax is 'ini' based. Following a quick sample:
51
52
``` ini
53
; Comments get started with a semicolon
54
;
55
; The Gateway will act/listen as LDAP Server with the following settings
56
[ldap]
57
  host      = 0.0.0.0
58
  ;port      = 1389
59
  base      = dc=example, dc=com
60
61
[ldap.bind]
62
  dn   = cn=pbx
63
  pass = your-password
64
65
[dav]
66
  server       = https://cloudserver.example.com/remote.php/dav
67
  user         = cloud-login-name
68
  pass         = cloud-login-password
69
  ;addressbooks = regular-expression-of-lookup-adressbook
70
  syncinterval = 5      ; Minutes
71
72
;[dav.map]
73
;  tel = TEL
74
;  fn  = FN
75
76
[location]
77
  int           = 1
78
  area          = 807
79
  maxarealength = 7
80
  language      = en
81
82
[log]
83
  conslevel    = verbose   ; Console log level. Might be one of silly, debug, verbose, info, warn or error
84
  ;filename     = ./l2cpbg.log
85
  ;filelevel    = info      ; File log level. Might be one of silly, debug, verbose, info, warn or error
86
```
87
88
### Config file description
89
90
#### \[ldap\] part
91
92
`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.  
93
`port` : Port to listen for LDAP requests. Defaults to port 1389. You normally don't need to change this.  
94
`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'.
95
96
#### \[ldap.bind\] part
97
98
`dn` : Distinguish name. Name, how the phone has to log into/authorize to the gateway.  
99
`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.
100
101
#### \[dav\] part
102
103
`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!  
104
`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.  
105
`pass` : Related user password.  
106
`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 user during startup and log them as 'Non-matching' or 'Matching' address book.
107
108
#### \[dav.map\] part
109
110
`tel` : CardDAV attribute which contain the phone numbers. Normally (and by default) 'TEL'.  
111
`fn` : CardDAV's 'Full Name' attribute. Normally (and default) 'FN'.
112
113
#### \[location\] part
114
115
`int` : International area code (1 = North America, ..., 44 = United Kingdom, 49 = Germany, ...) of your location.  
116
`area` : Local area code without leading 0 (20 = London (UK), 40 = Hamburg (DE), ...).  
117
`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.  
118
`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1\_alpha-2) country code (i.e. US, GB, DE, ...).
119
120
#### \[log\] part
121
122
`conslevel` : Console log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to verbose.  
123
`filename` : Log messages to this file. Might contain '%DATE%' with will be replaced by YYYYMMDD. Defaults to empty = no log file.  
124
`filelevel` : File log level. Might be one of silly, debug, verbose, info, warn or error. Defaults to info
125
126
The log levels are organized as follows:
127
128
`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!  
129
`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!  
130
`verbose` : Logs everything which might be interesting during use. Not only results, also when something get started, detailed results and such things.  
131
`info` : This is the most usual log level. Logs only stuff which is relevant.  
132
`warn` : Logs stuff which doesn't behave as expected. Not critical (generic functionality should be okay) but should be noticed/checked.  
133
`error` : Something essential/critical happened. Functionality is limited or aborted at all.
134
135
## Phone configuration
136
137
Here's a sample of a Yealink SIP-T52S configuration:  
138
![Yealink SIP-T52S settings sample](https://projects.shbe.net/attachments/download/3/config_yealink-t52s_fw7084_v050_en.jpg "Yealink SIP-T52S settings sample")  
139
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.
140
141
## Compatibility
142
143
This early version is currently only tested (working) with:
144
145
  - CardDAV Server:
146
      - [Nextcloud](https://nextcloud.com/) version 13.0.8
147
  - Phone Extensions:
148
      - [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W
149
  - Gateway Host OS:
150
      - [Debian](https://www.debian.org/) Stretch 9.x
151
152
## Limitations and Known Issues
153
154
There are already some known issues!!! Not sure which will get fixed, might depend on how much people are interested in.
155
156
  - The 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 nextwork!</span>
157
  - 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).
158
  - 'Basic Authentication' over 'HTTPS' will work (for sure), but without detailed certificate checking.
159
160
## To-Do
161
162
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]].
163
164
1.  Daemonize (run in background/as service)
165
2.  Would be cool to enter the CardDAV relevant settings directly within the phone's LDAP settings! Possible?
166
167
## Support & getting help
168
169
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