launchClient tool

Use the Java EE command line syntax for the launchClient tool for WebSphere Application Server.

Use the launchClient command from a node within a WAS ND environment. However, do not attempt to use the launchClient command from the Deployment Manager.

Important: All users who run commands from a specific profile must have authority to modify files created by other users that use the same profile. Otherwise, we might see a permission denied error in the log files. To avoid this issue, consider one of the following policies:

• (iSeries) Use specific profiles for distinct user authorities

• Use a separate installation for distinct user authorities
• Always use the same user for all of the commands that are run in a given profile

• Ensure that all users of a specific profile belong to the same group. In addition, ensure that each user of a group has the read and write authority to the files created by other members in the same profile.

The following example illustrates the command line invocation syntax for the launchClient tool:

launchClient [-profileName pName | -JVMOptions options | -help | -?] userapp [-CCname=value] [app args]

where

• userapp is the path and the name of the EAR file containing the application client.
• -CCname=value is the client container name-value pair parameter. See the client container parameters section, for supported name-value pair arguments.
• app args are arguments that pass to the application client.
• -profileName defines the profile of the Application Server process in a multi-profile installation. The -profileName option is not required for running in a single profile environment or in an Application Clients installation.

  The default is default_profile.

• -JVMOptions is a valid Java standard or nonstandard option string, except -cp or -classpath. Insert quotation marks around the string.
• -help, -? prints the usage information.

The first parameter must be -help, -? or contain no parameter at all. The -profileName pName and -JVMOptions options are optional parameters. If used, they must appear before the <userapp> parameter. All other parameters are optional and can appear in any order after the userapp parameter. The Java EE Application client run time ignores any optional parameters that do not begin with a -CC prefix and passes those parameters to the application client.

Client container parameters

Supported arguments include:

-CCadminConnectorHost

Host name of the server from which configuration information is retrieved.

The default is the value of the -CCBootstrapHost parameter or the value, localhost, if the -CCBootstrapHost parameter is not specified.

(iSeries) The default is the value of the -CCBootstrapHost parameter or the value, your.server.name, if the -CCBootstrapHost parameter is not specified.

-CCadminConnectorPort

Indicates the port number for the administrative client function to use. The default is 8880 for SOAP connections and 2809 for RMI connections.

-CCadminConnectorType

Specifies how the administrative client connects to the server. Specify RMI to use the RMI connection type, or specify SOAP to use the SOAP connection type. The default is SOAP.

-CCadminConnectorUser

Administrative clients use this user name when a server requires authentication. If the connection type is SOAP, and security is enabled on the server, this parameter is required.

-CCadminConnectorPassword

The password for the user name that the -CCadminConnectorUser parameter specifies.

-CCaltDD

The name of an alternate deployment descriptor file. This parameter is used with the -CCjar parameter to specify the deployment descriptor to use. Use this argument when a client JAR file is configured with more than one deployment descriptor. Set the value to null to use the client JAR file standard deployment descriptor.

-CCBootstrapHost

The name of the host server we want to connect to initially. The format is: your_server_of_choice.com

-CCBootstrapPort

The server port number. If we do not specify this argument, the WAS default value is used.

-CCclassLoaderMode

Class loader mode. If PARENT_LAST is specified, the class loader loads classes from the local class path before delegating the class loading to its parent. The classes loaded for the following are affected:

• Classes defined for the Java EE application client
• Resources defined in the Java EE application
• Classes specified on the manifest of the Java EE client JAR file
• Classes specified using the -CCclasspath option

If PARENT_LAST is not specified, then the default mode, PARENT_FIRST, causes the class loader to delegate the loading of classes to its parent class loader before attempting to load the class from its local class path.

-CCclasspath

A class path value. When we launch an application, the system class path is used. To access classes that are not in the EAR file or part of the system class paths, specify the appropriate class path here. Multiple paths can be concatenated.

-CCD

Use this option to have the WAS set the specified system property during initialization. Do not use the equals (=) character after the -CCD. For example: -CCDcom.ibm.test.property=testvalue. We can specify multiple -CCD parameters. The general format of this parameter is -CCD<property key>=<property value>. For example, -CCDI18NService.enable=true.

-CCdumpJavaNameSpace

Controls generation of a dump of the java: name space for the application that is launched, which can be used for debugging purposes. A value of true generates a dump in short format, and includes the name and object type for each binding. A value of long generates a dump in long format, and includes additional information for each binding over short format, such as the local object type and string representation of the local object. The default is false, and does not generate a dump.

-CCexitVM

Use this option to have the WAS call the System.exit() method after the client application completes. The default is false.

-CCinitonly

Initialize application client run time for ActiveX application clients without launching the client application. The default is false.

-CCjar

