Registering host computers with a Liberty collective

You 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.

Before you begin

  1. Construct a Liberty collective. See Configuring a Liberty collective.

    For IBM i platformsDistributed: [AIX MacOS Linux Windows]The collectiveController-1.0 feature and its capabilities are available only in multiple-server products such as WebSphere® Application Server Network Deployment Liberty and WebSphere Application Server for z/OS® Liberty. The feature is not available in single-server products such as WebSphere Application Server Liberty, or WebSphere Application Server Liberty Core. If you have a multiple-server product installation, you can use its collectiveController-1.0 feature to work with collective members from single-server products.

  2. If you need to enable connections to servers on local and remote hosts, complete the steps for your host operating system in Setting up RXA for Liberty collective operations. The topic provides information about the Tivoli® Remote Execution and Access (RXA) toolkit and enabling Secure Shell (SSH) protocol. You can use RXA to remotely start and stop servers, including starting and stopping servers on your local computer, and to transfer files to and from registered hosts.
    For Windows platformsNote: In Windows, system environment variables are visible only inside the shell that RXA connects to. Setting PATH in the command window is not sufficient. You must set PATH in the system variable section of the environment variables, or use -hostJavaHome <PATH TO IBM JAVA> with the updateHost option.

About this task

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 domain name system (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
Note: When a Liberty server is joined to a collective, the associated host is automatically registered with the collective controller if it is not already registered.

A host can be registered with the collective under different names. Ensure 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.

Procedure

  • Register a host with a collective controller.
    To register the current host where both the collective controller host and the remote target host are the same computer, 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

    To reduce the number of options needed, use the --controller option instead of--user, --password, --host, and --port.

    wlp/bin/collective registerHost 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    

    The previous example command generates a unique SSH key pair for authenticating to the SSH server of a specified host computer.

    The previous example command uses the collective-wide SSH key pair, if available, for authentication to the SSH server of the specified host computer. If you are registering a remote host for which an SSH key pair is already generated, you can specify the path of the SSH private key file. The following registerHost command assumes that the SSH private key is stored on the local controller computer at /home/user1/.ssh/id_rsa. The other file in the SSH key pair is the /home/user1/.ssh/authorized_keys public key file on the remote target host.
    wlp/bin/collective registerHost remotehost.ibm.com --host=controllerHost 
    --port=controllerHTTPSPort --user=controllerAdmin --password=controllerAdminPassword 
    --sshPrivateKey=/home/user1/.ssh/id_rsa

    To reduce the number of options needed, use the --controller option instead of--user, --password, --host, and --port.

    wlp/bin/collective registerHost remotehost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --sshPrivateKey=/home/user1/.ssh/id_rsa 
    
    If the remote target host does not support SSH or you do not want to use SSH keys, you can specify an operating system login user for rpcUser and login password for rpcUserPassword. If you include rpcUser with rpcUserPassword, do not include sshPrivateKey. The command to specify operating system login user and password resembles:
    wlp/bin/collective registerHost remotehost.ibm.com --host=controllerHost 
    --port=controllerHTTPSPort --user=controllerAdmin --password=controllerAdminPassword 
    --rpcUser=osUserForRemoteHost --rpcUserPassword=osUserPasswordForRemoteHost
    wlp/bin/collective registerHost remotehost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --rpcuser=osUserForRemoteHost --rpcUserPassword=osUserPasswordForRemoteHost 
    
    To transfer files to and from a host, you must specify host read and write paths. Unless the registerHost command specifies the paths, you 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. Paths that are specified by hostWritePath are also readable. For example, to upload an archive to /opt/wlp, you 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
    wlp/bin/collective registerHost myHost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --rpcuser=osUser --rpcUserPassword=osUserPassword 
    --hostReadPath=\opt --hostWritePath=/dir1 --hostWritePath=/dir2
    To use the Deploy tool of Admin Center to deploy a Liberty server package, you must set hostWritePath to the path to which you want 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
    wlp/bin/collective registerHost myHost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --rpcuser=osUser --rpcUserPassword=osUserPassword 
    --hostWritePath=c:\was\liberty\brokerageAppTest --hostWritePath=c:\wlp_backup

    Optionally, specify the path to the Java home directory of the host with the -hostJavaHome parameter. For example: -hostJavaHome=c:\java\jre

  • 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 that is used by the collective:

    wlp/bin/collective updateHost myHost.ibm.com --host=controllerHost 
    --port=controllerHTTPSPort --user=controllerAdmin --password=controllerAdminPassword 
    --rpcUser=osUser --rpcUserPassword=newOsUserPassword
    wlp/bin/collective updateHost myHost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --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
    wlp/bin/collective updateHost myHost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 
    --rpcuser=osUser --rpcUserPassword=osUserPassword 
    --hostReadPath=/optNew --hostWritePath=/opt --hostWritePath=/home/osUser
  • Validate RXA connectivity.

    Run the testConnection command on the collective utility script to validate RXA connectivity between the collective controller and the registered host. The hostName is the name of the registered host.

    wlp/bin/collective testConnection hostName --host=controllerHost 
    --port=controllerHTTPSPort --user=controllerAdmin 
    --password=controllerAdminPassword --autoAcceptCertificates
    Alternatively, use a simplified --controller option to provide the controller specific information.
    wlp/bin/collective testConnection hostName  
    --controller=user[:password]@host:HttpsPort 
    --autoAcceptCertificates
    
  • 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
    wlp/bin/collective unregisterHost myHost.ibm.com 
    --controller=controllerAdmin:controllerAdminPassword@controllerHost:controllerHttpsPort 

    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.