Chapter 11   Configuration Overview


This chapter provides an overview of iPlanet Directory Access Router (iDAR) configuration via the command line. The chapter contains the following sections:

• Introduction

• iDAR Configuration File Format

• Building a Configuration File

• iDAR Decision Functions

Introduction

---

Configuration of iDAR is a two step process. First, a startup configuration file (tailor.txt) must be created with information that will enable iDAR to find its configuration; for details, see Startup Configuration File. Then, the iDAR configuration file (tailor.ldif) must be created; it must reside in another file on disk or in an LDAP directory server. In the latter case, the startup configuration must also contain information about what mechanism is used to bind to the directory server. The remainder of this chapter is an overview of the iDAR configuration.

iDAR Configuration File Format

---

The iDAR configuration file (tailor.ldif) is in LDAP Data Interchange Format (LDIF). LDIF is used to represent LDAP entries in a simple text format. This format is used for iDAR configuration files for two reasons.

First, a simple text file is easy to modify, and second, using an LDIF file allows you to store the iDAR configuration in an LDAP directory server. This may be important for customers who decide to distribute their LDAP infrastructure geographically but want to manage the administration of that infrastructure centrally. By choosing to keep all iDAR configurations in a central LDAP repository, central administration of the iDARs can be achieved. The configuration file is divided into a number of distinct sections, each potentially comprising multiple directory entries:

• Server - The server entry identifies the iDAR server instance. It is constructed by including the ids-proxy-sch-LDAPProxy object class. The startup configuration file points to this entry. The server entry has some basic attributes that identify where the global configuration object is located, the name of the server instance, and the DNs under which the group, property, rule, and action object entries reside. Figure 11-1 shows these relationships graphically.

• Global - The global configuration entry is constructed of attributes that identify those iDAR properties that are common to all clients. Global entry is constructed by including the ids-proxy-sch-GlobalConfiguration object class. See Chapter 15 "Global Configuration."

• Groups - Each group entry identifies a specific client community, and specifies the restrictions to enforce on clients that match that group. Group entries are constructed by including the ids-proxy-sch-Group and the ids-proxy-sch-NetworkGroup object classes. See Chapter 16 "Groups Configuration."

• Properties - Each group entry may include a set of properties defined by property entries. These property entries describe more specialized restrictions on the clients. Property entries are constructed by including the ids-proxy-sch-Property object class together with its associated object classes. Properties are included within group entries by defining the property entry name as the value of the ids-proxy-con-include-property attribute. See Chapter 17 "Properties Configuration."

• Rules - A group or property entry may include one or more rule entries. These rules are evaluated at predetermined points of execution (determined by the rule type), and one or more actions (defined separately) can be taken based on the result of the evaluation. Rule entries are constructed by including the ids-proxy-sch-Rule object class together with its associated object classes. Rules are included within group entries by defining the rule entry name as the value of the ids-proxy-con-include-rule attribute. See Chapter 18 "Events Configuration."

• Actions - Depending on the evaluation of a rule, one or more actions may get executed. Action entries specify what the iDAR needs to do in the case where the rule that includes them evaluates to TRUE. Action entries are constructed by including the ids-proxy-sch-Action object class together with associated object classes. Actions are included as part of rule entries by defining the action entry name as part of the value of the ids-proxy-con-execute attribute. See Chapter 19 "Actions Configuration."

Figure 11-1    Information Model and Configuration Entry Relationship

It is worth noting at this point that the iDAR configuration file adheres to the following naming convention:

Those elements of the configuration file that specifically relate to the schema structure (as opposed to the iDAR configuration elements) start with the prefix ids-proxy-sch where the sch component indicates the schema. Examples of such elements are names of object classes (e.g., ids-proxy-sch-Group) and attributes with a syntax of DN (e.g., ids-proxy-sch-Property-Base). Those elements of the configuration file that are specifically related to the iDAR configuration start with the prefix ids-proxy-con where the con component indicates configuration. Almost all attributes defined as part of the iDAR schema (other than those with DN syntax) start with ids-proxy-con (e.g., ids-proxy-con-listen-port). This is because the vast majority of attributes relate to iDAR configuration options. The two notable exceptions are ids-proxy-sch-Enable and ids-proxy-sch-belongs-to. The first attribute determines if the entry is part of the configuration or not and the second attribute determines which server configuration(s) the entry belongs to.

Building a Configuration File

---

To build a configuration file:

• Define Global Entries

• Define Property Entries

• Define Action Entries

• Define Rule Entries

• Define Group Entries

Define Global Entries

