Kobee Resource Configurator Installation Guide

Purpose

This document explains how to install the Kobee Resource Configurator (KRC).

KRC is a web application to edit and generate models and resources that are part of the Kobee DevOps solution for z/OS mainframe. These models and resources will be used by the z/OS solution Phases running on a Kobee Agent. The models are JCL model templates and the resources are properties that will be used by the models to compile and promote sources and their results to the mainframe.

kobee zos architecture

It is recommended to install the Kobee Resource Configurator on the same host as the Kobee Agent that will run the z/OS Phases. This facilitates the export of the models and resources to the system that will use them. In most cases this will be on the same host as the Kobee Server, but this is not a strict requirement.

Prerequisites

The following section provides an overview of the prerequisites for installing KRC.

Hardware Requirements

The hardware requirements of KRC and the different Kobee components are shown in the table below, since they are usually installed on the same server.

Component Memory Disk

Kobee Resource Configurator

Min 128MB, recommended 256MB or more

Min 100MB, recommended 250MB

Kobee Web Application

Min 512MB, recommended 1GB or more

Min 1GB, recommended 5GB

Kobee Server

Min 512MB, recommended 1GB or more

Min 10GB, recommended 40GB

Kobee Agent

Min 512MB, recommended 1GB or more

Min 1GB

Java 17

KRC needs an installed Java JDK of version 17 or higher. It has been tested to run with Oracle Java, Adoptium Eclipse Temurin (formerly AdoptOpenJDK), Azul Zulu Builds of OpenJDK and OpenJDK on several Linux distros. Oracle Java can be obtained from Oracle’s website using an Oracle account. Adoptium OpenJDK can be obtained from https://adoptium.net and Azul Zulu Builds of the OpenJDK from https://azul.com/downloads/?package=jdk.

Database

KRC uses an in-memory database and does not require a preconfigured database. The database will be automatically created during installation in the KRC_HOME/data directory. Database backups can be performed on demand from within KRC and will be stored under KRC_HOME/backup.

Installing Kobee Resource Configurator

This section describes the different steps for installing Kobee Resource Configurator.

Configuring the Installer

KRC is delivered as a KRC_2-2-0-Bx.zip or KRC_2-2-0-Bx.tar.gz file, with x the Build Number. For example KRC_2-2-0-B11.zip for KRC Build Number 11. Expand this file somewhere on the target machine. The expanded folder containing the KRC installer files (gradle scripts) will be denoted as INSTALL_DIR.

The included installer will install KRC in the specified destination folder.

Configure the different properties that will be used by the installation script by editing the INSTALL_DIR/gradle.properties file.

