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.

Configure a Liberty collective.

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 WAS Liberty, WAS Liberty - Express, or WAS Liberty Core installations. A member 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...

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

Generate 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, 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, 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