Post core component installation and configuration

Following the installation of the core components, but prior to installing the agents, you must complete the following tasks: 

Before starting services or any of the post installation tasks, ensure you have applied any service or agent Fix Packs; make sure you follow the instructions in the Fix Pack readme file. The latest Fix Packs can be found under Release notes and notices.

When you complete the post installation tasks in this section, you can perform one of the following tasks:



Start services

Following installation, you must start the TrueSight Middleware and Transaction Monitor (TMTM) services in the correct order. 

Note that two minutes after starting the TMTM services, a Monitor Edition or newly installed licensed edition of TrueSight Middleware Administrator (TSMA) will be configured if it hasn’t already been done so. See Verifying your TSMA integration below for further information, including how to login to TSMA for the first time.

Start and stop order

 In addition to the required start and stop order for services, the following table includes the program name for the services.

Start order

Services

Program

Stop order

1

TMTM Application Service

qpas

6

2

TMTM Topic Service

qpts

5

3

TMTM Event Service

qpes

4

4

TMTM History Service

qphs

3

5

TMTM Client Gateway Service

qpcgateway

2

6

(Optional) TMTM ProactiveNet Service

qpps

1

Before you begin

On UNIX systems, ensure that the UNIX userid that starts the services has read access to /dev/random and /dev/urandom.

To start the services on Windows

  1. Open the Windows Service Control Manager.
  2. Scroll through the services, and locate TMTM Application Service. The status of the service is displayed as Started if it is running or blank if it is stopped.
  3. Select TMTM Application Service and click Start. A dialog box appears indicating the service is being started.
  4. If the service does not start, verify that the service is proxy configured with a valid user account and password.
  5. Repeat for the remaining services in the start order listed in the Start and stop order table.

To start and stop the services on Windows or UNIX using the command prompt

  1. Open a command prompt.
  2. Perform the required operation listed in the following table using the corresponding long or short command option. 

    To do this…

    Use long option

    Use short option*

    Start the service.

    --start

    -s

    Stop (kill) the service.

    --stop

    -k

    Run the program as a console application.

    --console

    -c

    Debug the service configuration startup.

    --debug

    -d

    Specify the service's configuration file.

    --conf filename

    -f filename

    Print the product version and exit.

    --version

    -v

    Install the program as a Windows service, with an automatic startup (Windows only).

    --install

    -i

    Remove the program from the Windows Service Manager (Windows only).

    --remove

    -r

    Print this option list.

    --help

    -h

    Display transient checkpoint data and exit.--transient-t
    Specify the service to be debug build only, used with third party tools that change process name (for internal use only).--progname serviceName-p
    *The short options are not valid with the TMTM Client Gateway Service.

    Examples

    Start the TMTM Event Service with the long option:
    qpes --start

    Start the TMTM Application Service with the short option:
    qpas -s


Verify your TSMA integration

By default, two minutes after starting the TMTM services, a Monitor Edition or newly-installed licensed edition of TSMA will be configured if it hasn’t already been done so. During the configuration process, TSMA is restarted and TMTM will wait up to five minutes for TSMA to restart. BMC recommends that you wait about ten minutes before attempting to log in to TSMA for the first time. 

This section includes:

Verifying in the qpas-webmc.log file

After TSMA restarts, or TMTM stops reconnecting if there was a configuration issue, the qpas-webmc.log file contains LM_NOTICE output. Below is an example of the output, where the configuration succeeded: 

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA administrator user admin_user authenticates.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA ldap user ldap_user authenticates.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Users and groups used by TSMA are up to date.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Able to log in to TSMA using initial user admin.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA version 0.1.0 is sufficient for integration.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA key installed.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Default TSMA user id admin has been removed.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA user id admin_user configured.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Configured TSMA for LDAP_LDAP using internal LDAP

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA succesfully notified to restart.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Able to log in to TSMA using configured user admin_user.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] TSMA version 0.1.0 is sufficient for integration.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=265, Thread=Admin - 0] Restart succeeded after 16 seconds.

...Level=LM_NOTICE) [Client File=AdminControllerImpl.java, Line=242, Thread=Admin - 0] TSMA integration configuration complete.

Verifying using the mqtool CLI

You can also use the mqtool CLI to verify the configuration.

Below is an example of output when the configuration was successful. 

mqtool --check-config -p BMCSOFTWARE SA 

