Changing the agent managed system name

Edit online

Different procedures apply to change the managed system name for different Cloud APM agents. For some agents, changing the managed system name means changing the host name or agent instance name (or both) in the managed system name. For other agents, specific procedures are required to change the managed system name.

Before you begin

Get familiar with the managed system name formats and naming restrictions as described in Managed system names.

About this task

For most Cloud APM agents, you can use the CTIRA_HOSTNAME parameter to change the host name used in the managed system name. To change the agent instance name in the managed system name for multi-instance agents, you can use the agent configuration parameter. If you have configured the agent, you must reconfigure it to assign a different agent instance name. After you reconfigure the agent, you will not be able to retrieve the data collected by the previous agent instance.

You might not be able to change the managed system name in one single procedure, depending on which part of the managed system name you want to change.

To find out the managed system name change method for the agent of your interest, refer to Table 1.

Exception: Changing the managed system name is not supported by the HTTP Server agent, Node.js agent, or the Synthetic Playback agent
Table 1. Changing managed system name methods for Cloud APM agents
Agent managed system name change method
Amazon EC2 agent Use agent configuration parameter to change the EC2 subnode name in the managed system name, see Configuration parameters for the Amazon EC2 agent.
Amazon ELB agent

Create a new agent instance with a new instance name to change the managed system name.
Azure Compute agent Use agent configuration parameter to change the subnode name in the managed system name, see Configuration parameters for the Azure Compute agent.
Cassandra agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Cisco UCS agent Use agent configuration parameter to change the agent instance name, see Configuration parameters for the agent.
Citrix VDI agent Use agent configuration parameter to change the Citrix site name, see Configuration parameters for the Citrix VDI agent.
Db2® agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
DataPower® agent Use agent configuration parameter to change the managed system name, see Configuring the DataPower agent.
DataStage® agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Hadoop agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
HMC Base agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
IBM® Cloud agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
IBM Integration Bus agent Specifying unique managed system name for IBM Integration Bus agent
JBoss® agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Linux® KVM agent Use agent configuration parameters, see Configuring Linux KVM monitoring.
Linux OS agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft .NET agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft Active Directory agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft Exchange Server agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft Hyper-V Server agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft IIS agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft Office 365 agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Microsoft SQL Server agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Microsoft SharePoint Server agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
MongoDB agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
MySQL agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
NetApp Storage agent Use agent configuration parameters, see Configuring NetApp Storage monitoring.
OpenStack agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Oracle Database agent Use agent configuration parameters, see Configuring Oracle Database monitoring.
PHP agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
PostgreSQL agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
RabbitMQ agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Response Time Monitoring agent Specifying unique managed system name for the Response Time Monitoring agent
Ruby agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
SAP agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
SAP HANA Database agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
SAP NetWeaver Java™ Stack agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Siebel agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Skype for Business Server agent (formerly known as Microsoft Lync Server agent)

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
Sterling File Gateway agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Sterling Connect Direct agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
Tomcat agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
UNIX OS agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.
WebSphere® Applications agent

To change the host name in the managed system name, see Changing the host name in MSN.

To change the server alias name in the managed system name, reconfigure the agent, see Reconfiguring the data collector interactively.
WebSphere Infrastructure Manager agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Use agent configuration parameter to change the instance name in the managed system name.
WebSphere MQ agent Specifying unique managed system names for multiple queue managers
Windows OS agent

Use CTIRA_HOSTNAME parameter to change the host name in the managed system name. See Changing the host name in managed system name.

Changing the host name in managed system name

Edit online

About this task

It is not a common practice to change the host name in the managed system name. The host name is automatically detected and set during agent configuration. Change the host name in the managed system name only when necessary and make sure the value that you specify does not cause any truncations due to managed system name naming restrictions.

Procedure

  1. Stop all existing instances of the agent and wait for the Cloud APM console to show that the agent or its subnodes are offline. If you do not have any existing agent instances, proceed to the next step.

    For more information about stopping agent instances, see Using agent commands.

  2. If the agent is a single-instance agent, complete the following steps to change the CTIRA_HOSTNAME parameter. The value that you specify for the CTIRA_HOSTNAME parameter is the value that is applied to all new agent instances.
    1. Make a backup copy of the following file:
      • Linux or AIXinstall_dir/config/pc.environment
      • Windowsinstall_dir/TMAITM6_x64/kpccma.ini
      where:
    2. Edit the file by changing the CTIRA_HOSTNAME parameter value as follows, where newhostname is the custom string that is used instead of the actual host name of the computer where the agent is installed.
      • Linux or AIXCTIRA_HOSTNAME=newhostname
      • WindowsCTIRA_HOSTNAME=newhostname .TYPE=REG_EXPAND_SZ
    3. Save your changes.
  3. If the agent is a multi-instance agent, complete the following steps to change the CTIRA_HOSTNAME parameter. Normally all agent instances on a computer use the same host name value. If you need agent instances to use differing values, vary the value that you assign to CTIRA_HOSTNAME when you perform this step.
    1. Make a backup copy of the following files:
      • Linux or AIXinstall_dir/config/pc_instance.environment
      • Windowsinstall_dir/TMAITM6_x64/kpccma_instance.ini
    2. Edit the file the change the CTIRA_HOSTNAME parameter value as follows:
      • Linux or AIXCTIRA_HOSTNAME=newhostname
      • WindowsCTIRA_HOSTNAME=newhostname .TYPE=REG_EXPAND_SZ
    3. Save your changes.
  4. Windows Reconfigure existing agent instances. You can either reconfigure the agent using the procedure in Using the IBM Cloud Application Performance Management window on Windows systems or use the agent .bat script to configure the agent. See Using agent commands for more details on using the agent .bat script. If the agent .bat script does not provide a config option, use the IBM Cloud Application Performance Management GUI to reconfigure the agent.
  5. Start all agent instances.

What to do next

After you change the agent managed system name, start the Cloud APM console and modify your applications by removing the old managed system name from applications and adding the new managed system name in its place.