¶ RioBroker Introduction
RioBroker is a new addition to BlackPearl that offers a greatly simplified API and reduces the amount of effort required to integrate across a broad range of applications needed by customers. RioBroker is a remote I/O broker that allows data movement into the BlackPearl through a simplified RESTful API. RioBroker operates as BlackPearl’s front-end, allowing for other applications to integrate into RioBroker rather than directly into the BlackPearl.
Applications to download:
RioBroker – Available at https://developer.spectralogic.com/rio
Postman – Used for API commands to RioBroker (Available via Google search)
Dummy File Creator – Creates dummy files of any size for testing (Available via Google search) Before you begin
- Make sure you have Administrator access to the server(s) that RioBroker will be installed on and the BlackPearl. RioBroker system requirements are as follows:
- RioBroker is only available for 64-bit Microsoft Windows operating systems. RioBroker is compatible with:
- Windows Server 2019
- Windows Server 2022
- The host server must meet the following requirements:
- Six processor cores
- 64GB RAM
- 500GB SSD disk space
- 10Gb/s network connection to both the BlackPearl system data port(s) and production storage
- RioBroker is compatible with BlackPearl software versions 4.1.x and 5.x
- Work with the end-user to identify a naming convention for all entities in RioBroker and BlackPearl. The naming convention will be used for adding devices to RioBroker as well as creating buckets. This will help the end-user navigate easily to these folders after Spectra has installed all programs.
¶ Install Rio Broker:
Download the latest RioBroker installation Spectra Logic Developer site under “RioBroker MSI” and accept the default options.
When complete, you can verify successful installation by checking to see if the service is running.
Note that the user account under which the RioBroker service is running must have file path access to the files on the source storage system (unless they are accessing the files via FTP or S3). To change the user account for the service, go to Administrative Tools > Services in Windows, find the service called “Spectra RioBroker Broker Server”, and double click. Click on the “Log On” tab, select “This account”, and enter the new user account information. Restart the service when done.
¶ Install PFR If required:
An install guide can be found here:
Also, see the PFR page
¶ About the API:
A complete description of the API is available here: https://developer.spectralogic.com/rio/
¶ RioBroker Setup
RioBroker can be configured in two different ways: A restful client (we recommend Postman) or the RioBroker web management interface. This guide will cover how to configure RioBroker through the web management interface.
In a web browser on the server where RioBroker is installed, navigate to https://localhost:5050
Set up the cluster:
RioBroker will ask to be joined to a new or existing cluster. Currently, only one server cluster is allowed in this release. RioBroker will support multi-server clusters in a future release.
Click New, create a cluster name, click submit. The program will load for a minute while it creates the cluster.
Once the cluster has been created, a login screen will pop up. Login using:
Username: spectra
Password: spectra
¶ Navigating RioBroker Interface
¶ Dashboard
The dashboard is the primary screen for RioBroker. The dashboard will show the status of Cluster members and Spectra devices, how many current active archive or restore jobs there are, and the amount of configured devices and brokers there are.
¶ Job Status
The job status screen displays information about all jobs that RioBroker has handled. There are four tabs: Active, Completed, Canceled, and Failed. When an active job is completed, it will automatically clear from the active tab and move into the corresponding tab
¶ Search
Search allows for you to search configured brokers for files that have been archived and indexed through RioBroker.
¶ Settings
The settings menu allows you to configure or access information for the system, cluster, devices, and brokers.
¶ Adding BlackPearl to RioBroker
Navigate to Settings (gear icon) -> Devices
This page automatically starts off on Spectra Devices. Click new and fill in the information Note that the “Name” field value is arbitrary but will be used in later steps.
Sample settings for connecting to a real BlackPearl (not for BlackPearl simulator):
Sample settings for connecting to a BlackPearl simulator (note port 8080 for data path):
Once this is done, the BlackPearl will be added into RioBroker.
¶ Creating a Broker
Click on the Gear Icon and go to “Brokers” and click new. A popup window will appear to add Broker information.
The Broker and Agent name can be named anything but is a best practice for both to use the same name as the bucket name. Also, note that RioBroker will change any name to all lower case. The BlackPearl name needs to match the name you gave the BlackPearl under Devices. The username is the username used to log into the BlackPearl and the bucket will be the bucket you created on BlackPearl for testing purposes. You must create the bucket on BlackPearl before creating the broker.
¶ Verifying RioBroker connectivity to the BlackPearl & Transferring Files
To verify that RioBroker is connected to the BlackPearl, and to transfer files, Postman will need to be utilized. Postman is able to interact with RioBroker using its HTTP-based API commands. This document will walk through basic commands in Postman to verify the RioBroker is correctly working. All RioBroker API commands can be viewed in a web browser from the server that is running RioBroker at https://localhost:5050/api/viewer/index.html.
Note: In the Postman settings ensure that you turn off “SSL certificate verification” as shown below:
¶ Authentication
An Authentication token first needs to be generated by calling the RioBroker API using Postman. This call is shown in the screen image below. Authentication tokens expire in 1 hour, but tokens can be generated as often as needed during testing.
The command to get a token is https://localhost:5050/api/tokens with a selection of “POST” in the dropdown to the left of the Address field.
The body needs to include the username and password for RioBroker as shown below.
Note the selection of “raw” and “JSON (application/json)”. These settings will be used for all calls to RioBroker.Once this information is filled in, hit the Send button and a token will be generated as shown below.
To input the token for the next RioBroker call, click on the “Authorization” tab. Type will be Bearer Token, and then on the right-hand side, the token can be pasted into the field.
Note: Each new call in Postman will need to have the token pasted into the authorization field.
¶ Archiving a File
We recommend starting with a small text file to test archiving and restoring. The POST command in Postman will be https://localhost:5050/api/brokers/{brokername}/archive
A basic archive will need the file name and the URI path to the file as shown in the image below.
Be sure to put the test file in a location where the user under which the RioBroker is running has access. Once the command is sent, the following information will be returned from RioBroker about the job.
To check a file is successfully archived, either the RioBroker GUI or Postman can be used.
- If using the RioBroker web interface, click on Job status in the left navigation, and then click on completed jobs. If the archive was successful, you should see the job under completed jobs. If the file is not there, then check under failed jobs. Failed jobs will give some information about why the job failed. More information about why a job failed can be found in the RioBroker logs.
- If utilizing Postman, open a new tab and create a GET command. The command will be https://localhost:5050/api/jobs/{jobId}. The output will list the Job ID, creation date, last updated date, and the status of that job.
¶ Restoring a File
Restoring a text file follows the same process as an archived file with two exceptions.
- The POST command will be https://localhost:5050/api/brokers/{brokername}/restore
- The file URI will need to be directed to a different location than from where the file is stored or if restoring to the same folder, the file will need to have a different name. It is a best practice to create a separate restore folder on the C: drive
Full documentation on all API commands can be found at https://localhost:5050/api/viewer/index.html
Contact the Spectra Logic Developer Program at https://developer.spectralogic.com/contact if you require additional assistance.