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
Perform the server name replacement tasks in the following order:
- 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:
arsrename [-u] [-p] [-a] [-x] [-t] [-timeout] [-o] [-tokens] [-f] [-fsf] [-fsv] [-ie] [-ief]
The following table describes the
arsrename command options, which can be used in any order in the command.
|Name that identifies the user account for the AR System server|
Password for the user account
If the user account has no password, use
Name of the external authentication string or Windows NT domain
This option is related to the Login window's Authentication field. See Authentication String Alias introduction.
|Name of the server to connect to|
TCP port number to connect to
If the port number is unknown, use
Time, in seconds, during which the connection must occur, specified in the following format:
Note: You must specify all three values even if you want to set a single timeout value.
2—Replace string tokens
3—Replace string tokens in files
4—Replace string tokens in Windows registry entries
|List of string tokens in comma-separated value format. This is the old server name that you need to replace. |
For example, onbmc-s,onbmc-s.bmc.com
File path of the CSV file that contains the list of forms and fields for token replacement (required if your operation code is 3)
While performing a scan operation, use the
Whether to use fast scan
Use this option with operation code 1.
Number of entries to scan
By default, 10,000 entries are scanned.
Whether to use the inclusion-exclusion list of forms in the scan
Path of the inclusion-exclusion list
If the path is not specified or if the value of the
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
|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:|
Flag that indicates whether the scanned server name is to be replaced or not; this value is referred to during the 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.
|Special (Y/N)?||Flag that indicates special handling required during the replace operation|
You can use the output generated by the scan operation directly as input for the replace operation, which replaces the server name in database.
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> -f c:\data\output.csv -ie 2 -ief C:\<ARSystemInstallationFolder>arsystem\artools\src\inclusion-exclusion-list.txt -tokens onbmc-s
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 #----the following qualification is for fetching outgoing messages that are sent i,AR System Email Messages,'18092'=1 and '18099'=1 #----The following qualification scans only those SRDs which are not closed. i,SRM:Request,'7'!=9000 #--Exclusion list e,AR System Server Group Operation Ranking e,AR System Service Failover Ranking e,AR System Service Failover Whiteboard e,ServerStatistics
The following table describes the formats used in this file:
|#||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\arsrename folder.
- 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.
Do not replace the server name in the following forms:
- AR System Server Group Operation Ranking
- AR System Service Failover Ranking
- AR System Service Failover Whiteboard
In the input.csv file, delete the rows that contain these form names.
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 2 -tokens "onbmc-s=tenant1-onbmc-s" -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:
|Component||Files in which to replace the server name|
|BMC Remedy AR System Server|
|BMC Atrium Core|
|BMC Remedy IT Service Management|
|BMC Remedy Service Level Management|
|BMC Remedy Service Request Management|
|BMC Remedy Knowledge Management|
|BMC Remedy IT Process Designer|
|Other files on Windows|
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 -x onbmc-s -o 3 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0
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 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0
- 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.