Directory

What is Directory?
Directory Storage Units
Local Units
Remote Units
Remote Directory Root
Binding to the Directory
Access Right Records
Access Right Specifications
Directory Browser
Importing Directory Data

The CommuniGate Pro Server includes the Directory Manager implementing high-performance standards-based Directory storage.

The Directory can contain records about the CommuniGate Pro Accounts, Domains, and other objects. It can also contain any other type of records, and it can be used as a stand-alone Directory Server serving any LDAP-based applications.

The Directory Manager is not the same as an LDAP server. The CommuniGate Pro LDAP module provides access to the Directory for LDAP clients, but various CommuniGate Pro components (Account and Domain Managers, WebUser Interface, etc.) access the Directory data directly, bypassing LDAP communications.

The Directory Manager implements Meta-Directory: it can store directory data in one or several sets of the server files (Local Units), and it can also use external LDAP servers as Directory Remote Units. Many different configurations are possible. The following simplest configurations are used most often:

All Directory data is stored in a single Local Unit. In this case Meta-Directory is the same as a Directory implemented with a regular LDAP server.
All Directory data is stored in a single Remote Unit. In this case Meta-Directory is used just as a method to access records stored on an external LDAP server.

What is Directory?

attribute

a name (attribute name) and one or several attribute values.
Usually an attribute is presented in the name=value form.
Attribute names are case-insensitive.
Samples:

userName=john
eyeColor=blue

object class

an attribute with the objectClass name; this attribute is used to specify a nature of the object it belongs to.
Samples:

objectClass=person
objectClass=organization

distinguished name (DN).

a sequence of attributes presented in the name=value form and separated with the comma (,) sign.
DNs are used as unqiue names for objects (records).
Sample:

userName=john,server=BigIron,realm=Internet

DNs are used to build object name trees, with the rightmost attribute specifying the most generic name, and the leftmost attribute specifying the unique object name itself.
The leftmost attribute is called Relative Distinguished Name (RDN) - it provides a unique name for the object among all objects with DNs having the same parent DN.
Sample:

userName=jim,server=BigIron,realm=Internet
this is a different DN, but it has the same "parent DN" (server=BigIron,realm=Internet)

Sample:

userName=john,server=SmallCopper,realm=Internet
this is a different DN, with a different "parent DN" (server=SmallCopper,realm=Internet)

directory record or object

set of attributes with a distinguished name
Usually a record is presented as several lines starting with the name presenting the record DN, followed by the lines presenting the record attributes. Several records are usually separated with an empty line.
Sample:

DN: userName=jim,server=BigIron,realm=Internet objectClass=person eyeColor=blue mailboxLimit=1024000 DN: userName=john,server=BigIron,realm=Internet objectClass=person eyeColor=green mailboxLimit=2048000

Note: the LDAP standard recommends to include the RDN attribute into the set of attributes making up a directory record. CommuniGate Pro Directory Manager enforces this rule.

directory

a set of directory records; this can be a very large set (millions of records). The set is organized as a tree using DNs. Records are removed automatically when the record with the parent DN is removed. Record DNs are updated automatically when the parent DN is changed (renamed).

directory schema

a set of directory restrictions, including:

a set of attribute names that can be used in the Directory (userName, mail, city, eyeColor, ...);
a set of objectClass attribute values that can be used in the Directory (person, organization, device, printer ...);
for each objectClass - names of the attributes that must be present in the object record; for records with objectClass=person a schema may require attributes with cn (canonical name) and sn (surname) names;
for each objectClass - names of the attributes that may be present in the object record; for records with objectClass=person a schema may allow attributes with driverLicense and eyeColor names.

Directory Storage Units

While the entire CommuniGate Pro Directory is presented to its clients as one large tree of directory records, its subtrees can be stored in separate storage units. This type of "virtual" directories is often called Meta-Directory.

CommuniGate Pro Directory supports two types of storage units:

local units - sets of files managed with the CommuniGate Pro File Directory Manager. These files contain directory records, replication information, and subtree schemas.
remote units - descriptors managed with the CommuniGate Pro LDAP Directory Manager. These descriptors contain the information about remote Directories accessed via LDAP.

As a result, the CommuniGate Pro Directory may include subtrees located on remote servers. If an LDAP server ldap.server.dom provides access to some directory tree, you can create a remote unit in the CommuniGate Pro Directory that points to the ldap.server.dom server and the entire ldap.server.dom directory tree or one of its subtrees will be seen in the CommuniGate Pro Directory as some subtree.