The name of the client Java Archive (JAR) file that resides within the EAR file for the application you wish to launch. Use this argument when we have multiple client JAR files in the EAR file.

-CCpropfile

Indicates the name of a properties file containing launchClient properties. Properties without the -CC prefix in the file, with the exception of the securityManager, securityMgrClass and securityMgrPolicy properties. See the following example: verbose=true.

-CCproviderURL

Provides bootstrap server information that the initial context factory can use to obtain an initial context. WAS initial context factory can use either a Common Object Request Broker Architecture (CORBA) object URL or an Internet Inter-ORB Protocol (IIOP) URL. CORBA object URLs are more flexible than IIOP URLs and are the recommended URL format to use. This value can contain more than one bootstrap server address. This feature can be used when attempting to obtain an initial context from a server cluster. We can specify bootstrap server addresses, for all servers in the cluster, in the URL. The operation will succeed if at least one of the servers is running, eliminating a single point of failure. The address list does not process in a particular order. For naming operations, this value overrides the -CCBootstrapHost and -CCBootstrapPort parameters. A CORBA object URL specifying multiple systems is illustrated in the following example:

-CCproviderURL=corbaloc:iiop:myserver.mycompany.com:9810,:mybackupserver.mycompany.com:2809

This value is mapped to the java.naming.provider.url system property.

-CCsecurityManager

Enable and runs the WAS with a security manager. The default is disable.

-CCsecurityMgrClass

Indicates the fully qualified name of a class that implements a security manager. Only use this argument if the -CCsecurityManager parameter is set to enable. The default is java.lang.SecurityManager.

-CCsecurityMgrPolicy

Indicates the name of a security manager policy file. Only use this argument if the -CCsecurityManager parameter is set to enable. When we enable this parameter, the java.security.policy system property is set. The default is app_server_root/properties/client.policy.

-CCsoapConnectorPort

The Simple Object Access Protocol (SOAP) connector port. If we do not specify this argument, the WAS default value is used.

-CCtrace

Use this option to obtain debug trace information. We might need this information when reporting a problem to IBM customer support. The default is false. For more information, read the Enabling trace topic.

-CCtracefile

Indicates the name of the file to which trace information is written. The default is to write output to the console.

-CCtraceMode

Trace format to use for tracing. If the valid value, basic, is not specified the default is advanced. Basic tracing format is a more compact form of tracing.

For more information on basic and advanced trace formatting, refer to the Interpreting trace output topic.

-CCverbose

This option displays additional information messages. The default is false.

If we are using an EJB client application with security enabled, edit the sas.client.props file, which is located in the profile_root/properties directory. Within the file, change the com.ibm.CORBA.loginSource value to none.

For more information on the sas.client.props utility, refer to the Manually encoding passwords in properties files and the PropFilePasswordEncoder command reference topics.

RMI connection with security. Used with the EJB and administrative client application.

Use Jacl:

wsadmin -conntype RMI -port  rmiportnumber -user userid 
-password password

(ZOS)

wsadmin.sh -conntype RMI -port  rmiportnumber -user userid 
-password password

Use Jython:

wsadmin -lang jython -conntype RMI -port  rmiportnumber -user userid 
-password password

(ZOS)

wsadmin.sh -lang jython -conntype RMI -port  rmiportnumber -user userid 
-password password

rmiportnumber for your connection displays in the administrative console as BOOTSTRAP_ADDRESS.

On the AIX, HP-UX, Linux, IBM i, Solaris, and z/OS operating systems, the use of -password option may result in security exposure as the password information becomes visible to the system status program, such as ps command, which can be invoked by other users to display all of the running processes. Do not use this option if security exposure is a concern. Instead, specify user and password information in the soap.client.props file for SOAP connector or sas.client.props file for RMI connector. The soap.client.props and sas.client.props files are located in the properties directory of our WAS profile.

If Kerberos (KRB5) is enabled for administrative authentication, the authentication target supports BasicAuth and KRB5. To use KRB5, update the sas.client.props, soap.client.props, and ipc.client.props files, according to the connector type.

When using Kerberos authentication, the user password does not flow across the wire. A one-way hash of password is used to identify the client.

The following examples demonstrate correct syntax.

(Windows)

launchClient c:\earfiles\myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2

(UNIX) (ZOS)

./launchClient.sh /usr/earfiles/myapp.ear -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2

(iSeries)

/QIBM/ProdData/WebSphere/AppServer/V61/Base/bin/launchClient /home/earfiles/myapp.ear
   -profileName myprofile -CCBootstrapHost=myWASServer -CCverbose=true app_parm1 app_parm2

Specify the directory for an expanded EAR file

(iSeries) Manually encoding passwords in properties files

(iSeries) PropFilePasswordEncoder command reference