Skip to content

Websocket Access

A web socket is provided to retrieve a stream of events. This can be accessed by hitting a URL in the form of:

https://<IP>:<API_PORT>/api/v3/ws?Token=<AUTH_TOKEN>

The URL will require authentication, but once authorized, the resulting web socket will receive events.

Events can be filtered by submitting register filters to the websocket listener.

Register for Events

The events desired must be registered for. This is done by sending a register request to the server. By sending, register *.*.*, this will cause all events that the authorized user can see to be delivered to the websocket receiver.

Multiple registers (and the corresponding deregister) are allowed.

The general form is:

register type.action.key

The fields are:

  • Type - the type of object (e.g. profiles, machines, ...)
  • Action - the action of the object (e.g. create, save, update, destroy, ...)
  • Key - the specific key of the object (e.g. machine uuid, profile name, ...)

Some simple example are provided in the DRP source tree:

Deregister Events

If you no longer wish to receive specific events you have registered for, you may use the deregister command. The command syntax is exactly like the register command.

The general form is:

deregister type.action.key

Websocket Tools

Most modern languages provide websocket libraries that you can use to create listeners in a given language. Some examples include (this is not an exhaustive list):

There are several extensions/add-ons for web browsers that will allow you to do basic testing of websocket listening. Here at RackN, we have used the following with some success:

There is a simple sample Python script available in the Digital Rebar Provision repo for reference, see the Websocket Integrations: page for further details.

Monitoring Connections

Digital Rebar has an API endpoint for listing active websocket and REST Connections under GET /api/v3/connections. This list of connections contains information such as create time, principal, address, and if the connection is a websocket.

Connections for specific machines can be accessed via GET /api/v3/machines/:uuid/connections. Clusters and Resource brokers have the similarly named API endpoints.

New connections and disconnections can be monitored by the connections.create.<principal> event. This is useful as individual runner connections can be monitored with connections.create.runner:<uuid>

A combination of the machine connections API endpoint and connection events can be used to monitor a relative "online" state of a machine's runner, a user's portal session, or the connectivity of a plugin.

Note

While connection events come in with Principal for the event key, connections are unique by RemoteAddr. This is because Principal, while not unique, is more useful. RemoteAddr is used as the key for GET /api/v3/connections/:RemoteAddr

Example Information

Here is a simple walk through of basic testing on how to use websockets with Digital Rebar. Please note this is fairly basic, but it should get you started on how to interact with and use websockets. This example was tested, using the " Simple Websocket Client" in both Chrome and Firefox that is listed above.

We assume you have the DRP endpoint installed on your localhost in these examples. You can adjust the IP address/hostname to point to a remote DRP Endpoint, just ensure you have access to Port 8092 (by default, or the API port you specify if you changed the default).

URL: wss://127.0.0.1:8092/api/v3/ws?token=rocketskates:r0cketsk8ts

Note that the token information is a set of credentials with permissions to view events. This example uses the default username/password pair. You may also create and specify access Tokens for the websocket client to use.

In the Request input box, enter your register filter you'd like to receive events for.

Request: register profiles.*.*

This example will only output websocket events related to Parameters. Now create and delete a few test parameters

# now create a `bar` param on the `global` profile
drpcli profiles set global param bar to blatz

# now remove the param from the `global` profile
drpcli profiles remove global param bar

...and you should see events like:

{"Time":"2017-12-21T23:26:43.412554192Z","Type":"profiles","Action":"save","Key":"global","Object":{"Validated":true,"Available":true,"Errors":[],"ReadOnly":false,"Meta":{"color":"blue","icon":"world","title":"Digital Rebar Provision"},"Name":"global","Description":"Global profile attached automatically to all machines.","Params":{"bar":"blatz","change-stage/map":{"centos-8-install":"packet-ssh-keys:Success","discover":"packet-discover:Success","packet-discover":"centos-8-install:Reboot","packet-ssh-keys":"complete-nowait:Success"},"kernel-console":"console=ttyS1,115200"}}}
{"Time":"2017-12-21T23:27:15.218761478Z","Type":"profiles","Action":"save","Key":"global","Object":{"Validated":true,"Available":true,"Errors":[],"ReadOnly":false,"Meta":{"color":"blue","icon":"world","title":"Digital Rebar Provision"},"Name":"global","Description":"Global profile attached automatically to all machines.","Params":{"change-stage/map":{"centos-8-install":"packet-ssh-keys:Success","discover":"packet-discover:Success","packet-discover":"centos-8-install:Reboot","packet-ssh-keys":"complete-nowait:Success"},"kernel-console":"console=ttyS1,115200"}}}