Configuration and Setup Instructions for Reading Policies From a LDAP server

Table of Contents

 Overview
 Files in this Package
 Including the Objectclass and Attribute Files in the LDAP Server
 Adding and Modifying Policy Entries to the LDAP Server
 Configuring the Router to Read Policy Information from LDAP
 Resetting the LDAP Configuration Parameters and the Policy Database
 Resolving Problems Interacting with the LDAP Server

Section 1: Overview

The 221x family of routers (with V3.3 or greater) allow the repository of policy information to be a LDAP (Lightweight Directory Access Protocol)  server.  LDAP is a protocol that allows a directory server to be searched and modified.  LDAP is a lightweight version of the X.500 standard. The routers support the ability to search (not modify) for information in the directory server.  The policy search agent in the router will retrieve all the policy information in the directory server that is intended for that device.

An advantage of using a directory server to store policy information as opposed to more traditional methods of locally stored configuration is the ability to make a change in one place and have that change applied across all the devices in the extended network.  This includes devices in the local administrative domain as well as devices across public boundaries.  Take for example, a IPSEC Transform definition that resides in the directory.  To change the corporate policy for encryption from DES to 3DES normally would require a change in the configuration of each device in the extended network. If the directory server is used to deploy the policies then one IPSEC transform would need to be changed in the LDAP server and then each policy enabled device in the network would need to rebuild the internal policy database.  Another good example would be if a DiffServ action named "GoldService" needed to be changed from 40% of bandwidth to 45% of bandwidth.  The LDAP server and policy infrastructure allows these types of configuration changes to scale much better and reduce configuration mismatches.

To take advantage of this feature a LDAP server operating at RFC Version 2 or 3 is required.  IBM's SecureWays LDAP server is the recommended implementation, however any LDAP server should work.  There are a couple of LDAP packages freely available on the internet (namely OpenLdap and the University of Michigan implementation).

LDAP Schema is the set of rules and information that comprise the class and attribute definitions that define the entries that ultimately exist in the directory. LDAP schema is typically written in ASN1 syntax similar to SNMP MIBs.  The Policy Schema developed for the IBM routers is based on pre-standard efforts being worked on in the IETF by the IPSEC and Policy Working Groups.  Every class definition consists of a set of attributes that define the class. The attributes are either required attributes or allowed attributes.  Required attributes are ones which must be present when the object is added or modified in the LDAP server. Allowed attributes are ones which may or may not be included in the object definition.  If they are not included then the default value will be used by the policy search agent in the router when parsing the object from the LDAP server.  The default values for each attribute can be found in the ibmPolicySchema.txt file included in this package.

Two key objects in the Policy schema that allow the Policy Search Agent to search for and find the necessary policies for the device are the DeviceProfile and the DevicePolicyRules.  The DeviceProfile has information about the device's mandatory DevicePolicyRules reference.  Devices can be grouped together into one DeviceProfile or each device in the network can have it's own DeviceProfile.  This really will depend on whether more than one box in the network needs to fetch the same set of rules.  Typically for Security Gateways this will not be true since every gateway will have a different tunnel endpoint.  For QOS only boxes, it would be conceivable that a group of devices would all read the same set of policies.

The DevicePolicyRules object will be retrieved based on the value in the DeviceProfile that is fetched for the device.  Once the DevicePolicyRules object has been retrieved, then the list of PolicyRules for that device can be retrieved.  If any of the objects are not found or if an error is detected during a consistency check on a object then the search is aborted and messages will be displayed for the PLCY ELS subsystem denoting the error detected.

The Policy Schema closely matches the configuration objects in the Policy Feature on the router.  Perform the configuration steps to add a policy in talk 6, feature policy to acquaint yourself with the policy objects and their relationships.

Section 2: Files in this Package

policyTemplates.ldif           Pre-defined policy objects
policyExamples.ldif            Some examples of security policies
ibmPolicySchema.txt            Description file for IBM's Policy Classes
policySchema_oc.conf           The objectclass file for the LDAP server
policySchema_netscape_at.conf  The attribute file for the Netscape LDAP server
policySchema_ibm_at.conf       The attribute file for the IBM LDAP server
policySchema_openLdap_at.conf  The attribute file for the OpenLdap server

Section 3: Including the Objectclass and Attribute Files in the LDAP Server

