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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	EnvCheck.GetDescriptors A subtask which returns the service descriptors and service destructors supplied by the service starter configuration constructed from args.
private class	EnvCheck.Pipe An I/O redirection pipe.

Field Summary

Fields

Modifier and Type	Field and Description
private String[]	args the command line arguments of the command being analyzed
private static ResourceBundle	bundle the localization resource bundle
(package private) String	classpath the classpath on the command line being checked
(package private) static String	combinedClasspath the classpath of the tool, including the plugins (updated in run)
private ServiceDescriptor[]	descriptors the ServiceDescriptors obtained from the starter config
(package private) String	jarToRun the executable JAR file on the command line being checked
private String	javaCmd the java command on the command line being checked
(package private) String	mainClass the main class on the command line being checked
(package private) String[]	options the options on the command line being checked (never null)
(package private) static ArrayList	pluginJarList the list of plugins supplied via the -plugin option
private ArrayList	pluginList the list of plugins instances to run
(package private) ClassLoader	pluginLoader the class loader for loading plugins
private boolean	printStackTraces flag controlling the display of stack traces in the output
(package private) Properties	properties the properties on the command line being checked (never null)

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.
private static void	findPlugins(String[] cmdLine) Search the command line for user supplied plugin definitions and place them in the internal plugin list.
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.
private String	getString(String key) Helper to print a localized string
private String	getString(String key, String val) Helper to print a localized string
private boolean	isPluginOption(String arg) Check whether arg is a plugin specific option.
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.
private void	loadConfiguration() Instantiate the service starter configuration if the command line being analyzed runs the service starter.
private void	loadPlugins() Load the plugin classes.
static void	main(String[] args) The entry point for the tool.
private void	parseArgs(String[] cmdLine) Parse the command line, identifying options for the tool and parsing the VM, system properties, options, JAR/main class and arguments for the command line being tested.
boolean	printStacks() Return the flag indicating whether to output stack traces that result from a check.
private void	run(String[] cmdLine) Perform the runtime checks.
private static void	usage() Output the usage message.

Methods inherited from class java.lang.Object

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

Field Detail

pluginList

private ArrayList pluginList

the list of plugins instances to run

printStackTraces

private boolean printStackTraces

flag controlling the display of stack traces in the output

args

private String[] args

the command line arguments of the command being analyzed

descriptors

private ServiceDescriptor[] descriptors

the ServiceDescriptors obtained from the starter config

bundle

private static ResourceBundle bundle

the localization resource bundle

javaCmd

private String javaCmd

the java command on the command line being checked

options

String[] options

the options on the command line being checked (never null)

properties

Properties properties

the properties on the command line being checked (never null)

classpath

String classpath

the classpath on the command line being checked

mainClass

String mainClass

the main class on the command line being checked

jarToRun

String jarToRun

the executable JAR file on the command line being checked

pluginJarList

static ArrayList pluginJarList

the list of plugins supplied via the -plugin option

pluginLoader

ClassLoader pluginLoader

the class loader for loading plugins

combinedClasspath

static String combinedClasspath

the classpath of the tool, including the plugins (updated in run)

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

usage

private static void usage()

Output the usage message.

getString

private String getString(String key)

Helper to print a localized string

Parameters:

key - the resource key

getString

private String getString(String key,
                         String val)

Helper to print a localized string

Parameters:

key - the resource key

val - the value parameter expected by the message

findPlugins

private static void findPlugins(String[] cmdLine)

Search the command line for user supplied plugin definitions and place them in the internal plugin list.

Parameters:

cmdLine - the original command line args

parseArgs

private void parseArgs(String[] cmdLine)

Parse the command line, identifying options for the tool and parsing the VM, system properties, options, JAR/main class and arguments for the command line being tested. The -plugin option is ignored by this parser since they must have been processed earlier.

Parameters:

cmdLine - the original 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

run

private void run(String[] cmdLine)

Perform the runtime checks. If any user plugins were supplied, construct a class loader capable of loading them and modify combinedClasspath to make the classes available to subtasks. Load the plugins and parse the command line. The plugins must be available to the parser so that plugin specific options can be checked for. Load the service starter configuration if the service starter is being invoked. Execute all of the plugin classes in the order loaded.

Parameters:

cmdLine - the original command line arguments

isPluginOption

private boolean isPluginOption(String arg)

Check whether arg is a plugin specific option. The isPluginOption method of every plugin is called in case an option is shared among multiple plugins.

Parameters:

arg - the argument to check

Returns:

true if any plugin's isPluginOption method returns true

loadConfiguration

private void loadConfiguration()

Instantiate the service starter configuration if the command line being analyzed runs the service starter. This is assumed to be true if the command line specified an executable JAR file named start.jar and if that file resides in the same directory as a file named jsk-platform.jar. Extract and save all of the service descriptors and service destructors from the configuration. If a ConfigurationException is thrown the tool will exit. If there are no ServiceDescriptor or ServiceDestructor entries supplied by the configuration a error is generated and a normal return is done. The instantiation of the configuration is done in a child process using the VM, properties, options and arguments supplied in the command line under test.

loadPlugins

private void loadPlugins()

Load the plugin classes. All of the resources named META-INF/services/org.apache.river.tool.envcheck.Plugin are read; each such resource is expected to contain a list of plugin class names, one per line (white space is trimmed). The corresponding classes are loaded and saved. Any other exceptions thrown while processing the plugin JAR files will cause the tool to exit.

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.