The configuration file is constructed by first defining a set of global entries that represent those properties of iDAR that are common to all client groups.

Examples of such properties are:

• The host name and port number iDAR is going to listen on for incoming connections

• The maximum number of simultaneous clients connections accepted

• SSL/TLS configuration

• The search base for the group, property, rule and action configuration entries

A complete description of all the global entry object classes and attributes can be found in Chapter 15 "Global Configuration."

Define Property Entries

Next, the property entries should be defined for all properties to be utilized within the configuration. For example, if iDAR is going to be configured for load balancing and automatic failover and failback, then a load balancing entry should be defined using the ids-proxy-sch-LoadBalanceProperty object class. A complete description of all the property entry object classes and attributes can be found in Chapter 17 "Properties Configuration."

Define Action Entries

The action entries should be defined next. iDAR currently supports the ids-proxy-sch-ChangeGroupAction object class that allows iDAR to be configured to change a client from one access group to another based on the evaluation of a rule. This is typically used to support mobile users where the rule might be ids-proxy-sch-OnBindSuccessRule. A mobile user could connect to the iDAR with a dynamic IP address and drop into a "default" access group. The "default" access group would have the ids-proxy-sch-OnBindSuccessRule rule specified that only evaluates to TRUE if the bind credentials provided by the mobile user are authenticated. This rule would also have the ids-proxy-sch-ChangeGroupAction specified to change the mobile user's access group from the "default" to the access group the mobile user is usually assigned to when accessing iDAR with a static IP address. Actions need to be defined before rules since the rule definition requires you to specify a previously defined action. A complete description of all the action entry object classes and attributes can be found in Chapter 19 "Actions Configuration."

Define Rule Entries

Rule entries should be defined next, following the definition of the action entries. iDAR currently supports the ids-proxy-sch-OnBindSuccessRule and the ids-proxy-sch-OnSSLEstablishedRule object classes. If the iDAR administrator wishes to change the access group of a client based on the evaluation of one of these two rules then both an ids-proxy-sch-ChangeGroupAction action entry and one of the two rule object classes need to be defined. The rule entry must include the name of the action entry as part of the value of the ids-proxy-con-execute attribute. A complete description of all the rule entry object classes and attributes can be found in Chapter 18 "Events Configuration."

Define Group Entries

Having defined global, property, action and rule entries you are now at the point to define the group entries. Group entries are the core entries of the iDAR configuration file because they identify the different LDAP client groups and determine the routing, access controls, request filtering, response filtering, etc., that iDAR applies to LDAP operations initiated by those clients. There are currently over 40 different attributes for configuration options within the ids-proxy-sch-Group and ids-proxy-sch-NetworkGroup object classes. These can be classified into the following categories:

• Group object attributes

• Client identification

• Including rules and properties

• SSL policy

• LDAP bind request validation

• Control of forwarding different LDAP operation types

• Controlling search, compare and modify requests and responses

• Referral following policy

• Controlling the directory server load

• Hiding a subtree of entries

A complete description of all the group entry object classes and attributes can be found in Chapter 16 "Groups Configuration."

Group entries are constructed by first considering the client communities you need to support or differentiate between. Identify the clients making up a community and create a group for them by first identifying them in the group entry by correctly defining the ids-proxy-con-client multi-valued attribute. If you have previously defined property and rule entries that are appropriate for this group, then include them by configuring the ids-proxy-con-include-property and/or the ids-proxy-con-include-rule attributes. Using the attributes defined for the group object classes, configure additional controls for this group as appropriate. Then move on to the next group definition.

Configuration File Build Tool

To help iDAR administrators get started with configuring iDAR, iDAR ships with a command-line configuration tool that allows you to build a number of different configuration files. A complete description of the iDAR configuration file build tool can be found in Chapter 13 "Configuration Generation Tool."

The command-line tool, tailor allows you to specify command line parameters that the tool uses to automatically generate a working iDAR configuration file in LDIF format. Note that there are limitations to what the command-line tool can generate so in most cases it should be considered a tool for building a basic working configuration file that can then be modified to provide further customization.

Currently, the build tool supports generating configuration files for the following customer scenarios:

• The bare minimum, "out-of-the-box" configuration to get the user up and running with a working iDAR configuration immediately. This configuration is a simple "passthru" from the LDAP client to a single LDAP directory server via iDAR. There is no filtering of requests or responses and no additional access controls. Only one client group will be generated.

• A more sophisticated configuration that incorporates load balancing and automatic failover and failback into the basic configuration mentioned above. The user can specify any number of LDAP directory servers and load balance the client load across them all. Only one client group will be generated.

