Set

Description#

The set command represents the gNMI Set RPC.

It is used to send a Set Request to the specified target(s) and expects one Set Response per target.

Set RPC allows the client to modify the state of data on the target. The data specified referenced by a path can be updated, replaced or deleted.

Note

It is possible to combine update, replace and delete in a single gnmic set command.

Usage#

gnmic [global-flags] set [local-flags]

The Set Request can be any of (or a combination of) update, replace or/and delete operations.

Common flags#

prefix#

The --prefix flag sets a common prefix to all paths specified using the local --path flag. Defaults to "".

If a user needs to provide origin information to the Path message, the following pattern should be used for the path string: "origin:path":

Note

The path after the origin value has to start with a /

gnmic set --update "openconfig-interfaces:/interfaces/interface:::<type>:::<value>"

target#

With the optional [--target] flag it is possible to supply the path target information in the prefix field of the SetRequest message.

Update Request#

There are several ways to perform an update operation with gNMI Set RPC:

1. in-line update, implicit type#

Using both --update-path and --update-value flags, a user can update a value for a given path.

gnmic set --update-path /configure/system/name --update-value router1

gnmic set --update-path /configure/router[router-name=Base]/interface[interface-name=system]/admin-state \
          --update-value enable

The above 2 updates can be combined in the same cli command:

gnmic set --update-path /configure/system/name \
          --update-value router1 \
          --update-path /configure/router[router-name=Base]/interface[interface-name=system]/admin-state \
          --update-value enable

2. in-line update, explicit type#

Using the update flag --update, one can specify the path, value type and value in a single parameter using a delimiter --delimiter. Delimiter string defaults to ":::".

Supported types: json, json_ietf, string, int, uint, bool, decimal, float, bytes, ascii.

# path:::value-type:::value
gnmic set --update /configure/system/name:::json:::router1

gnmic set --update /configure/router[router-name=Base]/interface[interface-name=system]/admin-state:::json:::enable

gnmic set --update /configure/router[router-name=Base]/interface[interface-name=system]:::json:::'{"admin-state":"enable"}'

3. update with a value from JSON or YAML file#

It is also possible to specify the values from a local JSON or YAML file using --update-file flag for the value and --update-path for the path.

In which case the value encoding will be determined by the global flag [ -e | --encoding ], both JSON and JSON_IETF are supported

The file's format is identified by its extension, json: .json and yaml .yaml or .yml.

interface.json

{
    "admin-state": "enable",
    "ipv4": {
        "primary": {
            "address": "1.1.1.1",
            "prefix-length": 32
        }
    }
}

gnmic set --update-path /configure/router[router-name=Base]/interface[interface-name=system] \
          --update-file interface.json

interface.yml

"admin-state": enable
"ipv4":
"primary":
    "address": 1.1.1.1
    "prefix-length": 32

gnmic set --update-path /configure/router[router-name=Base]/interface[interface-name=system] \
          --update-file interface.yml

Replace Request#

There are 3 main ways to specify a replace operation:

1. in-line replace, implicit type#

Using both --replace-path and --replace-value flags, a user can replace a value for a given path. The type of the value is implicitly set to JSON:

gnmic set --replace-path /configure/system/name --replace-value router1

gnmic set --replace-path /configure/router[router-name=Base]/interface[interface-name=system]/admin-state \
          --replace-value enable

The above 2 commands can be packed in the same cli command:

gnmic set --replace-path /configure/system/name \
          --replace-value router1 \
          --replace-path /configure/router[router-name=Base]/interface[interface-name=system]/admin-state \
          --replace-value enable

2. in-line replace, explicit type#

Using the replace flag --replace, you can specify the path, value type and value in a single parameter using a delimiter --delimiter. Delimiter string defaults to ":::".

Supported types: json, json_ietf, string, int, uint, bool, decimal, float, bytes, ascii.

gnmic set --replace /configure/system/name:::json:::router1

gnmic set --replace /configure/router[router-name=Base]/interface[interface-name=system]/admin-state:::json:::enable

