Readme File for IBM^® Spectrum Symphony 7.2.1 RFE 149006 and RFE 149007

Readme file for: IBM Spectrum Symphony

Product release: 7.2.1

Fix ID: sym-7.2.1-build600838-ms

Publication date: December 10, 2021

This IBM Spectrum Symphony 7.2.1 enhancement provides:

· The ability to pass the following parameters: labels, capabilities, security options, groups, and hostname to Docker containers in an IBM Spectrum Symphony cluster.

· The ability for you to start IBM Spectrum Symphony services on Docker containers in a TLS-enabled Docker environment.

1. Scope

Before you install this enhancement to your cluster, note the following requirements:

Operating system	RHEL 7.x 64-bit
Product version	IBM Spectrum Symphony 7.2.1

2. Installation

Follow these instructions to download and install this enhancement on management hosts in your cluster.

Prerequisites

a. Docker networking must be set up to use the host’s networking stack.

b. Docker images for compute hosts and service instances must be available.

c. The Docker daemon must be started with TLS enabled.

Package

Name

Description

egocore-3.7.0_x86_64_build600838.tar.gz

soamcore-7.2.1.0_x86_64_build600838.tar.gz

Package for Linux cluster hosts.

Installing

a. Log on to the primary host as the cluster administrator:

> egosh user logon -u Admin

b. Disable all applications:

> soamcontrol app disable all -f

c. Shut down the cluster:

> egosh service stop all

> egosh ego shutdown all

d. Download the egocore-3.7.0_x86_64_build600838.tar.gz and soamcore-7.2.1.0_x86_64_build600838.tar.gz packages to each of your management and compute hosts, for example, to a /symfixes directory.

e. Run the egoinstallfixes command to install the egocore-3.7.0_x86_64_build600838.tar.gz and soamcore-7.2.1.0_x86_64_build600838.tar.gz files:

> egoinstallfixes /symfixes/ egocore-3.7.0_x86_64_build600838.tar.gz

> egoinstallfixes /symfixes/soamcore-7.2.1.0_x86_64_build600838.tar.gz

Important: Running the egoinstallfixes command automatically backs up the current binary files to a fix backup directory. For recovery purposes of the original file, do not delete this backup directory. For more information on using this command, see the egoinstallfixes command reference.

f. Run the pversions command to verify the installation:

> pversions -b 600838

g. Pass the DOCKER_HOST_URL environment variable to enable an IBM Spectrum Symphony compute host to run in a Docker container. Specify the Docker daemon URL in the format tcp://$HOSTNAME:<port>. Note that IP addresses are not supported.

You can pass the DOCKER_HOST_URL by specifying the -e option in the docker run command. For example, use the following command to pass the environment variable while starting the compute host on Docker:

docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v /usr/bin/docker:/usr/bin/docker -e "DOCKER_HOST_URL=tcp://docker01.eng.lab.mycompany.com:2376" -d -h containerName --privileged=true --name=containerName imageName /usr/sbin/init

h. Start the cluster and enable your applications:

> egosh ego start all

> soamcontrol app enable application_name

3. Configuration and usage

To configure RFE 149006 to add Docker parameters: labels, capabilities, security options, groups, and hostname to Docker containers for security:

The additional Docker parameters will be defined in the application profile’s SSM section as environment variables. The following is the list of new variables.

LABELS	A list of user defined key-value pairs.
HOSTNAME	Can be empty (void) or a valid RFC 1123 hostname.
CAPADD	A list of kernel capabilities to add to the container. For details, see: https://man7.org/linux/man-pages/man7/capabilities.7.html
CAPDROP	A list of kernel capabilities to drop from the container.
SECURITYOPT	A list of string values to customize labels for multi-level security systems (MLS), such as for SELinux support.
LOGCONFIG	Log configuration parameters for the IBM Spectrum Symphony Docker controller. Max-size is the maximum file size in megabytes. Max-file sets the number of backup log files. Level is the logging level, where level 1 shows the least information and level 7 shows the most.
GROUPADD	A list of additional groups that the container process will run as.

Only host network mode is supported by the Docker controller. Note that string pair lists are specified using braces ({}), and string arrays use brackets ([]). During startup, SSM (the IBM Spectrum Symphony session manager) performs only basic prechecking. If the prechecking finds a problem, it will log a warning and not pass this variable to the Docker controller. See the SSM log for warnings with the following format:

2021-08-09 01:52:59.316 GMT WARN [28035:140257140643584] ssm.ssmcore.ARM - The value "{"no-new-privileges"}" specified for SSM_DOCKER_ATTR_HOSTCONFIG_SECURITYOPT is not valid.

If the syntax is incorrect and the precheck did not find the problem, the container will fail to start. Inspect the dockercontroller.log files in the soam/work directory, for more information.

a. For the application profile enabled for Docker (using the enableDockerForServiceInstance="true" setting in the Consumer section), add the new optional configuration to the SOAM > SSM > OsTypes > OsType > env section:

<env name="SSM_DOCKER_ATTR_LABELS">{"com.example.vendor":"ACME", "com.example.license":"GPL"}</env>

<env name="SSM_DOCKER_ATTR_HOSTCONFIG_CAPADD">["SYS_PTRACE", "IPC_LOCK"]</env>

<env name="SSM_DOCKER_ATTR_HOSTCONFIG_CAPDROP">["NET_BIND_SERVICE", "SETUID", "SETGID"]</env>

