====== LDAP Client ======

AstLinux includes the [[wp>Lightweight_Directory_Access_Protocol|LDAP]] client libraries along with command line tools that can be used to query an LDAP server.  PHP scripts may also act as an LDAP client where the query results can be easily filtered and acted upon.

!!Note: AstLinux 1.1.2 or later is required!!


===== LDAP Client System Defaults =====

Since AstLinux would typically only query a single LDAP server, it is convenient to define global system defaults that can be used by client queries.  Of course an LDAP client may override any of the system defaults if desired.

Select the Network Tab in the web interface.\\
{{:userdoc:ipv6-tunnel-network-tab.jpg?nolink|Network Tab}}

{{:userdoc:ldap-client-system-defaults.jpg?nolink|LDAP Client Defaults}}

  * LDAP Server URI(s): Space separated list of LDAP servers(s) as URI(s).
  * LDAP Base DN: Default base DN to use when performing LDAP operations. The base must be specified as a Distinguished Name in LDAP format.
  * LDAP Dereferencing:
    * [never] - Aliases are never dereferenced. This is the default.
    * [searching] - Aliases are dereferenced in subordinates of the base object, but not in locating the base object of the search.
    * [finding] - Aliases are only dereferenced when locating the base object of the search.
    * [always] - Aliases are dereferenced both in searching and in locating the base object of the search.
  * LDAP TLS Cert Check:
    * [never] - The client will not request or check any server certificate.
    * [allow] - The server certificate is requested. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, it will be ignored and the session proceeds normally.
    * [try] - The server certificate is requested. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, the session is immediately terminated.
    * [demand] - The server certificate is requested. If no certificate is provided, or a bad certificate is provided, the session is immediately terminated.
      * Server CA Cert File: CA file for [try] and [demand]. Example: ''/mnt/kd/ssl/ca-ldap.pem''

===== Phone LDAP Directory CGI Script =====

If your LDAP server's base DN allows anonymous queries, including names and phone numbers, AstLinux provides an unauthenticated Phone LDAP Directory CGI Script to perform anonymous LDAP queries.

While some IP Phones provide some sort of LDAP client address book, this CGI script provides a common result across many types of phones, even if they are not LDAP enabled.

!!Note ->!! The Network tab "LDAP Server URI(s):" entry must be defined for this directory CGI script to be enabled.

The ''phone-ldap-dir.php'' CGI script is similar to the ''phone-dir.php'' CGI script, but uses the "LDAP Client System Defaults" settings to query the data.

Examples:

  https://pbx/phone-ldap-dir.php?type=yealink&search=smith

  https://pbx/phone-ldap-dir.php?tls&type=snom&search=jones

The **type** may include: generic, polycom, aastra, yealink, or snom (defaults to "generic")


===== Custom LDAP Directory CGI Script =====

If your LDAP server's base DN does not allow anonymous queries for names and phone numbers, a custom version of ''phone-ldap-dir.php'' is required.  It is recommneded placing a custom copy of ''phone-ldap-dir.php'' in the ''/mnt/kd/phoneprov/'' directory which will be served via HTTP/HTTPS as ''/phoneprov/'' .

!!Tip ->!! A working knowledge of PHP is required.

If the ''/mnt/kd/phoneprov/'' directory does not exist, create it and restart lighttpd from the CLI, otherwise this step can be skipped.

  mkdir /mnt/kd/phoneprov
  service lighttpd stop
  service lighttpd init

Then copy the original ''phone-ldap-dir.php'' script to the ''/mnt/kd/phoneprov/'' directory...

  cp /stat/var/www/phone-ldap-dir.php /mnt/kd/phoneprov/

Next, edit the ''/mnt/kd/phoneprov/phone-ldap-dir.php'' script to suit your needs.  If authentication is required look for this section and define both ''$user'' and ''$pass'' variables.

  // begin - Custom variables, don't edit origional phone-ldap-dir.php script.
  // Copy this script to /mnt/kd/phoneprov/phone-ldap-dir.php to make changes.
  $user = '';
  $pass = '';
  $proto_version = 3;
  $ms_ad = FALSE;       // Set to TRUE for Active Directory server
  // end

