Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

cacaoadm


NAME
     cacaoadm - administer the common agent container

SYNOPSIS
     cacaoadm [-? | --help]

     cacaoadm [-V | --version]

     cacaoadm [enable | disable | start |  restart]  [-i  instan-
     cename]

     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]  modu-
     leName

     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 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  infrastructure  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 specific instance on
     which  the  action  will  be  performed.  If you specify the
     default instancename (called default), then  the  files  are
     associated  with  the  default daemon instance. This default
     instance is created automatically and cannot be deleted.

     Some subcommands require that the management daemon be  run-
     ning  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 set-param subcommand

       o  The delete-instance subcommand


     There is a short delay of several seconds  between  starting
     the common agent container's management daemon and its avai-
     lability. 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  con-
     tainer   administrator   (root  by  default  for  a  package
     install). These subcommands are as follows:

       o  The start, stop and restart subcommands

       o  The enable and disable subcommands

       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
          subcommands

       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
          subcommands

       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 recognised
     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  daemon to start up automatically during sub-
         sequent system boots and gracefully to stop during  sys-
         tem shutdown.



     disable [-i | --instance instancename]

         Configure a particular  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.



     start [-i | --instance instancename]

         Start  an  instance  of  the  common  agent  container's
         management daemon.



     restart [-i | --instance instancename]

         Stop and subsequently start an instance  of  the  common
         agent container's management daemon.



     stop [-i | --instance instancename] [-f| --force]

         Stop an instance of the common agent container's manage-
         ment  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 unsucessful, 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 suc-
         cessfully 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  common  agent  container  instance, including the
         current number of retries. Without  specifying  a  modu-
         lename,  display agent status including whether the com-
         mon 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
              service.  Note  that  this  status  applies  to the
              module lifecycle and not to the common  agent  con-
              tainer management daemon's lifecycle.

           o  UNLOCKED - The module named modulename  must  offer
              service.  Note  that  this  status  applies  to the
              module lifecycle and not to the common  agent  con-
              tainer management daemon's lifecycle.

         The status of the operational state can be either:


           o  ENABLED - The daemon, or  the  module  named  modu-
              lename,  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 opera-
              tional.

           o  DISABLED - The daemon, or the  module  named  modu-
              lename,  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  indicates 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
              prevents 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, along-
         side 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   particular   instance   of  the  common  agent
         container's daemon. The following 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  there-
             fore needs to be set by the user.cacaoadm refuses to
             start a container if this option is not configured.




         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.  For  all  other  instances, the default port
             value is -1 and therefore needs to  be  set  by  the
             user.



         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. For all  other  instances,  the
             default  port value is set to -1 and therefore needs
             to be set by the user.



         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.   For   all   other
             instances,  the  default port value is -1 and there-
             fore needs to be set by the user.

         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.  For  all  other
             instances,  the  default port value is -1 and there-
             fore needs to be set by the user.



         retries

             Set this value to the maximum number of  times  that
             the   common  agent  container's  management  daemon
             should try 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  mechan-
             ism  which  supersedes  the  common  agent container
             retry mechanism and SMF retries is not configurable.
             At   present,  this  parameter  is  not  taken  into
             account.



         java-flags

             Set this value with the Java flags used by the  com-
             mon  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  disactivate
             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 Management 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  confi-
             guration   parameter   secure-webserver-port.   This
             parameter designates the port used by  the  embedded
             secure web server.  The default value is 11165.



         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 network port is still a possible attack vec-
             tor.

             If you require remote network access to  the  common
             agent  container  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.

             Applications deploying management code into the Com-
             mon Agent Container may have reconfigured the param-
             eter to open up network access to the daemon  should
             they  require  it. Reducing network access by reset-
             ting  this  parameter  to  the  default  value   may
             adversely  affect the behavior of applications rely-
             ing on the common agent container's network support.



         user

             Set this parameter to define the owner of the common
             agent container process.  The default value is root.



         group

             Set this parameter to define  the  group  associated
             with the common agent container process. The default
             value is sys.



     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 unregister-module subcom-
         mand).  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. Note
         that 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  modu-
         lename.  Note  that  this action relates specifically to
         modules and not to the common agent container's  manage-
         ment 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  modu-
         leName.



     get-filter [-i| --instance instancename] [-v | --value] [-p
     | --persistent]filtername

         For a given instance, get the value associated with  the
         filter  named  filtername.   Without  the  -v or --value
         option, display the  filter  named  filterfame  and  its
         associated value.

         With the -v or --value option, display only the  associ-
         ated 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]
     filtername=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. How-
         ever,  you  can  make  the filter setting 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  func-
         tion work.



     list-filters [-i | --instance instancename] [-p] [-l]

         Display the list of all  available  filters  along  with
         their  levels.  With  the -l or --levels option, display
         the full list of all available filter levels.  with  the
         -p  or-persistent  option, display only the list of per-
         sistent 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 char-
         acter must be alphabetic, upper or  lower  case.  Subse-
         quent  characters  can  be  alphanumeric, upper or lower
         case, and underscores and dashes are permitted.

         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.

         Note that after executing  the  create-instance  subcom-
         mand,  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  crea-
              tion  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.

         Note that security files are created separately for each
         instance of the common agent container.

         Paths to the  logs  and  configuration  information  for
         instances  of the common agent container for the Solaris
         OS are as follows:


           o  /etc/cacao/instances/instancename : the  configura-
              tion  directory.  The  local  clients  may use this
              directory as the  value  for  the  cacao.config.dir
              system property when they want to retrieve the con-
              figuration 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 con-
              tainer 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  direc-
              tory 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.

         Note that 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 embedded.



     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  gen-
         erated.

         With the -n or --nonss option, no keys are generated for
         NSS.  Without  the  -n  or --nonss option, keys are gen-
         erated for NSS provided that NSS packages  are  present.
         Note  that  for command stream connections, or C connec-
         tions, NSS security keys must be used. Do not  therefore
         specify --nonss if you want secure command stream client
         connections or C client connections.

         With the -d or --directory option, keys are generated in
         the  directory  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 subcom-
         mand.




     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 certificate is  base64  encoded
         as specified in RFC1421.

         When  --verbose  is  omitted,  the  command  prints  the
         requested certificate to stdout in PKCS#10 format.  Oth-
         erwise, the command  acts  similar  to  keytool,  giving
         every detail known about 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 properties 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 char-
                   acters 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
                   separated 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  can-
         not  be specified together. The -i and -u options cannot
         be specified together. The -u option should 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 information, see the cacaourl man
         page.




     add-trusted-cert
     [-i | --instance instancename | [-u | --url jmx-service-url
      [-c | --connection-env environment]]] [-f | --file cert-
     file] cert-alias

         Add a certificate to the truststore  of  the  management
         daemon. The certificate must be base64 encoded as speci-
         fied in RFC1421.

         Add the -connection-env option to specify  the  environ-
         ment parameter for establishing connection to the common
         agent container. Using this option means that the  pass-
         word is not written to the command line interface.

         The format expected for the -connection-env option is in
         a properties 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 char-
                   acters 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
                   separated 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 cer-
         tificate is read from stdin. You must be root to execute
         this  command.  -i  and -u cannot be specified together.
         The -u option should be used to connect to a remote dae-
         mon.

         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  environ-
         ment parameter for establishing connection to the common
         agent container. Using this option means that the  pass-
         word is not written to the command line interface.

         The format expected for the -connection-env option is in
         a properties 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 char-
                   acters after a key  value.  The  common  agent
                   container  does not strip off these characters
                   and they cause the command to fail.  Addition-
                   ally,  each  key=value  line must be separated
                   from other key=value lines using a newline.

         When the --verbose option is omitted, the  command  puts
         the  aliases  in  the truststore. Otherwise, the command
         acts similar to keytool, providing  every  detail  known
         about each certificate entry. The -i and -u options can-
         not be specified together. The -u or --url option should
         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 information, see the cacaourl
         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
         certificate chain.

         Add the --connection-env option to specify the  environ-
         ment parameter for establishing connection to the common
         agent container. Using this option means that the  pass-
         word is not written to the command line interface.

         The format expected for the --connection-env  option  is
         in a properties 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 char-
                   acters after a key  value.  The  common  agent
                   container  does not strip off these characters
                   and they cause the command to fail.  Addition-
                   ally,  each  key=value  line must be separated
                   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 certificate  of  the  chain,  a  file  is
         created.  The  first  certificate  in  the  chain is the
         daemon's certificate. This certificate is in the  certi-
         ficate0  file. The root CA of the chain is the last cer-
         tificate. The certificate is base64 encoded as specified
         in  RFC1421.  When the -d or --directory option is omit-
         ted, cacaoadm directs the chain to stdout.

         The -c option and the -u option are compatible.





     register-module [-i | --instance instancename]
      moduledescriptorfile

         This command registers a new module for instance instan-
         cename. This is a persistent update. A registered module
         is one that will be started the next time the daemon  is
         started.




     unregister-module [-i | --instance instancename]
      moduledescriptorfile

         This command unregisters a module for  instance  instan-
         cename.  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,  dependencies 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 behaviour.



     rebuild-dependencies [-i | --instance instancename]

         This command redetects 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 parameters are found, none
         are updated. Where  the  command  is  unsuccessful,  the
         parameters are not updated.



     prepare-uninstall

         Stops all the  running instances and removes the startup
         resources.   Use this subcommand before uninstalling the
         common  agent  container  when   it's   been   installed
         remotely.



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      module      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.xml

     # /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 container's management daemon attempts to
          restart is set  to  5.  For  Solaris  10  systems,  the
          retries  parameter  has no effect. See the retries sub-
          command description on this man page for more  informa-
          tion.

     # /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 displayed.

     # /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 follow-
          ing command:

     # /usr/sbin/cacaoadm list-trusted-certs -i inst


          Example 11: Add a Trusted Certificate.
          In this example, the command adds  a  certificate  con-
          tained  in the file /tmp/trusted.cert as a trusted cer-
          tificate of the  common  agent  container'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  Common  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 Management 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 associ-
          ated 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,  -modfile3.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  iden-
          tify the path or value as an illegal option. This token
          is necessary for all subcommands whenever  a  parameter
          or  value  with an option-like name is used. The excep-
          tion 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  execut-
                             ing a root cacaoadm command



     17                      The  common   agent   container   is
                             already  running, if for example you
                             start two instances of the same com-
                             mon 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









Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments