Protocol Documentation

Table of Contents

bgp_route_service.proto

Top

Public API for the BGP routing services.

This IDL defines the APIs for the BGP-specific routing services.

AsPath

AS path through which the route was learned.

An AS Path is a string composed of a series of AS numbers separated by whitespace special delimiters. The following special delimiting characters are used for signifying confederations, confederation-sets, and AS-sets:

[ ] - Brackets enclose the local AS number associated with the AS set if more than one AS number is configured on the routing device, or if AS path prepending is configured.

( ) - Parentheses enclose a confederation.

( [ ] ) - Parentheses and brackets enclose a confederation set.

Programmed AS Paths implicitly have path origin IGP.

FieldTypeLabelDescription
aspath_string string optional

A string listing AS numbers separated by whitespace and special delimiter charaters (see message as-path). An AS Path must not exceed 1023 characters. REQUIRED

BgpAttrib32

A generic 32-bit unsigned value that implicitly carries an indication of whether any value has been set.

FieldTypeLabelDescription
value uint32 optional

32-bit unsigned value

BgpAttrib64

A generic 64-bit unsigned value that implicitly carries an indication of whether any value has been set.

FieldTypeLabelDescription
value uint64 optional

64-bit unsigned value

BgpRouteCleanupReply

Route service cleanup reply containing the status of the operation.

FieldTypeLabelDescription
status BgpRouteCleanupReply.BgpRouteCleanupStatus optional

The final return code for the request.

BgpRouteCleanupRequest

Request to cleanup the BGP route service. Any routes (and their associated gateways) that are added by the client are removed during the cleanup of the client state. No parameters are needed.

FieldTypeLabelDescription

BgpRouteEntry

A route entry specifying a single route destination and BGP path along with the route attributes for that path.

FieldTypeLabelDescription
dest_prefix RoutePrefix optional

Destination prefix of the route. REQUIRED

dest_prefix_len uint32 optional

Destination prefix length in bits. REQUIRED

table RouteTable optional

Route table specified by either name or ID. REQUIRED

protocol RouteProtocol optional

Protocol that installed the route in the table. In get requests, the only valid values are PROTO_UNSPECIFIED or PROTO_BGP_STATIC.

path_cookie uint64 optional

Path cookie value differentiates routes with the same destination. The cookie may be any unsigned 64-bit value. Optional (default is 0)

route_preference BgpAttrib32 optional

Route Preference, also known as administrative distance, is a unsigned value in the range from 0 through 4,294,967,295 (2^32 -1). Lower values of route preference are preferred. Optional (default route preference for programmed BGP-Static routes is 5)

local_preference BgpAttrib32 optional

Local Preference is an unsigned value in the range of 0 through 4,294,967,295 (2^32 - 1). Higher values of local preference are prefered. Optional (default is 100)

med BgpAttrib32 optional

Multi-Exit Discriminator (MED) is an unsigned value in the range of 0 through 4,294,967,295 (2^32 -1). Lower values of MED are preferred. Optional (By default no MED is advertised)

aigp_distance BgpAttrib64 optional

AIGP Distance is a 64-bit unsigned value in the range of 0 through (2^64 - 1). Lower values of AIGP distance are preferred. Optional (By default no AIGP distance is advertised)

vpn_label uint32 optional

A valid 20-bit unsigned label value must be less than decimal value 1048576 and not within the reserved label range of 4 through 15 (inclusive). It is not possible to set ToS bits in this case.

labels LabelStack optional

A properly constructed label stack which may include VPN label in addition to a BGP-LU label stack. NOTE: label stack is not supported in this release of the API.

communities CommunityList optional

List of route communities. Optional (By default no communities are advertised.)

aspath AsPath optional

AS Path for the route. Optional (By default no no AS path is advertised.)

originator_id BgpAttrib32 optional

BGP originator ID is an unsigned 32-bit BGP identifier value as per RFC 6286. It is encoded in network byte order. Optional (By default no originator ID is advertised.)

cluster_list BgpAttrib32 repeated

BGP cluster list - A list of cluster IDs specifying the path of route reflectors though which this route has traversed. Optional (By default no cluster list is advertised.)

cluster_id BgpAttrib32 optional

