# DataSource monitoring configuration (part 1)

These DataSource configuration items determine who can monitor and manage a DataSource application through JMX, and what objects can be monitored and managed. They apply to all DataSource applications, such as Liberator, Transformer and Integration Adapters.

You would typically monitor and manage the DataSource application from a monitoring client, such as the Caplin Management Console (CMC). The permissions grant or deny a monitoring user, such as someone logged in to the CMC, permission to invoke specific operations on the application’s MBeans.

More DataSource monitoring configuration items can be found in DataSource Monitoring Configuration (part 2).

`add-monuser` specifies the credentials that allow a monitoring client application to log into a DataSource application.

Use in: C, Java

Syntax: There are three ways to specify the credentials.

Alternative 1:

```add-monuser
roles rolename1,rolename2, ...
end-monuser```

Alternative 2:

```add-monuser
roles rolename1,rolename2, ...
end-monuser```

Alternative 3 (only applies to Liberator and Transformer):

```add-monuser
key-id akeyidentifier
roles rolename1,rolename2, ...
end-monuser```
Option Type Default Description

`user`

string

[none]

A username that the monitoring client application can use to log in to the DataSource application via JMX. If the `user` and `pass` options, or `user` and `secure-pass` options, or `user` and `key-id` options, are not specified, the DataSource application will accept monitoring login requests from any user.

`pass`

string

[none]

An unencrypted password that the monitoring client application’s user specified in `user` must supply when logging in to the DataSource application via JMX. The DataSource application uses this option to verify the user’s password.

You must specify a `pass` option, or a `secure-pass` option, or (for Liberator and Transformer only) a `key-id` option.

`secure-pass`

string

[none]

A secure encryption of the password that the user of the monitoring client application

(as specified in the `user` option) supplies when logging in to the DataSource application via JMX. The password the user enters must be encrypted before being passed to the DataSource application. The DataSource application uses this option to verify the user’s encrypted password.

The cryptographic formats supported are APR1 (an MD5-based encoding) and Unix Crypt.

You must specify a `secure-pass` option, or a `pass` option, or (for Liberator and Transformer only) a `key-id` option. The `secure-pass` option overrides the `pass` option.

`key-id`

string

[none]

The identifier of a signature key, as specified in the `key-id` option of an `add-sigkey` configuration entry.

This option can only be used in Liberator and Transformer configuration, and should be used instead of the `pass` option or `secure-pass` option when the monitoring client application is to log in using a KeyMaster user credentials token.

The Liberator or Transformer uses this option to verify the user’s user credentials token - see Using the key-id option below.

 This option is not available in Java-based DataSource applications.

`roles`

string

`*`

A comma separated list of roles that the user can have (no space separators allowed).

A role defines the JMX MBean oprations in the DataSource application that the user can invoke. Roles are associated with MBeans through `add-mon-roles` configuration items.

The wildcard role `*` grants the user permission to invoke any of the operations available on any MBeans; this is the default if no roles are specified.

If a user attempts to invoke an operation without having permission, a `SecurityException` is thrown back to the monitoring client (in the CMC the Exception is flagged in a pop-up), and, provided the DataSource application’s log-monitor-level configuration item is set to at least `INFO`, details of the user and operation are logged in the DataSource application’s monitoring log file.

In Liberator, the basic configuration file in the install kit contains the following monitoring client login credentials:

```add-monuser
end-monuser```

### Using the secure-pass option in add-monuser

Some examples:

• Here’s the configuration for a monitoring user called 'admin', with password 'admin' that’s encrypted using the APR1 algorithm:

```add-monuser
secure-pass $apr1$z71X7C20\$3B6zCqZLN.WrBWpObcPaj.
end-monuser```
• This configuration is for monitoring user 'admin2', with password 'admin' that’s encrypted using the Crypt algorithm:

```add-monuser
secure-pass hPF1s9piPZULA
end-monuser```

### Using the key-id option in add-monuser

This option can only be used in Liberator and Transformer configuration,

A monitoring client application can be designed so that it logs in to the Liberator or Transformer through KeyMaster, supplying a digitally signed user credentials token instead of a password (for example, the Caplin Management Console can do this). To allow Liberator/Transformer to handle monitoring login requests that have user credentials tokens, specify its add-monuser configuration with the options `user` and `key-id`, rather than `user` and `pass`. The value of the `key-id` option must match the key-id value in an add-sigkey configuration item:

```add-sigkey
key-id akeyidentifier
timeout 600
keyfile %r/etc/PublicKey.der
hashing-algorithm md5
end-sigkey

...
key-id akeyidentifier
end-monuser```

