Utility command group of the AdminTask object
Use the Jython or Jacl scripting languages to manage servers with the wsadmin tool. The commands in the Utility group can be used to change the host name of a node, to query for the name of the deployment manager, and to determine if the system is a single server or network deployment.
The Utility command groupcommands include:
changeHostName
Use the changeHostName command to change the host name of a node.
Target object: None
Parameters and return values
- -hostName
- The new host name. (String, required)
- -nodeName
- The name of the node whose host name is changed. (String, required)
Optional parameters:
- -systemName
- The name of the z/OS system on which this node runs. This field is only required if a node is to be moved from one system to another, for example, form system SYSA to system SYSB. If we are not
sure of the value that we should specify for this parameter, issue the IPLINFO command on your z/OS
system, and use the name that displays in the Sysname= field as the value for
this parameter.
When we run the changeHostName command interactively, the systemName parameter appears, but is only to be used for a z/OS system. The systemName parameter represents the z/OS system name defined in the server.xml file as a value for property, was.ConfiguredSystemName. When the systemName parameter is selected, this property is changed.
- -regenDefaultCert
- A request to regenerate default certificates. The only valid value for this parameter is "true"
to regenerate default certificates. Any other value assumes to NOT regenerate default certificates. The string argument is processed as a Boolean. The Boolean returned represents the value true if the string argument is not null and is equal, ignoring case, to the string "true". The regenDefaultCert parameter operates like
AdminTask.createChainedCertificate and has the following default values:
- -keyStoreName "NodeDefaultKeyStore"
- -keyStoreScope "(node):" + nodeName
- -certificateAlias" "default_" + hostName
- -certificateCommonName" nodeName
- -certificateOrganization" "IBM"
- -certificateOrganizationalUnit" nodeName
- -certificateCountry "US"
For both AdminTask.createChainedCertificate and the regenDefaultCert parameters, if using the deployment manager node the -keyStoreName value changes to -keyStoreName "CellDefaultKeyStore", and the -keyStoreScope value to -keyStoreScope "(cell):" + cellname.
The switch is a convenience switch that makes assumptions about the default values of the certificate parameters. If the default values are not used, then AdminTask.createChainedCertificate or regenDefaultCert should be used instead.
Be aware of these functional details:
- keyStoreName and keyStoreScope are not valid with the regenDefaultCert parameter.
- When we run the changeHostName command, we cannot specify certificateCommonName (CN of new certification). To specify a new hostname as the CN, we need to use AdminTask.createChainedCertificate .
Examples
Batch mode example usage:
- Jacl:
- $AdminTask changeHostName {-hostName host_name -nodeName node
-systemName system_name}
- Jython string:
- AdminTask.changeHostName('-hostName host_name -nodeName node
-systemName system_name')
- Jython list:
- AdminTask.changeHostName(['-hostName', 'host_name', '-nodeName', 'node',
'-systemName', 'system_name'])
Interactive mode example usage:
- Jacl:
- $AdminTask changeHostName {-interactive}
- Jython string:
- AdminTask.changeHostName ('[-interactive]')
- Jython list:
- AdminTask.changeHostName (['-interactive'])
getDmgrProperties
Use the getDmgrProperties command to return the name of the deployment manager.
Target object: None
Parameters and return values
- Parameters: None
- Returns: The name of the deployment manager in a network deployment system. Returns an empty string if the system is a single server.
Examples
Batch mode example usage:
- Jacl:
- $AdminTask getDmgrProperties {}
- Jython:
- AdminTask.getDmgrProperties()
isFederated
Use the isFederated command to check if the system is a single server or network deployment.
Target object: None
Parameters and return values
- Parameters: None
- Returns: Boolean. true if the system is a network deployment system. Otherwise, it returns false.
Examples
Batch mode example usage:
- Use Jacl:
- $AdminTask isFederated {}
- Use Jython string:
- AdminTask.isFederated ()
renameCell
New feature:
Use the renameCell command to change the cell name of stand-alone application server, deployment manager, administrative agent, job manager, and federated node profiles. This command can only be run in wsadmin local mode, i.e. wsadmin -conntype none.newfeat
Do not use the renameCell command in a mixed cell environment where a cell contains nodes installed with different WAS versions.
Target object: None
Parameters and return values
- -newCellName
- The new cell name. (String, required)
- -dmgr_host
- The name of the host or IP address of the deployment manager computer. (String, required if the command runs on a federated node)
- -dmgr_port
- The Java Management Extensions (JMX) connection port. (String, required if the command runs on a federated node. Default value "8879" is used if not specified)
- -connType
- The JMX connector type to use for connecting to the deployment manager. SOAP is the default JMX connector type for the command. Other valid types are JSR160RMI or RMI. (String, required if the command runs on a federated node. Default value "SOAP" is used if not specified)
- -userName
- The user name for authentication if security is enabled. (String, required if the command runs on a federated node and security is enabled)
- -password
- The password for authentication if security is enabled. (String, required if the command runs on a federated node and security is enabled)
Optional parameters:
- -regenCerts
- Determines whether to regenerate SSL certificates for all nodes of a cell. Only certificates for the default keystores are regenerated. This parameter does not apply for cells on z/OS operating systems. Keep in mind that regenerating certificates can cause clients accessing the server to reestablish trust with the server by getting the new certificate. The default is false. Set to true to regenerate SSL certificates for nodes of a cell. (Boolean, optional)
- -updateJaccContextID
- Determines whether to update the security context ID of applications used by a Java Authorization Contract for Containers (JACC) provider. The default is false. Set to true to update the security context ID. (Boolean, optional)
Batch mode example usage:
- Jython string:
- AdminTask.renameCell('-newCellName new_cell')
- Jython list:
- AdminTask.renameCell(['-newCellName', 'new_cell'])
Interactive mode example usage:
- Jython string:
- AdminTask.renameCell ('[-interactive]')
- Jython list:
- AdminTask.renameCell (['-interactive'])
Example scenarios using renameCell
Backing up the node configuration with the backupConfig tool from profile_root/bin directory is recommended before changing the cell name for that node using the renameCell command. If we are not satisfied with the results of the renameCell command and if the renameCell command execution failed unexpectedly, use the restoreConfig tool to restore the backup configuration.
Back up profile_root/bin/setupCmdLine script file before running the renameCell command. The command updates the cell name in this file with the new cell name but is unable to change it back if a user decides to discard the configuration change resulting of this command execution. If we decide to do so, we will need to restore the file after discarding the configuration change; otherwise, we won't be able to start a server in this profile.
- Renaming a cell for a stand-alone application server:
-
- Stop a stand-alone server.
- Rename the cell using wsadmin in local
mode:
- AdminTask.renameCell('-newCellName new_cell')
- Renaming a cell for a deployment manager and its federated nodes:
-
To rename a cell for a network deployment topology, the command needs to run on a deployment manager node/profile and all federated nodes/profiles.
If the cell is a part of a multi-cell topology, unlink the cell from the other cells before these steps and link again after the steps.
- Stop all servers in the cell, including the deployment manager server, node agent servers, and all application servers.
- Rename the cell of a deployment manager node/profile: run the command below with wsadmin in
local node, which makes the cell name changes along with the SSL certificate changes in the dmgr
master repository.
- AdminTask.renameCell('[-newCellName new_cell]')
- Run the rename cell command for all federated nodes/profiles in the cell.
- Start the deployment manager server.
- In the profile of each nodeagent and for every node that is not the deployment manager node,
start wsadmin in local mode and run the command shown
below:
- AdminTask.renameCell('[-newCellName new_cell -dmgr_host dmgr_hostname -dmgrPort dmgr_connector_port -connType SOAP -username my_user -password my_password]')
- Renaming a cell for an administration agent server:
-
- Stop an administration agent server.
- Rename the cell using wsadmin in local
mode:
- AdminTask.renameCell('-newCellName new_cell')
To rename a cell for a stand-alone application server registered to an administration agent server, we need unregister that stand-alone node with that administration server first. You will need to register the node with the administration server again after running the rename cell command to the administration server continues to manage that stand-alone node.
- Renaming a cell for a job manager server:
-
- Stop a job manager server.
- Rename the cell using wsadmin in local
mode:
- AdminTask.renameCell('-newCellName new_cell')
This is for stand-alone job manager profiles only. Do not use this for a deployment manager that is functioning as a job manager.
- Renaming a cell in the multi-cell topology:
-
To rename the cell in the multi-cell topology such as the star topology, the cell must be detached from the other cells before the rename. After the cell rename, the cell should then be attached back to the other cells.