gRPC Commands

This module describes the commands used to use the gRPC Protocol to define network operations with data models.

For detailed information about gRPC concepts, configuration tasks, and examples, see the Use gRPC Protocol to Define Network Operations with Data Models in the Cisco ASR 9000 Series Router module in the Programmability Configuration Guide for Cisco ASR 9000 Series Routers.

gRPC encodes requests and responses in binary. gRPC is extensible to other content types along with Protobuf. The Protobuf binary data object in gRPC is transported over HTTP/2.

grpc aaa accounting history-memory

To configure the maximum memory allocated for cached accounting history records, use the grpc aaa accounting history-memory command in the Global Configuration mode.

This command should be used in conjunction with the queue-size parameter to effectively limit the EMSD memory used by cached accounting history records. The approximate worst case memory usage would be (N+1)* history-memory, where N is the number of collectors connected.

grpc aaa accounting history-memory size

Syntax Description

size

Specifies the maximum memory allocated for cached accounting history records.

Command Default

The default size of the history memory is 40 MB. The size range is 1-400 MB.

Command Modes

Global Configuration mode

Command History

Release

Modification

Release 24.4.1

The command was introduced.

Usage Guidelines

None

Task ID

Task ID Operation

config-services

read, write

Examples

This example configures the maximum memory allocated for cached accounting history records to the specified size.

Router(config)#grpc aaa accounting history-memory 20

This example displays the memory configuration specified in the previous example.

Router(config)#show
Tue Jul 23 06:12:38.693 UTC
!! Building configuration...
!! IOS XR Configuration 24.4.1.17I
grpc
 aaa accounting history-memory 20
!
end

RP/0/RP0/CPU0:ios(config)#commit
Tue Jul 23 06:12:41.336 UTC
Router(config)#

Use the show gnsi acctz statistics command to display the maximum queue size configured using the grpc aaa accounting queue-size command.

grpc aaa accounting queue-size

To configure the number of accounting records in a queue, use the grpc aaa accounting queue-size command in the Global Configuration mode.

grpc aaa accounting queue-size size

Syntax Description

size

Specifies the number of accounting history records in a queue. The default value is 40, and it ranges from 1—512.

Command Default

None

Command Modes

Global Configuration mode

Command History

Release

Modification

Release 24.3.1

The command was introduced.

Usage Guidelines

None

Task ID

Task ID Operation

config-services

read, write

Examples

This example configures the maximum size for history record processing queues to the specified value.

Router# configure
Router(config)# grpc aaa accounting queue-size 30
Router(config)# end

grpc certificate common-name

To allow the router (tunnel client) to dial out to a collector (tunnel server), use the grpc command in the XR Config mode. To remove the gRPC service, use the no form of this command.

grpc certificate common-name WORD

Syntax Description

WORD

Specifies the common name when certificate is generated, default: ems.cisco.com .

Command Default

None

Command Modes

XR Config mode

Command History

Release

Modification

Release 24.1.1

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

config-services

read, write

Examples

The following example shows how to specify a common-name:

Router(config)#grpc
Router(config-grpc)#certificate common-name
Router(config-grpc)#commit

gnsi load service authorization policy

To instruct the router to load the service authorization policy file into its memory and update the policy, use the gnsi load service authorization policy command in Global Configuration Mode.

gnsi load service authorization policy file_path

Syntax Description

file-path

Specifies the path of the policy file.

Command Default

Enabled, by default

Command Modes

Global Configuration Mode

Command History

Release

Modification

Release 7.11.1

This command was introduced.

Usage Guidelines

A policy file which has no specified or the policy is invalid, the default behavior will transition to the zero-policy behavior. Zero-policy allows all gRPC services to all the users if their profiles are configured.

Task ID

Task ID Operation
config-services

read, write

Examples

This example shows how to activate the authorization policy test.json in the router.

Router(config)#gnsi load service authorization policy /disk0:/test.json
Successfully loaded policy

grpc gnsi service certz ssl-profile-id

To instruct the router to load the certz.proto, use the grpc gnsi service certz ssl-profile-id command in Global Configuration Mode. To disable the SSL profiles configured with certz.proto, use the no form of the command.

grpc gnsi service certz ssl-profile-id ssl-profile name

Syntax Description

ssl-profile name

Specifies the SSL-profile name for which certz. proto needs to be activated.

Command Default

None

Command Modes

Global Configuration Mode

Command History

Release

Modification

Release 24.1.1

This command was introduced.

Usage Guidelines

If Certz. proto is not active, then gNOI cert.proto is taken into consideration. If niether certz.proto nor cert.proto is active, then TLS trustpoint's data is considered.

Task ID

Task ID Operation
config-services

read, write

Examples

This example shows how to activate the certz.proto in the router.

Router(config)#grpc gnsi service certz ssl-profile-id gNxI
Router(config)#commit

grpc max-concurrent-streams

To specify a limit on the number of concurrent streams per gRPC connection to be applied on the server, use the grpc max-concurrent-streams command in the Global Configuration mode. To restore the default value, use the no form of this command.

grpc max-concurrent-streams limit

Syntax Description

max-concurrent-streams limit

Specifies the limit on the number of concurrent streams per gRPC connection to be applied on the server. The range is from 1 to 128. The command default is 32.

Command Default

By default, the maximum concurrent streams per gRPC connection is 32.

Command Modes

Global Configuration mode

Command History

Release

Modification

Release 24.1.1

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

config-services

read, write

Examples

The following example shows how to set the limit of the number of concurrent streams per gRPC connection to 40:

Router#configure
Router(config)#grpc max-concurrent-streams 40

script exec

To execute a script provided by Cisco, use the script exec command in EXEC mode.

script exec { auto-update file-name remote-server-path condition [ manual | on-run | schedule ] | file-name }

Syntax Description

auto-update

It enables routers to automatically update the local copy of the scripts with the latest copy of the scripts on the server.

manual

It enables routers to update the scripts at any specific time.

on-run

It enables routers to update the scripts during run time.

Only the exec scripts support the on-run option.

schedule

It enables routers to update the scripts at a scheduled time.

The schedule option does not support SCP protocol.

file-name

Specifies the file name of the script file. The script file must be in .py format.

Command Default

None

Command Modes

EXEC mode

Command History

Release

Modification

Release 7.5.1

This command was introduced.

Usage Guidelines

The script EXEC command opens the script utility, which allows you to execute Cisco-supplied scripts. The script utility can read standard terminal input from the user if the script you run requires input from the user.


Note

The script utility is designed to run only Cisco-supplied scripts. You cannot execute script files that lack Cisco signatures or that have been corrupted or modified.

When you run the script, the script is downloaded and the checksum is automatically configured on the router.

  • If on-run option is configured, running the script run command downloads the script.

  • If manual option is configured, then you must run script update Exec command.

  • If schedule option is selected, then the script is automatically updated after the specified interval.

Task ID

Task ID

Operations

config-services

read, write

Examples

The following example displays sample3.py script is automatically updated from the remote server at http://10.23.255.205:


Router# configure
Router(config)# script exec auto-update sample3.py http://10.23.255.205 condition manual

show gnsi acctz statistics

To display the detailed statistics for GNSI Acctz accounting, use the show gnsi acctz statistics command in the EXEC mode.

This command provides these information:

  • per service counter

  • drop counter

  • rate of accounting events

  • history

  • connected collectors

  • collector per service record counters

show gnsi acctz statistics

Syntax Description

This command has no keywords or arguments.

Command Default

None

Command Modes

EXEC mode

Command History

Release

Modification

Release 24.3.1

The command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID Operation

config-services

read, write

Examples

This example displays detailed statistics for GNSI Acctz accounting with the maximum queue size specified in the grpc aaa accounting queue-size command configuration examples respectively. 

Router#show gnsi acctz statistics
Tue Jul 23 05:59:28.755 UTC
Acctz History Buffer:
  Total Records                    : 80029
  Total History Truncation         : 0
    Grpc Service Records:
      GNMI                         : 80002
      GNOI                         : 0
      GNSI                         : 4
      GRIBI                        : 0
      P4RT                         : 0
      Unspecified                  : 0
    Cmd Service Records:
      Shell                        : 0
      Cli                          : 23
      Netconf                      : 0
      Unspecified                  : 0
  History snapshot:
    Max Memory Size                : 20 MB
    Memory Used                    : 0 MB
    Max Number Of Records          : 30
    Records Used                   : 30
gRPC Accounting Queue:
  Grpc services:
    GNMI                           : 80002 sent, 0 dropped, 0 truncated
    GNOI                           : 0 sent, 0 dropped, 0 truncated
    GNSI                           : 4 sent, 0 dropped, 4 truncated
    GRIBI                          : 0 sent, 0 dropped, 0 truncated
    P4RT                           : 0 sent, 0 dropped, 0 truncated
    Unspecified                    : 0 sent, 0 dropped, 0 truncated
  Queue Rate:
    Input                          : 80000
    Output                         : 80000
    Drop                           : 0
  Stats:
    Queue Buffer Used              : 0 MB
    Queue Enqueue                  : 80006
    Queue Dequeue                  : 80006
    Queue Drops                    : 0
    Queue Max Time                 : 14311 usec
    Queue Min Time                 : 1 usec
    Queue Avg Time                 : 504 usec
  Channel Stats:
    Queue Channel Size             : 512
    Queue Channel Length           : 0
    Queue Inuse Size               : 0
    Queue Size                     : 30
    Queue Low Water Mark           : 1
    Queue Water Mark               : false
    Queue Channel Closed           : false
    Queue Status                   : 2
    Queue Enqueue Count            : 80006
    Queue Decrement Count          : 80006
    Queue Retry Count              : 0
    Queue Retry Full Count         : 0
  Errors:
    Queue Init Failure             : 0
    Queue Update Failure           : 0
    Queue Dequeue Failure          : 0
    Queue Invalid Parameters       : 0
SendtoAAA Accounting Queue:
  Grpc services:
    GNMI                           : 80002 sent, 0 dropped, 0 truncated
    GNOI                           : 0 sent, 0 dropped, 0 truncated
    GNSI                           : 4 sent, 0 dropped, 0 truncated
    GRIBI                          : 0 sent, 0 dropped, 0 truncated
    P4RT                           : 0 sent, 0 dropped, 0 truncated
    Unspecified                    : 0 sent, 0 dropped, 0 truncated
  Queue Rate:
    Input                          : 80000
    Output                         : 80000
    Drop                           : 0
  Stats:
    Queue Buffer Used              : 0 MB
    Queue Enqueue                  : 80006
    Queue Dequeue                  : 80006
    Queue Drops                    : 0
    Queue Max Time                 : 66549 usec
    Queue Min Time                 : 1 usec
    Queue Avg Time                 : 2544 usec
  Channel Stats:
    Queue Channel Size             : 512
    Queue Channel Length           : 0
    Queue Inuse Size               : 0
    Queue Size                     : 40
    Queue Low Water Mark           : 1
    Queue Water Mark               : false
    Queue Channel Closed           : false
    Queue Status                   : 2
    Queue Enqueue Count            : 80006
    Queue Decrement Count          : 80006
    Queue Retry Count              : 0
    Queue Retry Full Count         : 0
  Errors:
    Queue Init Failure             : 0
    Queue Update Failure           : 0
    Queue Dequeue Failure          : 0
    Queue Invalid Parameters       : 0
Cmd Accounting Queue:
  Cmd services:
    Shell                          : 0 sent, 0 dropped, 0 truncated
    Cli                            : 23 sent, 0 dropped, 0 truncated
    Netconf                        : 0 sent, 0 dropped, 0 truncated
    Unspecified                    : 0 sent, 0 dropped, 0 truncated
  Queue Rate:
    Input                          : 2
    Output                         : 2
    Drop                           : 0
  Stats:
    Queue Buffer Used              : 0 MB
    Queue Enqueue                  : 23
    Queue Dequeue                  : 23
    Queue Drops                    : 0
    Queue Max Time                 : 248 usec
    Queue Min Time                 : 26 usec
    Queue Avg Time                 : 94 usec
  Channel Stats:
    Queue Channel Size             : 512
    Queue Channel Length           : 0
    Queue Inuse Size               : 0
    Queue Size                     : 40
    Queue Low Water Mark           : 1
    Queue Water Mark               : false
    Queue Channel Closed           : false
    Queue Status                   : 2
    Queue Enqueue Count            : 23
    Queue Decrement Count          : 23
    Queue Retry Count              : 0
    Queue Retry Full Count         : 0
  Errors:
    Queue Init Failure             : 0
    Queue Update Failure           : 0
    Queue Dequeue Failure          : 0
    Queue Invalid Parameters       : 0
Client Stats:
  Number Of Clients                : 2
  History Truncation Events        : 0
  Client Idle Timeouts             : 0
  Record Requests                  : 4
  Record Responses                 : 80029
Collectors:
  Collector Statistics:
    IP                             : 192.168.122.1
    Port                           : 25906
    Total                          : Records: 80029, Drops: 0
    Total History Truncation       : 0
    Grpc Service Records:
      gNMI                         : Records: 80002, Drops: 0
      gNOI                         : Records: 0, Drops: 0
      gNSI                         : Records: 4, Drops: 0
      gRIBI                        : Records: 0, Drops: 0
      P4RT                         : Records: 0, Drops: 0
      Unspecified                  : Records: 0, Drops: 0
    Cmd Service Records:
      Shell                        : Records: 0, Drops: 0
      CLI                          : Records: 23, Drops: 0
      Netconf                      : Records: 0, Drops: 0
      Unspecified                  : Records: 0, Drops: 0
   gRPC Stream Stats:
    gRPC Stream Status             : 2
    gRPC Send Status               : 1
    gRPC Send Error Channel Length : 0
    gRPC Send Errors               : 0
    gRPC Send Enqueue Count        : 80029
    gRPC Send Close Count          : 0
    gRPC Stream Send Count         : 80029
    gRPC Stream Send Error Count   : 0
  Send Channel Stats:
    Queue Channel Size             : 512
    Queue Channel Length           : 0
    Queue Inuse Size               : 0
    Queue Size                     : 40
    Queue Low Water Mark           : 0
    Queue Water Mark               : false
    Queue Channel Closed           : false
    Queue Status                   : 2
    Queue Enqueue Count            : 80029
    Queue Decrement Count          : 80029
    Queue Retry Count              : 0
    Queue Retry Full Count         : 0
  Collector Statistics:
    IP                             : 192.168.122.1
    Port                           : 25912
    Total                          : Records: 80029, Drops: 0
    Total History Truncation       : 0
    Grpc Service Records:
      gNMI                         : Records: 80002, Drops: 0
      gNOI                         : Records: 0, Drops: 0
      gNSI                         : Records: 4, Drops: 0
      gRIBI                        : Records: 0, Drops: 0
      P4RT                         : Records: 0, Drops: 0
      Unspecified                  : Records: 0, Drops: 0
    Cmd Service Records:
      Shell                        : Records: 0, Drops: 0
      CLI                          : Records: 23, Drops: 0
      Netconf                      : Records: 0, Drops: 0
      Unspecified                  : Records: 0, Drops: 0
   gRPC Stream Stats:
    gRPC Stream Status             : 2
    gRPC Send Status               : 1
    gRPC Send Error Channel Length : 0
    gRPC Send Errors               : 0
    gRPC Send Enqueue Count        : 80029
    gRPC Send Close Count          : 0
    gRPC Stream Send Count         : 80029
    gRPC Stream Send Error Count   : 0
  Send Channel Stats:
    Queue Channel Size             : 512
    Queue Channel Length           : 0
    Queue Inuse Size               : 0
    Queue Size                     : 40
    Queue Low Water Mark           : 0
    Queue Water Mark               : false
    Queue Channel Closed           : false
    Queue Status                   : 2
    Queue Enqueue Count            : 80029
    Queue Decrement Count          : 80029
    Queue Retry Count              : 0
    Queue Retry Full Count         : 0
Accounting Stats:
  Grpc Accounting                  : 80006
  Cmd Accounting                   : 23
Error Stats:
  AAA Dequeue Failed               : 0
  AAA Payload Failed               : 0
  Send To AAA Failed               : 0
  gRPC Dequeue Failed              : 0
  Cmd Dequeue Failed               : 0
  Accounting Payload Failed        : 0
  Record Create Failed             : 0
  Get RPC Failed                   : 0
  Get Method Failed                : 0
  Serialize Payload Failed         : 0
  Record Response Payload Failed   : 0
  Get Local Info Failed            : 0
  Get Remote Info Failed           : 0
  Get Username Failed              : 0
  Locald Invalid Service Type      : 0

show gnsi service authorization policy

To display the active gRPC service authorization policies on the router, use the show gnsi service authorization policy command in Global Configuration mode.

show gnsi service authorization policy

Syntax Description

This command has no keywords or arguments.

Command Default

Enabled, by default

Command Modes

Global Configuration mode

Command History

Release

Modification

Release 7.11.1

The command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID Operation
config-services

read

Examples

This example displays the policy which is active on the router:

Router#show gnsi service authorization policy
Wed Jul 19 10:56:14.509 UTC{
    "version": "1.0",
    "created_on": 1700816204,
    "policy": {
        "name": "authz",
        "allow_rules": [
            {
                "name": "allow all gNMI for all users",
                "request": {
                    "paths": [
                        "*"
                    ]
                },
                "source": {
                    "principals": [
                        "*"
                    ]
                }
            }
        ],
        "deny_rules": [
            {
                "name": "deny gNMI set for oper users",
                "request": {
                    "paths": [
                        "/gnmi.gNMI/*"
                    ]
                },
                "source": {
                    "principals": [
                        "User1"
                    ]
                }
            }
        ]
    }
}

show grpc certificate

To display the active gRPC certificate management policies on the router, use the show grpc certificate command in EXEC mode.

show grpc certificate

Syntax Description

This command has no keywords or arguments.

Command Default

None

Command Modes

EXEC mode

Command History

Release

Modification

Release 24.1.1

The command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID Operation
config-services

read

Examples

This example displays the active gRPC certificate management policies on the router. The below-mentioned command output is truncated version. 

Router#show grpc certificate
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 32 (0x20)
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=localhost,O=OpenConfig,C=US
        Validity
            Not Before: Nov  8 08:49:38 2023 GMT
            Not After : Mar 22 08:49:38 2025 GMT
        Subject: CN=ems,O=OpenConfig,C=US
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (4096 bit)
                Modulus:
                    00:ea:6a:6c:25:be:9f:15:71:ce:74:89:03:ec:ef:
                    0b:3b:de:58:a8:7e:28:b8:cf:b3:82:91:b4:5c:42:
                    e7:d8:28:98:35:bd:35:60:a7:4e:f8:77:02:46:5f:
                    27:a4:16:cf:3c:e3:24:28:69:9c:22:1e:e3:52:96:
                    71:87:7c:40:0c:1f:dd:30:ea:dc:40:ca:93:00:54:
                    5e:de:20:54:5b:f4:2f:9f:19:6f:71:61:28:69:3d:
                    97:26:ab:e1:5f:53:3c:f1:a2:c3:14:f4:01:90:1a:
                    .
                    .
                    .
                    
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature
            X509v3 Extended Key Usage: 
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Authority Key Identifier: 
                keyid:0A:A8:9A:6A:23:34:AE:CA:96:00:2C:F3:04:38:14:E3:D4:8D:77:BD

            X509v3 Subject Alternative Name: 
                DNS, IP Address:64.103.223.56
    Signature Algorithm: sha256WithRSAEncryption
         b9:89:ec:60:3d:8d:7d:9c:dc:08:56:89:99:44:92:98:45:b6:
         97:ba:e3:e5:f2:48:b2:44:8d:db:23:bb:a1:c0:62:79:78:18:
         d7:55:f6:4a:67:5b:75:e0:c0:0b:52:51:07:36:d5:6c:c7:67:
         48:86:8d:dd:70:1c:9f:7c:a1:7b:aa:a5:4e:e1:ad:cf:4c:e5:
         81:db:92:cf:88:70:5a:1c:8d:de:0d:e8:b3:05:de:b9:04:4d:
         23:e1:de:66:e5:08:bd:2e:31:0a:07:a6:c0:00:3a:38:2f:00:
         .
         .
         .

show tech-support script

To collect logs that contain debug information for logical traces and tech-support data, use the show tech-support script command in EXEC mode.

script tech-support script { file | filepath_filename | list-CLIs | time-out }

Syntax Description

file filepath_filename

Specifies the complete path to a file, including the filename to save the log.

list-CLIs

Creates a log zip file containing a list of all CLI commands executed as part of the tech-support script. The CLI commands are only listed, not executed.

time-out

Specifies the timeout value for each command in seconds ranging from 120-3600 seconds. By default, the timeout is 900 seconds.

Command Default

None

Command Modes

EXEC mode

Command History

Release

Modification

Release 7.5.1

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

config-services

read, write

Examples

This example displays how to save the logical traces and tech-support data in the test file in the disk0 path:

Router# show tech-support script file disk0:/test.log
Wed Sep 25 07:11:39.915 PDT
++ Show tech start time: 2024-Sep-25.071140.PDT ++
Wed Sep 25 07:11:40 PDT 2024 Waiting for gathering to complete
......................
Wed Sep 25 07:12:49 PDT 2024 Compressing show tech output
Show tech output available at 0/RP0/CPU0 : /disk0:/test.log.tgz
++ Show tech end time: 2024-Sep-25.071250.PDT ++