The `add-sigkey` item specifies a signature checking key. When the JMX enabled monitoring client application logs in, Liberator/Transformer looks for an `add-monuser` entry with a matching username and then finds the add-sigkey item that has a key-id value matching the `key-id` in `add-monuser`. It uses the `keyfile` option of the `add-sigkey` item to locate the file containing the user’s public encryption key. The Liberator’s or Transformer’s auth module can then use this public key to validate the digital signature in the user credentials token.

## mon-operation-default

The `mon-operation-default` configuration item sets the default roles (see the `role` option of add-monuser) that can invoke all the operations on all of the DataSource application’s MBeans.

Use in: C, Java

Type: string

Default value: [none]

Define the roles as a comma separated list with no spaces between the items; for example:

`mon-operation-default adminrole,superadminrole,superuserrole`

The settings of `mon-operation-default` are overridden for particular MBeans by the `operation-default` and `operation` options within add-mon-roles configuration items.

Each `add-mon-roles` configuration item refers to an MBean or set of MBeans, and specifies which roles grant permission to invoke specific operations on the MBean(s).

Use in: C, Java

Syntax: An `add-mon-roles` configuration item must contain a `beanname` option and at least one instance of `operation`, or `operation-default`.

For example:

```add-mon-roles
end-mon-roles```
Option Type Default Description

`beanname`

string

[none]

The name of an MBean object in the DataSource application, which can be monitored and/or managed. This option can also be a partial name that selects a set of MBeans. For an explanation of the formats allowed, see Beanname specifications and precedence below.

`operation`

string

[none]

The name of an operation on the MBean or MBeans selected by `beanname`, followed by a comma separated list of roles (see the role option of add-monuser). This list specifies roles (and hence users) that can potentially invoke the operation for the MBeans specified by `beanname`, subject to the precedence rules for matching `beanname`s defined in Beanname specifications and precedence below.

Example: `operation invokeMe adminrole, superadminrole`

An `operation` option overrides, for that particular operation, any `operation-default` settings in the same `add-mon-roles` block. In particular, if a role is listed in `operation-default`, but not in `operation`, that role cannot invoke the operation. For more about this, see Operation settings and their defaults below.

`operation-default`

string

[none]

A comma separated list of roles (see the `role` option of add-monuser). These roles are by default allowed to invoke all the operations on the MBeans specified by `beanname`, subject to the precedence rules for matching `beanname`s defined in Beanname specifications and precedence below.

Example: `operation-default adminrole, superadminrole`

The settings of `operation-default` are overridden by any operation settings in the same `add-mon-roles` block; see the description of the `operation` option.

## Beanname specifications and precedence

You can specify the `beanname` option of the `add-mon-roles` configuration item in one of four ways that define the precedence when matching MBeans to determine users' access to them.

### Beanname format

The general format for the beanname option follows the syntax for MBean object names:

`<domain-in-dot-notation>:<key-property-list>`

where `<key-property-list>` has the form:

`property1=value,property2=value,...`

In the examples on the rest of this page, we’ve assumed that our MBeans have just one property called `name`, which is the name of the MBean: `name=<bean-name>`

An example of a `beanname` that includes the `name` property is: `FXAdapter.example:name=bean1`

Because it has a fully specified domain and a `<key-property-list>`, this `beanname` specifies the Object Name of an MBean - the MBean called `bean1` in the domain `FXAdapter.example`

You can also define `beanname`s with only partial domains and/or no `<key-property-list>`. Such `beannames` have lower precedence when determining the access permissions that roles have to MBean operations - for more about this, see The four beanname specification types below.

 The naming convention used at Caplin is for an MBean’s domain to start with the name of the Integration Adapter, as in `FXAdapter.example`

For more about the syntax of MBean Object Names, and the conventions for them, see the Java documentation page Java Management Extensions (JMX) - Best Practices.

### The four beanname specification types

The four ways to specify `beanname`s.

#### Precedence level 4 (highest precedence)

A fully-specified domain with <key-property-list>.

```add-mon-roles
end-mon-roles```

In this example, the MBean called `bean1` in the domain `FXAdapter.example` exactly matches the `beanname`, so for this Integration Adapter, the role `adminrole` would be allowed to invoke `bean1`'s `invokeMe` operation. But if this configuration were applied to a Transformer with an MBean called `bean1` but the MBean’s domain is `Transformer.example`, there would be no match and `adminrole` would be denied access to that MBean’s `invokeMe` operation.

#### Precedence level 3

Partially specified domain with <key-property-list>.

```add-mon-roles
beanname  .example:name=bean1
end-mon-roles```

