org.apache.river.tool.envcheck

Class EnvCheck

java.lang.Object

org.apache.river.tool.envcheck.EnvCheck

public class EnvCheck
extends Object

Tool used to perform validity checks on the run-time environment of a client or service. The output of this tool is a report; command-line options control the verbosity and severity level at which report entries are generated. A simple plugin architecture is implemented; a set of plugins implementing a variety of checks is bundled with the tool, and support is provided to allow additional plugins to be supplied by the user.

The following items are discussed below:

• Running the Tool
• Processing Options
• Examples
• Bundled Plugins

Running the Tool

This tool primarily validates the system properties and configuration files used when starting the target client or service. This is accomplished by providing the unmodified command line for launching the component as arguments to the tool. Thus, for a service designed to be run by the service starter having the hypothetical original command line:

 java -Djava.security.policy=my_policy \
      -jar install_dir/lib/start.jar mystart.config
 

the simplest invocation of the tool would be:

 java -jar install_dir/lib/envcheck.jar \
      java -Djava.security.policy=my_policy \
           -jar install_dir/lib/start.jar mystart.config
 

Note that the entire command line, including the java command, is supplied as arguments to the tool. The java command used to run the tool may be different than the java command invoked by the command line under test. The first token in the command line being analyzed must not begin with a '-' and must end with the string "java".

Processing Options

-traces

The implementation of a validity check may detect success or failure by handling an expected exception. By default, an error message will be generated in these cases, but the stack trace will be inhibited. This option is a hint that stack traces are desired. It is the responsibility of the individual plugin implementation to honor this option.

-explain

By default, the output of a validity check will be a short message with enough detail to allow a knowledgeable user to interpret it; however, it may not be understandable to a novice user. The -explain option is a hint that may result in the generation of additional output describing the purpose and context of the check. An explanation is output the first time its associated message is output, and is not repeated. It is the responsibility of the individual plugin implementation to honor this option.

-level info|warning|error

The tool supports three severity levels for message generation.

info

'success' messages or other non-failure oriented configuration data

warning

a condition or value has been detected that is 'legal', but which could result in unintended behavior. An example is the use of localhost in a codebase annotation.

error

a condition has been detected that is likely due to an error on the command line or in a configuration file. An example is assigning the value of a non-existant file name to the java.util.logging.config.file system property.

This option is used to set the level at which message records are generated. The default value is warning.

-plugin file

Identifies a JAR file containing user supplied plugins that will be run after the standard plugins are run. All of the necessary support classes and resources required to support the plugins must be included in this file. The file must also include a resource named META-INF/services/org.apache.river.tool.envcheck.Plugin, which contains the class names of the plugins to run listed one per line. Every class listed must implement the org.apache.river.tool.envcheck.Plugin interface. This option may be supplied zero or more times.

-security

A plugin specific option that is recognized by one of the bundled plugins. Specifying this option will activate a number of JAAS and JSSE checks. User supplied plugins wishing to recognize this option must implement the isPlugOption method of the Plugin interface.

Examples

The following example will analyze a command line used to start a user service. The command being analyzed defines a classpath and two system properties, and names a class containing a main method:

 java -jar install_dir/lib/envcheck.jar -level info -explain -traces \
      java -cp mylib_dir/myservice.jar:/jini/lib/jsk-platform.jar \
           -Djava.security.policy=my_policy \
           -Djava.server.rmi.codebase=http://myhost/myservice-dl.jar \
           myservice.MyServiceImpl
 

In this case, the tool is limited to performing validity checks on the classpath, policy, and codebase values identified by the system properties and options provided on the service command line. The -level, -explain, and -traces options supplied will result in the most verbose output possible from the tool.

The following example will analyze a command line used to start reggie using the service starter. The command being analyzed uses a policy and service starter configuration located in the working directory:

 java -jar install_dir/lib/envcheck.jar -level error \
      java -Djava.security.policy=my_starterpolicy \
           -jar install_dir/lib/start.jar reggie.config
 

The tool can perform many more checks in this case because the bundled plugins include built-in knowledge about the service starter and its public configuration entries. The tool options used will minimize the output produced by the tool.

Bundled Plugins

A set of plugins are loaded automatically by the tool to perform some basic analysis.

If the command line being analyzed invokes the service starter, the tool will create a Configuration from the arguments of the command line being analyzed. Failure to create the Configuration will result in termination of the tool, otherwise the org.apache.river.start.ServiceDescriptors provided by the Configuration are examined. The following checks are done for each ServiceDescriptor:

• Verify that the getPolicy method returns a reference to a policy file that is valid and accessible
• Check whether that policy grants AllPermissions to all protection domains

The following checks are done for each NonActivatableServiceDescriptor and each SharedActivatableServiceDescriptor

• Verify that calling getServerConfigArgs does not return null or an empty array
• Verify that a Configuration can be constructed from those args
• Verify that any entry in that Configuration named initialLookupGroups does not have a value of ALL_GROUPS
• Verify that the export codebase is defined. For each component in the export codebase:
  • Verify that the URL is not malformed
  • If it is an HTTPMD URL, verify that the necessary protocol handler is installed
  • Check that domain names are fully qualified
  • Warn if an md5 HTTPMD URL is being used (md5 has a security hole)
  • Verify that the host name in the URL can be resolved
  • Verify that the host name does not resolve to a loopback address
  • Verify that it's possible to open a connection using the URL
