Installation

This section provides information on how to install DirX.

Initial Installation

The initial installation prepares networking over IDM stack.

Installation Procedure on Windows Platforms

On the English version of Windows systems the default base directory is "C:\Program Files\DirX\Directory" for the 64-bit version of DirX. On Windows systems with other language packages installed than English the default base directory may differ. The base directory for installation is under administrator control: The administrator can choose a different pathname.

It is strongly recommended to run the DirX Service under the administrator’s account. If the DirX Service runs under the system account, it is not possible to perform a dirxbackup command while the service is running.

The execution of the dbam command line tools dbamconfig and dbamboot and the backup tool dirxbackup require to be executed from a cmd shell that was started in the "run as administrator" mode.

Steps of the installation procedure:

Log in as administrator + disable UAC
Install DirX Directory

Insert the DVD. The installation procedure starts automatically. A menu is offered to choose the product.

Choose the DirX Directory product.

Choose from the options offered during the installation steps.

Note that the service must run under an account with administrator rights.

Only the 64-bit version of DirX Directory is available

After the installation procedure on Windows, 4 logfiles can be found on the system:

the InstallAnywhere logging named DirX_Directory_<version>_Install_<date_time>.log located in <dirx-inst-path>/tmp
the InstallAnywhere logging named dirxdirectory_installer_debug.txt located in
<dirx-inst-path>/logs after successful installation, and in
<user_temporary_folder> (C:\Users\<user>\AppData\Local\Temp\) written during first steps of installation
the application log file named dirxdirectory_debug.txt located in <system-temp> (c:\tmp\)

In the latter two files log entries are appended preserving older installation debug logging.

Installation Procedure on Linux Platforms

DirX Directory 10.0 has to run under a normal user id, the DirX account.

Log in as superuser
Mount the DVD on a directory:
mount <dvd-device> <mount-point>
e.g.
mount /dev/scd0 /mnt
Log in under the DirX account
Extract the tar archive to a temporary directory, e.g. /usr/tmp/dirx
```
mkdir /usr/tmp/dirx
cd /usr/tmp/dirx
tar xvf /mnt/Installation/Linux/DirXDirectory/DirXServer64/dirx*
```
tar creates temporary subdirectories containing all files for DirX-SV and an installation script.

At least 25 MB of free disk space must be available in the file system where the temporary directory resides. After installation you can remove the subdirectory dirx.
Install DirX with the script dirxinst
1. cd /usr/tmp/dirx ./dirxinst /usr/tmp/dirx <inst-directory>
  where the installation folder <inst-directory> may be the HOME folder of the DirX account or a special dedicated installation folder owned by the DirX account performing the script.
2. Log in as superuser
3. cd /usr/tmp/dirx bash ./dirxinst_root /usr/tmp/dirx <HOME folder of the DirX account>
  The second argument must be the HOME folder of the DirX account.
  
  If installing for an ActiveDirectory based user account, the userID of this account must be given as third argument of dirxinst_root script:
  bash ./dirxinst_root /usr/tmp/dirx <HOME folder of the DirX account> <userID>
  This script changes access permissions on executable files and changes systemd configuration data.
  
  The scripts also assume that Bash is the login shell of the DirX account. dirxinst inserts therefore the call to .dirxrc into the $HOME/.bash_profile. In case the Bash is not the login shell, the call to .dirxrc is inserted into $HOME/.profile.
  
  without execution of .dirxrc during the login procedure pathnames will not be set correctly. It also adds settings to the user’s .bash_profile.
4. Again log in under the DirX account. (Due to the .dirxrc call in your .bash_profile, some important variables are set when performing the login process.)
5. Remove the temporary tar extract
  rm -r /usr/tmp/dirx

After the installation procedure on Linux, a logfile can be found on the system:

the installation log file is stored in <inst-path>/tmp and is named dirx_install_<date>_<number>.log.

Each installation creates a new installation log file, the _<number> part of the name is used only if a file with that name already exists.

Use of systemd on Linux

The systemd is the default service used to control the DirX Directory service.

The DirX installation comes with a template file <DirXaccount>/etc/dirx.service, that is adjusted to the DirX Account by the dirxinst script (replacing the string DIRINST by the actual path to the DirX installation folder) similar to the file <DirXaccount>/etc/dirx . The file <DirXaccount>/etc/dirx ist called from the etc/dirx.service file with the parameters "start" or "stop" through the ExecStart and ExecStop directives in the [Service] section similarly to the former SysV mechanism. The dirxinst_root script copies the dirx.service unit file to the folder /usr/lib/systemd/system.
dirxinst_root creates two files in /usr/lib/systemd/system: dirx-listen.socket and dirx-listen@.service. They contain the necessary information about the listening port, the DirX Account and the start script.

Then systemd is updated and the DirX listening and boot service are enabled and started:

  # systemctl daemon-reload
  # systemctl enable dirx-listen.socket
  # systemctl start dirx-listen.socket
  # systemctl enable dirx.service
  # systemctl start dirx.service

The systemd status can be displayed with "systemctl status" or "systemctl status dirx-listen.socket" for the dirx-listen.socket only. Failed services are displayed with "systemctl --failed". Further information about a failed service with process-ID <pid>, which is found in the status information, can be displayed with "journalctl _PID=<pid>".

To deinstall the DirX configuration for systemd, you have to run dirxdeinst as root.

The scripts dirxinst_2nd and dirxint_2nd_root for parallel DirX installations avoid collisions in service unit file names by prefixing them with the alternate DirX account name.

Change of the default service port

DirX uses by default the port 5800 to communicate with the service start demon process of the system. In case this port number is already in use, you may change the value by editing the script dirxinst_root. Replace the portnuber 5800 in the assignment
DIRX_DEF_PORT=5800
by the desired port number value.

Note that you will have to supply the specific port number in the dirxadm start command sys start -port <specific-port-number> in order to start the DirX service on the local host.

Enable schema LDAP name checking according to standard

Strict LDAP name checking is disabled by default for compatibility reasons with older versions. In a new installation environment (with empty database) the flag "set DIRX_DSA_ENABLE_SCHEMA_STRICT_NAME_CHECK=1" should be added to dirxenv.ini in order to ensure better compliance with RFC. With this setting invalid attribute or object class names will be rejected by DSA. Name syntax is described in "Syntaxes and Attributes" "2.7.1 Attribute-Type-Description" and "2.7.2 Object-Class-Description".

Second DirX-installation on a LINUX-Server

In DirX 10.0 installation and deinstallation scripts are provided that allow to install and run a second instance of the Dirx Directory service on one Linux host.

Prerequisites and general Remarks:

systemd is up and running
Each such DirX installation has to be performed under a different LINUX user account only
Each such DirX installation (except the very first one) has to be configured separately after unzipping the DirX package to a temporary folder. This configuration task comprises in separating the various port settings.
Don’t setup log, audit or even conf folders to a common shared disk folder. This means, each DirX installation has to use of its own log, audit and conf folders.
Keep in mind that the number of sockets is limited to 64K per LINUX server instance. Thus, it is not recommended to establish more than two DirX installations per HW server.

It is assumed, there is one DirX installation performed in default mode under a certain user account (e.g. dirx01). Now, a second DirX installation is planned to be established under the new user-account (e.g. dirx02). To summarize all based on user accounts:

user=dirx01:

default DirX installation while applying the common installation scripts dirxinst and dirxinst_root (see $HOME)

user=dirx02:

second DirX installation to be configured first while applying the variant of the scripts for the second installation, i.e. dirxinst_2nd and dirxinst_2nd_root.

The second DirX user-account must not be "dirx" as this name is internally reserved for the first (default) DirX installation already.

Preparing the second DirX installation

These steps have to be performed as user=dirx02

Create a new folder under $HOME/temp (e.g. /home/dirx02/temp)
mkdir $HOME/temp → userName=dirx02
Extract the DirX-V9x package in the new $HOME/temp folder.
gzip -dc dirx100_10.0.xxx.ddmm.x86_lx-64.tar.gz | tar xf -
Adapt dirxinst_2nd for your needs, as follows:

Performing the second DirX installation

These steps have to be performed as user=dirx02

Passed parameters:

$1: pathname of the unpacked DirX package
$2: DirX installation pathname
PSAP port number:

The default port in the DSAs PSAP is set to 22200 in the second DirX installation. If you wish to use another port number, change the value in the following statement in dirxinst_2nd
```
vcomplete[v_NoElem]="DIRX_OWN_PSAP=\"TS=DSA1,NA='$SPEC_COM'TCP/IP_IDM!internet='$DIRX_LOCAL_IP'+port=22200'$SPEC_COM'\"";
```
DSA PMAP port number:

The default port for the DSA RPC portmapper is set to 8999 in the second DirX installation. If you wish to use another port number, change the value in the following statement in dirxinst_2nd
```
vcomplete[v_NoElem]="DIRX_PMAP_PORT=8999
```
LDAP PMAP port number:

The default port for the LDAP RPC portmapper is set to 9999 in the second DirX installation. If you wish to use another port number, change the value in the following statement in dirxinst_2nd
```
vcomplete[v_NoElem]="DIRX_LDAP_PMAP_PORT=9999
```
DSA name

The default DN for the DSA is set to "CN=${userName}-DSA-${DIRX_HOST_NAME}", where $userName expands to the Linux account name and ${DIRX_HOST_NAME} to the hostname of the machine. If you wish to use another name, change the value in the following statement in dirxinst_2nd
```
DIRX_DSA_NAME="CN=${userName}-DSA-${DIRX_HOST_NAME}"
```

Completing the second DirX installation

These steps have to be performed as user=root

Passed parameters:

$1: pathname of the unpacked DirX package
$2: DirX installation pathname

Assignments made in dirxinst_2nd_root

The script dirxinst_2nd_root sets xinetd listening port to 15800 by means of the following assignment:

DIRX_DEF_PORT=15800    ... listening for the system

Automatically assigned in dirxinst_2nd_root:

SYSTEMD_DIR=/usr/lib/systemd/system
SYSTEMD_LISTEN=${userName}-listen
SYSTEMD_LISTEN_SOCKET=$SYSTEMD_DIR/${SYSTEMD_LISTEN}.socket
SYSTEMD_LISTEN_SERVICE=$SYSTEMD_DIR/${SYSTEMD_LISTEN}@.service

Automatically added to /etc/services:

${userName}   $DIRX_DEF_PORT/tcp    # DirX service for user ${userName}

Automatically created in $SYSTEMD_DIR (default-file: dirx-listen.socket)

New file name:  $SYSTEMD_LISTEN_SOCKET with following content:
-
[Unit]
Description=DirX listening socket

[Socket]
ListenStream=$DIRX_DEF_PORT
Accept=yes

[Install]
WantedBy=sockets.target
-

Automatically created in $SYSTEMD_DIR (default-file: dirx-listen@.service)

New file name:  $SYSTEMD_LISTEN_SERVICE with following content:
-
[Unit]
Description=DirX start listen service

[Service]
ExecStart=/home/${userName}/bin/dirxdsa.sh
User=${userName}
StandardInput=socket
-

Automatically processed:

systemctl daemon-reload
systemctl enable ${SYSTEMD_LISTEN}.socket
systemctl start  ${SYSTEMD_LISTEN}.socket

Post second installation tasks

Make the settings in $HOME/.dirxrc effective

. $HOME/.dirxrc  (or while relogin with: su - dirx02)

Port settings (in particular the DAP port settings in config files)

Assign the same DAP-Port (as assigned before in C-1) in:
```
<inst-path>/client/conf/dirxcl.cfg and <inst-path>/ldap/conf/dirxldapv3.cfg
```
e.g. like:
/CN=DirX-DSA TS=DSA1,NA='TCP/IP_IDM!internet=127.0.0.1+port=22200'

LDAP configuration subentries

Prior to startup the DirX-Service with dirxadm make sure the LDAP port numbers (plain ldap as well as secure ldap port) may by distinct to those ones used in DirX service-1 (user=dirx01) otherwise the DirX-Service-2 (user=dirx02) will refuse to startup. In this case, first start the dirxdsa process manually and continue modifying the respective ldap numbers accordingly, i.e. modify the respective ldapConfigurations via DAP by replacing the attributes LPNU and LSPN with the values of the desired ldap ports.

In terms of a floating master configuration on the same HW-Server, at least two ldapconfiguration subentries now will have to be established, one for the DB-Master (e.g. user=dirx01) and one for the DB- Consumer (e.g. user=dirx02) in order to apply distinct ldap port numbers for both DirX services running on the same HW-server. Use the environment variable DIRX_DEFAULT_LDAP_SERVER to define the ldapconfiguration name referring to the alternate default ldapserver port for the second DirX installation.
In case of more than 1 ldapserver per installation specify values for the DIRX_ADDITIONAL_LDAP_SERVERS environment variable in each DirX installation.

Automatic DirX-Startup on server reboot
1. First DirX-Installation
  1. Follow the instructions in the ReleaseNotes
