1. Download installation package

First, the latest procman-X.X.XX.zip (e.g. procman-5.0.12.zip) must be downloaded from the customer portal and then it must be unzipped.

This installation package contains the components HWI (HORIZONT Web-application Interface), HWM (HORIZONT Workflow Manager), and HOS (HORIZONT Hand-Over System).

Login as an administrator on the Windows server where ProcMan shall be installed. Extract the ProcMan setup files from the package procman-5.0.X.zip in a setup directory on the server. Now open the setup directory.

2. Setup setup.rsp file

To install ProcMan, it is recommended to use the setup.rsp file. This is located in the extracted directory and can be edited with any editor. Open the file and adjust the installation opens.

To install ProcMan e.g. with the JCL module (but without IWS), the following parameters should be set in setup.rsp file. Parameters, which are not listed below, must not be adjusted.

Important information

If ProcMan is installed several times on one PC/Server, the APP_URL, APP_INSTALL_NAME, SESSION_NAME etc. must be unique.

HORIZONT_ROOT=C:\Horizont
…
APP_INSTALL_NAME=procman
...
APP_DOCU=Y
…
APP_TWS=N
…
APP_IWD=N

HDB (PostgreSQL)

If the HDB (HORIZONT Database / PostgreSQL) should be used, the parameters for APP_DB_HOST, etc. have to be set.

3. Run the installation

To start the installation, simply run the setup.cmd as administrator. Check all settings again in the CLI. After the installation, the HORIZONT Apache Webserver service needs to be restarted.

If a DB2 database is used, ProcMan needs to be able to communicate with the DB2 database. Therefore the DB2 PHP Extension needs to be activated.

To activate the extension, open the installation directory of HWF (c:/HORIZONT/hwf/php/php.d/). Open the file ibm_db2.ini with an editor. To activate the extension, row 6 must not be commented out. If you make changes to the file, the HORIZONT Apache Service needs to be restarted. See the picture below.

How to check if the extension is active:

At first, the windows code page should be changed on the target system in order to make sure that the communication with a DB2 database works without problems.

The environment variable DB2CODEPAGE=1208 has to be set on the ProcMan server before the installation of ProcMan can be started. This informs DB2 Client that all strings passed to the database are already UTF-8 encoded and there is no need to encode it again, to store them into tables using UTF-8 encoding. Otherwise the strings inserted into the database tables become longer than expected and eventually cause errors because they exceed the maximal length of database table columns.

There are possible 2 options to do that:

Option A

Use the windows search bar and search for "environment". Open the "Edit environment variables" app. Now click on "environment variables", a new window should appear. In the lower window ("system variables") change the value of the variable "DB2CODEPAGE" to 1208. If the variable doesn't exist, you have to create a new one.

Option B

Open the CLI, and use the commaned set. All defined environment variables should be shown now. In order to change the value of the variable "DB2CODEPAGE" to 1208, execute

set DB2CODEPAGE=1208

To check if the variable was successfully set, type in the command

set DB2CODEPAGE

General Information

This guide describes the installation of ProcMan on a Windows Server or normal Windows PC.

Important

The following guide will describe how to install ProcMan in the directory c:/

After ProcMan has been installed, you can continue setting up processes in ProcMan.

Overview

This document provides guidance on configuring the IBM DB2 Command Line Interface (CLI) for optimal performance and compatibility with ProcMan. The settings ensure efficient transaction handling and improved performance by adjusting the default behavior of the DB2 client.

DB2 Client Installation

1. Download the latest DB2 Client for Windows (For HORIZONT installations see v:/download/DB2_DSClient_11-1_Win_x86-64).

2. Run the setup.exe, select new installation, and accept the licence agreement. Start the installation.

3. Navigate to the installation directory (e.g. c:/program files/IBM/SQLLIB/BIN/db2cmdadmin.exe) and execute the db2cmdadmin.exe, the Command Line interface (CLI) should open now.

4. Execute the command db2 in the CLI, the DB2-Client CLI should start now.

Connect the client to the database

Now you need to connect to the DB2 Database.