• If the -security option was specified:
  • Verify that javax.net.ssl.trustStore is defined and that the trust store it references is accessible
  • Check whether org.apache.river.discovery.x500.trustStore is defined, and if so that the trust store it references is accessible
  • Check whether javax.net.ssl.keyStore is defined, and if so that the key store it references is accessible
  • Verify that a login configuration is defined and that it is accessible and syntactically correct

The following checks are done for each SharedActivatableServiceDescriptor:

• Verify that any entry in that Configuration named persistenceDirectory refers to either an empty directory or a non-existant directory

The following checks are done for each SharedActivationGroupDescriptor:

• Verify that the activation system is running
• Verify that the virtual machine (VM) created by that command is at least version 1.4
• Verify that jsk-policy.jar is loaded from the extensions directory
• Verify that jsk-platform.jar is in the classpath
• If java.util.logging.config.file is defined in the properties returned by calling getServerProperties then verify that the file it references is accessible

A subset of these checks are performed on the command line being analyzed:

• Codebase/URL checks based on the value of java.rmi.server.codebase
• Policy file checks based on the value of java.security.policy
• Check for jsk-policy being loaded by the extension class loader
• Check for jsk-platform in the classpath
• Security checks if -security was specified
• The logging config file check

In all cases, check that the local host name does not resolve to the loopback address.

Constructor Summary

Constructors

Constructor and Description
EnvCheck()

Method Summary

Modifier and Type	Method and Description
String	checkFile(String prop, String desc) Check for the existence of a file identified by a property supplied on the command line being analyzed.
String[]	getArgs() Get the command line arguments of the command being analyzed.
String	getClasspath() Get the classpath provided by the command line being analyzed.
ServiceDescriptor[]	getDescriptors() Return the ServiceDescriptors contained in the service starter configuration.
SharedActivationGroupDescriptor	getGroupDescriptor() Return the SharedActivationGroupDescriptor contained in the service starter configuration.
String	getJarToRun() Return the name of the executable JAR file supplied on the command line being analyzed.
String	getJavaCmd() Return the java command for the command line being analyzed.
Properties	getProperties() Return a copy of the properties that were specified on the command line being analyzed.
String	getProperty(String key) Return a property value that was specified on the command line being analyzed.
Object	launch(NonActivatableServiceDescriptor d, SharedActivationGroupDescriptor gd, String taskName) Launch a subtask using the environment defined by the given service descriptors.
Object	launch(NonActivatableServiceDescriptor d, SharedActivationGroupDescriptor gd, String taskName, String[] args) Launch a subtask using the environment defined by the given service descriptors.
Object	launch(String task) Launch a child VM using the java command, properties, and options supplied on the command line.
Object	launch(String javaCmd, Properties props, String[] opts, String[] args) Launch a subtask VM using the java command given by javaCmd.
Object	launch(String task, String[] args) Launch a child VM using the java command, properties, and options supplied on the command line being analyzed.
static void	main(String[] args) The entry point for the tool.
boolean	printStacks() Return the flag indicating whether to output stack traces that result from a check.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EnvCheck

public EnvCheck()

Method Detail

main

public static void main(String[] args)

The entry point for the tool. The localization resource bundle is located, the plugins are loaded, and the checks are performed. The system property java.protocol.handler.pkgs for the tool VM is set to net.jini.url to ensure that the tool can manipulate HTTPMD URLs.

Parameters:

args - the command line arguments

getDescriptors

public ServiceDescriptor[] getDescriptors()

Return the ServiceDescriptors contained in the service starter configuration. If the command being analyzed does not invoke the service starter, a zero-length array will be returned.

Returns:

the descriptors in the starter configuration or an empty array

getGroupDescriptor

public SharedActivationGroupDescriptor getGroupDescriptor()

Return the SharedActivationGroupDescriptor contained in the service starter configuration. Returns null if there is no such descriptor, or if the command being analyzed does not invoke the service starter.

Returns:

the SharedActivationGroupDescriptor or null

getArgs

public String[] getArgs()

Get the command line arguments of the command being analyzed.

Returns:

the args

printStacks

public boolean printStacks()

Return the flag indicating whether to output stack traces that result from a check.

launch

public Object launch(String task,
                     String[] args)

Launch a child VM using the java command, properties, and options supplied on the command line being analyzed. If an executable JAR file was specified, the classpath of the child VM consists of the JAR file name augmented with the classpath of the tool and plugins. If a main class was specified, the classpath of the child VM consists of the -cp/-classpath option value of the command line being analyzed augmented with the classpath of the tool and plugins.

Parameters:

task - the class name of the task to launch, which must implement the SubVMTask interface

args - the arguments to pass to the main method of the task

Returns:

the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

launch

public Object launch(String task)