You MUST specify ('/') or ('\\') in path properties. A single ('\') will not work.

krc_home=C:/krc
krc_java_home=D:\\java\\jdk-17.0.4.101-hotspot
krc_tomcat_shutdown_port=8505
krc_tomcat_port=8082
krc_tomcat_port_secure=8482
krc_tomcat_user_name=USERNAME
krc_sudo_password=PASSWORD
krc_encryption_password=KRCDefaultPassword
Property Description

krc_home

The location where the Kobee Resource Configurator should be installed. Further on in this document, this location will be referred to as KRC_HOME. Valid examples are c:/krc or /opt/krc.

krc_java_home

Set this to the Java Home of the Java Runtime that will be used to launch the KRC application server. Valid examples are D:\\java\\jdk-17.0.4.101-hotspot or /usr/lib/jvm/java-17-openjdk.

krc_tomcat_shutdown_port

The port number the KRC application server listens on for incoming shutdown requests. By connecting to this port and sending the SHUTDOWN command, the KRC application will be halted. Defaulted to '8505' to avoid conflicts with the default 8005 of a Tomcat web server that might be running the Kobee Web application on the same server.

krc_tomcat_port

The port number the KRC application server listens on for incoming HTTP requests. Defaulted to '8082' to avoid conflicts with the default HTTP 8080 port of a Tomcat web server that might be running the Kobee Web application on the same server.

krc_tomcat_port_secure

The port number the KRC application server listens on for incoming HTTPS requests. Defaulted to 8482 to avoid conflicts with the default HTTPS 8443 port of a Tomcat web server that might be running the Kobee Web application on the same server.

krc_tomcat_user_name

Only needed for Linux installations. User name needed to install KRC as a daemon in systemd on Linux distro’s.

krc_sudo_password

Only needed for Linux installations. The sudo password needed for registrating the KRC Tomcat Web Application Container as a service in systemd.

krc_encryption_password

The password used when encrypting/hiding passwords in properties used by KRC, like those of the user(s) of the DefaultSecurity, the ldap password or the Azure Active Directory client secret. See the section on [Encrypting passwords in KRC property files] for more info on this topic.

Running the Installer

By default, the installer uses the java executable that is available on the Operating System’s PATH. If no Java excutable is present on the PATH, or the version of the Java executable is unsuitable (lower than 17), then you need to set the JAVA_HOME environment used by the installation script.

On Windows, edit INSTALL_DIR/environment.bat, and replace the line

@REM SET JAVA_HOME=D:\java\jdk-17.0.4.101-hotspot

with something like :

SET JAVA_HOME=D:\java\jdk-17.0.4.101-hotspot

On Linux or Unix, edit INSTALL_DIR/install.sh, and replace the line

JAVA_HOME=

with something like :

JAVA_HOME=/usr/lib/jvm/java-17-openjdk

Launch the installer by executing the install.bat or install.sh script.

The installation procedure will unpack and configure the necessary files in the KRC_HOME location. It will setup an Apache Tomcat webserver under KRC_HOME/appserver/apache-tomcat-${version} , e.g. with Apache Tomcat version 10.1.8 this will be KRC_HOME/appserver/apache-tomcat-10.1.8. Further on in this document, this location will be referred to as KRC_HOME/appserver/apache-tomcat-${version}.

It is recommended to launch the installer from a command prompt, Powershell or Linux shell, to see the progress and the result of the installation. On Windows, if the installer is not run as an Administrator, a User Account Control dialog will pop up asking 'Do you want to allow this app to make changes to your device', where this app is the Apache Commons Daemon Service Runner. Click Yes so that the Service for stopping and starting KRC is correctly configured. On Linux, KRC will be registered as a daemon in systemd using the krc_sudo_password configured in the gradle.properties.

The user running the installer should have write access to the KRC_HOME location.

installer finished

When the installation succeeds, the BUILD SUCCESSFUL message appears.

Do NOT remove the INSTALL_DIR folder after installation, because you will need it to uninstall or upgrade KRC in the future.

Starting and stopping the Kobee Resource Configurator

To use the Kobee Resource Configurator, you need to make sure that the Windows service or Linux daemon that was configured during installation is started.

Starting the Kobee Resource Configurator

On Windows, start the Kobee Resource Configurator service in the Services app or execute following command in an Administrator Command Prompt :

net start krctomcat

To start the Kobee Resource Configurator daemon on a systemd compatible Linux system, open a shell and execute :

sudo systemctl start krctomcat

The KRC GUI can be reached by browsing to the url http://<hostname>:<krc_tomcat_port>/krc, For example: http://myhost:8082/krc. KRC requests can also be processed via the secured url https://<hostname>:<krc_tomcat_port_secure>/krc, for example: https://myhost:8482/krc.

The KRC Log in page will be displayed:

krc login

Log in with user id “global”, password “global”. For information about the security configuration, see Security configuration.

Stopping the Kobee Resource Configurator

On Windows, stop the Kobee Resource Configurator service in the Services app or execute following command in an Administrator Command Prompt :

net stop krctomcat

To stop the Kobee Resource Configurator daemon on a systemd compatible Linux system, open a shell and execute :

sudo systemctl stop krctomcat

Uninstalling KRC

By default, the uninstallation scripts use the java executable or JAVA_HOME variable as specified during the installation. This may be the java executable that is available on the Operating System’s PATH or the JAVA_HOME environment variable as set in the INSTALL_DIR/environment.bat (Windows) or INSTALL_DIR/environment.sh (Linux/Unix) file. Refer to the instructions of Running the Installer on how to set the JAVA_HOME variable.

First stop the KRC Windows service or Linux daemon (see Stopping the Kobee Resource Configurator), and then launch the uninstaller by executing the uninstall.bat or uninstall.sh script.

It is recommended to launch the uninstaller from a command prompt, Powershell or Linux shell, to see the progress and the result of the uninstallation. On Windows, if the uninstaller is not run as an Administrator, a User Account Control dialog will pop up asking 'Do you want to allow this app to make changes to your device', where this app is the Apache Commons Daemon Service Runner. Click Yes so that the Service for stopping and starting KRC is correctly removed. On Linux, the KRC daemon will be removed from systemd using the krc_sudo_password configured in the gradle.properties.

The user running the uninstaller should have write access to the KRC_HOME location.

The uninstaller will keep the following folder containing the database backups :

  • KRC_HOME/backup

If this folder needs to be removed, it must be deleted manually after the uninstallation.

uninstaller finished

When the uninstallation succeeds, the BUILD SUCCESSFUL message appears.

Upgrading KRC

The general approach for upgrading KRC is to first backup the crucial elements of the current installation and then run the KRC upgrade script.

If the upgrade process fails, you can restore the backup and continue running the previous version of KRC.

You should backup the following:

  1. The KRC database, by selecting the Create New Backup option in the Backups menu of the KRC GUI.

  2. The KRC_HOME location, as configured in the gradle.properties. This location also contains the database backup files, since they are stored in the KRC_HOME/backups location.

For safety reasons, it is highly recommended to back up the entire KRC_HOME directory. Experience has shown that, sometimes, one needs to restore a configuration like a security setting. To reduce the space of the backup, it is a good practice to remove old obsolete database backups. This can be done in the Backup File List of the Backups menu in the KRC GUI.

KRC Upgrade Procedure

  1. Stop the KRC service or daemon. Refer to Stopping the Kobee Resource Configurator.

  2. Make the necessary backups.

  3. Expand the new KRC distribution zip or tar.gz file on the target machine. The expanded folder containing the KRC upgrade files (gradle scripts) will be denoted as INSTALL_DIR.

    The included installer will install KRC in the specified destination folder.

  4. Configure the different properties that will be used by the installation script by editing the INSTALL_DIR/gradle.properties file. This may be done based on the gradle.properties file of a previous installation.

    By default, the upgrade scripts use the java executable that is available on the Operating System’s PATH. If no Java excutable is present on the PATH, or the version of the Java executable is unsuitable (lower than 17), then you need to set the JAVA_HOME environment used by the installation script. Refer to the instructions of Running the Installer on how to set the JAVA_HOME variable.

  5. Finally launch the upgrade script by executing the INSTALL_DIR/upgrade.bat or INSTALL_DIR/upgrade.sh script.

It is recommended to launch the upgrade script from a command prompt, Powershell or Linux shell, to see the progress and the result of the upgrade. On Windows, if the upgrade script is not run as an Administrator, a User Account Control dialog will pop up twice asking 'Do you want to allow this app to make changes to your device', where this app is the Apache Commons Daemon Service Runner. Click Yes so that the Service for stopping and starting KRC is correctly removed and reinstalled. On Linux the KRC daemon will be removed from and installed in systemd using the krc_sudo_password configured in the gradle.properties.

The user running the upgrade script should have write access to the KRC_HOME location.

Appendix A: Manually Installing and Removing KRC as a Windows Service

When the permission has been given during installation/upgrade or when the KRC installer is run as an Administrator, the Windows services for stopping and starting KRC is automatically created. If not, you can register the Windows service manually after installation/upgrade.

  • To register KRC as a Windows service:

    Execute "KRC_HOME/appserver/apache-tomcat-${version}/bin/service.bat install krctomcat".

  • To unregister KRC as a Windows service:

    Execute "KRC_HOME/appserver/apache-tomcat-${version}/bin/service.bat remove krctomcat".

The service.bat script must be run as Administrator.

If you want to reconfigure a service, edit the file KRC_HOME/appserver/apache-tomcat-${version}/bin/setenv_service.bat. You can, for example, change the amount of memory KRC can use (in MB) by changing : "set JvmMx = 256".

Appendix B: Manually Installing and Removing KRC as a Daemon Process in systemd on Linux Systems

When the krc_sudo_password provided in gradle.properties is correct, the KRC Daemon process for stopping and starting KRC is automatically registered in systemd during installion or upgrade. If not, you can register the Linux daemon manually after installation/upgrade.

Make the KRC_HOME/appserver/apache-tomcat-${version}/conf/krctomcat.service file executable.

chmod +x KRC_HOME/appserver/apache-tomcat-${version}/conf/krctomcat.service

Install the KRC service.

sudo systemctl -f enable KRC_HOME/appserver/apache-tomcat-${version}/conf/krctomcat.service

To start the KRC service, execute

sudo systemctl start krctomcat

To stop the KRC service, execute

sudo systemctl stop krctomcat

When you want to remove the KRC service, execute

sudo systemctl disable krctomcat

Appendix C: Security configuration

For the authentication and authorization of users, KRC uses Spring Security (see https://spring.io/projects/spring-security). This system has been set up so that it is easy to switch between 3 pre-defined security configuration types:

  • the default security type, or user and password authentication, which has a predefined global user.

  • the ldap security type, which allows authentication and authorisation using an ldap system.

  • the aad security type, where authentication and authorization is controlled by Microsoft Azure Active Directory, recently renamed to Microsoft Entra ID.

While you can use the default security system for getting started and for testing purposes, it is not recommended to use this for production. You should adapt the default user and password, or change to a more enhanced system, like ldap, Microsoft Active Directory or Microsoft Entra ID.

The KRC installation contains configuration file examples for each security type so that switching between them should be easy.

Default Security: user and password authentication

The default KRC security type allows authentication with user and password. By default the user name is global and its password global.

krc login

This default security can be configured in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/spring-default-security.properties file.

krc.security.type=default
spring.security.user.name=global
spring.security.user.password=global

This security system can be maintained in production if having only one user is sufficient, but we recommend changing the user and password, for example as follows.

krc.security.type=default
spring.security.user.name=kobee
spring.security.user.password=ENC(mn4/2Cku8ppHTXpBbBSG8pS1wsLIrjH8VgpdjdSFCPP+ciwiJVKd1LBaTYxS6RZ0)

For security reasons the password of the kobee user has been encrypted, see Encrypting Passwords in property files on how to do this.

LDAP Security

KRC authentication and authorization can also be configured by setting up a (secure) ldap connection. In order to do this you have to perform following steps:

  1. Stop the KRC Windows service or Linux daemon

    On Windows, stop the Kobee Resource Configurator service in the Services app or execute following command in an Administrator Command Prompt :

    net stop krctomcat

    To stop the Kobee Resource Configurator daemon on a systemd compatible Linux system, open a shell and execute :

    sudo systemctl stop krctomcat
  2. Change the settings in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/application.properties file

    Import the spring-ldap-security.properties file by commenting and uncommenting (using #) the correct import lines as follows:

    ...
    # import jpa and security properties
    #spring.config.import=spring-jpa.properties,spring-default-security.properties,optional:version.properties
    spring.config.import=spring-jpa.properties,spring-ldap-security.properties,optional:version.properties
    #spring.config.import=spring-jpa.properties,spring-aad-security.properties,optional:version.properties
    ...
  3. Configure the ldap connection properties in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/spring-ldap-security.properties file. See the table below for more info on these properties

  4. In case of ldaps, make sure the certificate is added to the trusted certificates of the Java jre, using the Java keytool program.

  5. Start the KRC Windows service or Linux daemon

    Use the Services application on Windows and start the Kobee Resource Configurator service, or excute the commands net start krctomcat (Windows) or sudo systemctl start krctomcat (Linux systemd) as explained above.

Configure the following properties in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/spring-ldap-security.properties file :

Property Description

krc.ldap.urls

The url(s) of the ldap server to use. Both ldap and ldaps are supported. In case of ldaps, make sure the certificate is added to the trusted certificates of the java jre, using the JDK keytool program. Sample value ldap://localhost:389.

krc.ldap.base

The Base DN where ldap searches for Users will start. Sample value DC=example,DC=com.

krc.ldap.subtreesearch

Allow subtree search. If set to true, a subtree scope search will be performed. If false, a single-level search is used.

krc.ldap.referral

Defines the strategy to handle referrals. Possible values: ignore, follow and throw.

krc.ldap.password

The password to use when authenticating with the ldap server. For security reasons this password may be encrypted, see Encrypting Passwords in property files on how to do this.

krc.ldap.userSearchFilter

The searchFilter for finding users in the ldap. For example: (uid={0}) - this would search for a username match on the uid attribute. Or (sAMAccountName={0}) for finding users in an Active Directory.

krc.ldap.groupSearchBase

The group search is performed within a DN specified by the groupSearchBase property, which should be relative to the root DN of its ContextSource. If this is an empty string, searching starts from the root. Sample value OU=groups,DC=example,DC=com.

krc.ldap.groupSearchFilter

The pattern to use for determining whether the user is a member of the group. {0} is the user’s DN. Example: (member={0}), or (|(sAMAccountName={1})(member={0})) for user member search in an Active Directory.

krc.ldap.anonymous-read-only

Defines whether read-only operations are performed by using an anonymous (unauthenticated) context.

krc.ldap.adminAuthorities

Authority or comma separated list of authorities that have access to KRC. Example: ADMIN, or ADMIN_KRC,ADMIN_KOBEE.

When using this security configuration, users can log in to KRC using their ldap or Active Directory credentials.

AAD Security: Microsoft Entra ID security, also known as Azure Active Directory

KRC authentication and authorization can also be configured by setting up a connection to Azure Active Directory (Azure AD or Entra ID). In order to do this you have to perform following steps:

  1. Stop the KRC Windows service or Linux daemon

    On Windows, stop the Kobee Resource Configurator service in the Services app or execute following command in an Administrator Command Prompt :

    net stop krctomcat

    To stop the Kobee Resource Configurator daemon on a systemd compatible Linux system, open a shell and execute :

    sudo systemctl stop krctomcat
  2. Change the settings in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/application.properties file

    Import the spring-aad-security.properties file by commenting and uncommenting (using #) the correct import lines as follows:

    ...
    # import jpa and security properties
    #spring.config.import=spring-jpa.properties,spring-default-security.properties,optional:version.properties
    #spring.config.import=spring-jpa.properties,spring-ldap-security.properties,optional:version.properties
    spring.config.import=spring-jpa.properties,spring-aad-security.properties,optional:version.properties
    ...
  3. Configure the Azure AD/Entry ID properties in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/spring-aad-security.properties file. See the table below for more info on these properties

  4. Start the KRC Windows service or Linux daemon

    Use the Services application on Windows and start the Kobee Resource Configurator service, or excute the commands net start krctomcat (Windows) or sudo systemctl start krctomcat (Linux systemd) as explained above.

Configure the following properties in the KRC_HOME/appserver/apache-tomcat-${version}/webapps/krc/WEB-INF/classes/spring-aad-security.properties file :

Property Description

spring.cloud.azure.active-directory.enabled

Enable the features provided by spring-cloud-azure-starter-active-directory.

spring.cloud.azure.active-directory.profile.tenant-id

Contains the Active Directory’s Tenant ID. Sample value 22222222-2222-2222-2222-222222222222.

spring.cloud.azure.active-directory.credential.client-id

Contains the Application ID of your app registration. Sample value 11111111-1111-1111-1111-1111111111111111.

spring.cloud.azure.active-directory.credential.client-secret

Contains the Client Secret value of your app registration. For security reasons, this value may be encrypted, see Encrypting Passwords in property files on how to do this.

krc.security.aad.role_admin

The Role that defines admin access in KRC from your app registration. Sample value ROLE_ADMIN.

When using this security configuration, a user opening the KRC GUI will be redirected to the Microsoft Entra sign-in page. After providing the correct Microsoft credentials, the user will be redirected to the KRC GUI. The following screenshot shows the Microsoft Entra sign-in page:

application login

Appendix D: Encrypting Passwords in property files

For security reasons, we advise you to encrypt certain passwords or secret info after installation of KRC.

Following properties may be encrypted:

  • the spring.security.user.password in the spring-default-security.properties file

  • the krc.ldap.password in the spring-ldap-security.properties file

  • the spring.cloud.azure.active-directory.credential.client-secret in the spring-aad-security.properties file

The encrypted value can be obtained by using the encrypt.bat (Windows) or encrypt.sh (Linux) command in the KRC_HOME/appserver/apache-tomcat-${version}/bin directory.

Open a command prompt or shell in this directory and type the following command:

encrypt -p <password> <value to encrypt>

Replace in this command password with the value of the krc_encryption_password you have set in the gradle.properties file during installation. value to encrypt is the password or secret key you want to encrypt, e.g. global in the case of the spring.security.user.password:

encrypt -p KRCDefaultPassword global

This will return following info in the command prompt or shell:

Encrypting value "global" with password "KRCDefaultPassword" ...
Encrypted value : KQnT+TyGZtZHE+ZpDPZyYaIiRYxNXwHqUU5TKlCjxbniAdze1Bo51e9guhNK3Ge+

Copy the Encrypted value and replace it as follows e.g. for the spring.security.user.password in the spring-default-security.properties

spring.security.user.password=ENC(KQnT+TyGZtZHE+ZpDPZyYaIiRYxNXwHqUU5TKlCjxbniAdze1Bo51e9guhNK3Ge+)

The KRC Windows service or Linux daemon must be restarted in order to activate the encrypted value. If you have made a mistake during encryption (e.g. wrong encryption password) or while copying the encrypted value, the KRC Windows service or Linux daemon will fail to restart.