This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

Renaming the AR System server

Important

This section describes the configuration procedures required to change the server name of a BMC Remedy Action Request System (BMC Remedy AR System) server when you upgrade from version 9.0 or later.

For more information on configuration procedures to change the server name of BMC Remedy AR System server for versions earlier than 9.0, see Changing a server name when using a duplicated or migrated environment.

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. For more information, see the knowledge article 000143818.
  • 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:

  1. Replace the server name in the database. In a server group environment, perform this operation only on the primary AR System server. 
  2. Replace the server name in files. In a server group, perform this operation on all servers in the server group.
  3. (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.
  4. 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]


Version 9.1.04 and later
	[-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.

OptionDescription
-uName that identifies the user account for the AR System server
-p

Password for the user account

If the user account has no password, use -p "". You can ignore this parameter if the password is empty or blank.

-a

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.

-xName of the server to connect to
-t

TCP port number to connect to

If the port number is unknown, use -t 0.

-timeout

Time, in seconds, during which the connection must occur, specified in the following format: 

-timeout Normal:Long:XLong 

The default values for Normal:Long:XLong are 120:400:1800.

Note: You must specify all three values even if you want to set a single timeout value.
For example, if you want to set the Long timeout value to 600 seconds, use the following command:
-timeout 120:600:1800.

-o

Operation code:

1—Scan

2Replace string tokens

3Replace string tokens in files

4Replace string tokens in Windows registry entries

-tokensList of string tokens in comma-separated value format
-f

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 -f parameter to generate the output CSV file. While performing a replacement operation, use the -f parameter to pass the input CSV file.

-fsf

Whether to use fast scan

Use this option with operation code 1.
Valid values:
0—Off (default)
1—On

-fsv

Number of entries to scan

By default, 10,000 entries are scanned.
Valid value: Any positive integer

-ie

Whether to use the inclusion-exclusion list of forms in the scan

Valid values:
0Do not use inclusion-exclusion list
1Forms specified in the list are scanned along with other forms
2—Only the forms specified in the list are scanned

-ief

Path of the inclusion-exclusion list

If the path is not specified or if the value of the -ie option is 1 or 2, the default text file available in the ARSystemInstallationFolder\ARSystem\artools\etc folder is used.

(Version 9.1.04 and later)

-del

Retains an existing entry and deletes a new entry that is auto-populated when a new server is added to the server group. The new entry is deleted only when you use the -del command with operation code: 2—Replace string tokens. This command is applicable only to the following forms:

  • AR System Server Group Operation Ranking
  • AR System Service Failover Ranking
  • AR System Service Failover Whiteboard
  • UDM:Config

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 NameDescription
Form nameName of the regular form in which the AR System server name is found
Field IDID 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
#----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:

FormatDescription
#Specifies a comment line
iSpecifies the inclusion list
eSpecifies 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

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 entries in these forms are auto-populated when you add a new server to the server group. If you do not want entries in these forms, you need to delete them manually.

Version 9.1.04 and later

Use the -del command with option 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 

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:

ComponentFiles 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 -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 onbmc-s -o 4 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0

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.


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

Comments

  1. Peter Lundqvist

    I just want to mention that when we ran arsrename to change file contents on RHEL it ended the lines with \r\n instead of \r (using DOS convention instead of UNIX convention).

    This meant that the bin/arsystem script stoped working. This is easily remedied by using sed -i 's/\r//' bin/arsystem (try it with sed -e first to verifiy that there are no cut/paste errors).

    It is probably a wise idea to do this with the other files the tool touches as well.

    Mar 07, 2017 04:20
    1. Anagha Deshpande

      Hello Peter,

      Thank you for the feedback. This is an issue in the tool. We have created defect SW00531307 to track this issue.

      Regards,

      Anagha

       

      Jun 22, 2017 03:40
  2. Piyush Sharma

    May need to revisit this documentation with below part -

    ===

    BMC Remedy Knowledge Management

    BMC_RKM_HOME\BmcRkmInstalledConfiguration.xml

    ===

    RKM is no more a separate installation and doesn't have a dedicated installation directory. It gets installed with ITSM installer only.

    Mar 16, 2017 05:52
  3. Peter Lundqvist

    I should caution you that the tool does not seem to replace all the matching entries.
    There is a defect, SW00528982, to track this issue.

    You can, with some uncertainty, work around this by running the tool multiple times. Don't be afraid of the time it takes - it is only the initial scan that takes a long time. Also, the replace scans go faster as the number of matches decreases.
    I do, however, not recomend this.

    Jul 08, 2017 07:20
    1. Anagha Deshpande

      Hello Peter,

      The defect SW00528982 was closed as not reproducible in BMC Remedy AR system version 9.1.03. This was not reproducible even with the data provided by the customer.

      If you have specific use case that consistently reproduces the issue, we request you to please share that data with the BMC support team so that it can be addressed in a future release. Click here to contact support.

      Regards,

      Anagha

      Jul 11, 2017 05:43
  4. Uwe Ryczek

    Hi,

    how do we have to use this tool to rename the Servername[s] from a Server-Group Dump [PROD] to a non Server-Group [TEST] environment and does this tool handle the entries in "AR System Configuration Component" and "AR System Configuration Component Setting" or do we have to clean them manually?

    Dec 06, 2017 05:28
    1. Anagha Deshpande

      Hello Uwe,

      I will check this with the SME and will write back to you.

      Regards,

      Anagha

      Dec 06, 2017 09:14
      1. Uwe Ryczek

        Are there any news from SME?

        Feb 01, 2018 08:26
        1. Anagha Deshpande

          Hello Uwe,

          Apologies for the delayed response.

          You can perform the following steps to rename the server:

          1. Stop the test server.
          2. Restore the database on the production server to the test server. 
          3. Start the test server.
          4. 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

          5. Run the arsrename utility with operation mode 2—Replace string tokens. 

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


          6. Restart the test server.
          7. 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


          8. Restart the test server.

          Version 91 has no option to delete the server entries. You have to delete the entries manually.

          Regards,

          Anagha

          Jun 29, 2018 01:29
          1. Piotr Sadowski

            Hi Anagha, operation code 7 is not described in the documentation, could you please update documentation and describe what this code means, if it is still valid code? Thanks

            Aug 19, 2018 05:28
            1. Anagha Deshpande

              Hello Piotr,

              Apologies for the late response.

              Operation code 7 to purge data from server group metadata tables is available from Remedy AR System version 18.05.

              The documentation is available here.

              Apr 25, 2019 02:56
      1. Uwe Ryczek

        i have to ask again! Are there any news?

        Mar 01, 2018 02:43
    1. Jd Hood

      We see the same behavior. We have verified that the scan does indeed check the forms, "AR System Configuration Component" and "AR System Configuration Component Setting" as they are written to the output file - and we subsequently include those forms in the input file, but they are not updated.

      Can BMC advise the corrective action we should take?

      Apr 18, 2019 11:10
      1. Anagha Deshpande

        Hello Jd,

        We are working on your query. We will respond soon.

        Regards,

        Anagha

        Apr 18, 2019 10:29
  5. Theo Fondse

    Hi Uwe,

    In such a case, you should follow the steps to remove the test server from the server group config (on the test server) and remove all the other production servers from the test server config as described here: https://docs.bmc.com/docs/ars91/en/removing-a-server-from-a-server-group-or-remove-an-unused-server-name-609073427.html

    Jan 09, 2018 12:30
    1. Uwe Ryczek

      Hi Theo,

      thanks, but this will not remove the entries from the "AR System Configuration Component" and "AR System Configuration Component Setting". They are still there!

      Regards, Uwe

      Feb 05, 2018 06:12
  6. Stefan Hall

    the content is displayed twice

    Feb 02, 2018 05:25
    1. Kamalakannan Srinivasan

      Hi Stefan,

      Thank you for your comment. The duplicate content has now been removed.

      Regards,
      Kamal

      Feb 06, 2018 11:52
  7. Rick Westbrock

    There is a broken image in the "Scanning the database for the server name" section just before the "Output of the scan operation" text.

    Feb 22, 2018 12:57
    1. Anagha Deshpande

      Hello Rick,

      Thanks for bringing this to our notice. I will fix the image link.

      Regards,

      Anagha

      Feb 22, 2018 08:51
      1. Piotr Sadowski

        Hi Anagha, this image is still broken, could you please fix the image? Thanks

        Aug 19, 2018 05:28
  8. Piotr Sadowski

    Hi, could you please more describe or give an example to what is doing "Special (Y/N)" flag in output/input.csv file. The current description ("Flag that indicates special handling required during the replace operation") is very laconic and does not explain exactly what can be used. What are the special case that this flag handle? Thanks

    Aug 19, 2018 05:31
    1. Onkar Telkikar

      Hello Piotr,

      The flag Special (Y/N) is currently not used. When a user uses the option 1 - scan, the rename utility always puts this special value as ‘N’ for all forms. Currently, even if the user sets this to ‘Y’, there is no handling inside the utility for any special case.

      Thanks,

      Onkar

      Oct 03, 2018 03:48