Red Hat Directory Server 8.1
Red Hat Directory Server 8.1 Release Notes
for Directory Server 8.1 Copyright 2009 Red Hat, Inc. Copyright 2009 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons AttributionShare Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. All other trademarks are the property of their respective owners. 1801 Varsity Drive Raleigh, NC 27606-2072 USA Phone: +Phone: 4281 Fax: +754 3701
April 28, 2009, updated September 9, 2009 Abstract
Red Hat Directory Server 8.1 Release Notes 1. 2. 3. 4. 5. 6. 7. New in Red Hat Directory Server 8.1.... 2 System Requirements.... 6 Installing Directory Server 8.1... 8 Basic Information about Red Hat Directory Server... 11 Bugs Fixed in 8.1.... 13 Errata Updates..... 20 Known Issues.... 20
These release notes contain important information available at the release of Red Hat Directory Server version 8.1. New features, system requirements, installation notes, known problems, resources, and other current issues are addressed here. Read this document before beginning to use Directory Server 8.1.
1. New in Red Hat Directory Server 8.1
Directory Server 8.1 has introduced many features to make managing the directory service and its data easier.
1.1. Enhanced Server to Server Connections with Added SASL/ Digest-MD5 (Kerberos), SASL/GSSAPI (Kerberos), and Start TLS Support
Red Hat Directory Server performs a number of different connections between servers, such as replication, chaining, synchronization, and pass-through authentication. To secure these connections, Red Hat Directory Server previously supported SSL and TLS authentication. Directory Server 8.1 expands the secure connection options to include SASL/Digest-MD5 (Kerberos), SASL/GSSAPI (Kerberos), and Start TLS for these server to server operations. Connections between Directory Server instances can be secured using SASL and Start TLS. This includes replication and chaining (database links). Pass-through authentication now allows optional arguments to enable Start TLS. (SASL connections are not supported for pass-through authentication.) Windows synchronization now supports Start TLS (a secure TLS connection over a standard LDAP port) for Active Directory-Directory Server connections. (SASL connections are not supported for Windows.) The configuration attributes and Console has been updated to include these enhancements: For replication and synchronization, the nsds5ReplicaBindMethod and nsds5ReplicaTransportInfo attributes For chaining, the nsUseStartTLS, nsBindMechanism and nsActiveChainingComponents attributes
1.2. Server Task Management to LDAP with cn=tasks Entries
Directory Server 8.1 has long had the ability to launch server maintenance tasks over LDAP. Directory tasks like import, export, backup, restore, and indexing, as well as new tasks for reloading schema and updating people's group membership attributes. However, this feature has not previously been documented. In Directory Server, documentation has been added for the five original database tasks (import, export, index, backup, and restore). Additionally, two new tasks have been created for the new dynamic schema reload and memberOf tasks. 2

Red Hat Directory Server 8.1 Release Notes Directory Server 8.1 has added a new managed attribute, memberOf, and a new MemberOf Plug-in. Whenever a member is added to a static group, the MemberOf Plug-in uses the person's DN from the member or uniqueMember attribute to search for the user entry, and then adds a memberOf attribute to the user entry. This way, it's simple to tell from looking at the user entry what groups it belongs to. memberOf attributes are initially assigned to entries by running a special task. This task can be launched by creating a task entry beneath the cn=memberof task, cn=task,cn=config container entry or by running the new fixup-memberof.pl script.
1.7. Extended Get Effective Rights Operations with Options for NonExistent and Operational Attributes
A get effective rights operation is an extended ldapsearch that, along with regular search results, returns that access permissions that one directory user has to a directory entry or entries. Directory Server 8.1 adds two additional attribute search options for get effective rights searches. One (*) returns rights for non-existent attributes for the entry, meaning attributes which could be set on the entry but currently are not. The other (+) returns access rights for operational attributes for the entry.
1.8. Added New Support for 64-Bit Integers for Performance Counters on 32-Bit Systems
Many of the performance counters for the Directory Server including server statistics, database statistics, and SNMP monitoring record 32-bit integers. For large or high-traffic systems, these counters may roll over too quickly, creating quirky performance statistics and making it difficult to conduct long-term analysis. Directory Server 8.1 introduces support for 64-bit integers for performance counters, even on 32bit systems. These 64-bit integers are enabled through a new configuration attribute on the DSE, nsslapd-counters. When 64-bit integers are enabled, all available counters support 64-bit integers. For server statistics, there are five counters which support 64-bit integers: opsinitiated opscompleted entriessent bytessent totalConnections For database statistics, there are four counters which support 64-bit integers: entrycachehits entrycachetries currententrycachesize maxentrycachesize All of the attributes monitored by SNMP can support 64-bit integers.
Added New Parameter for Setting the Interval for Win Sync Checks
1.9. Added New Parameter for Setting the Interval for Win Sync Checks
In synchronization, updates are sent two ways, from the Directory Server to the Active Directory server and from Active Directory back to the Directory Server. The frequency which Directory Server sends updates to Active Directory is set in the synchronization schedule, handled by the nsds5replicaupdateschedule attribute. The frequency which Directory Server checked Active Directory for updates was hard coded at five minutes. A new attribute has been added, winSyncInterval, which sets how frequently the Directory Server should check the Active Directory peer for changes. If this attribute is not set, the default frequency is still every five minutes. This new Win Sync interval can be used with existing sync agreements. To apply this new attribute: 1. Upgrade the software, as described in Section 3.4, Upgrading to Directory Server 8.1. 2. Copy the 01common.ldif from the common /etc/dirsrv/schema directory into the instancespecific directory, such as /usr/lib/dirsrv/slapd-instance_name/schema. It is okay to overwrite the new 01common.ldif schema file because it is new and because the core configuration schema should never be modified, so there shouldn't be any custom settings. 3. Reload the schema. For example:

2.3. Directory Server Supported Platforms
Directory Server 8.1 is supported on the following platforms: HP-UX 11i Itanium/IPF Red Hat Enterprise Linux 4 i386 (32-bit) Red Hat Enterprise Linux 4 x86_64 (64-bit) Red Hat Enterprise Linux 5 i386 (32-bit) Red Hat Enterprise Linux 5 x86_64 (64-bit) 6
Directory Server Console Supported Platforms
Red Hat Directory Server 8.1 is supported running on a virtual guest on a Red Hat Enterprise Linux 5 virtual server.
Sun Solaris 9 (SPARC v9, 64-bit)
2.4. Directory Server Console Supported Platforms
The Directory Server Console is supported on the following platforms: HP-UX 11i Itanium/IPF Red Hat Enterprise Linux 4 i386 (32-bit) Red Hat Enterprise Linux 4 x86_64 (64-bit) Red Hat Enterprise Linux 5 i386 (32-bit) Red Hat Enterprise Linux 5 x86_64 (64-bit) Sun Solaris 9 (SPARC v9, 64-bit) Windows XP Windows 2000 Server Windows 2003 Server
The Directory Server Console can be installed on additional Windows platforms at an additional cost.
2.5. Windows Sync Service Platforms
The Windows Sync tool runs on these Windows platforms: Windows 2003 Active Directory (32-bit) Windows 2000 Active Directory (32-bit)
2.6. Web Application Browser Support
Directory Server 8.1 supports the following browsers to access web-based interfaces, such as Admin Express and online help tools: Firefox 1.0 (Red Hat Enterprise Linux 4 and Solaris 9) Mozilla 1.4 (HP-UX) Mozilla 1.4.3 (Solaris 9) 7
Red Hat Directory Server 8.1 Release Notes Mozilla 1.7.3 (Red Hat Enterprise Linux 4) Microsoft Internet Explorer 6.0 (Windows)
3. Installing Directory Server 8.1
For more detailed instructions on installing Directory Server 8.1, see the Directory Server Installation Guide at http://www.redhat.com/docs/manuals/dir-server/.

