Administration

Managing Webhooks

A webhooks is a registered HTTP endpoint that forwards notifications from RBMS to an external endpoint.

rbms webhooks overview

RBMS stores a domain event if a status in RBMS has changed. An event is only created when the transaction was comitted. An event is not fired when the transaction rolls back.

The events are grouped in different topics:

  • element, the element topic contains all element-related messages

  • image, the image topic contains all image-related messages

An event has a descriptive name that describes what state change is being reported. All events have a unique ID to identify different instances of the same event unambiguously.

For example, the ElementRenamedEvent informs about an element being renamed. The event is stored in the element topic.

A webhook subscribes a topic and calls the configured endpoint for all events that match the specified name filter. By default, the message send to the endpoint contains the JSON representation of the domain event. An optional template allows rewriting the event message.

The authentication can be done via HTTP Basic Authorization or bearer token. RBMS stores the provided credentials AES-protected in the database.

The AES secret and initialization vector (IV) can be specified in the master.secret and master.iv environment variables.

Unauthenticated endpoint calls are also supported.

A webhook invocation is considered successful if a HTTP success family status code is returned. For all other status codes the invocation is considered as failed.

A webhook can retry all failed messages. In addition, a webhook can be reset to a certain message to process this message and all subsequent messages again.

The complete message processing lifecycle is shown below:

rbms webhook message lifecycle

New domain event messages are READY for being processed. The state changes to IN PROGRESS when the processing has begun and eventually to PROCESSED if the endpoint processed the message successfully and to FAILED otherwise respectively.

A webhook can be disabled to temporarily suspend the event processing. All events that occured while the webhook was disabled are processed when the webhook gets enabled again unless the event got dropped because the topic buffering capacity was exceeded.

Viewing Webhooks

To view the list of webhooks

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Click the name of the webhook that you want to view.

Adding Webhooks

To add a webhook

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Click Add webhook

  4. Specify the general, subscription and authentication information about the webhook.

  5. Click Save webhook.

Disabling a Webhook

To disable a webhook

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Select the webhook to be disabled.

  4. Click Disable webhook.

Enabling a Webhook

To enable a webhook

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Select the webhook to be enabled.

  4. Click Enable webhook.

Reset a Webhook

To reset a webhook

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Select the webhook to be reset.

  4. Click Message Queue in the left navigation pane. The list of the last 100 processed messages appear.

  5. Enter the event ID in the Filter field and click Filter.

  6. Open the displayed message.

Message detail

  1. Click Reset webhook to process the message and all subsequent messages again. The message queue view appears.

rbms webhook resetlist

Viewing Webhook Statistics

The webhook statistics provides information about processing times and the message count grouped by the processing state.

To view the webhook statistics

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Select the webhook for which to retry the failed invocations.

  4. Click Statistics in the left navigation pane. The webhook statistics appear.

rbms webhooks statistics

Retrying Failed Webhook Invocations

To retry failed webhook invocations

  1. Click the Administration tab.

  2. Click Webhooks in the left navigation pane. The list of all webhooks appear.

  3. Select the webhook for which to retry the failed invocations.

  4. Click Statistics in the left navigation pane. The message statistics appear.

rbms webhooks statistics

  1. Click Reset failed messages to reset all failed messages to ready state.

Managing Users

This section outlines how to manage users in the RBMS built-in user repository. If RBMS is connected to an authorization service the users are configured in the authorization service.

Viewing all existing users

To view all existing users

  1. Click the Administration tab.

  2. Click Users in the left navigation pane. The list of all existing users appear.

admin users

  1. Click the name of the user whose details you want to view.

Adding users

You can add a new users to the user repository.

To add a user

  1. Click the Administration tab.

  2. Click Users in the left navigation pane. The list of all existing users appear.

  3. On the Users page, click Add user.

  4. Specify user details such as username, password, and access token.

  5. Click Add user.

Removing users

To remove a user

  1. Click the Administration tab.

  2. Click Users in the left navigation pane. The list of all existing users appear.

  3. Click the name of the user whom you want to remove.

  4. On the User Settings page, click Remove user.

Resetting Password

To reset a user password

  1. Click the Administration tab.

  2. Click Users in the left navigation pane. The list of all existing users appear.

  3. Click the name of the user whom you want to remove.

  4. On the User Settings page, click Reset password. The Reset Password page appears.

  5. Enter the new password.

  6. Re-type the new password in order to detect accidental typos.

  7. Click Reset Password.

Managing Roles

This section outlines how to manage roles in the RBMS built-in user repository. If RBMS is connected to an authorization service the roles are be configured in the authorization service. See Scopes for more information about the existing acccess scopes.

