Overriding Liberty server host information

The collectiveMember-1.0 feature enables a server to be managed by the collective controller. Most server host information can be automatically detected. However, in certain scenarios, we must provide extra host information so that the collective controller can establish a connection to the server.

To enable the host information override, add the following element to the server.xml file: 

    <hostAuthInfo rpcPort="ssh_port"
  rpcUser="user_ID"
  rpcUserPassword="password"
  rpcUserHome="user_home"
  rpcHost="host_name"
  sudoUser="sudo_user"
  sudoPassword="sudo_user_password"
  sshPublicKeyPath="public_key_path"
  sshPrivateKeyPath="private_key_path"
  sshPrivateKeyPassword="private_key_password"
  useHostCredentials="true_or_false"
  useCollectiveSSHKey="true_or_false"/>

    rpcPort

    Port for the RPC mechanism, which is SSH port 22 by default. If the system uses a nonstandard port, set this value accordingly. If this value is not specified, the default value is 22.

    rpcUser

    User ID that the collective controller uses to connect to the server. If the host does not support SSH or the use of SSH keys is not wanted, we can use this parameter to specify an operating system login user. For example, if you log in to the host with the myID user, then we specify rpcUser="myID". If this value is not specified, the default value is System.getProperty("user.name").

    rpcUserPassword

    Password for the specified user ID. For example, if you log in to the host with the myID user and the myPwd password, then we specify rpcUser="myID" and rpcUserPassword="myPwd". If this value is not specified, the server either generates an SSH key pair or uses the SSH key pair for the connection as specified by the privateKeyPath and publicKeyPath parameters.

    If this value is not specified, the server uses the collective-wide SSH key pair if available. That SSH key pair is the SSH key pair as specified by the sshPrivateKeyPath and sshPublicKeyPath parameters, or generates an SSH key pair. If SSH is not installed on the server (such as, for a Windows or OS/400 operating system), the password is required.

    rpcUserHome

    This parameter specifies the home directory of the user. If this value is not specified, the default value is System.getProperty("user.home"). If rpcUser is specified, specify rpcUserHome.

    rpcHost

    This parameter specifies the host on which the RPC mechanism is configured to listen. If this value is not specified, the default value is the value of the defaultHostName variable. If the system uses a host other than the defaultHostName, set this value accordingly.

    sudoUser

    If this value is specified, it allows the collective controller to run commands as another, or "sudo", user instead of as the user ID used for the connection. This parameter applies only to servers that have an SSH server installed. This parameter has no default value.

    sudoPassword

    Password for the sudo user specified by the sudoUser parameter. This parameter applies only to servers that have an SSH server installed. This parameter has no default value.

    sshPublicKeyPath

    Path and file name of a user-specified public key file. If this value is not specified, the default is ${server.output.dir}/resources/security/ssh/id_rsa.pub. If the specified file (or default file) does not exist, a new public key file is generated.

    If this value is not specified, the server uses the collective-wide SSH key pair if available, or the server generates an SSH key pair at the default location.

    sshPrivateKeyPath

    Path and file name of a user-specified private key file and is intended for use with sshPrivateKeyPassword to establish a password protected private key. If this value is not specified, the default is ${server.output.dir}/resources/security/ssh/id_rsa. If the specified file (or default file) does not exist, a new private key file will be generated.

    If this value is not specified, the server will use the collective-wide SSH key pair if available, or the server will generate an SSH key pair at the default location.

    sshPrivateKeyPassword

    Password for the private key. This parameter has no default value. For the private key to be used, the password must be provided using sshPrivateKeyPassword. The Liberty default configuration uses non-protected private keys. If we generate our own private key with a password, then use sshPrivateKeyPassword or our own private key is not usable.

    Note:

    1. When a private key is protected by a password, the key bytes, as stored, are encrypted with a password-derived symmetric key. A private key is readily encodable as a sequence of bytes, and can be copied, encrypted, and decrypted just like any file.

    2. For key-based authentication, if we use sshPrivateKeyPassword 

        <hostAuthInfo