BGP Cluster ID is an unsigned 32-bit BGP identifier value as per RFC 6286. It is encoded in network byte order. Cluster ID is appended to the cluster_list for advertisement with reflected routes. Optional (By default no cluster ID is advertised.)

route_oper_flag uint32 optional

Flag indicating the route operations defined in RouteOperation enum These values can be ORed to indicate a combination of operations.

protocol_nexthops IpAddress repeated

Protocol next-hop for the route. If multiple next-hops are given, the route is treated as a BGP multipath for load balancing.

NOTE: Multipath is not currently supported by the API. An error is returned when adding or changing a route with more than one next-hop. REQUIRED

BgpRouteGetReply

Route get reply containing the status of the operation and the full or partial set of matching routes. Whether the set of matching routes is full or partial depends on whether or not the reply is split into multiple streams. A single stream indicates a full set. Multiple streams indicates that only a partial set is contained within each RPC reply stream.

FieldTypeLabelDescription
status BgpRouteGetReply.BgpRouteGetStatus optional

The final return code for the request.

bgp_routes BgpRouteEntry repeated

One or more matching bgp routes.

BgpRouteGetRequest

Route get operation request parameters.

FieldTypeLabelDescription
bgp_route BgpRouteMatch optional

Route matching parameters

or_longer bool optional

Boolean value to set the or_longer route match option.

If or_longer is FALSE, only routes for the exact destination prefix and prefix length are matched.

If or_longer is TRUE, routes for the given destination prefix or longer prefixes are matched.

Optional (default is FALSE)

active_only bool optional

If active_only is TRUE, inactive and hidden routes for a matching prefix are omitted from the results. If active_only is FALSE, inactive and hidden routes are also returned.

Optional (default is FALSE)

reply_address_format AddressFormat optional

The format for IP addresses in the replies to this request.

Optional (default is string)

reply_table_format RouteTableFormat optional

The format for route tables in the replies to this request.

Optional (default is string)

route_count uint32 optional

The maximum number of routes requested in each reply. Replies are streamed in multiple RPCs, each having no more routes than given by this value. Counts from 1 through the maximum of 1000 can be specified. A value of zero indcates that the server chooses an appropriate number of routes to stream in each reply.

Optional (default 1)

BgpRouteInitializeReply

BGP route service initialize reply containing the status of the operation. Replies indicate to the client whether any old routing state was recovered and rebound to this connection.

FieldTypeLabelDescription
status BgpRouteInitializeReply.BgpRouteInitializeStatus optional

The final return code for the request.

gw_n_routes uint32 optional

Valid only when status is CLEANUP_PENDING. It indicates the number of routes on the gateway, giving an idea of the time required to cleanup

BgpRouteInitializeRequest

Request to initialize the BGP route service. No parameters are needed.

FieldTypeLabelDescription

BgpRouteMatch

Route matching parameters provide the key for identifying BGP routes. Programmed BGP-Static routes must be unique for the bgp_route_match paramaters. Dynamic BGP routes may may have multiple matches to a given set of bgp_route_match parameters.

FieldTypeLabelDescription
dest_prefix RoutePrefix optional

Destination prefix of the route. REQUIRED

dest_prefix_len uint32 optional

Destination prefix length in bits. REQUIRED

table RouteTable optional

Route table specified by either name or ID. REQUIRED

protocol RouteProtocol optional

Protocol that installed the route in the table.

path_cookie uint64 optional

Path cookie value differentiates routes with the same destination. The cookie may be any unsigned 64-bit value. Optional (default is 0, which indicates that cookie is not evaluated for matching)

BgpRouteOperReply

Route operation reply containing the status of the operation. Replies always returns the final status (either success or the first error encountered) and the number of routes that were successfully processed prior to any error or full completion of the request.

FieldTypeLabelDescription
status BgpRouteOperReply.BgpRouteOperStatus optional

The final return code for the request.

operations_completed uint32 optional

The number of requested operations for which the operation completed successfully. Note that in the case of remove operations with or_longer=TRUE or cookie=0, this is not the number of routes matched and removed.

BgpRouteRemoveRequest

Route remove operation request parameters.

