jpcconf host hostname
- Organization of this page
Format
jpcconf host hostname [-lhost logical-host-name] -newhost new-host-name -d backup-directory-name [-dbconvert {convert|delete}]
Function
The jpcconf host hostname command changes the monitoring host name for a Performance Management system. When changing the real host name, use this command to change the monitoring host name, and then change the real host name. The monitoring host name for the physical host and logical host can be changed.
This command does not change the method for acquiring the monitoring host name. Note that when this command is executed, all definition information and performance information is carried over.
Hosts that can execute the command
-
PFM - Manager
-
PFM - Agent
-
PFM - RM
Execution permission
- In Windows:
-
User with Administrators permissions (executed from the administrator console when Windows UAC functionality is enabled)
- In UNIX:
-
User with root user permissions
Installation directory
- In Windows:
-
installation-folder\tools\
- In UNIX:
-
/opt/jp1pc/tools/
Arguments
-lhost logical-host-name
Specifies the logical host name to be changed. For logical-host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters. If you omit this specification, the physical host is assumed. Wildcard characters cannot be used.
-newhost new-host-name
Specifies a new host name. The following table contains cautions about host name types and input values, for each condition.
Condition |
Specified host name |
Cautions regarding the input value |
|
---|---|---|---|
Specified -lhost option |
Method for acquiring the monitoring host name #1 |
||
Not specified |
hostname |
Physical host name (value displayed by the hostname command) |
|
uname -n |
Physical host name (value displayed by the uname -n command) |
||
alias |
Alias name (optional host name)#2 |
|
|
Specified |
-- |
Logical host name |
|
- Legend:
-
--: Not applicable.
- #1
-
The method for acquiring the monitoring host name is set by using the jpcconf host hostmode command.
The jpcconf host hostmode -display command can be used to check the current setting of the method for acquiring the monitoring host name.
- #2
-
For details about alias names, see the chapter describing installation and setup in the JP1/Performance Management Planning and Configuration Guide.
-d backup-directory-name
Specifies the backup destination directory. Specify an existing directory. Note that you cannot specify a subdirectory of the directory that contains the Store database for Agent Store or RM Store. For backup-directory-name, specify a string of 1 to 130 bytes, consisting of alphanumeric characters, symbols, and space characters. However, the following symbols cannot be specified:
; , * ? ' " < > |
If the file name contains spaces, enclose the entire name in double quotation marks (").
In directory-name, specify an empty directory that contains no files or directories.
-dbconvert {convert|delete}
Specifies how performance data is carried over. If nothing is specified, convert is set.
When convert is specified, the host name information for the Store database is converted to a new host name, and data is carried over.
If delete is specified, the Store database is deleted, and data is not carried over. However, information about event data managed by PFM - Manager is not deleted, and carried over.
Notes
-
When the jpcconf host hostname command is executed, the version of PFM - Manager or PFM - Base on the execution host must be 09-00 or later.
-
When the jpcconf host hostname command is executed, all services on the specified host must be stopped.
-
The directory specified for the -d option of the jpcconf host hostname command must have about the same amount of free disk space as the capacity of the Store database for PFM - Agent and PFM - RM on the specified host. The directory specified for the -d option of the jpcconf host hostname command must have free space that is as large as the total size of the following databases: The Store databases for PFM - Agent and PFM - RM on the specified host and the database in the import directory. If the directories that contain these databases have been changed from the default directories, use the sizes of the databases in the directories actually used for calculation.
-
Do not execute any other commands while the jpcconf host hostname command is executing. If another command is executed, the jpcconf host hostname command or other command might fail to execute.
-
If the jpcconf host hostname command fails with a KAVE05181-E or KAVE05182-E message, use the following procedure to correct the error:
-
Check the message that was output immediately before the above message, and remove the cause of the error.
-
Check whether a KAVE05172-I message was output when the command failed.
If the message was output, use the backup data in the backup directory to restore the backup source data.
The table below shows the types of data that are backed up. Restore these types of data from the data in the backup destination directories. In Windows, replace a slash (/) with a backslash (\) in the table.
Types of data backed up if the physical host name cannot be changed:
Category
Backup source
Backup destination
Store database
The Store directory of the Agent product
- For a multi-instance agent:
-
backup-directory/agtX#1/instance/store
- For a single-instance agent:
-
backup-directory/agtX#1/store
Definition file
installation-directory/jpcns.ini
backup-directory/jpcns.ini
installation-directory/jpcns_backup.ini
backup-directory/jpcns_backup.ini
installation-directory/jpccomm.ini
backup-directory/jpccomm.ini
installation-directory/agtX#1/agent/agtlist.ini#2
backup-directory/agtX#1/agent/agtlist.ini#2
installation-directory/agtX#1/store/stolist.ini#2
backup-directory/agtX#1/store/stolist.ini#2
installation-directory/bin/statsvr/restart.ini
backup-directory/bin/statsvr/restart.ini
installation-directory/sys/jp1sysEvent.ini
backup-directory/sys/jp1sysEvent.ini
#1: The agtX item indicates the Agent product's service key. For the service key of an Agent product, see any manual of that Agent product.
#2: This data is backed up only for a multi-instance agent.
Types of data backed up if the logical host name cannot be changed:
Category
Backup source
Backup destination
Store database
The Store directory of the Agent product
- For a multi-instance agent:
-
backup-directory/agtX#1/instance/store
- For a single-instance agent:
-
backup-directory/agtX#1/store
Definition file
environment-directory/jp1pc/jpcns.ini
backup-directory/jpcns.ini
environment-directory/jp1pc/jpcns_backup.ini
backup-directory/jpcns_backup.ini
environment-directory/jp1pc/jpccomm.ini
backup-directory/jpccomm.ini
environment-directory/jp1pc/agtX#1/agent/agtlist.ini#2
backup-directory/agtX#1/agent/agtlist.ini#2
environment-directory/jp1pc/agtX#1/store/stolist.ini#2
backup-directory/agtX#1/store/stolist.ini#2
environment-directory/jp1pc/bin/statsvr/restart.ini
backup-directory/bin/statsvr/restart.ini
environment-directory/jp1pc/sys/jp1sysEvent.ini
backup-directory/sys/jp1sysEvent.ini
#1: The agtX item indicates the Agent product's service key. For the service key of an Agent product, see any manual of that Agent product.
#2: This data is backed up only for a multi-instance agent.
-
Re-execute the command.
-
Return values
0 |
The command terminated normally. |
1 |
An argument specification is invalid. |
2 |
The user does not have execution permission for the command. |
4 |
The Performance Management service is running at the executing host. |
10 |
The command is being executed. |
11 |
The user or the system canceled processing. |
100 |
The Performance Management environment is invalid. |
102 |
The specified logical host name has not been set up. |
200 |
A memory shortage occurred. |
210 |
A disk space shortage occurred. |
211 |
A file or directory cannot be accessed. |
220 |
A host name specified in the service configuration information file is invalid. |
222 |
A communication error occurred. |
223 |
A communication processing timeout error occurred. |
255 |
An unexpected error occurred. |
Usage example 1
This example changes the physical host name to hostB.
jpcconf host hostname -newhost hostB -d d:\backup
Usage example 2
This example changes the logical host name lhostA to lhostB.
jpcconf host hostname -lhost lhostA -newhost lhostB -d d:\backup -dbconvert delete
Output example
This example shows the standard output when backup deletion is successful.
Example of standard output
KAVE05166-I Host name change has started. KAVE05172-I Host information backup was successful. KAVE05174-I Deletion of host information backup was successful. KAVE05167-I Host name change has terminated normally.
This example shows the standard output when backup deletion fails.
Example of standard output
KAVE05166-I Host name change has started. KAVE05172-I Host information backup was successful. KAVE05175-W Deletion of host information backup failed. KAVE05167-I Host name change has terminated normally.