sshPrivateKeyPassword="private_key_password"
/>

      ...a CWWKX8120W message occurs warning you that the sshPrivateKeyPassword was set without using a corresponding sshPrivateKeyPath.

    useHostCredentials

    This parameter specifies whether collective member server commands inherit RPC credentials from the host. The default is false, requiring the user to specify RPC credentials for the controller to remotely start or stop the member. When set to true, collective member server commands inherit RPC credentials from the host registration and ignore all other RPC credentials in the hostAuthInfo configuration element.

    useCollectiveSSHKey

    This property specifies whether the server uses the collective-wide SSH key pair or another RPC mechanism. If not set, the server uses another RPC mechanism if specified, the collective-wide SSH key pair if available, or generate a new SSH key pair for use exclusively by this server. If set to true, the server uses the collective-wide SSH key pair or issue an error message if a collective-wide key is not available. If set to false, the server uses another RPC mechanism if specified or generate an SSH key pair for use exclusively by this server .


Examples

Scenario 1: Server is on Windows operating system, no SSH is installed

Scenario 2: Server has SSH installed, SSH is running on port 2222

Scenario 3: Need to run commands as another user 

    <hostAuthInfo sudoUser="anotherUser" sudoPassword="anotherPassword"/>

Scenario 4: Server is on a Windows operating system and an SSH service such as Cygwin is installed. With the following server configuration, the controller connects the member server with SSH. In this case, the requirement to disable Windows User Account Control (UAC) does not apply. The parameter <user's home directory> is the user default home directory; for example, C:\cygwin\home\bob:

Scenario 5: The collective controller and member are on separate hosts, and not on the same host. To specify that the member inherit RPC credentials from the host, set useHostCredentials to true in the server.xml file of the member. Complete the following steps to configure the member to inherit RPC credentials from the host by specifying --useHostCredentials in the join command that joins a server as a member to the collective.

  1. Create, configure, and start a collective controller named myController as shown in step 1 of Configure a Liberty collective.

  2. Register the host for the member with the collective. The member and the collective controller are on different hosts.

    In this scenario, the registerHost command uses the collective controller host hostA.ibm.com with port number 9443, user admin, and password adminpwd. The command registers the member host hostB.ibm.com with the collective, and sets rpcUser to an operating system login user ID for the member host osUser1, and rpcUserPassword to the operating system login password for the user ID for the member host osUser1Pwd. Run the registerHost command on the collective controller host. 

      wlp/bin/collective registerHost hostB.ibm.com --host=hostA.ibm.com --port=9443 --user=admin --password=adminpwd --rpcUser=osUser1 --rpcUserPassword=osUser1Pwd

    Alternate syntax: 

      wlp/bin/collective registerHost hostB.ibm.com --controller=admin:adminpwd@hostA.ibm.com:9443 --rpcUser=osUser1 --rpcUserPassword=osUser1Pwd

    Enter y (yes) when prompted to accept the certificate chain. After registration, the Host hostB.ibm.com successfully registered. message displays. The collective controller host now has the operating system user ID and password of the member host.

  3. On the member host, create a server named myMember to use as a collective member. 

      wlp/bin/server create myMember

  4. Add the myMember server to the collective controller, specifying to use host credentials. In the join command, which is run on the member host, specify --useHostCredentials so that the member inherits RPC credentials from the host registration. 

      wlp/bin/collective join myMember --host=hostA.ibm.com --port=9443 --user=admin --password=adminpwd --keystorePassword=memberKSPassword --useHostCredentials

    Alternate syntax: 

      wlp/bin/collective join myMember --controller=admin:adminpwd@hostA.ibm.com:9443 --keystorePassword=memberKSPassword --useHostCredentials

  5. Update the member server.xml file as shown in step 2 of Configure a Liberty collective.

    Because you specified --useHostCredentials in the join command, the configuration generated for the member server.xml file sets useHostCredentials to true: 

      <!-- Remote host authentication configuration -->
<hostAuthInfo useHostCredentials="true" />

With the --useHostCredentials option, we do not need to specify the operating system user ID and password in the member server.xml file because the member inherits credentials from the host. Later, if the operating system user ID or password of the member server changes, run the updateHost command to change the user ID or password. For more information about the registerHost and updateHost commands, see Register host computers with a Liberty collective.