cacaoadm(1M) System Administration Commands cacaoadm(1M)NAMEcacaoadm - administer the common agent container
SYNOPSIScacaoadm [-? | --help]
cacaoadm [-V | --version]
cacaoadm [enable | disable | start | restart] [-i instancename]
cacaoadm stop [-i instancename] [-f]
cacaoadm status [-i instancename] [modulename]
cacaoadm get-param [-i instancename] [-v] param
cacaoadm set-param [-i instancename] param=value
cacaoadm list-params [-i instancename] [-d]
cacaoadm list-modules [-i instancename] [-r]
cacaoadm deploy [-i instancename] moduleFile
cacaoadm [undeploy | lock | unlock] [-i instancename]moduleName
cacaoadm get-filter [-i instancename] [-v] [-p] filterName
cacaoadm set-filter [-i instancename] [-p] filterName=filterLevel
cacaoadm list-filters [-i instancename] [ [-p] |[-l]]
cacaoadm create-instance [-e] instancename
cacaoadm delete-instance -i instancename
cacaoadm list-instances
cacaoadm create-keys [-i instancename] [-f ] [ -n][ -d directoryname]
cacaoadm delete-keys [-i instancename]
cacaoadm show-trusted-cert [-i instancename | [-u jmx-service-url
[-c environment]]] [-f certfile] [-v] cert-alias
cacaoadm add-trusted-cert [-i instancename | [-u jmx-service-url
[-c environment]]] [-f certfile] cert-alias
cacaoadm list-trusted-certs [-i instancename |
[-u jmx-service-url [-c environment]]] [-v]
cacaoadm show-cert-chain [-i instancename | [-u jmx-service-url
[-c environment]]] [-d directory]
cacaoadm register-module [-i instancename] module-descriptor-file
cacaoadm unregister-module [-i instancename]module-descriptor-file
cacaoadm verify-configuration [-i instancename]
cacaoadm rebuild-dependencies [-i instancename]
cacaoadm prepare-uninstall
DESCRIPTION
The cacaoadm utility is the command line interface for managing the
common agent container's management daemon.
The common agent container's management daemon provides a modular in‐
frastructure that hosts both a management agent and service modules.
Several instances of the common agent container's management daemon can
run at the same time. Use the -i instancename option to specify a spe‐
cific instance on which the action will be performed. If you specify
the default instancename (called default), then the files are associ‐
ated with the default daemon instance. This default instance is created
automatically and cannot be deleted.
Some subcommands require that the management daemon be running when the
subcommand is issued. These subcommands include:
o The deploy and undeploy subcommands
o The lock and unlock subcommands
o The list-modules subcommand (except when it is used with the
-r option)
o The show-trusted-cert, add-trusted-cert, and list-trusted-
certs subcommands
o The show-cert-chain subcommand
o The get-filter, set-filter, and list-filters subcommand
(except when they are used with the -p option)
Some subcommands require the common agent container's management daemon
not to be running when the subcommand is issued. These subcommands
include :
o The create-keys subcommand
o The delete-keys subcommand
o The set-param subcommand
o The delete-instance subcommand
o The rebuild-dependencies subcommand
There is a short delay of several seconds between starting the common
agent container's management daemon and its availability. During this
period, some subcommands can fail with an explicit error message. These
subcommands are as follows:
o The deploy and undeploy subcommands
o The lock and unlock subcommands
o The status module subcommand
o The stop subcommand
o The list-modules subcommand without the -r option.
o The list-filter, get-filter, and set-filter subcommands
without the -p option.
Stop and start an instance of the common agent container's management
daemon by executing the cacaoadm script manually using the following
command:
# /usr/sbin/cacaoadm [start | stop] [-i | --instance instancename]
Some subcommands can be run only as the common agent container adminis‐
trator (root by default for a package installation). These subcommands
are as follows:
o The start, stop and restart subcommands
o The enable and disable subcommands. (Requires an administra‐
tor with root privileges.)
o The status subcommand
o The create-keys subcommand
o The set-param subcommand
o The get-filter, set-filter and list-filters subcommands
o The create-instance, delete-instance and list-instances sub‐
commands
o The deploy and undeploy subcommands
o The lock and unlock subcommands
o The disable and enable subcommands
o The register-module, unregister-module and list-modules sub‐
commands
o The add-trusted-cert subcommand
o The verify-configuration subcommand
o The rebuild-dependencies subcommand
The common agent container's parser identifies anything with an option-
like value to be an option, and only accepts the reserved options
described in this man page. If you issue a command with a value that
contains an option-like element, the parser treats the value as an
option, or if there is no corresponding legal option, the parser does
not recognize the syntax. This is explained in example 14.
OPTIONS
The following options are supported.
-? | --help
Display the usage summary.
-V | --version
Display the common agent container's version information.
SUBCOMMANDS
enable [(-i | --instance) instancename]
Enable an instance of the common agent container's management dae‐
mon to start up automatically during subsequent system boots and to
stop gracefully during system shutdown. The cacaoadm enable subcom‐
mand is the only supported method of managing the management dae‐
mon.
This command requires some privileges. If you use a tarball distri‐
bution with a normal user account, this command will fail.
disable [(-i | --instance) instancename]
Configure an instance of the common agent container daemon not to
start on reboot. The instance remains disabled until you re-run the
cacaoadm script with the enable subcommand for that instance. The
cacaoadm disable subcommand is the only supported method of dis‐
abling the management daemon.
This command requires some privileges. If you use a tarball distri‐
bution with a normal user account, this command will fail.
start [(-i | --instance) instancename]
Start an instance of the common agent container's management dae‐
mon.
This command is synchronous in Solaris 10 and later. The CLI may
take some time to exit as it waits for modules deployed inside to
finish their initialization. It is not recommended to interrupt
this process.
restart [(-i | --instance) instancename]
Stop and subsequently start an instance of the common agent con‐
tainer's management daemon.
stop [(-i | --instance) instancename] [-f| --force]
Stop an instance of the common agent container's management daemon.
This is a clean stop in which all deployed modules are locked and
then undeployed. If an error occurs and the clean stop is unsuc‐
cessful, the common agent container's management daemon undergoes a
forced stop and returns 0. This is true even if the --force or -f
option was not used. The return value of 0 does not necessarily
imply that all deployed modules were successfully undeployed before
the common agent container's management daemon stopped.
Add the --force or -f option for a forced stop, in which no modules
are undeployed before the agent stops.
status [(-i | --instance) instancename] [modulename]
Display the common agent container's daemon status for a given com‐
mon agent container instance, including the current number of
retries. Without specifying a modulename, display agent status
including whether the common agent container's management daemon is
enabled or disabled, its process numbers, and its uptime. With a
modulename specified, display only the status of the module named
modulename. See the examples section for an example of the status
command.
The status of the administrative state can be either:
o LOCKED - The module named modulename must not offer ser‐
vice. This status applies to the module lifecycle and
not to the common agent container management daemon's
lifecycle.
o UNLOCKED - The module named modulename must offer ser‐
vice.This status applies to the module lifecycle and not
to the common agent container management daemon's life‐
cycle.
The status of the operational state can be either:
o ENABLED - The daemon, or the module named modulename, is
able to offer service. Do not confuse this status with
the enable subcommand, which is a cacaoadm sub-command
for starting the common agent container daemon at system
startup. The ENABLED operational state indicates that a
module is operational.
o DISABLED - The daemon, or the module named modulename,
is unable to offer service. Do not confuse this status
with the disable subcommand, which is a cacaoadm sub-
command for disabling the common agent container daemon
at system startup. The DISABLED operational state indi‐
cates that the common agent container has detected an
error for the module and the module is not operational.
The availability status is empty unless the operational state is
set to DISABLED, in which case the interesting values are:
o DEPENDENCY - indicates that the resource cannot operate
because some other resource on which it depends is
unavailable.
o OFF_LINE - indicates that a routine operation is needed
to bring the resource back into use.
o FAILED - the resource has an internal fault that pre‐
vents it from operating.
get-param [(-i | --instance) instancename] [-v | --value] param
Display the parameter named param for a particular instance of the
common agent container's daemon, alongside its associated value.
With the -v or --value option, display only the associated value.
set-param [(-i| --instance) instancename] param=value
Set the value associated with the parameter named param for a par‐
ticular instance of the common agent container's daemon. The fol‐
lowing parameters can be set:
jmxmp-connector-port
Set this value to the connector port for the JavaTM Management
Extensions (JMXTM) software. For the default instance of the
common agent container, the default port value is 11162. For
all other instances, the default port value is -1 and therefore
needs to be set by the user. cacaoadm does not start a con‐
tainer if this option is not configured. The port value can be
set to 0, in which case a port number is dynamically set. The
actual value of the port is stored in the
installdir/var/run/cacao/instances/instancename/run/run‐
time.properties file.
rmi-registry-port
Set this value to the port for Java Remote Method Invocation
(RMI). For the default instance of the common agent container,
the default port value is 11164. The port value can be set to 0
in which case a port number is dynamically chosen. The actual
value of the port will be stored in the
installdir/var/run/cacao/instances/instancename/run/run‐
time.properties file. The port value can also be set to -1 in
which case the connector will be deactivated.
snmp-adaptor-port
Set this value to the port for SNMP. For the default instance
of the common agent container, the default port value is 11161.
The port value can be set to 0 in which case a port number is
dynamically chosen. The actual value of the port will be stored
in the installdir/var/run/cacao/instances/instancename/run/run‐
time.properties file. The port value can also be set to -1 in
which case the connector will be deactivated.
snmp-adaptor-trap-port
Set this value to the port for SNMP traps. For the default
instance of the common agent container, the default port value
is 11162. The port value can be set to 0 in which case a port
number is dynamically chosen. The actual value of the port will
be stored in the installdir/var/run/cacao/instances/instance‐
name/run/runtime.properties file. The port value can also be
set to -1 in which case the connector will be deactivated.
commandstream-adaptor-port
Set this value to the port for command stream. For the default
instance of the common agent container, the default port value
is 11163. The port value can be set to 0 in which case a port
number is dynamically chosen. The actual value of the port will
be stored in the installdir/var/run/cacao/instances/instance‐
name/run/runtime.properties file. The port value can also be
set to -1 in which case the connector will be deactivated.
retries
Set this value to the maximum number of times that the common
agent container's management daemon tries to restart, in the
event of an unexpected abort.
For Solaris 10 systems, the retries parameter has no effect
because the common agent container daemon is being managed by
SMF. SMF has its own retry mechanism which supersedes the com‐
mon agent container retry mechanism and the number of SMF
retries is not configurable. This parameter is not taken into
account.
java-flags
Set this value with the Java flags used by the common agent
container's daemon. Set these values carefully because some
setting levels could have an impact on the functionality of the
common agent container's management daemon.
enable-instrumentation
Set this parameter to activate and deactivate instrumentation.
The default value is false.
java-home
Set this parameter to define the path for the Java software.
nss-lib-home
Set this parameter to define the path to the network security
services libraries.
nss-tools-home
Set this parameter to define the path to the network security
services tools.
jdmk-home
Set this parameter to defines the path to the Java Dynamic Man‐
agement Kit.
secure-webserver-port
The common agent container includes a Java web application
server (called the Secure Embedded Web server) embedded into
the common agent container's daemon as an additional module and
available to external clients through secure HTTP and the con‐
figuration parameter secure-webserver-port. This parameter des‐
ignates the port used by the embedded secure web server. The
default value is 11165. The port value can be set to 0 in which
case a port number is dynamically chosen. The actual value of
the port will be stored in the
installdir/var/run/cacao/instances/instancename/run/run‐
time.properties file. The port value can also be set to -1 in
which case the connector will be deactivated.
network-bind-address
By default, the common agent container only listens to incoming
requests from the local machine, by binding all its sockets to
127.0.0.1 (the loopback address). This default configuration is
a security requirement; even though all network communication
to and from the common agent container is secured, an open net‐
work port is still a possible attack vector.
If you require remote network access to the common agent con‐
tainer daemon, then you must change the configuration value of
the network-bind-address. If you need full network access,
change this parameter value to 0.0.0.0, which will make the
daemon listen on all network ports.
IPv6 bind addresses are specified using JMX conventions. For
example, [::1] is the IPv6 loopback.
Applications deploying management code into the common agent
container might have reconfigured the parameter to open net‐
work access to the daemon. . Reducing network access by reset‐
ting this parameter to the default value might adversely affect
the behavior of applications relying on the common agent con‐
tainer's network support.
user
Set this parameter to define the owner of the common agent con‐
tainer process. The default value is root. Changing user param‐
eters requires that the container be owned by a privileged
user. When using a tarball distribution under a normal user
account, if the user value is changed the container may fail to
start.
group
Set this parameter to define the group associated with the com‐
mon agent container process. The default value is sys. Changing
group parameters requires that the container be owned by a
privileged user. When using a tarball distribution under a nor‐
mal user account, if the group value is changed the container
may fail to start.
micro-agent
Defines whether or not the agent is launched in a Java ME envi‐
ronment. The SUNWcacaome package must be installed.
log-file-limit
Set this parameter to define the maximum number of bytes to
write to the log file. If set to 0, no limit will be placed.
log-file-count
Set this parameter to define the rolling log file count.
log-file-append
Set this parameter to define the append mode for log files.
watchdog-heartbeat-timeout
Defines the value in seconds of the timeout of the heartbeat
sent between the common agent container and its monitoring
agent. This timeout can be set to -1 in which case the heart‐
beat mechanism will be deactivated.
Setting a value less than 30 seconds is not recommended, since
on a machine with limited resources or a machine overloaded by
the activities of deployed modules the common agent container
may be restarted because of a lost heartbeat.
list-params [(-i| --instance) instancename] [-d| --description]
Display the list of parameters for a particular instance of the
common agent container's daemon. Without the --description option,
display the list of parameters and their associated values.
With the --description option, display the list of parameters and a
description of each parameter.
list-modules [(-i| --instance) instancename] [-r| --registered]
Display the list of modules that are registered with the daemon,
that is, the modules that have been previously registered using the
register-module subcommand (and not yet unregistered by the unreg‐
ister-module subcommand). Without the --registered option, display
the list of all modules available.
deploy [(-i | --instance) instancename] modulefile
For a given instance, deploy the module described by the XML
descriptor indicated in the path modulefile. This action relates
specifically to modules and not to the common agent container's
management daemon.
undeploy [(-i | --instance) instancename] modulename
For a given instance, undeploy the module named modulename. this
action relates only to modules and not to the common agent con‐
tainer's management daemon.
lock [(-i | --instance) instancename] modulename
For a given instance, lock the module named moduleName.
unlock [(-i | --instance) instancename] modulename
For a given instance, unlock the module named moduleName.
get-filter [(-i | --instance) instancename] [-v | --value] [-p | --per‐
sistent]filtername
For a given instance, get the value associated with the filter
named filtername. Without the -v or --value option, display the
filter named filtername and its associated value.
With the -v or --value option, display only the associated value.
With the -p or -- persistent option, you can display the level
value persistent over restart for the specified filter.
set-filter [(-i | --instance) instancename] [-p | --persistent] filter‐
name=filterlevel
For a given instance, set the filter named filtername to a level,
filterlevel. The predefined filter levels, in descending order, are
as follows:
o SEVERE (highest value)
o WARNING
o INFO
o CONFIG
o FINE
o FINER
o FINEST (lowest value)
o ALL
o OFF
o NULL (resets the level)
By default, the set-filter subcommand is run-time only. Therefore
the setting of filters is only functional while the common agent
container daemon is running. However, you can make the filter set‐
ting persist across common agent container restarts by using the -p
option. After you specify the command with the -p option, you must
restart the container to make the persistent function work.
list-filters [(-i | --instance) instancename] [-p | --persistent] [-l |
--levels]
Display the list of all available filters along with their levels.
With the -l or --levels option, display the full list of all avail‐
able filter levels. with the -p or-persistent option, display only
the list of persistent filter levels.
Other levels can be defined by user modules.
create-instance [-e | --embedded] instancename
Create a new instance of the name instancename. Instance names are
limited to 32 characters, and the first character must be alpha‐
betic, upper or lower case. Subsequent characters can be alphanu‐
meric, upper or lower case, and underscores and dashes are permit‐
ted.
If the -e or --embedded option is selected, the created instance is
configured to run in a JVM container and it is not started through
the cacaoadm command. In this case, instance management cacaoadm
subcommands such as start, stop, restart, enable, and disable do
not work.
After executing the create-instance subcommand, and before starting
the instance, you must do the following step:
o Set the jmxmp-connector-port parameter and all other
port parameters to available port numbers using the set-
param subcommand. At instance creation time, all ports
are set to an invalid value (-1) for non-default
instances of the management daemon.
After creating instances, check that your configuration is correct
by using the verify-configuration subcommand.
Security files are created separately for each instance of the com‐
mon agent container.
Paths to the logs and configuration information for instances of
the common agent container for the Oracle Solaris OS are as fol‐
lows:
o /etc/cacao/instances/instancename: the configuration
directory. The local clients may use this directory as
the value for the cacao.config.dir system property when
they want to retrieve the configuration parameters of
the instance.
o /etc/cacao/instances/instancename/modules: the wellknown
repository of modules where you can put a deployment
descriptor to be registered with the container and thus
loaded the next time the container starts.
o /etc/cacao/instances/instancename/security: the security
directory. See the cacao(5) man page for details on
security files.
o /var/cacao/instances/instancename/logs: the directory
for log files.
o /var/cacao/instances/instancename/audits: the directory
for audit files.
o /var/run/cacao/instances/instancename/run: the directory
for the pid file.
The common agent container DTDs can be found under
/usr/lib/cacao/lib/tools. They do not differ from one instance to
another.
delete-instance (-i | --instance) instancename
Remove the specified instance including all instance configuration
files. This subcommand also applies to embedded instances. You need
to stop the instance before you can remove it.
The delete-instance subcommand does not ask for confirmation before
it executes. You cannot delete core instances using this command.
list-instances
List all created and not removed instances. The default common
agent container daemon instance is also listed. In the output,
instances that are embedded are clearly indicated as being embed‐
ded.
create-keys [(-i | --instance) instancename] [-f --force]
[-n | --nonss] [(-d | --directory) directoryname]
Generates keys for the common agent container. With no options,
keys are generated, if they not have been already generated.
With the -f or --force option, keys are always generated.
With the -n or --nonss option, no keys are generated for NSS. With‐
out the -n or --nonss option, keys are generated for NSS provided
that NSS packages are present. For command stream connections, or C
connections, NSS security keys must be used. Do not therefore spec‐
ify --nonss if you want secure command stream client connections or
C client connections.
With the -d or --directory option, keys are generated in the direc‐
tory specified by the path directoryname. If keys are already
present in the directory specified by directoryname, then no action
is taken, unless the --force option is also used.
The create-keys subcommand does not generate keys if used when the
common agent container's management daemon is already running. You
must stop the common agent container's management daemon before
using this subcommand.
delete-keys [(-i | --instance) instancename]
Removes security keys for the common agent container previously
created during the start of the container or by a previous call to
the create-keys command. You must stop the common agent container's
management daemon before using this subcommand.
show-trusted-cert [(-i | --instance) instancename | [(-u | --url) jmx-
service-url
[(-c | --connection-env) environment]]] [-v | --verbose] [(-f |
--file) certfile] cert-alias
Display the certificate associated with the alias cert-alias in the
common agent container's management daemon's truststore. The cer‐
tificate is base64 encoded as specified in RFC1421.
When --verbose is omitted, the command prints the requested cer‐
tificate to stdout in PKCS#10 format. When --verbose is included,
the command acts in a similar way to keytool, giving every detail
of the certificate entry.
The -c option and the -u option are compatible. The -c option and
the -i option are incompatible.
Add the --connection-env option to specify the env.properties file,
which contains the environment variables specified as key=value
pairs, for establishing connection to the common agent container.
Using this option means that the password is not written to the
command line interface.
The format expected for the --connection-env option is in a proper‐
ties file format. For example:
key1=value1
key2=value2
A connection environment file can contain any keys described in the
ENVIRONMENT VARIABLES section of the cacaourl(5) man page except
the jmx.remote.credentials key which is not supported.
Caution -
When using the -connection-env option, be careful not to add any
space or tab characters after a key value. The common agent con‐
tainer does not strip off these characters and they cause the
command to fail. Additionally, each key=value line must be sepa‐
rated from other key=value lines using a newline.
If the --file option is used, the certificate is put in the file
certfile with no output to stdout, so the file is not displayed.
The options --verbose and --file cannot be specified together. The
-i and -u options cannot be specified together. The -u option must
be used to connect to a remote daemon. When the -i and -u options
are omitted, the local default instance is targeted.
The show-trusted-cert subcommand can be used by non-root users,
provided that the non-root user adds the --url option, and that the
wellknown attribute of the URL is set to false. For more informa‐
tion, see the cacaourl(5) man page.
add-trusted-cert
[(-i | --instance) instancename | [(-u | --url) jmx-service-url
[(-c | --connection-env) environment]]] [(-f | --file) certfile] cert-
alias
Add a certificate to the truststore of the management daemon. The
certificate must be base64 encoded as specified in RFC1421.
Add the --connection-env option to specify the environment parame‐
ter for establishing connection to the common agent container.
Using this option means that the password is not written to the
command line interface.
The format expected for the --connection-env option is in a proper‐
ties file format. For example:
key1=value1
key2=value2
A connection environment file can contain any keys described in the
ENVIRONMENT VARIABLES section of the cacaourl man page except the
jmx.remote.credentials key which is not supported.
Caution -
When using the --connection-env option, be careful not to add any
whitespace or tab characters after a key value. The common agent
container does not strip off these characters and they cause the
command to fail. Additionally, each key=value line must be sepa‐
rated from other key=value lines using a newline.
If --file option is present, the certificate is read and added to
the truststore. If --file is omitted, the certificate is read from
stdin. You must be root to execute this command. -i and -u cannot
be specified together. The -u option must be used to connect to a
remote daemon.
The -c option and the -u option are compatible. The -c option and
the -i option are incompatible.
list-trusted-certs
[(-i | --instance) instancename |[(-u | --url) jmx-service-url [(-c |
--connection-env) environment]]]
[-v | --verbose]
List all the certificate aliases of the common agent container's
management daemon.
Add the --connection-env option to specify the environment parame‐
ter for establishing connection to the common agent container.
Using this option means that the password is not written to the
command line interface.
The format expected for the -connection-env option is in a proper‐
ties file format. For example:
key1=value1
key2=value2
A connection environment file can contain any keys described in the
ENVIRONMENT VARIABLES section of the cacaourl(5) man page except
the jmx.remote.credentials key which is not supported.
Caution -
When using the --connection-env option, be careful not to add any
space or tab characters after a key value. The common agent con‐
tainer does not strip off these characters and they cause the
command to fail. Additionally, each key=value line must be sepa‐
rated from other key=value lines using a newline.
When the --verbose option is omitted, the command puts the aliases
in the truststore. When --verbose is included, the command acts in
a similar way to keytool, providing every detail of each certifi‐
cate entry. The -i and -u options cannot be specified together. The
-u or --url option must be used to connect to a remote daemon.
The list-trusted-certs subcommand can be used by non-root users,
provided that the non-root user adds the --url option, and that the
wellknown attribute of the URL is set to false. For more informa‐
tion, see the cacaourl(5) man page.
show-cert-chain
[(-i | --instance) instancename | [(-u | --url) jmx-service-url [(-c |
--connection-env) environment]]]
[(-d | --directory) certdir] cert-alias
Display the common agent container's management daemon's certifi‐
cate chain.
Add the --connection-env option to specify the environment parame‐
ter for establishing connection to the common agent container.
Using this option means that the password is not written to the
command line interface.
The format expected for the --connection-env option is in a proper‐
ties file format. For example:
key1=value1
key2=value2
A connection environment file can contain any keys described in the
ENVIRONMENT VARIABLES section of the cacaourl(5) man page except
the jmx.remote.credentials key which is not supported.
Caution -
When using the --connection-env option, be careful not to add any
space or tab characters after a key value. The common agent con‐
tainer does not strip off these characters and they cause the
command to fail. Additionally, each key=value line must be sepa‐
rated from other key=value lines using a newline.
The -directory option specifies a directory where you can put all
certificates in the certificate chain into a file. For each cer‐
tificate of the chain, a file is created. The first certificate in
the chain is the daemon's certificate. This certificate is in the
certificate0 file. The root CA of the chain is the last certifi‐
cate. The certificate is base64 encoded as specified in RFC1421.
When the -d or --directory option is omitted, cacaoadm directs the
chain to stdout.
The -c option and the -u option are compatible.
register-module [(-i | --instance) instancename] module-descriptor-file
This command registers a new module for instance instancename. This
is a persistent update. A registered module is one that will be
started the next time the daemon is started.
It may not be possible to register a module using the CLI if a
post-installation script or a remote installation are in progress.
In such cases a module can be registered manually by placing its
descriptor inside the following directory:
installdir/etc/cacao/instances/instancename/modules/
If the registration is made before the common agent container
installation, you can create this directory. The directory must be
kept secure and usable. It must be owned by the common agent con‐
tainer owner, and must be created using 755 mode.
unregister-module [(-i | --instance) instancename] module-descriptor-
file
This command unregisters a module for instance instancename. An
unregistered module will not be started the next time the daemon is
started. Additionally, the modules XML file is erased so you will
not get back its descriptor.
verify-configuration [(-i | --instance) instancename]
This command checks whether the configuration of the common agent
container is valid. It includes a check on parameter values,
expected permissions on configuration files, security files, depen‐
dencies belonging to the specified instance, and possible conflicts
with other instances.
This command helps you to detect some errors. However, it does not
assess the impact any errors might have on your configuration or
provide the steps necessary to fix the configuration.
Furthermore, the common agent container may start even if verify-
configuration returns a non-zero exit code. However, in such a
case, the daemon can go into an unknown or undefined state and
behavior.
rebuild-dependencies [(-i | --instance) instancename]
This command detects all the dependencies possible. This command
updates the Java, NSS and Java Dynamic Management Kit parameters
belonging to an instance named instancename. If no correct parame‐
ters are found, none are updated. Where the command is unsuccess‐
ful, the parameters are not updated.
prepare-uninstall
This subcommandtops all the running instances and removes the
startup resources. If the common agent container was installed
using a tarball archive or a remote package installation, issue
this subcommand before uninstalling the common agent container. Do
not use this command if the common agent container was installed
from native packages because the uninstallation process calls this
command automatically.
Do not attempt to use the common agent container after you issue
this subcommand. Uninstall the common agent container immediately.
EXAMPLES
Here are some examples to help you understand how to use the cacaoadm
command, along with its options and subcommands, to manage modules.
Example 1: Deploying a Module
In this example, a module is deployed. The precise XML path to the mod‐
ule is given, (com.sun.cacao.example.xml)
# /usr/sbin/cacaoadm deploy com.sun.cacao.example.xml
Example 2: Removing a Deployed a Module
In this example, the module that is already deployed is removed. The
module is named com.sun.cacao.example
# /usr/sbin/cacaoadm undeploy com.sun.cacao.example
Example 3: Locking a Module
In this example, a module named com.sun.cacao.example is locked.
# /usr/sbin/cacaoadm lock com.sun.cacao.example
Example 4: Unlocking a Module
In this example, a module named com.sun.cacao.example is unlocked.
# /usr/sbin/cacaoadm unlock com.sun.cacao.example
Example 5: Setting the Maximum Number of Retries
In this example, the maximum number of times that the common agent con‐
tainer's management daemon attempts to restart is set to 5. For Oracle
Solaris 10 systems, the retries parameter has no effect. See the
retries subcommand description on this man page for more information.
# /usr/sbin/cacaoadm set-param retries=5
Example 6: Setting the SNMP Adaptor Port
In this example, the UDP port to which the SNMP server listens, for
SNMPv3 requests, is set to port number 10165.
# /usr/sbin/cacaoadm set-param snmp-adaptor-port=10165
This port number is used for example only.
Example 7: Displaying a Module's Status.
In this example, the status of a module named com.sun.cacao.efd is dis‐
played.
# /usr/sbin/cacaoadm status com.sun.cacao.efd
Operational State:ENABLED
Administrative State:UNLOCKED
Availability Status:[]
Module is in good health.
If you are using the common agent container on a Solaris 10 system, the
status command has a slightly different output due to the OS use of
SMF.
# cacaoadm status
default instance is DISABLED at system startup.
Smf monitoring process:
2087
Uptime: 0 day(s), 0:0
Example 8: Generate Certificates in the Daemon Chain.
In this example, certificates are generated in each of the common agent
container's management daemon chains. Each certificate is generated in
a separate file and placed in a directory named foo.
# /usr/sbin/cacaoadm show-cert-chain -d /foo
A certificate is available in file /foo/certificate0
A certificate is available in file /foo/certificate1
Example 9: Display Certificate of Common Agent Container's Management
Daemon on a Host.
In this example, the certificate with the certificate alias cacao_ca is
displayed for the host named bar.
# /usr/sbin/cacaoadm show-trusted-cert -c env.properties -u
"service:jmx:cacao-rmi://bar;wellknown=true" cacao_ca
The env.properties file declared above and specified with the -c option
contains the following:
com.sun.cacao.rmi.username=root
For more information, see the part of this man page explaining the
--connection-env option.
Example 10: List All Trusted Certificates of an Instance.
In this example, all of the trusted certificates of an instance named
inst can be displayed using the following command:
# /usr/sbin/cacaoadm list-trusted-certs -i inst
Example 11: Add a Trusted Certificate.
In this example, the command adds a certificate contained in the file
/tmp/trusted.cert as a trusted certificate of the common agent con‐
tainer's management daemon on the host named foohost. The certificate
alias of this certificate is foocert.
# /usr/sbin/cacaoadm add-trusted-cert -c env.properties -u
"service:jmx:cacao-rmi://foohost;wellknown=true"
-f /tmp/trusted.cert foocert
The env.properties file declared above and specified with the -c option
contains the following:
com.sun.cacao.rmi.username=root
For more information, see the part of this man page explaining the
--connection-env option.
Example 12: Creating, Configuring, and Starting an Instance of the Com‐
mon Agent Container's Management Daemon.
In this example, the create-instance subcommand is used to create an
instance, named instance1, as follows:
# /usr/sbin/cacaoadm create-instance instance1
The instance is then configured to use available specific ports for
JMXMP, SNMP, RMI, and commandstream protocols. This is done using the
set-param subcommand as follows:
# /usr/sbin/cacaoadm set-param -i instance1
jmxmp-connector-port=10182
# /usr/sbin/cacaoadm set-param -i instance1
snmp-adaptor-port=10181
# /usr/sbin/cacaoadm set-param -i instance1
snmp-adaptor-trap-port=10182
# /usr/sbin/cacaoadm set-param -i instance1
commandstream-adaptor-port=10183
# /usr/sbin/cacaoadm set-param -i instance1
rmi-registry-port=10184
The instance, instance1, is then started using the start subcommand as
follows:
# /usr/sbin/cacaoadm start -i instance1
Example 13: Deleting an Instance of the Common Agent Container's Man‐
agement Daemon:
In this example, an instance of the management daemon named instance1
is deleted using the delete-instance subcommand:
# /usr/sbin/cacaoadm delete-instance -i instance1
When the instance is deleted, all configuration associated with the
instance is also deleted.
Example 14: Deploying a Module With a File Path that is Acceptable to
the Parser:
This example deploys a module with an XML descriptor file path, -mod‐
file3.xml, that is acceptable to the parser, despite the option-like -
character in its name.
# /usr/sbin/cacaoadm deploy -i instance2 -- -modfile3.xml
This example contains the -- token, which instructs the parser to
accept the option-like -modfile3.xml as a valid path, so that the
parser does not wrongly identify the path or value as an illegal
option. This token is necessary for all subcommands whenever a parame‐
ter or value with an option-like name is used. The exception is the
set-param subcommand.
Example 15: Create instance instance1 and open the remote network
access.
# /usr/sbin/cacaoadm create-instance instance1
# /usr/sbin/cacaoadm set-param -i instance1 network-bind-address=0.0.0.0
Example 16: Set the filter level of the example module to FINEST for
the default instance and make it persist across restarts.
# /usr/sbin/cacaoadm set-filter -p com.sun.cacao.example=FINEST
You must restart the container after you issue this command in order
for the persistent function to work.
Example 17: Create instance instance2 and list the set of persistent
filter levels for it.
# /usr/sbin/cacaoadm create-instance instance2
#/usr/sbin/cacaoadm list-filter --instance instance2 --persistent
com.sun.cacao=FINE
com.sun.cacao.examples=ALL
javax.management.remote=SEVERE
Example 18: Stop all the running instances and remove their startup
resources.
# /usr/sbin/cacaoadm prepare-uninstall
# pkgrm SUNWcacaort
EXIT STATUS
The following exit values are returned:
0
Successful completion
1
An error occurred
2
Invalid usage
3
If the common agent container is not started and the command fails
11
If the common agent container is starting or stopping, or there is
another problem, and the command fails
13
The user is not root and is executing a root cacaoadm command
17
The common agent container is already running, if for example you
start two instances of the same common agent container
22
Invalid usage, or XML file not found
ATTRIBUTES
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcacaort │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSO
cacao.5, cacaourl.5
Oracle Solaris May 2010 cacaoadm(1M)