System Administration Commands smreg(1M)
NAME
smreg - register objects for the Sun Web Console
SYNOPSIS
/usr/sbin/smreg [-h | --help] subcommand options
DESCRIPTION
The smreg utility is a Command Line Interface (CLI) -based
registration mechanism to manage the information in theconsole's registration databases. smreg adds management web
applications, libraries, and configuration information to registration databases. It also validates an application's deployment descriptor to make sure it has certain required tags that enable the application to run in the console.smreg has four subcommands: add, remove, check, and list.
SUBCOMMANDS The following subcommands are supported: add Registers objects of a specified type. If the object is already registered, any new registrationwill replace the previous registration. The appli-
cation registration descriptor app.xml is verified to ensure that meets some initial requirements. The format of the add subcommand is:add -a [-x context] path
add -d path
add -l [-L] [-n lib_name] -s ALL | app_name path
add -m -b behavior [-s service] -o name=value ...
moduleadd -p [-c | -e] name=value ...
add -h
remove Unregisters named objects. The format of the remove subcommand is:remove -a app_name | context
remove -n app_name | -d path
SunOS 5.11 Last change: 8 Mar 2005 1
System Administration Commands smreg(1M)
remove -l -s ALL | app_name lib_name
remove -m [-s service] module
remove -p [-c | -e] name ...
remove -h
check Check an application. The check subcommand parses the application's web.xml file to make sure that it has the filterand filter-mapping tags. The console requires
these tags to run an application. The required tags are as follows:
SessionManagerFilter com.sun.management.services.session.AppSessionManagerFilter
ignore-paths images/*
SessionManagerFilter
/* Elements in the web.xml file must appear in a fixed order. For example, the filter tag must
appear in the web.xml file before the filter-
mapping tag. For more information, see the Java Servlet Specifications 2.3.The smreg check subcommand parses the
application's web.xml file, checking for the existence of these tags and for the correct tagcontent. That is, the embedded filter-name tag
content must be SessionManagerFilter, and thefilter-class tag content must be:
com.sun.management.services.session.AppSessionManagerFilterSunOS 5.11 Last change: 8 Mar 2005 2
System Administration Commands smreg(1M)
If the tag content is not correct, the application will not be registered. If the tags are not included in the application's web.xml file, the script prints to standard output a corrected version the web.xml file, with the tags embedded in the correct location. Becausemultiple filter tags are allowed in a file, smreg
also includes the new tags as the first in a series. The format for the check subcommand is:check [-d] path
check -h
The -d is used strictly to maintain interface com-
patibility with 1.0-based application packages,
and is otherwise ignored. list Prints list of registered objects. The format of the list subcommand is:list [-a | -l | -m | -p]
If no options are specified, then all registered objects are listed. OPTIONS The following options are supported:-a | --application
Object type is an application.See app_name under ARGUMENTS for more information on the
name by which an application is registered.-b behavior | --behavior behavior
A flag value that controls behavior as authentication proceeds down the login module stack. See behavior under ARGUMENTS for more information on values allowed.-c name=value ... | --configuration name=value ...
SunOS 5.11 Last change: 8 Mar 2005 3
System Administration Commands smreg(1M)
When used with -p, this option specifies that the pro-
perty arguments are server configuration properties. The name=value pairs are written to a datastore, to be read during the next server startup. Any property name can be created, but only those recognized by the server will have any effect.-d path | --directory path
This option is deprecated and is preserved only for com-
patibility with existing 1.0-based applications. It will
be removed in a future release. When used with the "add" subcommand, it has the sameeffect as "-a".
When used with the "remove" subcommand, path is the pathto the original installation location of the applica-
tion. This path will be mapped to the registeredapp_name so that the application can be unregistered
using "smreg remove -a app_name". When used with the
"check" subcommand, -d is ignored. The -d option is
preserved strictly to maintain 1.0 interface compatibil-
ity.-e name=value ... | --environment name=value ...
When used with -p, this option specifies that the pro-
perty arguments are server environment properties. Thename=value pairs are placed into the server's environ-
ment during the next server startup. Any environment name can be created, and is available for use by any application.-h | -? | --help
Displays command and subcommand usage information.-l | --library
Object type is a library JAR file. Library JAR files that are not installed in the same location as the application, or are not registered atthe same time as the application (for example, localiza-
tion JAR files), can be registered separately by usingthis option. See lib_name under ARGUMENTS for more
information on the name by which a library isSunOS 5.11 Last change: 8 Mar 2005 4
System Administration Commands smreg(1M)
registered. A library can be registered with global scope so that itcan be used by all applications, by specifying the -s
ALL option. A library can be registered so that it may only be used by a specific application, by specifyingthe -s app_name option. If a library must be shared by
more than one application but not globally, then a seperate registration is required for each instance in which the library is to be shared.-L | --link
Specifies to register the library JAR as a symbolic link rather than as a file copy. This option is ignored on operating systems which do not support symbolic links.-m | --module
Object type is a login module.-n [app_name | lib_name] | --name [app_name | lib_name]
When used with the "add -l" subcommand, specifies the
name by which an application or library is known to the registration service. When used with the "remove" subcommand, specifies the name by which an application is known to the registryservice. "remove -n" is deprecated and is preserved only
for compatibility with existing 1.0-based applications.
It will be removed in a future release.See app_name under ARGUMENTS for more information on the
name by which an application is registered.See lib_name under ARGUMENTS for more information on the
name by which a library is registered.-o name=value ... | --option name=value ...
Options specific to the login module implementation. The options are specified as name=value pairs, each precededby the -o option. Values containing more than one word
must be enclosed in double quotes (").SunOS 5.11 Last change: 8 Mar 2005 5
System Administration Commands smreg(1M)
-p | --properties
Object type is properties. This option is specified foruse with either -c (for configuration properties) or -e
(for environment properties). If neither -c nor -e are
specified, then -c is assumed.
See the PROPERTIES section for information on specific configuration properties that are useful to a system administrator.-s [ALL | app_name] | --scope [ALL | app_name]
When used with -l, specifies the sharing scope for the
library being registered. A scope of ALL makes the library available to all applications. A scope ofapp_name makes the library available only to the appli-
cation already registered as app_name. See app_name
under ARGUMENTS for more information on the name by which an application is registered.-s service | --scope service
When used with -m, specifies the login service scope for
the module. If not specified, the default is ConsoleLo-
gin, which is the web console's browser login service.-V | --version
Display console version information.-x context | --context context
The deployment context path for an application. This option is to be used to register applications built with the SDK version 2.1 or greater. If not provided and the application is unpacked, the context is the parentdirectory of the application's WEB-INF directory. This
option is ignored when registering applications built with an SDK version prior to 2.1. ARGUMENTS The subcommand arguments are:app_name The unique name of the registered application in
the format of pluginName_version, where plugin-
Name and version are tags extracted from theSunOS 5.11 Last change: 8 Mar 2005 6
System Administration Commands smreg(1M)
application's registration descriptor, app.xml. All subsequent references to the registered application must then be made by using this registered name.path When used with the "add -a", "add -d", or
"remove -d" subcommands, the full directory path
where the application has been installed. When used with the check subcommand, if it is a directory then it is the full directory path where the application has been installed. If itis a file, then it is the path to a web.xml-
compliant file.When used with the "add -l" subcommand, the full
path where the library JAR file is installed.behavior Specifies the authentication behavior. The pos-
sible values are: required, requisite, suffi-
cient, or optional.lib_name The name by which a library JAR file is known to
the registration service. By default, libraries will be registered using the basename of the path to the library. This default value can beoverridden by using the -n lib_name option to
register the object by using a globally unique name.module The fully-qualified class name of the module.
For example: com.sun.management.services.authentication.MyLoginModule PROPERTIES While the list of configuration properties is unlimitted,certain properties that may be useful to a system adminis-
trator are mentioned here: session.timeout.value This is the time interval of no user activity after which the user will be prompted to log in again to continue. The default session timeout is 15 minutes. Setting thevalue to -1 means there is no
timeout. To set the session timeout to 5 minutes, run the followingSunOS 5.11 Last change: 8 Mar 2005 7
System Administration Commands smreg(1M)
command:# smreg add -p -c session.timeout.value=5
debug.trace.path This is the directory where log files are created. The default is /var/log/webconsole. To set the directory to /tmp/logs, run the following command:# smreg add -p -c debug.trace.path=/tmp/logs
java.home This is the path to the Java Development Kit (JDK) that will be used to run the web server. The default is /usr/j2se on Solaris and /usr/java/j2sdk1.4.2 on Linux. To set the path to /usr/jdk142, run the following command:# smreg add -p -c java.home=/usr/jdk142
java.options This contains the options for con-
figuring the Java Virtual machine(JVM). The defaults are "-server
-XX:+BackgroundCompilation". To
include setting the initial Javaheap size to 64MB, run the follow-
ing command:# smreg add -p -c java.options="-Xms64 \
-server -XX:+BackgroundCompilation"
EXAMPLES
Example 1 Registering an unpacked Application The following command registers an application which has been installed unpacked in /opt/myCompany/myApp:SunOS 5.11 Last change: 8 Mar 2005 8
System Administration Commands smreg(1M)
# smreg add -a /opt/myCompany/myApp
Example 2 Unregistering an Application The following command unregisters an application previousregistered with an app_name of com.myCompany.myApp_1.2:
# smreg remove -a com.myCompany.myApp_1.2
Example 3 Registering a Library JAR File with Global Scope The following command registers myLibrary.jar, installed in/opt/myCompany/MyApp, as com_myCompany_myLibrary.jar for use
by all applications:# smreg add -l -n com_myCompany_myLibrary.jar \
-s ALL /opt/myCompany/MyApp/myLibrary.jar
Example 4 Registering a Library JAR file with a Specific Application Scope The following command registers Utilities.jar, installed in/opt/SomeCompany/lib, with the application already
registered as com.myCompany.myApp_1.2:
# smreg add -l -s com.myCompany.myApp_1.2 \
/opt/SomeCompany/lib/Utilities.jar Example 5 Unregister a Library JAR File from Global Scope The following command unregisters
com_myCompany_myLibrary.jar from global scope so that it is
not available to applications:# smreg remove -l -s ALL com_myCompany_myLibrary.jar
SunOS 5.11 Last change: 8 Mar 2005 9
System Administration Commands smreg(1M)
Example 6 Unregister a Library JAR File from a Specific Application Scope The following command unregisters Utilities.jar so that it is not available to the registered applicationcom.myCompany.myApp_1.2:
# smreg remove -l -s com.myCompany.myApp_1.2 Utilities.jar
Example 7 Checking that Application's Deployment Descriptor Meets Sun Web Console Guidelines Either of the following commands to check to see if thedeployment descriptor located at /opt/myCompany/myApp/WEB-
INF/lib/web.xml meets the Sun Web Console guideline:# smreg check /opt/myCompany/myApp# smreg check /opt/myCompany/myApp/WEB-INF/lib/web.xm
Example 8 Registering an Environment Property The following command registers the environment property name GREETING with value "Hello World" and the name FOO withthe value "bar" so that they appear in the server's environ-
ment and are available to any application:# smreg add -p -e GREETING="Hello World" FOO=bar
Example 9 Unregistering an Environment Property The following command unregisters the environment property names GREETING and FOO so that they no longer appear in theserver's environment and are not available to any applica-
tion:# smreg remove -p -e GREETING FOO
SunOS 5.11 Last change: 8 Mar 2005 10
System Administration Commands smreg(1M)
Example 10 Registering a Login Module The following command registers the module class com.sun.management.services.authentication.myLoginModule with "requisite" behavior and a commandPath argument:# smreg add -m -b requisite \
-o commandPath="/usr/lib/webconsole" \
com.sun.management.services.authentication.myLoginModule Example 11 Unregistering a Login Module The following command unregisters the module class com.sun.management.services.authentication.myLoginModule:# smreg remove -m com.sun.management.services.authentication.myLoginModule
Example 12 Print a List of All Registered Applications# smreg list -a
EXIT STATUS The following exit values are returned: 0 Successful completion. 1 Usage error: missing or malformed arguments.2 An error occurred that prevents registration - either a
console configuration problem, or badly-formatted
web.xml or app.xml. 3 Unable to determine OS for this machine. 4 Detected OS for this machine is not supported.SunOS 5.11 Last change: 8 Mar 2005 11
System Administration Commands smreg(1M)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWmcon ||_____________________________|_____________________________|
| Inteface Stability | Obsolete ||_____________________________|_____________________________|
SEE ALSO
smcwebserver(1M), attributes(5)SunOS 5.11 Last change: 8 Mar 2005 12