Initially, the CommuniGate Pro server creates one Local Storage Unit Main that contains the entire directory. You may add additional storage units using the WebAdmin Interface:

The diagram below shows a directory stored in one Local Unit Main:

The diagram below shows the same directory stored in 2 Storage Units, with the entire o=MyCompany subtree stored in a separate Storage Unit LDAP1:

Example 1:

An external LDAP server ldap1.com has a subtree o=MyCompany, and you want to store all CommuniGate Pro Domain and Account records in that subtree. You can use the following settings:

In the Integration settings, specify Base DN as o=MyCompany,o=ldap1
Create a Remote Unit MYLDAP for the o=ldap1 subtree.
Enter ldap1.com as the server name, and an empty string as the Server Subtree in the MYLDAP Unit Settings.

Now, when the CommuniGate Pro Server tries to access a directory record for the account john in the domain1.com domain:

The uid=john,cn=domain1.com,o=MyCompany,o=ldap1 DN is formed.
The Directory Manager detects that this record should reside on the MYLDAP Unit, and it asks that Unit to perform the requested operation on the record with the uid=john,cn=domain1.com,o=MyCompany DN (the Unit "mount point", o=ldap1 is removed from the DN).
The MYLDAP Unit sends the request for the uid=john,cn=domain1.com,o=MyCompany DN to the remote server ldap1.com.

Example 2:

An external LDAP server ldap1.com has a subtree o=MyCompany, and you want to store all CommuniGate Pro Domain and Account records in that subtree (the same situation as in the Example 1). You can use the following settings:

In the Integration settings, specify Base DN as o=ldap1
Create a Remote Unit MYLDAP for the o=ldap1 subtree.
Enter ldap1.com as the server name, and o=MyCompany as the Server Subtree in the MYLDAP Unit Settings.

Now, when the CommuniGate Pro Server tries to access a directory record for the account john in the domain1.com domain:

The uid=john,cn=domain1.com,o=ldap1 DN is formed.
The Directory Manager detects that this record should reside on the MYLDAP Unit, and it asks that Unit to perform the requested operation on the record with the uid=john,cn=domain1.com DN (the Unit "mount point", o=ldap1 is removed from the DN).
The MYLDAP Unit adds the Server Subtree suffix (o=MyCompany) to the DN, and then it sends the request for the uid=john,cn=domain1.com,o=MyCompany DN to the remote server ldap1.com .

Click the Directory link in the left frame of the CommuniGate Pro Server WebAdmin Interface. The Directory Storage Units page opens. You need to have the Directory access right to open this page.

The <root> string is used to specify the name of the default Storage Unit (i.e. the Storage Unit that stores the root of the Directory Tree).

To create a new Storage Unit, type a name for the new unit (this name will be used for administrating only), the Distinguished Name (DN) for the subtree that should be stored in that unit, and click the Add Remote Unit or Add Local Unit button.

Local Units

Local Directory unit is a set of files containing unit data (records/entries), unit schema, unit settings, and unit modification journal.

Open the Directory WebAdmin page and click the name of a Local Storage Unit. The unit Settings page opens.

Settings
Log:
	Enforce Schema	Search Result Limit:	records

Log: Use this setting to specify what kind of information the Local Storage Unit Manager should put in the Server Log.
Enforce Schema: When this option is selected, the Local Storage Unit Manager compares the structure of all new and updated records with the Unit Schema. If this option is disabled, then the Manager checks only the names of the record attributes and ensures that those attributes are included into the Unit Schema, but it does not enforce the objectClass-related restrictions.
Search Results Limit: This setting limits the maximum number of records a Directory Search operation can return.

Each Local Unit has its own Schema. See the Schema section for more details on Unit Schemas.

You can browse and modify the Local Unit Schema by retrieving and modifying the virtual record with the cn=schema DN. If the Local Unit is mounted on some Directory subtree, the DN for the Unit Schema record is cn=schema,subtree.

Remote Storage Unit

Click a Remote Storage Unit name on the Directory WebAdmin page to open the unit Settings page:

Settings
Log:
LDAP Server Name:
Security:
Server Subtree:
BIND DN:
BIND Password:
Protocol Version:
Channel Cache:

