Register host computers with a Liberty collective

We can register a host computer with a Liberty collective controller, update host information, or unregister a host. Registration enables the collective controller to access applications, command files, and other resources on the host. Registered hosts are members of the collective.

Construct a Liberty collective. See Configure a Liberty collective.

Note: The collectiveController-1.0 feature and its capabilities are available only in WebSphere Application Server Liberty Network Deployment and WebSphere Application Server Liberty for z/OS .

The feature is not available in WebSphere Application Server Liberty, WebSphere Application Server Liberty - Express , or WebSphere Application Server Liberty Core.

If we have a WebSphere Application Server Liberty Network Deployment installation, we can use its collectiveController-1.0 feature to work with collective members from WebSphere Application Server Liberty, WebSphere Application Server Liberty - Express, or WebSphere Application Server Liberty Core installations.

A host computer is not required to have any WebSphere Application Server products installed. There are no software requirements for a host beyond its operating system. The host can be the same computer on which the product is installed or a different computer.

To register a host with a collective controller, update host information, and unregister a host, use the registerHost, updateHost, and unregisterHost commands. Specify the host computer name in one of the following formats:

• Fully qualified DNS host name string, such as xmachine.ibm.com
• Default short DNS host name string, such as xmachine
• Numeric IP address, such as 127.1.255.3

When a Liberty server is joined to a collective, the associated host is automatically registered with the collective controller if it has not already been registered.

A host can be registered with the collective under different names. It is important that the host name specified for registerHost, updateHost, and unregisterHost be consistent with the host name used for the registered collective members. The defaultHostName variable in the registered server member's server.xml file controls the host name to which the server considers itself to belong.

Register a host with a collective controller

To register the current host, run the registerHost command on the collective utility script with no explicit host target. Specify the collective controller's host name, port, and administrative user name and password. For example:

wlp/bin/collective registerHost 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword

This example command generates a unique SSH key pair for authenticating to the SSH server of a specified host computer. If we are registering a remote host for which an SSH key pair is already generated, specify this remote host name in the local SSH private key file:

wlp/bin/collective registerHost remotehost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --sshPrivateKey=/path/to/private/key/file

If the host does not support SSH or using SSH keys is not desired, we can include an operating system login user and password:

wlp/bin/collective registerHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --rpcUser=osUser 
    --rpcUserPassword=osUserPassword

To transfer files to and from a host, we must specify host read and write paths. Unless the registerHost command specifies the paths, we cannot deploy a Liberty archive to the host. The hostReadPath specifies the directories that the collective controller can read. The hostWritePath specifies the directories to which the collective controller can write. For example, to upload an archive to /opt/wlp, we must specify --hostWritePath=/opt. Specify a parameter multiple times for multiple paths.

wlp/bin/collective registerHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --rpcUser=osUser 
    --rpcUserPassword=osUserPassword 
    --hostReadPath=/opt 
    --hostWritePath=/dir1 
    --hostWritePath=/dir2

To use the Deploy tool of the WebSphere Liberty Administrative Center ("Admin Center"), set hostWritePath to the path to which to deploy a server package. To transfer files to multiple directories, include multiple instances of the hostWritePath parameter in the command. For example:

wlp/bin/collective registerHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --rpcUser=osUser 
    --rpcUserPassword=osUserPassword 
    --hostWritePath=c:\was\liberty\brokerageAppTest 
    --hostWritePath=c:\wlp_backup

Update registered host authentication information

Run the updateHost command on the collective utility script to change the authentication information of a registered host. For example, if the user password changes, the following command updates the host password used by the collective:

wlp/bin/collective updateHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --rpcUser=osUser 
    --rpcUserPassword=newOsUserPassword

Update registered host read or write paths

Run the updateHost command on the collective utility script to change the host read and write paths. Paths in this command override the previously set paths for hostReadPath and hostWritePath, and do not add to the existing paths.

wlp/bin/collective updateHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword 
    --rpcUser=osUser 
    --rpcUserPassword=osUserPassword 
    --hostReadPath=/optNew 
    --hostWritePath=/opt 
    --hostWritePath=/home/osUser

Unregister a host from a collective controller

Run the unregisterHost command on the collective utility script; for example:

wlp/bin/collective unregisterHost myHost.ibm.com 
    --host=controllerHost 
    --port=controllerHTTPSPort 
    --user=controllerAdmin 
    --password=controllerAdminPassword

Unregistering a host removes all the registered servers on that host and any other host-based information from the collective controller.

What to do next

For information about all parameters of the registerHost, updateHost, and unregisterHost commands, see the API documentation for the CollectiveRegistration MBean.

Concepts:

Collective architecture
File transfer in a Liberty collective
Collective security
File transfer
Liberty collective troubleshooting

Tasks:

Set the default host name of a Liberty server

Reference:

Example of setting up a JMX routing environment
List of provided MBeans