FieldTypeLabelDescription
or_longer bool optional

Boolean value to set the or_longer route match option.

If or_longer is FALSE, only routes for the exact destination prefix and prefix length are matched.

If or_longer is TRUE, routes for the given destination prefix or longer prefixes are matched. Optional (default is FALSE)

bgp_routes BgpRouteMatch repeated

One or more programmed bgp routes to remove.

REQUIRED

BgpRouteUpdateRequest

Route add, modify, or update operation request parameters.

FieldTypeLabelDescription
bgp_routes BgpRouteEntry repeated

One or more programmed bgp routes to add, udpate, or modify. REQUIRED

Community

A single communty is a string identifying a regular, extended, or well-known community name or values with no whitepace.

The following communities are recognized:

Well-known communities: no-export no-advertise no-export-confed llgr-stale no-llgr

RFC 1997 comunities: domain-id:ipaddress:0 domain-id-vendor: <n>:<n>

Route targets extended communities: target:ipv4-address:16 bit# target:16bit#:32bit# target:as2b:16bit#:32bit# target:as4b:32bit#:16bit#

Origin extended communities: origin:ipv4-address:16 bit# origin:16bit#:32bit#

Bandwidth management extended communities: bandwidth:16bit#:bw {traffic-rate}:16 bit#:bw

Redirect extended communities: redirect:ipv4-address:16 bit# redirect:16bit#:32bit#

Tunnel encapsulation extended communities: encapsulation:0L:tunnel-type

FieldTypeLabelDescription
community_string string optional

A string that uniquely identifies a single regular, extended, or well-known community. A community string must not exceeed 1023 characters. REQUIRED

CommunityList

A list of communities.

FieldTypeLabelDescription
com_list Community repeated

An unordered list of zero, one, or more individual communities.

A Community list may not exceed 256 communities

LabelStack

A label stack constructed according to the rules of RFC 3032.

FieldTypeLabelDescription
entries LabelStackEntry repeated

An ordered list of one or more label stack entries beginning with the bottom of the stack and ending with the top of the stack. REQUIRED (one or more entries)

LabelStackEntry

A single label entry in the stack of labels.

FieldTypeLabelDescription
label_value uint32 optional

One of either well_known_labels or a valid 20-bit unsigned label value that must be less than decimal value 1048576 and not within the reserved label range of 4 through 15 (inclusive).

REQUIRED

exp_value uint32 optional

A valid 32-bit unsigned EXP value that must be less than decimal value 8. Optional (DEFAULT is 0)

ttl_value uint32 optional

A valid 8-bit unsigned TTL value that must be less than decimal value 256. Optional (DEFAULT is 0)

bottom_of_stack bool optional

Indicates that this Label stack entry is on the bottom of the label stack. Bottom-of-Stack is always set by the library and must never set by the client. READ-ONLY

BgpRouteCleanupReply.BgpRouteCleanupStatus

Possible return codes for route service cleanup operations.

NameNumberDescription
SUCCESS 0

Request successfully completed.

INTERNAL_ERROR 1

Request failed due to an internal server error.

NOT_INITIALIZED 2

Request failed because there was no initialized state to cleanup.

BgpRouteGetReply.BgpRouteGetStatus

Possible return codes for route get operations.

NameNumberDescription
SUCCESS 0

Request successfully completed in full.

INTERNAL_ERROR 1

Request failed due to an internal server error.

NOT_INITIALIZED 2

Request failed because there was no initialized state to cleanup.

TABLE_INVALID 3

Request contained an invalid table.

TABLE_NOT_READY 4

Request contained a table that was not ready for operations.

PREFIX_INVALID 5

Request contained an invalid destination address prefix

PREFIX_LEN_TOO_SHORT 6

Request contained a destination prefix length too short for the supplied address/NLRI.

PREFIX_LEN_TOO_LONG 7

Request contained a destination prefix length too long for the supplied address/NLRI.

ROUTE_NOT_FOUND 8

Request contained a route that does not match destinations in the routing table.

PROTOCOL_INVALID 9

Request specified an invalid protocol to match

ROUTE_INVALID 10

Request does not contain valid route match parameters

REQUEST_UNSUPPORTED 11

