cacaourl(5) Standards, Environments, and Macros cacaourl(5)NAMEcacaourl - Use the common agent container's JMX service URL to connect
to a common agent container daemon
SYNOPSIS
service:jmx:cacao-rmi://<host>[:<port>][;<key1>=<value1>;<key2>=<value2>;...]
DESCRIPTION
A JMX Service URL is an abstract service URL for SLP, as defined in RFC
2609, and amended by RFC 3111. This man page describes the format of
the JMX Service URLs used by the common agent container's administra‐
tion command, cacaoadm, or by any generic JMX client, such as JConsole,
each time they want to address and connect to the common agent con‐
tainer.
The syntax of the JMX Service URLs supported by the common agent con‐
tainer is: /service:jmx:cacao-rmi://<host>[:port][attrs]/
The syntax of the JMX Service URL specifies the cacao-rmi protocol
where communication is encrypted by means of the Transport Layer Secu‐
rity (TLS) protocol. The servers use a public certificate and private
key, the clients are authenticated by sending a username/password chal‐
lenge or their own certificate and a valid system identity.
The attributes referred to as [attrs] here are in fact sets of
key=value pairs separated by semi-colons.
OPTIONS
The following options are supported.
-host This parameter is the host name of the machine on which the
common agent container you want to contact is running. It is
either an IPv4 numeric host address, or an IPv6 numeric
address enclosed in square brackets.
-port This parameter is a decimal port number of the common agent
container to contact. If no port is specified, the default
port is used.
-attrs This parameter contains one or more attributes. Each
attribute begins with a semicolon and consists of a key and
an optional value. The key is one or more letters or digits,
where the first is a letter. The value, if any, is preceded
by an equals character (=) and continues to the end of the
address or the next semicolon (;). If there is no equals
character, then the value is the string "true".
Keys and values may be encoded using URL encoding, special characters
being represented by a percent sign followed by 2 hexadecimal digits.
The same attribute key can appear more than once in the attrs. The
value associated with the last key occurrence is the one that is
retained.
Case is not significant in the initial /service:jmx:cacao-rmi string or
in the host part of the address. Case is significant in attribute keys.
Case is sometimes significant in an attribute value depending on the
attribute.
Supported keys are as follows:
o wellknown - boolean with default value of false. If the key
is set to true, the client sends it public certificate. If
the wellknown key is set to false, the client needs to pro‐
vide a password key.
o trustserver - the trustserver key. This is a boolean with a
default value of false. Use of trustserver means that pass‐
words are transmitted to the named host without having veri‐
fied the public certificate that was received from the com‐
mon agent container during the initialization of the connec‐
tion. This is a potential security risk and must be used
only for development purposes.
For unknown clients providing system user credentials, thanks to the
connection environment mapping:
com.sun.cacao.rmi.username=username
com.sun.cacao.rmi.userpass=userpass
For unknown clients providing system user and role credentials (Solaris
only), thanks to the connection environment mapping:
com.sun.cacao.rmi.username=username
com.sun.cacao.rmi.userpass=userpass
com.sun.cacao.rmi.rolename=rolename
com.sun.cacao.rolepass=rolepass
For wellknown clients, only a system identity needs be provided in the
connection environment map:
com.sun.cacao.rmi.username=username
Define the following key in the common agent container's JMX service
URL:
wellknown=true
As noted, the rolename and rolepass keys are supported only on the
Solaris OS.
ENVIRONMENT VARIABLES
The common agent container's JMX Service URL can have a connection
environment composed of key value pairs.The following keys are sup‐
ported:
o com.sun.cacao.wellknown - boolean with default value of
false. If the wellknown key is set to true, the client sends
it public certificate. If the wellknown key is set to false,
the client needs to provide a password key.
o com.sun.cacao.username - the system identity that the client
wants to authenticate
o com.sun.cacao.userpass - the system user's password to
authenticate the username
o com.sun.cacao.rolename - the system role (Solaris only) to
authenticate
o com.sun.cacao.rolepass - the system role password (Solaris
only) to authenticate
o com.sun.cacao.trustserver - the trustserver key. This is a
boolean with a default value of false. Use of trustserver
means that passwords are transmitted to the named host with‐
out having verified the public certificate that was received
from the common agent container during the initialization of
the connection. This is a potential security risk and must
be used only for development purposes.
o com.sun.cacao.ssl.truststore.file - the path to the trust‐
store file used by the client to verify the agent's certifi‐
cate. The default value is /usr/sbin/cacaoadm/instance‐
name/security/jsse/truststore
o com.sun.cacao.ssl.truststore.password - the password pro‐
tecting the truststore. The default value is trustpass.
o com.sun.cacao.ssl.keystore.file - the path to the keystore
file used by the client. Useful only if the client sends its
own certificate to be authenticated by the common agent con‐
tainer. The default value is /usr/sbin/cacaoadm/instance‐
name/security/jsse/keystore
o com.sun.cacao.ssl.keystore.password - the password protect‐
ing the keystore used by the client. No default value.
o com.sun.cacao.ssl.keystore.password.file - the path to a
file containing the password protecting the keystore and all
its entries. Default value is /usr/sbin/cacaoadm/instance‐
name/security/password
o com.sun.cacao.config.dir — the configuration directory you
use to get the default values for all the other keys when
they are not defined themselves. The default value is the
directory of the default instance, that is,
/usr/sbin/cacaoadm/default. The expected value looks like
/usr/sbin/cacaoadm/instancename and must match the configu‐
ration directory of a local instance of the common agent
container.
o jmx.remote.credentials - the public and private credentials
used to authenticate the user. If this key is used, its
value must be an array of strings with two elements in each:
o The first element is equivalent to com.sun.cacao.user‐
name
o The second element is equivalent to com.sun.cacao.user‐
pass
Other keys are not supported. How you set up your environment with
those keys depends on the client you are using. For keys that you do
not define explicitly, default values are used.
Parameter keys map to connection environment keys quite simply: they
are identical, but connection environment keys start with
com.sun.cacao. For example, for the trustserver parameter key , the
equivalent connection environment key is com.sun.cacao.trustserver.
Any parameter key attribute that you specify in the URL can be replaced
by an equivalent environment key entry. For example, if you specify
that wellknown=true in the URL, this is as if you set the
com.sun.cacao.wellknown environment key value to be =true. If you spec‐
ify that wellknown=true in the URL, the value of the
com.sun.cacao.wellknown environment key is not overwritten - it is dis‐
regarded.
In summary, if a parameter value is declared in the URL, it always
supercedes the equivalent entry in the connection environment.
EXAMPLES
Here are some examples to help you understand how to use the JMX Ser‐
vice URL function.
Example 1.
This example uses the Service URL to connect to an agent with the
unknown mode. The user name and password are provided through environ‐
ment properties:
com.sun.cacao.rmi.username=username
com.sun.cacao.rmi.userpass=userpass
If the user does not exist or if the password is wrong, the connection
is refused. In this example the Service URL uses the default port.
service:jmx:cacao-rmi://localhost;wellknown=false
Example 2.
This examples uses the JMX Service URL function to connect to an agent
using the wellknown mode. The user name and password are provided
through environment properties:
com.sun.cacao.rmi.username=username
In this example the connection is to host host1 and uses port 11355.
service:jmx:cacao-rmi://host1:11355;wellknown=true
Example 3.
This example is similar to example 2, except in this case you do not
need to import the agent certificate into your truststore to establish
the communication with the common agent container's agent.
service:jmx:cacao-rmi://host1:11355;wellknown=true;trustserver=true
Example 4.
This example is similar to the previous one but this example uses the
rolename and rolepass attributes. These attributes are based on having
an RBAC user defined on your system. This feature is available only on
Solaris. Environment properties are:
com.sun.cacao.rmi.username=username
com.sun.cacao.rmi.userpass=userpass
com.sun.cacao.rmi.rolename=rolename
com.sun.cacao.rmi.rolepass=rolepass
The URL is:
service:jmx:cacao-rmi://localhost;wellknown=false
ATTRIBUTES
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcacaort │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSO
cacao.5, cacaoadm.1m
Oracle Solaris May 2010 cacaourl(5)