In the ProcMan Installation package, you should see a file called add_connection_example.db2 in the directory /DB2. Open that file in your preferred editor (e.g. notepad++). Copy the last 6 rows (see code below) one after another and execute them in the CLI.

Important: Do not copy the semicolons. You should get positive feedback for each command in the CLI.

Testing the DB2 connection

To test the connection to the HORIZONT DB2 Database, execute the following two commands in the CLI.

You should get a positive response in the CLI, like in the picture below.

Recommended configuration options

The following addtional configurations are recommended.

TXNIsolation

• Setting: TXNIsolation=1

• Meaning: Sets the transaction isolation level to Read Uncommitted

• Effect: Allows dirty reads, enabling higher performance with minimal locking

DB2Optimization

• Setting: DB2Optimization=5

• Meaning: Enables a higher level of CLI optimization

• Effect: Improves execution speed and efficiency by pre-packaging SQL statements more aggressively

Option A: Edit db2cli.ini

This option is recommended if file access is available.

Open the following file: c:\Users\All Users\IBM\DB2\DB2COPY1\cfg\db2cli.ini (beware that this default path of the file can be overwritten in the system variable DB2CLIINIPATH

For older DB2 Client versions the default path is: c:\Program Files\IBM\DB2\DB2COPY1\cfg\db2cli.ini

Add the following lines under the section for your database alias:

Option B: Use DB2 CLI Commands

This option is recommended if no file access is available and if your user is part of the DB2ADMIN group on the ProcMan server.

1. Open the DB2 Command Line Processor (db2cmd) on the ProcMan server

2. Run the following commands:

Replace <DBALIAS> with your configured database alias.

For to check if the options have been set correctly execute the following command:

Catalogue database

The database, which shall be used by ProcMan, has to be cataloged in the DB2 Client in a way that the user authentication is done by the DB2 Server:

This ensures that DB2 Client does not try to authenticate the user used for establishing a database connection on the client system (where DB2 Client is installed), but sends the user information for authentication immediately to the DB2 Server, which leads to a better performance.

Troubleshooting

Licence error

If you get an licence error while executing the command

you need to install a licence. Ask some one like Jörg/Rado for the licence file db2consv_zs.lic, place it on your PC, open the CLI, navigate to the directory where the licence file is stored and execute the command

to install the licence. To check if the licence was installled correctly, execute the command

db2cmdadmin window opens and immediately closes

Connect with the server with remote desktop. Go to computer management and two groups. First, create local DB2ADMNS and DB2USERS groups and add your user to that group. Then, add the Domain Account to one or both of these groups. These groups are the default groups recognized by DB2. Members of the DB2ADMNS group have SYSADMIN Authority. Members of the DB2USERS group do not have SYSADMIN Authority but are able to execute DB2 commands. Also use the CLI (as admin) and execute the command 'db2extsec'.

Next, from a Windows Command Prompt execute:

Now the db2cmdadmin CLI should open and not immediately close.

ProcMan requires PHP and a Webserver, which we deliver in the so-called HORIZONT Web Framework (HWF). This document only describes how to install HWF for ProcMan.

1. Download HWF

Download the latest HWF installation package from the HORIZONT customer portal (e.g. HWF V6.0.6) and extract it somewhere on the target system.

2. Optional: Install/update the Microsoft Visual Studio C++ runtime

Install/update the Microsoft Visual Studio C++ runtime (MSVC) manually. Navigate to ../hwf/contrib/ and search for all the vcredist_x64-YYYY.exe files. Run them all as administrator.

3. Run the setup.cmd

Now run the setup.cmd in the downloaded HWF package as administrator and follow the installation steps.

Important things to consider:

• In step 1 set the correct installation directory of the existing HWF installation.

• In step 4 choose "no" if you decided to install/update the MSVC manually.

• There is no need to set the TNS_ADMIN and DB2INSTANCE options in the HWF installation dialog for ProcMan, as they are ignored. They can be left empty (which is the default).

• Do not install HDB (HORIZONT Database Module) after the HWF installation, which is asked in the HWF installation dialog after HWF installation finished.

4. Enable full version of DB2 client

There is a light version of the DB2 Client installed with HWF. After the installation of HWF the PATH system variable contains the path to this light version of the DB2 client in the beginning, which disables the full version of the DB2 client required by ProcMan.

To correct this, after HWF installation, remove from the content of the PATH variable the following part:

%HWF_ROOT%\LIB\DB2\BIN;

After changing the content of the PATH variable you have to restart the Web Server (e.g. in Windows’s Services dialog restart the HORIZONT HTTP Server service) before the change takes effect.

5. Verify HWF installation

6. Recommended: Configuring the HWF service to run with a special user

Windows

By default, the HORIZONT HTTP Server service runs under the Local System account, which is highly privileged—more so than a standard administrator account in certain areas. For better security and manageability, it is strongly recommended to run the service under a dedicated local or domain user account with limited privileges.

This guide walks you through:

• Creating or assigning a restricted user

• Granting required filesystem and DB2 access

• Running the service under the new user

• Configuring permissions to allow restarting the service from ProcMan

Step 1: Create or Select a Service User

1. Create a local user in Windows or use an existing local/domain user.

2. Ensure the user has a non-expiring password.

3. Grant this user modify permissions on the HORIZONT installation directory (by default C:\HORIZONT) and all its subdirectories.

Step 2: Assign DB2 Access (if applicable)

If the DB2 Client was installed with Windows Authentication, it creates two local user groups:

• DB2ADMNS

• DB2USERS

Add the service user to the DB2USERS group to allow DB2 access while maintaining minimal privilege.

Step 3: Configure the Service to Run Under the User

1. Open the Services management console:

   Control Panel → System and Security → Administrative Tools → Services

2. Locate the HORIZONT HTTP Server service.

3. Double-click to open its properties and go to the Log On tab.

4. Select "This account", enter the user credentials created/selected in Step 1, and confirm.

5. Click OK and restart the service.

Step 4: Allow the User to Restart the Service via ProcMan

By default, only administrators and system accounts can start/stop services. To allow the non-admin service user to restart the web server (e.g. via ProcMan), follow these steps using the Microsoft Management Console (MMC):

A. Prepare a Custom Security Template

1. Open MMC as administrator:

   • Press Win + R, type mmc, and press Enter.

2. From the menu: File → Add/Remove Snap-in…

3. Add the following snap-ins:

   • Security Templates

   • Click OK

4. In the Security Templates tree, select a directory (e.g., C:\Windows\Security\Templates) and then:

   • Action → New Template

5. Enter a name and (optional) description for the template and click OK.

B. Define Service Permissions in the Template

1. Under your new template, go to: System Services → HORIZONT HTTP Server

2. Right-click and select: Action → Properties

3. In the dialog:

   • Check: "Define this policy setting in the template"

   • Set Startup mode to Automatic

   • Click Edit Security

4. In the security dialog:

   • Add the dedicated service user

   • Grant the permission: Start, stop, and pause

5. Click OK to close all dialogs and save the template.

C. Apply the Security Template

1. Again, open: File → Add/Remove Snap-in…

2. Add: Security Configuration and Analysis Click OK

3. In the snap-in:

   • Action → Open Database

   • Choose a name for the database file (e.g. horizont_service_config)

4. When prompted, select the template you created earlier.

5. Then run: Action → Configure Computer Now

6. After applying, restart the HORIZONT HTTP Server service once manually as an administrator to ensure new permissions take effect.

Important Notes

• These permission changes are persistent and survive system restarts.

• The MMC interface may vary slightly between Windows versions.

• Always verify service functionality after changing its user context or security settings.

Linux

The web server switches automatically after it is started to run under a lower privileged user. So there is nothing to be done explicitly.

If it should be later possible to restart the web server by an administrator from the ProcMan dialog, the user under which the web server is running, has to be authorized to restart the web server. For this the user has to be authorized to start the httpd program as a super user using the sudo command without a tty session and without entering a password. To allow this open the file /etc/sudoers for editing. If there is a line like this

Defaults requiretty

comment it out with a hash (#) in the beginning of the line. Further add a line like this

<httpd_user>     ALL=    NOPASSWD: <http_path>/httpd

in the file /etc/sudoers. Replace <httpd_user> by the proper user name. Replace <httpd_path> by the proper path to the httpd program. For example:

procman     ALL=     NOPASSWD: /usr/sbin/httpd

hos_db_config.php

Important note: During the installation of ProcMan or HWM only the file hwm_db_config.php is created automatically and correctly filled. In all other configuration files, where the database connection, alias, DB user, password etc. appear, the values must be set manually.

So the next thing to do is to adjust the hos_db_config.php file e.g. located in c:/horizont/procman/etc/hos_db_config.php.

This configuration file is used to define the database connection from ProcMan to e.g. the DB2 database (in addition to hwm_db_config.php).

In the 'db' section at the very bottom, the correct "prefix", "alias" and "pwd" (see in the hwm_db_config.php) must be set.

The configuration dialog has the following two parts: Basic configuration, Database configuration. Go through the dialog screens, fill the requested data and continue to the next screen by clicking the Continue button.

First page

Single Sign-on

In this section the Single Sign-on authentication may be selected. Select ‘-‘, if there is none in use. Currently only the IBM Tivoli Access Manager WebSEAL is supported here.

Log file

This section of the dialog allows specifying where to write the log files and what message level shall be logged. If the dialog is started for the first time, the path of the log file is preset depending on the settings in the etc/hwi_config.php file. The file name may contain the sequence $D$, which means that every day will be opened a new log file and the sequence is replaced in the real file name by the current date, e.g.

D:/log/ProcMan/hwm-$D$.log

Following Message levels are accepted:

Intervals for user and activity status update

This section allows configuring the feature that for long time active activities automatically change their status to pending.

The user login status interval specifies how often the information that a user is logged-in is actualized in ProcMan. The value means count of minutes. The value must be an integer greater or equal 0 (zero). If set to 0 (zero) the updating of the user login-in status as well as the automatic change of activity status from active to pending is switched off.

The activity status interval specifies that after the last update user of an active activity is not logged-in for this time, the status of the activity shall be automatically set to pending.

The value means count of minutes. The value must be an integer greater or equal 0 (zero). If set to 0 (zero) the automatic change of activity status from active to pending is switched off.

SMTP

Here the SMTP server for sending alarm e-mails can be configured. If the SMTP server supports SSL encryption it can be used by specifying the SMTP server IP/DNS prefixed by ‘ssl://’ (e.g. ssl://smtp.my_company.com) and the port on which the SMTP server accepts the SSL encrypted communication (default is 465).

Put the IP address or DNS of the ProcMan Server in the Client computer for identification at the server field.

Second page - Database configuration

On the second page, the DB2 parameters must be set so that ProcMan/HWM can communicate with the DB2 database. The customer normally provides the DB2 database information.

The checkboxes for "Create Database", "Initialize Database", and "Only generate Scripts..." should be set.

Detailed description of page 2 - Database configuration

Basically HWF supports following Database system types: DB2 (z/OS), Oracle, PostgreSQL. The dialog differs slightly depending on the Database system type selected.

• The current ProcMan version and HOS (JCL) supports only DB2 on z/OS,

• Special parameters for DB2 are the Alias and the Table Qualifier.

• Special parameters for Oracle are Host (IP address or DNS name), Port and Database Name.

Special parameters for PostgreSQL are Host (IP address or DNS name), Port, Database Name and Schema. Other parameters are the same.

Table name and Index name templates are optional and are dedicated for cases, when the Customer has special conventions for table/index names.

For example if the tables shall be named in the range ABCDT00 – ABCDT99 and indexes in the range ABCDI00 – ABCDI99, put in as the Table name template ABCDT__ and as the Index name template ABCDI__. The __ (two underscores) is then replaced by a running number in the generated SQL statements.

In User, Password and Repeat Password put in the information about the technical user which will be used by HWM for the Database access. The information about the technical user will be stored in a configuration file, the password will be encrypted.

Check the Drop database checkbox if you want to replace already existing Database.

Check the Create Database checkbox if:

• you want that a new Database (schemas, tables, indexes, etc.) shall be created by the dialog

• the Database already exists and you want to drop it and create newly,

• you want only to generate the Database definitions in a file. The file can be reviewed and maybe send to z/OS and executed there by e.g. SPUFI or a batch job.

Check the Initialize Database checkbox if:

• you want to fill a newly created Database with initial data,

• you want to delete all data in the Database and initialize it newly.

Check the Migrate data checkbox if:

• you want to migrate data in a newly created migration database,

• you want to reinitialize the data in the current database with the data from an existing migration database.

If at least one of the Create Database and Initialize Database checkboxes is checked and the dialog is submitted, the configuration procedure generates a file DBDefinition.sql in the database subdirectory of the ProcMan installation. It contains all SQL statements needed for creation and/or initialization of the database. This file has no influence on the run of HWM.

It may be useful if you do not have database administration rights at the time of HWM configuration. In this case you can send this file to your database administrator to check, adjust and execute the SQL statements in this file.

If none of the Create Database and Initialize Database checkboxes is checked and the dialog is submitted, only the Database access settings are saved.

Check the ‘Only generate scripts checkbox’ if you only want to generate the SQL statements into the file database/DBDefinition.sql described above without creating and/or initializing the database.

If the Drop/Create Database checkbox has been checked a further dialog is being shown after submitting.

The user specified in admin user and password is being used only for the Database creation. The information about the admin user will not be stored anywhere (in opposite to the technical user on the previous screen).

The Database Name, Table Space, Database creation parameters, Tablespace creation parameters, Table creation parameters and Index creation parameters fields are shown only in the DB2 variant of the dialog. Put in meaningful parameters as they will be used for the Database creation. The Table Space name may contain a sequence of two or more underscores to specify that for every table a new table space shall be created. The sequence of underscores is in the generated SQL statements replaced by a running number like in the Table name and Index name templates in the previous dialog screen.

The Database/Tablespace/Table/Index creation parameters may contain any parameters accepted by DB2 for the respective database object type. When the dialog is running for the first time they are initialized by default values.

In the Users to be admin granted parameter database users which shall be granted to be admins of the database can be specified as a list (one user name in each line).

The Only generate scripts checkbox is the same like on the previous screen.

Protection of the Configuration dialog

Because the Configuration dialog is being started via an Internet Browser it could be started later by any user of HWM from any client computer. To allow this could have fatal follow-ups because everyone could change the HWM configuration. Therefore the Configuration dialog has a built in protection. At the end of the first successful run of the dialog, it generates a file hwm_install_blocker.php in the etc subdirectory of the ProcMan installation. This file contains only one option:

$hwm_install_blocker = true;

If the file exists and the value of the option $hwm_install_blocker in the file is true, every try to start hwm_install.php by any user ends with an error message. If you need to start the Configuration dialog later, you have two possibilities:

• delete the etc/hwm_install_blocker.php file

• set the value of the option $hwm_install_blocker in the etc/hwm_install_blocker.php file to false

If you delete the etc/hwm_install_blocker.php, you will be allowed to start the Configuration dialog only once. At the end it generates the etc/hwm_install_blocker.php again and disables repeated starts.

If you change the value of the option $hwm_install_blocker in the etc/hwm_install_blocker.php file to false, you will be able to start the Configuration dialog arbitrary times. Do not forget to change the value of the $hwm_install_blocker option back to true at the end of your configuration work. Otherwise the protection is switched off and any user may start the Configuration dialog from any client computer.

Finishing the setup

With a click on "Continue" the HWM setup is completed.

In case of a re-setup of HWM

The file hwm_db_config.php is overwritten after finishing the setup. All other files in case of an existing ProcMan installation are not changed.

Now there should be a DBDefinition.sql file in the installation directory, e.g. in c:/horizont/procman/database/.

This DBDefinition.sql file contains all queries to created the tables needed for the Procman installation. The file should be forwarded to the responsible DB2 administrator. He needs to execute the SQL queries contained in the file to create the tables needed for the ProcMan installation on the DB2 database.

In case you have administration rights on the DB2 database

Follow the steps below to run and execute the queries in the DBDefinition.sql file.

1. Start the db2cmdadmin.exe as admin. A CLI should open.

2. Type and execute the command db2

3. Connect to the database.

connect to <Database> user <zOSUser>

1. Execute the command "quit"

2. Navigate with the command cd to the directory where the DBDefinition.sql file is located.

3. Execute the file with the following command.

–tvf DBDefinition.sql

You should see a lot of successful responses that the commands have been executed successfully.

Now the HWM setup is complete. Finally, it is recommended to check the parameters contained in the hwm_db_config.php file in the installation directory (e.g. c:/horizont/procman/etc/hwm_db_config.php) to check if everything is correct (e.g. db_alias, db_name).

Additional information

As described in the article before, in the hos_config2.php files, multiple environment files are included.

These hos_env_<module>.php files contain environment settings that are relevant for the processes in ProcMan.

In most cases, there should also be a hos_env_general.php file. This environment file can be seen as a fallback and contains environment settings that should be used for all clients and processes if no other environment files have been defined.

For a detailed description of all the environment parameters of the hos_config2.php file, please see:

Process specific environment configuration

In most installations, processes require individual environment configurations.

See the code example below which shows an example of a hos_env_jcl.php file.

From line 3 to 51 a general environment config is set.

From line 58 to the end, the environment setting for a specific process with the name JCL_INIT_CO is set. This means that this config will "overwrite" the lines 3 to 51, because it is process specific.

If the client systems (user workstations, proxies, single sign-on systems, etc.) sending client certificates to the web server along with HTTPS requests and a verification of these certificates is required following settings must be done. After this is configured all the requests sent from systems not providing valid client certificates will be rejected.

Copy the certification authority (CA) certificate file of the CA which released the client certificates into the httpd/config.d subdirectory of the HWF installation.

Add the following lines (if they are not already there) in the section of the .conf configuration file of the Web Server of ProcMan:

SSLVerifyClient require
SSLVerifyDepth 10
SSLCACertificateFile conf.d/<ca_certificate_file>
<Location />
 SSLRequire <client_certificate_check>
</Location>

Replace <ca_certificate_file> with the real name of the CA certificate file you previously copied to httpd/config.d.

Replace <client_certificate_check> with an expression for the client certificate validation.

For more information of how these expression looks like, see the Apache documentation (http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslrequire) and the example below.

Example (.conf):

...
<VirtualHost procman.my_company.com:11443>
 ...
 SSLVerifyClient require
 SSLVerifyDepth 10
 SSLCACertificateFile conf.d/company_ca.crt
 <Location />
 SSLRequire %{SSL_CLIENT_S_DN_O} == "My Company Ltd." \
 && %{SSL_CLIENT_S_DN_OU} == "My Company CA" \
 && %{SSL_CLIENT_S_DN_CN} == "procman_client.my_company.com"
 </Location>
 ...
</VirtualHost>
...

Optionally ProcMan can be configured for exchanging data with external systems. This feature is typically used to connect an external ticket system, which allows associating ProcMan processes with tickets managed by the ticket systems, filling ProcMan process dialog fields with data from tickets and reporting ProcMan process/activity status changes back to the external system. The communication is managed by a ProcMan module called HWM Universal Interface. An important prerequisite is that the external system provides an HTTP/HTTPS server interface. ProcMan can currently be configured only as a client of the communication and does not provide any server service for handling request from external systems.

As any external system provides its own communication protocol (the form of the requests/responses and security requirements), configuration of the communication in ProcMan means to set special options and implementing some callback functions. Thus the configuration of the communication always requires HORIZONT support. To be able to configure it, a precise specification of the protocol provided by the external system is required.

The specification of the protocol shall provide at least answers to following questions:

Is it an encrypted communication, are CA and/or client certificates required and who provides them? Over what URL is the external system accessible? What method shall the request use: GET or POST? What is the structure of a request, what has to be sent in GET/POST parameters, what in http headers, what in http data? Are there some special data required in the request by the external system (e.g. authentication string, special http headers, etc.)? What format (JSON, XML, etc.) and structure (attribute/tag names, data types, etc.) shall the request data have? What format (JSON, XML, etc.) and structure (attribute/tag names, data types, etc.) have the response data? What data are sent in the http response headers and what in the http response data by the external system? Are there special responses in case of errors sent by the external system and what structure they have? Shall also the activity/process status changes be reported by ProcMan to the external system? If yes, what are the answers to the above questions for this kind of communication? Can all open tickets be requested by one request from the external system or only data for one in the request specified ticket?

In the next step, the file c:/horizont/procman/etc/hos_config2.php must be adjusted.

This is the most important file to start with, because in this file most of the configurations for a ProcMan installation come together. E.g., in this file it is defined which systems should be connected with ProcMan and also which environment variables should be used for the processes.

Section system_mapping

In the section system_mapping systems are defined in an array that should be connected with the ProcMan installation. In this section it is defined which IP is associated with which ID.

Important: Generally, the IP addresses have to be unique! This can be "bypassed" by assigning IP addresses to names in the c:/Windows/System32/drivers/etc/hosts file on the windows server. See the picture below.

For example, at HORIZONT, the z/OS with the IP 192.168.47.14 has to be defined in the section system_mapping. Therefore, we add a variable in the pm_system_settings.php file e.g. named $TEST_ip and assign the value 'TEST' to that variable. That means that the windows server now resolves 'TEST' to the IP 192.168.47.14 because this was set in the hosts file (as shown in the picture above).

In the following example (see picture below), we defined two systems in the hos_config2.php file. If you check the assigned variables' values in the pm_system_settings.php file, you can see that both systems are identical because they have equal IPs. The IP for the system DEV is directly defined in the hos_config2.php file, for the system DEMO the ip is resolved by windows through the c:/windows/system32/drivers/etc/hosts file.

Section environment

In this section. it is defined which config files for environment definitions should be used. These hos_env_XXX.php files contain environment definitions for processes in ProcMan.

It is recommended to create a seperate hos_env_<module>.php file for every module which is used in an installation, e.g. one for the jcl_proccesses named hos_env_jcl.php, one for IWS/AD processes named hos_env_iws_ad.php, and one for IWS/CP processes named hos_env_iws_cp.php. These files must then be included in the hos_config2.php file.

Important: The definitions in those files need to start at the correct array-layer, make sure not to mess that up, otherwise this can break ProcMan.

The picture below shows an example of three env_config files placed in the directory /etc/env_configs/. One for the JCL module, one for the IWS/AD module and one for the IWS/CP module.

Please see the next article Environment filesof a description of these files.

Section zos_tech_user

In this section, it is defined which z/OS user is used for which system with which password. Here it is also highly recommended to use variables defined in the pm_system_settings.php file.

Section rot_ini_file

In the section rot_ini_file it is defined which system (see above section system_mapping) uses which .ini file for the communication to the z/OS systems.

Important: After a new installation most probably no .ini file was created. Therefore a new file with the name e.g. horcclnt.ini has to be created. Use the file /procman/etc/horcclnt.ini-dist to make a new copy for your system. If multiple z/OS systems are connected to ProcMan, create multiple files with different names like horcclnt_test.ini or horcclnt_prod.ini .

The example below illustrates two possible communications to a TEST and a PROD system.

'rot_ini_file' => array (
        $TEST_id 	=> $hwi_config ['hwi_root'].$TEST_hor_ini,
        $PROD_id  	=> $hwi_config ['hwi_root'].$PROD_hor_ini 
 ),

The variables starting with $ are e.g. resolved from the pm_system_settings file as this:

$TEST_hor_ini = '/etc/horcclnt_test.ini';
$PROD_hor_ini = '/etc/horcclnt_prod.ini';

horcclnt.ini files

The following adjustments have to be made in the .ini files. Row 14: Correct path Row 18: Correct path Row 26: Optional: Adjust log path Row 50: Set the correct host port from the installation of ProcMan z/OS part Row 54: Set the correct member from the installation of ProcMan z/OS part

Sections template_dsn_cntl, base_tmp_dsn and temp_dsn_alloc_site

In the section template_dsn_cntl it is defined, which dataset on the z/OS contains the skeletons for the ProcMan JCL Module.

In the section base_tmp_dsn it is defined, which dataset is used when the ProcMan JCL modules creates outputs. Those members are also defined in the installation of the z/OS part of ProcMan.

The ProcMan server certificate and key file provided by the CA (see prerequisites) has to be copied into the httpd/conf.d subdirectory of the HWF installation. Beware that the certificate file must be in X.509 Base64 encoded PEM format.

You can verify whether this is the case by opening it in a text editor. If it is in the proper format, it must not contain any binary data and it must contain a section like this:

If the file contains binary data instead, the certificate is probably in the DER format and it has to be converted into the Base64 encoded PEM format. For the conversion you can either use the openssl command:

or (only on Windows) open the certificate file by double click from the Windows Explorer in the Windows Certificate tool and copy it into a Base64 encoded PEM file:

The names of the files set in the Web Server configuration file are by default .crt and .key where is the installation name set in the setup.rsp at the ProcMan installation. If the certificate and key file names differ from these, rename them or open the Web Server configuration file in a text file editor and change the file names in the options SSLCertificateFile and SSLCertificateKeyFile.

It is highly recommended to use HTTPS and a HTTPS certificate for ProcMan.

The default Web Server configuration created at the installation of ProcMan is for an encrypted HTTPS communication between the clients and the ProcMan server.

It is strongly recommended not to change this configuration to an unencrypted HTTP communication. However if there is some crucial reason for this it can be done in the Web Server configuration file <name>.conf by changing the port number and commenting out the options starting with SSL.

You need a .crt and a .key file which you can get from an official licensing site or from your companies certificate department.

1. Place the .crt and .key file in C:\HORIZONT\hwf\httpd\conf.d

2. Open the C:\HORIZONT\hwf\httpd\conf.d\<installationname>.conf file. In there, under the VirtualHost section, change the SSLCertificateFile path and the SSLCertficcateKeyFile path to the files added above.

If the user login shall work via encrypted secure LDAP communication (LDAPS), there have to be set some system environment variables to configure the LDAPS communication and after that the Web Server has to be restarted (e.g. in Windows’s Services dialog restart the HORIZONT HTTP Server service). On Unix/Linux the setting of the system variables works as well, but the preferred way is to set appropriate options in the ldap.conf file (see the description for this later in this chapter).

No server certificate verification required

If server certificate verification by the client is not required, set the environment variable LDAPTLS_REQCERT=never

Server certificate verification required

If server certificate verification by the client is required, copy the certificate of the server certificate’s authority provided by the customer to a file on the ProcMan server (e.g. C:\Programs\HORIZONT\ldap\server_ca.crt). If the server certificate has been issued using an intermediate authority certificate, which self has been signed by a parent authority certificate, copy all the chain of the intermediate authority certificate and all its ancestor authority certificates in arbitrary order in a single file on the ProcMan server.

Set the environment variables LDAPTLS_REQCERT=try and LDAPTLS_CACERT=<file>, where <file> is the file with its absolute path containing the certificate of the server certificate’s authority (or chain of authority certificates) previously copied to the ProcMan server.

Client certificate verification required

Beside the server certificate verification by the client, also client certificate verification by the server can be required for the secure LDAP communication in some installations. In this case a client certificate file and its private key file provided by the customer and issued by an authority known to the server has to be copied to files on the ProcMan server (e.g. C:\Programs\HORIZONT\ldap\client.crt and C:\Programs\HORIZONT\ldap\client.key). Beware that the key file has to be protected to avoid its misuse.

Set the environment variables LDAPTLS_CERT=<cert_file> and LDAPTLS_KEY=<key_file>, where <cert_file> is the client certificate file and <key_file> is the private key file, with their absolute paths, previously copied to the ProcMan server.

On Unix/Linux the preferred way is to set appropriate options in the ldap.conf file, rather than use the system variables. In a HWF installation the ldap.conf file is placed in /opt/horizont/hwf/etc/ldap.conf. The configuration options corresponding to the system variables described above are TLS_REQCERT, TLS_CACERT, TLS_CERT and TLS_KEY. The required options can be added by editing the ldap.conf file.

Example (ldap.conf):

The default Web Server configuration created at the installation of ProcMan is for an encrypted HTTPS communication between the clients and the ProcMan server. It is strongly recommended not to change this configuration to an unencrypted HTTP communication. However if there is some crucial reason for this it can be done in the Web Server configuration file .conf by changing the port number and commenting out the options starting with SSL by using the '#' at the start of the row.

For example: