gRPC

In gNMI service, the client discovers the capabilities of the gRPC server through a Capability-Discovery RPC, which consists of ‟CapabiltyRequest” and ‟CapabilityResponse” messages.

During this message exchange, the gRPC server informs the client about following attributes:

• supported gNMI version

• supported models

• supported encodings

The SR OS server announces the supported models based on the configuration in the following context.

configure system management-interface yang-modules

The supported models includes the Nokia YANG or OpenConfig (OC) models.

The advertised module names and organizations are as follows:

• nokia-conf, org = "Nokia"

• nokia-state, org = "Nokia"

• openconfig, org = "OpenConfig working group" (as specified by the 'organization' in the YANG models)

• version - the version number is be defined as follows:

  • for Nokia YANG models, the version number corresponds to an SR OS release number, for example, "16.0.R1"

  • for OC YANG models, the version number corresponds to a version number defined in "oc-ext:openconfig-version" that is included in the respective YANG models

  • for OC-YANG models, including Nokia deviations, the version number corresponds to an SR OS release number, for example, "16.0.R1"

The following is an example of a ‟Capabilities Response Message”:

Going to send message of type gnmi.CapabilityResponse:
 .gnmi_version: 0.4.0
 .supported_encodings (1):
  .encoding: 0 = JSON
 .supported_models (47):
  { .name: 'nokia-conf', .organization: 'Nokia', .version: '16.0.R1' }
  { .name: 'nokia-state', .organization: 'Nokia', .version: '16.0.R1' }
  { .name: 'openconfig-
bgp', .organization: 'OpenConfig working group', .version: '4.0.1' }
<snip>
  { .name: 'nokia-sr-openconfig-if-ethernet-deviations', .organization: 'Nokia', 
.version: '16.0.R1' }
  { .name: 'nokia-sr-openconfig-if[[-ip-deviations', .organization: 'Nokia', 
.version: '16.0.R1'..."

Information is retrieved from the NE using GET RPC messages, which consists of ‟GetRequest” and ‟GetResponse” messages. The client asks for information by specifying following:

• a set of paths

  All rules to a path definition apply, as specified in the gNMI specification.

• type

  This refers to configuration, state, or operational data.

• encoding

  In accordance to server advertisement during capability discovery.

• use_models

  This message is ignored.

There is an upper limit on the size of the ‟GetResponse” message. This limit cannot exceed 100MB. If the limit is exceeded, the SR OS gRPC server responds with an error message.

To modify the information in an NE element, a SET gRPC message is used. This gRPC supports three types of transactions:

• delete

• replace

• update

With a gNMI SET RPC, SR OS authorizes all configuration changes, that is, it checks the YANG tree and authorizes every changed element.

The deletion of a container results in the deletion of any children containers that are authorized for deletion as well as their contents. Children containers that are not authorized for deletion, as well as their contents, are retained. For example, upon deletion of configure system, configure system security is not deleted because the deletion of that child container is not authorized.

The subscribe RPC is part of the telemetry support in gNMI.

The gRPC client initiates a subscription by sending a Subscribe RPC that contains a "SubscribeRequest" message to the gRPC server. A prefix can be specified in the "SubscribeRequest". If a prefix is present, it is appended to the start of every path to provide a full path.

A subscription contains the following:

• a list of one or more paths with the following conditions:

  • A path represents the data tree as a series of repeated strings and elements. Each element represents a data tree node name and its associated attributes.

  • A path must be syntactically valid within the set of schema modules that the gRPC server supports.

  • The path list cannot be modified during the lifetime of the subscription.

  • If the subscription path is to a container node, all child leafs of that container node are subscribed to.

  • Any specified path must be unique within the list; paths cannot be repeated within the list. An error is returned if the same path is used more than once in a single subscription.

  • A specified path does not need to pre-exist within the current data tree on the gRPC server. If a path does not exist, the gRPC server continues to monitor for the existence of the path. Assuming that the path exists, the gRPC server transmits telemetry updates.

  • The gRPC server does not send any data for a non-existent path; for example, if a path is non-existent at the time of subscription creation or if the path was deleted after the subscription was established.

  • The maximum number of paths for all subscriptions on a single SR OS device is 14400. A path using a wildcard is still considered a single path.

• an encoding with the following supported options:

  • JSON
  • JSON-IETF
  • BYTES
  • PROTO

    The following command affects PROTO and BYTES encoding.

    configure system grpc gnmi proto-version

    If the command option is latest, the encodings are interpreted as defined in specification v0.8.0. The following table lists the summary of different encoding options and the values used based on the proto-version command for all possible values defined in the gnmi.proto OpenConfig module.

    Table 1. Options for the proto-version command

    Response field	JSON	JSON-IETF	PROTO	BYTES
    string string_val = 1;			latest	v0.7.0
    int64 int_val = 2;			latest	v0.7.0
    uint64 uint_val = 3;			latest	v0.7.0
    bool bool_val = 4;			latest	v0.7.0
    bytes bytes_val = 5;			latest	v0.7.0
    float float_val=6 [deprecated=true]; // Deprecated - use double_val.
    Decimal64 decimal_val = 7 [deprecated=true]; // Deprecated - use double_val.				v0.7.0
    ScalarArray leaflist_val = 8;			latest
    google.protobuf.Any any_val = 9;
    bytes json_val = 10;	x
    bytes json_ietf_val = 11;		x
    string ascii_val = 12;
    bytes proto_bytes = 13;			v0.7.0	latest
    double double_val=14;			latest

• a subscription mode of one of the following types:

  • ONCE mode

    The server returns only one notification containing all the information to which the client has subscribed. In general, use telemetry to retrieve large amounts of information from the NE: ‟SubscribeRequest” message with ONCE subscription type.

  • ON_CHANGE mode

    The server returns notifications only when the value of the subscribed field changes. See ON_CHANGE subscription mode for more information.

  • SAMPLE mode

    The gRPC server sends notifications at the specified sampling interval.

  • TARGET_DEFINED mode

    This refers to ON_CHANGE for all states supporting ON_CHANGE notifications and SAMPLE mode for all other objects in the YANG tree.

• a sample interval for each path

  • If a sample interval of less than 1 s is specified, the gRPC server returns an error.
  • If the sample interval is set to 0, the default value of 10 s is used.
  • A sample interval is specified in nanoseconds (10 000 000 000 by default)

When a subscription is successfully initiated on the gRPC server, ‟SubscribeReponse” messages are sent from the gRPC server to the gRPC client. The ‟SubscribeResponse” message contains update notifications about the subscription's path list.

An update notification contains:

• a timestamp of the statistics collection time, represented in nanoseconds

• a prefix

  • If a prefix is present, it is logically appended to the start of every path to provide the full path.

  • The presence of a prefix in the ‟SubscribeResponse” message is not related to the presence of a prefix in the original ‟SubscribeRequest” message. The prefix in the ‟SubscribeResponse” message is optimized by the gRPC server.

• a list of updates (path and value pairs)

  • A path represents the data tree path as a series of repeated strings or elements, where each element represents a data tree node name and its associated attributes. See Schema paths for more information.

  • The ‟TypedValue” message represents the value of the data tree node, where the encoding is ‟JSON”, ‟JSON_IETF”, ‟Bytes”, or ‟Protobuf” depending on the information in the ‟SubscribeRequest” message.

Multiple notification messages can be combined in a single ‟SubscribeResponse” message. This bundling minimizes overhead, which improves the efficiency of telemetry data transport, however, this may delay some notifications and timestamps may be less accurate. The following options control message bundling:

max-time-granularity

controls the maximum time during which notifications can be bundled

max-msg-count

controls the maximum number of notifications that can be bundled

A sync response notification is sent one time after the gRPC server sends all updates for the subscribed-to paths. The sync response must be set to ‟true” for the gRPC client to consider that the stream has synced one time. A sync response is used to signal the gRPC client that it has a full view of the subscribed-to data.

The gRPC server sends an error, if required. The error contains a description of the problem.

Authorization checks are not performed by default for telemetry data. All configuration and state elements are available to authenticated telemetry subscriptions, with the exception of LI (Lawful Intercept) configuration and state elements, which are authorized separately based on the LI authorization configuration.

Use the following command to control telemetry data authorization:

• MD-CLI

  configure system security aaa management-interface output-authorization telemetry-data

• classic CLI

  configure system security management-interface output-authorization telemetry-data

With dial-out telemetry, where the SR OS node is the gRPC client instead of the gRPC server, the SR OS node sends a Publish RPC with a ‟SubscribeResponse” message to the gRPC server. (See Dial-out telemetry.)

Because the current gnmi.proto definition does not support dial-out mode, a protobuf definition is introduced, with a separate gRPC service, as follows:

NOKIA-DialOut.proto
      option (dialout_service) = 0.1.0
      service gMIDialOut {
              rpc Publish(stream SubscribeResponse) returns (stream PublishResponse)
      }
      message PublishResponse {
      }

The preceding proto file definition reuses the ‟SubscribeResponse” message defined for dial-in telemetry, in accordance with the gNMI specification.

Telemetry subscriptions include a set of schema paths used to identify which data nodes are of interest to the collector.

The paths in Telemetry Subscribe RPC requests follow the conventions described in the OpenConfig gnmi-path-conventions.md published on github.com (version 0.4.0, published June 21, 2017).

A path consists of a set of path segments often shown with a ‟/” character as a delimiter; for example, /configure/router[router-instance=Base]/interface[interface-name=my-interface1]/description.

These paths are encoded as a set of individual string segments in gnmi.proto (without any ‟/” characters); for example, ["configure", "router[router-name=Base]", "interface[interface-name=my-interface1]", "description"].

A path selects an entire subtree of the data model and includes all descendants of the node indicated in the path. Schema paths describes the types of schema paths that are supported in SR OS telemetry.

The following list describes the telemetry paths support in SR OS.

• The following wildcards are supported in the schema:

  • Specifying ‟/…” wildcard expands to multiple element levels in a path.

  • Specifying ‟/*” wildcard expands to only one level in a path.

• Wildcards for entire path segments are supported as follows:

  • For example: ‟/state/card/.../oper-state” expands to following paths

    /state/card[slot-number=*]/hardware-data/oper-state

    /state/card[slot-number=*]/mda[mda-slot=*]/hardware-data/oper-state

    /state/card[slot-number=*]/mda[mda-slot=*]/flex[group-index=*]/oper-state

  • For example: ‟/state/card/*/oper-state” expands to following path

    /state/card[slot-number=*]/hardware-data/oper-state

• If a wildcard is used for any key of a list, a wildcard must be used for all the keys of that list. In a single path segment, all keys must either have specific values or all keys must have wildcards. A mix of wildcards and specific values for different parts of a list key is not supported. For example:

  Supported:

  /a/b[key1=*][key2=*]/c[key1=foo]

  /a/b[key1=foo][key2=bar]/c[key1=*]

  Not supported:

  /a/b[key1=foo][key2=*]

• Functions such as ‟current()”, ‟last()” and mathematical operators, such as stat<5 or octets>3 are not supported in paths. The ‟|” (OR operator, used to select multiple paths) is not supported.

• Wildcards in multiple segments of a path are supported.

  For example: /state/card[slot-number=*]/mda[mda-slot=*]

• The paths with wildcards are expanded when a subscription is activated; this applies to dynamic and persistent subscriptions. In some cases, it is possible that a single path with wild cards can be expanded across both Nokia and Openconfig YANG models. However, this occurs only if both model types are enabled. If only one type is enabled, the path is expanded only within the enabled model. If the other type is enabled later, it is necessary to reset all subscriptions, which ensures that the expansion includes the newly enabled model type.

Telemetry is a network monitoring and fault management framework. Telemetry is driven by the need to use fresh data obtained from the network to make fast networking decisions such as traffic optimization and preventive troubleshooting.

NE configuration and information retrieval using gNMI service shows NE configuration and information retrieval using the gNMI service.

In the context of gNMI, every SET RPC appears as an single commit operation, regardless of the number of paths included in the message. Both, Nokia and OC models are supported by gNMI SET/GET RPC.

An example of the SET RPC command (including the response message from the gRPC server) follows:

 gNMI_rpc - DEBUG - SENT::SetRequest
prefix {
}
update {
  path {
    elem {
      name: "configure"
    }
    elem {
      name: "system"
    }
 }
 val {
   json_val: {"location": "zurich"}
 }
}
gMI_rpc - DEBUG - RCVD::SetResponse
prefix {
}
response {
  path {
    elem {
      name: "configure"
    }
    elem {
      name: "system"
    }
  }
  op: UPDATE
} 

An example of the GET RPC command (including the response message from the gRPC server) follows:

gNMI_rpc - INFO - SENT::GetRequest GET140550212650064
path {
  elem {
    name: "configure"
  }
  elem {
    name: "system"
  }
  elem {
    name: "location"
  }
}
type: CONFIG
2017-12-06 12:17:28,639 - gMI_rpc - INFO - 
 RCVD::GetResponse GET140550212650064
notification {
  timestamp: 1512559048634751055
  update {
  path {
    elem {
      name: "configure"
    }
    elem {
      name: "system"
    }
    elem {
      name: "location"
    }
  }
  val {
    json_val: "zurich"
  }
 }
}

RPC GetCertificates provide information to the controller about all active certificates on the server (SR OS node). RPC GetCertificates message flow shows the message sequence.

The RPC GetCertificates messages include a GetCertificateRequest and a GetCertificateRespone message. The GetCertificatesResponse message shown in RPC GetCertificates message flow includes the following information:

• certificate_id

  The SR OS uses a certificate filename as the certificate ID.

• CertificateType

  This is always set to X509, because it is the only type that the SR OS supports.

• endpoint

  This indicates the CERT profiles in the SR OS node that use this certificate; if multiple CERT profiles use the certificate, the names are concatenated with the separation character ‟/”.

The RPC CanGenerateCSR message can be used to determine if the gRPC server (SR OS node) can generate a Certificate Signing Request (CSR). It is a simple request and response operation as shown in RPC CanGenerateCSR message flow.

The SR OS only supports RSA keys and X509 certificates, so it only responds positively if those values are filled in the respective fields. The key size must be between 512 and 8192. In all other cases, the SR OS responds negatively to the CanGenerateCSRRequest message.

RPC Rotate allows the controller to rotate an active certificate on the server. After the rotation is completed, a new certificate can be used without affecting existing TLS connections.

The following cases are supported for a certificate rotation:

• server capable of generating a CSR (see RPC Rotate message flow for CSRs generated on the SR OS node)

• server not capable of generating a CSR (see RPC Rotate message flow when CSRs are not generated on the SR OS node)

The SR OS supports both scenarios, although it is assumed that in most cases the CSR is generated on SR OS node.

The following steps apply to both scenarios:

1. Generate the CSR.

2. Sign the CSR by the Certificate Authority (CA).

3. Load the new certificate on the server.

4. Verify the new certificate by creating a new connection.

5. Finalize by confirming that the new certificate is being used.

After the RPC Rotate is completed, all new connections use new keys.

From the perspective of the interaction of the controller and the server (SR OS) two stages are the most important:

• message exchange to generate the CSR

• message exchange to load the new certificates on the server

GenerateCSR message flow shows a detailed content of the messages that are exchanged for CSR generation. The SR OS accepts requests only for the X509 certificate type, RSA key type, and a minimum key length of 512 bits.

For RPC Rotate, the certificate_id points to an existing certificate on the node. All the other parameters in the GenerateCSRRequest message are not checked by the SR OS software explicitly. They are used by the internal API to generate the CSR and that result is transparently passed to the controller.

After the CA signs the certificates, the files are loaded to the server using LoadCSRRequest and LoadCSRResponse message exchange, as shown in LoadCSRRequest/Response message flow. If this message exchange is used in the context of RPC Rotate, the certificate_id should not be present in LoadCSRRequest message. When the SR OS receives the message, it performs all the necessary steps to load this certificate, including storing the certificate and key files on the disk.

The controller is responsible for verifying the connection with the new certificate (Step 4 in RPC Rotate message flow for CSRs generated on the SR OS node and RPC Rotate message flow when CSRs are not generated on the SR OS node); SR OS treats this as an optional step.

After the whole RPC is successfully closed, the system can use the new certificate to start new TLS connections.

The controller can use RPC Install to install a new certificate on the server. After the certificate is installed, the server must be configured (assign a certificate and key files in the CERT profile) before the new certificate can be used.

The following two possible cases are supported for installing a certificate:

• server capable of generating a CSR (see RPC install message flow for CSRs generated on the SR OS node)

• server is not capable of generating a CSR (see RPC install message flow if CSRs are not generated on the SR OS node)

The SR OS supports both scenarios, although it is assumed that in most cases the CSR is generated on the SR OS node.

Both scenarios require the following steps:

1. Generate the CSR.

2. Sign the CSR by the Certificate Authority (CA).

3. Load the new certificate on the server.

The message exchange during phases 1 and 3 is the same as shown in GenerateCSR message flow and LoadCSRRequest/Response message flow. The only difference, in the case of RPC Install, is that, a new certificate_id is used.

After new certificates are installed, the system must be configured before it can be used. Configuration is supported using the following methods:

• an existing gRPC session

• a CLI session, SNMP, or NETCONF

The purpose of the RPC RevokeCertificates is to render the existing certificate unusable by any client. In cases where the certificate being revoked by the client does not exist on the SR OS node, the corresponding RPC silently succeeds. The message flow is shown in RPC RevokeCertificates message flow.