Dynamic Routing command

The setup, genPluginCfg, and genKeystore collective command actions are used to generate the plug-in configuration and keystore files. The genPluginCfg collective command action is used any time after the initial setup to regenerate the plugin-cfg.xml file. For example, when the Dynamic Routing feature is enabled on a new controller or a new web server is added. The genKeystore collective command action is used to generate the keystore file. Each of the dynamic routing collective command actions support online help.

setup

The setup dynamicRouting command generates a keystore in PKCS12 or JKS format and one or more WebSphere plug-in configuration files. The keystore contains a personal certificate and both the memberRoot and controllerRoot signer certificates that allow secure communication between the WebSphere plug-in and the Dynamic Routing service. The same keystore is also be used to send HTTPS requests to applications in the Liberty collective members. The plug-in configuration file contains the <IntelligentManagement> stanza, which enables Intelligent Management in a WebSphere plug-in. The <IntelligentManagement> stanza contains one <ConnectorCluster> stanza that represents the collective. The <ConnectorCluster> stanza contains one <Connector> stanza for each controller where the Dynamic Routing feature is enabled.

To get command help, issue...

<Controller root>/bin/dynamicRouting help setup

Usage: dynamicRouting setup [options]

Options:

--host=name	Required. The host name of the target Collective Controller.
--password[=pwd]	Required. The password for the Administrator user for the target Collective Controller. If no value is defined we will be prompted.
--port=num	Required. The HTTPS port number of the target Collective Controller.
--user=name	Required. An Administrator user for the target Collective Controller.
--pluginInstallRoot=path	Required. Fully qualified path of the WebSphere plug-in root directory on the web server host.
--webServerNames=webServerName[,webServerName1]	Required. Comma separated names of the web servers for which WebSphere plug-in configuration files need to be generated.
--keystorePassword[=pwd]	Required. The password for the generated keystore. If specified and no value is defined we are prompted.
--keystoreType=type	Optional. The type of the generated keystore. Default type is JKS. Valid values are JKS and PKCS12.
--certificateSubject=DN	Optional. The DN for the generated SSL certificate. Default DN is CN=<<value of --user argument>>, OU=client, O=ibm, C=us

SSL certificates can be automatically trusted by setting the JVM property... com.ibm.websphere.dynamicRouting.utility.autoAcceptCertificates=true

The keystore generated by the setup and genKeystore commands is in JKS or PKCS12 format. It needs to be copied to a directory on the web server machine and converted to a CMS formatted store by running gskcmd. The CMS formatted store file (.kdb) must be moved to the directory <value of the --pluginInstallRoot argument>/config/<web server name>. The .rdb and .sth files must also be moved to the same directory.

Following is the output of the command when run with all required arguments:

./dynamicRouting setup 
                 --port=9444 
                 --host=controller1.acme.com 
                 --user=admin 
                 --password=foo 
                 --keystorePassword=keypass 
                 --pluginInstallRoot=/opt/HTTPServer_Plugins 
                 --webServerNames=webServer1,webServer2 
                 --keystoreType=PKCS12 

Generating WebSphere plug-in configuration files for web servers webServer1, webServer2

Auto-accepting the certificate chain for target server. 
Certificate subject DN: CN=admin, OU=controller1, O=ibm, C=us

Successfully completed MBean request to the controller. 
Successfully generated WebSphere plug-in configuration files plugin-cfg-webServer1.xml, plugin-cfg-webServer2.xml

Generating keystore for web servers webServer1, webServer2

Auto-accepting the certificate chain for target server. 
Certificate subject DN: CN=admin, OU=controller1, O=ibm, C=us

Successfully completed MBean request to the controller. 
Successfully generated keystore plugin-key.p12.

Generated WebSphere plug-in configuration files plugin-cfg-webServer1.xml, plugin-cfg-webServer2.xml for web servers webServer1, webServer2. 
Also generated keystore file plugin-key.p12 that enables secure communication between the Dynamic Routing service and clients.. 

The file contains personal certificate issued to DN CN=admin,OU=client,O=ibm,C=us. Ensure the admin user exists in the user registry and has a role assigned. 

If we are using quick start security, add the following line to the controller server.xml file and update the password:

   <quickStartSecurity user="admin" "password=""/>

If we are using basic registry, add the following lines to the controller server.xml file and update the password:

  <basicRegistry id="basic" realm="ibm/api">
  <user name="admin" password=""/>
  </basicRegistry>

  <administrator-role>
  <user>admin</user>
  </administrator-role/>

Copy the WebSphere plug-in configuration file to the directory specified in the WebSpherePluginConfig directive 
in the IBM HTTP Server httpd.conf file. Copy keystore file plugin-key.p12 to a directory on the web server host, 
and run "gskcmd" to convert the keystore to CMS format and to set personal certificate as the default. 
For example: 

gskcmd -keydb 
       -convert 
       -pw <<password>> 
       -db /tmp/plugin-key.p12 
       -old_format pkcs12 
       -target /tmp/plugin-key.kdb 
       -new_format cms 
       -stash gskcmd 
       -cert 
       -setdefault 
       -pw <<password>> 
       -db /tmp/plugin-key.kdb 
       -label default 

 Copy resulting /tmp/plugin-key.kdb, .sth, .rdb files to the directory /opt/HTTPServer_Plugins/config/webServer1

genPluginCfg

This action generates the plug-in configuration files. Each plug-in configuration file contains the <IntelligentManagement> stanza, which enables the Intelligent Management features of the plug-in. The <IntelligentManagement> stanza contains one <ConnectorCluster> stanza, that represents the collective. The <ConnectCluster> stanza contains one <Connector> stanza for each controller where Dynamic Routing feature is enabled. Comma-separated web server names are specified to the --webServerNames argument. For example, if --webServerNames=webServer1,webServer2 is specified , plugin-cfg-webServer1.xml and plugin-cfg-webServer2.xml files are generated.

To get online help, issue...

<Controller root>/bin/dynamicRouting help genPluginCfg

Usage: dynamicRouting genPluginCfg [options]

Options

--host=name	Required. The host name of the target Collective Controller.
--password[=pwd]	Required. The password for the Administrator user for the target Collective Controller. If no value is defined we will be prompted.
--port=num	Required. The HTTPS port number of the target Collective Controller.
--user=name	Required. An Administrator user for the target Collective Controller.
--pluginInstallRoot=path	Required. Fully qualified path of the WebSphere plug-in root directory on the web server host.
--webServerNames=webServerName[,webServerName1]	Required. Comma separated names of the web servers for which WebSphere plug-in configuration files need to be generated.

SSL certificates will automatically be trusted by setting the JVM property... com.ibm.websphere.dynamicRouting.utility.autoAcceptCertificates=true

Following is the output of the command when run with all required arguments:

./dynamicRouting genPluginCfg 
                     --port=9444 
                     --host=controller1.acme.com
                     --user=admin 
                     --password=foo 
                     --pluginInstallRoot=/opt/HTTPServer_Plugins
                     --webServerNames=webServer1 

This action generates the plug-in configuration files.
    
Generating WebSphere plug-in configuration file for web server webServer1

Auto-accepting the certificate chain for target server. 
Certificate subject DN: CN=admin, OU=controller1, O=ibm, C=us

Successfully completed MBean request to the controller. 
File /home/user1/Liberty/wlp/bin/plugin-cfg.xml exists. 
Saving to /home/user1/Liberty/wlp/bin/plugin-cfg.xml.old. 
Successfully generated WebSphere plug-in configuration file plugin-cfg.xml

Generated WebSphere plug-in configuration file plugin-cfg.xml for web server webServer1. 
Copy the WebSphere plug-in configuration file to the directory specified in the 
WebSpherePluginConfig directive in the IBM HTTP Server httpd.conf file.

genKeystore

This action generates a keystore in PKCS12 or JKS format. Use the --keystoreType action to specify the keystore format. Generation of the PKCS12 keystore is only supported when using IBM Java. The keystore contains a personal certificate and both the memberRoot and controllerRoot signer certificates that allow secure communication between the WebSphere plug-in and the Dynamic Routing service. The same keystore is also be used to send HTTPS requests to applications in the Liberty collective members.

To get online help, issue...

<Controller root>/bin/dynamicRouting help genKeystore

Usage: dynamicRouting genKeystore [options]

Options

--host=name	Required. The host name of the target Collective Controller.
--password[=pwd]	Required. The password for the Administrator user for the target Collective Controller. If no value is defined we will be prompted.
--port=num	Required. The HTTPS port number of the target Collective Controller.
--user=name	Specifies an Administrator user for the target Collective Controller. (Required)
--keystorePassword[=pwd]	Required. The password for the generated keystore. If specified and no value is defined, we are prompted.
--keystoreType=type	Optional. The type of the generated keystore. Default type is JKS. Valid values are JKS and PKCS12.
--certificateSubject=DN	Optional. The DN for the generated SSL certificate. Default DN is CN=<<value of --user argument>>, OU=client, O=ibm, C=us

SSL certificates will automatically be trusted by setting the JVM property... com.ibm.websphere.dynamicRouting.utility.autoAcceptCertificates=true

Following is the output of the command when run with all required arguments:

 ./dynamicRouting genKeystore --port=9444 
                              --host=contoller1.acme.com 
                              --user=admin 
                              --password=foo 
                              --keystoreType=PKCS12 
                              --keystorePassword 

Enter password --keystorePassword: 
Re-enter password --keystorePassword: 

Generating the plugin-key.p12 keystore... 

Auto-accepting the certificate chain for target server. 
Certificate subject DN: CN=admin, OU=controller1, O=ibm, C=us 

Successfully completed MBean request to the controller. 
File /home/user1/Liberty/wlp/bin/plugin-key.p12 exists. 
Saving to /home/user1/Liberty/wlp/bin/plugin-key.p12.old. 
Successfully generated keystore plugin-key.p12.

Generated keystore file plugin-key.p12 that enables secure communication between the Dynamic Routing service and clients..
The file contains a personal certificate issued to DN CN=admin,OU=client,O=ibm,C=us. Ensure the admin user exists in the user registry and has a role assigned. 

If we are using quick start security, add the following line to the controller server.xml file and update the password:

  <quickStartSecurity user="admin" password=""/>

If we are using basic registry, add the following lines to the controller server.xml files and update the password:

  <basicRegistry id="basic" realm="ibm/api">
  <user name="admin" password=""/>
  </basicRegistry>

  <administrator-role>
  <user>admin</user>
  </administrator-role/>

Copy the WebSphere plug-in configuration file to the directory specified in the WebSpherePluginConfig directive 
in the IBM HTTP Server httpd.conf file. Copy keystore file plugin-key.p12 to a directory on the web server host, 
and run "gskcmd" to convert the keystore to CMS format and to set personal certificate as the default. 
For example: 

gskcmd -keydb 
       -convert 
       -pw <<password>> 
       -db /tmp/plugin-key.p12 
       -old_format pkcs12 -target /tmp/plugin-key.kdb 
       -new_format cms -stash 
gskcmd -cert 
       -setdefault 
       -pw <<password>> 
       -db /tmp/plugin-key.kdb 
       -label default 

Copy resulting /tmp/plugin-key.kdb, .sth, .rdb files to the keyring directory specified in the plug-in configuration file.

Parent topic:

Set up Dynamic Routing for Liberty collectives

Concepts:

Liberty collective troubleshooting
File transfer in a Liberty collective
Collective architecture

Tasks:

Set up Dynamic Routing for Liberty collectives
Set up collectives
Configure a Liberty collective
Register host computers with a Liberty collective