OPTION SETTINGS: --check-config = true

Able to log in to TSMA using configured user admin_user.

TSMA version 0.1.0 is sufficient for integration.

TSMA has key already installed.

TSMA has a Monitor Edition key.

TSMA uses the same LDAP as TMTM.

TSMA user id admin_user already configured.

TSMA is configured for LDAP_LDAP using internal LDAP.

TSMA has 0 projects defined. 

Logging into TSMA for the first time 

When logging into TSMA for the first time, and when using the TMTM security, you can use any user that is a member of the TSMA Administrators group or that has the “TSMA Integration Configuration” permission. For an initial test, you can use the SA user.

When using Active Directory you can use the TSMA administrative user specified during execution of the Security Configuration Tool.

If you are still unable to log in to TSMA, see the instructions in the following sections. 

Note

The WMQ connections need to be discovered as this will not be automatic. See Creating the WMQ Connection server connection channel. 

If you are using TMTM Security  

When integrating with TSMA located on another host, network interfaces are used by default to determine a hostname or IP address to configure TSMA, so that it can connect to TMTM.

Search the TSMA log (log/bmm.admin.log) for the string “URL”. For example: URL 'ldaps://testhost.bmc.com:15011'.

Verify the host from the log (for example, testhost.bmc.com) is reachable using ping or another network tool. 

If for some reason the hostname or IP address used is not reachable from the TSMA machine, you can specify a hostname or IP address by changing the ldap_hostname keyword of the [App_Service] stanza in services.cfg from localhost to a reachable hostname or IP address. When altering this value, you will have to re-install and re-configure TSMA as outlined in How to re-configure TSMA after configuration issues

If you are using Active Directory 

Verify that when the Security Configuration Tool was used, all the values passed validation. If not, re-execute the Security Configuration Tool and correct those values. Otherwise, execute the ADCheck CLI to see if it reports any possible configuration errors that can be corrected. If any configuration values were altered, reconfigure the TSMA integration by executing the following command from the TMTM installation directory:

mqtool --reconfigure -p BMCSOFTWARE SA

If the old value still seems to be in use, you may need to re-install TSMA and reconfigure, as outlined in How to re-configure TSMA after configuration issues.

Note that when logging into TMTM, make sure to add groups that match the groups configured in your Active Directory. A group where the TSMA administrative user specified during execution of the Security Configuration Tool is a member must have the “TSMA Integration Configuration” permission. Any group with the “TSMA Integration Configuration” permission is configured as an administrator in TSMA. If you add groups or change permissions you may need to re-install TSMA and reconfigure as outlined in How to re-configure TSMA after configuration issues.

Contacting BMC Support

If are still unable to log into TSMA, the following is required when contacting BMC Support.

  • Output from executing the mqtool CLI and ADCheck CLI to obtain the current configuration state.
    • Execute from the TMTM installation directory: mqool -v --check-config -p BMCSOFTWARE SA
    • Execute from the TMTM installation directory if using Active Directory, ADCheck.
  • TMTM do_support
  • TSMA logs

How to re-configure TSMA after configuration issues

  1. Stop TSMA
  2. Uninstall TSMA
  3. Re-install TSMA
  4. Start TSMA
  5. Execute from the TMTM installation directory: mqtool --reconfigure -p BMCSOFTWARE SA

If for some reason you are unable to re-install TSMA, you will need to contact BMC Support to assist you in altering the values in the TSMA database.


Secure communication among product components

This section describes the post-installation security setup when necessary.

Securing HTTPS in the TMTM Application Service

You can securely access the TMTM product launch page, distribute agents, or view and download reports by using HTTPS (configured, by default, on network port 15004).

HTTPS access to the TMTM Application Service is secured out of the box with a self-signed X.509 certificate. This certificate and its private key are held in the java keystore file in the following location: InstallDir/jetty/webapps/localhost.jks.

Note

TMTM can use two SSL security certificates. One for the TMTM Application Service in secure mode; the other when configuring Active Directory. These are different certificates and should not be confused.

That certificate is presented to your web browser whenever you visit a secured web page on the TMTM Application Service so that you can be certain that you are communicating only with the TMTM Application Service, and that any information sent or received remains confidential.

