Installing, configuring, and completing common usage scenarios for a TLS proxy

Edit online

This simple TLS/TCP proxy is used between IBM Netcool Operations Insight® applications that run on-premises and on Kubernetes cloud environments.

Before you begin

The proxy supports plain text, TLS, and mutual TLS connections. Use TLS version 1.3, but older versions of TLS are also supported.

About this task

License
Review and accept the terms in the license file before you use this software.
Installation
  1. You must enable the TLSProxy during the installation. To get the name of the deployment, use the following command:
    oc get noi
    Example:
    # oc get noi
NAME      AGE
noi-467   4d8h
  2. Edit the chart by using the following command: 
    oc edit noi <noi-deployment-name>
    Add the following lines:
    helmValuesNOI:
    tlsproxy:
      enabled: true
    proxy:
      enabled: false
  3. The proxy installation archive can be downloaded directly from the target cluster, as shown in the following example: 
    DEPLOYMENT_NAME=<noi-deployment-name>
    INGRESS_DOMAIN=$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})
    curl -kO https://netcool-${DEPLOYMENT_NAME}.${INGRESS_DOMAIN}/deploy/netcool-tls-proxy-0.0.4-linux-amd64.tar.gz
    Note: Examples use evtmanager as the DEPLOYMENT_NAME. You must use the DEPLOYMENT_NAME=<noi-deployment-name>, where <noi-deployment-name> is the name of your deployment.
    Extract the tar archive on the target system and configure according to the quick start instructions or one of the how-to scenarios.

Procedure

  1. Configure plain text to TLS. The following route configuration specifies two routes that both accept a plain text connection and connect to a TLS version 1.3 server. This configuration scenario is typical of one that Netcool® Operations Insight ObjectServer IDUC Gateway requires. 
    {
    "routes": [{
            "name": "primary-tds",
            "source": {
                "host": "0.0.0.0",
                "port": 4100,
                "tls": false
            },
            "destination": {
                "host": "DESTINATION_ADDR",
                "port": 4100,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "trusted-cert.pem"
                }
            }
        },
        {
            "name": "primary-iduc",
            "source": {
                "host": "0.0.0.0",
                "port": 4101,
                "tls": false
            },
            "destination": {
                "host": "DESTINATION_ADDR",
                "port": 4101,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "trusted-cert.pem"
                }
            }
        }
    ]
}
    1. The server trusted certificate is stored in the trusted-cert.pem file. To create this file on a system with Kubernetes API access through oc or kubectl, run the following command: 
      oc get secret ${RELEASE_NAME}-tlsproxy-cert -o go-template='{{ index .data "tls.crt" }}' -n ${NAMESPACE} | base64 --decode > ${DEPLOYMENT_NAME}-tlsproxy-cert.pem
    2. The DESTINATION_ADDR that is specified in the route configuration must match a value in the Subject Alternative Name extension section of the certificate that is presented by the server. 
      openssl x509 -text -noout -in trusted-cert.pem
    ...
    X509v3 Subject Alternative Name: 
        DNS:evtmanager-tlsproxy.netcool.svc, DNS:evtmanager-tlsproxy.netcool.svc.cluster.local
    3. It might be necessary to create an entry in /etc/hosts to provide name resolution. 
      cat /etc/hosts
    ...
    CLUSTER_IP evtmanager-tlsproxy.netcool.svc
    4. Start the proxy. 
      NETCOOL_TLS_PROXY_ROUTE=routes.json ./netcool-tls-proxy
  2. Configure the proxy with environment variables and a routes configuration file. Values that are specified in the routes configuration file take precedence over values from the environment. The routes configuration file defines the source and destination elements that both comprise a route. See the following example for a simple route configuration: 
    {
    "routes": [{
            "name": "primary-tds",
            "source": {
                "host": "0.0.0.0",
                "port": 4100,
                "tls": false
            },
            "destination": {
                "host": "netcool.uk.ibm.com,
                "port": 4100,
                "tls": true
            }
        }
    ]
}
    The following table describes the route configuration.
    Name Description
    routes Array of route objects.
    name Text description of route.
    source Object describing the listening side of the proxy.
    host Hostname or IP address to listen for connection.
    port Port number to listen for connection.
    tls Enable TLS authentication (true or false).
    destination Object describing the connecting side of the proxy.
    host Hostname or IP address to dial.
    port Port number to dial.
    1. If necessary, specify TLS configuration parameters in a configuration file for each half of a route by defining a tlsConfig object. 
      "tlsConfig": {
    "tlsVersion": "TLS_13",
    "tlsAuth": "server",
    "certPath": "cert.pem",
    "keyPath": "key.pem",
    "trustCertPath": "cert.pem"
}
      The following table describes the route configuration.
      Name Description
      tlsConfig TLS configuration object
      tlsVersion Minimum version of TLS supported (TLS_12 or TLS_13)
      tlsAuth TLS authentication type (SERVER|MUTUAL)
      certPath Path to x509 certificate
      keyPath Path to private key
      trustCertPath Path to peer trusted certificate.
    2. In the absence of a tlsConfig object, configuration is read from environment variables. Running the proxy with --help displays all environment variables that are used by the proxy and their current value. 
      bin/netcool-tls-proxy --help
    netcool-tls-proxy
    -help
            Output help text
    -version
            Output version info
    Env:
    NETCOOL_TLS_PROXY_ROUTE=(unset)
    NETCOOL_TLS_PROXY_SOURCE_CERT=(unset)
    NETCOOL_TLS_PROXY_SOURCE_KEY=(unset)
    NETCOOL_TLS_PROXY_SOURCE_TRUST_CERT=(unset)
    NETCOOL_TLS_PROXY_DESTINATION_TRUST_CERT=(unset)
    NETCOOL_TLS_PROXY_DESTINATION_CERT=(unset)
    NETCOOL_TLS_PROXY_DESTINATION_KEY=(unset)
    NETCOOL_TLS_PROXY_TLS_AUTH_TYPE=(unset)
    NETCOOL_TLS_PROXY_TLS_MIN_VERSION=(unset)
    NETCOOL_TLS_PROXY_HEALTH_HTTP=(unset)
    NETCOOL_TLS_PROXY_HEALTH_PORT=(unset)
      The following definitions explain the environment variable values:
      NETCOOL_TLS_PROXY_ROUTE
      The path to the route configuration file.
      NETCOOL_TLS_PROXY_SOURCE_CERT
      The certificate path for the source (listening) side of the proxy.
      NETCOOL_TLS_PROXY_SOURCE_KEY
      Key path for source (listening) side of proxy.
      NETCOOL_TLS_PROXY_SOURCE_TRUST_CERT
      The trusted certificate path for the client verification on the source (listening) side of proxy (Mutual TLS).
      NETCOOL_TLS_PROXY_DESTINATION_TRUST_CERT
      The trusted certificate path for the destination (dialing) side of the proxy.
      NETCOOL_TLS_PROXY_DESTINATION_CERT
      The certificate path for the destination (dialing) side of the proxy (Mutual TLS).
      NETCOOL_TLS_PROXY_DESTINATION_KEY
      The key path for the destination (dialing) side of the proxy (Mutual TLS).
      NETCOOL_TLS_PROXY_TLS_AUTH_TYPE
      The TLS authentication type (SERVER or MUTUAL).
      NETCOOL_TLS_PROXY_TLS_MIN_VERSION
      Minimum accepted TLS version (TLS_12 or TLS_13).
      Note: If you want to send data from on-premises probes, for example Simnet, to your Netcool Operations Insight on Red Hat® OpenShift® deployment, you must specify TLS_12 as the NETCOOL_TLS_PROXY_TLS_MIN_VERSION value.
      NETCOOL_TLS_PROXY_HEALTH_HTTP
      Health API (ON or OFF).
      NETCOOL_TLS_PROXY_HEALTH_PORT
      Health API listening port.

