ReadFromDirectory statement

Use the ReadFromDirectory statement to initialize Policy Agent as an LDAP client. The policies are downloaded from the LDAP server, along with the policies specified in this Policy Agent configuration file (the current one being used by Policy Agent that contains this statement). All the policies are installed to the appropriate TCP images.

You can use a set of sample files to help set up the LDAP server and populate it with policies. These files reside in the /usr/lpp/tcpip/samples directory.

One set of sample files defines the schema object classes and attributes for LDAP protocol version 3 servers. These files are:

pagent_r8qosschema.ldif
pagent_r5idsschema.ldif

Requirement: These files must be installed on the LDAP server as a subschema of the cn=schema object by using the command.

See the prologs in these sample files and z/OS Communications Server: IP Configuration Guide for more information.

The remaining sample files are examples of policy objects that can be installed on an LDAP server after the schema has been defined using this schema definition files. These files are:

pagent.ldif contains a top level structure of policy objects.
pagent_starter_IDS.ldif contains a starter set of IDS policies.
pagent_starter_QoS.ldif contains a starter set of QoS policies.
pagent_advanced_IDS.ldif contains an advanced set of IDS policies.
pagent_advanced_QoS.ldif contains an advanced set of QoS policies.

See the prologs in these sample files and z/OS Communications Server: IP Configuration Guide for more information.

Tip: These policies are not intended to be used as shipped, but they can be copied to a custom set (defined in pagent.ldif) and modified as needed.

For more information about how to use LDAP and for other LDAP references, see Understanding LDAP (SG24–4986).

Syntax


>>-ReadFromDirectory--| Place Braces and Parameters on Separate Lines |-><

Place Braces and Parameters on Separate Lines

