Notes

This section provides miscellaneous information about DirX that is not provided in the DirX user documentation.

Example Scripts

This section provides information about installed example scripts.

Easy Use of Example Scripts

For the Entrust-Setup implementation some changes of the example scripts (Stand_alone and Entrust) were required. To avoid installing the same example files twice (for entrust and for Stand_alone) a file was created that includes all global variables, for example country, organization, contextPrefix, …​ .

All stand-alone and Entrust example scripts include the file
<install path>/scripts/InitVar.tcl.
This TCL-Script includes the file
<install path>/scripts/Stand_alone/GlobalVar.tcl or
<install path>/scripts/LdapApplications/Entrust/Security-Manager/DefEntrustVar.tcl
specifying all global variables for the setup.

If you want to use a private copy of the files and change some global variables you also may have to change the variables ScriptsDir, EntrustScripts, StandAloneScripts in the file
<install path>/scripts/InitVar.tcl.
Otherwise the default scripts under Stand_alone or LdapApplications/Entrust/Security-Manager are used.

Monitoring Scripts

This release provides scripts for monitoring a DSA. The scripts are installed in
<install path>/scripts/AuditingMonitoring.

Please read the instructions in the file:
<install path>/scripts/AuditingMonitoring/README

LDIF Scripts

This release provides scripts to illustrate the use of LDIF agreements. The scripts are installed in
<install path>/scripts/LdifAgreements.

Please read the instructions in the file:
<install path>/scripts/LdifAgreements/README

Shadowing Scripts

This release provides scripts to illustrate the use of shadow agreements. Note that shadowing can only work correctly if you have administered the environment variables DIRX_DSA_NAME and DIRX_OWN_PSAP correctly for all DSA participating in your network. That is it is NOT possible to work with the default DSA name and the local loop back address. The scripts are installed in
<install path>/scripts/ShadowAgreements.

Please read the instructions in the file:

<install path>/scripts/ShadowAgreements/README_SHADOW

LdapApplications Scripts

This release provides unintegrated scripts to illustrate the use of DirX in the context of PKI (public Key Infrastructure) and Access Management.

The scripts are installed in
<install path>/scripts/LdapApplications.

Please read the instructions in the files:
<install path>/scripts/LdapApplications/*/README* or
<install path>/scripts/LdapApplications/*/*/README*

  1. The SSE scripts for TrustedCA support the PGP (Pretty Good Privacy) object class and attributes as well.

DirX Manager

The Java-based LDAP management client DirX Manager provides a configurable, platform-independent graphical administration interface for local and remote administration of DirX (and other LDAP compliant servers). DirX Manager provides its own installation procedure. Please refer to the Readme file Documentation\DirXDirectory\DirXManager\Readme.html for installation instructions and for information not provided in the DirX Manager online help and user documentation.

Installing and running the DirX Manager application requires a suitable Java Runtime Environment being installed on the machine as described in the Readme file. Java Runtime version 1.7.0_40 and later rejects server certificates during the SSL handshake, if the server certificate contains a public key with a length of less than 1024 bit. Therefore generally, if a Java based LDAP client application (JRE >= 1.7.0_40) attempts to access a LDAP server using a public key with a length less than 1024, the LDAPS connection fails, if the ldapserver’s key material is less than 2014 bit. The SSL trace file shows a "certificate unknown" alert (0x2e) in this case.

The correctly working Java Runtime Environment should be checked by opening a command shell, and executing the 'java -version' command.

Activate console output redirection to file

In some cases additional debug traces are necessary. For example for ssl problems you may want to set -Djavax.net.debug=all in the run.bat script for the DirX Manager. If java instead of javaw is called inside the run.bat script all the logging goes to the console window.

For large output this is not very user friendly. Now you can define an additional switch in the run.bat:

-Ddirxmanager.redirectconsole=true

Then all stdout and stderr output is redirected to a file.

The file(s) are named like dirxmgr_system.000.log

The number is incremented up to 999 and afterwards a wraparound takes place. This means the files with lower numbers are overwitten. The files are located in: <instpath>/DirX Manager/logs

The files are not deleted by DirX Manager. So the files have to be removed manually. Existing files are overwritten by the next run.

Possibly add some information from the following (source = stackoverflow):

Information on using the JVM flag

-Djavax.net.debug=ssl

all

turn on all debugging

ssl

turn on ssl debugging

The following can be used with ssl:

record

enable per-record tracing

handshake

print each handshake message

keygen

