HTTP services

Rotonda runs an HTTP server providing a (very basic) Web UI, metrics in Prometheus format, and various JSON endpoints. All these are served on one single port, configured in rotonda.conf. Note that even though the endpoints are under /api/v1, this does not mean everything on this page is considered stable at this point.

Web UI

The web UI lives at the root of the configured web server. It provides a simple overview of the basics. These pages should not be scraped, use the JSON endpoints to fetch information properly.

Prometheus metrics

On /metrics a Prometheus style file is served. This currently contains a mix of metrics from Rotonda itself, and possibly user-defined metrics from Roto filters.

Warning

The metrics defined by Rotonda itself are soon to be overhauled, and currently in sub-optimal shape after various refactors of the codebase. Some counters will always be 0, some will be incorrect. Use these to get a general idea of activity of the system, but not for accurate numbers whatsoever.

JSON endpoints

Important

While under /api/v1, these endpoints are considered under development and might change without a version bump in the URL.

Rotonda offers endpoints to query information on ingresses, i.e. sources of routing information such as BMP streams or BGP sessions, and on routes stored in the RIBs. Both these endpoints allow filtering in the query part of the request.

GET /api/v1/ingresses[?filter[A]=x[&filter[B]=y]..]

Returns all the ingresses for this Rotonda instance. The filter options below can be combined, and will be evaluated in boolean AND fashion.

?filter[type]=<INGRESS_TYPE>
where <INGRESS_TYPE> can be one of bmp, bgpViaBmp, bgp, mrt.
?filter[ribType]=<RIB_TYPE>
where <RIB_TYPE> can be one of inPre, inPost, loc, outPre, outPost.
?filter[peerAddress]=<IP_ADDR>
where <IP_ADDR> is an IPv6 or IPv4 address.
?filter[peerAsn]=<ASN>
where <ASN> is an Autonomous System Number, possibly prefixed with “AS”.

GET /api/v1/ribs/ipv4unicast/routes/<IP_ADDR_PART>/<PREFIX_LENGTH>[?filter[A]=x[&filter[B]=y]..]

Returns all the active routes for this IPv4 Unicast prefix. The filter options below can be combined, and will be evaluated in boolean AND fashion.

Filters

?filter[originAsn]=<ASN>
where <ASN> is an Autonomous System Number, possibly prefixed with “AS”.
?filter[otc]=<OTC>
filters on the Only-To-Customer path attribute, where <OTC> is an Autonomous System Number, possibly prefixed with “AS”.
?filter[community]=<COMMUNITY>
filters on a standard Community (RFC1997), where <COMMUNITY> is either in canonical AS65412:666 form, or the name of a well-known communitiy e.g. NO_PEER.
?filter[largeCommunity]=<LARGE_COMMUNITY>
filters on a Large Community (RFC8092), where <LARGE_COMMUNITY> is in canonical AS65412:1234:9999 form.
?filter[ribType]=<RIB_TYPE>
where <RIB_TYPE> can be one of inPre, inPost, loc, outPre, outPost.
?filter[rovStatus]=<ROV_STATUS>
where <ROV_STATUS> can be one of notChecked, notFound, valid, invalid.
?filter[peerAsn]=<ASN>
where <ASN> is an Autonomous System Number, possibly prefixed with “AS”.
?filter[peerAddress]=<IP_ADDR>
where <IP_ADDR> is an IPv6 or IPv4 address.

Functions

?function[roto]=<ROTO_FUNCTION>

where <ROTO_FUNCTION> is the name of a user-defined Roto function taking PathAttributes as a parameter, and indicating via accept or reject whether a route should be included in the response.

For example, the filter returns routes that contain both an OTC and AS_PATH path attribute where the ASN for the OTC is not part of the AS_PATH.

fn my_filter_function(attr: PathAttributes) {
    match attr.otc() {
        Some(otc) -> {
            match attr.aspath() {
                Some(aspath) -> {
                    if not aspath.contains(otc) {
                        accept
                    } else {
                        reject
                    }
                },
                None -> reject,
            }
        }
        None -> { reject }
    }
}

Fields

Fields can be used to override the default output fields of parts of the response. This can help to greatly reduce the size of responses. Note that this is different from filtering.

?fields[pathAttributes]=<LIST_OF_TYPECODES>
where <LIST_OF_TYPECODES> is a comma separated list of integers, representing one or multiple types of path attibutes. Only path attributes of these types will be included in the response.

For example, to only return the Standard and Large communities:
```
/api/v1/ribs/ipv4unicast/routes?fields[pathAttributes]=8,32
```

Includes

Includes are used to incorporate data additional to the exact prefix searched for. The ``filter``s and ``field``s are applied on these as well.

Danger

Including routes for more-specific prefixes via include=moreSpecifics can result in very large responses.

?include=<LIST_OF_INCLUDES>
where <LIST_OF_INCLUDES> is a comma separated list of one or multiple of: moreSpecifics, lessSpecifics.

GET /api/v1/ribs/ipv6unicast/routes/<IP_ADDR_PART>/<PREFIX_LENGTH>

Returns all the active routes for this IPv6 Unicast prefix.

Takes the same filter, fields, function and include as the ipv4 unicast endpoint described above.

Danger

Depending on the volume of routes in the RIB, querying the endpoints below can be expensive, and/or result in huge responses.

GET /api/v1/ribs/ipv4unicast/routes

Returns all the active routes for the entire IPv4 Unicast address family.

This mimics a request to /api/v1/ribs/ipv4unicast/0.0.0.0/0?include=moreSpecifics and as such, all results will be part of the included object in the response:

{ ..
    "included": { "moreSpecifics": [ .. ] }
}

Takes the same filter, fields, function and include as the ipv4unicast endpoint described above.

GET /api/v1/ribs/ipv6unicast/routes: Returns all the active routes for the entire IPv6 Unicast address family, similar to the IPv4 Unicast endpoint described above.