Renaming the AR System server

You must scan for AR System server names and rename servers in the following circumstances:

You move your database to a new environment during an upgrade.
You copy a production database to a development or test environment.
You use a standard image to instantiate a virtual machine for BMC Remedy AR System.
You move your existing AR System server into a multitenant mid tier environment, which requires that each AR System server is uniquely named.

Use the BMC Remedy AR Server Rename utility to rename an AR System server and to ensure that the server name used by the mid tier and the AR System server is the same.

Using the Rename utility, you can:

Scan the database for the AR System server name
Replace the AR System server name in the following locations:
- Specified forms and fields in the database
- Specific configuration files and property files
- Windows Services and Registries

This topic explains how to use the Rename utility to scan for and replace the server name:

Sequence of server name replacement tasks
Rename utility command and options
Scanning the database for the server name
Replacing the server name in the database
Scanning and replacing the server names in a server group
Replacing the server name in files, services, and registry entries
Purge the server name in the server group metadata tables

Sequence of server name replacement tasks

Perform the server name replacement tasks in the following order:

Scan the database for the server name.
Replace the server name in the database. In a server group environment, perform this operation only on the primary AR System server.
Replace the server name in files. In a server group, perform this operation on all servers in the server group.
(Windows only) Replace the server name in the Windows Services and Registries. In a server group, perform this operation on all servers in the server group.
Restart your computer. In a server group, restart the computers on which the primary and secondary servers are running.

Rename utility command and options

The BMC Remedy AR Server Rename command-line utility (arsrename.bat or arsrename.sh) is available in the ARSystemInstallationFolder\ARSystem\artools folder. Use the following command and its options to run the utility:

Run this utility in scan mode first to produce the output. Review the output and then proceed to run the utility in rename mode using this output.

arsrename

[-u] [-p] [-a] [-x] [-t] [-timeout]
[-o] [-tokens] [-f] [-fsf] [-fsv] [-ie] [-ief] [-del ]

The following table describes the arsrename command options, which can be used in any order in the command.

Scanning the database for the server name

Use the Rename utility to scan for the AR System server name or a token string in the database (Regular forms, character and diary fields). For example, in a multitenant environment, you can use the utility to scan the database forms and fields for occurrences of the onbmc-s string in the AR System server name on the myARServer computer. At the command prompt, type the following command:

arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -tokens "onbmc-s"
-f "c:\data\Output.csv"
-timeout 120:600:1800

The output of the scan operation is a CSV file (output.csv) that displays the results of the scan as a table consisting of the information shown in the following figure and described in the subsequent table:

Output of the scan operation

Column Name	Description
Form name	Name of the regular form in which the AR System server name is found
Field ID	ID of the character field in which the AR System server name is found
Is Partial (Y/N)?	Flag that indicates whether the field contains a partial or a complete string of the server name: Y—Partial string N—Whole string
Merge (Y/N)?	Flag that indicates whether the scanned server name is to be replaced or not; this value is referred to during the replace operation Y—Standard field N—Custom field; not replaced during replace operation If you want even the custom fields to be replaced, you must enter Y in the column for the custom field whose server name value you want to replace. Note: In 9.1.02, this option in non-functional. Irrespective of the value specified in the Merge column, the BMC Remedy AR Server Rename command-line utility replaces all the form fields including custom forms with the scanned server name. Workaround Manually remove the form name in the output.csv
Special (Y/N)?	Flag that indicates special handling required during the replace operation

Tip

You can use the output generated by the scan operation directly as input for the replace operation, which replaces the server name in database.

Examples

Use the following command to perform a fast scan for 5,000 entries:

Arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.csv -fsf 1 -fsv 5000 -tokens onbmc-s

Use the following command to scan only the forms listed the inclusion-exclusion list (a text file) available at the specified path:

arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.csv -ie 2 -ief
C:\<ARSystemInstallationFolder>arsystem\artools\etc\inclusion-exclusion-list.txt -tokens onbmc-s

Note

Running the scan in Fast mode indicates that only first 5000 entries are scanned as a sample to find presence of the old server name. If it is not found in first 5000 entries, such form is ignored from the output.This helps to scan faster when a form has thousands or millions of entries. However, use this option with caution since it may not replace server name in forms that have huge amount of data and server name missing from first 5000 entries.

Format of the inclusion-exclusion list

You can control the forms that are scanned by creating an inclusion-exclusion text file that contains the list of forms that you want to include in or exclude from the scan and the qualification that you want to set for the scan.

The following sample code shows the format of the inclusion-exclusion list:

#--Inclusion list
#----below mentioned qualification is for fetching outgoing messages that are to be send
i,AR System Email Messages,'18092'=1 and '18099'=1
i,SRM:Request,'7'<7000
i,SLM:Measurement,'300364200'=0
i,AR System Server Group Operation Ranking
i,AR System Service Failover Ranking
i,AR System Service Failover Whiteboard
i,AR System Configuration Component
i,AR System Configuration Component_Backup
i,AR System Configuration Setting
i,AR System Configuration Setting_Backup