In this example, any MBean called `bean1` whose domain ends in `.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation of `FXAdapter.example:name=bean1` and `Transformer.example:name=bean1`, but would be denied access to this operation in `Transformer.example:name=bean2`.

#### Precedence level 2

Fully specified domain but no <key-property-list>.

```add-mon-roles
end-mon-roles```

In this example, any MBean in the domain `FXAdapter.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation on any MBean (that has this operation defined for it) in the `FXAdapter.example` domain. But if this configuration were applied to a Transformer where the domain is `Transformer.example`, there would be no match and `adminrole` would be denied access to the `invokeMe` operation on any of the MBeans having that operation.

#### Precedence level 1 (lowest precedence)

Partially specified domain and no <key-property-list>.

```add-mon-roles
beanname  .example:
end-mon-roles```

In this example, any MBean whose domain ends in `.example` matches the `beanname`. So `adminrole` would be allowed to invoke the `invokeMe` operation of any MBean (that has this operation defined for it) in the domains `FXAdapter.example` and `Transformer.example`

### Applying the precedence rules

If your configuration contains multiple instances of `add-mon-roles` with `beannames` of different precedences the permissions are applied to roles in the order of precedence as described above. These permissions are not additive; the permissions for a `beanname` with higher precedence always overwrite those for a `beanname` with lower precedence.

For example, consider this configuration:

```add-monuser
end-monuser

user user1
roles userrole
end-monuser

# Precedence level 1
beanname  .server.peerstats:
end-mon-roles```

Here the `add-mon-roles` configuration entry allows the role `adminrole` (and hence the user called 'admin') to invoke the `invokeMe` operation on any MBean that has this operation defined for it and that has a domain ending in `.server.peerstats`

Now consider what happens when we add another `add-mon-roles` entry with a higher precedence for the `beanname` match:

```...
# Precedence level 1
beanname  .server.peerstats:
end-mon-roles

# Precedence level 4
operation invokeMe userrole
end-mon-roles```

The second `add-mon-roles` entry has a `beanname` with both a fully specified domain and a bean object name, so it has the highest precedence (level 4) and overrides the first `add-mon-roles` entry (which has the lowest possible precedence level of 1). This new entry allows the role `userrole` (and hence the user called 'user1') to invoke the `invokeMe` operation, on the MBean called `bean1` in the `FXAdapter.server.peerstats` domain.

Because the permissions in the `add-mon-roles` entries are not additive, by default this new entry denies role `adminrole` (and any other roles) access to any of `bean1`'s operations. So to ensure that role `adminrole` can access `bean1` in domain `FXAdapter.server.peerstats`, we need to add this role to the second `add-mon-roles` entry:

```...
# Precedence level 1
beanname  .server.peerstats:
end-mon-roles

# Precedence level 4
end-mon-roles```

We add `adminrole` to the role list in the `operation` option, so that this role can access `invokeMe`.

## Operation settings and their defaults

The settings of the `mon-operation-default` configuration item, and the `operation-default` and `operation` options of `add-mon-roles` override each other in the following manner:

 `Note: mon-operation-default` is overridden by `operation-default` which is overridden by `operation`

In particular, if a role is listed in an `operation-default` option for a given `beanname` but there is also an `operation` option for the same `beanname` that doesn’t list the role, that role is denied access to the operation.

### Example of operation settings defaults

First, we define a global default:

`mon-operation-default superuserrole,adminrole,userrole`

where `mon-operation-default` allows the roles `superuserrole`, `adminrole`, and `userrole` to invoke any operations on any MBeans.

Now we modify the permissions for a specific type of MBean by adding an `add-mon-roles` entry:

```mon-operation-default superuserrole,adminrole,userrole

beanname  .server.peerstats:name=bean1
operation-default superuserrole
end-mon-roles```

The `operation-default` option allows `superuserrole` to invoke all the operations of `bean1` MBeans in domains ending in

`.server.peerstats`, but no other roles (including `adminrole` and `userrole`) can do so.

Finally, we modify the permissions for a specific MBean by adding a second `add-mon-roles` entry:

```mon-operation-default superuserrole,adminrole,userrole

beanname  .server.peerstats:name=bean1
operation-default superuserrole
end-mon-roles

This second `add-mon-roles` entry defines operation permissions for the MBean called `open` in the domain `FXAdapter.server.open`
• Because the role `userrole` is listed in the `operation-default` option, this role can perform all operations on the MBean, except `invokeMe` (see third bullet point below).
• The `operation-default` option overrides the `mon-operation-default` entry, so we have to add `superuserrole` and `adminrole` to the `operation-default` to ensure that these roles can continue to invoke operations on the MBean (other than `invokeMe`).
• The `operation` option gives role `userrole2` permission to invoke the operation `invokeMe` on the MBean, but `superuserrole`, `adminrole` and `userrole` are denied access to `invokeMe` because these roles aren’t listed in the option`.`