2. Second DirX-Installation
  1. Copy $HOME/etc/dirx to $HOME/etc/<userName>
  2. Edit $HOME/etc/<userName> while applying the same port number (DIRX_DEF_PORT - see dirxinst_2nd_root) to the dirxadm-start command
  3. Follow the instructions in the ReleaseNotes while applying the new $HOME/etc/<userName>

Deinstalling the first and the second DirX installation

In order to remove the second DirX installation apply the script dirxdeinst_2nd running in root-user mode after stopping the DirX service in scope.

If one wants to remove the first (user=dirx01 here) DirX installation, also stop the DirX service of user=dirx02 and apply the dirxdeinst script running in root- user mode

In case of a single DirX installation apply the common dirxdeinst script instead running in root-user mode.

During deinstallation all files and folders below <dirx-inst-path> which were created by the install script will be deleted. This includes all private files and folders in these install script created subfolders.
Private files/folders added directly under <dirx-inst-path> will be preserved during deinstallation.

Upgrade Installation

An upgrade installation does not clean up the existing installation folders. The following existing configuration files will not be overwritten:

dirxcl.cfg
dirxldap.cfg
idmssl.cfg
rpcssl.cfg
ldap/conf/dirx_pkcs12.pwd
ldap/conf/cert_ldapserver.p12
ldap/conf/cert_ldapserver.der
client/conf/trusted_ca.pem
conf/snmptraps.cfg
conf/dirx.lic
conf/dirx.lic.sig
monitoring/supervisor/setup_common_data.tcl
http/conf/dirxhttp.cfg
http/conf/http.pem
http/conf/http_pkcs12.pwd

The dirxabbr file format has not changed, but some new elements may have been added. The dirxabbr file of the old DirX version is renamed to "dirxabbr.old".

Create application-specific dirxabbr-ext files with all your project specific extensions. You avoid to re-enter your project-specific extensions to the newly installed dirxabbr file when you perform an upgrade installation in future. See section "Abbreviation Files" in the DirX Administration Reference for details.

All other existing files will be overwritten when they also exist on the installation DVD, for example dirxlog.cfg.

Before you start the upgrade processes it is recommended to save the existing database with dirxbackup, and also export it to LDIF files.

The format of DSA audit files and LDAP audit files has been changed. Before performing the DirX upgrade installation you should evaluate the binary audit files with the dirxauddecode or dirxaudstatistics tool of the predecessor version. Before starting DirX service after upgrade installation the audit.log files from DSA and LDAP server should be removed since their format is incompatible and the DirX service might not start.

DirX Directory introduced a stricter LDAP name check in schema (switched off by default). This verification might be turned on in future releases. In order to prevent any problems with future releases, this is a good opportunity to test whether your existing DB complies to the rules.

Steps to do this verification:

step 1: Start a new terminal window
step 2: Set environment variable: "set DIRX_DSA_ENABLE_SCHEMA_STRICT_NAME_CHECK=1"
step 3: Execute "dbamverify -D" on the online DB or on a backup. This will display a list of found invalid names, if any.
step 4: Rename the listed invalid attribute or object class names to be standard compliant.

Upgrading DirX DSAs within a shadowing environment takes much more attention then an upgrade of a standalone DirX DSA. Please read carefully chapter "2.4 Upgrade Installation in a Shadowing Environment" in this document.

The LDAP controls supported by the current version of the DirX DSA are stored in the SCON attribute of the /CN=ldapRoot element of the database. This information will only be added at database creation time (dbamboot), and will not be updated automatically during a later upgrade installation.
If the database was created with an older version of the DirX DSA, the list of supported LDAP controls must be updated manually via dirxadm after the upgrade installation.

New DSE type checks have been introduced in dbamverify, which upon detection of errors previously unseen, will block any new backups to be made. Therefore, it is highly recommended to take a backup right before switching to the new version.

Upgrade Installation on Windows

It is required to close the Windows Event Viewer and the Windows Service Manager before starting the DirX upgrade installation on Windows.

To upgrade your previous installation, install DirX V10.0 from your DVD as described in section titled "Initial Installation" above. The installation procedure performs an automatic data migration.

Upgrade Installation on Linux Platforms

Follow the instructions given in Installation Procedure on Linux Platforms to overwrite the existing installation with the new release.

Upgrade installation and database migration

Upgrade Installation from DirX Directory 9.0 and later versions

The DBAM database structure of DirX Directory 9.0 and later versions is fully upward compatible with that of DirX Directory 10.0. An upgrade installation is possible without performing any DBAM database conversion procedures. However, due to new features and functional changes in DirX Directory 10.0 additional migration steps are required as described later in this chapter.