Request contains a parameter that is not currently supported.

TRY_AGAIN 12

Request cannot be serviced until current requests are processed.

ROUTE_COUNT_INVALID 13

Request contains a route_count that exceeds the max of 1000

BgpRouteInitializeReply.BgpRouteInitializeStatus

NameNumberDescription
SUCCESS 0

Request successfully completed and no preexisting state for old clients with the same name was rebound.

SUCCESS_STATE_REBOUND 1

Request successfully completed AND preexisting routing state for an old client connection of the same name has been recovered and bound to this client connection.

INTERNAL_ERROR 2

Request failed due to an internal server error.

ALREADY_INITIALIZED 3

Failed due to previous initialization operation.

GATEWAY_INVALID 4

Failed to find or create a gateway

CLEANUP_PENDING 5

Previous clean up work is pending try again later

BgpRouteOperReply.BgpRouteOperStatus

Possible return codes for route add, modify, update, or remove operations.

NameNumberDescription
SUCCESS 0

Request successfully completed in full.

INTERNAL_ERROR 1

Request failed due to an internal server error.

NOT_INITIALIZED 2

The bgp route service has not been initialized

NO_OP 3

Request did not result in any operations

TOO_MANY_OPS 4

Request contained too many operations

TABLE_INVALID 5

Request contained an invalid table.

TABLE_NOT_READY 6

Request contained a table that was not ready for operations.

PREFIX_INVALID 7

Request contained an invalid destination address prefix

PREFIX_LEN_TOO_SHORT 8

Request contained a destination prefix length too short for the supplied address/NLRI.

PREFIX_LEN_TOO_LONG 9

Request contained a destination prefix length too long for the supplied address/NLRI.

GATEWAY_INVALID 10

The server did not have a valid gateway associated with the client.

NEXTHOP_INVALID 11

Request contained an invalid nexthop.

NEXTHOP_ADDRESS_INVALID 12

Request contained a nexthop with an invallid address.

NEXTHOP_ECMP_LIMIT 13

Request to add paths exceeding maximum ECMP paths for a destination.

COMMUNITY_LIST_INVALID 14

Request contained an invalid community.

ASPATH_INVALID 15

Request contained an invalid AS path.

LABEL_INFO_INVALID 16

Request contained a invalid label information.

ROUTE_EXISTS 17

Request contains a route that is already present in the table.

ROUTE_NOT_FOUND 18

Request contains a route that is NOT present in the table.

CLUSTER_LIST_INVALID 19

Request contains an invalid cluster list.

PROTOCOL_INVALID 20

Request contains an invalid protocol. Only PROTO_UNSPECIFID or PROTO_BGP_STATIC are allowed in route change operations.

ROUTE_ADD_FAILED 21

Request contains a route that is NOT present in the table.

BGP_NOT_READY 22

The BGP protocol is not initialized and ready to accept route change operations.

TRY_AGAIN 23

Request cannot be serviced until current requests are processed.

REQUEST_UNSUPPORTED 24

Request contains a parameter that is not currently supported.

LabelStackEntry.WellKnownLabels

Well-known label values defined by RFC 3032. These must only be used in label stacks in accordance with the rules of RFC 3032.

NameNumberDescription
IPV4_EXPLICIT_NULL_LABEL 0

IPv4 explicit NULL - This setting is valid only at the bottom of the stack.

ROUTER_ALERT_LABEL 1

Router Alert - This setting is valid anywhere in a label stack except the bottom.

IPV6_EXPLICIT_NULL_LABEL 2

IPv6 Explict NULL - This setting is valid only at the bottom of the stack

IMPLICIT_NULL_LABEL 3

Implicit NULL - See RFC 3032

RouteOperation

Route Operation Flag values that alter route add behavior.

NameNumberDescription
UNSPECIFIED 0

Unspecified Operation, meaning no special operation specified.

NO_ADVERTISE 1

Route operation indicating whether to attach the well-known no-advertise community. No-advertise has the effect of instructing the router not to advertise the route further. The community can be included in the community_list.

NO_EXPORT 2

Route operation indicating whether to attach the well-knwon no-export community. No-export has the effect of instructing the router not to advertise the route beyond the BGP confederation boundary. The community can be included in the community_list.