Connect an on-premises IDUC client

  1. Follow these steps to complete common usage scenarios. Connect an on-premises IDUC client to the IBM Netcool Operations Insight cloud ObjectServer deployment.
    1. [Cloud] Expose ObjectServer ClusterIP ports by using the loadbalancer service.

      Use the loadbalancer service in a development or test environment to expose ObjectServer ClusterIP services externally. Set the variables according to your environment. The WORKER_IP variable doesn't need to match the node that hosts the ObjectServer.

      NAMESPACE=netcool
DEPLOYMENT_NAME=evtmanager
WORKER_IP=1.2.3.4
cat <<- EOF | oc create -n ${NAMESPACE} -f -
apiVersion: v1
kind: Service
metadata:
  name: ${DEPLOYMENT_NAME}-tlsproxy-loadbalancer
spec:
  ports:
  - name: aggp-tds
    port: 4100
  - name: aggp-iduc
    port: 4101
  - name: aggb-tds
    port: 4102
  - name: aggb-iduc
    port: 4103
  - name: tlsproxy-http
    port: 8000
  externalTrafficPolicy: Cluster
  externalIPs:
  - ${WORKER_IP}
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: tlsproxy
EOF
    2. [Cloud] Change the backup ObjectServer to use port 4103 for IDUC.
      To avoid a port number clash, when both the primary and backup ObjectServer services are deployed on the same cluster, change the IDUC port number that is used by the backup ObjectServer service.
      DEPLOYMENT_NAME=evtmanager
