iPlanet Directory Access Router Service Pack 1
Release Notes
Updated May 17, 2002
These
release notes contain important information about
iPlanet Directory Access Router Service Pack 1. New
features and enhancements, installation notes, known problems, and other
late-breaking issues are addressed here. Read this document before you
begin using iPlanet Directory Access Router (DAR).
These
release notes contain the following sections:
What's New in Directory
Access Router, Version 5.0 SP1
This release
of DAR includes the following changes (when compared to DAR, version 2.1):
-
The supported platforms list
has changed; check the DAR Installation Guide for details.
-
Java based GUI consoles, called
the DAR Server Console and DAR Configuration Editor Console, to aid in
the configuration of DAR. It is recommended that you use the DAR consoles
to configure and maintain new installations of DAR.
-
Several performance improvements
and bug fixes; see section Resolved Bugs.
DAR Documentation
The complete
set of DAR documentation for this release includes the following:
-
iPlanet Directory Access Router
Release Notes (this document) -- The release notes contain information
on new features of this release, software/ hardware requirements for installing
the product, important notes and known bugs, last-minute product information,
and how to send feedback.
-
iPlanet Directory Access Router
Installation Guide -- This document describes how to plan for and install
DAR. Read this document next, after you have read these release notes.
Both HTML and PDF versions of this document are provided.
-
iPlanet Directory Access Router
Administrator's Guide -- This document provides detailed information on
configuring and maintaining DAR. Both HTML and PDF versions of this document
are provided.
-
iPlanet Directory Access Router
Frequently Asked Questions -- This document contains answers to frequently
asked questions, clarifications on DAR features, and troubleshooting information.
Both HTML and PDF versions of this document are provided. Note that the
same document is included as an appendix in the DAR Administrator's Guide.
After you
run the setup script as described in the installation instructions, check
this file for a list of documentation installed with the product: <server-root>/manual/en/idar/index.htm,
where <server-root> is your DAR installation directory. For the release
notes, check this directory: <server-root>/bin/idar.
For the
latest information about DAR, including current release notes, technical
notes, and deployment information, check this web site:
http://docs.iplanet.com/docs/manuals/dar.html
Installation Notes
Note the
following:
-
Software and hardware requirements
and installation instructions are documented in the DAR Installation Guide.
-
If you have an existing installation
of DAR, before installing this version of DAR, save any configuration files
in the file system to a place outside of the DAR install directory. Then
uninstall the existing DAR unless your intent is to install DAR's patch.
-
After installing DAR on a Windows
NT system, make sure to reboot the system; you can do this from the Start
menu.
Important Notes
This section
contains important notes about the following:
Migrating Configuration From
DAR 2.1 To DAR 5.0
If you have
an existing installation of DAR 2.1, a tool has been provided to assist
in the conversion of DAR 2.1 configuration into one recognized by the DAR
5.0 console-based configuration. Using the configuration tool, you can
import existing DAR 2.1 configuration objects from an LDIF file into an
instance of iPlanet Directory Server functioning as the configuration directory.
This tool is useful for porting existing DAR installations to this version
of DAR 5.0, which uses the iPlanet Console.
You can
find the configuration tool in the following directory:
<server-root>/bin/idar/admin/script
Note that
configuration objects are expected to appear in a known location in the
directory (currently ou=dar-config, o=netscaperoot) and conform to a predefined
structure. The tool is invoked as follows:
-
ImportConfigurationLdif <options>
ldif where, ldif is a required directive indicating where the tool is to
find the LDIF file containing DAR configuration objects and options can
be substituted with the following:
-
-C <configuration
name> The name of
configuration to create/augment. Defaults to "imported-configuration".
-
-h
<host> The hostname
of the configuration directory. If omitted, the utility assumes "localhost".
-
-p <port
number> The port number
of the configuration directory. If omitted, the utility assumes 389.
-
-D <bind
dn> The bind DN of
the Directory user. If omitted, the utility will bind anonymously, but
you may not be able to make updates.
-
-w <password>
The password of the Directory user.
For example,
the following command imports objects from the specified LDIF file, sample.ldif:
ImportConfigurationLdif
-D uid=admin,ou=Administrators,ou=TopologyManagement, o=netscaperoot -w
admin sample.ldif
Configuring DAR For SSL/Certificates
Chapter 5,
"Configuring System Parameters" and Chapter 12, "Configuring Security"
of the DAR Administrator's Guide document how to set up DAR for SSL-enabled
communication. Here are a few additional notes that you should take into
consideration when setting up DAR for SSL-enabled communication:
-
If DAR is configured to verify
client certificates (see Step 4 of "Steps to Configure TLS/SSL Support")
the client cannot use SASL EXTERNAL to authenticate based on the subject
DN of the client certificate. Instead, the client will have to use simple
BIND, CRAM-MD5, or DIGEST-MD5, unless an anonymous BIND is sufficient.
-
While it is possible to configure
DAR to present its certificate to a directory server, the clients of DAR
will still have to perform simple BINDs in order to present valid credentials
over the SSL connection between DAR and the directory server. The point
is that simply validating DAR to the directory server does not implicitly
authenticate the DAR client to the directory. DAR does not use the proxy
authentication control.
-
When using certificates, make
sure that the appropriate root certificates are known to the appropriate
entities: to DAR, to the directory servers, and to the LDAP clients. If
any of these entities can't verify the root certificate path while validating
a certificate, then it fails to communicate with the entity that presented
the certificate.
On iPlanet
Directory Server (versions 4.11 and later), use the Certificate Setup Wizard,
which can be launched from within the console, to import any necessary
CA certificates. You might also have to make the appropriate changes to
the certmap.conf file. For more information on setting up the Directory
Server, check the Directory Server documentation at: http://docs.iplanet.com/docs/manuals/directory.html
In DAR,
the file <server-root>/idar-<hostname>/etc/rootcerts.pem
contains a list of root certificates in the PEM format. This list includes
most of the common root CA certificates, but certificates such as "Thawte
TEST CA" will have to be added as needed.
Note that
there can be up to three certificate paths involved, each with potentially
different root certificates: the certificate list which DAR presents to
the LDAP client and to the directory server; the certificate list which
the client presents to DAR; and the certificate list which the directory
server presents to DAR. DAR 5.0 currently does not support having different
certificate lists for communication to clients from that which it uses
to authenticate to the directory server.
-
If you configure iPlanet Directory
Server (versions 4.11 or later) to require client authentication (this
option is under the Encryption tab in the console), then you must also
set the ids-proxy-con-send-cert-as-client
attribute to TRUE in the DAR configuration.
-
iPlanet Directory Server 4.11
only supports RSA certificates. If you are going to configure Directory
Server to require client authentication, you must ensure that the DAR certificate
has an RSA public key and an RSA signature. This consideration is relevant
when using a DSA certificate for DAR to be used with non-RSA clients over
SSL or TLS.
Generating Core Files
On platforms
other than Windows NT, DAR cannot generate core files if the attribute
ids-proxy-con-userid
in the ids-proxy-sch-GlobalConfiguration
object class is set to something other than the user that started the DAR
process. If you want DAR to generate a core file in case it fails unexpectedly,
set the above mentioned attribute to the same user that starts the DAR
process.
Using the Support Tool
A utility
has been provided that allows you to retrieve the DAR configuration from
a directory and store it in a file in the LDIF format. This file can then
be sent to product support for help with configuration problems or you
can tell DAR to use this file to configure itself on startup. (Check the
DAR Administrator's Guide for information related to the tailor.txt
file.) You can find the utility in the following directory:
<server-root>/bin/idar/server/scripts/
The utility
takes the following options. Both options are required.
-
-t <tailor
filename> Where <tailor
filename> is the path
to the startup configuration file on disk.
-
-o <output
file> Where <output
file> is the path
of file where you want the configuration to be stored.
For example,
the following command will read the tailor.txt
file, retrieve the configuration from the location specified in the tailor.txt
file, and save the configuration in the
tailor.ldif file. (This
example assumes the current working directory is an DAR instance directory
and the iDARPrintConfig
command's location is in the environment "PATH".)
iDARPrintConfig
-t tailor.txt -o tailor.ldif
Note that
the command does not actually print anything. It downloads the configuration
for further consideration.
Known Problems and
Limitations
This section
lists known problems and provides work a rounds for some of the problems
that you may encounter with the product. Numbers enclosed within square
brackets, for example, [548588], are bug numbers. Bug numbers are useful
when discussing issues with Technical Support or Professional Services.
Installation
-
DAR installation assumes that
you are always installing DAR on a server root that already has an instance
of iPlanet Administration Server installed or you are installing it in
conjunction with an Administration Server.
-
Only one instance of DAR can
be installed on a given host. [548588]
-
The DAR console installation
does not handle server root paths that possess "special" characters that
are key word characters in TCL. For example, [ ] characters instruct TCL
to perform a command. Thus, if the server root path possesses [ ] within
it, it would cause certain parts of the installation to act improperly.
The characters that should be avoided are as follows: ? " ' [ ] ( ) # .
~ $ ^ * +
-
iPlanet Administration Server
Console refuses to start if the <server-root>
possesses an embedded space. Thus, it is recommended that you do not install
using a <server-root>
with an embedded space. [543176]
-
iPlanet Administration Server
that ships with DAR cannot be installed on the same server root as an iPlanet
Web Server 6.0 installation. This implies iPlanet Directory Server 5.1
server roots should be avoided as the iPlanet Directory Server 5.1 uses
iPlanet Web Server 6.0 for its Administration Server.
-
The DAR Installation Guide describes
how to disable ports other than TCP 389 on Windows NT using the TCP/IP
Properties on the Network Control Panel. Please be aware that disabling
UDP may prevent DNS lookups from occurring properly. If your configuration
makes use of domain names which DAR must resolve using DNS, you should
allow UDP as well as the TCP port for LDAP.
-
On Windows, the installation
routine is not capable of sensing that the user has told DAR to listen
on the same port number as the iPlanet Administration Server. Thus, be
sure to use a unique port to avoid complications. [541046]
-
If you uninstall DAR and plan
to reinstall it on the same machine, make sure to follow either of the
procedures listed below. Failure to do so may cause DAR to fail to start
or to not function properly. [548593] Before installation, delete the configuration
associated with the machine name on which you are installing DAR. (You
can delete the configuration either via the console or in the configuration
directory itself.) After installation, open the DAR Server Console, go
to the Configuration tab, enable the Save button by choosing configuration
object <NONE>,
select the configuration associated with the machine name, and click Save.
Miscellaneous
-
DAR supports a maximum of 32
back end directory servers across any single group.
-
While processing a referral,
DAR does not recognize the ldaps
url form.
-
In the case where one of the
back-end LDAP directory server hosts becomes unreachable from the host
on which DAR is running, clients that were virtually connected to that
host may seem to hang as they wait for DAR to time out its back-end connection.
A fail over is performed by DAR when the connection gets timed out. The
time-out is modifiable on Solaris systems. (Check the details about the
idsktune utility. The utility gets installed at <server-root>/shared/bin
and is explained in section "Operating System Requirements" of Chapter
2, "Computer System Requirements" in the DAR Installation Guide.)
UI (Console Interface)
-
The DAR Configuration Editor
Console fails to warn the user that a configuration reload is required
(by recycling the server or by HUP) of all subscribing DARs if a configuration
object (Group, Action, Rule, Property, or System) is deleted.
-
The DAR Configuration Editor
Console fails to warn the user that a configuration reload is required
(by recycling the server or by HUP) of all subscribing DARs if the user
changes the priority of groups by using the Up/Down arrow buttons in the
Group Object View.
-
On Unix variants, the Console's
"helper" functions used to determine if DAR is up and running won't see
DAR if the ldapfwd DAR is running is a symbolic link. This is only an issue
if DAR installation has been manually manipulated post installation. (In
other words, do not rename the DAR executable or convert it to a symbolic
link.)
Uninstallation
-
During uninstallation, DAR does
not remove all entries subordinate to
ou=dar-config, o=NetscapeRoot.
[548593]
-
On Windows, the correct way to
uninstall DAR is to remove DAR first and then subsequently uninstall the
iPlanet Administration Server. [540694]
The DAR
uninstallation must not be done simultaneously with the removal of its
corresponding Administration Server. The reason for this is that when everything
is being removed, the uninstall program stops the Administration Server
and removes its service manager entry prior to the DAR uninstall routines
being given the opportunity to remove its configuration. Because DAR depends
on the Administration Server to carry out an uninstallation task, the Administration
Sever should be up and functioning when DAR is being uninstalled. If DAR
is uninstalled simultaneously with the Administration Server, it leaves
its configuration subordinate to ou=dar-config,
o=NetscapeRoot in the
configuration repository untouched. This could cause undesired behavior
with DAR, should you reinstall DAR on the same host and use the same configuration
repository subsequently as it could see residual "belongs to" entries.
Manual
remedy should you not heed this advice: find all entries subordinate
to ou=dar-config,
o=NetscapeRoot whose ids-proxy-sch-belongs-to
matches the host in question and remove the attribute. Note that the entry
may be removed only if the entry no longer possesses any value for the
ids-proxy-sch-belongs-to
attribute.
Resolved Bugs
This section
contains the list of bugs that have been resolved in this release of DAR:
Bugs/enhancements
fixed with 5.0 SP1:
Bug Number |
Description |
4537392 |
On bind evaluation now requires non
zero length password before an action will occur. |
4535792 |
Installation of DAR without a console
now supported on NT. |
4632706 |
Suspend heartbeat monitoring for SSL
only servers. |
4632716 |
Second bind over v2 connection not being
passed to backend server. |
4674645 |
Allow zero length attributes in searches. |
4675022 |
Console configuration omitted "never"
case on SSL configuration. |
4678584 |
Copyright on console touched. |
4680128 |
Gethostname failing on Solaris. |
4680138 |
DAR could fail when changing group to
a group that uses same server set. |
4680142 |
RC4 ciphers have returned to DAR's supported
cipher list. |
4680145: |
Corrected blocking socket issue for
large packets sent over SSL |
4680150 |
When receiving an ldap:/// referral
without a host, nor port number, stipulated: DAR uses the host name and
port number of the referring server. |
Bugs fixed
with 5.0 base:
Bug Number |
Description |
440769 |
hopcount on referrals is not working |
441849 |
TCL configuration tool and iDS ldif
idiosyncrasies |
441869 |
TCL configuration tool always decomposes
DN |
442009 |
TCL configuration tool does not handle
quoted suffix |
512817 |
certreq invoked with no option returns
with file open errors |
520001 |
StartTLS interoperability problem with
iDS5.0 |
520002 |
Application error if directory server
is not running |
520063 |
Windows configuration tool only supports
default install path |
531360 |
Typos in configuration script error
message |
531361 |
LDIF file contains RDN values of parent
entries |
533854 |
Improve Logging in DAR |
534287 |
DAR core dumps on referral following |
534288 |
DAR crash |
540631 |
Security hole reported by CERT affects
DAR too |
541798 |
NT files do not have access control
restrictions |
541891 |
CRTL-C kills ldapfw if started with
/etc/rc.d/S93 DAR |
542760 |
Support URL ldap:/// |
542807 |
Encoding error for large entries |
543331 |
Crash on failover for server with 0
priority |
546990 |
Reverse-DNS lookup fails in DARv2.1,
IP-addresses do work |
How to Report Problems
If you have
problems with iPlanet Directory Access Router, contact iPlanet customer
support using one of the following mechanisms:
So that we
can best assist you in resolving problems, please have the following information
available when you contact support:
-
Description of the problem, including
the situation where the problem occurs and its impact on your operation
-
Machine type, operating system
version, and product version, including any patches and other software
that might be affecting the problem
-
Detailed steps on the methods
you have used to reproduce the problem
-
Any error logs or core dumps
You may also
find it useful to subscribe to the following interest groups, where iPlanet
Directory Access Router topics are discussed:
snews://secnews.netscape.com/netscape.dev.directory
For More Information
Useful iPlanet
information can be found at the following Internet locations:
Use
of iPlanet Directory Access Router is subject to the terms described in the
license agreement accompanying the software.
Copyright
© 2002 Sun Microsystems, Inc. All rights reserved.