Installing IBM Connect:Direct for UNIX using an IBM Certified Container Software

IBM Certified Container Software (CCS) can be installed on the Kubernetes based cluster.

Kubernetes is an open-source container orchestration engine to automate the deployment, scaling and management of containerized applications. This application release has been qualified and certified on an on-premise Red Hat® OpenShift® Container Platform (OCP) which is an enterprise-ready Kubernetes container platform with full-stack automated operations to manage the deployment life-cycle.

IBM CCS offers a container image and a helm chart. It meets the standard criteria for the packaging and deployment of containerized software. In addition, the container image is Red Hat certified.

For more details, refer to the below links:

Post-installation tasks

Edit online

The post deployment configuration steps can be performed via:

• Session Limits per Pod

As per the default resource limits provided in the Helm chart configuration, update the network map file after deployment with the following values:

local.node:\
  :api.max.connects=20

tcp.ip.default:\
  :sess.total=30:\
  :sess.pnode.max=30:\
  :sess.snode.max=30:

<remote node>@<nodename>:\
  :sess.total=20:\
  :sess.pnode.max=20:\
  :sess.snode.max=20:

• Connect Direct Web Services

Login to the Connect Direct Web services using the Load Balancer or External IP address and the port to which container API port (1363) is mapped. For configuration steps, see Connect:Direct Web Services Help Videos.
Issue the following command to get the external IP address
```
kubectl get svc
```

Certificate based authentication in Connect Direct Web Services

While connecting to Connect:Direct server with Ordinary User Mode enabled, use certificate based authentication. It will authenticate IBM Sterling Connect:Direct Web Services request to connect to IBM Sterling Connect:Direct for Unix using certificates. There are some simple steps which are divided into two separate sections for Browser's Settings for Certificate Configuration and Certificate Configuration Connect:Direct Web Services/Connect:Direct Unix below which can be followed to enable certificate based login:

Certificate Configuration Connect:Direct Web Services/Connect:Direct Unix:

Login as Admin user into IBM Sterling Connect:Direct Web Services and create a node entry for IBM Sterling Connect:Direct for Unix.
CA certificate is required, this could be same certificate which IBM Sterling Connect:Direct for Unix might be using for authenticating other IBM Sterling Connect:Direct for Unix nodes in file transfer. If CA certificate is chained then separate them into individual certificates and import them to IBM Sterling Connect:Direct Web Services trust store individually.
A key certificate should generated using the command below:
```
openssl req -x509 -sha256 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
```
Note: When entering the certificate details, enter the hostname as the common name.
Combine the key.pem and cert.pem to create a singe certificate and import it to IBM Sterling Connect:Direct Web Services key store. Then, import cert.pem to IBM Sterling Connect:Direct for Unix node's.
Then, if there is any key certificate which is used KeyCertLabel in secure plus configuration. Then, that certificate can be separated into two parts comprising of key part and the certificate part. Namely, cert_R.pem and key_R.pem.
Create a fingerprint with the cert_R.pem file using below command:
```
openssl x509 -noout -fingerprint -sha256 -inform pem -in cert_R.pem
```
In IBM Sterling Connect:Direct Web Services, application properties file, configure SSL alias by setting server.ssl.key-alias=combined.pem and configure certificate fingerprint by setting certificate.finger.print=<Certificate Label>;<Fingerprint> and Save the application properties file.
Go to the server and open userfile.cfg file, create an admin user record with client authentication set to y and user name as hostname of the machine.
Restart IBM Sterling Connect:Direct Web Services and refresh the IBM Sterling Connect:Direct Web Services link to see the certificate based authentication menu pop-up and select the node to login to it.

Browser's Settings for Certificate Configuration:

For Certificate-based Authentication from UI, the user needs to add their configured key certificate to a browser’s personal certificate. Since, Google Chrome and Microsoft Edge use Microsoft keystore, you can also add a certificate to the Microsoft keystore directly.

Follow the below steps to add the key certificate used in previous configuration in the Personal Certificates to the browser keystore.

Using Google Chrome browser:
1. Go to Settings > Privacy & Security > Security, under Advanced, click Manage device certificates to display Certificates window.
2. Click Import to open Certificate Import Wizard and click Next.
3. Follow the Certificate Import Wizard to import the certificate.
4. After successful import, restart the browser.
Using Mozilla Firefox:
1. Go to Settings > Security, under Certificates, click View Certificates to display Certificate Manager window.
2. Click Import, select an appropriate key certificate file and enter the password for the same to import the certificate.
3. Restart the browser after successfully importing the certificate.
Using Microsoft Edge:
1. Go to Settings > Privacy, search, and services, under Manage Certificates, click View Certificates to display Certificate Manager window.
2. Click Import to open Certificate Import Wizard.
3. Follow the Certificate Import Wizard to import the certificate.
4. After successful import, restart the browser.
After configuring the client certificate, enter the CDWS URL in address bar and press enter, Select a certificate pop-up displayed that shows the client certificate, select the appropriate client certificate.
After selecting the appropriate client certificate, Select a Node pop-up displayed. One selected node must be configured for certificate-based authentication.

