jpcconf port define
- Organization of this page
Format
Format 1
jpcconf port define -key service-key [-lhost logical-host-name] [-inst instance-name] [-only] [-input definition-file-name] [-noquery]
Format 2
jpcconf port define -key service-key [-lhost logical-host-name] [-inst instance-name] -template definition-file-name [-noquery]
Function
The jpcconf port define command sets the port numbers that are used with Performance Management.
The port numbers assigned by Performance Management are classified into fixed port numbers and preferential port numbers, and the settings that can be specified in the command differ according to the service type. For details about the port numbers assigned by Performance Management, see Appendix C. Port Numbers.
Also, you can execute the jpcconf port define command to display the port numbers that are set currently.If you press the return key without specifying a port number, the system uses the displayed port number.
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
-key service-key
Specifies the service key of the service whose port numbers are to be the subject of this execution of the command. You can also specify the following in service-key:
-
all: Specifies the port numbers of all programs of the Performance Management products.
-
Manager or mgr: Specifies the port numbers that are used with the PFM - Manager services (excluding the Status Server and Action Handler services), and between PFM - Web Console and the View Server service.
-
Product name or agtX: Specifies the port numbers that are used with the specified PFM - Agent or PFM - RM service, and the Name Server service#.
-
AH or act: Specifies the port numbers that are used with the Action Handler service and the Name Server service#.
-
StatSvr or stat: Specifies the port numbers that are used with the Status Server service and the Name Server service.
- #
-
If the -only option is specified, the port number of the Name Server service is not handled.
Product name or agtX indicates the service key for the particular PFM - Agent or PFM - RM. For details about the service key of the PFM - Agent or PFM - RM service, see the naming rules described in the appendix of the JP1/Performance Management Planning and Configuration Guide.
-lhost logical-host-name
When the command targets a logical environment, specify the host name of a logical host.
For logical-host-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters with no space characters and no periods (.).
For logical-host-name, you cannot specify localhost, an IP address, or a host name beginning with a hyphen (-).
-inst instance-name
Specifies the instance name of the instance whose port numbers are to be the subject of this execution of the command. For instance-name, specify a string of 1 to 32 bytes, consisting of alphanumeric characters. This option is applicable only to a PFM - Agent or PFM - RM that has an instance environment.
-only
If this option is specified, changing of the port numbers for only specific products or instances, or changing of the port number for only the Action Handler service, is enabled. Therefore, there is no need to restart the services whose port numbers are not changed. This option can be specified only if product-name, agtX, AH, or act is specified for the -key option#. If the -only option is specified when a service key other than these is specified, the KAVE05093-E message is output, and processing stops.
- #
-
The -only option cannot be specified if the health check agent (HC or agt0) is specified.
-noquery
If this option is specified, the command does not output any query messages that interrupt command execution, making it unnecessary for the user to respond.
To execute this command in non-interactive mode, specify this option and the -input option together.
The command behavior changes in various situations, as described below:
-
If there are Performance Management services that are running:
The command execution is interrupted with a KAVE05143-E message. Stop the services, and then re-execute the command.
-
If there is already a file with the same name as the file specified for the -template option:
A KAVE05399-I message is output and the file is updated.
-input definition-file-name
Specifies the path name of the definition file from which port numbers will be loaded. For definition-file-name, specify a string of 1 to 250 bytes. The port numbers set in the specified file will be set.
If the command is executed with auto specified in the service-name label in the definition file specified by the -input option, the following processing occurs:
- Services with a fixed port:
-
A fixed port number is set.
- Services with a preferential port:
-
A preferential port number is set. However, if the preferential port number is already in use, another port number that is not currently used is set.
For details about fixed port numbers and preferential port numbers, see C.1 Performance Management port numbers.
If the string that you want to specify contains spaces, enclose the entire string in double quotation marks (").
To execute this command in non-interactive mode, specify this option and the -noquery option together.
-template definition-file-name
Specifies the path name of the definition file to which port numbers that are set will be output. For definition-file-name, specify a string of 1 to 245 bytes. The labels of all services indicated by the specified service key will be output to the definition file. Note that in [component-name] sections, the port numbers that are set or 0 will be output as the label values.
If the string that you want to specify contains spaces, enclose the entire string in double quotation marks (").
Format of the definition file (for the jpcconf port define command)
The definition file is a text file consisting of sections and labels described below. The label names and values are specified in name=value format. Invalid section and label names are ignored.
- [Common Definitions] section
-
Specifies the basic information in the definition file. This section and all labels in this section are required.
- Definition File Version label
-
Specifies the version of the definition file. Specify the constant 0001.
- [component-name] section
-
Use this section to specify the port numbers that you want to set.
For component-name, specify the name of a component that contains the services for which you want to set port numbers. You can specify multiple [component-name] sections (with different component-name values).
If you specify multiple [component-name] sections with the same component-name value, only the section specified first takes effect.
The values that can be specified for component-name are as follows:
-
Common
Specify Common when you want to set the port numbers that will be used by the Name Server, Status Server, and Action Handler services.
-
Manager
Specify Manager when you want to set the port numbers that will be used by PFM - Manager services.
-
PFM - Agent or PFM - RM product name
Specify the name of a PFM - Agent or PFM - RM product when you want to set the port number that will be used by a PFM - Agent or PFM - RM product. For product names that can be specified, see the chapter on the Performance Management functionality in the JP1/Performance Management Planning and Configuration Guide.
- Subsection with an instance name
-
To specify port numbers that will be used in a PFM - Agent or PFM - RM instance environment, specify them in this subsection. You can specify this subsection only if the specified component is a PFM - Agent or PFM - RM that has multiple instances.
If you specify multiple subsections with the same name in a [component-name] section, the subsection specified first takes effect.
- Label with a service name
-
Specify a label with the name of a service for which you want to set a port number.
If you specify multiple labels with the same name in a section or subsection, the label specified first takes effect.
-
If you want a port number to be dynamically assigned each time the service is restarted, specify 0 as the value. However, those ports assigned a fixed number by Performance Management will be assigned a port number even if you specify 0.
-
To use the default port numbers that are assigned by Performance Management, specify auto as the values. However, you cannot specify auto for ports that are assigned a fixed number by Performance Management.
-
When you specify port numbers, select port numbers that are in the range from 1024 through 65535 and are not currently used within the system.
-
If you do not change port numbers, specify nothing for these values.
If you specify a value that is outside the range from 1024 through 65535 or specify a value that includes non-numeric characters (except auto), the processing for the relevant services will be skipped.
-
-
The following table lists and describes component names, service names, and values that can be specified for [component-name] sections and service-name labels.
Component name |
Service name |
Value |
---|---|---|
Common |
Name Server |
Name Server port number |
Status Server |
Status Server port number |
|
Action Handler |
Action Handler port number |
|
Manager |
Master Manager |
Master Manager port number |
Master Store |
Master Store port number |
|
Correlator |
Correlator port number |
|
Trap Generator |
Trap Generator port number |
|
View Server |
View Server port number |
|
View |
View Server port number (between PFM - Web Console and View Server services) |
|
PFM - Agent or PFM - RM product name |
Collector |
Port number to be used by PFM - Agent Collector or Remote Monitor Collector |
Store |
Port number to be used by Agent Store or Remote Monitor Store |
The following shows an example of specifying settings in the definition file.
[Common Definitions] Definition File Version=0001 [Common] Name Server=22285 Status Server=22350 [Manager] Master Manager=auto Master Store=auto Correlator=auto ... [Windows] Collector=0 Store=0 ... [Oracle] [[oracle1]] Collector=0 Store=0
Notes
-
Earlier than 11-01
Before you execute this command to set port numbers, make sure that no Performance Management program services are running on the local host. When you finish setting the port numbers, start the services manually.
-
11-01 or later
Before you execute this command to set port numbers, you might need to stop Performance Management program services. The services to be stopped differ depending on whether you specify the -only option, as shown below.
- If you set the port numbers without the -only option specified
-
Stop all services running on the local host.
- If you set the port numbers with the -only option specified
-
Stop the services specified by the -key and -inst options.
When you finish setting the port numbers, manually restart the services that you stopped.
-
If the user attempts to execute the command without stopping the services that must be stopped, a message indicating that the services will forcibly be stopped appears. With the message, the user can select whether to continue the command processing. If the services cannot be stopped completely when the user chooses to continue the command processing, the command fails. In this case, the user must stop the service completely and then re-execute the command. After the settings are complete, manually restart the service. If the -noquery option is specified, the service is not stopped automatically while the command is being processed.
-
If you terminate this command during execution by pressing the Ctrl + C keys, the port numbers will not be set correctly. In this case, re-execute the command to set the port numbers again.
-
Make sure that you set the same port number for the Name Server service on all hosts in the Performance Management system.
Similarly, for the Status Server service, make sure that you set the same port number on all hosts in the Performance Management system.
Also, for other PFM services, use the same correspondence between port numbers and service names throughout the Performance Management system to avoid confusion.
-
Use the fixed port number or preferential port number assigned by Performance Management unless the same port number exists within the host.
-
This command automatically edits the services file of the operating system.
-
This command edits only the local services file at the host where the command is executed. For UNIX, if you are managing the services file using NIS or NIS+, you must manually apply to the NIS server a port number added to the local services file.
-
When you enter a port number, the command displays the value that is contained in the services file at the host where the command is executed. In an NIS or NIS+ environment, if the port number information managed by the NIS server does not match the information in the services file of the NIS client, the displayed information may not be the actual value used by the service.
-
If command execution is interrupted by pressing the Ctrl + C keys or by a signal, a predefined return value is not returned. Therefore, you should ignore the return value when the command was interrupted by the Ctrl + C keys or by a signal.
-
When you execute the command with the -input option, the command execution is interrupted if the definition file does not contain all necessary labels or an invalid value is specified for Definition File Version. If you add the -noquery option to automatically execute the command in a batch or script file, confirm that the settings in the definition file are correct beforehand. If the command is automatically executed, you can check whether the command terminates normally with a message or return value that is output.
-
If the -input option is specified, the command processes only the port numbers of the services specified by the -key option and the -input option. Similarly, if the -only option is specified together with the -input option, the command does not process the port number of the Name Server service in the definition file. Even if the definition file contains sections, subsections, or labels that are not processed by the command, no errors occur.
-
In an environment in which an overwrite install was done from a version earlier than 11-00 to version 11-0 or later, if the -template option is specified, the OpenView service (the service for NNM linkage) will be included in the definition file that is output. In that case, delete the OpenView service line from the definition file.
If you do not delete the line, and then read the definition file with the -input option, the OpenView service port number will be set in the services file. In that case, edit the services file and delete the OpenView service line. However, even if the OpenView service is set, it will not affect the behavior of Performance Management.
To prevent the OpenView service line from being output to the definition file, see the description in the notes on migration (version 11-00 or later) in the appendix of the JP1/Performance Management Planning and Configuration Guide.
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 specified service has not been stopped. |
5 |
The specified service key was not found. |
6 |
The definition file contains errors. |
7 |
The specified service key was not found at the logical host. |
10 |
The command is executing. |
11 |
The user canceled the processing (by entering N at the prompt). |
13 |
Setting was skipped for one or more services because values could not be set as specified in the definition file. |
100 |
The Performance Management environment is invalid. |
101 |
Acquisition of a port number failed. |
102 |
The specified instance was not found. |
106 |
Port number has not been registered in the services file. |
200 |
A memory shortage occurred. |
210 |
A disk space shortage occurred. |
211 |
File cannot be accessed. |
222 |
A communication error occurred (IP address could not be acquired). |
224 |
There is no available port number to set in the services file. |
230 |
Execution of an internal command failed. |
255 |
An unexpected error occurred. |
Usage example
Example 1
This example specifies that the port numbers for all services of Performance Management programs will be set to fixed values.
jpcconf port define -key all
Example 2
This example specifies that the port number for PFM - Agent for Oracle will be set to a fixed value without setting a port number for the Name Server service.
# jpcconf port define -key Oracle -only
Example of executing the command in non-interactive mode
If the -noquery, -input, and -template options are specified, setup can be performed without any queries output from Performance Management. The following shows usage examples.
Example 3
This example generates the files AgentPort01.txt and AgentPort02.txt. The AgentPort01.txt file is the template file for the file that defines the port numbers that must be set in PFM - Agent for Platform (Windows). The AgentPort02.txt file is the template file for the file that defines the port numbers that must be set in PFM - Agent for Oracle.
# jpcconf port define -key Windows -template AgentPort01.txt # jpcconf port define -key Oracle -template AgentPort02.txt
Example 4
This example sets port numbers that are used in PFM - Agent for Platform (Windows) and PFM - Agent for Oracle.
This example assumes that the user has prepared the definition files AgentPort01.txt and AgentPort02.txt by editing the template files generated in Example 1.
# jpcconf port define -key Windows -input AgentPort01.txt -noquery # jpcconf port define -key Oracle -input AgentPort02.txt -noquery