Download PDF
Home

1. Administration

1.1. 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.

Tip 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.

1.1.1. 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.

1.1.2. 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.

1.1.3. 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.

1.1.4. 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.

1.1.5. 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

1.1.6. 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

1.1.7. 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.

1.2. Managing Users

Caution 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.

1.2.1. 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.

1.2.2. 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.

1.2.3. 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.

1.2.4. 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.

1.3. Managing Roles

Caution 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.

1.3.1. 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.

1.4. 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.

1.4.1. 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.

1.5. Managing Access Keys

1.5.1. 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.

1.6. 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.

1.6.1. 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.

1.6.2. 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.

1.6.3. 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

1.7. 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.

Tip Scopes are cumulative by convention. For example, the ivt.elment scope includes the ivt.element.settings scope.
Caution 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.

2. Managing Jobs

RBMS includes a job scheduler used by the network management applications to run management jobs. A job is a set of tasks that are executed in a specified order.

The task execution flow is defined by the application creating the job. Tasks can be executed sequentially or in parallel. Parallel execution flows can be joined to continue with a single flow. Technically speaking a job is described as state engine. Each task represents a node in the the state engine. The transition between tasks form the execution flow.

The figure below shows a simplified execution flow for a fabric upgrade.

jobs overview

The Pre-Upgrade Check task runs all checks to test whether the fabric can be upgraded. If the fabric passes all checks the execution flow is splitted to run the Spine 1 Upgrade and Spine 2 Upgrade in parallel. The Post-Upgrade Check waits for both upgrades to be completed before it runs the checks to test whether the upgrade was successful. If both switche upgrades were successful the job upgrades the two remaining switches in parallel. Finally another Post-Uograde Check is executed to check whether the upgrade was successful.

An application can program a job task to wait for an explicit confirmation. For example, an operator might want to inspect the state of a switch when a new image has been installed the very first time in the network. The upgrade application can program the first post-upgrade check to wait for confirmation before proceeding with the next upgrade.

The job module is a generic job viewer to inspect the state and progress of scheduled jobs. It also allows to confirm that a job can continue.

2.1. Viewing job list

To view the list of jobs

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Optinally filter the job list by job name. The job name can be specied as prefix, full name of regular expression.

jobs list filtered

2.2. Viewing job task list

To view the list of job tasks

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to view. The Job Tasks page appears.

jobs task list

2.3. Viewing task flow

The task flow enables you to inspect taskflow and progress of the selected task.

To view the list of task flow

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to view.

  3. Click Flow in the left navigation pane. The Taskflow page appears.

jobs task flow

2.4. Viewing task details

To view the task details

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to view. The Job Tasks page appears.

  3. Click the name of the task that you want to view. The Job Task page appears.

jobs task

2.5. Canceling a Job

To cancel a job

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to view.

  3. Click Tasks in the left navigation pane. The Job Tasks page appears.

  4. Click Cancel job. The job state changes to cancelled.

jobs cancelled job

2.6. Removing a Job

To remove a completed, cancelled or failed job

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to view.

  3. Click Tasks in the left navigation pane. The Job Tasks page appears.

  4. Click Remove. A confirmation dialog is displayed.

  5. Click Confirm to remove the job.

2.7. Configuring Job Settings

To configure the job settings

  1. Click the Jobs tab. The list of currently active or scheduled jobs appear.

  2. Click the name of the job that you want to configure.

jobs settings
  1. Make necessary configurations for the job.

  2. Click Save settings.


©Copyright 2022 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrickā€™s Term of Use Policy, available at https://www.rtbrick.com/privacy. Use of marks belonging to other parties is for informational purposes only.