Migration of cert8.db key material

Run the following command in the folder, containing cert8.db and key3.db.

"C:\Program Files\DirX\Directory\bin\certutil.exe" -L -d .

Go through the certificates and dump them to a pem file by using the following command

"C:\Program Files\DirX\Directory\bin\certutil.exe" -L -d . -a -n DirXDemoCA > DirXDemoCA.pem

Each folder which contained a cert8.db certificate database file, should contain a new trusted_ca.pem. All the exported CA certificates should be added to the trusted_ca.pem. The certificate files used for SASL authentication, should be exported as pem files and can be later referred by corresponding commands.

An example, for exporting the certificate of cn=Mayer,ou=Sales,o=My-Company:

"C:\Program Files\DirX\Directory\bin\certutil.exe" -L -d . -a -n mayer > mayer.pem
pk12util -o mayer.p12 -n mayer -d .
openssl pkcs12 -in mayer.p12 -nocerts -out mayer.key

Example usage:

dirxcp> bind -sasl -mech EXTERNAL -certpath mayer.pem -privatekeypath mayer.key -privatekeypassword dirxdirx -prot ldapv3

As cert8.db is not supported anymore, all client calls using SASL bind should also be migrated. The affected tools are

dirxcp
dirxmodify
dirxcmph
dirxextop

Upgrade installation in a shadowing environment

Upgrade from DirX Directory 9.0 or newer

Upgrading from DirX Directory 9.0 or newer to DirX Directory 10.0 requires no further migration steps with respect to shadowing.

You are free to start the upgrade on your master or on any of your consumers as long as you do NOT use UNIQUE indexes. If UNIQUE indexes are used and the agreement to consumer has "REPLS=TRUE" meaning consumer can replace supplier, then you MUST start the upgrade on the master.

Uninstallation

This section describes the uninstallation on Windows only. For Linux uninstallation, see section Deinstalling the first and the second DirX installation.

On Windows, the prerequisite for successful uninstallation of DirX Directory is the presence of 64-bit Java Virtual Machine version 11. When this JVM is present, it should be possible to start the uninstallation from both the Add and Remove system settings or from the command-line by executing "Uninstall DirX Directory.exe" from the <dirx-inst-path>\UninstallerData directory.

If problems occur during uninstallation, refer to the "Known Problems" section Uninstallation on Windows for possible solutions.

During uninstallation all files and folders below <dirx-inst-path> which were created by the installer will be deleted. This includes all private files and folders in these installer created subfolders. Private files/folders added directly under <dirx-inst-path> will be preserved during uninstallation.

Code Signing and Verification

At this release, signature files named <original_name>.sig are supplied for all executables and dynamic libraries delivered with DirX. These signature files can be used to verify that the code has not been altered or corrupted since it was signed.
To perform the verification, use the verify.sh (Linux) or verify.bat (Windows) script in the folder <DIRX_INST_PATH>/signing and specify the full path of the public key for verification "dxd_sign_public.pem" on the command line. This public key is contained in the folder <DIRX_INST_PATH>/signing and can also be downloaded from the support portal. For further details, see the section "Code Signing Files" in the chapter "DirX Directory Files" in the DirX Directory Administration Reference.

Troubleshooting Installation Problems

InstallAnywhere Disk Space Check

see: https://community.revenera.com/s/article/disk-space-check

Synopsis

Installers built with InstallAnywhere run native commands in order to calculate the amount of free disk space on the target machine. On many non-Windows operating systems, the "df" command is used to check the available space. Because of the huge variety of return output from "df", InstallAnywhere will occasionally fail to parse the output appropriately. If this happens, InstallAnywhere may believe there is not enough free disk space and may not allow the users to install.

Mitigation

By setting an environment variable named "CHECK_DISK_SPACE" to "OFF", and making sure its status in the environment will be accessible to subprocesses, the installer will force the install to assume there is sufficient disk space and not run the action again under the same rules of preemption.

On Windows the simplest way to utilize the Environment Variable method is to open a Command Prompt and type the following:
C:\> set CHECK_DISK_SPACE=OFF
Then the installer should be run from this window (i.e. in the same "scope").

On UNIX in csh/tcsh set the variable this way:
% setenv CHECK_DISK_SPACE OFF
and run the installer within that shell.

On UNIX in sh/ksh/bash set the variable this way:
$ export CHECK_DISK_SPACE=OFF
and run the installer within that shell.