Log: Use this setting to specify what kind of information the Remote Unit Manager should put in the Server Log.
LDAP Server Name: This field specifies the name or the IP address of the remote LDAP server that hosts the Storage Unit subtree. If the remote LDAP server uses non-standard TCP port, you can specify the Server Name as servername:port.
Security: If the TLSPort option is set, connections to the remote server will be established in the secure mode. The default port for secure connections is 636.
If the STARTTLS option is set, connections are established to the regular LDAP port, and then the STARTTLS LDAP command is sent to initiate secure (encrypted) communication.
Server Subtree: This field specifies the remote LDAP server subtree to be "mounted". When this setting is left empty, the entire remote directory becomes visible as a CommuniGate Pro Directory subtree.
BIND DN, BIND Password: These fields specify the Distinguished Name and Password to use for "binding" (logging into) the remote LDAP server. If these fields are left blank, the CommuniGate Pro will use anonymous access to the remote LDAP server.
Protocol Version: Use this field to specify the LDAP protocol version supported with the remote LDAP server.
Channel Cache: Use this field to specify the number of "cached" TCP connections used to connect to the remote LDAP server.

Remote Directory Root

In certain situations a CommuniGate Pro server should not keep any Directory data in its Local Storage units. Instead, all Directory records should be stored on a remote LDAP server (some other CommuniGate Pro server or a third-party Directory server). In this case, the CommuniGate Pro "root" should be stored in a Remote Storage Unit pointing to that external server. By default, the Directory "root" is stored in the Main Local Storage Unit. To tell the CommuniGate Pro server that the Directory "root" and the entire Directory tree is stored on a remote server, follow these steps:

open the Main Storage Unit settings.
relocate the Unit to a fictitious subtree o=dummy
create a Remote Storage Unit RemoteRoot specifying an empty string as its Subtree.
configure the RemoteRoot Storage Unit so it will access the proper remote LDAP server.
check that the remote directory is available (using the CommuniGate Pro Directory Browser).
open the Main Storage Unit settings and click the Remove Unit button to remove this Storage Unit.

Binding to the Directory

Directory records can be (and usually are) protected from unauthorized access. When users want to access protected Directory data, they should authenticate themselves first. This process is called binding and successful authentication "binds" the user to a certain DN (distinguished name) in the Directory.

When a user tries to read or modify the Directory data, the binding DN is used to check the Directory Access Rights.

When a user accesses the Directory from a CommuniGate Pro Web User Interface session, the binding DN is the DN of the user Account record:
uid=accountname,cn=domainname,o=MyCompany.
See the Directory Integration chapter for the details.

When the Directory is accessed using the LDAP module, the client can authenticate itself using the CommuniGate Pro Account name and the Account password. In this case, the binding DN is the DN of the Account record.

Before converting the user account name into the account Directory record DN, the user account Server Access Rights are checked. If the account has the Directory access right, the special "master" bind DN is used instead of the user account record DN. Clients with the "master" bind DN have unlimited Directory access rights.

Any Directory DN can be used for LDAP binding. The directory record with the specified DN must exist, the record should contain the userPassword attribute, and the attribute value must match the supplied password string.

If a client has not authenticated itself, the special anyone bind DN is used.

Access Right Records

CommuniGate Pro Directory restricts client rights to read, search, and modify Directory records. The Directory contains a set of the Access Right records that allow and prohibit directory operations depending on the target directory subtree and on the client binding DN.

Open the Directory Access Rights page to set the Access Right records:

Each Access Right record has:

a name.
a target: the DN the record applies to; wildcard characters ("*") can be used in Target strings.
a Bind DN: the client binding DN the record applies to.
the record type: enabling or disabling.
a link to the Record specific access rights.

The Up and Down buttons allow you to move the records in the table, increasing and decreasing record priorities.

When a client requests to perform a search, read, modify, or any other operation on a record or a subtree with a certain DN, the Access Right records are checked from top to the bottom. The server looks for an Access Right record that:

has the Target field matching the DN specified in the client request.
has the Bind DN field matching the client binding DN.
has the operation (delete, create) matching the requested operation, or has the attribute matching the attribute used in the operation.

When such an Access Right record is found, the record type specifies if the operation is allowed or prohibited. If no Access Right record is found, the operation is prohibited.

If the client binding DN is "master" (see above), all operations are allowed.

