Project

General

Profile

Readme 050 » History » Version 5

Jörg Ebeling, 03/13/2019 08:07 PM

1 1 Jörg Ebeling
# LDAP-2-CardDAV Phone Book Gateway (l2cpbg)
2
3 2 Jörg Ebeling
{{>toc}}
4
5 1 Jörg Ebeling
An LDAP to CardDav (1 way read) Phone Book Gateway.
6
7
## Use case
8
9
Most modern (business) voice phones have the capability to do comfortable LDAP directory look-up like:
10
11
  - Directory search by alphabet letters
12
  - Reverse lookup for inbound calls
13
  - Reverse lookup by entering parts or the phone number
14
15
Unfortunately, most of the 'smaller' companies (i guess companies beyond 100 employee) don't have an 'enterprise' LDAP directory, much less than private persons.
16
17
Most of such companies do have something like a cloud address book, often based on WebDAV / CardDAV (i.e. Nextcloud, Ownlcoud, ...).
18
19
This is, where this Gateway might make your live easier (hopefully).
20
21
If this program get started on some kind of hardware (Windows, Mac, Linux, ???), it will do the following:
22
23
1.  Answer on LDAP requests from your voice phone(s)
24
2.  Ask your CardDAV (Nextcloud, Owncloud, ...) Server for the LDAP requested phone book entry
25
3.  Return the CardDAV query results, back as LDAP results to your phone.
26
27
## Features
28
29
  - Query your CardDAV address book(s) by entering the alphabetic letters (or parts of the telephone number) in you (LDAP capable) (business) phone (and dial one of the matching numbers).
30
  - Reverse lookup inbound calls and display matching contact information on the phone.
31
  - Work with local (non- E.164) formatted CardDAV entered phone numbers like: '040-123456' or '001 807 1234567' as well as '+49 (0)40 1234567-8'.
32
  - Alphabetic search requests get queried live (without a caching layer or sync delay). This might get changed or optionally enhanced in future, once I do have some experience with different CardDAV Server and larger (+1000 CardDAV) address books.
33
  - Reverse lookup on phone numbers, depend on a tiny caching layer and thus a (configurable) sync interval.
34
35
## Usage
36
37
You need some kind of 24/7 machine where this Gateway live. Windows, Linux, Mac, (ARMx might come later).
38
39
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'.
40
41
No installation required. Only one simple executable. Place it wherever your like. But I advice to start it as normal (non-root, non-administrative) user.
42
43
It will look for a configuration file in the following places (in the given order):
44
45 4 Jörg Ebeling
1.  ./.l2cpbgrc (or in it's parents)
46
2.  $HOME/.l2cpbgrc
47
3.  $HOME/.config/l2cpbg
48
4.  /etc/l2cpbgrc
49
5.  and some more uncommon places
50 1 Jörg Ebeling
51
## Config file syntax
52
53
The config file syntax is 'ini' based. Following a quick sample:
54
55
``` ini
56
; Comments get started with a semicolon
57
;
58
; The Gateway will act/listen as LDAP Server with the following settings
59
[ldap]
60
    host      = 0.0.0.0
61
    ;port      = 1389
62
    base      = dc=example, dc=com
63
[ldap.bind]
64
    dn   = cn=pbx
65
    pass = your-password
66
[dav]
67
    server       = https://cloudserver.example.com/remote.php/dav
68
    user         = cloud-login-name
69
    pass         = cloud-login-password
70
    ;addressbooks = regular-expression-of-lookup-adressbook
71
    syncinterval = 5      ; Minutes
72
;[dav.map]
73
;  tel = TEL
74
;  fn  = FN
75
[location]
76
    int           = 1
77
    area          = 807
78
    maxarealength = 7
79 5 Jörg Ebeling
    country       = en
80 1 Jörg Ebeling
```
81
82
### Config file description
83
84
#### \[ldap\] part
85
86
`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.  
87
`port` : Port to listen for LDAP requests. Defaults to port 1389. You normally don't need to change this.  
88
`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'.
89
90
#### \[ldap.bind\] part
91
92
`dn` : Distinguish name. Name, how the phone has to log into/authorize to the gateway.  
93
`pass` : Related 'dn' password, a phone has to use when logging in/authorize to the gateway.
94
95
#### \[dav\] part
96
97
`server` : Your WebDAV/CardDAV server address/URL. Please see 'Limitations'!  
98
`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.  
99
`pass` : Related user password.  
100
`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.
101
102
#### \[dav.map\] part
103
104
`tel` : CardDAV attribute which contain the phone numbers. Normally (and by default) 'TEL'.  
105
`fn` : CardDAV's 'Full Name' attribute. Normally (and default) 'FN'.
106
107
#### \[location\] part
108
109
`int` : International area code (1 = North America, ..., 44 = United Kingdom, 49 = Germany, ...) of your location.  
110
`area` : Local area code without leading 0 (20 = London (UK), 40 = Hamburg (DE), ...).  
111
`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.  
112
`country` : Two-letter [ISO 3166-1 alpha-2](https://wikipedia.org/wiki/ISO_3166-1\_alpha-2) country code (i.e. US, GB, DE, ...).
113
114
## Phone configuration
115
116 2 Jörg Ebeling
p(. Here's a sample of a Yealink SIP-T52S configuration:  
117 1 Jörg Ebeling
![Yealink SIP-T52S settings sample](config_yealink-t52s_fw7084_v050_en.jpg "Yealink SIP-T52S settings sample")  
118
Take attention that <span style="color: #d97a3a;">Server Address</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.
119
120
## Compatibility
121
122
This early version is currently only tested (working) with:
123
124
  - CardDAV Server:
125
      - [Nextcloud](https://nextcloud.com/) version 13.0.8
126
  - Phone Extensions:
127
      - [Yealink](https://www.yealink.com/) SIP-T52S, SIP-T54S, SIP-T54W
128
  - Gateway Host OS:
129
      - [Debian](https://www.debian.org/) Stretch 9.x
130
131
## Limitations and Known Issues
132
133
There are already some known issues!!! Not sure which will get fixed, might depend on how much people are interested in.
134
135 3 Jörg Ebeling
  - 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>
136 1 Jörg Ebeling
  - 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).
137
  - 'Basic Authentication' over 'HTTPS' will work (for sure), but without detailed certificate checking.
138
139
## To-Do
140
141
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]].
142
143
1.  Add (non-ansi) logging to file
144
2.  Add date & time info to log
145
3.  Daemonize (run in background/as service)
146
4.  DB-Caching layer for huge CardDAV address books (or slow CardDAV Server)
147
5.  Would be cool to enter the CardDAV relevant settings directly within the phone's LDAP settings! Possible?
148
149
## Support & getting help
150
151
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