3. replace with a value from JSON or YAML file#

It is also possible to specify the values from a local JSON or YAML file using flag --replace-file for the value and --replace-path for the path.

In which case the value encoding will be determined by the global flag [ -e | --encoding ], both JSON and JSON_IETF are supported

The file is identified by its extension, json: .json and yaml .yaml or .yml.

interface.json

{
    "admin-state": "enable",
    "ipv4": {
        "primary": {
            "address": "1.1.1.1",
            "prefix-length": 32
        }
    }
}

interface.yml

"admin-state": enable
"ipv4":
"primary":
    "address": 1.1.1.1
    "prefix-length": 32

Then refer to the file with --replace-file flag

gnmic set --replace-path /configure/router[router-name=Base]/interface[interface-name=system] \
          --replace-file interface.json

Delete Request#

A deletion operation within the Set RPC is specified using the delete flag --delete.

It takes an XPATH pointing to the config node to be deleted:

gnmic set --delete "/configure/router[router-name=Base]/interface[interface-name=dummy_interface]"

Template Based Set Request#

A Set Request can also be built based on a template and (optionally) a set of variables.

The variables allow to generate the request on per target basis.

If no variable file is found, the execution continues and the template is assumed to be a static string.

A template results in a single gNMI Set Request.

Template Format#

The rendered template data can be a JSON or YAML valid string.

It has 3 sections, updates, replaces and deletes.

In each of the updates and replaces, a path, a value and an encoding can be configured.

If not specified, path defaults to /, while encoding defaults to the value set with --encoding flag.

updates and replaces result in a set of gNMI Set Updates in the Set RPC, deletes result in a set of gNMI paths to be deleted.

The value can be any arbitrary data format that the target accepts, it will be encoded based on the value of "encoding".

JSON

{
  "updates": [
      {
          "path": "/interface[name=ethernet-1/1]",
          "value": {
              "admin-state": "enable",
              "description": "to_spine1"
           },
           "encoding": "json_ietf"
      },
      {
          "path": "/interface[name=ethernet-1/2]",
          "value": {
              "admin-state": "enable",
              "description": "to_spine2"
           },
           "encoding": "json_ietf"
      }
  ],
  "replaces": [
      {
          "path": "/interface[name=ethernet-1/3]",
          "value": {
              "admin-state": "enable",
              "description": "to_spine3"
           }
      },
       {
          "path": "/interface[name=ethernet-1/4]",
          "value": {
              "admin-state": "enable",
              "description": "to_spine4"
           }
      }
  ],
  "deletes" : [
      "/interface[name=ethernet-1/5]",
      "/interface[name=ethernet-1/6]"
  ]
}

YAML

updates:
  - path: "/interface[name=ethernet-1/1]"
    value:
      admin-state: enable
      description: "to_spine1"
    encoding: "json_ietf"
  - path: "/interface[name=ethernet-1/2]"
    value:
      admin-state: enable
      description: "to_spine2"
    encoding: "json_ietf"
replaces:
  - path: "/interface[name=ethernet-1/3]"
    value:
      admin-state: enable
      description: "to_spine3"
  - path: "/interface[name=ethernet-1/4]"
    value:
      admin-state: enable
      description: "to_spine4"
deletes:
  - "/interface[name=ethernet-1/5]"
  - "/interface[name=ethernet-1/6]"

Per Target Template Variables#

The file --request-file can be written as a Go Text template.

The parsed template is loaded with the excellent library of additional functions sprig.

gnmic generates one gNMI Set request per target.

The template will be rendered using variables read from the file --request-vars. Just like the template file, the variables file can either be a JSON or YAML formatted file.

If the flag --request-vars is not set, gnmic looks for a file with the same path, name and extension as the request-file, appended with _vars.

Within the template, the variables defined in the --request-vars file are accessible using the .Vars notation, while the target name is accessible using the .TargetName notation.

Example request template:

replaces:
{{- range $interface := index .Vars .TargetName "interfaces" }}
  - path: "/interface[name={{ index $interface "name" }}]"
    encoding: "json_ietf"
    value: 
      admin-state: {{ index $interface "admin-state" | default "disable" }}
      description: {{ index $interface "description" | default "" }}
    {{- range $index, $subinterface := index $interface "subinterfaces" }}
      subinterface:
        - index: {{ $index }}
          admin-state: {{ index $subinterface "admin-state" | default "disable" }}
          {{- if hasKey $subinterface "ipv4-address" }}
          ipv4:
            address:
              - ip-prefix: {{ index $subinterface "ipv4-address" | toString }}
          {{- end }}
          {{- if hasKey $subinterface "ipv6-address" }}
          ipv6:
            address:
              - ip-prefix: {{ index $subinterface "ipv6-address" | toString }}
          {{- end }}
    {{- end }}
{{- end }}

The below variables file defines the input for 3 leafs:

leaf1:57400:
  interfaces:
    - name: ethernet-1/1
      admin-state: "enable"
      description: "leaf1_to_spine1"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.78.1/30
    - name: ethernet-1/2
      admin-state: "enable"
      description: "leaf1_to_spine2"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.79.1/30

leaf2:57400:
  interfaces:
    - name: ethernet-1/1
      admin-state: "enable"
      description: "leaf2_to_spine1"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.88.1/30
    - name: ethernet-1/2
      admin-state: "enable"
      description: "leaf2_to_spine2"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.89.1/30

leaf3:57400:
  interfaces:
    - name: ethernet-1/1
      admin-state: "enable"
      description: "leaf3_to_spine1"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.98.1/30
    - name: ethernet-1/2
      admin-state: "enable"
      description: "leaf3_to_spine2"
      subinterfaces:
        - admin-state: enable
          ipv4-address: 192.168.99.1/30

Result Request file per target:

leaf1

updates:
  - path: /interface[name=ethernet-1/1]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf1_to_spine1
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.78.1/30
  - path: /interface[name=ethernet-1/2]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf1_to_spine2
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.79.1/30

leaf2

updates:
  - path: /interface[name=ethernet-1/1]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf2_to_spine1
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.88.1/30 
  - path: /interface[name=ethernet-1/2]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf2_to_spine2
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.89.1/30

leaf3

updates:
  - path: /interface[name=ethernet-1/1]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf3_to_spine1
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.98.1/30 
  - path: /interface[name=ethernet-1/2]
    encoding: "json_ietf"
    value: 
      admin-state: enable
      description: leaf3_to_spine2
      subinterface:
        - index: 0
          admin-state: enable
          ipv4:
            address:
              - ip-prefix: 192.168.99.1/30

Examples#

1. update#

in-line value#

gnmic -a <ip:port> set --update-path /configure/system/name \
                       --update-value <system_name>

value from JSON file#

cat jsonFile.json
{"name": "router1"}

gnmic -a <ip:port> set --update-path /configure/system \
                       --update-file <jsonFile.json>

echo '{"name": "router1"}' | gnmic -a <ip:port> set \
                             --update-path /configure/system \
                             --update-file -

specify value type#

gnmic -a <ip:port> set --update /configure/system/name:::json:::router1
gnmic -a <ip:port> set --update /configure/system/name@json@router1 \
                       --delimiter @

2. replace#

cat interface.json
{"address": "1.1.1.1", "prefix-length": 32}

gnmic -a <ip:port> --insecure \
      set --replace-path /configure/router[router-name=Base]/interface[interface-name=interface1]/ipv4/primary \
          --replace-file interface.json

echo '{"address": "1.1.1.1", "prefix-length": 32}' | gnmic -a <ip:port> --insecure \
      set --replace-path /configure/router[router-name=Base]/interface[interface-name=interface1]/ipv4/primary \
          --replace-file -

3. delete#

gnmic -a <ip:port> --insecure set --delete /configure/router[router-name=Base]/interface[interface-name=interface1]