#--Exclusion list
e,AR System API Statistics
e,AR System Email Error Logs
e,AR System Email Error Messages
e,AR System Service Statistics
e,AR System Service Statistics Configuration
e,AR System Version Control: Object Modification Log
e,AR System Version Control: Object Reservation Label
e,AP:Detail
e,AP:Question-Comment-Info
e,Application Pending
e,BPCU-Logs
e,Server Statistics
e,FB:History
e,AR System Historical License Usage
e,AR System Log: SQL
e,AR System Log: Alert
e,AR System Log: Server Group
e,AR System Log: User
e,AR System Log: Thread
e,AR System Log: ALL
e,AR System Log: Archive
e,AR System Log: Escalation
e,AR System Log: FullText Index
e,AR System Log: API
e,AR System Log: Filter

e,HPD:HelpDesk_AuditLogSystem
e,NTE:Notifier Log
e,SRD:AuditLog
e,CTM:AuditLogSystem
e,CTM:CFG PeopleTagNumGenerator

The following table describes the formats used in this file:

Format	Description
#	Specifies a comment line
i	Specifies the inclusion list
e	Specifies the exclusion list

Exclusions from the scan operation

The scan operation ignores the following forms and fields during scanning:

Archive forms
Audit forms
Reserved fields on any regular forms
- Core fields with field IDs ranging from 1 to 99 (except field ID 8)
- Distributed Server Option (DSO) fields with field IDs ranging from 300 to 322
- Dynamic groups with IDs ranging from 60000 to 60999
- Special fields
  - 112 (Access control)
  - 179 (GUID)
  - 160 (Locale)

Server Statistics form
AR System API Statistics form
AR System Service Statistics form
AR System Service Statistics Configuration form
AR System Version Control: Object Modification Log form
AR System Version Control: Object Reservation Label form
AP:Detail form
AP:Question-Comment-Info form
Application Pending form
AR System Email Error Logs form
AR System Email Error Messages form
AR System Email Messages form
BPCU-Logs form

Replacing the server name in the database

Use the Rename utility to replace the AR System server name in the database. The replace operation takes a CSV file as an input and either completely or partially replaces the server names, depending upon the values specified in the input CSV file. The input.csv file is available in the AR_SERVER_HOME\artools\etc folder.

Notes

The input.csv file contains the information required to replace the server names in a tabular format with the same columns as the output.csv file.
Use the input.csv file if you have not done any customizations to get the server name in any base field, overlay, or custom field.

Warning

Use the -del command with operation code 2—Replace string tokens to delete entries from the following forms:
- AR System Server Group Operation Ranking
- AR System Service Failover Ranking
- AR System Service Failover Whiteboard
- UDM:Config
- AR System Configuration Component

The replace operation replaces only those forms or fields that have a Merge flag set to Y in the input.csv file. To handle special cases, specify Y in the Special (Y/N?) column of the input.csv file.

As an example, use the following command to replace the onbmc-s string with tenant1-onbmc-s:

arsrename -x myARServer -u Demo -o -p <password> 2 -tokens "onbmc-s=tenant1-onbmc-s"
-f "<C:\Program Files\BMC Software\ARSystem\artools\etc\arsrename\input.csv>"
-timeout 120:600:1800

Scanning and replacing the server names in a server group

When using the arsrename.bat utility for scanning or replacing servers in a server group, ensure that you provide multiple tokens to scan and replace the server group alias name (Server-Name config parmeter) as well as individual host names. In the following examples, the prod-s string is the server group alias name in Production and prodVmName1 and prodVmName2 are the host names in Production. test-s is the server group alias name in Test environment and testVmName1, testVmName2 are the host names in Test environment.

Example for scanning multiple server names in one command (option 1)

arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -tokens "prod-s,prodVmName1,prodVmName2"
-f "c:\data\Output.csv"
-timeout 120:600:1800

Example for replacing multiple server names in one command (option 2)

arsrename -x myARServer -u Demo -o 2 -p <password> -tokens "prod-s=test-s,prodVmName1=testVmName1,prodVmName2=testVmName2"
-f "<C:\Program Files\BMC Software\ARSystem\artools\etc\arsrename\input.csv>"
-timeout 120:600:1800

Replacing the server name in files, services, and registry entries

Use the utility to replace the current server name in the following files of the BMC installed products, services, and registry entries. For files and registry entries, you need not have the AR System Server up and running :

