Using the 'gnmic' Command (with Examples)

gnmic is a command-line client for the gNMI (gRPC Network Management Interface) protocol, which allows users to manage network device configurations and view operational data in a streamlined manner. This tool is essential for network administrators and engineers looking to efficiently interact with network devices over a gNMI interface. Below, we explore various use cases for gnmic, showcasing different functionalities that it offers.

Use Case 1: Request Device Capabilities

Code:

gnmic --address ip:port capabilities

Motivation:

Understanding the capabilities of a network device is fundamental for network management. This command allows a user to gain insight into what a network device can support, such as its supported models, versions, and available paths. Before performing any configuration or state retrieval tasks, knowing the device’s capabilities ensures compatibility and provides a clearer picture of its functionalities.

Explanation:

• gnmic: This is the command-line tool for interfacing with gNMI-compatible devices.
• --address ip:port: This specifies the IP address and port number where the network device is listening for gNMI requests. It points gnmic to the correct device to interrogate for capabilities.
• capabilities: This is the specific gNMI operation being requested. It asks the device to return a list of its supported capabilities and models.

Example Output:

{
  "supported_models": ["openconfig-interfaces", "openconfig-acl"],
  "supported_encodings": ["JSON", "PROTO"],
  "gNMI_version": "0.7.0"
}

Use Case 2: Provide a Username and Password to Fetch Device Capabilities

Code:

gnmic --address ip:port --username username --password password capabilities

Motivation:

Some network devices require authentication to allow access to their capabilities. This command is used when the network device is secured with a username and password, ensuring that only authorized users can request and view its capabilities. Sensitive operations over the network need to be protected from unauthorized access, making authentication essential.

Explanation:

• --address ip:port: As before, this specifies the target device.
• --username username: Specifies the username required for authentication to the device.
• --password password: This argument provides the corresponding password for the specified username.
• capabilities: Again, this requests a list of capabilities from the device.

Example Output:

{
  "supported_models": ["openconfig-interfaces", "openconfig-acl"],
  "supported_encodings": ["JSON", "PROTO"],
  "gNMI_version": "0.7.0"
}

Use Case 3: Get a Snapshot of the Device State at a Specific Path

Code:

gnmic -a ip:port get --path path

Motivation:

Retrieving the current state of a network device at a specific path is vital for monitoring and diagnostics. This use case addresses the need to view particular configurations or operational data without making changes to the device. It helps in analyzing the current setup and performance metrics of the network device.

Explanation:

• -a ip:port: This is a shorthand version of --address, denoting the device’s IP and port.
• get: This command signifies that we want to retrieve information from the device.
• --path path: This specific path identifies which part of the device’s state we are interested in retrieving. It can refer to interfaces, routing information, or other relevant data nodes.

Example Output:

{
  "interfaces": {
    "interface": [
      {
        "name": "ethernet-1/1",
        "oper-status": "UP"
      }
    ]
  }
}

Use Case 4: Update Device State at a Specific Path

Code:

gnmic -a ip:port set --update-path path --update-value value

Motivation:

Being able to update the configuration of a network device is a core task for network administrators. This use case allows for modifying the device’s operational data or configurations to align with desired network policies or to resolve issues. Updating device states effectively allows for automation and implementing network-wide changes efficiently.

Explanation:

• -a ip:port: Again, specifies the device’s network address and port for communication.
• set: This command indicates that a change or update will be made to the device.
• --update-path path: Specifies the path within the device’s schema where the update will occur.
• --update-value value: This represents the new value that will be assigned to the specified path, updating the device’s state or configuration accordingly.

Example Output:

Update successful: Path '/interfaces/interface[name=ethernet-1/1]/enabled' set to 'false'

Use Case 5: Subscribe to Target State Updates Under the Subtree at a Specific Path

Code:

gnmic -a ip:port subscribe --path path

Motivation:

Subscribing to real-time updates from a network device is crucial for maintaining a responsive and aware network management system. This command allows users to receive notifications on changes or events occurring under a specific subtree, facilitating proactive management and monitoring.

Explanation:

• -a ip:port: Continues to be the specification for the network device’s address and port.
• subscribe: This keyword indicates that the user wishes to establish a subscription to receive updates automatically.
• --path path: This defines the subtree within the device from which updates will be reported. Monitoring specific paths means receiving only relevant updates, minimizing unnecessary data flow.

Example Output:

Subscription started: Monitoring path '/interfaces/interface'
Notification received: Interface 'ethernet-1/1' status changed to 'DOWN'

Conclusion:

gnmic is a powerful tool for network professionals, providing a comprehensive set of functions to interact with and manage network devices using the gNMI protocol. The commands explored here demonstrate the versatility of gnmic in handling various tasks from retrieving capabilities and monitoring state, to dynamic updates and real-time subscriptions. Understanding and utilizing these commands can greatly enhance the efficiency and effectiveness of network management practices.