print key generation data

session

print session activity

defaultctx

print default SSL initialization

sslctx

print SSLContext tracing

sessioncache

print session cache tracing

keymanager

print key manager tracing

trustmanager

print trust manager tracing

pluggability

print pluggability tracing

handshake debugging can be widened with:

data

hex dump of each handshake message

verbose

verbose handshake message printing

record debugging can be widened with:

plaintext

hex dump of record plaintext

packet

print raw SSL/TLS packets

System Tuning

To accommodate heavy load conditions, that is, very large databases and/or a large number of clients, your server operating system should be tuned with respect to:

  • unlimited file size for installation user id / root

  • more than 512 sockets (NUMSOM)

  • more than 128 network users (MAXUSERS)

  • more than 500 semaphores (SEMMNU)

  • number of file descriptors per process must be 8192 on LINUX.

Environment Variables

This section provides information how to set environment variables on different operating systems and on useful environment variables not documented in the user documentation.

DIRX_PROTECTED_ITEMS_LDAPNAMES

Optionally print out Protected-Items of ACI in ldap notation. Change Request. The dirxcp and dirxadm command line tools of DirX Directory 8.1A (and newer versions) support a new environment variable DIRX_PROTECTED_ITEMS_LDAPNAMES. If this variable is set with any value, the output of dirxcp and dirxadm in the pretty mode displays the attributes of the protected-Items within an ACI attribute (SACI, PACI or EACI) using the ldapnames instead of the abbreviations specified in the dirxabbr file. The default output without setting the environment is to use the abbreviation.

Example of default output:

        ...
        User-Permissions
        Protected-Items
          Attribute-Type             : UP
                                     : TN
          All-Attribute-Values       : UP
                                     : TN
        Grants-And-Denials           : grantAdd+grantRemove
        ...

Example with set DIRX_PROTECTED_ITEMS_LDAPNAMES=1:

        ...
        User-Permissions
        Protected-Items
          Attribute-Type             : userPassword
                                     : telephoneNumber
          All-Attribute-Values       : userPassword
                                     : telephoneNumber
        Grants-And-Denials           : grantAdd+grantRemove
        ...
The output of ACIs can only be customized for the pretty print mode, i.e when the option -p is specified in the search/show command.
As of DirX Directory 8.3 setting this environemnt result also in printing ldap-style ObjectClass Names contained in Specification Filters of (AcessControl)-Subentries.

DIRX_CONS_KEEP_REFERENCES

By setting the variable in the consumer dirxdsa environment to the value of TRUE (case sensitive), the shadow consumer dsa is configured to ignore the following DSE-Types in incoming shadow update requests: SUBR, IMM_SUPR and XR. (SUPR is an attribute of the root dse and is therefore not a subject of shadowing). This applies to both the existence or the absence of such DSEs in the requests (would result in adding or deleting such entries).

DIRX_LDAP_MAX_PDUSIZE

By default the maximum LDAP PDU size accepted by the ldapserver is 32 MB. The max size can be increased by setting the environment DIRX_LDAP_MAX_PDUSIZE=xx for the ldapserver process, where xx is the max size in MB.

DIRX_NO_SWITCH_RECOVERY

The switch recovery procedure is performed by each Supplier or Consumer DSA at startup time in order to confirm the current Supplier DSA has not changed since the DSA was online. In case network settings or firewall rules etc. prevent the DSP connection to be established or prevent an immediate connection failure, the DSA would hang in the DSP bind.
Export this environment with the value 1 in order to skip the switch recovery bind at DSA startup time. By setting this environment, the local DSA will assume that the Supplier DSA has not changed since it was online.

DIRX_MAP_CERT_ALTNAME_ATTR

DirX 8.10 introduces the possibility to configure the attribute used for mapping (see description of the attribute ldapSASLAuthIdMapping) by setting the environment DIRX_MAP_CERT_ALTNAME_ATTR to the OID of the mapping attribute. The attribute named by this OID must have an IA5Str Syntax. example:
DIRX_MAP_CERT_ALTNAME_ATTR=0.9.2342.19200300.100.1.3
During the sasl bind the user presents a certificate with an altName.email extension containing the value "abele@my-company.com". The DSA searches its whole DIT for an entry having this value in its rfc822Mailbox (with OID 0.9.2342.19200300.100.1.3) and assigns this entry as the bind requestor.

DIRX_SET_TLS_LEVEL_MIN and DIRX_SET_TLS_LEVEL_MAX