• Attaching to the container

Follow the steps given below:

Issue the following command to get the pod name
```
kubectl get pods -n <namespace>
```

Issue the following command to attach to the container
```
kubectl exec -it <pod name> bash
```

• Restarting Connect:Direct services inside container

Sometime, few configurations of IBM® Connect:Direct® for UNIX needs its services to be restarted. To restart the Connect:Direct service in container, access container terminal either from the command line or OCP dashboard. Inside the container run the below command:
```
touch /cdinstall/.cdrecycle
```
After creating this file in the container, CDPMGR services can be stopped by login to direct prompt using the below command:
```
/opt/cdunix/ndm/bin/direct
```
Then type stop; and press enter key. Connect:Direct service will be stopped inside container.
Verify the changes and then restart CDPMGR process using the below command:
```
/opt/cdunix/ndm/bin/cdpmgr -i /opt/cdunix/ndm/cfg/<nodename>/initparm.cfg
```
Note: Pass Connect:Direct Nodename of the container in the above command.
Consider, liveness and readiness probes configuration before stopping CDPMGR service. If Connect:Direct service remains unavailable beyond liveness and readiness configuration then it would result in pod restart.
After Connect:Direct service is restarted, delete the created file using the below command:
```
rm -f /cdinstall/.cdrecycle
```

Known Limitations

Edit online

Multi-pod deployment is not supported in Azure Kubernetes Service (AKS) when using the Azurefile storage class due to performance issues.
IBM Connect:Direct for Unix chart supports only the x64 architecture.
Adding extra system users at runtime is not supported.
Interaction with IBM Control Center Director is not supported.
The container does not include X-Windows support, so SPAdmin cannot run inside the container. SPCli will run in the container and Connect Direct Web Services (CDWS) can be used outside the container in place of using SPAdmin.
Extension of Connect:Direct containers by customers is not supported. If you want any modifications or updates to the containers you need to raise an enhancement request.

Migrating to Connect:Direct for UNIX using Certified Container Software

Edit online

Follow the steps given below to create a backup and restore IBM Connect:Direct for Unix using Certified Container Software:

Create a backup
To create a backup of configuration data and other information such as stats and TCQ, present in the persistent volume, follow the steps given below:
1. Go to mount path of Persistent Volume.
2. Make copy of the following directories and store them at a secured location:
  - WORK
  - SECURITY
  - CFG
  - SECPLUS
  - PROCESS
  - FACONFIG
  - FALOG
    Note:
    
    Update the various values in initparm.cfg, netmap.cfg and ndmapi.cfg for the C:D installation path, hostname/IP and port numbers. The installation path is `/opt/cdunix/` , hostname would be <helm-release-name>-ibm-connect-direct-0 and client port is 1363 and server port is 1364.
    
    The nodename of Connect:Direct for Unix running on traditional system should be same while migrating it inside container.
    
    If Connect:Direct for UNIX is installed in a conventional mode, create a backup of the following directories:
    
    <install_dir>/work
    
    <install_dir>/ndm/security
    
    <install_dir>/ndm/cfg
    
    <install_dir>/ndm/secure+
    
    <install_dir>/process
    
    <install_dir>/file_agent/config
    
    <install_dir>/file_agent/log
    A file must be created in a work directory before taking backup. The file can be created by invoking the following command:
    <path to cdunix install directory>/etc/cdver > <path to cdunix install directory>/work/saved_cdunix_version
Restore the data in a new deployment
To restore data in a new deployment, follow the steps given below:
1. Create a Persistent Volume.
2. Copy all the backed-up directories to the mount path of Persistent Volume.
For other prerequisites such as secrets see, cdu_pre_installation_tasks.html.

Upgrade to Certified Container Software

Create a new instance of chart using the following helm CLI command:

Helm version 2

helm install --name <release-name> --set license=true,image.repository=<reponame> image.tag=<image tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.4.x.tgz

Helm version 3

helm install <release-name> --set license=true,image.repository=<reponame> image.tag=<image tag>,cdArgs.crtName=<certificate name>,image.imageSecrets=<image pull secret>,secret.secretName=<C:D secret name> ibm-connect-direct-1.4.x.tgz

Note: The nodename of Connect:Direct for Unix running on traditional system should be same for migration to IBM Certified Container Software. Configure the nodename using "cdArgs.nodeName" parameter.

Migration from Helm 2 to Helm 3

Edit online

This migration only applies if you have IBM Certified Container Software instances/releases that are running on Helm 2 and you want to use Helm 3 release. It is the responsibility of the Cluster Administrator to decide on the migration strategy according to deployment requirement and specific use case scenario. Although, there is a detailed and exhaustive documentation provided by the Helm on migration. Please refer the this link, Helm.