Launch a child VM using the java command, properties, and options supplied on the command line. If an executable JAR file was specified, the classpath of the child VM consists of the JAR file name augmented with the classpath of the tool and plugins. If a main class was specified, the classpath of the child VM consists of the -cp/-classpath option value of the command line being analyzed augmented with the classpath of the tool and plugins.

Parameters:

task - the class name of the task to launch, which must implement the SubVMTask interface

Returns:

the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

getProperty

public String getProperty(String key)

Return a property value that was specified on the command line being analyzed. Only properties explicitly defined on the command line will resolve to a value.

Parameters:

key - the name of the property

Returns:

the property value, or null if undefined

getProperties

public Properties getProperties()

Return a copy of the properties that were specified on the command line being analyzed. The caller may modify the returned properties object.

Returns:

the properties, which may be empty

launch

public Object launch(String javaCmd,
                     Properties props,
                     String[] opts,
                     String[] args)

Launch a subtask VM using the java command given by javaCmd. If javaCmd is null, the command to run is derived from the value of the java.home property of the tool VM. The first value in args must name a class that implements the SubVMTask interface. The props and opts arrays must contain fully formatted command line values for properties and options (i.e. "-Dfoo=bar" or "-opt"). opts must include a -cp or -classpath option and its value must completely specify the classpath required to run the subtask.

Parameters:

javaCmd - the java command to execute, or null to create another instance of the tool VM

props - properties to define, which may be null or empty

opts - options to define, which must include a classpath definition

args - arguments to pass to the child VM

Returns:

the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

Throws:

IllegalArgumentException - if opts does not include a classpath definition, or if args[0] does not contain the name of a class that implements SubVMTask

launch

public Object launch(NonActivatableServiceDescriptor d,
                     SharedActivationGroupDescriptor gd,
                     String taskName)

Launch a subtask using the environment defined by the given service descriptors. Calling this method is equivalent to calling launch(d, g, taskName, null).

Parameters:

d - the services descriptor, which may be null

gd - the group descriptor, which may be null

taskName - the name of the subtask to run

Returns:

the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

launch

public Object launch(NonActivatableServiceDescriptor d,
                     SharedActivationGroupDescriptor gd,
                     String taskName,
                     String[] args)

Launch a subtask using the environment defined by the given service descriptors.

If d and gd are both null, then calling this method is equivalent to calling launch(taskName, args).

If d is null and gd is non-null then the properties are taken from gd.getServerProperties() and the java.security.policy property is added or replaced with the value of gd.getPolicy(). The options are taken from gd.getServerOptions(), but any -cp/-classpath option is discarded; a -cp option is added that is the value of gd.getClasspath() augmented with the classpath of the tool and plugins. If gd.getServerCommand() is non-null, its value is used to invoke the child VM; otherwise the java command of the command line being analyzed is used. The arguments passed to the child VM consist of an array whose first element is taskName and whose remaining elements are taken from args.

If d is not null, but gd is null, then if d is an instance of SharedActivatableServiceDescriptor an IllegalArgumentException is thrown. Otherwise the properties and options are taken from the command line being analyzed. The java.security.policy property is added or replaced using the value of d.getPolicy(). The -cp/-classpath option is replaced with the value of d.getImportCodebase() augmented with the classpath of the tool and plugins. The arguments passed to the child VM consist of taskName followed by args if args is non-null, or followed by d.getServerConfigArgs() otherwise. The VM is invoked using the java command of the command line being analyzed.

if d and gd are both non-null then if d is an instance of SharedActivatableServiceDescriptor then the properties, options, and java command are taken from gd.getServerProperties(), gd.getServerOptions(), and gd.getServerCommand(); however, if the value of gd.getServerCommand() is null, the java command is taken from the command line being analysed. If d is not an instance of SharedActivatableServiceDescriptor then the properties, options, and java command are taken from the command line being analyzed. In all cases the java.security.policy property is added or replaced using the value of d.getPolicy(). The -cp/-classpath option is added or replaced with the value of d.getImportCodebase() augmented with the value of the classpath of the tool and plugins. The arguments passed to the child VM consist of taskName followed by args if args is non-null, or followed by d.getServerConfigArgs() otherwise.

Parameters:

d - the service descriptor, which may be null

gd - the group descriptor, which may be null

taskName - the name of the subtask to run

args - the arguments to pass to the child VM, which may be null

Returns:

the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

getJavaCmd

public String getJavaCmd()

Return the java command for the command line being analyzed.

Returns:

the java command

checkFile

public String checkFile(String prop,
                        String desc)

Check for the existence of a file identified by a property supplied on the command line being analyzed.

Parameters:

prop - the name of the property

desc - a brief description of the file

Returns:

the property value, or null if undefined

getJarToRun

public String getJarToRun()

Return the name of the executable JAR file supplied on the command line being analyzed.

Returns:

the JAR file name, or null if the command line did not specify one.

getClasspath

public String getClasspath()

Get the classpath provided by the command line being analyzed. If getJarToRun() returns a non-null value then its value is returned. Otherwise the value supplied by the command line -cp/-classpath option is returned.

Returns:

the classpath supplied on the command line being analyzed.