• The third scenario is probably the most complex. This scenario will allow the LDAP client to bind to the LDAP directory server either anonymously or with bind credentials and treat the two differently. The tailor.tcl tool will generate two groups: one that is employed when a client binds with bind credentials and another group that acts as a "default" group. All clients that bind anonymously will fall into the "default" group and will be limited to search operations only. Those clients that bind with bind credentials will initially drop into the "default" group. The "default" group has the ids-proxy-sch-OnBindSuccessRule rule included in it. This rule has the ids-proxy-sch-ChangeGroupAction action associated with it. So clients that bind with bind credentials that are subsequently authenticated cause the rule to evaluate to TRUE and the action to get executed that changes the group the client belongs to from the "default" group to a group with more access rights. The concept behind these two groups is to grant more access rights to those clients binding with bind credentials and to restrict the access rights of clients binding anonymously.

The tailor tool can be helpful in generating LDIF configuration files. For example, tailor could be used to generate a configuration file for the typical customer deployment of an internal high availability configuration described using Figure 2-1. You would use tailor load balancing scenario with the following syntax:

tailor          -server ldaphost-1 -server ldaphost-2 -server ldaphost-3\
          -server ldaphost-4

No further customization of the configuration file generated by tailor is necessary. The firewall deployed in this scenario should ensure there is no external access to either the iDAR or the LDAP directory server. However, for additional peace of mind the user could customize the configuration file by identifying "internal" LDAP clients via the ids-proxy-con-Client multi-valued attribute in the ids-proxy-sch-NetworkGroup object class. Any client that attempts to connect to the iDAR but hasn't been identified by the ids-proxy-con-Client multi-valued attribute will be rejected.

Don't forget to use TCP wrapper or equivalent program on UNIX platforms and TCP/IP port filtering on Windows NT to ensure access to the LDAP directory servers is only permitted for the iDARs you deploy.

iDAR Decision Functions

---

This section describes the flow of control in iDAR for some specific functionalities.

Establishing Group on Connection

When a client makes a connection to iDAR, it checks the ids-proxy-con-Client attribute in ids-proxy-sch-NetworkGroup object entries until it finds a match. The ids-proxy-sch-NetworkGroup objects are tried in highest to lowest priority defined by the ids-proxy-con-priority attribute. iDAR places the client in the first group whose ids-proxy-con-client attribute matches the IP address of the client. If no matching groups are found, the connection is closed.

Change Group on Bind

When the client initially connects, it is placed in a group based on its IP address. The client can be moved to a different group with different access controls when it binds to a directory. To accomplish this, the initial group object must include a rule object that is evaluated on a successful bind operation. If the rule evaluates to TRUE, the change group action is taken to move the client to a different group. Figure 11-2 illustrates this functionality.

Figure 11-2    Change Group on Bind

Change Group on Establishment of TLS

Similar to the change group on bind mechanism is the change group on establishment of TLS, whereby a client can change group when it successfully establishes an TLS session. The SSL Established rule is evaluated when the client establishes TLS, following which the Change Group action follows. This functionality is illustrated in Figure 11-3.

Figure 11-3    Change Group on Establishment of TLS

High Availability Setup

If you have configured more than one backend directory server, then you can set up iDAR to load balance across these and fail over to another if one of the backend servers go down. In order to do this, you must create a Load Balance Property (see Load Balancing Property or ids-proxy-sch-LoadBalanceProperty Object Class) and include it in the group object for which you want to load balance. You will also need to create LDAP Server Properties (see LDAP Server Propertyor ids-proxy-sch-LDAPServer Object Class) for each of your backend servers and include it in the Load Balance Property. You must specify the amount of load in percentage of total load each of your backend servers should handle in the Load Balance Property object. With this setup, iDAR will redistribute load across its backend directory servers if one of them goes down. It will fail over clients from one server to another in case the first goes down. iDAR will also fail over if the network link between itself and the LDAP server is down or if the LDAP server becomes unresponsive (see ids-proxy-con-keepalive-interval).

---

Note	iDAR is unable to fail over if the client was bound using a SASL mechanism.

---

Following Referrals

iDAR can be set up to follow referrals for LDAPv2 clients that cannot do so on their own. Your backend LDAP directory server must be capable of sending referrals, i.e., it must support LDAP v3 standards. Configure iDAR to use LDAP v3 between itself and the backend LDAP server in order for iDAR to receive referrals from the directory server (see ids-proxy-con-use-version). Then set your group's referral (see Controlling the Return of Referrals) and continuation referral policy (see ids-proxy-con-search-reference).