LDAP servers typically have the ability to enforce "schema checking".  Schema checking is the ability for the LDAP server to understand the attributes of a class, which attributes are required for the object to be added to the directory and the attributes that are optionally allowed with the object. The LDAP server will not allow the object to be added if a required attribute is not included or if an unknown attribute is included within the object. Since IBM's Policy Schema is not standardized yet, the schema will not come pre-installed with the LDAP server. The instructions for adding the objectclass file (policySchema_oc.conf) and the attribute file (policySchema_<platform>_at.conf) to the LDAP server configuration file are detailed below:
 
  1. Locate the LDAP server configuration file. This typically is the slapd.conf file. On Unix machines this may be in the /etc directory.
  2. Edit the slapd.conf file and add the following lines (these lines should be added after any other include statements in the config file)
      3.  
      include <path>/policySchema_<platform>_at.conf
      include <path>/policySchema_oc.conf
The oc and at files were tested and verified to work with the versions of the respective LDAP servers at the time of this writing. Conceivably there
may be changes by these vendors that cause the files to be modified. In the event that installing these files does not work and you cannot determine the problem, please contact someone in router support and every attempt will be made to resolve the issue.

Section 4: Adding and Modifying Policy Entries to LDAP Server

Depending on your platform, LDAP server choice and growth of products which interact with the LDAP server there may be numerous ways to modify the information stored in your LDAP server.  Currently the ubiquitous method of editing the content of the directory server is via the command line utilities which parse LDIF (LDAP Data Interchange Format).  These command line utilities are ldapsearch, ldapmodify, ldapdelete and ldapadd.  Every LDAP server we have tested with included versions of these client utilities.

Two files are included in this package to help the administrator get started deploying policies in the LDAP server.

The instructions for how to add the objects defined in these files to the LDAP server are described below:
  1. Add policy templates first
    1. Remove comments from file using the following command
        2. grep -v '^#' policyTemplates.ldif > out.ldif
    2. Add the entries in the new out.ldif file using the ldapmodify client
        3. ldapmodify -h <hostname> -D <user dn> -w <password> -rac -f out.ldif
  2. Make any modifications to the example policies supplied and then perform the following steps
    1. Remove comments from the file using the following command
        2. grep -v '^#' policyObjects.ldif > out.ldif
    2. Add the entries in the new out.ldif file using the ldapmodify client
        3. ldapmodify -h <hostname> -D <user dn> -w <password> -rac -f out.ldif
These same instructions can be used to perform modifications to the objects in the directory. Note, if you do not care to put comments in the ".ldif" files you can just make modifications directly in the file produced by the grep command.

An easy way to manage the information residing in the LDAP server is to keep a master LDIF file which represents all the definitions residing in the LDAP server. Any modifications or additions are made directly to this file and the ldapmodify command may be used to apply these changes to the
LDAP server. This also allows the administrator to have a text file backup in the event that the LDAP server needs to be restored.

To make modifications use the following syntax of the ldapmodify command:

ldapmodify -h <hostname> -D <user dn> -w <password> -rc -f out.ldif

Section 5: Configuring the Router to Read Policy Information from LDAP Server

Now that policies actually exist in the LDAP server, you must enable the routers to retrieve their policy information from the LDAP server.  To do this perform the following steps:
  1. Attach to the router using an ascii terminal or a telnet session
  2. At the "*" prompt, type "talk 6" and enter
  3. Proceed to the policy feature by typing "feature policy" and enter
  4. Enter the IP address of the LDAP server which contains the policy information needed by this device
      5. Policy config>SET LDAP PRIMARY-SERVER 11.0.0.1
  5. If the LDAP server requires authentication then set the bind parameters. First enable sending of authentication parameters be issuing the following command:
      6. Policy config>SET LDAP ANONYMOUS-BIND no
      Policy config>SET LDAP BIND-NAME cn=root
      Policy config>SET LDAP BIND-PW password
  6. Configure the distinguished name of the deviceprofile object in the LDAP server for this device.
      7. Policy config>SET LDAP POLICY-BASE cn=deviceProfileForSG1, o=ibm, c=us
  7. Enable retrieving policies from the LDAP server
      8. Policy config>ENABLE LDAP POLICY-SEARCH
  8. List the LDAP parameters and verify they look similar to the following:
      9. Policy config>LIST LDAP
      LDAP CONFIGURATION information:

      Primary Server Address: 11.0.0.1
      Secondary Server Address: 0.0.0.0
      Search timeout value: 3 sec(s)
      Retry interval on search failures: 1 min(s)
      Server TCP port number: 389
      Server Version number: 2
      Bind Information:
      Bind Anonymously: No
      Bind Name: cn=root
      Base DN for this device's policies: cn=deviceProfileForSG1, o=ibm, c=us
      Retrieve policies from LDAP Server Only

Section 6: Resetting the Ldap Configuration and Policy Database

