Creating an Insight Server collective controller

You can manage multiple servers from a single management domain by using a collective controller. You must create and configure a collective controller server so that you can monitor all of the servers in your topology.

About this task

You must identify the servers that are part of the collective, and then create a collective controller server. Then, you set up security and user access and configure the remaining servers as members of the collective. The collective controller server receives data from the members within the collective.

If you plan to monitor a production topology, when you restart the system for example, configure the collective on a separate node. You can also configure the collective controller on a catalog host or a runtime host if it has extra capacity.

Important: The collective controller for Insight Server is configured to run in SP800-131a strict mode. The jvm.options file for each server in the collective (controller and members) must specify the -Dhttps.protocols=TLSv1.2 property.

Procedure

Create a server to act as the collective controller.
The following example shows the command to create a server that is named myController.
```
wlp/bin/server create myController --template=cisCollectiveController
```
When you use the cisCollectiveController template, the iaAdminCenter feature is automatically included in the feature manager list of the server.xml file.
Configure the collective controller:
1. Secure the communication between the controllers and the members:
  The following example shows the command to define a keystore password for myController server.
```
wlp/bin/collective create myController --keystorePassword=controllerKSPassword --createConfigFile=myPath/collective-create-include.xml
```
  The optional --createConfigFile parameter, writes the output to a file.
2. New in 8.10.2 Open myPath/collective-create-include.xml file, and replace the certificate extension .p12 by .jks. For each certificate add an attribute type with the value JKS.
```
<keyStore id="defaultKeyStore" 
          location="${server.config.dir}/resources/security/key.jks" 
          password="a password" 
          type="JKS"/>
```
3. For 8.10.1 and earlier: Open myPath/collective-create-include.xml file, and add sslProtocol="TLSv1.2" to the ssl configuration service object with id="defaultSSLConfig".
  The object must include the specific version for TLS:
```
<ssl id="defaultSSLConfig"
     keyStoreRef="defaultKeyStore"
     trustStoreRef="defaultTrustStore"
     clientAuthenticationSupported="true"
     sslProtocol="TLSv1.2"/>
```
4. Open the server.xml file of your collective controller server and add an include statement to locate the created configuration file.
  The following example shows the path to the configuration file collective-create-include.xml.
```
<include location="myPath/collective-create-include.xml"/>
```
5. New in 8.10.2 Change the default format of a certificate from p12 to jks, and convert the p12 certificates to jks.
  Go to the myPath/resources/security and myPath/resources/collective folders and run the keytool command.
```
keytool -importkeystore -srckeystore <certificat p12 filename> -srcstoretype pkcs12 -srcstorepass <password> -destkeystore <certificat jks filename> -deststorepass <password> -deststoretype jks
```
  For example, the following commands converts trust.p12 to trust.jks.
```
keytool -importkeystore -srckeystore trust.p12 -srcstoretype pkcs12 -srcstorepass MyPassword -destkeystore trust.jks -deststorepass MyPassword -deststoretype jks
```
6. For 8.10.1 and earlier: Verify that the ssl configuration service objects with id="controllerConnectionConfig" and id="memberConnectionConfig" are present in the server.xml file.
```
<ssl id="controllerConnectionConfig" sslProtocol="TLSv1.2"/>
<ssl id="memberConnectionConfig" sslProtocol="TLSv1.2"/>
```
7. Specify administrative user ID and password values for the collective:
```
<basicRegistry id="basic" realm="realm">
   <user name="adminUser" password="adminPassword"/>
</basicRegistry>

<administrator-role>
   <user>adminUser</user>
</administrator-role>
```
Add the ia_admincenter tag after the feature manager and define the user and password attributes.
The user attribute must refer to the runtime administrator user. For example, the following tag defines the user and password as "tester".
```
<ia_admincenter http.ssl.config="defaultSSLConfig" user="tester" password="tester"/>
```
Run the server start command to start the collective controller.
Verify that the collective controller server started successfully by checking the messages in <InstallDir>/runtime/wlp/user/servers/myController/logs/messages.log. You must see the following message:
```
CWWKX9003I: CollectiveRegistration MBean is available.
```

Configure the remaining servers to join the collective as members:

Run the collective command to join the servers to the collective as members.

The following example shows the command to add the myCatalog and myRuntime servers as members of myController server.


wlp/bin/collective join myCatalog --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword --createConfigFile=myPath/collective-catalog-include.xml
wlp/bin/collective join myRuntime --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword --createConfigFile=myPath/collective-container-include.xml

Type yes to trust the certificate when prompted.

Set the -Dhttps.protocols property to TLSv1.2 in the jvm.options file for each new member that includes the property.
```
-Dhttps.protocols=TLSv1.2
```
New in 8.10.2 Open myPath/collective-create-include.xml file, and replace the certificate extension .p12 by .jks. For each certificate add an attribute type with the value JKS.
```
<keyStore id="defaultKeyStore" 
          location="${server.config.dir}/resources/security/key.jks" 
          password="a password" 
          type="JKS"/>
```

For 8.10.1 and earlier: Open the myPath/collective-catalog-include.xml and myPath/collective-container-include.xml files, and add sslProtocol="TLSv1.2" to the ssl configuration service object with id="defaultSSLConfig".


<!-- clientAuthenticationSupported set to enable bidirectional trust --> 
<ssl id="defaultSSLConfig" 
     keyStoreRef="defaultKeyStore" 
     trustStoreRef="defaultTrustStore" 
     clientAuthenticationSupported="true" 
     sslProtocol="TLSv1.2"/>

Open the server.xml file of each new member, and replace the ssl id="defaultSSLConfig" tag with an include to the collective member configuration file. The following line includes the collective-catalog-include.xml file in the server.xml files:
```
<include location="myPath/collective-catalog-include.xml"/>
```

New in 8.10.2 Change the default format of a certificate from p12 to jks, and convert the p12 certificates to jks.

Go to the myPath/resources/security and myPath/resources/collective folders and run the keytool command.

keytool -importkeystore -srckeystore <certificat p12 filename> -srcstoretype pkcs12 -srcstorepass <password> -destkeystore <certificat jks filename> -deststorepass <password> -deststoretype jks

For example, the following commands converts trust.p12 to trust.jks.

keytool -importkeystore -srckeystore trust.p12 -srcstoretype pkcs12 -srcstorepass MyPassword -destkeystore trust.jks -deststorepass MyPassword -deststoretype jks

For 8.10.1 and earlier: Uncomment the ssl configuration service objects with id="controllerConnectionConfig" and id="memberConnectionConfig" in the server.xml file.
```
<ssl id="controllerConnectionConfig" sslProtocol="TLSv1.2"/>
<ssl id="memberConnectionConfig" sslProtocol="TLSv1.2"/>
```

Add the following feature to enable the monitoring of the runtime environment:

<feature>monitor-1.0</feature>

The server.xml file of the collective member must include both the monitor feature and the collective configuration file.


<server description="collective member server">
    <!-- Enable features -->
    <featureManager>
        <feature>jsp-2.3</feature>
        <feature>monitor-1.0</feature>
    </featureManager>
    <httpEndpoint id="defaultHttpEndpoint"
                  host="*"
                  httpPort="9081"
                  httpsPort="9444" />
    <include location="myPath/collective-catalog-include.xml"/>
</server>

Note: To avoid conflicts with other servers, make sure that the host and port parameters are set correctly in the bootstrap.properties.

Start the member servers.

The following example restarts a topology of seven servers.

wlp/bin/server start myCatalog01
wlp/bin/server start myCatalog02
wlp/bin/server start myCatalog03
wlp/bin/server start myRuntime01
wlp/bin/server start myRuntime02
wlp/bin/server start myInbound01
wlp/bin/server start myOutbound01

Verify that all collective members are recognized by the collective controller server. Open the log file <InstallDir>/runtime/wlp/user/servers/server_name/logs/messages.log.

Look for the following messages:

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.