When a client requests a "read"-type operation, the procedure is repeated for all attributes the client wants to retrieve. If the operation is prohibited for all specified attributes, the read operation fails. Othwerwise, the operation is peformed, and the attributes the client has a right to retrieve are returned to the client.

If a client requests a "search"-type operation, the procedure is repeated for all attributes used in the search filter. If the search operation is prohibited for at least one of those attributes, the search operation fails. The RDNs of found records is checked. If the RDN attribute is not allowed to be read, the record is not returned to the client.

If a client requests a "rename"-type operation, the procedure is used twice: to learn if the client has a right to delete the original Directory record, then to learn if the client has a right to create a Directory record in the new location.

Special strings can be used in the Bind DN field:

brother: the Access Right record is applied if the Bind DN and the Target DN has the same parent DN. For example, the uid=someuser,cn=domain1.com and uid=otheruser,cn=domain1.com DNs are "brothers". This type of bind DN specifications is useful to grant CommuniGate Pro users access to the Directory records of other users in the same CommuniGate Pro domain.
parent: the Access Right record is applied if the Bind DN is a parent of the Target DN. For example, the cn=domain1.com DN is a parent of uid=user1,cn=domain1.com and id=book1,uid=user1,cn=domain1.com DNs.
child: the Access Right record is applied if the Target DN is a parent of the Bind DN.
self: the Access Right record is applied if the Target DN is the same as the Bind DN. This type of bind DN specification is useful to grant CommuniGate Pro Account users a right to modify their own directory record attributes.

To create an Access Right record, enter the record name, target DN, and bind DN into the last empty element of the Access Rights table and click the Update button. Use the Up buttons to set the record priority.

To remove an Access Right record, delete the record name and click the Update button.

Access Right Specifications

To specify Directory Access Rights, open the Access Rights page and click the "specifications" link to open the Access Right record:

These options specify if clients with the given Bind DN can create or delete records with the given Target DN.

This field lists the data attributes that clients with the given Bind DN can read from the records with the given Target DN. The attribute names should be comma-separated. To allow clients read all record attributes, use the asterisk ("*") sign.

This field lists the attributes that clients with the given Bind DN can use in filters when searching Target DN subtrees.

This field lists the data attributes that clients with the given Bind DN can modify in the Target DN records.

Sample Access Right record:

Target DN: uid=*,cn=domain1.com
Bind DN: brother
Type: allow
Readable Attrbutes: objectClass,officeEmail,roomNumber,cn,uid

This record allows all domain1.com users to read the objectClass, cn, uid, officeEmail, and roomNumber attributes from Directory records of other domain users.

Sample Access Right record:

Target DN: cn=domain1.com
Bind DN: child
Type: allow
Readable Attrbutes: objectClass,officeEmail,roomNumber
Searchable Attrbutes: cn,uid

This record allows all domain1.com users to search the domain Directory subtree by cn (cannonical name) and uid, but not by other readable attributes.

Directory Browser

The CommuniGate Pro WebAdmin Interface includes a Directory Browser. Open the Directory page and click the Browser link to open the Directory Browser page.

The Browser page includes the DN field:

Use this field to type the DN of the Directory record/subtree you want to view and click the Go button. Click the Up button to remove the leftmost DN element and open the parent Directory record.

The next panel displays the Directory record with the specified DN:

Attribute	Value
businesscategory	"Software development/technical support"
description	"\"subsidiary for Stalker Software, Inc.\""
o	"Stalker Labs"
objectclass	organization
seealso	"o=Stalker Software, c=US"
telephonenumber	676-555-1212

If the record with the specified DN could not be retrieved, this panel will contain the error message.

The next panel displays all record children.

Use the pop-up menu to limit the number of records displayed on the subtree panel.

To search for specific records, enter an LDAP filter string (in the RFC 2254 format) into the Filter field and click the Display button.

The table elements display children RDNs and object classes.

Click the child element RDN link to open the child record in the Directory Browser.

Importing Directory Data

The CommuniGate Pro WebAdmin Interface allows the Server Administrator to import directory modifications from text files in the LDIF and "replog" formats:

To import data into the CommuniGate Pro Directory, click the Browse button and select an LDIF file on your workstation. Click the LDIF Import button to insert all records from the selected LDIF file.

To apply a set of record modifications to the CommuniGate Pro Directory, click the Browse button and select a "replog" file on your workstation. Click the LMOD Import button to apply all modifications from the selected file.