For the changes made above to take affect, the user must either restart/reload the router or go into talk 5 and use the dynamic reconfiguration feature of the router to activate the changes. This procedure is shown in the following steps:
 
  1. Turn on ELS messages for PLCY subsystem in talk 5 (this step is not necessary)
  2. In feature policy (talk 5), reset the ldap configuration
  3. In feature policy (talk 5), reset the policy database
A screen capture showing these steps is below:

*
*TALK 5
+EVENT
Event Logging System user console
ELS>NODISPLAY SUBSYSTEM all all
Complete
ELS>DISPLAY SUBSYSTEM PLCY ERROR
ELS>DISPLAY EVENT PLCY.22
ELS>DISPLAY EVENT PLCY.26
ELS>EXIT
+FEATURE Policy
IP Network Policy console
Policy console>RESET LDAP-CONFIG
LDAP Policy Configuration reset successfully
Policy console>RESET DATABASE
Policy Database reset successful
Policy console>

A sample ELS message output is shown below:
21:09:03 PLCY.022: Found object (DN: cn=policySecure11to12, o=ibm, c=us), parse using class def PolicyRule
21:09:03 PLCY.022: Found object (DN: cn=11to12, o=ibm, c=us), parse using class def TrafficProfile
21:09:03 PLCY.022: Found object (DN: cn=allTheTime, o=ibm, c=us), parse using class def PolicyValidityPeriod
21:09:03 PLCY.022: Found object (DN: cn=secure11to12, o=ibm, c=us), parse using class def IPSecSecurityAction
21:09:03 PLCY.022: Found object (DN: cn=generalPhase1Action, o=ibm, c=us), parse using class def IPSecISAKMPAction
21:09:03 PLCY.022: Found object (DN: cn=strongP2EspProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:03 PLCY.022: Found object (DN: cn=strongP2EspAhProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:03 PLCY.022: Found object (DN: cn=veryStrongP2EspProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:03 PLCY.022: Found object (DN: cn=veryStrongP2EspAhProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:03 PLCY.022: Found object (DN: cn=veryStrongP1PropRSACert, o=ibm, c=us), parse using class def ISAKMPProposal
21:09:03 PLCY.022: Found object (DN: cn=strongP1PropRSACert, o=ibm, c=us), parse using class def ISAKMPProposal
21:09:03 PLCY.022: Found object (DN: cn=veryStrongP1PropSharedKey, o=ibm, c=us), parse using class def ISAKMPProposal
21:09:03 PLCY.022: Found object (DN: cn=strongP1PropSharedKey, o=ibm, c=us), parse using class def ISAKMPProposal
21:09:03 PLCY.022: Found object (DN: cn=espTunnelMD5andDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=espTunnelSHAandDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=espTunnelDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=ahTunnelMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=ahTunnelSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=espTunnelSHAand3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=espTunnelMD5and3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=espTunnel3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=ahTunnelSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=ahTunnelMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:03 PLCY.022: Found object (DN: cn=gatewayToLdapServerPolicy, o=ibm, c=us), parse using class def PolicyRule
21:09:04 PLCY.022: Found object (DN: cn=gatewaysToLDAPServer, o=ibm, c=us), parse using class def TrafficProfile
21:09:04 PLCY.022: Found object (DN: cn=secureLdapServer, o=ibm, c=us), parse using class def IPSecSecurityAction
21:09:04 PLCY.022: Found object (DN: cn=strongP2EspProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=strongP2EspAhProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=veryStrongP2EspProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=veryStrongP2EspAhProp, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=espTunnelMD5andDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTunnelSHAandDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTunnelDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTunnelMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTunnelSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTunnelSHAand3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTunnelMD5and3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTunnel3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTunnelSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTunnelMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=remoteAccessto11, o=ibm, c=us), parse using class def PolicyRule
21:09:04 PLCY.022: Found object (DN: cn=remoteUserto11, o=ibm, c=us), parse using class def TrafficProfile
21:09:04 PLCY.022: Found object (DN: cn=secureRemoteAccessUsersTo11, o=ibm, c=us), parse using class def IPSecSecurityAction
21:09:04 PLCY.022: Found object (DN: cn=strongP2EspPropXport, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=strongP2EspAhPropXport, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=veryStrongP2EspPropXport, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=veryStrongP2EspAhPropXport, o=ibm, c=us), parse using class def IPSecProposal
21:09:04 PLCY.022: Found object (DN: cn=espTransportMD5andDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTransportSHAandDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTransportDES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTransportMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTransportSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTransportSHAand3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTransportMD5and3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=espTransport3DES, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTransportSHA, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=ahTransportMD5, o=ibm, c=us), parse using class def IPSecTransform
21:09:04 PLCY.022: Found object (DN: cn=dropPublicTrafficSG1, o=ibm, c=us), parse using class def PolicyRule
21:09:04 PLCY.022: Found object (DN: cn=inOutPublicSG1, o=ibm, c=us), parse using class def TrafficProfile
21:09:04 PLCY.022: Found object (DN: cn=ipsecDrop, o=ibm, c=us), parse using class def IPSecSecurityAction
21:09:04 PLCY.026: Completed building policy DB, 13 rules loaded

An alternative way to cause the policy database in the router to reload the policies from the LDAP server is to perform an SNMP set.  Please refer to the vpnpolicy.mib file which can be found under the MIB download page (http://www.networking.ibm.com/support/code.nsf/mibscode).  The name of the object in the vpnpolicy MIB to set is the "vpSysRefreshConfig".  It may be useful to build a script which sets this object for each policy enabled router in the network.

Section 7: Resolving Problems Interacting with the LDAP Server

The following steps should be performed to isolate problems interacting with the LDAP server. The example LDAP configuration used in section 5
will be used in this analysis:

LDAP server information:

    Primary Server Address: 11.0.0.1
    Search timeout value: 3 sec(s)
    Server TCP port number: 389
    Server Version number: 2
    Bind Anonymously: No
    Bind Name: cn=root
    Bind Password: password
    Base DN for this device's policies: cn=deviceProfileForSG1,o=ibm,c=us
  1. Can the router ping the LDAP server?
  2. Can I perform a ldapsearch locally on the LDAP server and receive the results I expect. Issue the following command on the same machine the LDAP server is installed on. If this command cannot be issued on the LDAP server itself, try using another host in the network with an LDAP search client installed. The point is to try to isolate the problem to the LDAP server or to the router.
      3.  
      ldapsearch -h 11.0.0.1 -D "cn=root" -w password -b "cn=deviceProfileForSG1,o=ibm,c=us" objectclass=*

      This should return exactly one result. If this step fails then make sure the authentication information is correct and check the error logs on the LDAP server for other information. Also make sure that the LDAP server is listening on port 389 (the default). Resolve this errors before moving on to step 3.

  3. Using the same search criteria and authentication parameters in the step above, verify the equivalent of the ldapsearch command on the router can be successfully completed.  Go to the policy feature in talk 5 (* -> talk 5 -> feature policy) and type search.  You will be prompted for the following information.
      4. -----------------------------------------------------------
      Policy console>SEARCH
      Do you wish to bind to the server anonymously? [No]:
      Enter your bind DN: [cn=root]?
      Enter your bind PW: [password]?
      Enter the base DN for the search:
        [cn=deviceProfileForSG1, o=ibm, c=us]?
      Enter the scope of your search:
      Choices: 1-BASE, 2-SUBTREE, 3-ONELEVEL
      Enter (1-3): [2]?
      Enter the search filter: [objectclass=*]?
      Enter IP address of LDAP server [11.0.0.1]?
      Enter Port Number for LDAP Server: [389]?
      Bind completed, starting search

      dn: cn=deviceProfileForSG1, o=ibm, c=us
      objectclass: deviceprofile
      cn: deviceProfileForSG1
      devicerulesreference: cn=rulesForSG1, o=ibm, c=us
      creatorsname: cn=root
      modifiersname: cn=root
      createtimestamp: 19990524193651Z
      modifytimestamp: 19990524193651Z

      1 results returned from ldap search
      -----------------------------------------------------------

      If no results are returned then make sure that no access controls are turned on preventing you from reaching the LDAP server on port 389.  Also increasing the LDAP search timeout value may help if the LDAP server lies across an extremely slow speed connection or you are experiencing significant congestion in your network. Do not proceed to step 4 until this operation completes.
       

  4. Turn on the policy error ELS messages to make sure that no errors are being encountered during the search operation. These errors could result from time-outs arising from low speed connections or from misconfigured policy objects in the directory. In most instances the exact error that was detected by the policy search agent will be displayed in the ELS output. To turn on the policy ELS messages type the following
      5.  
      * -> talk 5 -> event -> display subsystem plcy error

      In the policy feature in talk 5, type "reset database" and then proceed to the monitoring process (talk 2) and determine which error the policy subsystem is encountering. Resolve the configuration issue in the LDAP directory and repeat step 4 until there are no more errors.
       

  5. In reaching this point the policy engine on the router should be able to read the policies from the LDAP server without any errors. To determine whether this is true, proceed to the feature policy in talk 5 and type "status". The output should display that the last refresh was successful.  If you are still experiencing problem, please gather the following information and contact router support: