Dynamic routing command

The dynamicRouting command actions are used to generate plug-in and keystore files.

Attention: Prior to version 19.0.0.3, the dynamicRouting command created a JKS keystore. With version 19.0.0.3 and later, the dynamicRouting command creates a PKCS12 keystore.

See Configure a Liberty collective.


setup

The dynamicRouting setup command generates keystore files in PKCS12 or JKS format and one or more WebSphere plug-in configuration files. The keystore files contain personal certificates and both the memberRoot and controllerRoot signer certificates that allow secure communication between the WebSphere plug-in and the Dynamic Routing service. The keystore files are also 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 in the collective where the Dynamic Routing feature is enabled.

To get command help, run: ${wlp.install.dir}/bin/dynamicRouting help setup

Description

The setup dynamicRouting command generates keystore files that contain personal certificates and signer certificates required to enable secure communication between the Dynamic Routing service and clients. It also generates a WebSphere plug-in configuration file with an <IntelligentManagement> stanza, which enables Intelligent Management in the WebSphere plug-in.

Usage

dynamicRouting setup [options]

Options

    --host=name

    Required for single-collective dynamic routing. The hostname of the target collective controller.

    Do not specify --host with the --collectives option.

    --password[=pwd]

    Required for single-collective dynamic routing. The password for the Administrator user for the target collective controller. If no value is defined, we are prompted.

    Do not specify --password with the --collectives option.

    --port=num

    Required for single-collective dynamic routing. The HTTPS port number of the target collective controller.

    Do not specify --port with the --collectives option.

    --user=name

    Required for single-collective dynamic routing. An Administrator user for the target collective controller.

    Do not specify --user with the --collectives option.

    --pluginInstallRoot=path

    Required. Fully qualified path of the WebSphere plug-in root directory on the web server host.

    --targetPath=directory|(full_file_path)

    Optional. By default, the plug-in configuration file is generated in the current directory. When webServerNames option has only one name, the file name is plugin-cfg.xml. Otherwise, the file name is plugin-cfg-webServerName.xml for each of the webServerNames options. We might either specify the directory name where the file must be placed, or specify a fully qualified file name. The new file replaces an existing file. The path must exist with one exception. The final path component can be the ${webServerName} variable. 

      // Existing "config" folder and default names for plug-in configuration files.
--targetPath='config/'

// The existing "config" folder. Each plug-in configuration file is created. The file name must end with ".xml".
--targetPath='config/${webServerName}.xml'

// Folders are created for each webServerName and default names for the plug-in configuration files.
--targetPath='config/${webServerName}/'

// Folders are created for each webServerName and plug-in configuration files named plugin-cfg.xml.
--targetPath='config/${webServerName}/plugin-cfg.xml'

    --logFileName=file_path

    Optional. A fully qualified path of the WebSphere plug-in log file on the web server host. By default, pluginInstallRoot/logs/webserverName/http_plugin.log. For Apache-based web servers, a path that begins with a pipe character is interpreted as an external piped logger. 

      --logFileName='|/opt/IHS905/bin/rotatelogs 
/opt/HTTPServer_Plugin/logs/${webServerName}/http_plugin.log.%Y-%m-%d-%H_%M_%S 60'

      --logFileName="|C:/IBM/HTTPServer/bin/rotatelogs.exe 
C:/IBM/WebSphere/Plugins/logs/${webServerName}/%Y-%m-%d-%H_%M_%S-http_plugin.log 60"

    --webServerNames=webServerName[,webServerName1]

    Required. Comma-separated names of the web servers for which WebSphere plug-in configuration files need to be generated.

    With the --collectives option, specify only one web server name. Run the command multiple times if we need more than one plugin-cfg.xml file. Complete processing on all generated files before we run the command again.

    --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 PKCS12. Valid values are PKCS12 and JKS.

    --certificateSubject=DN

    --certificateSubject=DN is no longer used and is ignored.

    See Dynamic Routing SSL Certificates.

    --collectives=user1[:password1]@host1:port1,user2[:password2]@host2:port2,…

    Required to generate artifacts for more than one collective. A list of collective controllers to connect to for dynamic routing information. Select one controller from each collective. All controllers must be started. Specify collectives in the format collective_user:user_password@collective_host:port with a comma that separates each collective. If a password is not specified, we are prompted.

    --autoAcceptCertificates

    Optional. Automatically trust SSL certificates during this command. Alternatively, SSL certificates can be automatically trusted by setting the JVM property com.ibm.websphere.collective.utility.autoAcceptCertificates to true.

    Note: The keystore generated by the setup and genKeystore commands is in PKCS12 or JKS 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 --pluginInstallRoot_argument_value/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 for a single collective: ./dynamicRouting setup --port=9444 --host=controller1.acme.com --user=admin --password=password --keystorePassword=keypass --pluginInstallRoot=/opt/HTTPServer_Plugins --webServerNames=webServer1,webServer2

    Generate 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 Generate keystore for web servers webServer1, webServer2 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. Copy the WebSphere plug-in configuration file to the directory specified in the WebSpherePluginConfig directive in the IBM HTTP Server httpd.conffile. 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 pcks12 -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/

Following is the output of the command when run with all required arguments for multiple collectives: ./dynamicRouting setup --collectives=admin:pw@controller1.acme.com:9443,admin:pw@controller2.acme.com:9443 --keystorePassword=keypass --pluginInstallRoot=/opt/HTTPServer_Plugins --webServerNames=webserver1

    Auto-accepting the certificate chain for target server. Certificate subject DN: CN=myuser.ibm.com, OU=mycontroller, O=ibm, C=us Generate WebSphere plug-in configuration file for web server webserver1 Successfully completed MBean request to the controller. Auto-accepting the certificate chain for target server. Certificate subject DN: CN=myuser.ibm.com, OU=mycontroller2, O=ibm, C=us Generate WebSphere plug-in configuration file for web server webserver1 Successfully completed MBean request to the controller. The merged plugin configuration document is created successfully = /extra/workspaces/CD-Liberty/build.image/wlp/bin/plugin-cfg.xml Generate keystore... Successfully completed MBean request to the controller. Successfully generated keystore plugin-key-default.p12. Generate keystore... Successfully completed MBean request to the controller. Successfully generated keystore plugin-key-collective2.p12. Generated WebSphere plug-in configuration file plugin-cfg.xml for web server webserver1. Also generated keystore files (plugin-key-default.p12, plugin-key-collective2.p12, plugin-key.p12) that enable secure communication between the Dynamic Routing service and clients. 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 files (plugin-key-default.p12, plugin-key-collective2.p12, 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/<<keystore file>> -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/IBM/WebSphere/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 for each collective. The <ConnectCluster> stanza contains one <Connector> stanza for each controller where Dynamic Routing feature is enabled. Comma-separated web server names are specified with the --webServerNames argument. For example, if --webServerNames=webServer1,webServer2 is specified, plugin-cfg-webServer1.xml and plugin-cfg-webServer2.xml files are generated.

With the --collectives option, specify only one web server name. Run the command multiple times if we need more than one plugin-cfg.xml file. Copy the generated plugin-cfg.xml file to the web server directory before we run the command again.

To get command help...

    ${wlp.install.dir}/bin/dynamicRouting help genPluginCfg

Description

Generates a WebSphere plug-in configuration file with an <IntelligentManagement> stanza that enables Intelligent Management in the WebSphere plug-in.

Usage

dynamicRouting genPluginCfg [options]

Options

    --host=name

    Required for single-collective dynamic routing. The hostname of the target collective controller.

    Do not specify --host with the --collectives option.

    --password[=pwd]

    Required for single-collective dynamic routing. The password for the Administrator user for the target collective controller. If no value is defined, we are prompted.

    Do not specify --password with the --collectives option.

    --port=num

    Required for single-collective dynamic routing. The HTTPS port number of the target collective controller.

    Do not specify --port with the --collectives option.

    --user=name

    Required for single-collective dynamic routing. An Administrator user for the target collective controller.

    Do not specify --user with the --collectives option.

    --pluginInstallRoot=path

    Required. The fully qualified path of the WebSphere plug-in root directory on the web server host.

    --targetPath=directory|(full_file_path)

    Optional. By default, the plug-in configuration file is generated in the current directory. When webServerNames option has only one name, the file name is plugin-cfg.xml. Otherwise, the file name is plugin-cfg-webServerName.xml for each of the webServerNames options. We might either specify the directory name where the file must be placed, or specify a fully qualified file name. The new file replaces an existing file. The path must exist with one exception. The final path component can be the ${webServerName} variable. 

      // Existing "config" folder and default names for plug-in configuration files.
--targetPath='config/' 

// The existing "config" folder. Each plug-in configuration file is created. The file name must end with ".xml".
--targetPath='config/${webServerName}.xml' 

// Folders are created for each webServerName and default names for the plug-in configuration files.
--targetPath='config/${webServerName}/' 

// Folders are created for each webServerName and plug-in configuration files named plugin-cfg.xml.
--targetPath='config/${webServerName}/plugin-cfg.xml'

    --logFileName=file_path

    Optional. A fully qualified path of the WebSphere plug-in log file on the web server host. By default, pluginInstallRoot/logs/webserverName/http_plugin.log. For Apache-based web servers, a path that begins with a pipe character is interpreted as an external piped logger. 

      --logFileName='|/opt/IHS905/bin/rotatelogs   
/opt/HTTPServer_Plugin/logs/${webServerName}/http_plugin.log.%Y-%m-%d-%H_%M_%S 60' 

      --logFileName="|C:/IBM/HTTPServer/bin/rotatelogs.exe 
C:/IBM/WebSphere/Plugins/logs/${webServerName}/%Y-%m-%d-%H_%M_%S-http_plugin.log 60"

    --webServerNames=webServerName[,webServerName1]

    Required. Comma-separated names of the web servers for which WebSphere plug-in configuration files need to be generated.

    With the --collectives option, specify only one web server name. Run the command multiple times if we need more than one plugin-cfg.xml file. Copy the generated plugin-cfg.xml file to the web server directory before we run the command again.

    --collectives=user1[:password1]@host1:port1,user2[:password2]@host2:port2,…

    Required to generate artifacts for more than one collective. A list of collective controllers to connect to for dynamic routing information. Select one controller from each collective. All controllers must be started. Specify collectives in the format collective_user:user_password@collective_host:port with a comma that separates each collective. If a password is not specified, we are prompted.

    --autoAcceptCertificates

    Optional. Automatically trust SSL certificates during this command. Alternatively, SSL certificates are automatically trusted by setting the JVM property com.ibm.websphere.collective.utility.autoAcceptCertificates to true.

Following is the output of the command when run with all required arguments for a single collective:

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

    Generate 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. Successfully generated WebSphere plug-in configuration file s plugin-cfg-webserver1.xml, plugin-cfg-webserver2.xml Generated WebSphere plug-in configurations plugin-cfg-webserver1.xml, plugin-cfg-webserver2.xml for web servers webserver1, webserver2.. Copy the WebSphere plug-in configuration file to the directory specified in the WebSpherePluginConfig directive in the IBM HTTP Server httpd.conf file.

For the --collectives option, the generated plugin-cfg.xml file contains information about all collectives.


genKeystore

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

To get command help, run: ${wlp.install.dir}/bin/dynamicRouting help genKeystore

Description

Generates a keystore containing a personal certificate and signer certificates that are required to enable secure communication between the Dynamic Routing service and clients.

Usage

dynamicRouting genKeystore [options]

Options

    --host=name

    Required for single-collective dynamic routing. The hostname of the target collective controller.

    Do not specify --host with the --collectives option.

    --password[=pwd]

    Required for single-collective dynamic routing. The password for the Administrator user for the target collective controller. If no value is defined, we are prompted.

    Do not specify --password with the --collectives option.

    --port=num

    Required for single-collective dynamic routing. The HTTPS port number of the target collective controller.

    Do not specify --port with the --collectives option.

    --user=name

    Required for single-collective dynamic routing. An Administrator user for the target collective controller.

    Do not specify --user with the --collectives option.

    --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 PKCS12. Valid values are PKCS12 and JKS.

    --certificateSubject=DN

    --certificateSubject=DN is no longer used and is ignored.

    See Dynamic Routing SSL Certificates.

    --collectives=user1[:password1]@host1:port1,user2[:password2]@host2:port2,…

    Required to generate artifacts for more than one collective. A list of collective controllers to connect to for dynamic routing information. Select one controller from each collective. All controllers must be started. Specify collectives in the format collective_user:user_password@collective_host:port with a comma that separates each collective. If a password is not specified, we are prompted.

    --autoAcceptCertificates

    Optional. Automatically trust SSL certificates during this command. Alternatively, SSL certificates are automatically trusted by setting the JVM property com.ibm.websphere.collective.utility.autoAcceptCertificates to true.

Following is the output of the command when run with all required arguments for a single collective:

./dynamicRouting genKeystore --port=9444 --host=controller1.acme.com --user=admin --password=password --keystorePassword

    Enter password --keystorePassword: Re-enter password --keystorePassword: Auto-accepting the certificate chain for target server. Certificate subject DN: CN=admin, OU=mycontroller, O=ibm, C=us Generate keystore... Successfully completed MBean request to the controller. Successfully generated keystore plugin-key.p12. Generated keystore file plugin-key.p12 that enables secure communication between the Dynamic Routing service and clients. If we are using Intelligent Management in the WebSphere plug-in, 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 WebSphere plug-in configuration file.

Following is the output of the command when run with all required arguments for multiple collectives: ./dynamicRouting genKeystore --collectives=admin:admin@localhost:9443,admin:admin@localhost:9446 --keystorePassword=webAS

    Generate keystore... Successfully completed MBean request to the controller. Successfully generated keystore plugin-key-default.p12. Generate keystore... Successfully completed MBean request to the controller. Successfully generated keystore plugin-key-collective2.p12. Generated keystore file plugin-key-default.p12, plugin-key-collective2.p12, plugin-key.p12 that enables secure communication between the Dynamic Routing service and clients. If we are using Intelligent Management in the WebSphere plug-in, copy keystore file plugin-key-default.p12, plugin-key-collective2.p12, 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-default.p12, plugin-key-collective2.p12, 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 WebSphere plug-in configuration file.