Interface CollectiveRegistrationMBean


public interface CollectiveRegistrationMBean
CollectiveRegistrationMBean defines the interface for registering and unregistering servers and hosts with the collective.

The ObjectName for this MBean is "WebSphere:feature=collectiveController,type=CollectiveRegistration,name=CollectiveRegistration".

The registration operations must provide sufficient data (the host authentication information) for a remote client to be able to start the server. The unregistration operation removes all data associated with the host or server from the collective.

The values specified to the host authentication information should match the values set in the &lthostAuthInfo&gt configuration element for the registered server. Host authentication information should define sufficient information to authenticate the operating system user, using either the user's password or an SSH private key. Use of keys is encouraged; use of passwords is discouraged.

Supported Properties

Host Authentication Information

The host authentication information map containing properties that would be needed by a remote client to start the server. Must not be null during host registration. May be null during host updates, if there is no data to be changed. When specified, the hostAuthInfo map must be complete. Partial updates of the information are not supported.

For example, if the "rpcUserPassword" password has changed, the entire set of required properties must be defined to the host update operation: the "rpcUserPassword", the "rpcUserPassword", and any other information.

Recognized properties are summarized in the following table. Most property values are non-empty Strings, with types and further constraints list by key. Complete details for each property are documented with each property constant.
Property Name Description Data Type / Format Required/Optional
"useHostCredentials" Indicates whether to inherit the host level credentials for member server RPC Boolean optional; default is false. If this option is set to true, all other RPC credentials specified in hostAuthInfo config element are ignored.
"useCollectiveSSHKey" Indicates whether to use a single SSH Key pair for member server RPC Boolean optional; default is true. This option is mutually exclusive with options "RPC_USER_PASSWORD" and "SSH_PRIVATE_KEY".
"rpcHost" The fully qualified host name or IP address String optional; defaults to the hostName parameter specified
"rpcPort" The SSH or RPC port number Integer optional; defaults to SSH port (22)
"rpcUser" The user ID for the remote connection String required
"rpcUserPassword" The password for the user ID String (either clear text or encoded) required if the "sshPrivateKey" property is not specified; otherwise optional
"sshPrivateKey" The SSH private key String (either clear text or encoded) required if the "rpcUserPassword" property is not specified; otherwise optional
"sshPrivateKeyPassword" The password for the SSH private key String (either clear text or encoded) required if the SSH private key is password protected; otherwise optional
"useSudo" Indicates whether using sudo should be used Boolean optional
"sudoUser" The sudo user ID String optional
"sudoUserPassword" The password for the sudo user String (either clear text or encoded) required if the "sudoUser" property specified and a password is required to authenticate as the sudo user; otherwise optional
"hostReadList" The list of locations on the host with allowed read-access. List<String> (The list is allowed to be empty, and string inside it is also allowed to be empty) optional
N.B. This value should be specified in the host paths map. If the host paths map is provided, the value specified in the hostAuthInfo map will be ignored.
"hostWriteList" The list of locations on the host with allowed write-access. List<String> (The list is allowed to be empty, and the string inside it is also allowed to be empty) optional
N.B. This value should be specified in the host paths map. If the host paths map is provided, the value specified in the hostAuthInfo map will be ignored.
"hostJavaHome" The location of the java installation to use for this host. String (If specified, must not be empty) optional
N.B. This value should be specified in the host paths map. If the host paths map is provided, the value specified in the hostAuthInfo map will be ignored.

Host Paths

The host paths map contains the various paths that the collective controller should be aware of on a given host. The host paths map may be null. If host paths map is provided, all path values used are from this map. If host paths map is not provided, some path values from hostAuthInfo map will be used (if defined in hostAuthInfo map). See Host Authentication Information for the set of path values which hostAuthInfo map can define.

Partial updates of the host paths map is supported, individual keys are replaced with new values. For example, a host update operation can change only the "hostReadList" by specifying a new value in the host paths map. In this case, the other values in the host paths map are not changed, but the previous value of "hostReadList" is replaced with the new value specified in the host paths map.

Recognized properties are summarized in the following table. All properties are optional and are documented by key. Complete details for each property are documented with each property constant.
Property Name Description Data Type / Format Required/Optional
"hostReadList" The list of locations on the host with allowed read-access. List<String> (The list is allowed to be empty, and string inside it is also allowed to be empty) optional
"hostWriteList" The list of locations on the host with allowed write-access. List<String> (The list is allowed to be empty, and string inside it is also allowed to be empty) optional
"hostJavaHome" The location of the java installation to use for this host. String (If specified, must not be empty) optional