Component	Files in which to replace the server name
BMC Remedy AR System Server	AR_SERVER_HOME\ARSystemInstalledConfiguration.xml AR_SERVER_HOME\conf\ar.cfg AR_SERVER_HOME\conf\armonitor.cfg AR_SERVER_HOME\AREmail\EmailDaemon.properties AR_SERVER_HOME\flashboards\server.conf AR_SERVER_HOME\pluginsvr\pluginsvr_config.xml AR_SERVER_HOME\pluginsvr\fts\primary\pluginsvr_config.xml AR_SERVER_HOME\pluginsvr\fts\secondary\pluginsvr_config.xml AR_SERVER_HOME\diserver\.kettle\arservers.xml
BMC Atrium Core	ATRIUMCORE_HOME\AtriumCoreInstalledConfiguration.xml ATRIUMCORE_HOME\cmdb\plugins\ne\pluginsvr_config.xml ATRIUMCORE_HOME\cmdb\plugins\shared\pluginsvr_config.xml ATRIUMCORE_HOME\cmdb\reswift\conf\REConf.properties
BMC Remedy IT Service Management	BMC_REMEDY_ITSM_SUITE_HOME\BMCRemedyITSMSuiteInstalledConfiguration.xml
BMC Remedy Service Level Management	BMC_SLM_HOME\SLMInstalledConfiguration.xml
BMC Remedy Service Request Management	BMC_SRM_HOME\BMCServiceRequestManagementInstalledConfiguration.xml
BMC Remedy Knowledge Management	BMC_RKM_HOME\BmcRkmInstalledConfiguration.xml Note: If you have installed BMC Remedy Knowldege Management earlier using a separate installer, the setup environment variable BMC_RKM_HOME is not required if BMC_RKM_HOME/BmcRkmInstalledConfiguration.xml exists on your machine.
BMC Remedy IT Process Designer	BMC_ITSM_PROCESS_DESIGNER_HOME\ProcessDesignerInstalledConfiguration.xml BMC_ITSM_PROCESS_DESIGNER_HOME\Server\\ARID.xml
Other files on Windows	C:\Windows\System32\drivers\etc\hosts C:\Program Files\Common Files\AR System\Licenses\server_HostName If the name of the folder contains the server name, the folder name is replaced. In the preceding example, the folder name server_HostName gets replaced.
Services	BMC Remedy Action Request System Server server_HostName BMC Remedy Email Engine - server_HostName 1 BMC Remedy Flashboards Server - server_HostName
Registry entries	HKEY_LOCAL_MACHINE\SOFTWARE\Remedy\ARServer\server_HostName HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Remedy\server_HostName

Examples

Use the following command to replace a server name that contains the onbmc-s string with tenant1-onbmc-s in AR System and other files:

arsrename -o 3 -tokens "onbmc-s=tenant1-onbmc-s"

Use the following command to replace a server name that contains the onbmc-s string with tenant1-onbmc-s in the Windows services and registry entries:

arsrename -x tenant1-onbmc-s -o 4 -p <password> -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0
arsrename -o 4 -tokens "onbmc-s=tenant1-onbmc-s"

Notes

The Rename utility changes the server name in the configuration files, property files, and XML files. The utility does not change the data in the archive (.arx) files.
Before you run the command to replace server names in the files, ensure that the following environment variables are defined:
- ATRIUMCORE_HOME = D:\BMCSoftware\BMCAtriumCore
- BMC_AR_SYSTEM_HOME = D:\BMCSoftware\BMCARSystem
- BMC_REMEDY_ITSM_SUITE_HOME = D:\BMCSoftware\BMCITSM
- BMC_SERVICE_REQUEST_MANAGEMENT_HOME = D:\BMCSoftware\BMCSRM
- BMC_SLM_HOME = D:\BMCSoftware\BMCSLM
- BMC_RKM_HOME = D:\BMCSoftware\BMCRKM

If any of these environment variables is not defined, the server name in the files is not replaced.

Purge the server name in the server group metadata tables

Use the utility to clean up old server entries from the server group. Perform this step only on the primary server.

Purge the current server name in the following metadata tables:

servgrp_board
servgrp_config
servgrp_resources
servgrp_userlic
servgrp_ftslic
servgrp_applic

Example: To use the utility and rename the production server database to any other server database

Before using the arsrename utility, you must manually change the database references in the ar.cfg (ar.conf) file.

Stop the test server.
Restore the database on the production server to the test server.
Start the test server.
Run the arsrename utility with operation mode 1—Scan.
Arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.csv -fsf 1 -fsv 5000 -tokens onbmc-s
Run the arsrename utility with operation mode 2—Replace string tokens.
arsrename -o 2 -tokens "onbmc-s=tenant1-onbmc-s"
Restart the test server.
Run the arsrename utility with operation mode 7—Purge data from server group metadata tables.
arsrename -x tenant1-onbmc-s -o 7 -u Demo -p "" -t 0
Restart the test server.

For information about how to remove multiple server names from the Centralized Configuration, see the knowledge article Remove multiple server names from Centralized Configuration.