Viewing list of roles

To view the list of roles

  1. Click the Administration tab.

  2. Click Roles in the left navigation pane. The list of all existing users appear. image::admin_roles.png[]

  1. Click the role that you want to view or modify.

Creating Roles

To create a role

  1. Click the Administration tab.

  2. Click Roles in the left navigation pane. The list of all existing users appear.

  3. On the Roles page, click Add role.

  4. Specify the details of the new role such as role name, Accessible Resource Scopes, and description.

  5. Click Add role.

Removing roles

To remove a role

  1. Click the Administration tab.

  2. Click Roles in the left navigation pane. The list of all existing roles appear.

  3. Click the role that you want to remove.

  4. On the Role <rolename> page, click Remove role.

Managing Access Keys

Viewing list of access keys

To view the list of all existing access keys

  1. Click the Administration tab.

  2. Click Access Keys in the left navigation pane. The list of all existing access keys appear.

admin access keys

  1. Click the name of the access key that you want to view or modify.

Creating Access Keys

To create an access key

  1. Click the Administration tab.

  2. Click Access Keys in the left navigation pane. The list of all existing access keys appear.

  3. On the Access Keys page, click Add access key.

admin access keys add

  1. Specify the details of the new access key such as key name, scopes, and description.

  2. Click Create access key.

Revoking an access key

To revoke an access key

  1. Click the Administration tab.

  2. Click Access Key in the left navigation pane. The list of all existing access keys appear.

  3. Click the access key that you want to revoke.

  4. On the <access key name> accesskey page, click Revoke access key.

Validating an access key

The validating access key feature enables you to validate an encoded access key.

To validate an access key

  1. Click the Administration tab.

  2. Click Access Key Validator in the left navigation pane.

admin access keys validator

  1. In the Access Key text box, enter the access key to be validated.

  2. Click Validate.

Restoring an revoked access key

To restore an accidentally revoked access key

  1. Click the Administration tab.

  2. Click the Access Key Validator in the left navigation pane.

  3. Paste the access key to be restored in the text area.

  4. Click Validate.

admin access keys revoked

  1. Clicke Restore to restore the revoked access key.

admin access keys restored

Scopes

Access to RBMS is granted through an access token. The access token is either issued by an OAuth2 compliant authorization service or by RBMS itself, depending on whether RBMS delegates to an authorization service or the RBMS built-in user repository is used.

The access token conveys the list of scopes the user is allowed to access. The table below lists all existing scopes:

Scope

Description

adm

Full access to the RBMS administration API and UI.

adm.read

Readonly access to the RBMS administration API and UI.

adm.accesskey

Full access to the RBMS access key administration API and UI.

adm.accesskey.read

Readonly access to the RBMS access key administration API and UI.

adm.user

Full access to the RBMS user management API and UI.

adm.user.read

Readonly access to te RBMS user management API and UI.

adm.webhook

Full access to the RBMS webhook management API and UI.

adm.webhook.read

Readonly access to the RBMS webhook management API and UI.

ctrld

Full access to all CTRLD actions that can be triggered from RBMS.

ctrld.reinstall

Permission to trigger CTRLD to run ZTP sequence for an software image upgrade again.

ctrld.settings

Permissions to update the CTRLD settings on the switch via RBMS.

ivt

Full access to the resource inventory.

ivt.read

Readonly access to the resource inventory.

ivt.element

Manage elements in the resource inventory.

ivt.element.settings

Manage element settings in the resource inventory.

ivt.element.config

Manage element configuration in the resource inventory.

ivt.element.dns

Manage element DNS records in the resource inventory.

ivt.element.module

Manage element hardware module information in the resource inventory.

ivt.group

Manage element grouos in the resource inventory.

ivt.group.settings

Manage element group settings in the resource inventory.

ivt.image

Manage software images in the resource inventory.

ivt.rack

Manage racks in the resource inventory.

job

Full access to the RBMS job API and UI.

job.read

Readonly access to the RBMS job API and UI

job.task

Manage job tasks via RBMS Job API or UI.

tmy

Full access to the RBMS metric API and UI.

tmy.read

Readonly access to the RBMS metric API and UI.

tmy.metrics

Full access to manage RBMS metrics.

tmy.metrics.read

Readonly access to metrics.
Scopes are cumulative by convention. For example, the ivt.elment scope includes the ivt.element.settings scope.
For UI access always grant the read scope in combination with a specific write scope to avoid trouble. For example, grant ivt.element.settings in combination with ivt.read. Otherwise a user might not be able to navigate to the view to apply the changes.