smreg(1M) System Administration Commands smreg(1M)NAMEsmreg - 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 the console's registration data‐
bases. smreg adds management web applications, libraries, and configu‐
ration 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 registration will replace the previous regis‐
tration. The application registration descriptor app.xml is veri‐
fied 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 ... module
add -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
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 filter and filter-mapping tags. The console
requires these tags to run an application.
The required tags are as follows:
<filter>
<filter-name>SessionManagerFilter</filter-name>
<filter-class>
com.sun.management.services.session.AppSessionManagerFilter
</filter-class>
<init-param>
<param-name>ignore-paths</param-name>
<param-value>
images/*
</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>SessionManagerFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
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 tag
content. That is, the embedded filter-name tag content must be Ses‐
sionManagerFilter, and the filter-class tag content must be:
com.sun.management.services.session.AppSessionManagerFilter
If the tag content is not correct, the application will not be reg‐
istered.
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. Because mul‐
tiple 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 compatibility 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 ...
When used with -p, this option specifies that the property argu‐
ments 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 compatibility
with existing 1.0-based applications. It will be removed in a
future release.
When used with the "add" subcommand, it has the same effect as
"-a".
When used with the "remove" subcommand, path is the path to the
original installation location of the application. This path will
be mapped to the registered app_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 compatibility.
-e name=value ... | --environment name=value ...
When used with -p, this option specifies that the property argu‐
ments are server environment properties. The name=value pairs are
placed into the server's environment 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 at the same time as the
application (for example, localization JAR files), can be regis‐
tered separately by using this option. See lib_name under ARGUMENTS
for more information on the name by which a library is registered.
A library can be registered with global scope so that it can 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 specifying the -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 registry service. "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 preceded by the -o option.
Values containing more than one word must be enclosed in double
quotes (").
-p | --properties
Object type is properties. This option is specified for use 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 configura‐
tion 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 of app_name makes the library available only
to the application already registered as app_name. See app_name
under ARGUMENTS for more information on the name by which an appli‐
cation is registered.
-s service | --scope service
When used with -m, specifies the login service scope for the mod‐
ule. If not specified, the default is ConsoleLogin, 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 con‐
text is the parent directory of the application's WEB-INF direc‐
tory. 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 pluginName and ver‐
sion are tags extracted from the application's regis‐
tration 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 applica‐
tion has been installed.
When used with the check subcommand, if it is a direc‐
tory then it is the full directory path where the
application has been installed. If it is 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 possible
values are: required, requisite, sufficient, 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 be overridden 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 exam‐
ple: com.sun.management.services.authentica‐
tion.MyLoginModule
PROPERTIES
While the list of configuration properties is unlimitted, certain prop‐
erties that may be useful to a system administrator 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 the value to -1 means there is no
timeout. To set the session timeout to 5 minutes, run the following
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 configuring the Java Virtual machine
(JVM). The defaults are "-server -XX:+BackgroundCompilation". To
include setting the initial Java heap 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:
# smreg add -a /opt/myCompany/myApp
Example 2: Unregistering an Application
The following command unregisters an application previous registered
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/Some‐
Company/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
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 application com.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 the deployment
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.xml
Example 8: Registering an Environment Property
The following command registers the environment property name GREETING
with value "Hello World" and the name FOO with the value "bar" so that
they appear in the server's environment and are available to any appli‐
cation:
# smreg add -p -e GREETING="Hello World" FOO=bar
Example 9: Unregistering an Environment Property
The following command unregisters the environment property names GREET‐
ING and FOO so that they no longer appear in the server's environment
and are not available to any application:
# smreg remove -p -e GREETING FOO
Example 10: Registering a Login Module
The following command registers the module class com.sun.manage‐
ment.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.manage‐
ment.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 con‐
sole 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.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWmcon │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Obsolete │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOsmcwebserver(1M), attributes(5)SunOS 5.10 8 Mar 2005 smreg(1M)