Most web browsers will not accept a self-signed certificate by default, but most browsers will let you import or temporarily accept a self-signed X.509 certificate. Always review the browser dialog boxes carefully when accepting a self-signed certificate to ensure it is the exact certificate you expect (and always take care to distribute the information you use to verify self-signed certificate by a trusted, secure means).

If your local security policies do not permit self-signed certificates, you must install a certificate signed by a trusted Certificate Authority. Use the following steps to install your own X.509 certificate.

To create a keystore file

  1. After creating or obtaining the certificate, generate a Java keystore format file by importing your certificate into the Java keystore file with the keytool java utility.
  2. Enter the following information to the keytool utility:
    • The certificate file name.
    • The location of the keystore to be created or updated.
    • An alias name (to identify this certificate in the future).
    • A keystore password (a new password if the keystore is being created or the previous keystore password if it is being updated).
    • The certificate password that came with the certificate.

To insert the obfuscated (OBF) encoded passwords in services.cfg

  1. Open services.cfg in a text editor and locate the lines:

    jetty_keystore=jetty/webapps/localhost.jks
    jetty_keystore_password=OBF:1fuk1kl61f9d1mrf1ldm1gu71ldw1mrn1f991klg1fuq
    jetty_keystore_keypassword=OBF:1fuk1kl61f9d1mrf1ldm1gu71ldw1mrn1f991klg1fuq

  2. To generate OBF encoded passwords for both the keystore and key passwords, run the obfpassword program twice from the installation directory.

    CD InstallDir
    obfpassword.bat password


    where password is the keystore or key password.

    Example output from the obfpassword.bat command

    password
    OBF:1O4O1ZLY1QW01VU11YM71YM71VV91QXQ1ZLK1O5Y
    MD5:48503DFD58720BD5FF35C102065A52D7 (ignore this line)

  3. Copy and paste the OBF generated passwords into the jetty_keystore_password and jetty_keystore_keypassword lines in services.cfg. Do not use the MD5 string.
  4. Replace jetty/webapps/localhost.jks with the path to your certificate where localhost.jks is the name of the new or existing keystore file.
  5. Recycle the services to enable the changes made after editing services.cfg.
  6. To verify that the expected certificates are being used by the TMTM Application Service, enter https://hostname:15004 in the address bar of the browser.
    where hostname is the host name or IP address of the computer running the TMTM Application Service

Certificates for securing TLS communications

The TMTM services use X.509 certificates to secure TLS communications in several scenarios. This section summarizes those certificates.

UseConfiguration SectionConfiguration OptionsContents
HTTPS[App_Service]

jetty_keystore

jetty_keystore_password

jetty_keystore_keypassword

HTTPS key and certificate.

A self-signed certificate is generated on qpas start if the keystore file does not already exist.

Password is plain text or OBF encoded. Password and key password must be the same.

LDAPS[App_Service]

ldaps_keystore

ldaps_keystore_password

LDAPS key and certificate.

A self-signed certificate is generated on qpas start if the keystore file does not already exist.

Password is plain text or Cryptor encoded.

LDAPS[App_Service]

javax.net.ssl.trustStore

javax.net.ssl.trustStorePassword

LDAPScertifcates.

A trusted entry for the self-signed certificate is added when the certificate is generated (above).

Entries for trusted Active Directory servers are also stored in here.Password is plain text or Cryptor encoded.

Agent Tunnel


[Tunnel_Service]

ssl_truststore_file

ssl_truststore_password

Agent certificates (see Tunneling Agent connections).

Password is plain text or OBF encoded.

ssl_keystore_file

ssl_keystore_password

Services keys & certificates (see Tunneling Agent connections).

Password is plain text or OBF encoded.

ssl_revokestore_file

ssl_revokestore_password

Revoked agent certificates (see Tunneling Agent connections).

Password is plain text or OBF encoded.

N/A (Not used at runtime)Root key for the tunnel service CA (internal certificates only; see Tunneling Agent connections).

Report Access in Secure Mode (HTTPS)

The same SSL certificate that is used to identify the Application Service is used to secure access to reports accessed either through the Management Console, via a browser, or from the command line (if using HTTPS in the report URL – which is the default option).

The SSL certificate is verified by the underlying HTTP client. The HTTP client making the request can attempt to verify the SSL certificate (i.e. verify that the certificate was issued by an already trusted Certificate Authority). If the identity cannot be verified by the HTTP client (usually be accessing pre-configured trust stores, such as Java keystores), the report might not render.

