The collective join command adds the server to the collective configuration, and also
creates server-side XML to define the communication path to the collective controller.
From
the host server, run the collective join command to add the server.
Before
you run the command, ensure that you have these items:
- A network connection to the collective controller.
- An administrative user ID and password to perform MBean operations on the controller.
- Values for the --host, --port,
-user, and --password parameters. Obtain these parameters
from the server.xml file of the collective controller.
Run the following
command:
wlp/bin/collective join server1 --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword [--hostname=memberHostname]
On
the --keystorePassword parameter, set a value for the member keystore password,
such as memberKSPassword. You can specify different
--keystorePassword values for each server that you join to the
collective.
Set the optional --hostname parameter only if the system for
the member server has multiple host names or does not have a host name configured. If you set the
parameter, the value must match the defaultHostName variable that is defined in
the server.xml file.
To reduce the
number of parameters needed, use the --controller parameter instead of the
--user, --password, --host, and
--port parameters:
wlp/bin/collective join server1 --controller=user[:password]@host:httpsPort --keystorePassword=memberKSPassword [--hostname=memberHostname]
By
default, self-signed certificates are created. For more information on collective-wide SSH,
including how to use existing keys, see
Collective-wide SSH key configuration.
If you already set up your
own keystore and truststore files, you can add more parameters to the
collective
join command to specify the keystore and truststore files to
use:
wlp/bin/collective join server1 --controller=user[:password]@host:httpsPort --keystorePassword=controllerKSPassword --serverIdentityKeystore="keystore_filespec" --serverIdentityKeystoreAlias="certificate_alias" --collectiveTrustKeystore="truststore_filespec" [–certificateRdn="xxx"]
When you run the
collective join command to
add the member server to the collective, you must use SAF key rings and certificates instead of
file-based keystore files. If you set up your key ring and certificates in advance, you can specify
the
--setupSAF parameter to indicate that you are using the following default values:
- SAF key ring name for SSL:
LZMember.Ring
- SAF certificate label for SSL:
LZMember.CERT
The certificate must be signed and must be the default certificate in the key ring. You must
specify the relative distinguished name (RDN) value of
OU=LZCollective
in the
certificate or alternatively specify an RDN value on the
--certificateRDN
parameter. Use the
--certificateRDN parameter when the RDN value is not
OU=LZCollective
. You can use a SAF key ring and certificate that you already set up
for the
collective join command instead of keystore files.
The following
collective join command example uses the
--setupSAF and
--certificateRDN parameters that are
described
previously:
wlp/bin/collective join server1 --controller=user[:password]@host:httpsPort --keystorePassword=password --createConfigFile=$WLP_USER_DIR/servers/server1/member.xml --setupSAF [–certificateRdn="xxx"]
To
specify your own key ring and certificate names for the z/OS operating system, omit the
--setupSAF parameter. If your collective RDN is something other than a value of
OU=LZCollective
, provide the key ring and certificate name, along with a value for
the
--certificateRdn parameter. The following example shows how to specify your
own key ring and
certificate:
wlp/bin/collective join server1 --controller=user[:password]@host:httpsPort --keystorePassword=password --createConfigFile=$WLP_USER_DIR/servers/server1/member.xml --serverIdentityKeystore="safkeyring:///LZ2.Ring" --serverIdentityKeystoreAlias="LZ2.CERT" --collectiveTrustKeystore="safkeyring:///LZ2.Ring" [–certificateRdn="xxx"]
For example, the JVM
java.security file might specify the
following two cryptographic providers.
security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.2=com.ibm.crypto.provider.IBMJCE
In this case, include the
--safKeystoreType and
--safKeystoreProvider parameters to specify the
IBMJCECCA
cryptographic hardware provider, as shown in the following
example.
wlp/bin/collective join memberName --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword
--keystorePassword=memberKSPassword --serverIdentityKeystore="safkeyringhw:///MEMBER.KEY"
--serverIdentityKeystoreAlias="MEMBER" --collectiveTrustKeystore="safkeyringhw:///MEMBER.KEY"
--safKeystoreType=JCECCARACFKS --safKeystoreProvider=IBMJCECCA
In a hybrid scenario,
the JVM
java.security file might specify the following three cryptographic providers.
security.provider.1=com.ibm.crypto.ibmjcehybrid.provider.IBMJCEHYBRID
security.provider.2=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA
security.provider.3=com.ibm.crypto.provider.IBMJCE
In this case, the
--safKeystoreType and
--safKeystoreProvider parameters can specify the
IBMJCEHYBRID
cryptographic hybrid provider, as shown in the following
example.
wlp/bin/collective join memberName --host=controllerHostname --port=443 --user=adminUser --password=adminPassword
--keystorePassword=memberKSPassword --serverIdentityKeystore="safkeyringhybrid:///MEMBER.KEY"
--serverIdentityKeystoreAlias="MEMBER" --collectiveTrustKeystore="safkeyringhybrid:///MEMBER.KEY"
--safKeystoreType=JCEHYBRIDRACFKS --safKeystoreProvider=IBMJCEHYBRID
In version 22.0.0.10 and later, the collective join
--help command provides information about the --safKeystoreType and
--safKeystoreProvider parameters.
You can specify
deployment variables by using the optional genDeployVariable parameter. For
more information, see Generating
deployment variables when joining a member server to a collective.
To write the output of this collective command to a file, instead of to
a console screen, specify an optional
--createConfigFile parameter. Then,
include the outputted file in the collective configuration by adding an
include
statement to the member
server.xml
file:
<include location=outputFilePath />
By default, the join operation leaves remote procedure call (RPC) credentials
undefined. You must specify values for the rpcUser parameter, the
rpcUserPassword parameter. You must also specify values for the operating
system login user ID and password for the host on which the member server exists. If the member host
is registered with the collective controller and the member host is not enabled for SSH, specify an
optional --useHostCredentials parameter. When you specify this parameter, the
member inherits the RPC credentials from its host registration on the controller. Typically, Linux® hosts are
enabled for SSH and Windows hosts are not enabled for SSH; thus, the
--useHostCredentials
parameter is useful for Windows member hosts. Specifying
--useHostCredentials
adds <hostAuthInfo useHostCredentials="true"
/>
to the member server.xml file. You then can run collective member
server commands such as start or stop without specifying RPC
credentials because the member inherits credentials from its host. See Overriding Liberty server host information for
information about the hostAuthInfo
element, the
--useHostCredentials
parameter, and connecting the collective controller to the
server. See Setting up RXA for Liberty collective
operations for information about enabling SSH on your host computer.
For information about these required parameters and other optional parameters, run the
collective help join command at a command line.