oc patch sts ${DEPLOYMENT_NAME}-ncobackup \
-p '{"spec":{"template":{"spec":{"containers":[{"name": "ncobackup-agg-b", "env":[{"name": "NCO_IDUC_LISTENING_PORT","value": "4103"}]}]}}}}'
      Fix the backup ObjectServer service to reflect the port number change.
      oc patch svc ${DEPLOYMENT_NAME}-objserv-agg-backup -p '{"spec":{"ports":[{"name": "backup-iduc-port-patch","port": 4103}]}}'
    3. [On-premises] Add primary and backup ObjectServer IDUC hostnames to /etc/hosts. 
      DEPLOYMENT_NAME=evtmanager

cat << EOF >> /etc/hosts
127.0.0.1 ${DEPLOYMENT_NAME}-objserv-agg-primary ${DEPLOYMENT_NAME}-objserv-agg-backup 
EOF
    4. [On-premises] Store the proxy certificate as a trusted certificate on the on-premises host. In a trusted environment, the certificate can be read directly through the following command: 
      CLUSTER_ADDRESS=$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})
    DEPLOYMENT_NAME=evtmanager
    echo -n | openssl s_client -connect ${CLUSTER_ADDRESS}:4100 \
    -servername ${DEPLOYMENT_NAME}-tlsproxy.netcool.svc | \
    openssl x509 > ${DEPLOYMENT_NAME}-tlsproxy-cert.pem
      Alternatively, on a system with Kubernetes API access through oc or kubectl, run the following command:
      DEPLOYMENT_NAME=evtmanager
    NAMESPACE=netcool
    oc get secret ${DEPLOYMENT_NAME}-tlsproxy-cert \
       -o go-template='{{ index .data "tls.crt" }}' \
       -n ${NAMESPACE} | base64 --decode > ${DEPLOYMENT_NAME}-tlsproxy-cert.pem
    5. [On-premises] Add the Subject Alternative Name from the certificate to the /etc/hosts folder. 
      CLUSTER_IP=1.2.3.4
    DEPLOYMENT_NAME=evtmanager
    SAN=${DEPLOYMENT_NAME}-tlsproxy.netcool.svc
    echo << EOF >> /etc/hosts
    ${CLUSTER_IP} ${SAN} 
    EOF

      The Subject Alternative Name can be read from the certificate:

      openssl x509 -text -noout -in ${DEPLOYMENT_NAME}-tlsproxy-cert.pem
    ...
    X509v3 Subject Alternative Name: 
        DNS:evtmanager-tlsproxy.netcool.svc, DNS:evtmanager-tlsproxy.netcool.svc.cluster.local

      To complete TLS authentication, the DESTINATION_ADDR that is specified in the route configuration must match a value in the Subject Alternative Name extension section of the certificate that is presented by the server.

    6. [On-premises] Configure the proxy route. 
      DEPLOYMENT_NAME=evtmanager
SAN=${DEPLOYMENT_NAME}-tlsproxy.netcool.svc
DESTINATION_ADDR=${SAN}
TRUSTED_CERT=${DEPLOYMENT_NAME}-tlsproxy-cert.pem
cat << EOF > routes.json
{
    "routes": [{
            "name": "primary-tds",
            "source": {
                "host": "0.0.0.0",
                "port": 4100,
                "tls": false
            },
            "destination": {
                "host": "${DESTINATION_ADDR}",
                "port": 4100,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "${TRUSTED_CERT}"
                }
            }
        },
        {
            "name": "primary-iduc",
            "source": {
                "host": "0.0.0.0",
                "port": 4101,
                "tls": false
            },
            "destination": {
                "host": "${DESTINATION_ADDR}",
                "port": 4101,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "${TRUSTED_CERT}"
                }
            }
        },
        {
            "name": "backup-tds",
            "source": {
                "host": "0.0.0.0",
                "port": 4102,
                "tls": false
            },
            "destination": {
                "host": "${DESTINATION_ADDR}",
                "port": 4102,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "${TRUSTED_CERT}"
                }
            }
        },
        {
            "name": "backup-iduc",
            "source": {
                "host": "0.0.0.0",
                "port": 4103,
                "tls": false
            },
            "destination": {
                "host": "${DESTINATION_ADDR}",
                "port": 4103,
                "tls": true,
                "tlsConfig": {
                    "tlsVersion": "TLS_13",
                    "tlsAuth": "server",
                    "trustCertPath": "${TRUSTED_CERT}"
                }
            }
        }
    ]
}
EOF
    7. [On-premises] Start the proxy. 
      NETCOOL_TLS_PROXY_ROUTE=routes.json ./netcool-tls-proxy
    8. [On-premises] Configure the $NCHOME/etc/OMNI.dat file. 
      cat << EOF >> $NCHOME/etc/omni.dat
[OCP_AGG_P]
{
	Primary: 127.0.0.1 4100
}
[OCP_AGG_B]
{
	Primary: 127.0.0.1 4102
}
EOF

$NCHOME/bin/nco_igen
    9. You can now connect an IDUC client to the cloud-based ObjectServer services through the secure TLS tunnel provided by the TLS proxy.