RIS Live Manual

Any of the below is subject to change or removal at the end of the prototype stage. We depend on your feedback to guide us on whether this system is useful. If you would like us to continue development and support for RIS Live, please fill in our survey.

RIS Live provides real-time JSON BGP messages via a fully filterable interactive WebSocket JSON API, and a full stream ("firehose") containing all of the messages generated by RIS. If you find any bugs or inconsistencies then please send an email to rislive@ripe.net.

Authentication and limits

RIS Live does not currently require any authentication. This may change during the course of or after the prototype stage.

If a client is unable to keep up with the incoming data, then a final error message will be sent and the connection will be closed.

Although not required, it is highly recommended to include ?client=<some-meaningful-identifier> in all URLs. This will make it easier for us to identify your application and help you to debug any issues that may arise.

WebSocket API

The WebSocket interface is a two-way message API that allows you to subscribe to one or more filters. It is available at wss://ris-live.ripe.net/v1/ws/. WebSocket support is included in every major web browser, and is available in all major programming languages via various libraries.

Unlike low-level network sockets, WebSockets are message-based rather than packet-based. In RIS Live, all messages are formatted as JSON objects containing a type key that shows what sort of message it is, and a data key containing the payload. After creating a RIS Live WebSocket you should send a JSON message indicating a set of filters that you wish to subscribe to. The server will then start sending you messages corresponding to BGP messages that match your filters, again in a well defined JSON format. Below is a JavaScript example that outputs every routing announcement seen by RRC21 that involves a transit through a Level 3 ASN. You can try it yourself by opening the JavaScript/Web Console in your browser and entering the following:

var ws = new WebSocket("wss://ris-live.ripe.net/v1/ws/?client=js-manual-example");
ws.onmessage = function(message) {
    var parsed = JSON.parse(message.data);
    console.log(parsed.data);
};
ws.onopen = function() { 
    ws.send(JSON.stringify({type: "ris_subscribe", data: {host: "rrc21", path: 3356}}));
};

This is a simple example in Python that uses the 'websocket-client' library to do the same thing as above:

import json
import websocket

ws = websocket.WebSocket()
ws.connect("wss://ris-live.ripe.net/v1/ws/?client=py-manual-example")
ws.send(json.dumps({"type": "ris_subscribe", "data": {"host": "rrc21", "path": 3356}}))
for data in ws:
    parsed = json.loads(data)
    print(parsed["type"], parsed["data"])

Message types

The following message types make up the RIS Live protocol:

Sender Type Data Description
client ris_subscribe A filters object (see below) Instructs the server to start sending ris_message messages matching the given filters.
client ris_unsubscribe A filters object previously sent in a ris_subscribe message Cancels a previous subscription.
client request_rrc_list - Instructs the server to send a ris_rrc_list message with a list of the available RRC hosts, and to resend every time the list changes.
client ping - Instructs the server to send a single pong message. Note: this is an application-level message to allow you to easily check the connection. The server and client will additionally exchange WebSocket protocol-level 'ping' (0x9) and 'pong' (0xa) control frames to act as heartbeats, but these will usually be handled automatically and transparently.
server ris_message An object representing a particular BGP message
server ris_error An object giving details of an error. You should remember to monitor messages of this type because they are useful in developing robust applications and debugging issues. They may be sent at any time there is a user or server error, including when you send an invalid message to the server.
server ris_rrc_list An array containing a list of RRCs that may appear in the host field of RIS messages
server pong - Sent in response to a ping message.

Filters

The following filters are supported for ris_subscribe messages:

Name Type Description
host string Only include messages collected by a particular RRC.
type string Only include messages of a given BGP or RIS type. Possibly values are: "UPDATE", "OPEN", "NOTIFICATION", "KEEPALIVE" and "RIS_PEER_STATE".
require string Only include messages containing a given key. Useful values are "announcements" or "withdrawals".
peer string (IP address) Only include messages sent by the given BGP peer.
path integer or comma-separated string of integers Match based on the ASNS in the AS path. Can optionally begin with ^ to only match the first item of the path (which is the last traversed ASN), or end with $ to only match the last item of the path (which is the originating ASN). e.g:
  • "789$": match paths that originate with AS789
  • 456 match any path that traverses AS456 at any point
  • "^123,456": match paths where the last traversed ASNs were 123 and 456 (in that order)
  • "^123,456,789$"Match the exact path [123, 457, 789]
Note: full regular expressions are not supported.
prefix string (IPv4 or IPv6 CIDR prefix) Only include UPDATE messages concerning a particular prefix.
moreSpecific boolean (default: true) If true, match prefixes that are more specific (part of) prefix.
lessSpecific boolean (default: false) If true, match prefixes that are less specific (contain) prefix.
socketOptions object Object of options that apply to all subscriptions over the current WebSocket. If a subscription contains socketOptions it will override those from previous subscriptions. Currently supported:

includeRaw (boolean, default: false): tell the server to include a Base64-encoded version of the original binary BGP message.

Full stream ("firehose")

The full stream is a one-way interface that is designed for researchers and other users who want to monitor all real-time RIS data with as little effort as possible. The basic structure of the messages is the same as in the WebSocket interface, but you are not able to take advantage of server-side filtering. It is available at the URL https://ris-live.ripe.net/v1/stream/?format=<format>. Once connected, the server will immediately begin sending representations of BGP messages, and will continue until the connection is closed.

In principle, you can access the full stream using any programming language or tool that supports HTTP. The available output formats are json and sse.

json messages include a type and a data key containing the BGP message. This is exactly the same format used in the WebSocket interface:

$ curl -s "https://ris-live.ripe.net/v1/stream/?format=json&client=cli-example-1"
{"type":"ris_message","data":{"timestamp":1549982565.19,"peer":"80.249.208.189","peer_asn":"20562","id":"80.249.208.189 ...

sse messages are in the Server-Sent Events format, which is part of the HTML 5 standard. The event field corresponds to the type in the WebSocket interface.

$ curl -s "https://ris-live.ripe.net/v1/stream/?format=sse&client=cli-example-2"
event: ris_message
data: {"timestamp":1549983011.99,"peer":"80.81.192.30","peer_asn":"3257" ...