Some HTTP clients (e.g. web browsers, the Management Console) can give the user the option to verify the certificate themselves. That verification lasts for the current viewing session. Additionally, some HTTP clients (depending on local security policies) allow the user to import the certificate into a local trust store. That verification persists over future viewing sessions.

Users must consider that local security policies can override default behavior as described above (e.g. a site-wide policy might block users from importing any certificates into their browser).

To understand how to configure the certificates in the Application Service, refer to Services Configuration Examples.


Define Tunneling Agent connections

This section includes:

Overview

Connections between the TMTM Agent tier and the TMTM Services tier can, optionally, be routed via a secure tunnel. In this mode all network traffic between the TMTM Agent host and the TMTM Services host is tunneled via a single TCP/IP connection, and the traffic is encrypted using TLS.

This both protects the data from eavesdropping and simplifies the network management, since the only port requirements are for the TLS tunnel itself.

When a TMTM Agent is deployed from a bootstrap configuration it is configured to work against the TMTM Services from which it was deployed. If tunneling is configured in the Services, the Agent is deployed with the appropriate configuration options already set.

An exception to this is for end-user provided keys and certificates where client authentication is required. In this case, the agent must be configured with its keys and certificates after deployment.

Similarly to configuring the TMTM Services for end-user provided keys and certificates (see the Services Configuration Examples), the Java Keytool can be used to populate the key stores for the agent.

Configuration options should then be set in the agents configuration file (located in bmmtm_agent/configuration/services/tunnel.properties). Those properties are documented in the following table.

Note

If the TMTM Services tunnel configuration is changed after the agent has been deployed the agent's configuration will be out of date. A new agent deployment is required.

Many of the defaults for values are derived from those set in the services configuration (services.cfg). Those parameters are described in Defining configuration options in services.cfg.

TMTM Agents distributed as part of a bootstrap package have these properties set at the point of distribution.

Property name

Description

tunnel.to.address

Default: [Topic_Service].agent_ts_host
The hostname or IP to which agents connect.
Agent RTServer_Hostname preference overrides this property.

tunnel.to.port

Default: [Tunnel_Service].tunnel_port
The port number to which agents should connect.

tunnel.bind.address

Default: 0.0.0.0
If accepting service-initiated tunnel connections, the interface to which the agent binds.

tunnel.service.proxy.ms.local

Default : [App_Service].web_secure_port
The local port that serves as a proxy for the Media Service.
TMTM Config Extension ASPort preference overrides this property.

tunnel.service.proxy.ms.remote

Default : [App_Service].web_secure_port
The remote port to which the tunnel terminates Media Service connections.
TMTM Config Extension ASPort preference overrides this property.

tunnel.service.proxy.ts.local

Default: [Topic_Service].listen_port
The local port that serves as a proxy for the Topic Service.
Agent RTServer_Port preference overrides this property.

tunnel.service.proxy.ts.remote

Default : [Topic_Service].listen_port
The remote port to which the tunnel terminates Topic Service connections.
Agent RTServer_Port preference overrides this property.

tunnel.client.proxy.qpea.local

Default: 2612
The local port to which tunneled connections to the extensible agent are terminated.

tunnel.client.proxy.qpcfg.local

Default: 6002
The local port to which tunneled connections to qpcfg are terminated.

ssl.truststore.file

Default: bmtmAgentTrustStore.jks

ssl.truststore.password

Default : changeit
Password for the store file. Can be OBF encoded.
OBF encoded values must be escaped (e.g. "OBF\:xxx").

ssl.truststore.type

Default: jks

ssl.trustmanager.algorithm

Default: PKIX

ssl.keystore.file

Default: bmtmAgentKeyStore.jks

ssl.keystore.password

Default : changeit
Password for the store file. Can be OBF encoded.
OBF encoded values must be escaped (e.g. "OBF\:xxx").

ssl.keystore.type

Default: jks

ssl.keymanager.algorithm

Default: PKIX

Note

Tunneling is not a supported configuration for TMTM Agents and TMTM Services located on the same host. Starting a TMTM Configuration Agent that is configured with a tunnel enabled can result in errors – it uses ports that are either already in use, or it listens on ports that the TMTM Services need to operate.

Connection initiation direction

The tunnel connection initiation direction can be configured for each agent via the "ConnectionInitiation" preference, using the agentpref tool. It can also be set to an initial value when a bootstrap package is provisioned.