3.1. Installing the JDK

Directory Server 8.1 requires Sun JRE 1.6.0 or OpenJDK 1.6.0. The appropriate Sun JDK should already be available on Sun Solaris systems, but it is necessary to install the JDK separately for other platforms. Either Sun JDK 6.0 or OpenJDK 1.6.0 is allowed. For example, to install OpenJDK on Red Hat Enterprise Linux 5:
yum install java-1.6.0-openjdk
OpenJDK is also available for download from http://openjdk.java.net/install/ for Red Hat Enterprise Linux and HP-UX. For Red Hat Enterprise Linux 4, subscribe to the Extras channel in Red Hat Network, and install Java IBM 1.6.0 using up2date:

up2date java-1.6.0-ibm

3.2. Obtaining Packages
Red Hat Directory Server 8.1 packages are available for download from Red Hat Network (http:// rhn.redhat.com). Downloading packages from Red Hat Network requires specific entitlements for the account for the 8.1 release. To download Red Hat Directory Server 8.1 packages, log into Red Hat Network, then open the Red Hat Directory Server 8.1 channel in Channels and go to the Downloads tab. Both RPMs and ISO images are available for download through Red Hat Network. RPM packages can be downloaded and installed using rpm. The ISO images for Red Hat Enterprise Linuxand Solaris can be downloaded and burned on to a CD-recordable media using the appropriate software. Along with the packages, there are tarball (.tar.gz file) archives for the source code.

The source files are tarball (.tar.gz) archive files, not ISO images.
Running setup-ds-admin.pl Red Hat Enterprise Linux customers can use Red Hat Network to obtain packages, or they can simply install or update their packages using yum or up2date, using an account with entitlements for the Red Hat Directory Server 8.1 release. Directory Server packages are installed using native package management tools. For example, on Red Hat Enterprise Linux:
ls *.rpm | egrep -iv -e devel -e debuginfo | xargs rpm -ivh

On Sun Solaris:

for pkg in *.pkg ; do pkgadd -d $pkg all done
The Password Sync packages available for download contain the PassSync.msi installer file. Download this file to the Windows machine, and then double-click the icon and go through the installer.
Although the Password Sync packages are listed in every Directory Server channel in Red Hat Network (Solaris, Red Hat Enterprise Linux 32-bit and Red Hat Enterprise Linux 64-bit), Password Sync is only supported on 32-bit Windows machines.
3.3. Running setup-ds-admin.pl
After installing the packages, run the setup-ds-admin.pl script to configure the new Directory Server and Administration Server instances. For example:

setup-ds-admin.pl

See the Directory Server Installation Guide for more information about setup-ds-admin.pl script options and the Directory Server configuration interface.
3.4. Upgrading to Directory Server 8.1
Red Hat Enterprise Linux systems support an in-place upgrade when moving from Red Hat Directory Server 8.0 to Red Hat Directory Server 8.1. To do this: 1. Back up your current Directory Server, according to your preferred backup method. For example:
cd /usr/lib/dirsrv/slapd-instance_name db2bak /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2009_04_30_16_27_56
2. Install or update the RPMs. For example:

yum update -y

This automatically updates the Red Hat Directory Server packages and all required packages. Red Hat Directory Server 8.1 requires that all of the packages in the Red Hat Directory Server channel be updated. Running simply yum update updates all Red Hat Directory Server and Red 9
Red Hat Directory Server 8.1 Release Notes Hat Enterprise Linux packages. To exclude packages from updating on your system, you can use --exclude packages, restrict the update to only the Red Hat Directory Server channel, or explicitly list the packages to update. Run man yum for a list of options. 3. Re-run the setup script with the -u option.

setup-ds-admin.pl -u

The basic schema used by the Directory Server itself was divided into two files. All of the schema the server are contained in 00core.ldif. All of the other configuration schema elements used b Server instances are in 01common.ldif.

238762

By default, the nsslapd-import-cache-autosize attribute for the LDBM Database Plug-in wa means that the cache is automatically set to half (50%) of the available memory. However, the Dire Console shows the default value as 20000000 bytes, not the auto size. And, since auto cache sizi over manually assigning the cache size, whatever was set in the Directory Server Console was ign The Directory Server Console has a new checkbox to enable or disable auto cache sizing. If auto enabled, the value set for the cache size is ignored.

387851

Occasionally, the Directory Server's ns-slapd could shut down successfully, but its.pid file was there was an existing.pid file for a server instance, then the server could not restart, even if it wa Some cn changes on Directory Server were not synced over to Active Directory.
The Directory Server would allocate as much memory as a client suggested for a SASL operation, any other limits being imposed. This can be restricted now in Directory Server 8.1 through the new maxsasliosize configuration attribute, which sets a limit on the size of incoming SASL packets.

426435

If a user was logged in as the Directory Manager and tried to change the admin user's password in Administration Server's Console, the server would try to change the Directory Manager's password Changing the admin user's password in the Administration Server Console closed the connection immediately when the change was saved.
When a non-privileged user logged into a console and attempted to open a configuration tab, the c throw Java exceptions to standard output and open error dialogs.
The Windows version of the Directory Server Console looked for its NSS libraries in the wrong loc
If a CRL was located in the /usr/lib/dirsrv/slapd-instance_name directory, it could not b CRL tab of the Directory Server Console's Certificate Wizard. If the CRL was located anywhere els loaded through the Certificate Wizard just fine.

428232 428929

Performing a rename operation failed if the DN was only different in case (such as cn=john smit Smith) or where the new DN was identical to the old DN.
The Directory Server was caching the values of attributes with DirectoryString formats. For examp was added with a value in all capital letters, and then the value was deleted and replaced with all l sometimes the Directory Server would return the correct lower-case value, and sometimes it would previous upper-case value. This happened because replication doesn't delete attribute values; it s state information. When the attribute was re-added, the old attribute was resurrected with updated and, since DirectoryString is case-insensitive, the old value looked identical to the new value. If a virtual subtree was used to configure synchronization, the Directory Server crashed.

430368 432135

The date and time fields were incorrectly parsed and displayed in the Administration Server Conso
Consumer initialization would crash the consumer server or the process would hang endlessly if th with a very large attribute. There was a memory leak in the collation plug-in.
The setup-ds-admin.pl script did not correctly set the IP address of the Administration Server Administration Server IP address was different than the Directory Server instance's IP address.
When configuring a new instance with setup-ds.pl, the server could fail to start because it coul var/run/dirsrv/ directory and, therefore, open the stats file for the instance.
Red Hat Directory Server 8.1 Release Notes Bug Number 430568 Description
It is possible to specify which locale to use when running an ldapsearch. Specifying the default locale (2.16.840.1.113730.3.3.2.0.1), however, returned spurious errors to the log, saying that the collati and strength could not be set, even though they were.

430993

The log deletion policies set for the access, audit, and error logs could be ignored if the two parameters de time amount (integer) and time unit (day, week, month, or year) are not in the proper order. In dse.ldif, amount had to be listed first, then the time unit next.
Changing only one of the defaults for the deletion policy in the Directory Server Console added only that o parameter to the dse.ldif file. If only one of the parameters was in the file, than the nsslapd-TYPEloglogexpirationtime defaulted to not expiring (PR_INT32_MAX) and nsslapd-TYPElog-logexpirationtimeunit 431607
The Referential Integrity Plug-in did not ignore spaces in DNs. So, it treated ou=groups, dc=example, as different than ou=groups,dc=example,dc=com. However, the plug-in would insert white spaces into during a rename operation, so if ou=groups,dc=example,dc=com was added to the database, the Ref Integrity Plug-in would change it to ou=groups, dc=example, dc=com. This would then break referen integrity.

435774

When trying to install a new instance of Directory Server using setup-ds.pl and specifying an input file to populate the databases, the script failed with an error that it could not import LDIF file. The new instanc partially configured, and had to be removed and re-installed.

435778

The ds_removal script assumed that any instance being removed was fully configured and running. The when trying to remove an instance where the setup had failed, the configuration had become corrupted, o off would fail with this error: Error:The server '' is not reachable. Error: unknown error

437049

If the inherited object classes were not explicitly set in an entry, the supplier server would show that the en inherited object classes, but the replicated on the entry in the consumer server would not have the inherite classes. Inherited object classes were not replicated. Rename operations failed if the RDN contained a backslash (\).

445602

Trying to create a second Directory Server instance on a server would fail if its Unix user and group IDs w different than the first instance's Unix user and group IDs.
Because schema with an empty description was treated as user-defined, some standard schema element replicated into consumers' 99user.ldif files. Some standard schema were removed between Directory 7.1 and Directory Server 8.0 and 8.1. Then, during migration, some of these deprecated schema elements migrated to the new version (because they had been replicated) but other elements mentioned in the sche definitions were still missing, so the 99user.ldif file was invalid. This caused migration to fail.

447353

Many standard schema elements have empty descriptions (DESC ''). However, any schema element wit description was treated as a custom element and was replicated into the 99user.ldif file on a consume Therefore, many standard schema elements were replicated.
The Directory Server limited indexed searches to a minimum of three characters. This meant that a substr such as ab* was indexed and completed very quickly, but a search such as a* was unindexed and could time.
In some cases, it's necessary to have indexed searches for very short strings, even though there is a perfo hit. A new attribute, nsSubStrLen, was added to reset the minimum search string length for an index. If the ns-slapd process stopped uncleanly while the server was writing to the changelog, the changelog would hang when the ns-slapd process restarted, unless the entire system was rebooted.
If an operation was opened with unsupported critical controls, then the operation wasn't closed with an un abandon request, and the connection stayed open.

If two supplier bind DNs were added to the database using an ldapmodify request, then replication usin second or subsequent bind DN failed.
If the Administration Server was configured to use SSL, the Console would save its server certificate to its console.conf file without putting quotes around the certificate name. If the certificate name had spaces Administration Server was then unable to restart. The ldclt tool was enhanced to perform abandon operations.

471138 471998

The dbverify tool could not process integer-based sorting, but it was possible to configure an index with sorting by setting nsMatchingRule: integerOrderingMatch. The dbverify tool has been extende include numeric sorting.

472457 474237

If a custom server-side sorting order was used and then the database was indexed, then the Directory Se crash or become unresponsive under certain circumstances.
If a suffix was exported that had subsuffixes, then erroneous and confusing error messages were printed d the export claiming that (parent) instance already existed as it processed the subsuffix entries. The db2ld s command has be modified so that it checks for the parent DN of every suffix it processes. This also ena script to be run on a branch point, like ou=groups,dc=example,dc=com, successfully because the scri up the directory tree until it finds the suffix to export.

474248 474621

If replication was set up for a backend which did not exist on the consumer, then the consumer Directory S would crash as soon as the supplier tried to initialize the consumer.
When adding a user-specified nsUniqueID value for a new entry, the Directory Server would reject the va use an auto-generated nsUniqueID value. However, if nsUniqueID was used as the RDN, the original u supplied nsUniqueID value was still used in the DN, even though that value didn't exist in the entry.

474729 475338

Some search results which contained unindexed attributes did not contain the notes=U message in the a to indicate an unindexed search.
The nsslapd-*log-logmaxdiskspace, nsslapd-*log-logminfreediskspace, and nsslapd-*l maxlogsize configuration attributes accept sizes in megabytes, but the values were converted to bytes i backend. Using 32-bit integers for the sizes overflowed easily. These configuration attributes have been ch handle 64-bit integers.

475899

An extensible match filter is used as part of an LDAP that instructs the server what kind of matching rule to example, ou:2.16.840.1.113730.3.3.2.46.1:=* matches any ou that uses the Swedish locale. Ho using an operator with the extensible match filter, such as ou:2.16.840.1.113730.3.3.2.46.1:=>= crashed the Directory Server.

If an independent process, such as db2ldif was used to rotate the error log, the Directory Serve
Running the setup-ds-admin.pl script as an update (-u) or as a silent installation (-s and (-f errors for settings which were mapped for default values in the interactive mode but not in silent m example:
The map value 'ServerIpAddress' for key 'as_addr' did not map to a value in any of the given inform

6. Errata Updates

The following errata have been issued for Red Hat Directory Server, fixing important security and performance issues. The complete list of errata issued for Red Hat Directory Server 8.1 is available through Red Hat Network: Red Hat Enterprise Linux 5 Red Hat Enterprise Linux 4
Table 4. Bugs Fixed in Errata Updates for Directory Server 8.1 Release Date Errata Release January 21, 2010 Bug Number Description There was an issue an issue with synchronizing a deletion for a user entry. When a user entry with a comma character in the CN attribute was deleted in Active Directory, the deletion was not synchronized to the Red Hat Directory Server side. The Active Directory tombstone DN was unable to be mapped to the associated Red Hat Directory Server DN. This updated package corrects the tombstone mapping logic, allowing the deletion to be synchronized successfully.

RHBA-2010:006487681 3

7. Known Issues
The following are some of the most important known issues in Directory Server 8.1. If applicable, supported workarounds are also described. Table 5. Known Issues in Directory Server 8.1 Bug Number 151705 Description Workaround The Administration Server Console is hardNever edit the Administration Server ciphers through the coded to set all TLS ciphers to enabled. directory. Disabling the TLS ciphers through the Console is not saved, and the ciphers are re-enabled when the Administration Server is restarted. Installing a certificate with the same name as an existing certificate fails in the Directory Server Console with the error Internal error: Fail to install certificate -8169. Upgrading the Windows Sync service on the Windows server from version 7.1 to version 7.1 SP1 or higher (including 8.1) requires two things: Rebooting the Windows machine. Performing a full manual resynchronization. To manually synchronize Active Directory and Directory Server, open the Directory Server Console, and, in the Configuration tab, click the Replication folder, select

159025

If it is necessary to have two certificates with the same na
certutil -importcert -v /path/to/certificate_file

171140

Known Issues Bug Number Description the database, and the right-click on the synchronization agreement. 182509 The changelog used for replication stores passwords in clear text in order to replicate them. In some contexts, this could be a security risk. By default, not all attributes are automatically replicated to consumers in multi-master replication, including several password-associated attributes such as passwordRetryCount, retryCountResetTime, and accountUnlockTime. Global syntax checking attributes should be enforced if the settings aren't configured in the local password policy. However, if both global and local password policies are configured, the global policies aren't being enforced as the default. In Directory Server 8.1, the 00core.ldif file has be split so that 00core.ldif, correctly, only contains the schema directly required for starting the server. The other schema previously in that file have been moved to a new standard schema file, 01common.ldif. However, on startup, the Directory Server may record schema-related errors. For example:

[02/Jan/2008:11:20:33 -0800] - Entry "cn=config" has unknown object class "nsslapdConfig"

Workaround

Enable fractional replication and specifically exclu changelog. For example:
nsds5replicatedAttributeList: (objectclass=*) $ EX

190824

To replicate these attributes, set the passwordIs
dn: cn=config changetype: modify replace: passwordIsGlobalPolicy passwordIsGlobalPolicy: 1

190862

1. Enable global syntax checking. 2. Enable fine-grained password checking.
3. Edit the local password policy to contain all p Command, and File Reference.
4. Re-edit the local password policy with the de 230808

250535

On HP-UX and Solaris, the replmonitor.pl script returns an error that it cannot find the appropriate Mozilla/LDAP/ Conn.pm Perldap modules.
On Solaris, edit the repl-monitor.pl script one in your path.
On HP-UX, edit the repl-monitor.pl script add the following line after the comment block
"use lib qw(/opt/dirsrv/lib/perl /opt/dirsrv/lib/perl/arch)"

426139

When a non-privileged user logs into the Directory Server Console and selects the Configuration tab, the Console throws Java exception errors to standard output. When performing any import or export database operation through a remote Console will fail with the error Cannot write to file. if a relative path is given for the file.

426145

Import and export operations through a remote C
Using a relative path to import or export an LDI
Using an absolute path to import or export an L
Red Hat Directory Server 8.1 Release Notes Bug Number Description Workaround
However, importing or exporting the database to the rem
When importing or exporting databases on a remote mac select a file. 426421 If both Password Sync and the Directory Server Console are installed on the same Windows machine, then the Directory Server Console will load the Password Sync nss3.dll, and will fail when it attempts to open. When using the Console to install a CRL, if the CRL is placed in the proper directory, / etc/dirsrv/slapd-instance_name, the Console returns an error that it cannot locate the file. If a Directory Server instance is migrated from a previous version to Directory Server 8.1, the nsslapd-saslpath is not migrated with the dse.ldif on the new 8.1 instance, so that the SASL libraries cannot be loaded. This configuration attribute is properly created in fresh Directory Server installations. The nsslapd-maxbersize attribute sets the maximum import size for LDAP entries; this is one way of improving performance and preventing denial of service attacks. This attribute is not listed as an attribute that requires a server restart after being changed. However, if the nsslapd-maxbersize attribute is increased, the old limit is still used. This is because the attribute value is applied when the connection table is created when the server is first started and the value is not reset dynamically. When updating from Berkeley DB libdb-4.4 to libdb-4.7, there can be problems migrating the data in the older database. This is indicated in the error logs with messages like: libdb: Program version 4.7 doesn't match environment version 4.4 Do not install Password Sync and the Windows version

426439

Put the CRL in the Administration Server directory, /etc

427321

Use ldapmodify to edit the 8.1 dse.ldif file and add

433718

Restart the server after changing the nsslapd-maxber

470084

Migrate to the newer Berkeley DB with this procedure: 1. Shut down the older database.
2. Still using the old version of Berkeley DB, run recove
3. With the DB_ENV->open method to run recovery, ma appropriate system utility.
4. Archive the database environment for catastrophic re
5. Recompile and install the new version of the applicat
6. Force a checkpoint using the DB_ENV->txn_checkpo the utility; that is, the version that came with the relea 7. Restart the application.
Known Issues Bug Number Description Workaround
When the Directory Server restart, if it sees tha database with DBLAYER_CLEAN_RECOVER

472131

Directory Server stores entry IDs in an ID list in a duplicate btree. If the ID list is very long, the internal database uses internal pages to sort the entries. When verifying database data, Berkeley DB's verify function returns outof-order key errors because the database verification does not differentiate between the duplicate btree ID list and the main tree entry pages. The database, then, incorrectly tries to compare the main database page to itself rather than the duplicate ID btree. This affects Directory Server client tools such as verifydb.pl and dbverify. Due to a security concern, the Perl files on Create symlinks to the new Perl directory. Sun Solaris platforms were moved from / ln -s /usr/lib/sparcv9/dirsrv/perl5x /opt/perl5x opt/perl5x to /usr/lib/sparcv9/ dirsec/perl5x. However, some Perl utilities includes with Red Hat Certificate System are hard-coded to reference /opt/perl5x. This move can cause problems if users running Red Hat Certificate System upgrade their local Directory Server to Red Hat Directory Server 8.1 on the same machine. The Windows Sync packages have links on every Red Hat Network channel but are only available for 32-bit Windows platforms. The links on the 64-bit platforms (Red Hat Enterprise Linux 64-bit and Solaris 9) still download 32-bit Windows packages. For an in-place upgrade from Directory Server 8.0 to Directory Server 8.1, the Administration Server is also updated. However, the Administration Server console still shows the old version number, such as 8.0.4. For an in-place upgrade from Directory Server 8.0 to Directory Server 8.1, the new plug-in entries for the MemberOf and Distributed Numeric Assignment (DNA) Plugins are not automatically added to the server configuration. When Windows synchronization is enabled, if a user is moved from one subtree on Active Directory to another subtree, the user entry

476096 489558

484472

484929

Restart the Administration Server. This updates t
service dirsrv-admin start

495073

Manually add the new plug-in entries to the dse.

517905

Delete the user on the Windows server, and then
Red Hat Directory Server 8.1 Release Notes Bug Number Description is not moved to the corresponding location on the Directory Server during the next synchronization. Workaround

Red Hat Directory Server 8.1 Using the Admin Server
with Red Hat Directory Server Ella Deon Lackey

Using the Admin Server

Red Hat Directory Server 8.1 Using the Admin Server with Red Hat Directory Server Edition 8.1.1
Author Copyright 2009 Red Hat, Inc. Copyright 2009 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons AttributionShare Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. All other trademarks are the property of their respective owners. 1801 Varsity Drive Raleigh, NC 27606-2072 USA Phone: +Phone: 4281 Fax: +Ella Deon Lackey
The Admin Server is a support server which drives access to the Directory Server Console, provides a web server for Directory Server web applications, and stores some Directory Server configuration. This guide covers how to manage the Admin Server through the Console, through the command line, and through the web services, along with covering basic Admin Server concepts.
Preface v 1. Examples and Formatting... v 1.1. Command and File Examples... v 1.2. Tool Locations.... v 1.3. LDAP Locations.... v 1.4. Text Formatting and Styles... v 2. Additional Reading.... vi 3. Giving Feedback... vii 4. Documentation History... viii 1. Introduction to Red Hat Admin Server 1
2. Admin Server Configuration 3 2.1. Directory Server File Locations... 3 2.2. Starting and Stopping the Admin Server.. 4 2.2.1. Starting and Stopping Admin Server from the Console... 4 2.2.2. Starting and Stopping Admin Server from the Command Line. 5 2.3. Opening the Admin Server Console... 6 2.4. Viewing Logs.... 8 2.4.1. Viewing the Logs through the Console... 8 2.4.2. Viewing Logs in the Command Line.. 9 2.4.3. Changing the Log Name in the Console.. 10 2.4.4. Changing the Log Location in the Command Line... 11 2.4.5. Setting the Logs to Show Hostnames Instead of IP Addresses.. 12 2.5. Changing the Port Number.... 12 2.5.1. Changing the Port Number in the Console... 12 2.5.2. Changing the Port Number in the Command Line... 13 2.6. Setting Host Restrictions... 14 2.6.1. Setting Host Restrictions in the Console.. 14 2.6.2. Setting Host Restrictions in the Command Line.. 16 2.7. Changing the Admin User's Name and Password.. 17 2.8. Working with SSL... 18 2.8.1. Requesting and Installing a Server Certificate.. 19 2.8.2. Installing a CA Certificate... 23 2.8.3. Enabling SSL... 26 2.8.4. Creating a Password File for the Admin Server.. 28 2.9. Changing Directory Server Settings.... 29 2.9.1. Changing the Configuration Directory Host or Port.. 30 2.9.2. Changing the User Directory Host or Port.. 30 3. Admin Express 3.1. Managing Servers in Admin Express... 3.1.1. Opening Admin Express.... 3.1.2. Starting and Stopping Servers... 3.1.3. Viewing Server Logs... 3.1.4. Viewing Server Information... 3.1.5. Monitoring Replication from Admin Express.. 3.2. Configuring Admin Express.... 3.2.1. Admin Express File Locations... 3.2.2. Admin Express Configuration Files.. 3.2.3. Admin Express Directives... 43
4. Admin Server Command-Line Tools 47 4.1. sec-activate.... 47 4.2. modutil.... 47
Using the Admin Server Index 59

Preface

The Admin Server Guide provides information on using a support administrative server with identity management projects including Red Hat Directory Server and Red Hat Certificate System. The Admin Server runs the Java consoles used by those servers, as well as providing web services and storing configuration information for those services. The Admin Server is installed and configured automatically with Red Hat Directory Server. This guide covers how to use and manage the Admin Server through its own Java Console (part of Red Hat Console, along with the Directory Server Console), through native command-line tools, and through the integrated web services.

1. Examples and Formatting
Each of the examples used in this guide, such as file locations and commands, have certain defined conventions.
1.1. Command and File Examples
All of the examples for Red Hat Directory Server commands, file locations, and other usage are given for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files for your platform. Example 1. Example Command To start the Red Hat Directory Server:

service dirsrv start

1.2. Tool Locations
The tools for Red Hat Directory Server are located in the /usr/bin and the /usr/sbin directories. These tools can be run from any location without specifying the tool location.

1.3. LDAP Locations

There is another important consideration with the Red Hat Directory Server tools. The LDAP tools referenced in this guide are Mozilla LDAP, installed with Red Hat Directory Server in the /usr/lib/ mozldap directory on Red Hat Enterprise Linux 5 (32-bit) (or /usr/lib64/mozldap for 64-bit systems). However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP in the /usr/ bin directory. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL, which OpenLDAP tools use by default.
1.4. Text Formatting and Styles
Certain words are represented in different fonts, styles, and weights. Different character formatting is used to indicate the function or purpose of the phrase being highlighted. Formatting Style Monospace font Purpose Monospace is used for commands, package names, files and directory paths, and any text displayed in a prompt.

Preface Formatting Style

Monospace with a background
Purpose This type of formatting is used for anything entered or returned in a command prompt. Any text which is italicized is a variable, such as instance_name or hostname. Occasionally, this is also used to emphasize a new term or other phrase. Most phrases which are in bold are application names, such as Cygwin, or are fields or options in a user interface, such as a User Name Here: field or Save button.

Italicized text

Bolded text
Other formatting styles draw attention to important text.
A note provides additional information that can help illustrate the behavior of the system or provide more detail for a specific issue.

IMPORTANT

Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.

WARNING

A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.

2. Additional Reading

The Directory Server Administrator's Guide describes how to set up, configure, and administer Red Hat Directory Server and its contents. this manual does not describe many of the basic directory and architectural concepts that you need to deploy, install, and administer a directory service successfully. Those concepts are contained in the Red Hat Directory Server Deployment Guide. You should read that book before continuing with this manual. When you are familiar with Directory Server concepts and have done some preliminary planning for your directory service, install the Directory Server. The instructions for installing the various Directory Server components are contained in the Red Hat Directory Server Installation Guide. Many of the scripts and commands used to install and administer the Directory Server are explained in detail in the Red Hat Directory Server Configuration, Command, and File Reference. Also, Managing Servers with Red Hat Console contains general background information on how to use the Red Hat Console. You should read and understand the concepts in that book before you attempt to administer Directory Server. vi

Chapter 2.

Admin Server Configuration
The Admin Server is a separate server from Red Hat Directory Server or Red Hat Certificate System, although they work interdependently. The Admin Server processes, file locations, and configuration options are also separate. This chapter covers the Admin Server information, including starting and stopping the Admin Server, enabling SSL, viewing logs, and changing Admin Server configuration properties, such as the server port number.
2.1. Directory Server File Locations
Red Hat Admin Server conforms to the Filesystem Hierarchy Standards. For more information on FHS, see the FHS homepage, http://www.pathname.com/fhs/. There are slight difference in the file locations depending on the platform, so the default Red Hat Enterprise Linux FHS locations (used in the examples) may not match every installation. Some platforms treat the Admin Server as optional software and therefore, under FHS, store Admin Server files in /opt directories. The files and directories installed with Directory Server are listed in the tables below for each supported platform. Table 2.1. Red Hat Enterprise Linux 4 and 5 (x86 and x86_64) File or Directory Log files Configuration files Instance directory Database files Runtime files Location /var/log/dirsrv/admin-serv /etc/dirsrv/admin-serv /usr/lib/dirsrv/admin-serv /var/lib/dirsrv/admin-serv /var/lock/dirsrv/admin-serv.* /var/run/dirsrv/admin-serv.* Init scripts /etc/rc.d/init.d/dirsrv-admin /etc/sysconfig/dirsrv-admin Tools /usr/bin/ /usr/sbin/ Table 2.2. HP-UX 11i (IA64) File or Directory Log files Configuration files Instance directory Database files Runtime files Binaries Location /var/opt/dirsrv/admin-serv/logs /etc/opt/dirsrv/admin-serv/runs /opt/dirsrv/admin-serv /var/opt/dirsrv/admin-serv /var/opt/dirsrv/admin-serv /opt/dirsrv/bin/ /opt/dirsrv/sbin/ Libraries /opt/dirsrv/lib/
Chapter 2. Admin Server Configuration
2.2. Starting and Stopping the Admin Server
The Admin Server is running when the setup-ds-admin.pl configuration script completes. Avoid stopping and starting the server to prevent interrupting server operations. When starting in SSL, the start script prompts for the password for the security (SSL certificate) database. It is possible to restart in SSL without being prompted for a password by using a password file. See Section 2.8.4, Creating a Password File for the Admin Server for more information. If there is not password file, then the Admin Server cannot be restarted in SSL through the Console, only the command-line scripts. Rebooting the host system can automatically start the Admin Server's httpd process. The directory provides startup or run command (rc) scripts. On Red Hat Enterprise Linux, use the chkconfig command to enable the Admin Server to start on boot. For HP-UX, check the operating system documentation for details on adding these scripts.

2.2.1. Starting and Stopping Admin Server from the Console
1. Start the Console, and open the Admin Console.
/usr/bin/redhat-idm-console -a http://localhost:9830
2. In the Tasks tab, click Restart Server or Stop Server.
Starting and Stopping Admin Server from the Command Line
When the Admin Server is successfully started or stopped from the Console, the server displays a message box stating that the server has either started or shut down.
2.2.2. Starting and Stopping Admin Server from the Command Line
There are two ways to start, stop, or restart the Admin Server: There are scripts in the /usr/sbin directory.
/usr/sbin/{start|stop|restart}-ds-admin
The Admin Server service can also be stopped and started using system tools on Red Hat Enterprise Linux 5 (32-bit) using the service command. For example:
service dirsrv-admin {start|stop|restart}
The service name for the Admin Server process on Red Hat Enterprise Linux 5 (32-bit) is dirsrv-admin.
2.3. Opening the Admin Server Console
There is a simple script to launch the main Console. On Red Hat Enterprise Linux, run the following:
/usr/bin/redhat-idm-console
HP-UX has a different location for the script:
/opt/dirsrv/bin/redhat-idm-console
When the login screen opens, the Admin Server prompts for the username, password, and Admin Server location. The Admin Server location is a URL; for a standard connection, this has the http: prefix for a standard HTTP protocol. If SSL/TLS is enabled, then this uses the https: prefix for the secure HTTPS protocol.

Figure 2.1. Login Box

Opening the Admin Server Console
It is possible to send the Admin Server URL and port with the start script. For example:
The a option is a convenience, particularly for logging into a Directory Server for the first time. On subsequent logins, the URL is saved. If the Admin Server port number is not passed with the redhat-idm-console command, then the server prompts for it at the Console login screen.
This opens the main Console window. To open the Admin Server Console, select the Admin Server instance from the server group on the left, and then click the Open at the top right of the window.
Figure 2.2. The Admin Server Console
Make sure that Sun JDK or OpenJDK version 1.6.0 is set in the PATH before launching the Console. Run the following to see if the Java program is in the PATH and to get the version and vendor information:

java -version

2.4. Viewing Logs
Log files monitor activity for Admin Server and can help troubleshoot server problems. Admin Server logs use the Common Logfile Format, a broadly supported format that provides information about the server. Admin Server generates two kinds of logs: Access logs. Access logs show requests to and responses from the Admin Server. By default, the file is located at /var/log/dirsrv/admin-serv/access. Error logs. Error logs show messages for errors which the server has encountered since the log file was created. It also contains informational messages about the server, such as when the server was started and who tried unsuccessfully to log on to the server. By default, the file is located at /var/ log/dirsrv/admin-serv/error. The logs can be viewed through Admin Server Console or by opening the log file.

-----BEGIN NEW CERTIFICATE REQUEST----MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF 0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7
ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n /zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N 9YdbjveMVXW0v4XwIDAQABoAAwDQYK ------END NEW CERTIFICATE REQUEST-----
4. Wait for the CA to respond with the server certificate; this can be as short as a few hours for an internal CA or as long as several weeks for a third-party CA. 5. Save the issued certificate to a file.
Keep a backup of the certificate data in a safe location. If the system ever loses the certificate data, the certificate can be reinstalled using the backup file.
6. Install the certificate. a. Select the Tasks tab, and click Manage Certificates.
b. Select the Server Certs tab, and click Install. c. Give the absolute path to the certificate (In this file radio button) or paste the certificate text in the text box (In the following encoded text block radio button), then click Next.
Installing a CA Certificate
d. Check that the certificate information displayed is correct, and click Next. e. Name the certificate, and click Next. f. Provide the password that protects the private key. This password is the same as the one provided in step c.
After installing the server certificate, configure the Admin Server to trust the CA which issued the server's certificate.
2.8.2. Installing a CA Certificate
To configure the Admin Server to trust the CA, obtain the CA's certificate and install it into the server's certificate database. Some commercial CAs provide a web site that allow users to automatically download the certificate, while others will email it back to users. After receiving the CA certificate, use the Certificate Install Wizard to configure the Admin Server to trust the CA. 1. In the Admin Server Console, select the Tasks tab, and click Manage Certificates.
2. Go to the CA Certs tab, and click Install.
Installing a CA Certificate 3. If the CA's certificate is saved to a file, enter the path in the field provided. Alternatively, copy and paste the certificate, including the headers, into the text box. Click Next.
4. Click Next to move through the panels that show the CA certificate information and the certificate name. 5. Select the purpose of trusting this certificate authority; it is possible to select both options: Accepting connections from clients (Client Authentication). The server checks that the client's certificate has been issued by a trusted certificate authority. Accepting connections to other servers (Server Authentication). This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted certificate authority.

The configuration file must be in a directory that is accessible to the Admin Server, and the file must be readable by the Admin Server user. By default, the user is nobody. The user is set in the console.conf file. To check the user, use grep to return the value:
The configuration file should be readable by the Admin Server user and no other users, so consider resetting the permissions on the file:
2. In the Admin Server web page, click the Admin Express link, and log in. 3. Click the Replication Status link by the supplier server name. 4. Type the path to the configuration file in the Configuration file field. Also, set the refresh rate, which is how frequently the replication status page updates; the default is 300 seconds.
Figure 3.4. Viewing Replication Status 5. Click OK. The Replication Status page shows the status for sending updates to every consumer listed in the configuration file.
Figure 3.5. Viewing Replication Status Table Table header Description The table header shows the replica ID of the supplier replica, the replicated suffix root (such as dc=example,dc=com), and the maximum change state number (CSN) on the supplier. (The CSN is the ID of the latest change on the supplier, while the max CSN for the supplier shows the last update it received.) The ID number of the most recent CSN the consumer has received that originated from the supplier. How long it takes for the consumer to receive updates from the supplier; this is the time difference between the supplier and the consumer's max CSNs. When a consumer is in sync with its supplier, the time lag is 0. Gives the time of the last update for the consumer (the time the last CSN entry was sent).

Max CSN

Time lag

Last Modify Time

Chapter 3. Admin Express Table Supplier Description Gives the name of the supplier sending updates to that consumer; this can be useful if a consumer receives updates from multiple suppliers or there are multiple suppliers being monitored on the Replication Status page. The number of changes that were sent from the supplier and the number skipped in the replication update. The numbers are kept in suppliers' memory only and are cleared if the supplier is restarted. The status code (and meaning) for the last update. This column can indicate a possible deadlock if all the suppliers complain that they cannot acquire a busy replica. It is normal for there to be a busy message if one of the suppliers is doing an update. The timestamps for when the most recent update process started and ended. The configured replication schedule. 0:-: means that the consumer is continually updated by the supplier. Indicates whether the supplier connects to the consumer over SSL.

Sent/Skipped

Update Status
Update Start and End Schedule
3.2. Configuring Admin Express
Admin Express can be edited for the page appearance, but most functionality is controlled through the web server or the Admin Server configuration and should be edited through those servers, not by editing the configuration files directly.

Figure 3.8. Monitoring Replication View Page Elements 40
Admin Express Configuration Files The text for the table headings, labels, and page sections are set in the Perl script. For example:
#Print the header of consumer print "\n<tr class=bgColor16>\n"; print "<th nowrap>Receiver</th>\n"; print "<th nowrap>Time Lag</th>\n"; print "<th nowrap>Max CSN</th>\n";. print "</tr>\n";
The styles for the Replication Status page are printed in the Perl script in the <style> tag in the HTML header. Many of the classes are the same as those in the style.css for the other web applications. These can be edited in the Perl script or by uncommenting the stylesheet reference and supplying a CSS file. For example:
# print the HTML header print "Content-type: text/html\n\n"; print "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 3.2//EN\"><html>\n"; print "<head><title>Replication Status</title>\n"; # print "<link type=text/css rel=stylesheet href=\"master-style.css\">\n"; print "<style text/css>\n"; print "Body, p, table, td, ul, li {color: #000000; font-family: Arial, Helvetica, sansserif; font-size: 12px;}\n"; print "A {color:blue; text-decoration: none;}\n"; print "BODY {font-family: Arial, Helvetica, sans-serif}\n"; print "P {font-family: Arial, Helvetica, sans-serif}\n"; print "TH {font-weight: bold; font-family: Arial, Helvetica, sans-serif}\n"; print "TD {font-family: Arial, Helvetica, sans-serif}\n"; print ".bgColor1 {background-color: #003366;}\n"; print ".bgColor4 {background-color: #cccccc;}\n"; print ".bgColor5 {background-color: #999999;}\n"; print ".bgColor9 {background-color: #336699;}\n"; print ".bgColor13 {background-color: #ffffff;}\n"; print ".bgColor16 {background-color: #6699cc;}\n"; print ".text8 {color: #0099cc; font-size: 11px; font-weight: bold;}\n"; print ".text28 {color: #ffcc33; font-size: 12px; font-weight: bold;}\n"; print ".areatitle {font-weight: bold; color: #ffffff; font-family: Arial, Helvetica, sansserif}\n"; print ".page-title {font-weight: bold; font-size: larger; font-family: Arial, Helvetica, sans-serif}\n"; print ".page-subtitle {font-weight: bold; font-family: Arial, Helvetica, sans-serif}\n"; print "</style></head>\n<body class=bgColor4>\n";

3.2.2.3. Files for the Server Information Page
There are two files formatting the server information page: The body of the page, /usr/share/dirsrv/html/viewdata.html The heading of the page, /usr/share/dirsrv/html/htmladmin.html
Figure 3.9. Server Information Page Elements The viewdata.html file is very simple, using only the two directives to insert the server data, plus other directives to insert other information. For the Admin Server, the SHOW_DATA directive takes the information from the /etc/dirsrv/admin-serv/local.conf file. For the Directory Server, it takes the data from the /etc/dirsrv/slapd-instance_name/dse.ldif file. The ID_TITLE is the name of the server instance.
<body text="#000000" bgcolor="#FFFFFF" link="#666699" vlink="#666699" alink="#333366"> <br> <table BORDER=0 CELLSPACING=2 CELLPADDING=2 WIDTH="100%"> <!-- ID_TITLE --> <p> <!-- SHOW_DATA --> <p> <font face="PrimaSans BT, Verdana, sans-serif"><font size=-1>Additional Information:</font></ font> <p> <!-- CHECK_UPGRADE --> <p> <!-- SHOW_URL --> </table> <!-- HELPBUTTON --> </body>
3.2.2.4. Files for the Server Logs Page
There are two files formatting the server logs page: The body of the page, /usr/share/dirsrv/html/viewlog.html 42
Admin Express Directives The heading of the page, /usr/share/dirsrv/html/htmladmin.html
Figure 3.10. Log View Page Elements The page information is set through the inserted directives. The server instance name is set in the ID_TITLE directive. The log is displayed through the ACCESS_LOG directives. The form at the top is formatted with directive pairs, one which sets the descriptive text and the other inserting the field type. For example, this sets the log type menu:
<form method=GET action=ViewLog> <font face="PrimaSans BT, Verdana, sans-serif"><font size=-1> <!-- BEGINELEM --> <!-- ELEM txt="Log to view: " --> <!-- LOG_TO_VIEW -->. <!-- SUBMIT --> </font></font> </form>

3.2.3. Admin Express Directives
The Admin Express directives are HTML comments that are interpreted by the CGI scripts; these directives are used to set form fields and to pull data from the server configuration and log files. Table 3.2. Admin Express Directives Directive ACCESS_LOG ADMURL Description Inserts the server log file. Example <!-- ACCESS_LOG --> <!-- ADMURL -->
Chapter 3. Admin Express Directive BEGINELEM Description Example
Marks the opening of form input <!-- BEGINELEM --> elements. This is always paired with ENDELEM. <!-- CHECK_UPGRADE --> Inserts a text element. This has one argument, txt=, which defines the text to use. Inserts a text element. This has one argument, txt=, which defines the text to use. Marks the ending of form input elements. This is always paired with BEGINELEM. Inserts a button to open context-specific help. Inserts a link to the general Admin Express help file. <!-- ELEM txt="Field name here: " --> <!-- ELEMADD txt="Field name here: " --> <!-- ENDELEM -->

CHECK_UPGRADE ELEM

ELEMADD

ENDELEM

HELP_BUTTON HELPLINK HIDDEN_ID ID_TITLE
<!-- HELP_BUTTON --> <!-- HELPLINK --> <!-- HIDDEN_ID -->
Inserts the name of the server <!-- ID_TITLE --> instance, such as adminserv or example (if the Directory Server instance name is slapd-example) Inserts the contents of the HTML file. The inserted file should include both the text and any HTML markup. Inserts a drop-down menu with the types of logs available to view. Inserts a form field to set the number of lines to return. Inserts a form field to set the refresh interval (in seconds) for replication monitoring. <!-- INCLUDEIFEXISTS "file.html" -->

INCLUDEIFEXISTS

LOG_TO_VIEW
<!-- LOG_TO_VIEW -->
NUM_TO_VIEW REFRESHINTERVAL
<!-- NUM_TO_VIEW --> <!-- REFRESHINTERVAL -->
SERVHOST SERVPORT SHOW_DATA Inserts the server data from the configuration file, including the port number, installation date, and build number.
<!-- SERVHOST --> <!-- SERVPORT --> <!-- SHOW_DATA -->
SHOW_URL SITEROOT STRING_TO_VIEW Inserts a form field to use to set the search string for the logs.
<!-- SHOW_URL --> <!-- SITEROOT --> <!-- STRING_TO_VIEW -->
Admin Express Directives Directive SUBMIT Description Inserts a three-button set: to save or submit the form; to reset the form; and to open a help topic. Example <!-- SUBMIT -->

Chapter 4.

Admin Server Command-Line Tools
Red Hat Admin Server has command-line utilities which make it easier to manage the Admin Server without having to launch the Admin Console. This chapter explains where to find and how to use the Admin Server tools.

4.1. sec-activate

The sec-activate tool activates and deactivates SSL for the Admin Server. Location Syntax

Location

The sec-activate tool is located in the /usr/lib/dirsrv/cgi-bin/ directory.

Syntax

sec-activate serverRoot SSLEnabled

Argument serverRoot

Description The location of the Admin Server configuration directory. The default location is /etc/dirsrv/ admin-serv. Sets whether to turn SSL on or off for the Admin Server.

SSLEnabled For example:

sec-activate /etc/dirsrv/admin-serv on

4.2. modutil

The modutil tool is a command-line utility for managing PKCS #11 module information stored in secmod.db files or hardware tokens. modutil can perform a variety of security database operations: Adding and deleting PKCS #11 modules Changing passwords Setting defaults Listing module contents Enabling or disabling slots Enabling or disabling FIPS-140-1 compliance Assigning default providers for cryptographic operations Creating key3.db, cert8.db, and secmod.db security databases. 47
Chapter 4. Admin Server Command-Line Tools Security module database management is part of a process that typically involves managing key databases (key3.db files) and certificate databases (cert8.db files). The key, certificate, and PKCS #11 module management process generally begins with creating the keys and key database necessary to generate and manage certificates and the certificate database. Location Syntax Tasks and Options JAR Information File Examples of Using modutil
The modutil tool is located in the /usr/bin folder.

modutil task [option]

task is one of the commands listed in Table 4.1, Task Commands for modutil and option is from Table 4.2, Options for modutil. Each modutil command can take one task and one option.

Tasks and Options

You can use the modutil tool to perform a number of different tasks. These tasks are specified through the use of commands and options. Commands specify the task to perform. Options modify a task command.

modutil Option Description AES DES DH SHA1 and SHA256 SSL and TLS MD2 and MD5 RANDOM (for random number generation) FRIENDLY (for certificates that are publicly readable). -newpwfile newPasswordFile Specifies a text file containing a token's new password. This allows the password to be automatically updated when using the changepw command. Instructs modutil not to open the certificate or key databases. This has several effects: When used with the -changepw command, no one is able to set or change the password on the internal module, because the password is stored in key3.db. When used with the -create command, only a secmod.db file will be created; cert8.db and key3.db will not be created. When used with the -jar command, signatures on the JAR file will not be checked. -pwfile passwordFile Specifies a text file containing a token's current password. This allows automatic entry of the password when using the -changepw command. Specifies a particular slot to enable or disable when using the -enable or -disable commands. Specifies a folder in which to store temporary files created by the -jar command. If a temporary folder is not specified, the current folder is used.

-nocertdb

-tempdir temporaryFolder

JAR Information File

JAR (Java Archive) is a platform-independent file format that aggregates many files into one. JAR files are used by modutil to install PKCS #11 modules. When modutil uses a JAR file, a special JAR information file must be included. This information file contains special scripting instructions and must be specified in the JAR file's MANIFEST file. Although the information file can have any name, it is specified using the Pkcs11_install_script METAINFO command.
Chapter 4. Admin Server Command-Line Tools For details on how to declare this METAINFO command in the MANIFEST, see http://docs.sun.com/ source/816-6164-10/contents.htm. If a PKCS #11 installer script is stored in the information file pk11install, the text file for the Signing Tool contains the following METAINFO tag:
+ Pkcs11_install_script: pk11install
The JAR information file in Example 4.1, Example JAR File has instructions for installing a PKCS #11 module on different platforms. Example 4.1. Example JAR File
ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } Platforms { Linux:2.0.32:x86 { ModuleName { "Fortezza Module" } ModuleFile { win32/fort32.dll } DefaultMechanismFlags{0x00000001 } CipherEnableFlags{ 0x00000001 } Files { win32/setup.exe { Executable RelativePath { %temp%/setup.exe } } win32/setup.hlp { RelativePath { %temp%/setup.hlp } } win32/setup.cab { RelativePath { %temp%/setup.cab } } } } Linux:2.0.32:x86 { EquivalentPlatform {WINNT::x86} } SUNOS:5.5.1:sparc { ModuleName { "Fortezza UNIX Module" } ModuleFile { unix/fort.so } DefaultMechanismFlags{ 0x00000001 } CipherEnableFlags{ 0x00000001 } Files { unix/fort.so { RelativePath{%root%/lib/fort.so} AbsolutePath{/usr/local/Red Hat/lib/fort.so} FilePermissions{555} } xplat/instr.html { RelativePath{%root%/docs/inst.html} AbsolutePath{/usr/local/Red Hat/docs/inst.html} FilePermissions{555} } } } IRIX:6.2:mips { EquivalentPlatform { SUNOS:5.5.1:sparc} } }

Installing a Cryptographic Module from a JAR File
To install a module using a JAR file, first create the JAR file script. For example:
Platforms { Linux:2.0.32:x86 { ModuleName { "SuperCrypto Module" } ModuleFile { crypto.dll } DefaultMechanismFlags{0x0000} CipherEnableFlags{0x0000} Files { crypto.dll { RelativePath{ %root%/system32/crypto.dll } } setup.exe { Executable RelativePath{ %temp%/setup.exe } } } } Win95::x86 {
Chapter 4. Admin Server Command-Line Tools
EquivalentPlatform { Winnt::x86 } } }
To install from the script, use the following command.
modutil -dbdir "/etc/dirsrv/admin-serv" -jar install.jar -installdir "/etc" WARNING: Performing this operation while the browser is running could cause corruption of your security databases. If the browser is currently running, you should exit browser before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue: Using database directory /etc/dirsrv/admin-serv. This installation JAR file was signed by: ---------------------------------------------**SUBJECT NAME** C=US, ST=California, L=Mountain View, CN=SuperCrypto Inc., OU=Digital ID Class 3 - Red Hat Object Signing, OU="www.verisign.com/repository/CPS Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network **ISSUER NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network ---------------------------------------------Do you wish to continue this installation? (y/n) Using installer script "installer_script" Successfully parsed installation script Current platform is Linux:2.0.32:x86 Using installation parameters for platform Linux:2.0.32:x86 Installed file crypto.dll to /winnt/system32/crypto.dll Installed file setup.exe to./pk11inst.dir/setup.exe Executing "./pk11inst.dir/setup.exe". "./pk11inst.dir/setup.exe" executed successfully Installed module "SuperCrypto Module" into module database Installation completed successfully
Changing the Password on a Token
To change the password for a security device in use by a module.
modutil -dbdir "/etc/dirsrv/admin-serv" -changepw "Admin Server Certificate DB" WARNING: Performing this operation while the browser is running could cause corruption of your security databases. If the browser is currently running, you should exit browser before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue: Using database directory /etc/dirsrv/admin-serv. Enter old password: Enter new password: Re-enter new password: Token "Admin Server Certificate DB" password changed successfully.