Certificate Creation Properties

Properties Additional properties to control the certificate creation. May be null or an empty Map. If the Map is null or empty, all default values will be taken. Recognized properties are summarized in the following table. All property values are non-empty Strings, with further constraints by key. Complete details for each property are documented with each property constant.
Property Name Description Data Type / Format Required/Optional
"serverIdentityKeystorePassword" The password for the serverIdentity.p12 keystore String (either clear text or encoded) optional; defaults to the specified keystorePassword parameter
"serverIdentityCertificateValidity" The validity period in number of days for the server identity certificate is valid for Integer, unit is days optional; defaults to 5 years or 1825 days
"collectiveTrustKeystorePassword" The password for the collectiveTrust.p12 keystore String (either clear text or encoded) optional; defaults to the specified keystorePassword parameter
"httpsKeystorePassword" The password for the key.p12 keystore String (either clear text or encoded) optional; defaults to the specified keystorePassword parameter
"httpsCertificateSubject" The DN to use as the HTTPS certificate subject String optional; defaults to CN=hostname,OU=serverName,O=ibm,C=us
"httpsCertificateValidity" The validity period in number of days for the HTTPS certificate is valid for Integer, unit is days optional; defaults to 5 years or 1825 days
"httpsTruststorePassword" The password for the trust.p12 keystore String (either clear text or encoded) optional; defaults to the specified keystorePassword parameter
  • Field Details

    • OBJECT_NAME

      static final String OBJECT_NAME
      A String representing the ObjectName that this MBean maps to.
      See Also:
    • USE_HOST_CREDENTIALS

      static final String USE_HOST_CREDENTIALS
      Whether to inherit the host level credentials for member server RPC.

      If this property is set to true, any RPC operations will use host level credentials.

      This property is optional. If it is not specified, the default is false. If this option is set to true, all other RPC credentials specified in hostAuthInfo config element are ignored.

      See Also:
    • USE_COLLECTIVE_SSH_KEY

      static final String USE_COLLECTIVE_SSH_KEY
      Whether to use a single SSH Key pair for member communication.

      If this property is set, then the product uses a single SSH Pair created by the Collective Controller to invoke commands. The public key will be placed into the configured userId's authorized_keys file if it is not present.

      This property is optional. This property mutually exclusive with properties "rpcUserPassword" and "sshPrivateKey".

      See Also:
    • RPC_HOST

      static final String RPC_HOST
      Host name host authentication information map.

      The host can take on the form of a fully qualified domain name, or an IP address. The host name must be unique within the network and must be the host name on which the remote connection protocol is listening (SSH, or OS specific RPC). The host name should match the defaultHostName or configured value for &lthostAuthInfo&gt in the server.xml.

      This property is optional. If it is not specified, the hostName specified will be used.

      See Also:
    • RPC_PORT

      static final String RPC_PORT
      Port for host authentication information map.

      The port on which the remote connection protocol is listening (SSH, or other supported RPC mechanism). See product documentation for supported RPC mechanisms.

      This property is optional. Type is Integer. If the property is not specified, the SSH port (22) is assumed.

      See Also:
    • RPC_USER

      static final String RPC_USER
      User ID for host authentication information map.

      The operating system user ID to use to connect to the host.

      This property is required.

      See Also:
    • RPC_USER_PASSWORD

      static final String RPC_USER_PASSWORD
      User password for host authentication information map.

      The password for the operating system user.

      Either "rpcUserPassword" or "sshPrivateKey" should be specified, but not both. If both are specified, an IllegalArgumentException will be thrown.

      This property is optional.

      See Also:
    • COLLECTIVE_MEMBER_TYPE

      static final String COLLECTIVE_MEMBER_TYPE
      Collective member type for host authentication information map.

      The type of member that is joining the collective.

      This property is optional.

      See Also:
    • COLLECTIVE_SSH_KEY_SUPORTED

      static final String COLLECTIVE_SSH_KEY_SUPORTED
      Internal hidden property to indicate a client calling CollectiveRegistrationMBean supports collectiveHostAuthionfo.
      See Also:
    • SSH_PRIVATE_KEY

      static final String SSH_PRIVATE_KEY
      SSH private key for host authentication information map.

      The SSH private key to use for authenticating the specified operating system user. The SSH private key value is expected to be in the PEM format; a path to a key file is not supported.

      Example PEM format

      -----BEGIN RSA PRIVATE KEY-----
      ....
      -----END RSA PRIVATE KEY-----
      Any key algorithm supported by the target sshd server is valid.

      Either "rpcUserPassword" or "sshPrivateKey" should be specified, but not both. If both are specified, an IllegalArgumentException will be thrown.

      This property is optional.

      See Also:
    • SSH_PRIVATE_KEY_PASSWORD

      static final String SSH_PRIVATE_KEY_PASSWORD
      SSH private key password for host authentication information map.

      The password for the SSH private key.

      If this property is set but no "sshPrivateKey" has been set, an IllegalArgumentException will be thrown.

      This property is optional.

      See Also:
    • SSH_PUBLIC_KEY

      static final String SSH_PUBLIC_KEY
      SSH public key for host authentication information map.

      The SSH public key to use for allowing the collective controller to connect to a collective members host.

      Example PEM format

      -----BEGIN RSA PRIVATE KEY-----
      ....
      -----END RSA PRIVATE KEY-----
      Any key algorithm supported by the target sshd server is valid.

      Either "rpcUserPassword" or "sshPrivateKey" should be specified, but not both. If both are specified, an IllegalArgumentException will be thrown.

      This property is optional.

      See Also:
    • USE_SUDO

      static final String USE_SUDO
      Use sudo key for host authentication information map.

      If this property is set to true, then sudo will be used to invoke commands. The user to sudo as can be controlled by setting "sudoUser". If "sudoUser" is not set, then the user to sudo as will be the configured default sudo user for the target host.

      If this property is not set, and either "sudoUser" or "sudoUserPassword" are set, then "useSudo" is assumed to be true.

      If this property is set to false, and either "sudoUser" or "sudoUserPassword" are set, then an IllegalArgumentException will be thrown.

      This property is optional. Type is Boolean. Defaults to false if no sudo options are set.

      See Also:
    • SUDO_USER

      static final String SUDO_USER
      sudo user for host authentication information map.

      Causes sudo to run the as specified user.

      This property must not be set when "useSudo" is set to false.

      This property is optional.

      See Also:
    • SUDO_USER_PASSWORD

      static final String SUDO_USER_PASSWORD
      sudo user password for host authentication information map.

      Set this property if the sudo user (explicit or implied) requires a password.

      This property must not be set when "useSudo" is set to false.

      This property is optional.

      See Also:
    • HOST_READ_LIST

      static final String HOST_READ_LIST
      A list of locations on the host with allowed read-access. Key for host paths map. Also supported in the host authentication information map.

      Set this property if file access is needed outside of the server instance level. An example scenario is routing (host level context) a file transfer operation through the collective controller into a registered member.

      This property is optional. Type is List<String>. This property is only valid for registerHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>) and updateHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>).

      See Also:
    • HOST_WRITE_LIST

      static final String HOST_WRITE_LIST
      A list of locations on the host with allowed write-access. Key for host paths map. Also supported in the host authentication information map.

      Set this property if file access is needed outside of the server instance level. An example scenario is routing (host level context) a file transfer operation through the collective controller into a registered member.

      This property is optional. Type is List<String>. This property is only valid for registerHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>) and updateHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>).

      See Also:
    • HOST_JAVA_HOME

      static final String HOST_JAVA_HOME
      The location of the java installation that the collective controller should use for this host. Key for host paths map. Also supported in the host authentication information map.

      Set this property if a different java instance is to be used by the collective controller when invoking archive expansion on the host during routing file transfer uploads.

      This property is optional. If specified, must not be empty. This property is only valid for registerHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>) and updateHost(java.lang.String,java.util.Map<java.lang.String,java.lang.Object>,java.util.Map<java.lang.String,java.lang.Object>).

      See Also:
    • COLLECTIVE_ROOT_KEYSTORE_PASSWORD

      static final String COLLECTIVE_ROOT_KEYSTORE_PASSWORD
      The rootKeys.p12 keystore password for the certificate properties.

      This property is optional.

      See Also:
    • SERVER_IDENTITY_KEYSTORE_PASSWORD

      static final String SERVER_IDENTITY_KEYSTORE_PASSWORD
      The serverIdentity.p12 keystore password for the certificate properties.

      This property is optional.

      See Also:
    • SERVER_IDENTITY_CERTIFICATE_VALIDITY

      static final String SERVER_IDENTITY_CERTIFICATE_VALIDITY
      The validity in days of the serverIdentity certificate for the certificate properties.

      This property is optional. Type is Integer, unit is days. Defaults to 5 years or 1825 days.

      See Also:
    • COLLECTIVE_TRUST_KEYSTORE_PASSWORD

      static final String COLLECTIVE_TRUST_KEYSTORE_PASSWORD
      The collectiveTrust.p12 keystore password for the certificate properties.

      This property is optional.

      See Also:
    • HTTPS_KEYSTORE_PASSWORD

      static final String HTTPS_KEYSTORE_PASSWORD
      The key.p12 keystore password for the certificate properties.

      This property is optional.

      See Also:
    • HTTPS_CERTIFICATE_SUBJECT

      static final String HTTPS_CERTIFICATE_SUBJECT
      The subject of the HTTPS certificate for the certificate properties.

      This property is optional.

      See Also:
    • HTTPS_CERTIFICATE_VALIDITY

      static final String HTTPS_CERTIFICATE_VALIDITY
      The validity in days of the HTTPS certificate for the certificate properties.

      This property is optional. Type is Integer, unit is days. Defaults to 5 years or 1825 days.

      See Also:
    • HTTPS_TRUSTSTORE_PASSWORD

      static final String HTTPS_TRUSTSTORE_PASSWORD
      The trust.p12 keystore password for the certificate properties.

      This property is optional.

      See Also:
    • KEYSTORE_SERVER_IDENTITY_P12

      static final String KEYSTORE_SERVER_IDENTITY_P12
      Key for the serverIdentity.p12 entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/serverIdentity.p12

      See Also:
    • KEYSTORE_SERVER_IDENTITY_JKS

      static final String KEYSTORE_SERVER_IDENTITY_JKS
      Key for the serverIdentity.jks entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/serverIdentity.jks

      See Also:
    • KEYSTORE_SERVER_IDENTITY_PFX

      static final String KEYSTORE_SERVER_IDENTITY_PFX
      Key for the serverIdentity.pfx entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/serverIdentity.pfx

      See Also:
    • X509_CERTIFICATE

      static final String X509_CERTIFICATE
      See Also:
    • KEYSTORE_COLLECTIVE_TRUST_JKS

      static final String KEYSTORE_COLLECTIVE_TRUST_JKS
      Key for the collectiveTrust.jks entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/collectiveTrust.jks

      See Also:
    • KEYSTORE_COLLECTIVE_TRUST_P12

      static final String KEYSTORE_COLLECTIVE_TRUST_P12
      Key for the collectiveTrust.p12 entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/collectiveTrust.p12

      See Also:
    • KEYSTORE_COLLECTIVE_TRUST_PFX

      static final String KEYSTORE_COLLECTIVE_TRUST_PFX
      Key for the collectiveTrust.pfx entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/collectiveTrust.pfx

      See Also:
    • KEYSTORE_KEY_JKS

      static final String KEYSTORE_KEY_JKS
      Key for the key.jks entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/key.jks

      See Also:
    • KEYSTORE_KEY_P12

      static final String KEYSTORE_KEY_P12
      Key for the key.p12 entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/key.p12

      See Also:
    • KEYSTORE_KEY_PFX

      static final String KEYSTORE_KEY_PFX
      Key for the key.pfx entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/key.pfx

      See Also:
    • KEYSTORE_TRUST_JKS

      static final String KEYSTORE_TRUST_JKS
      Key for the trust.jks entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/trust.jks

      See Also:
    • KEYSTORE_TRUST_P12

      static final String KEYSTORE_TRUST_P12
      Key for the trust.p12 entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/trust.p12

      See Also:
    • KEYSTORE_TRUST_PFX

      static final String KEYSTORE_TRUST_PFX
      Key for the trust.pfx entry in the map returned by join and replicate.

      This entry should be written to: ${server.config.dir}/resources/security/trust.pfx

      See Also:
    • KEYSTORE_ROOT_KEYS_JKS

      static final String KEYSTORE_ROOT_KEYS_JKS
      Key for the rootKeys.jks entry in the map returned by replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/rootKeys.jks

      See Also:
    • KEYSTORE_ROOT_KEYS_P12

      static final String KEYSTORE_ROOT_KEYS_P12
      Key for the rootKeys.p12 entry in the map returned by replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/rootKeys.p12

      See Also:
    • FILE_COLLECTIVE_UUID

      static final String FILE_COLLECTIVE_UUID
      Key for the collective.uuid entry in the map returned by replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/collective.uuid

      See Also:
    • FILE_COLLECTIVE_NAME

      static final String FILE_COLLECTIVE_NAME
      Key for the collective.name entry in the map returned by replicate.

      This entry should be written to: ${server.config.dir}/resources/collective/collective.name

      See Also:
    • CERTIFICATE_SUBJECT

      static final String CERTIFICATE_SUBJECT
      The subject of the certificate for the genKey certificate.

      This property is optional.

      See Also:
    • CERTIFICATE_SUBJECT_ALT_NAMES

      static final String CERTIFICATE_SUBJECT_ALT_NAMES
      The subject alternative names of the certificate for all certificate.
      See Also:
    • CERTIFICATE_VALIDITY

      static final String CERTIFICATE_VALIDITY
      The validity in days of the certificate for the genKey certificate.

      This property is optional. Type is Integer, unit is days. Defaults to 5 years or 1825 days.

      See Also:
    • CustomKeystoreMember

      static final String CustomKeystoreMember
      Property to identify when custom keystores are specified in CLI

      See Also:
    • KEY_FOR_CONTROLLER

      static final String KEY_FOR_CONTROLLER
      See Also:
    • SERVER_IDENTITY_ALIAS

      static final String SERVER_IDENTITY_ALIAS
      See Also:
  • Method Details

    • registerHost

      void registerHost(String hostName, Map<String,Object> hostAuthInfo, Map<String,Object> hostPaths) throws IOException, IllegalArgumentException, IllegalStateException
      Registers a host with the collective. The host name provided is converted to lowercase when it is registered.

      The host authentication information requires either the user password or the SSH private key.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      hostAuthInfo - See the Host Authentication Information CollectiveRegistrationMBean. Must not be null.
      hostPaths - See the Host Paths CollectiveRegistrationMBean. May be null.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid or if any of the keys in the properties map are unrecognized
      IllegalStateException - If the host was already registered
    • registerHost

      void registerHost(String hostName, Map<String,Object> hostAuthInfo) throws IOException, IllegalArgumentException, IllegalStateException
      Same as registerHost(String, Map, Map), except hostPaths is null. Some host paths are may be specified in hostAuthInfo.
      Throws:
      IOException
      IllegalArgumentException
      IllegalStateException
    • updateHost

      void updateHost(String hostName, Map<String,Object> hostAuthInfo, Map<String,Object> hostPaths) throws IOException, IllegalArgumentException, IllegalStateException
      Updates the authentication information for a known host with the collective.

      The host authentication information requires either the user password or the SSH private key.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      hostAuthInfo - See the Host Authentication Information CollectiveRegistrationMBean. May be null if there is no authentication information to change.
      hostPaths - See the Host Paths CollectiveRegistrationMBean. May be null if there is no path information to change.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid or if any of the keys in the properties map are unrecognized
      IllegalStateException - If the host was not registered
    • updateHost

      void updateHost(String hostName, Map<String,Object> hostAuthInfo) throws IOException, IllegalArgumentException, IllegalStateException
      Same as registerHost(String, Map, Map), except hostPaths is null. Some host paths are may be specified in hostAuthInfo.
      Throws:
      IOException
      IllegalArgumentException
      IllegalStateException
    • unregisterHost

      void unregisterHost(String hostName) throws IOException, IllegalArgumentException, IllegalStateException
      Unregisters a host from the collective. Any servers on this host will be automatically removed from any clusters for which they are a member.
      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid
      IllegalStateException - If the host was not registered
    • join

      Map<String,byte[]> join(String hostName, String wlpUserDir, String serverName, String wlpInstallDir, String keystorePassword, Map<String,Object> certProperties, Map<String,Object> hostAuthInfo) throws IOException, IllegalArgumentException, IllegalStateException, CertificateException, KeyStoreException
      Join the specified server to the collective as a member.

      This will register the server and generate the security credentials required by the server to communicate with the collective.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      The host authentication information requires either the user password or the SSH private key.

      Parameters:
      hostName - The host name. Must not be null or an empty string. The host name set here will directly control where the server's information is stored within the repository. This host name should match the host name set to the defaultHostName variable for the server's server.xml Must not be null or an empty string.
      wlpUserDir - The canonical path for the user directory of server. This should match the WLP_USER_DIR environment variable for the server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      serverName - The server name. Must not be null or an empty string.
      wlpInstallDir - The Liberty install directory for this server. Must not be null or an empty string.
      keystorePassword - The password to protect the created keystores. Must not be null. Each keystore's password can be overridden individually by specifying additional certProperties.
      certProperties - See the Certificate Creation Properties CollectiveRegistrationMBean
      hostAuthInfo - See the Host Authentication Information CollectiveRegistrationMBean
      Returns:
      A Map of byte[] mapped to a keystore name. Each element in the map represents the bytes of a keystore file that should be laid down on disk.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid or if any of the keys in the properties maps are unrecognized
      IllegalStateException - If the server was already registered
      CertificateException - If there is a problem creating the certificates
      KeyStoreException - If there is a problem creating the keystore
      PrivilegedActionException
    • genKey

      Map<String,byte[]> genKey(String keystorePassword, Map<String,Object> certProperties, Boolean addMemberRootSigner) throws IOException, IllegalArgumentException, IllegalStateException, CertificateException, KeyStoreException
      Generate a collective controller client keystore.

      This will register the server and generate the security credentials required by the server to communicate with the collective.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      The host authentication information requires either the user password or the SSH private key.

      Parameters:
      keystorePassword - The password to protect the created keystores. Must not be null. Each keystore's password can be overridden individually by specifying additional certProperties.
      certProperties - See the Certificate Creation Properties CollectiveRegistrationMBean
      addMemberRootSigner - if true, add member root signer to the generated keystore
      Returns:
      A Map of byte[] mapped to a keystore name. The return element in the map represents the bytes of a keystore file that should be laid down on disk.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid or if any of the keys in the properties maps are unrecognized
      IllegalStateException - If the server was already registered
      CertificateException - If there is a problem creating the certificates
      KeyStoreException - If there is a problem creating the keystore
    • replicate

      Map<String,byte[]> replicate(String hostName, String wlpUserDir, String serverName, String wlpInstallDir, String keystorePassword, Map<String,Object> certProperties, Map<String,Object> hostAuthInfo) throws IOException, IllegalArgumentException, IllegalStateException, CertificateException, KeyStoreException
      Replicates the collective controller configuration it order to allow the specified server to act as a collective controller.

      This will register the server and generate the security credentials required by the server to communicate with the collective.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      The host authentication information requires either the user password or the SSH private key.

      Parameters:
      hostName - The host name. Must not be null or an empty string. The host name set here will directly control where the server's information is stored within the repository. This host name should match the host name set to the defaultHostName variable for the server's server.xml
      wlpUserDir - The canonical path for the user directory of server. This should match the WLP_USER_DIR environment variable for the server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      serverName - The server name. Must not be null or an empty string.
      wlpInstallDir - The Liberty install directory for this server. Must not be null or an empty string.
      keystorePassword - The password to protect the created keystores. Must not be null. Each keystore's password can be overridden individually by specifying additional certProperties.
      certProperties - See the Certificate Creation Properties CollectiveRegistrationMBean
      hostAuthInfo - See the Host Authentication Information CollectiveRegistrationMBean
      Returns:
      A Map of byte[] mapped to a keystore name. Each element in the map represents the bytes of a keystore file that should be laid down on disk.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid or if any of the keys in the properties maps are unrecognized
      IllegalStateException - If the server was already registered
      CertificateException - If there is a problem creating the certificates
      KeyStoreException - If there is a problem creating the keystore
    • remove

      void remove(String hostName, String wlpUserDir, String serverName) throws IOException, IllegalArgumentException, IllegalStateException
      Removes the server from the collective. The server will be automatically removed from any clusters for which it is a member.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      Parameters:
      hostName - The host name. Must not be null or an empty string. This host name should match the host name set to the defaultHostName variable for the server's server.xml
      wlpUserDir - The canonical path for the user directory of server. This should match the WLP_USER_DIR environment variable for the server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      serverName - The server name. Must not be null or an empty string.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid
      IllegalStateException - If the server was not registered
    • avow

      void avow(String hostName, String wlpUserDir, String serverName) throws IOException, IllegalArgumentException, IllegalStateException
      Avow the server to the collective. The server will be allowed to authenticate to the collective as long as it has the correct credentials.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      Parameters:
      hostName - The host name. Must not be null or an empty string. This host name should match the host name set to the defaultHostName variable for the server's server.xml
      wlpUserDir - The canonical path for the user directory of server. This should match the WLP_USER_DIR environment variable for the server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      serverName - The server name. Must not be null or an empty string.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid
      IllegalStateException - If the server was not registered
    • disavow

      void disavow(String hostName, String wlpUserDir, String serverName) throws IOException, IllegalArgumentException, IllegalStateException
      Disavow the server from the collective. The server will be prevented from authenticating to the collective controllers.

      A server is uniquely identified by its name, the host on which it resides, and the wlpUserDir within which it resides. The wlpUserDir is used in the repository path to differentiate between servers of the same name on the same host.

      Parameters:
      hostName - The host name. Must not be null or an empty string. This host name should match the host name set to the defaultHostName variable for the server's server.xml
      wlpUserDir - The canonical path for the user directory of server. This should match the WLP_USER_DIR environment variable for the server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      serverName - The server name. Must not be null or an empty string.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid
      IllegalStateException - If the server was not registered
    • registerInstallDir

      void registerInstallDir(String hostName, String type, String wlpInstallDir) throws IOException, IllegalArgumentException, IllegalStateException
      Registers the liberty installed directory for the host to the collective repository. It will add a new branch per host to collective repository /sys.was.collectives/local/hosts/installdirs//<install-dir> and <install-dir> will be URL encoded. Example of an (unencoded) install-dir value: /opt/wlp
      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      type - The installable type, valid types are wlp, jre and other. Default is other.
      wlpInstallDir - The canonical path for the install directory. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      Throws:
      IOException - If there was any problem completing the operation.
      IllegalArgumentException - If any of the parameters are not valid.
      IllegalStateException - If the host was unregistered or the install directory was registered already.
    • unregisterInstallDir

      void unregisterInstallDir(String hostName, String type, String wlpInstallDir) throws IOException, IllegalArgumentException, IllegalStateException
      Unregisters the liberty installed directory for the host from the collective repository.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      type - The installable type, valid types including wlp, jre and other. Default is other.
      wlpInstallDir - The canonical path for the install directory. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      Throws:
      IOException - If there was any problem completing the operation.
      IllegalArgumentException - If any of the parameters are not valid.
      IllegalStateException - If the host or install directory was unregistered.
    • listInstallDirs

      List all liberty installed directories under the specified host.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      type - The installable type, valid types including wlp, jre and other. Default is other.
      Throws:
      IOException - If there was any problem completing the operation.
      IllegalArgumentException - If the parameter is not valid.
      IllegalStateException - If the host was unregistered.
    • listHosts

      List all hosts configured in the collective repository .

      Throws:
      IOException - If there was any problem completing the operation.
      IllegalStateException
    • listUserDirs

      List all user directories of server for the specified host.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid
      IllegalStateException - If the host was unregistered.
    • listServers

      List<String> listServers(String hostName, String wlpUserDir) throws IOException, IllegalArgumentException, IllegalStateException
      List all liberty servers created under the specified host and user directory.

      Parameters:
      hostName - The case insensitive host name. Must not be null or an empty string.
      wlpUserDir - The canonical path for the user directory of server. Must not be null or an empty string. Must not have a trailing slash. Must not be encoded.
      Throws:
      IOException - If there was any problem completing the operation
      IllegalArgumentException - If any of the parameters are not valid.
      IllegalStateException - If the host was unregistered
    • getPublicSSHKey

      String getPublicSSHKey() throws IllegalStateException
      Return the public SSH key for this server if the controller is not part of a replica.

      Throws:
      IllegalStateException
    • isContollerUsingCustomKeystore

      boolean isContollerUsingCustomKeystore() throws IllegalStateException
      Return if the controller is using custom/3rd party keystores. A controller uses a custom / 3rd party keystore if a keystore and trust store were provided when the controller was created, rather than a new keystore and trust store that were generated by the collective utility

      Throws:
      IllegalStateException