The custom script is called per the following example, just as previously but with ''/phoneprov/'' and usually with ''tls'' enabled.

  https://pbx/phoneprov/phone-ldap-dir.php?tls&type=snom&search=jones

\\
!!Note ->!! You may want to restrict access via the web server for ''/phoneprov/'' access.  Using the **Network** tab in the web interface...

**Network** -> Network Services:

{{:userdoc:tt_ip_phone_provisioning1.png?nolink|Network Tab}}


===== Phone LDAP Directory CLI Scripts =====

In addition to the HTTPS CGI script described above, AstLinux also supports Command-Line-Interface (CLI) scripts to access LDAP directory data.  By default the scripts are configured to access the LDAP server with anonymous access (possibly 'localhost' when the LDAP Server enabled).  If user/pass authentication is required it is suggested to copy the script from ''/usr/bin/'' to ''/mnt/kd/bin/'' and customize the script accordingly.

!!Note: AstLinux 1.1.4 or later is required!!

If the local LDAP Server is enabled and populated with a directory, the typical LDAP Client setting to anonymously access via localhost is as follows:

{{:userdoc:ldap-client-system-defaults.jpg?nolink|LDAP Client Defaults}}
\\
\\
**ldap-phone-num-lookup**

  Usage: ldap-phone-num-lookup [-ht] [--tls] [-m|--match-num list] [-o|--output-name list] number
  
  Options:
      -h, --help             Show help
      -t, --tls              Enable TLS using start_tls
      -m, --match-num list   Comma separated list to match number. Default: telephonenumber,mobile,cellphone,homephone
      -o, --output-name list Comma separated list to display the name. Default: displayname,cn,sn,givenname

By default the 'number' is matched as: ''(|(telephonenumber=$number)(mobile=$number)(cellphone=$number)(homephone=$number))''

Standard output returns the first ''displayname/cn/sn/givenname'' that contains a matching number.

Use the optional ''-m|--match-num list'' and ''-o|--output-name list'' options to limit and specify the order of the matching and output.
\\
\\
**ldap-phone-name-lookup**

  Usage: ldap-phone-name-lookup [-ht] [--tls] [-m|--match-name list] [-o|--output-num list] name
  
  Options:
      -h, --help             Show help
      -t, --tls              Enable TLS using start_tls
      -m, --match-name list  Comma separated list to match name. Default: cn,displayname
      -o, --output-num list  Comma separated list to display numbers. Default: telephonenumber,mobile,cellphone,homephone

By default the 'name' is matched as: ''(|(cn=$name)(displayname=$name))''

Standard output returns (multiple) phone number(s) separated by a tilde (~).

Use the optional ''-m|--match-name list'' and ''-o|--output-num list'' options to limit and specify the order of the matching and output.

==== Asterisk Usage Examples ====

Examples how the ''ldap-phone-name-lookup'' and ''ldap-phone-num-lookup'' scripts can be used an Asterisk dialplan.

**CallerID number lookup via LDAP and AstDB**

<code>[subCID-lookup]
; CallerID(num) lookup, first LDAP then AstDB
exten => s,1,NoOp(CallerID lookup, first LDAP then AstDB ...)
 same => n,ExecIf($[ $["${CALLERID(num)}" != ""] & $["${CALLERID(name)}" = ""] ]?Set(LDAP_Name=${SHELL(ldap-phone-num-lookup '${ARG1}')})
 same => n,ExecIf($["${LDAP_Name}" != ""]?Set(CALLERID(name)=${LDAP_Name}))
 same => n,ExecIf($[ $["${CALLERID(num)}" != ""] & $["${CALLERID(name)}" = ""] ]?Set(CALLERID(name)=${DB(cidname/${CALLERID(num)})}))
 same => n,Return()</code>

And in your incoming context put this line somewhere:

  exten => s,n,GoSub(subCID-lookup,s,1(${CALLERID(num)}))