Here are some examples of how to configure a DataSource application so that users can monitor its state through a JMX monitoring client, such as the Caplin Management Console. Monitoring configuration applies to all DataSource applications, such as Liberator, Transformer and Integration Adapters.
Want some background to all this first? See Features and concepts of DataSource monitoring and management. And for detailed information about all the monitoring configuration items, refer to the Reference documentation: DataSource monitoring configuration.
|One other thing you need to know before looking at the examples: in DataSource applications built with the current (version 6.1) releases of the DataSource APIs (Caplin Integration Suite, C DataSource API), all monitoring users can read all MBean attributes, though they can’t write to them. So there’s no configuration that controls access to attributes.|
Example 1: Basic monitoring configuration
Here’s an example of some basic monitoring configuration for an Integration Adapter.
You’d add the configuration to the Adapter blade’s configuration file in
monitor-plugin jmx monitor-moddir %r/DataSource/lib process-usage-period 20 log-monitor-level NOTIFY
monitor-plugin jmxis mandatory. It specifies that the JMX monitoring module is to be loaded into the Integration Adapter.
monitor-moddirdefines the directory where the DataSource application’s JMX monitoring module is located. The %r marker causes the Deployment Framework to prefix the directory with the root directory of the Adapter installation; for example forming the directory /MyAdapterBlade/DataSource/lib
process-usage-perioddefines the time interval in seconds at which the Adapter’s CPU time counters
system-cputime-totalare updated. These counters can be viewed through JMX monitoring. Here the time interval’s been doubled to 20 seconds (the default is 10 seconds) to reduce the amount of data transmitted to the monitoring client.
log-monitor-levelspecifies the threshold at which log messages about the Adapter’s events and errors are published to the monitoring subsystem, to be viewed by a monitoring client. Here we’ve set the level to
NOTIFY, which is a lower threshold than the default setting of
INFOand so reduces the amount of data transmitted to the monitoring client.
Example 2: Adding monitoring users and roles
Taking the configuration of Example 1, we need to the add some user credentials that will allow designated users to monitor the Adapter through a monitoring client. Here we add two users:
admin, with a secure (encrypted) password,
adminpass, can read the attributes of the Adapter’s MBeans and invoke any operation on any MBean.
guest, with a non-secure password,
guestpass, can only read the attributes of the Adapter’s MBeans, and can’t invoke any operations.
The additional configuration looks like this:
... add-monuser user admin secure-pass $apr1$twr9ykne$grsfePTtmxi76iD3iUF651 roles adminrole end-monuser add-monuser user guest pass guestpass roles guestrole end-monuser mon-operation-default adminrole
add-monuserconfiguration item defines the
adminuser’s user name (
user admin), the APR1 encrypted password (
secure-pass $apr1$twr…), and a role for the user (
roles adminrole) that determines the
adminuser’s access permissions to the Adapter’s MBeans.
add-monuseritem defines the same set of things for the
guestuser, but this time the password definition isn’t encrypted (
pass guestpass), and the user has a different role (
roles guestrole), because they are to be given different permissions.
The default permission setting for MBean operations is that a user role is barred from invoking an operation unless it’s explicitly given permission. The
mon-operation-defaultconfiguration item overrides this default for users with the role
adminrole, so the
adminuser, who has this role, can invoke any operations on any of the Adapter’s MBeans. The
guestuser doesn’t have the
adminrole, so (by default) can’t invoke any operations on any MBeans;
guestcan only read the MBean attributes.
Example 3: Granting extra access permissions
Now we expand Example 2 to allow the
guest user to invoke any operations on a specific MBean.
Assume the Adapter has an MBean with Object Name
myadapter.server.peerstats:identifier=0 and this bean has the operations
set-monitoring-interval. To enable the
guest user to invoke any of these operations on just this particular bean, add an
add-mon-roles configuration item that includes the
... mon-operation-default adminrole add-mon-roles beanname myadapter.server.peerstats:identifier=0 operation-default adminrole,guestrole end-mon-roles
beannameoption specifies the MBean that we want to give the extra permissions to.
operation-default …specifies the role
guestrole, so this role (and hence the
guestuser) can invoke all the operations on this MBean.
adminroleappear in the
operation-defaultoption as well?
This is because the permissions granted in the various configuration items are not additive, and in this case, the
operation-defaultoption overrides the
mon-operation-defaultitem. So although the
adminrolethe ability to invoke any operation on any MBean, if we just used
operation-default guestrole, the absence of
adminrolein this option would by default prevent
adminrolefrom invoking operations on the specified MBean. Adding
operation-default's role list preserves that role’s access permissions for the MBean operations.
If you subsequently added another role to
mon-operation-default, you’d also have to add it to the
operation-defaultoption in the
add-mon-rolesitem so that the new role could invoke all operations on the MBean.
Note that there mustn’t be any spaces in the comma-separated list of roles:
Example 4: Reducing access permissions
Starting from Example 3, we’ll restrict
guestrole's access to the operations on the MBean with Object Name
Now we only want
guestrole to be able to invoke this MBean’s
reset-counters operation, and we want to deny it access to the
The configuration you need looks like this:
... mon-operation-default adminrole add-mon-roles beanname myadapter.server.peerstats:identifier=0 operation reset-counters adminrole,guestrole end-mon-roles
operationoption explicitly grants
guestrolepermission to invoke the MBeans’s
We’ve removed the
guestrolecan’t invoke any other operations on the MBean.
adminroleappear in the
For the same reason we put it in the
operation-defaultoption in Example 3 - the
operationoption overrides the
mon-operationoption and therefore we have to explicitly include
operationoption so it can continue to invoke
reset-counterson the MBean as well as
Example 5: Restricting developers' access to MBean operations
In this example, we have a Liberator, Transformer and two Integration Adapters (A and B). The Liberator has some MBeans in the domain
rttpd.server.peers: that allow users monitoring the Liberator to invoke operations affecting the connections to the Transformer and the Integration Adapters.
The MBeans in the domain
rttpd.server.peers:peer-number=0(MBean relating to connections to the Transformer)
rttpd.server.peers:peer-number=1(MBean relating to connections to IntegrationAdapter A)
rttpd.server.peers:peer-number=2(MBean relating to connections to IntegrationAdapter B)
There are three roles:
adminRolecan invoke any operations on the Liberator MBeans.
peerManagerRolecan invoke operations only on the MBeans in the domain
devRoleis for developers who are working on IntegrationAdapterA; they can invoke only certain operations on the MBeans relating to the connection to IntegrationAdapterA.
|What’s the significance of the term 'peer'? This is explained in the DataSource Overview.|
Here’s the Liberator’s monitoring configuration for
You’d normally add the configuration to the jmx.conf file in the Deployment Framework’s overrides file for the Liberator:
We allow the
adminRole to invoke operations on all the Liberator’s MBeans, and the
peerManager role to invoke operations only on the MBeans that are in the domain
mon-operation-default adminRole add-mon-roles beanname rttpd.server.peers: operation-default adminRole,peerManagerRole end-mon-roles
As in the previous examples, we’ve had to add
adminRoleto the role list in the
operation-defaultoption so that this role can continue to invoke operations on the MBeans in the domain
mon-operation-defaultfor these MBeans).
Adding permissions for developers
So far, users with role
devRole only have read access to the
rttpd.server.peers: MBeans. Now say IntegrationAdapterA is under development, whereas IntegrationAdapterB and the Liberator and Transformer aren’t. We want developer users to be able to invoke the MBean operations called
set-down relating to IntegrationAdapter A, for testing purposes. The
set-down operation makes the Liberator disconnect from the Integration Adapter, and
set-up makes it reconnect. We don’t want developer users to be able to invoke these operations on the connections to the other Adapter or the Transformer.
We add the following configuration to the Liberator:
add-mon-roles # MBean relating to the DataSource peer IntegrationAdapterA beanname rttpd.server.peers:peer-number=1 operation set-up adminRole,peerManagerRole,devRole operation set-down adminRole,peerManagerRole,devRole end-mon-roles
We’ve explicitly identified the Liberator MBean relating to IntegrationAdapterA
devRoleto invoke the MBean’s
devRolecan’t invoke any other operations on this MBean or on any other MBeans.
As in the previous examples, we’ve added
peerManagerRoleto the role lists in the
operationoptions, so they can continue to invoke the
set-downoperations on the MBean.