Combined RPCs and messages for programming and notifications of AF objects.
This API supports programming the device by multiple clients.
If there are multiple clients intending to program the network element using this API, the clients initiating a programming or get RPC MUST pass a gRPC-context metadata identifying themselves. The client application MUST set the gRPC metadata key named "iosxr-slapi-clientid" with a numeric string holding a number between 0 and 65535.
Each client application MUST use a unique client ID identifying itself that is separate from other clients programming the server. If there are multiple instances of the client application, then each such instance MUST be uniquely idenified.
If "iosxr-slapi-clientid" gRPC metadata is missing, server assumes a default client id of 0 for that RPC invocation and associates objects programmed by that RPC with the default client id of 0.
The co-ordination of the ClientId amongst these instances is outside the scope of this specification.
Clients MUST not change their identity for their lifetime - such as RPC disconnects, process restarts or software update.
SL-API stores the objects programmed by clients and preserves them across RPC disconnects, client restarts and server gRPC process restarts. As such if a client application or instance is no longer needed, the client MUST remove all its programming from the server before it is disabled or removed.
Objects programmed by this RPC are stored in DBs that are key'ed on Client ID, VRF name and object type. Clients must ensure that only one programming RPC is operating on the DB. System behavior is undefined if simultaneous programming RPC sessions end up modifying the same DB.
The route redistribution and notifications are scoped to the RPC and as such do not require a client ID.
RPC Calls | |
| rpc | SLAF::SLAFVrfRegOp (SLAFVrfRegMsg) returns(SLAFVrfRegMsgRsp) |
| RPCs for object programming and access. More... | |
| rpc | SLAF::SLAFVrfRegGet (SLAFVrfRegGetMsg) returns(stream SLAFVrfRegGetMsgRsp) |
| VRF get. Used to retrieve VRF attributes from the server. | |
| rpc | SLAF::SLAFOp (SLAFMsg) returns(SLAFMsgRsp) |
| Route, MPLS label and Path operations. More... | |
| rpc | SLAF::SLAFOpStream (stream SLAFMsg) returns(stream SLAFMsgRsp) |
| Stream object operations. More... | |
| rpc | SLAF::SLAFGet (SLAFGetMsg) returns(stream SLAFGetMsgRsp) |
| Retrieves object attributes. | |
| rpc | SLAF::SLAFNotifStream (stream SLAFNotifReq) returns(stream SLAFNotifMsg) |
| The route redistribution and next hop tracking RPC. More... | |
Messages | |
| message | SLAFVrfReg |
| AF VRF Registration message. More... | |
| message | SLAFVrfRegMsg |
| AF VRF Registration messages. More... | |
| message | SLAFVrfRegMsgRes |
| AF VRF Registration message Result. More... | |
| message | SLAFVrfRegMsgRsp |
| VRF Registration message Response. More... | |
| message | SLAFVrfRegGetMsg |
| VRF Reg Get Request Message. More... | |
| message | SLAFVrfRegGetMsgRsp |
| VRF Reg Get Message Response. More... | |
| message | SLPathGroup |
| Path Group definition. More... | |
| message | SLPathGroup::SLPathList |
| A list of SLPathList. More... | |
| message | SLPathGroup::SLPath |
| message | SLMplsEntry |
| MPLS entry. More... | |
| message | SLAFObject |
| One of AF objects. More... | |
| message | SLAFOp |
| Operation on a forwarding table object. More... | |
| message | SLAFGetMsg |
| Used to retrieve objects in a VRF table. More... | |
| message | SLAFFibStatus |
| message | SLAFGetMsgRspEntry |
| Object and its programming status returned on Get. More... | |
| message | SLAFGetMsgRsp |
| Get AF message response. More... | |
| message | SLAFMsg |
| Operation on the address family. More... | |
| message | SLAFRes |
| Result of an operation on the object. More... | |
| message | SLAFMsgRsp |
| Route operations result status. More... | |
| message | SLAFRedistRegMsg |
| Request message for route redistribution registration. More... | |
| message | SLAFNextHopRegKey |
| Next hop registration request key. More... | |
| message | SLAFNextHopRegKey::SLNextHopKey |
| message | SLAFNextHopRegMsg |
| Next hop registration message. More... | |
| message | SLAFNotifRegReq |
| Notification request message for a single item. More... | |
| message | SLAFNotifReq |
| RPC Notification request - either a route redistribution request or a next hop change notification request. More... | |
| message | SLAFNotifRsp |
| Notification response message for a single item. More... | |
| message | SLNextHop |
| Next hop Notification. More... | |
| message | SLAFNotif |
| AF Notification message. More... | |
| message | SLAFNotifMsg |
| RPC Notification message. More... | |
| rpc SLAF::SLAFNotifStream | ( | stream | SLAFNotifReq | ) |
The route redistribution and next hop tracking RPC.
The notification request registrations and corresponding notifications are scoped to the RPC. On a RPC disconnection, the client should re-establish the RPC and re-program the notification requests. The caller MUST keep the RPC up as long as there is interest in the notifications.
For route redistribution, this call is used to get a stream of route notifications. It can be used to get "push" notifications for route adds/updates/deletes.
For next hop change notifications, this call can be used to get "push" notifications for nexthop adds/updates/deletes.
The call takes a stream of per-VRF table notification requests. Each notification request is first responded to with the result of the registration operation itself, followed by any redistributed routes if requested and present, and any next hops if requested and present. From then on, any updates are notified as long as RPC is up.
| rpc SLAF::SLAFOp | ( | SLAFMsg | ) |
Route, MPLS label and Path operations.
SLAFMsg.Oper = SL_OBJOP_ADD: Object add. Fails if the object already exists and is not stale. First ADD operation on a stale object is treated as implicit update and the object is no longer considered stale.
SLAFMsg.Oper = SL_OBJOP_UPDATE: Object update. Create or update the object. The RPC implements replacement semantics, wherein if the object exists, all its attributes are replaced with values from the new message.
SLAFMsg.Oper = SL_OBJOP_DELETE: Object delete. The object's key is enough to delete the object. Other attributes if present are ignored. Delete of a non-existant object is returned as success.
| rpc SLAF::SLAFOpStream | ( | stream | SLAFMsg | ) |
Stream object operations.
SLAFMsg.Oper = SL_OBJOP_ADD: Object add. Fails if the objects already exists and is not stale. First ADD operation on a stale object is allowed and the object is no longer considered stale.
SLAFMsg.Oper = SL_OBJOP_UPDATE: Object update. Creates or updates the object.
SLAFMsg.Oper = SL_OBJOP_DELETE: Object delete. The object's key is enough to delete the object. Delete of a non-existant object is returned as success.
| rpc SLAF::SLAFVrfRegOp | ( | SLAFVrfRegMsg | ) |
RPCs for object programming and access.
Supported objects are IP Routes, MPLS Labels, and Path Group objects.
A Path Group object created by one client can be referenced by any other object (e.g. IP Route and MPLS label object) created by ANY other client.
Only the client that created the object (IP/MPLS and Path Group included) can manipulate that object.
VRF registration operations. By default, The client must register with the corresponding VRF table before programming objects in that table.
SLAFVrfRegMsg.Oper = SL_REGOP_REGISTER: VRF table registration: Sends a list of VRF table registration messages and expects a list of registration responses. A client Must Register a VRF table BEFORE objects can be added/modified in the associated VRF table.
SLAFVrfRegMsg.Oper = SL_REGOP_UNREGISTER: VRF table Un-registration: Sends a list of VRF table un-registration messages and expects a list of un-registration responses. This can be used to convey that the client is no longer interested in these VRF tables. All previously installed objects would be remove.
SLAFVrfRegMsg.Oper = SL_REGOP_EOF: VRF table End Of File message. After Registration, the client is expected to send an EOF message to convey the end of replay of the client's known objects. This is especially useful under certain restart scenarios when the client and the server are trying to synchronize their objects.
The VRF table registration operations can be used by the client to synchronize objects with the device. When the client re-registers the VRF table with the server using SL_REGOP_REGISTER, server marks objects in that table as stale. Client then MUST reprogram objects it is interested in. When client sends SL_REGOP_EOF, any objects not reprogrammed are removed from the device.
The client MUST perform all operations (VRF registration, objects) from a single execution context.
The VRF registration requirement and recovery using mark and sweep can be disabled by configuring "grpc service-layer auto-register" on the device. In presence of this configuration, on client restart or RPC disconnects, the client has the responsibility to reconcile its new state with the state on the device by replaying the difference.
| message SLAFVrfReg |
AF VRF Registration message.
Attributes | |
| SLTableType | Table = 1 |
| Registration message is applied on VRF's identified table. | |
| SLVrfReg | VrfReg = 2 |
| VRF registration attibutes. | |
| message SLAFVrfRegMsg |
AF VRF Registration messages.
Attributes | |
| SLRegOp | Oper = 1 |
| Registration Operation. | |
| repeated SLAFVrfReg | VrfRegMsgs = 2 |
| List of VRF registrations. | |
| message SLAFVrfRegMsgRes |
AF VRF Registration message Result.
Attributes | |
| SLErrorStatus | ErrStatus = 1 |
| Corresponding error code. | |
| string | VrfName = 2 |
| VRF Name. | |
| SLTableType | Table = 3 |
| Table type. | |
| message SLAFVrfRegMsgRsp |
VRF Registration message Response.
Attributes | |
| SLErrorStatus | StatusSummary = 1 |
| Summary result of the bulk operation (refer to enum SLErrorStatus) In general, the StatusSummary implies one of 3 things: More... | |
| repeated SLAFVrfRegMsgRes | Results = 2 |
| In case of errors, this field indicates which entry in the bulk was erroneous. | |
| SLErrorStatus SLAFVrfRegMsgRsp::StatusSummary = 1 |
Summary result of the bulk operation (refer to enum SLErrorStatus) In general, the StatusSummary implies one of 3 things:
| message SLAFVrfRegGetMsg |
VRF Reg Get Request Message.
Returns the VRF registrations done for all table types.
Attributes | |
| bool | GetAll = 1 |
| If true, returns VRF registrations for all clients. More... | |
| bool SLAFVrfRegGetMsg::GetAll = 1 |
If true, returns VRF registrations for all clients.
If false, returns VRF registrations for this client as identified by the gRPC metadata.
| message SLAFVrfRegGetMsgRsp |
VRF Reg Get Message Response.
Attributes | |
| SLErrorStatus | ErrStatus = 1 |
| Status of the Get operation. | |
| uint64 | ClientID = 2 |
| Client that performed this registration. | |
| SLTableType | Table = 3 |
| If ErrStatus is SL_SUCCESS, Table and Entries contain the table in which the VRF registration operation was previously applied. | |
| repeated SLVrfReg | Entries = 4 |
| VRF registration operation. | |
| message SLPathGroup |
Path Group definition.
Attributes | |
| SLObjectId | PathGroupId = 1 |
| Path Group ID. | |
| uint32 | AdminDistance = 2 |
| Administrative distance of the Path Group. More... | |
| oneof { | |
| SLPathList PathList = 3 | |
| Path List. | |
| }; | |
| Description of paths in the PathGroup. More... | |
| uint32 | Flags = 4 |
| Flags to control programming of the PathGroup to Routing Information Base. More... | |
| oneof { ... } |
Description of paths in the PathGroup.
Oneof is used here for future extensibility.
| uint32 SLPathGroup::AdminDistance = 2 |
Administrative distance of the Path Group.
[0-255]. RIB uses this field to break the tie when multiple sources install the same Path Group. Lower distance is preferred over higher distance. The per path group object admin distance overrides the default admin distance set at VRF registration. see SLVrfReg.
| uint32 SLPathGroup::Flags = 4 |
Flags to control programming of the PathGroup to Routing Information Base.
Each flag is indicated as a bit field. See SLRouteFlags for flag enumerations. Supported values are:
SL_ROUTE_FLAG_VIABLE_PATHS_ONLY.
SL_ROUTE_FLAG_ACTIVE_ON_VIABLE_PATH.
Others - Reserved.
| message SLPathGroup::SLPathList |
A list of SLPathList.
Attributes | |
| repeated SLPath | Paths = 1 |
| message SLPathGroup::SLPath |
Attributes | |
| SLRoutePath | Path = 1 |
| Primary path. | |
| message SLMplsEntry |
MPLS entry.
This message defines an entry in the MPLS forwarding table.
Attributes | |
| uint32 | LocalLabel = 1 |
| Local Label. | |
| uint32 | AdminDistance = 2 |
| Administrative distance of the MPLS label. More... | |
| repeated SLRoutePath | PathList = 3 |
| For ADD or UPDATE operation, only one of PathList or SLPathGroupRefKey must be specified. More... | |
| oneof { | |
| SLPathGroupRefKey PathGroupKey = 4 | |
| Path group reference key. | |
| }; | |
| Reference to the Path Group for this MPLS label entry. More... | |
| uint32 | Flags = 5 |
| Flags to control programming of the MPLS Entry to Routing Information Base. More... | |
| oneof { ... } |
Reference to the Path Group for this MPLS label entry.
The attribute is oneof to allow for future extension.
| uint32 SLMplsEntry::AdminDistance = 2 |
Administrative distance of the MPLS label.
Possible values are [0-255]. RIB uses this field to break the tie when multiple sources install the same incoming MPLS label. Lower distance is preferred over higher distance. The per MPLS label object admin distance overrides the default admin distance set at VRF registration. see SLVrfReg.
| uint32 SLMplsEntry::Flags = 5 |
Flags to control programming of the MPLS Entry to Routing Information Base.
Each flag is indicated as a bit field. See SLRouteFlags for flag enumerations. Supported values are:
SL_ROUTE_FLAG_VIABLE_PATHS_ONLY - This flag on the MPLS Entry is applicable only if the MPLS Entry contains the PathList.
SL_ROUTE_FLAG_ACTIVE_ON_VIABLE_PATH - This flag is supported only for MPLS Entries that contain the PathList.
Others - Reserved.
| repeated SLRoutePath SLMplsEntry::PathList = 3 |
For ADD or UPDATE operation, only one of PathList or SLPathGroupRefKey must be specified.
For DELETE, neither are required. List of paths for this MPLS label entry. Specifying more than one path is allowed for ECMP/UCMP cases.
| message SLAFObject |
One of AF objects.
Attributes | |
| oneof { | |
| SLRoutev4 IPv4Route = 1 | |
| SLRoutev6 IPv6Route = 2 | |
| SLMplsEntry MplsLabel = 3 | |
| SLPathGroup PathGroup = 4 | |
| }; | |
| message SLAFOp |
Operation on a forwarding table object.
Attributes | |
| SLAFObject | AFObject = 1 |
| uint64 | OperationID = 2 |
| Unique operationID sent by the client to corelate the responses. More... | |
| SLRspACKType | AckType = 3 |
| The type of Acknowledgment that the controller or agent expects from the network element. | |
| uint64 SLAFOp::OperationID = 2 |
Unique operationID sent by the client to corelate the responses.
The responses from network element can be out of order, and client can use operation ID to correlate the response for the operation on the object. Operation Id should be monotonically increasing for the life of the client.
| message SLAFGetMsg |
Used to retrieve objects in a VRF table.
Only objects produced by this client (as indicated in the RPC's metadata) are returned unless the GetAllClients is set to true. In that case, all the objects produced by all the clients is returned.
Attributes | |
| string | VrfName = 1 |
| VRF name. More... | |
| SLTableType | Table = 2 |
| If Table is set to SL_TABLE_TYPE_RESERVED, or is unset, objects from all tables for selected VRFs are returned. | |
| bool | GetAllClients = 3 |
| Get objects programmed by all clients, ignoring any RPC ClientID metadata. | |
| repeated SLRouteGetMatch | RouteMatch = 4 |
| Get objects that match the value. | |
| string SLAFGetMsg::VrfName = 1 |
VRF name.
If VRF name is not specified or is nil, get objects from all VRFs.
| message SLAFFibStatus |
Attributes | |
| SLErrorStatus | ErrorCode = 1 |
| Error code associated with hardware programming. | |
| uint64 | OperationID = 2 |
| Operation ID associated with hardware programming. | |
| uint64 | Version = 3 |
| Version associated with hardware programming. More... | |
| string | ErrorString = 4 |
| Descriptive string describing error if any, on the hardware programming. | |
| repeated SLAFFibStatus | DepResult = 5 |
| DepResult is the result of any operation that this operation depends on. More... | |
| repeated SLAFFibStatus SLAFFibStatus::DepResult = 5 |
DepResult is the result of any operation that this operation depends on.
For example: if this OperationID is about programming an ipv4 or ipv6 route that is pointing to a Path Group, then DepResult will carry the Result of operation that programmed that Path Group. NOTE: DepResult is not supported on Get Operations.
| uint64 SLAFFibStatus::Version = 3 |
Version associated with hardware programming.
A valid version is a non-zero positive number.
| message SLAFGetMsgRspEntry |
Object and its programming status returned on Get.
Attributes | |
| SLAFOp | AFOp = 1 |
| Object. | |
| SLAFFibStatus | FIBStatus = 2 |
| If the operation was programmed with ACK type set to RIB_AND_FIB_ACK, then FIBStatus indicates status of hardware programming of the operation. | |
| message SLAFGetMsgRsp |
Get AF message response.
The objects can be returned in any order.
Attributes | |
| SLErrorStatus | ErrStatus = 1 |
| Status of the Get Stats operation. | |
| string | VrfName = 2 |
| VRF name. | |
| uint64 | ClientID = 3 |
| Client ID. More... | |
| repeated SLAFGetMsgRspEntry | AFList = 4 |
| Returned entries as requested in the Get operation. More... | |
| repeated SLAFGetMsgRspEntry SLAFGetMsgRsp::AFList = 4 |
Returned entries as requested in the Get operation.
if ErrStatus is SL_SUCCESS, entry contains the list of objects from the specified Table.
| uint64 SLAFGetMsgRsp::ClientID = 3 |
Client ID.
If the client requested read of all clients' objects, the Client ID field can be used by the client to determine if the object was previously programmed by this client or some other client.
| message SLAFMsg |
Operation on the address family.
The objects are programmed in the given VRF's corresponding table.
Attributes | |
| SLObjectOp | Oper = 1 |
| Route Object Operations. | |
| string | VrfName = 2 |
| VRF name. VRF name is ignored for MPLS ILM operations. | |
| repeated SLAFOp | OpList = 3 |
| List of operations. | |
| message SLAFRes |
Result of an operation on the object.
Attributes | |
| SLErrorStatus | ErrStatus = 1 |
| Error code. | |
| SLAFOp | Operation = 2 |
| The operation, expected to carry only the part that is considered the key to uniquely identify the object that is programmed. | |
| SLAFFibStatus | FIBStatus = 3 |
| If the operation was programmed with ACK type set to RIB_AND_FIB_ACK, then FIBStatus indicates status of hardware programming of the operation. | |
| message SLAFMsgRsp |
| message SLAFRedistRegMsg |
Request message for route redistribution registration.
Attributes | |
| string | SrcProto = 1 |
| Source Protocol. More... | |
| string | SrcProtoTag = 2 |
| Source Protocol Tag. More... | |
| SLTableType | Table = 3 |
| Table type the client is interested in. More... | |
| string SLAFRedistRegMsg::SrcProto = 1 |
Source Protocol.
Only routes with specified source protocol and protocol tag will be notified. Contact Cisco for supported protocol string names. This field is mandatory.
| string SLAFRedistRegMsg::SrcProtoTag = 2 |
Source Protocol Tag.
This can be empty if N/A. Contact Cisco for supported protocol tags. This field is optional.
| SLTableType SLAFRedistRegMsg::Table = 3 |
Table type the client is interested in.
This field is mandatory.
| message SLAFNextHopRegKey |
Next hop registration request key.
Attributes | |
| oneof { | |
| SLNextHopKey NextHop = 1 | |
| A next hop IP address. | |
| }; | |
| Notification request key. | |
| message SLAFNextHopRegKey::SLNextHopKey |
Attributes | |
| SLIpAddress | NextHop = 1 |
| Next Hop IP to resolve. | |
| uint32 | NextHopLen = 2 |
| Length of Next Hop IP address to use for resolution. | |
| bool | ExactMatch = 3 |
| Chose exact vs. best match. | |
| bool | AllowDefault = 4 |
| Allow default route to be returned. | |
| bool | Recurse = 5 |
| If this flag is not set or set to False, only the immediate viable path list is returned. More... | |
| bool SLAFNextHopRegKey::SLNextHopKey::Recurse = 5 |
If this flag is not set or set to False, only the immediate viable path list is returned.
If set to True, recursively resolve the next hop's paths and return the flattened path list. If the list exceeds MaxPathsInNexthopNotif, then only the first MaxPathsInNexthopNotif will be returned.
| message SLAFNextHopRegMsg |
Next hop registration message.
Attributes | |
| SLAFNextHopRegKey | NextHopKey = 1 |
| Next hop registration key. | |
| message SLAFNotifRegReq |
Notification request message for a single item.
Attributes | |
| oneof { | |
| SLAFRedistRegMsg RedistReq = 1 | |
| Route redistribution request. | |
| SLAFNextHopRegMsg NextHopReq = 2 | |
| Next hop notification request. | |
| }; | |
| uint64 | OperationID = 3 |
| Unique OperationID sent by the client to correlate the registration request with the response. More... | |
| uint64 SLAFNotifRegReq::OperationID = 3 |
Unique OperationID sent by the client to correlate the registration request with the response.
When this change registration request is applied in the server, the result of this registration operation is returned to the client along with Operation ID to allow the client correlate responses with the requests. Note, server reflects the OperationID only in registration responses, and not in the corresponding notifications.
| message SLAFNotifReq |
RPC Notification request - either a route redistribution request or a next hop change notification request.
If the number of NotifReq exceeds MaxNotifReqPerSLAFNotifReq, RPC will exit with error.
If VrfName is not set, each req in NotifReq is errored and sent to client. RPC will then wait for next message on stream.
If the number of NotifReq is zero, RPC will send empty response to client with only VRF populated. RPC will then wait for next message on stream.
Attributes | |
| SLNotifOp | Oper = 1 |
| Oper = SL_NOTIFOP_ENABLE This is to enable route notifications in a VRF or the next hop change notification Oper = SL_NOTIFOP_DISABLE This is to disable route notifications in a VRF or the next hop change notification. | |
| string | VrfName = 2 |
| Vrf that the client is interested in. | |
| repeated SLAFNotifRegReq | NotifReq = 3 |
| Notification request. | |
| message SLAFNotifRsp |
Notification response message for a single item.
Attributes | |
| SLAFNotifRegReq | NotifReq = 1 |
| Corresponding request. | |
| SLErrorStatus | NotifStatus = 2 |
| The NotifStatus implies one of 2 things: SL_SUCCESS: signifies that the notification request was successful. More... | |
| SLErrorStatus SLAFNotifRsp::NotifStatus = 2 |
The NotifStatus implies one of 2 things: SL_SUCCESS: signifies that the notification request was successful.
SL_XXX: signifies an error in setting up a notification for the Vrf.
| message SLNextHop |
Next hop Notification.
If there are no viable paths to the next hop, ResolvingRoute, ResolvingRouteLen, SrcProto are not set, AdminDistance/Metric are set to UINT32_MAX.
Attributes | |
| SLAFNextHopRegKey | NextHopKey = 1 |
| Next hop registration key. | |
| SLIpAddress | ResolvingRoute = 2 |
| Prefix of the route resolving the nexthop. | |
| uint32 | ResolvingRouteLen = 3 |
| Resolving route's prefix length. | |
| string | SrcProto = 4 |
| Source Protocol. More... | |
| string | SrcProtoTag = 5 |
| Source Protocol Tag. More... | |
| uint32 | AdminDistance = 6 |
| Nexthop route distance. | |
| uint32 | Metric = 7 |
| Nexthop route metric. | |
| repeated SLRoutePath | Paths = 8 |
| Nexthop's path list. More... | |
| repeated SLRoutePath SLNextHop::Paths = 8 |
Nexthop's path list.
Paths indicate paths available for the next hop. In case of recursive next hop resolution, the returned path list consists of flattened directly connected paths. Returned attributes in Path are NexthopAddress, NexthopInterface, VrfName.
If this field is not present, then no viable path to the next hop exist.
| string SLNextHop::SrcProto = 4 |
Source Protocol.
Contact Cisco for supported protocol string names.
| string SLNextHop::SrcProtoTag = 5 |
Source Protocol Tag.
This can be empty if N/A. Contact Cisco for supported protocol tags. This field is optional.
| message SLAFNotif |
AF Notification message.
Attributes | |
| oneof { | |
| SLAFNotifRsp NotifStatus = 1 | |
| This field carries the status of the SLAFNotifReq message. | |
| SLAFObject RedistObject = 4 | |
| Route redistribution notification. | |
| SLNextHop NextHop = 5 | |
| Next hop change notification. | |
| }; | |
