cacaoadm man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

cacaoadm(1M)		System Administration Commands		  cacaoadm(1M)

NAME
       cacaoadm - administer the common agent container

SYNOPSIS
       cacaoadm [-? | --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)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net