DirX 8.10 introduces the possibility to configure which TLS version are accepted by the dirx command line client dirxcp. The accepted range of the TLS version is by default set to TLS1.0 up to TLS1.3. This range can be restricted by means of the environment variables DIRX_SET_TLS_LEVEL_MIN and DIRX_SET_TLS_LEVEL_MAX. The valid values for these are "1.0", "1.1", "1.2" and "1.3".

DIRX_SYSSTART_TIMEOUT

Enhanced Service restart on Linux. The DirX service start mechanism on Linux implemented by the watchdog process dirxdsas has been enhanced. Dirxdsas will now use an incrementally enlarged waittime before killing and restarting the dirxdsa process. A DSA process may need some time to start up, if a database recovery is necessary. The watchdog will now take this into account by performing at most 5 restart attempts in a loop, where the waittime is increasing from initially DIRX_SYSSTART_TIMEOUT seconds (default 30) up to (1+2+4+8+16) * DIRX_SYSSTART_TIMEOUT seconds.

The waittime applied to the dirxadm start command has been adopted.

The dirx watchdog restart loop in the dirx_start procedure of the $HOME/etc/dirx file is no longer needed and has been removed.

Access to DirX Using ADSI (LDAP provider)

Microsoft provides different ADSI versions for its operating systems. Access to DirX using ADSI works successfully from Windows systems with DirX V9.1.

Deletion of profiles with dbamconfig

Deletion of the active DBAM profile is rejected by dbamconfig. dbamconfig -d -P <oldProfileName> is returning error, if the .DirXSync file contains the same profile name -P <oldProfileName>. This behavior was introduced to avoid deletion of the active profile accidentally, since the DBAM database couldn’t be accessed anymore after the deletion.

If it is required to change the device specification of the active profile perform the following steps :

  • Make a backup of the database with dirxbackup if the database is to be reused.

  • Create a new profile first with
    dbamconfig -c -P <newProfileName> <device-spec>

  • Initialize the devices and the .DirxSync file with
    dbamboot -P <newProfileName>
    Now <newProfileName> is the new active profile.

  • Delete the old profile with dbamconfig -d -P <oldProfileName>

  • Optionally restore the saved database with dirxbackup.

watchdog start without systemd on LINUX

The watch process dirxdsas on Linux may be started from a shell. After completing the installation, you can start the dirxdsas using the DirX installation account.
Syntax: dirxdsas -m -d <dirx-inst-path>

DirX crash handler

The settings for the DirX crash handler may have been changed. Please read the notes on this topic which you can find in the ReadMe.txt file installed in the crash directory.

Dirx DSA cache size

DBAM cache is recommended to be set to the total size of the currently used database blocks or larger. Unless the complete database fits into the DBAM cache, some operations may have to read blocks from the disk which results in longer request durations. For example, if a search needs to read in 10000 1k blocks and the disk can read at that time with 10MB/s, then only disk reading will take 1s.

You can get total size of the used blocks by either creating a non-compressed backup and checking the size of the file or from the dbamdevinfo output. To calculate the total size you have to add up the used space in all logical device in the dbamdevinfo output. For example, 3.6 GB of an 8 GB REAL device, 9.2 GB of a 16 GB AVIDX device and 4.4 GB of an 8 GB logical device is used, then the currently used blocks in your database takes 17.2 GB. Now you should consider if your database will grow because more entries will be added or new indexes will be created in the near future. Here in this example a growth factor of 1.3 is considered, because it is assumed that 30% more entries will be added and no new indexes will be created. So the new size is 22.36 GB.

The value of 22.36 GB specifies the amount of memory which is required for data buffers to load the content from disk into the DBAM cache. But the DBAM cache also needs memory for the page headers, for buffer management and a reserve of data buffers for the page version management. So it is required to multiply 22.36 GB with a factor of 1.27. That is 28.4 GB. Since the unit for the environment variable is megabyte you need to define DIRX_DSA_CACHE_SIZE=28400 to specify the size of the DSA cache.

dirxschema tool

The dirxschema tool can be used to extract the currently used schema from a running DirX Directory environment as an ldif file.

USAGE:

dirxschema
    [-h <host>] (Host name or IP address of LDAP server. Default: localhost)
    [-p <port number] (LDAP server’s port number. Default: 389)
    [-s <schema name] (LDAP schema name. Default: cn=schema)

Example:

dirxschema -host <SUPPLIERDSA> -p 389 >supplier-schema.ldif