|--+-{--------------------------------+-------------------------|
   +-| ReadFromDirectory Parameters |-+   
   '-}--------------------------------'   

ReadFromDirectory Parameters

   .-LDAP_Server --127.0.0.1-.  .-LDAP_Port --389--.   
|--+-------------------------+--+------------------+------------>
   '-LDAP_Server --address---'  '-LDAP_Port --port-'   

>--+-----------------------------+------------------------------>
   '-LDAP_BackupServer --address-'   

   .-LDAP_BackupPort --389--.   
>--+------------------------+----------------------------------->
   '-LDAP_BackupPort --port-'   

>--+---------------------------------------------------------+-->
   '-LDAP_DistinguishedName --string--LDAP_Password --string-'   

   .-LDAP_SessionPersistent --No-----.   
>--+---------------------------------+-------------------------->
   '-LDAP_SessionPersistent--+-Yes-+-'   
                             '-No--'     

   .-LDAP_ProtocolVersion --3----.   
>--+-----------------------------+------------------------------>
   '-LDAP_ProtocolVersion----3---'   

   .-LDAP_SchemaVersion --3----.                      
>--+---------------------------+--+---------------+------------->
   '-LDAP_SchemaVersion--+-1-+-'  '-Base --string-'   
                         +-2-+                        
                         '-3-'                        

>--+---------------------------+-------------------------------->
   '-LDAP_SelectedTag --string-'   

>--+-----------------------------+------------------------------>
   '-SearchPolicyBaseDN --string-'   

>--+-----------------------------------+------------------------>
   | .-------------------------------. |   
   | V                               | |   
   '---SearchPolicyKeyword --keyword-+-'   

>--+-----------------------+------------------------------------>
   | .-------------------. |   
   | V                   | |   
   '---PolicyRole --role-+-'   

>--+---------------------------------------+-------------------->
   | .-----------------------------------. |   
   | V                                   | |   
   '---SearchPolicyGroupKeyWord --string-+-'   

>--+--------------------------------------+--------------------->
   | .----------------------------------. |   
   | V                                  | |   
   '---SearchPolicyRuleKeyWord --string-+-'   

   .-LDAP_AbstractPolicy --Yes----.   
>--+------------------------------+----------------------------->
   |                      .-Yes-. |   
   '-LDAP_AbstractPolicy--+-No--+-'   

>--LDAP_SSL--| Place Braces and Parameters on Separate Lines |--|

Place Braces and Parameters on Separate Lines

|--+-{-----------------------+----------------------------------|
   +-| LDAP_SSL Parameters |-+   
   '-}-----------------------'   

LDAP_SSL Parameters

|--LDAP_SSLKeyringFile --filename------------------------------->

>--+------------------------------------+----------------------->
   '-LDAP_SSLKeyringPassword --password-'   

>--+-----------------------+------------------------------------|
   '-LDAP_SSLName --string-'

Parameters

LDAP_Server

The name of the server that contains policy definitions. The name can be specified as a character string (for example, 'ldapserver.mynetwork.com') or as an IPv4 address (for example, 9.11.12.13). The default is the LDAP server in the local host (127.0.0.1).

LDAP_Port

The port on which the directory server is running. If not specified, the default, well-known LDAP port of 389, is used.

LDAP_BackupServer

This attribute specifies the name or IPv4 address of the backup LDAP server for which the search is performed if the Policy Agent cannot connect to the LDAP server as specified in the LDAP_Server and LDAP_Port parameters. The default is no backup server.

LDAP_BackupPort

This attribute specifies the port number on which the backup LDAP server is running. The default is the well-known LDAP port 389.

LDAP_DistinguishedName

This attribute is a character string value that specifies the distinguished name for user ID to connect to the LDAP server. If this attribute is not specified, anonymous user ID is used for the connect. If this attribute is specified, LDAP_Password must also be specified.

Restriction: Case sensitivity of this attribute is determined by the LDAP server.

LDAP_Password

The password of the connection to the LDAP server. If this attribute is specified, LDAP_DistinguishedName must also be specified.

LDAP_SessionPersistent

A string that specifies whether the LDAP session with the directory server should be kept open or closed during an update interval time. If this value is not specified, the session is closed after every query from the directory server. Valid values are yes or no. If the LDAP session update interval is small, the value of keeping the session open is greater, because it reduces the overhead of opening the session for each query.

LDAP_ProtocolVersion

This attribute indicates to Policy Agent what version of the LDAP protocol to use. The default value is 3.

LDAP_SchemaVersion

This attribute indicates to Policy Agent what version of the schemas to retrieve from LDAP. The value can be 1, 2, or 3. The value should be selected based on your LDAP configuration. The default value is 3. End of change

Base

The distinguished name of the subtree in the directory containing the policies.

Requirement: This is required when using schema Version 1 only.

LDAP_SelectedTag

A string used to select a subset of the policies under the base tree. If not specified, the first machine name returned by gethostname is used.

Restriction: This is allowed only when using schema Version 1.

SearchPolicyBaseDN

This attribute is a character string value (a base distinguished name) that is used as a key to search the LDAP server for policies. It is considered as the initial subtree/group/object to start the search.

Requirement: This attribute is only allowed, and is required, if LDAP_SchemaVersion 2 or higher is specified.

Guideline: Case-sensitivity of this attribute is determined by the LDAP server.

SearchPolicyKeyword

This attribute specifies a generic search keyword to match against all policy objects. Use this attribute to filter the policy objects to be retrieved.

Restriction: This attribute is valid only with LDAP_SchemaVersion 3.

You can specify up to eight instances of this attribute. Specify either a single keyword delimited by blanks or any string containing blanks or other special characters, contained in double quotation marks. For example:

SearchPolicyKeyword     singleword
SearchPolicyKeyword     "quoted string"

SearchPolicyGroupKeyWord

This attribute is a character string value used to scope the search for all group objects.

Restrictions:

Only policy groups that have a matching PolicyGroupKeywords attribute are returned in the initial search.
This attribute is allowed only if LDAP_SchemaVersion 2 or higher is specified.

This is similar to the LDAPSelectedTag attribute that is used with LDAP_SchemaVersion 1.

Guidelines:

Up to eight instances of this attribute are allowed.
Case-sensitivity of this attribute is determined by the LDAP server.

SearchPolicyRuleKeyWord

This attribute is a character string value that allows users to limit the scope of the policyRule search.

Restrictions:

Only policy rules that have a matching policyRuleKeywords attribute are returned in the initial search.
This attribute is allowed only if LDAP_SchemaVersion 2 or higher is specified.

This attribute can also be used when there is no group association in the LDAP server (for example, there is no group hierarchy defined, only rule objects exist) for the policyRule objects.

Guidelines:

Up to eight instances of this attribute are allowed.
Case-sensitivity of this attribute is determined by the LDAP server.

PolicyRole

Specifies a policy role or role-combination. Use this parameter to filter the policy rules to be retrieved.

Restriction: This parameter is valid only with LDAP_SchemaVersion 3.

Guidelines:

This parameter can be repeated as many times as necessary.
Either a single role or a set of roles, known as a role-combination, can be specified.
The roles can be single words, or any strings containing blanks or other special characters, contained in double quotation marks.

Role-combinations are specified as follows. The first role is specified the same way that a single role is specified. Each additional role in the role-combination is prefixed with the characters &&. For example:

PolicyRole     role1 
PolicyRole     &&"quoted role 2"
PolicyRole     "quoted role 3"
PolicyRole     role4

Use this parameter to filter out policy rules that do not contain any of the specified roles or role-combinations, using the attribute ibm-policyRoles. For example, the set of roles specified in this example result in the retrieval of any policy rules that specify "role1&&quoted rule 2" or "quoted role3" or "role4" in their ibm-policyRoles values.

LDAP_AbstractPolicy

Specifies whether or not the Policy Agent should search the LDAP server using a search filter that only selects policy object classes. Valid values are YES or NO, and YES is the default. If the LDAP server supports matching of auxiliary classes for the objectClass attribute, specify YES. Otherwise, specify NO. This attribute is valid only with LDAP_SchemaVersion 3 and LDAP protocol version 3.

LDAP_SSL

Indicates that additional SSL parameters follow.

LDAP_SSLKeyringFile

LDAP_SSLKeyringFile is the name of the key ring file created by gskkyman. It usually contains the certificates of the trusted (by the client) Certificate Authorities. It can also contain a public key and the associated certificate.

Restriction: This is only needed when client authentication is required.

This attribute is required when LDAP_SSL is specified.

LDAP_SSLKeyringPassword

LDAP_SSLKeyringPassword is the password which protects the key ring file. It is set when the key ring file is created with the gskkyman tool.

LDAP_SSLName

LDAP_SSLName is a case-sensitive value that specifies the label assigned when creating a private key/certificate pair with gskkyman. This is used when the client is authenticated.

Restriction: Some servers do not support client authentication; therefore, this parameter is not used.

Examples

The following is a Version 1 schema example:

ReadFromDirectory
        {
             Ldap_server     ldapserver.mynetwork.com
             Ldap_port       9000
             Base            o=ibm,c=us
             Ldap_selectedtag      MVS1
        }

The following is a Version 2 schema example:

ReadFromDirectory 
        { 
             LDAP_Server 9.11.12.13 
             LDAP_Port 9000 
             LDAP_SessionPersistent Yes 
             LDAP_BackupServer 9.11.22.23 
             LDAP_BackupPort 555 
             LDAP_DistinguishedName cn=root, o=IBM, c=US 
             LDAP_Password secret
             LDAP_SchemaVersion 2 
             LDAP_ProtocolVersion 3 
             SearchPolicyBaseDN o=ibm, c=us
             SearchPolicyGroupKeyword MVSA
             SearchPolicyRuleKeyword cherryPicker
             SearchPolicyRuleKeyword ripe
        }

The following is a Version 3 schema example:

ReadFromDirectory 
        { 
             LDAP_Server ldapv3server
             LDAP_BackupServer 10.100.1.5 
             LDAP_BackupPort 7500 
             LDAP_DistinguishedName cn=root, o=IBM, c=US 
             LDAP_Password secret
             LDAP_SchemaVersion 3 
             LDAP_ProtocolVersion 3
             LDAP_AbstractPolicy Yes 
             SearchPolicyBaseDN cn=policy, o=ibm, c=us
             SearchPolicyKeyword QoS
             SearchPolicyKeyword Diffserv
       }