<env name="SSM_DOCKER_ATTR_HOSTCONFIG_SECURITYOPT">["no-new-privileges"]</env>

<env name="SSM_DOCKER_CONTROLLER_LOGCONFIG">{"max-size":"100", "max-file":"2", "level":"7"}</env>

</osType>

</osTypes>

Note: Enable service instances to run in a Docker container according to the steps in IBM Documentation

b. From the primary host, reregister your Docker applications:

soamreg profile.xml

To configure RFE 149007 to support TLS connections for Docker:

Enabling service instances to run in a TLS-enabled Docker container involves configuring the application profile. You must first enable service instances to run in a Docker container, then configure the environment variables introduced by this enhancement to run service instances in a TLS-enabled Docker environment.

a. Enable service instances to run in a Docker container according to the steps in IBM Documentation.

b. Configure the application profile, either from the cluster management console or by manually editing the profile, to enable services instances to start in a TLS-enabled Docker environment:

· In the service section of the application profile, add the DOCKER_TLS_VERIFY environment variable. Valid values are 1 (enabled) or 0 (disabled). Default is 0.

For example:

<osType name="all"

startCmd="${SOAM_HOME}/${VERSION_NUM}/${EGO_MACHINE_TYPE}/bin/sympingservice">

</osType>

</osTypes>

…

</Service>

· Optional: Add the DOCKER_CERT_PATH environment variable to specify the location of the TLS authentication certificates for the Docker daemon and client. If your certificates are available at ${HOME}/.docker, you don’t need to define DOCKER_CERT_PATH.

· Optional: Add the DOCKER_API_VERSION environment variable to specify the Docker API version used by IBM Spectrum Symphony, the precondition is the Docker API version you specified should exist on the hosts; if not specified, IBM Spectrum Symphony will use the default Docker API version (1.21).

· Run the soamreg command to re-register the application.

4. Uninstallation

If required, follow these instructions to uninstall this enhancement on management hosts in your cluster:

a. Log on to the primary host as the cluster administrator:

> egosh user logon -u Admin

b. Disable all applications:

> soamcontrol app disable all -f

c. Shutdown the cluster:

> egosh service stop all

> egosh ego shutdown all

d. Log on to each management and compute host in the cluster and roll back this enhancement:

> egoinstallfixes -r 600838

e. Start the cluster:

> egosh ego start all

f. Enable your applications:

> soamcontrol app enable application_name

5. Troubleshooting

If RFE 149007 is not enabled successfully, following below steps to troubleshoot the problems.

a. If SSM could not start a SIM on compute host for the application successfully, check whether there is docker resource on compute host.

· go to the Resources -> Resource planning (slot) -> Resource groups -> ComputeHosts -> Member hosts from PMC page and check the docker_active value of compute host is a valid docker version (1.13.1).

· Check the /var/run/docker.sock exists on the compute host. The /var/run/docker.sock is needed to mount when docker startup.

b. If service container could not be started. There might be multiple reasons.

· SIM could not communicate with docker daemon, check following steps:

i. Check the docker daemon listening address matches with $HOST in $DOCKER_HOST_URL.

ii. Check the $HOST in DOCKER_HOST_URL can be parsed on compute host. If not, you can add the $HOST and address in the /etc/hosts.

iii. Check DOCKER_HOST_URL is a valid value on the compute host.

iv. Check the certificate is generated successfully and no expiration via docker command.

v. Check whether python is installed on compute host. The SIM need python script to communicate with docker daemon.

· If SIM start the container via docker daemon successfully, however the service container exit in a short time. Check whether lack of depended on package in the service images.

6. List of files

egocore-3.7.0_x86_64_build600838.tar.gz	3ce5fc7719880d2dbb047b6ae5924732
3.7/linux-x86_64/etc/egodocker/libs/pod/constants.py	5370d18c8943b852364508dd637ba83f
3.7/linux-x86_64/etc/egodocker/libs/pod/dockerclient.py	85c48a5307fa68cc0deca32bc5c17b29
3.7/linux-x86_64/etc/egodocker/libs/pod/dockercontainers.py	4f2d9bebc331a6efacdcc275ceacbed1
3.7/linux-x86_64/etc/egodocker/libs/external/docker/client.py	d4180c0440521f11213d1fb1e6ef2c4d
3.7/linux-x86_64/etc/egodocker/libs/external/docker/api/container.py	425d628351257fdbe799fde7d3197074
3.7/linux-x86_64/etc/egodocker/libs/external/docker/utils/utils.py	b60ff2b39295b3f8ee7b402ca5ab9180
3.7/linux-x86_64/etc/pem	af01057080d6fdb6c4d96934bfe8ce4a
soamcore-7.2.1.0_x86_64_build600838.tar.gz	0fedaec2781d5048d07ffa37d742c660
soam/7.2.1/linux-x86_64/etc/ssm	b6ef324af5b27cf60a1e048e0f915b50
soam/7.2.1/linux-x86_64/etc/sim	ec9f601862eabb785bb6e933aee4a877

7. Product notifications

To receive information about product solution and patch updates automatically, subscribe to product notifications on the My Notifications page http://www.ibm.com/support/mynotifications/ on the IBM Support website (http://support.ibm.com). You can edit your subscription settings to choose the types of information you want to get notification about, for example, security bulletins, fixes, troubleshooting, and product enhancements or documentation changes.

8. Copyright and trademark information

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM®, the IBM logo and ibm.com® are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml .