| Previous Contents Index Next |
| iPlanet Directory Access Router Administrator's Guide |
Chapter 13 Configuration Generation Tool
iPlanet Directory Access Router (iDAR) configuration generation tool is described in this chapter, in the following sections:
Introduction
Introduction
iDAR's operation requires the creation of two independent sets of configuration information. The main iDAR configuration is large and can be unwieldy (in contrast to the startup configuration), and can be enumerated within a text file or it can be stored in an LDAP server. The advantage of storing the main configuration in an LDAP server is that it allows central administration of distributed set of iDAR deployments.The startup configuration file possesses only the information necessary for iDAR to find the main configuration. Unlike the main configuration, which could be in an LDAP server, the startup configuration must be a text file on a file system accessible by the machine hosting the iDAR process.
Configuration Assistance
To simplify the generation of these two configuration files, iDAR is packaged with a command-line tool, tailor, that will generate working configuration files from a minimal set of user supplied parameters. The tool has been created to ease the chore of expressing the relation between iDAR, its clients, and its LDAP servers. However, the tool does not attempt to support some of iDAR's more complex configuration subtleties such as attribute renaming, subtree hiding, etc. Complex configuration such as those are best accomplished by using the tool as the starting point and then completing the tailoring process via iDAR's console-based administration facilities.
Configuration Tool's Parameters
The configuration tool tailor assumes it is being run on the environment that will host the iDAR that's being configured.The tool has the following syntax:
The parameters follow a fixed pattern: a hyphenated key word/option followed by one or more values to associate with the option.
Tailor Options
The following recognized options are grouped by subject:
- The -ldif option informs the configuration tool where to store the textual representation of the subsequently generated configuration file. The resulting text file can either be loaded directly by iDAR or imported into an LDAP server with certain provisos (i.e., the suffix is acceptable to the server and the server has supporting iDAR attributes and class configuration information).
- The supplied outFile should be stipulated as a complete and absolute path to the destination file. An absolute path is required. The configuration tool will verify that you have sufficient permissions to create or replace the given file.
- If this option is omitted, the tool will name the output file tailor.ldif and place it in the etc subdirectory subordinate to the installation's instance directory. No attempt is made by the tool to import the resulting configuration into an LDAP environment. That step requires end user manual intervention.
-bind_pw password
-bind_dn dn
-url [ldap://]host[:port]
- These options are used in the case where iDAR is to retrieve its main configuration from an LDAP server. The -bind_dn, -bind_pw, and -url options are recorded into iDAR's startup configuration where they'll be used by iDAR when it contacts the configuration's host server.
Note All three of these options are required if any one of them is stipulated.
- This option instructs the tool where to place iDAR's startup configuration file.
- Corollary to the -ldif option, the outFile option supplied here should also be a complete and absolute path to the destination file. Again, an absolute path is required. The configuration tool will verify that you have sufficient permissions to create or replace the given file.
- If this option is omitted, the tool will name the output file tailor.txt and place it in the etc subdirectory subordinate to the installation's instance directory.
- This option provides the facility to dictate which TCP port number on which iDAR will listen for new connections. This option sets the value stipulated for ids-proxy-con-listen-port enumerated for the ids-proxy-sch-GlobalConfiguration objectclass entry.
- The tool assumes a value of 389 for this option when it is not stipulated.
-onbind [[ldap://]host[:port] [name] [secureport]]]
-server [ldap://]host[:port] [name] [secureport]]
- The -server option is used to enumerate the hosts that iDAR can contact; thus more than one -server could be specified. The optional name and secureport values are used to associate a name to the given host and to indicate which TCP port (if any) the host expects secured connections. Those two optional values may be stipulated in any order. In addition, either or both the name and the secureport directives may be omitted. The name given will be used to form part of the distinguished name in the properties section of the resulting configuration; thus, care should be exercised to avoid duplicating names. Note: the tool generates a default name in the case where one isn't given. Those default names begin with "server-" and are appended with a sequentially generated number to avoid duplication.
- If the tool is given more than one -server option, the tool will emit a configuration that reflects load balancing directives. Note: iDAR assumes that a set of servers that are being load balanced are of equal content and of equal functionality. If the configuration tool isn't presented a -server option, it will act as if -server ldap://localhost:389 has been stipulated.
- The -onbind directive informs the configuration tool that it is to establish two distinct groups within the configuration: one group for anonymous binds and another for non-anonymous binds. The -onbind option's syntax is similar to -server's syntax with the notable exception that it does not require the specification of a host name. If the host name is omitted, then -onbind will assume that the set of hosts to contact on successful bind is the same set as stipulated by the -server option(s). The key to recognize here is that connections that fall within -onbind's purgative will still contact the same machines but the connections will have an expanded set of available operations. To the contrary, stipulating one or more -onbind hosts removes the possibility of supporting the rebinding of a SASL connection.
- If you use -onbind to enumerate more than one host, then the configuration tool will set up additional properties to accommodate load balancing across the set of -onbind hosts.
-ssl_cert file
-ssl_key file
-ssl_version number
-ldaps port
- These options enable iDAR to support encrypted connections from its clients. These options do not affect iDAR's ability to encrypt connections between itself and its corresponding servers. The -ssl_cert parameter specifies the absolute path to the file that possess the certificate that iDAR should employ. The -ssl_key option identifies the file that possesses the key iDAR should use in conjunction with the given certificate. These options map their values to the ids-proxy-sch-GlobalConfiguration objectclass' ids-proxy-con-ssl-key and ids-proxy-con-ssl-cert attributes.
- If both -ssl_key and -ssl_cert are specified then the tool will also allow the specification of -ssl_version and/or -ldaps.
- The -ssl_version must be one of the following values: 20, 23, 30, or 31. A value of 20 configures iDAR for SSL version 2 only, 30 selects SSL version 3 only, 23 permits either SSL version 2 or version 3 connections and 31 stipulates TLS version 1 only. This option maps its value to the ids-proxy-sch-GlobalConfiguration objectclass' ids-proxy-con-ssl-version attribute.
- Setting a value for -ldaps instructs iDAR to listen on the given TCP port (in addition to the TCP port specified by the -listen directive) with the subtle difference being that only encrypted connections will be accepted on the -ldaps specified TCP port. This option maps its value to the ids-proxy-sch-GlobalConfiguration objectclass' ids-proxy-con-ldaps-port attribute.
- The tool will append the given suffix to all of the distinguished names used internally within the generated configuration. This option adds value to the resulting configuration if and only if the intent is to store the configuration in an LDAP server. Otherwise, the suffix just serves to clutter the distinguished names. The tool does assume that the given suffix already exists in the destined LDAP server.
- If your production deployment model calls for iDAR to keep its configuration in an LDAP server and you are employing schema checking, then you will probably need to supplement the configuration's entries with one or more objectclasses. By default, the configuration tool will tag each entry it creates with an objectclass of ids-proxy-top, but by stipulating this option (one or more times), you can specify the objectclass(es) to use instead.
-remember outFile
-recall file
- The -remember and -recall options provide a mechanism to support the recording of the command-line parameters and their subsequent reuse. The -remember and -recall directives can be used simultaneously or independently of each other. When used together, the given file names may or may not be the same depending if you wish to overlay the given input (same names) or evolve the input (different names). The -remember and -recall options can be used in conjunction with any other options as the tool merely merges the current command line with the recalled values.
Configuration Examples
First, let's define the pseudo environment we have at our disposal.Because bitter.iplanet.com is declared as supporting encryption, then the iDAR stationed at bitter.iplanet.com will support "Start TLS" operations over its non-secured port as well.
Let's further assume that DNS can resolve the aforementioned machines merely by their hostname, i.e., red, blue, green, etc. And the last assumption: the subsequent examples assume that the tool is being run from a UNIX environment.
Given these assumptions, we can now show you how the example configurations shown in Appendix A "Sample Configuration Files" were generated.
The tool is capable of generating four different classes of configurations: straight through, load balancing, binding based operation filtering, and load balancing with binding based operation filtering.
Straight Through Configuration
In the straight through configuration, iDAR is not adding much value to the overall process; rather, it is just relaying the information from its clients to a server. The general expectation is that the straight through configuration would not have much application in a production deployment but it does have value when it comes to building confidence that your iDAR is inter-operating with your clients and your LDAP server. In this particular case, the command-line tool is given information regarding only which TCP port number the iDAR process should listen on and what single server should iDAR contact.tailor -listen 389 -server ldap://pink.iplanet.com:10205
This will yield the first example configuration file found in Code Example A-1. The output files were named <server-root>/idar-<hostname>/etc/tailor.txt and <server-root>/idar-<hostname>/etc/tailor.ldif as we didn't supply the -startup and -ldif options.
Load Balancing Configuration
This scenario expands upon the straight through configuration via the stipulation of more than one server to contact. The configuration tool will emit directives specifying that the given set of servers is to divide the connection load among themselves.tailor -server pink:10205 -server red:10389 -server blue
Here the tool generates a configuration where pink.iplanet.com will receive 34 percent, red.iplanet.com receives 33 percent and blue.iplant.com receives 33 percent of the connections. The tool will apportion the set of servers equally based on the cardinality of the set stipulated. To provide 100 percent coverage, any remaining percentage is added to the first enumerated server.
Again you'll find the resulting configuration files as one of the examples in Appendix A "Sample Configuration Files."
Binding Based Operation Filtering
Upon examination of the generated configuration files from the previous scenarios, you'll note that the configuration tool generated only one group. (Note: all connections through iDAR resolve to a group through which permissions, actions, and rules are derived.) In this scenario, the tool will generate two groups: one that is employed when a connection utilizes a non-anonymous bind and another group that acts as a catch-all.The idea behind these two groups is to extend permissions to non-anonymous binding connections and to restrict the permissions to anonymous binding connections; specifically, anonymous clients will be given search capabilities only.
Load Balancing and Binding Based Operation Filtering
Creating a configuration that capitalizes on these two types of functions merely requires combining their parameter lists.tailor -server pink:10205 -server red:10389 -server blue -onbind
The emitted configuration will instruct iDAR to load balance over the pink, red, and blue servers and anonymous binding connections will possess search privileges only.
See Appendix A for a listing of the resulting configuration file.
Startup Configuration File
The tailor.txt file contains the bootstrap information iDAR needs to locate its main configuration. The directives in this file dictate if iDAR will utilize an additional file for its main configuration or if iDAR will solicit its main configuration from an LDAP server. By default, iDAR expects to find the startup configuration file, tailor.txt, in the etc subdirectory of the installation's instance directory. Note: via the use of the command-line parameter -t, iDAR can be instructed to use an alternate file as its startup configuration file.As an aid in supporting high availability configurations, a startup configuration file may list several contact points for the main configuration's retrieval. Contact points are delineated within the startup configuration file by the use of two keywords: Begin and End. iDAR will process the contact information one by one in the order given. iDAR's actions on each contact point depends on the type of the given contact point (either an LDAP URL or an absolute path name to a file).
For LDAP-URL-based contact points, iDAR will attempt to contact the given host. If the host is unwilling or unable to return a configuration, then iDAR will proceed to its next contact point (if any). If the host returns a configuration, then iDAR will edit the contents returned and will then either begin following the main configuration's directives or end its execution if the configuration was deemed invalid.
For file based contact points, iDAR will attempt to load the given file as its main configuration. If the specified configuration is missing or is deemed invalid, iDAR will end its execution. iDAR will not attempt to move to the next contact point once it encounters a file based contact point.
In the case where iDAR is retrieving its main configuration from an LDAP host, iDAR can bind to the host using one of three methods: anonymous, simple, or by using SASL.
Anonymous binding is accomplished by omitting the configuration_bind_pw and configuration_bind_dn directives. In other words, your startup configuration's contact information would specify a configuration_url directive and nothing else.
Simple binding is supported through the use of both the configuration_bind_pw and the configuration_bind_dn directives.
SASL binding requires the specification of the sasl_bind_mechanism, conguration_bind_pw and one (and only one) of the following directives: either configuration_bind_dn or configuration_username.
Startup Configuration's Keywords
Each enumerated contact point uses the keyword Begin to signify the start of a contact point entry. Conversely, each contact point entry is terminated by the keyword End. Every directive stipulated in a startup configuration file is expressed on a line by itself. Line continuation within the startup configuration is not recognized nor supported. The configuration's options are specified via an option, followed by a colon, and a value triplet.
configuration_url
The configuration_url option specifies either an LDAP directory server and the distinguished name of the entry in that directory where the iDAR configuration is stored, or a local file in LDIF format. For example, if the iDAR configuration is stored in an LDAP directory on host ldap.iplanet.com with the LDAP service running on port 389 and the distinguished name of the iDAR entry is "ids-proxy-con-Server-Name=iDAR", then the following should be added to the configuration file:Begin
configuration_url:
ldap://ldap.iplanet.com:389/ids-proxy-con-Server-Name=iDAR
EndIf the configuration is to be kept in an LDAP server, you would probably need to specify a suffix following the ids-proxy-con-Server-Name=iDAR in order to maintain compatibility with the host directory's naming context. For example:
Begin
configuration_url:
ldap://ldap.iplanet.com:389/ids-proxy-con-Server-Name=iDAR,
ou=services, dc=iPlanet, dc=com
EndEach startup configuration directive should be specified as one contiguous line within the configuration file.
Note Do not interpret the line wrapping in the configuration_url examples as an instruction to insert a line break into your configuration file.
In the case where the configuration is stored in a LDIF formatted file, i.e., <server-root>/idar-<hostname>/etc/tailor.ldif, the following should be added to the configuration file:
Begin
configuration_url:
file://<server-root>/idar-<hostname>/etc/tailor.ldif#ids-proxy-con- Server-Name=iDAR
End
configuration_bind_dn
The configuration_bind_dn option specifies the distinguished name to use when iDAR binds to the LDAP server specified in the configuration_url option. If this option is not specified, and an LDAP directory is specified as the value of the configuration_url option, then iDAR binds anonymously to the directory. If it is specified, iDAR will perform a simple bind with this distinguished name and the value of configuration_bind_pw as the password. For example:Begin
configuration_url:
ldap://ldap.iplanet.com:389/ids-proxy-con-Server-Name=iDAR
configuration_bind_dn: cn=Directory Manager
configuration_bind_pw: secret
EndThe configuration_bind_dn option is not needed and ignored if configuration_url is of the "file" form. Note: the configuration_bind_dn and configuration_username directives are mutually exclusive.
configuration_bind_pw
The configuration_bind_pw option is used to specify the password to use when binding to the LDAP directory. The directive is used to specify the password to use for either simple or SASL based binding. In order to preserve security, the configuration file must be protected against unauthorized reading. The configuration_bind_pw option is not needed and ignored if configuration_url is of the "file" form. (See configuration_bind_dn for an example.)
configuration_username
The configuration_username option specifies the username to use when iDAR binds to the LDAP server specified in the configuration_url option. This option is used only if SASL bind mechanism is used. Note: the configuration_bind_dn and configuration_username directives are mutually exclusive.Begin
configuration_url:
ldap://ldap.iplanet.com:389/ids-proxy-con-Server-Name=iDAR
configuration_username: administrator
configuration_bind_pw: secret
sasl_bind_mechanism: CRAM-MD5
End
sasl_bind_mechanism
The sasl_bind_mechanism option can be set to either CRAM-MD5 or DIGEST-MD5 depending on which SASL bind mechanism you want iDAR to use. iDAR will perform either a simple bind or an anonymous bind if this option is absent. DIGEST-MD5 provides a higher level of security than CRAM-MD5 but DIGEST-MD5 has not been as widely adopted as CRAM-MD5.
Previous Contents Index Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated July 26, 2001