Configuring agents to connect to a different server or to use HTTPS communication

Edit online

Before you install agents, you must configure the installation package to connect to the Cloud APM server. Agent package configuration is done automatically during server installation or done manually at another time. If you want to change the Cloud APM server that the agents connect to or to connect the agents using HTTP communication, run the agent2server script.

About this task

The agent2server script is run on each managed system that you want to connect to a different Cloud APM server or if you want to use HTTPS communication to connect with the current Cloud APM server.
The change in server connection affects all agents that are installed on the managed system. For example, if you have the Linux® OS agent, IBM® Integration Bus agent, and WebSphere® MQ agent on the same system, all three agents are reconnected to a different Cloud APM server.
The script is run with a different option, depending on whether agent communication with the server uses the HTTP or secure HTTPS protocol.
For HTTPS communications, determine the type of certificates you plan to use. See Configuring certificates between the server and agents for HTTPS communication for more details. After you configure the Cloud APM server to use certificates for agent to server communication, you then continue using the instructions in this procedure to reconfigure existing agents to use HTTPS communication and the certificates that you chose to deploy. Before reconfiguring the agents, an extra step is required to copy the agent configuration package from the Cloud APM server to the managed system. The server information in the agent configuration package is used to modify the managed system for the Cloud APM server address and signer certificate.

Procedure

Take the following steps to change the Cloud APM server connection of all agents that are installed on the managed system to connect to a different Cloud APM server or to use HTTPS communication to connect with the current Cloud APM server:

If the managed system uses secure HTTPS communications, copy the agent configuration package from the Cloud APM server to the managed system.
The agent configuration package is the output of the make_configuration_packages script, which was run during the server installation. If you want to configure the agent images see (Downloading and installing the server) or run manually later, see (Configuring the downloaded images).
If you configured HTTPS communication during the Cloud APM server installation, you must copy the onprem_config compressed file from the install_dir/ccm/agentconfig directory on the Cloud APM server to a managed system directory, such as /opt/ibm/apm/newagentconfig/onprem_config.tar for Linux, AIX®, or Solaris or \IBM\APM\newagentconfig\onprem_config.zip for Windows.

If you configured HTTPS communication or new certificates after the Cloud APM server installation, you must copy the onprem_config compressed file from the configuration package directory that was specified when you ran the make_configuration_packages.sh script.
.
On the managed system, change to the install_dir/bin directory. Examples:
- ```
cd /opt/ibm/apm/agent/bin
```
- ```
cd \IBM\APM\agent\bin
```
For nonsecure HTTP communications, run the following command to reconfigure the agents to connect to the specified Cloud APM server. Otherwise, continue to the next step for secure HTTPS communications.
- ```
./agent2server.sh -s host_name
```
- ```
agent2server.bat -s host_name
```
where host_name is the IP address or fully qualified host name of the system where the Cloud APM server is installed that you want to connect to.
For secure HTTPS communications, complete the following steps:
1. If you are not using the default certificates, you must modify the agent configuration file to show which certificate the agent must use. Modify the KDEBE_KEY_LABEL=agent_key_label variable or add it to the configuration file if it does not exist. Replace agent_key_label with the label that you entered when you created the agent keystore in Configuring a self-signed certificate or Configuring a Third-Party Root CA custom certificate for HTTPS agent communications.
  If your third-party CA provides only an RSA signature, change the KDEBE_FIPS_MODE_ENABLED=SuiteB-128 variable to KDEBE_FIPS_MODE_ENABLED=NO. The configuration file is platform dependent:
  - For a 64-bit installation, modify the variable in the \TMAITM6_x64\KPCENV file where PC is the agent product code. For example, for an agent that is installed in the C:\IBM\APM directory, to modify the OS agent configuration on a 64-bit installation, you must change the C:\IBM\APM\TMAITM6_x64\KNTENV file.
  - For a 32-bit installation, modify the variable in the \TMAITM6\KPCENV file where PC is the agent product code.
  - Modify the variable in the agent_installation_path/config/global.environment file.
2. Run the agent2server script to reconfigure the agents to use HTTPS communication to the Cloud APM server:
  - ./agent2server.sh -f path
  - agent2server.bat -f path
    where path is the path to the agent configuration package that you copied to the agent system in step 1.
    The following examples specify the full path to the agent configuration packages on Linux and Windows managed systems:
    agent2server.sh -f /opt/ibm/apm/newagentconfig/onprem_config.tar
    agent2server.bat -f ..\..\newagentconfig\onprem_config.zip
If you change the agent configuration from using http to https or vice versa for connecting to the Cloud APM server, perform the following steps to configure the protocol and hostname that the agents use to download configuration files from the Cloud APM server:
1. If you are not logged in to the Cloud APM console, log in now. For more information, see Starting the Cloud APM console .
2. Click System Configuration > Advanced Configuration and click Agent Central Configuration.
3. Ensure that the Host Name Override field specifies the same IP address or fully qualified host name that you use to configure the agents when you run the agent2server.sh script.
4. Ensure that the Protocol field specifies the same protocol that you use to configure the agents when you run the agent2server.sh script.
5. After you click Save, the Cloud APM server sends the new central configuration URL to the agents.
  
  Note: All agents are configured to use the same Central Configuration URL to download their configuration files from the Cloud APM server when you perform the procedure. It is not possible to configure a subset of the agents to use a different Central Configuration URL.

Results

The agents are reconfigured to connect to a different Cloud APM server or HTTPS communications are established with the server. If you ran the script for using secure HTTPS communications, the agents are also configured with the signer certificate for the new server. The agents no longer connect to the original server.

What to do next

You must configure the Cloud APM server agents to use HTTPS and certificates. See Configuring the communications protocol for server agents for instructions.