Configuring a Liberty collective
You can organize Liberty servers into collectives to support clustering, administration, and other operations that act on multiple Liberty servers. By using collectives, you can efficiently and accurately deliver application services to your organization.


Before you begin
The collectiveController-1.0 feature and its capabilities are available only in WebSphere® Application Server Liberty Network Deployment and WebSphere Application Server Liberty for z/OS®. The feature is not available in WebSphere Application Server Liberty, WebSphere Application Server Liberty - Express, or WebSphere Application Server Liberty Core. If you have a WebSphere Application Server Liberty Network Deployment installation, you can use its collectiveController-1.0 feature to work with collective members from WebSphere Application Server Liberty, WebSphere Application Server Liberty - Express, or WebSphere Application Server Liberty Core installations.
About this task
A Liberty collective is a set of Liberty servers that are configured as part of the same administrative and operational domain.
Configuration and state data about a Liberty collective is housed in an active operational repository.
Membership in a Liberty collective is optional. Liberty servers join a collective by registering with a collective controller to become members. Members share information about themselves through the operational repository of the controller.
- A Liberty server can be a member of only one collective.
- Different Liberty servers on the same host can be in different collectives.
- Liberty servers on the same host that are members of a collective can coexist with Liberty servers that are not members of a collective.
Watch:
Introduction
to creating a collective demonstrates the procedure. This video, and other information about
collectives, is available on the WASdev website. [Transcript]
Procedure
- Create and configure your controller.
- Create a server to act as the collective controller.
wlp/bin/server create myController
- Create the collective controller configuration.
The collective controller configuration consists primarily of the administrative domain security configuration that is used for secure communication between controllers and members.
wlp/bin/collective create myController --keystorePassword=controllerKSPassword
By default, this collective command writes all output to a console screen. In the next step, you copy the configuration output into the server.xml. To write the configuration to a file instead of to a console screen, specify a --createConfigFile=outputFilePath parameter, for example:
After you run the create command, the include statement to use is displayed. To include the outputted file in the collective configuration, add the include statement to the server.xml file, for example:wlp/bin/collective create myController --keystorePassword=controllerKSPassword --createConfigFile=c:/wlp/usr/servers/myController/collective-create-include.xml
<include location="c:\wlp\usr\servers\myController\collective-create-include.xml" />
- Update the server.xml file of the collective controller.
- Copy and paste output.
If the command wrote output to a console screen, proceed with the following steps:
- Copy output from the collective command and paste it into the server.xml file.
- Specify administrative user ID and password values for the collective. For example,
change:
to:<quickStartSecurity userName="" userPassword="" />
<quickStartSecurity userName="adminUser" userPassword="adminPassword" />
The default path for the collective controller server.xml file is ${wlp.install.dir}/usr/servers/myController/server.xml or, if the $WLP_USER_DIR variable is set in a server.env file or command window, $WLP_USER_DIR/servers/myController/server.xml. After editing, the file will resemble the following example:<server description="controller server"> <!-- Enable features --> <featureManager> <feature>jsp-2.2</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" httpsPort="9443" /> <featureManager> <feature>collectiveController-1.0</feature> </featureManager> <!-- Define the host name for use by the collective. If the host name needs to be changed, the server should be removed from the collective and re-joined or re-replicated. --> <variable name="defaultHostName" value="controllerHostname" /> <!-- TODO: Set the security configuration for Administrative access --> <quickStartSecurity userName="adminUser" userPassword="adminPassword" /> <!-- clientAuthenticationSupported set to enable bidirectional trust --> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true" /> <!-- inbound (HTTPS) keystore --> <keyStore id="defaultKeyStore" password="yourPassword" location="${server.config.dir}/resources/security/key.jks" /> <!-- inbound (HTTPS) truststore --> <keyStore id="defaultTrustStore" password="yourPassword" location="${server.config.dir}/resources/security/trust.jks" /> <!-- server identity keystore --> <keyStore id="serverIdentity" password="yourPassword" location="${server.config.dir}/resources/collective/serverIdentity.jks" /> <!-- collective trust keystore --> <keyStore id="collectiveTrust" password="yourPassword" location="${server.config.dir}/resources/collective/collectiveTrust.jks" /> <!-- collective root signers keystore --> <keyStore id="collectiveRootKeys" password="yourPassword" location="${server.config.dir}/resources/collective/rootKeys.jks" /> </server>
Add an include statement.
If you wrote the output to a file by using the --createConfigFile=outputFilePath parameter, add an include statement to $WLP_USER_DIR/servers/myController/server.xml to include the outputted file in the collective configuration. For example:<server description="controller server"> <!-- Enable features --> <featureManager> <feature>jsp-2.2</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9080" httpsPort="9443" /> <include location="c:\wlp\usr\servers\myController\collective-create-include.xml" /> </server>
Ensure the outputted file sets administrative user ID and password values for the collective, for example:<quickStartSecurity userName="adminUser" userPassword="adminPassword" />
- Copy and paste output.
- Start the collective controller server.
wlp/bin/server start myController
Figure 1. Collective of one - Verify that the collective controller server started correctly and is ready to receive
members.
- Open an editor on the collective controller messages log, $WLP_USER_DIR/servers/myController/logs/messages.log.
- Look for the following
message:
CWWKX9003I: CollectiveRegistration MBean is available.
If you want to enable a collective controller and its members to use the security TLSv1.2 protocol for the Secure Sockets Layer (SSL) context, see Setting up Liberty to run in SP800-131a. The server.xml files of the controller and members need ssl id elements and each host computer needs a server.env file with the JVM_ARGS=-Dhttps.protocols=TLSv1.2 statement in its ${wlp.install.dir}/etc directory.
- Create a server to act as the collective controller.
- Create and configure a member to join the collective.
The controller and members can be on separate hosts. In this example, the controller and member are on the same host.
- Create a member server.
wlp/bin/server create myMember
- Join the member.
Run the collective join command to join the server to the collective as a member.
The join command requires a network connection to the collective controller and an administrative user ID and password for performing MBean operations on the controller. Look at the server.xml file of the collective controller to find the values for the --host, --port, --user, and --password parameters. For --keystorePassword, set a value to use for the member keystore password, such as memberKSPassword. You can specify different --keystorePassword values for each server that is joined to the collective.
wlp/bin/collective join myMember --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword
The optional parameter --hostname specifies the host name to use for the system. Set --hostname only if the system has multiple host names or does not have its host name configured. If set, the value must match the defaultHostName variable that is defined in the server.xml file.
To write the output of this collective command to a file, instead of to a console screen, specify an optional --createConfigFile=outputFilePath 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 rpcUser, rpcUserPassword, and the operating system login user and password for the host on which the member server resides. If the member host is registered with the collective controller and the member host is not enabled for SSH, specify an optional --useHostCredentials parameter to enable the member to inherit 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 hostAuthInfo, the --useHostCredentials parameter, and connecting the collective controller to the server.
For information about these required parameters and about optional parameters, run collective help join at a command line.
- If prompted to accept the certificate chain, enter y (yes).
- Update the member server.xml file.
- Copy and paste output.
If the command wrote output to a console screen, proceed with the following steps:
- Copy output from the collective command and paste it into the member server.xml file.
- Modify the ports so that the server can open its HTTP ports. Ensure the member
server.xml sets unique HTTP port numbers on its host. For example, if the
member is on the same host as the collective controller, change the HTTP port
numbers:
Optionally, to access the member server from a remote client, also set host="*" in the httpEndpoint element.<httpEndpoint id="defaultHttpEndpoint" httpPort="9081" httpsPort="9444" />
In $WLP_USER_DIR/servers/myMember/server.xml, for example:<server description="member server"> <!-- Enable features --> <featureManager> <feature>jsp-2.2</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9081" httpsPort="9444" /> <featureManager> <feature>collectiveMember-1.0</feature> </featureManager> <!-- Define the host name for use by the collective. If the host name needs to be changed, the server should be removed from the collective and re-joined or re-replicated. --> <variable name="defaultHostName" value="memberHostname" />
<!-- Remote host authentication configuration --> <hostAuthInfo rpcUser="admin_user_id" rpcUserPassword="admin_user_password" /> <!-- Connection to the collective controller --> <collectiveMember controllerHost="controllerHostname" controllerPort="9443" /> <!-- clientAuthenticationSupported set to enable bidirectional trust --> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true" /> <!-- inbound (HTTPS) keystore --> <keyStore id="defaultKeyStore" password="yourPassword" location="${server.config.dir}/resources/security/key.jks" /> <!-- inbound (HTTPS) truststore --> <keyStore id="defaultTrustStore" password="yourPassword" location="${server.config.dir}/resources/security/trust.jks" /> <!-- server identity keystore --> <keyStore id="serverIdentity" password="yourPassword" location="${server.config.dir}/resources/collective/serverIdentity.jks" /> <!-- collective truststore --> <keyStore id="collectiveTrust" password="yourPassword" location="${server.config.dir}/resources/collective/collectiveTrust.jks" /> </server>
Add an include statement.
If you wrote the output to a file by using the --createConfigFile=outputFilePath parameter, add an include statement to $WLP_USER_DIR/servers/myMember/server.xml to include the outputted file, for example:<server description="member server"> <!-- Enable features --> <featureManager> <feature>jsp-2.2</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9081" httpsPort="9444" /> <include location="c:\wlp\usr\servers\myMember\collective-join-include.xml" /> </server>
- Copy and paste output.
If you did not specify --useHostCredentials in the join command and the member host is not enabled for SSH, set RPC credentials for hostAuthInfo in the member server.xml file or the outputted file. You can set RPC credentials for the member server in either of two ways:
- Set hostAuthInfo RPC user and password values. Set rpcUser to
an operating system login user ID for the host on which the member server resides, and set
rpcUserPassword to the operating system login password for the user ID. For
example, if you log into the member computer with user test1 and password
test1pwd, then change the hostAuthInfo element to the
following:
<hostAuthInfo rpcUser="test1" rpcUserPassword="test1pwd" />
- If the member host is registered with the collective controller, set
hostAuthInfo
useHostCredentials to true for the member server to inherit RPC
credentials from its
host.
<hostAuthInfo useHostCredentials="true" />
See Overriding Liberty server host information for information about hostAuthInfo settings and for an example that shows how to register a member host and run the join command with --useHostCredentials.
- Set hostAuthInfo RPC user and password values. Set rpcUser to
an operating system login user ID for the host on which the member server resides, and set
rpcUserPassword to the operating system login password for the user ID. For
example, if you log into the member computer with user test1 and password
test1pwd, then change the hostAuthInfo element to the
following:
- Start the member server.
wlp/bin/server start myMember
Figure 2. Simple collective - Verify that the member server started correctly and is publishing information to the
controller.
- Open an editor on the member messages log, $WLP_USER_DIR/servers/myMember/logs/messages.log.
- Look for the following messages in any
order:
CWWKX8112I: The server's host information was successfully published to the collective repository. CWWKX8114I: The server's paths were successfully published to the collective repository. CWWKX8116I: The server STARTED state was successfully published to the collective repository.
- Create a member server.
Subtopics
Configuring a Liberty collective using the developer tools
Using the Liberty Utilities menu in the developer tools, you can create a collective controller or join a collective.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=tagt_wlp_configure_collective
File name: tagt_wlp_configure_collective.html