TCLI – TextFSM Device CLI

Forked from https://github.com/google/tcli - as that repo is archived.

TCLI was a starter project at Google back in 2008. Although a powerful tool for network troubleshooting, and popular within Google for over a decade, it was accidental code lacking in software design. This fork may add little in the way of functionality, it does however slay a few of those dragons.

Overview

TCLI is a client interface for issuing commands to arbitrarily large numbers of devices (hundreds, thousands, even hundreds of thousands). TCLI is a frontend to TextFSM and adds a rich set of interactive functions and collates responses into various tabular display formats.

An essential tool for scaling network administration when device access is required via CLI. The cross section of devices to receive commands is controlled by matching on device names or other attributes. The commands are sent and received asyncronously and the outputs are collated into tables for a unified view.

Useful for real time analysis, interactive or exploratory troubleshooting, and creating holistic views of device state or configuration for the cross section of the fleet you are interested in.

Can be used against a live network, for real-time data, or against a repository of stored command outputs for offline use with near-realtime data.

See the TCLI Power Users Guide for how to make use of the interactive CLI functionality.

Type /help to get started. TCLI commands are prefixed with a forward slash /. All other commands are forwarded to the target device/s for remote execution.

Pipes are supported locally in the client with double piping || . e.g. show inter terse | grep ge || wc -l Sends 'show inter terse | grep ge' to the target devices and pipes the result through wc -l locally in the TCLI host.

Inline commands are supported with double slash //. e.g. show version //display csv //color on

Returns the output of the 'show version' in csv format, with color still on, regardless of what the global setting are. Global settings are not changed by inline commands.

Commands can be passed to the host shell with /! or /exec.

The file ~/.tclirc is executed at startup.

Interactive TCLI starts in 'safe mode' - toggle off with /S or /safemode.

Cautions and Caveats

Empowers users to run commands across potentially large sets of devices with very few restrictions – Exercise caution against 'overmatching' with your target and attribute filters and please use wisely and cautiously.

Does not support commands that are multi-part, or have non-discrete responses e.g. the ping command.

Note: You can use commands like ping count 5 127.0.0.1 or monitor traffic brief count 2 that do not require Ctrl + C to terminate.

Architecture

TCLI is the front end of the software stack and there are several additional components needed for a complete solution.

graph LR
    style TCLI fill:#eee,color:#333
    TCLI@{shape: rounded}
    A@{shape: manual-input, label: fa:fa-user User}
    B@{shape: cyl, label: "Device\nInventory"}
    C@{shape: proc, label: Authenticator}
    D@{shape: procs, label: Accessor}
    E@{label: TextFSM}
    F@{shape: docs, label: Templates}
    A <--> TCLI
    TCLI <--> B
    TCLI <--> C
    C <--> D
    TCLI <--> E
    E --- F

Loading

• TextFSM for formatting raw CLI output into structured tables

• NTC Templates for TextFSM to be able to structure output for specific commands and families of devices.

• Accessor: A service to send and receive commands to/from devices. Examples include:

  • Notch
  • Rancid
  • Salt
  • Scrapli
  • Netmiko

• Inventory: A database, DNS or CVS file of device names and attributes, or the data file from the accessor library above, such as router.db from RANCID.

• Authenticator: Authentication and authorisation policies for what commands can be sent to devices.

  An AAA policy might allow NOC personnel to use the CLI but then only permit 'show' commands so that changes cannot be made to the devices.

  This policy and its implementation will vary greatly between organisations and unfortunately you'll need to 'roll your own' here.

Getting Started

Although TCLI requires significant setup and basic Python familiarity. It can be run straight out of the box with fictitious devices and a limited set of commands with canned output:

• Devices:
  • device_a
  • device_b
  • device_c
• Commands:
  • show version
  • show vlan

To try TCLI, execute the main.py script in the parent directory.

python3 main.py

Once setup for your environment, the Power Users guide will get you up and running fast! - TCLI Power Users Guide

Setup

To use in your environment TCLI needs to be configured to retrieve a list of devices from whatever system is used to manage the site specific inventory. And integrated to call your device accessor system (or to scrape the output files that it produces).

Your site customisations are made to a new file that implements a child class of Inventory. This class is declared in inventory.py. So import, inherit, and override the methods _FetchDevices and SendRequests of the parent Inventory class in your file.

A "canned" example is included inventory_csv.py for illustration.

Your substitute module is imported by the command line flag 'inventory_file'. The module is expected to be located in the tcli directory.

Contributors are welcome to add various inventory_<accessor>.py files for popular open source device accessor methods.

The structured format for device output is enabled via TextFSM. You can create new templates to display output in CSV or other structured formats per the TextFSM Code Lab. Or use the open source template repository ntc-templates that provides a library of templates for many device types and common commands.