ConnectionInitiation

Description

0

No tunnel

1

Agent initiated (TCP connection originates from the Agent tier).

2

Service Initiation (TCP connection originates from the Service tier).

Note

Service Initiated Tunneling is not a supported configuration for multiple TMTM Agents located on the same host. Only one TMTM Agent set per-host can use a tunnel. Whilst it can be configured manually (by mapping the appropriate ports in the agent configuration), it is not a recommended configuration.

Service initiated tunnels for Tunneling Agent connections

Bootstrap packages that are provisioned with a "ConnectionInitiation" preference of "2" (which is equivalent to selecting the "TMTM Services initiate Secure Tunnel Connection to Agent" option on the Agent Distribution site) must be introduced to the TMTM Services using hosttool. This is required in order that the TMTM Services know that a tunnel must be initiated. See Managing hosts with the CLI for further details.

This step is not required if the Agent is deployed in a different connection initiation mode, and then later switches to a Service initiated tunnel mode (since, at that point, the Agent is already known to the Services).

When migrating an Agent to an alternate TMTM Service tier and the Agent is running a Service Initiated tunnel, the Agent must be explicitly removed from the previous TMTM Service tier. To do this, use the Object Repository tab in the Management Console, or hosttool.

Multiple Agents on a host

To support multiple agents using Agent Initiated tunnels, two additional ports must be defined via extension preferences (this is in addition to normal port customization required to support multiple agents – i.e. changes to eaapi.ini, and ServicePort preferences changes for the "WebSphere MQ Monitor" and "WebSphere MQ Configuration" extensions, as appropriate).

Extension name

Preference name

Value

TMTM Tunnel Service

ASProxyPort

Any free, unused port number.

TMTM Tunnel Service

MSProxyPort

Any free, unused port number.

So, for example:

% agentpref --port 2712 --set "BMTM Tunnel Service" ASProxyPort 16009
% agentpref --port 2712 --set "BMTM Tunnel Service" MSProxyPort 17009

Note

In the above examples a non-default port is used to communicate with qpea (2712 in the example, 2612 is the default). The example assumes that normal port customization has taken place for the additional agent set, and these extension preferences are being applied to that additional agent set.

Note

Service Initiated Tunneling is not a supported configuration for multiple TMTM Agents located on the same host. Only one TMTM Agent set per-host can use a tunnel. Whilst it can be configured manually (by mapping the appropriate ports in the agent configuration), it is not a recommended configuration.

TMTM Agent keys and certificates

If Agent Authentication is required in the TMTM Services, and internal certificates are being used, then each TMTM Agent must be explicitly authenticated to the TMTM Services after it has been deployed.

For example:

% cd bmtm-agent/bin
% agent –-console
osgi> authClient services.host.name userId password

where services.host.name should be replaced with the hostname of TMTM Services.

Depending on your configuration, you might be prompted to verify the TMTM Services certificate. Inspect the presented certificate carefully, and compare the signatures to ensure that you are authenticating with the expected entity.

If a TMTM Agent needs to trust a different TMTM Service (rather than the one from which it was deployed), it can add the TMTM Services to its trust store as follows:

% cd bmtm-agent/bin
% agent –-console
osgi> authServer services.host.name

where services.host.name should be replaced with the hostname of TMTM Services.

Depending on your configuration, you might be prompted to verify the TMTM Services certificate. Inspect the presented certificate carefully, and compare the signatures to ensure that you are trusting the expected entity.

A TMTM Agent only trusts one set of TMTM Services at a time. If it is directed to a previously trusted TMTM Service tier it must re-authenticate that server, using the process described above.

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Claudio Furuno

    The link to The WMQ connections need to be discovered as this will not be automatic. See Supported methods to define the server connection channel and TSMA WMQ Connection Ends with a page not found. Can you please correct this? Thanks

    Dec 17, 2018 07:02
  2. Claudio Furuno

    In the section called Service initiated tunnels for Tunneling Agent connections the link Managing hosts with the CLI ends with a page not found. Please correct the link. Thanks.

    Dec 17, 2018 07:08
    1. Ashley Pearson

      Claudio, thanks for your feedback regarding the two broken links. They are now linking correctly.

      Dec 17, 2018 07:37
  3. Claudio Furuno

    Thank you Ashley!

    Dec 17, 2018 07:50