USE_NH_REJECT 4

Route Operation indicating whether to use NH_REJECT for the route. It is recommended to set this when programming the route in a route reflector (RR). This setting can save memory when there are a high number of unique nexthops.

RouteProtocol

Routing protocols

NameNumberDescription
PROTO_UNSPECIFIED 0

Unspecified protocol. The default behavior is dependent on the API.

For route change requests the default protocol is PROTO_BGP_STATIC.

For route get requests it is either PROTO_BGP or PROTO_BGP_STATIC.

PROTO_BGP 1

BGP dynamic routes

PROTO_BGP_STATIC 2

BGP static programmed routes

BgpRoute

BGP route operations service

Method NameRequest TypeResponse TypeDescription
BgpRouteInitialize BgpRouteInitializeRequest BgpRouteInitializeReply

BGP Routing Initialize operation BgpRouteInitialize() must be called upon connection or reconnection to the server. If the client is connecting for the first time, the server initializes the per-client state for the connection. If the client is reconnecting with the same client name following a connection fault (If a previous connection is closed without a call to BgpRouteCleanup), then the gateway and route state are rebound to the new connection. In this case, the return status indicates that the client state was rebound and the client need not send the previous routing state to the server.

BgpRouteCleanup BgpRouteCleanupRequest BgpRouteCleanupReply

BGP Routing Cleanup operation BgpRouteCleanup purges all gateway and route states for the client.

BgpRouteAdd BgpRouteUpdateRequest BgpRouteOperReply

BGP Route Add operation Add a BGP-Static route to the routing table. The function, bgp_route_add, may be called multiple times for the same prefix to add multiple paths to the same destination, each with a distinct path_cookie. If a matching route already exists in the given table, then an error is returned. BgpRouteOperRequest can contain from one to 1000 routes to be added. If the request contains multiple routes, the routes are processed in the order given and the first error encountered causes the request to abort. The API always returns the final status (success or first error encountered) and the number of routes that were successfully created prior to any error or full completion of the request.

BgpRouteModify BgpRouteUpdateRequest BgpRouteOperReply

BGP Route Modify operation Modify an existing BGP-Static route in the routing table. For each route in the request, if the route_key is matched, the matched route is updated with the supplied route attributes. If a matching route does not exist in the given table, then an error is returned. BgpRouteOperRequest may contain from one to 1000 routes to be modified. If the request contains multiple routes, the routes are processed in the order given and the first error encountered causes the request to abort. The API always returns the final status (success or first error encountered) and the number of routes that were successfully modified prior to any error or full completion of the request.

BgpRouteUpdate BgpRouteUpdateRequest BgpRouteOperReply

BGP Route Update operation Create a new BGP-Static route if a matching route does not exist. Modify an existing BGP-Static route if it is already present in the routing table. BgpRouteOperRequest may contain from one to 1000 routes to be added. If the request contains multiple routes, the routes are processed in the order given. The first error encountered causes the request to abort. The API always returns the final status (success or first error encountered) and the number of routes that were successfully modified prior to any error or full completion of the request.

BgpRouteRemove BgpRouteRemoveRequest BgpRouteOperReply

BGP Route Remove operation Remove a BGP-Static route from the routing table. BgpRouteRemove may be called multiple times for the same prefix to remove multiple paths, each with a distinct path_cookie for the same destination. The request may contain from one to 1000 routes to be removed. If the request contains multiple routes, the routes are processed in the order given and the first error encountered causes the request to abort. The API always returns the final status (success or first error encountered) and the number of routes that were successfully modified prior to any error or full completion of the request.

BgpRouteGet BgpRouteGetRequest BgpRouteGetReply

BGP Route Get operation Lookup a BGP or BGP-Static protocol route from the routing table. All match parameters are optional. Match fields that are not specified or that might match more than one route; for example, a less-specific destination prefix, may result in multiple routes being returned in the replies. Only BGP and BGP-Static routes are matched. Replies are streamed until all match routes have been sent. The client receives a final null message once all routes have been received. The server's walk of search results is not atomic so route changes that happen during streaming and consumption of replies may not be reflected in the results. See BgpRouteGetReply.

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str