Nokia Linux Quick Start Guide

CLI PLUG-IN GUIDE Release 20.6

Nokia Service Router Linux

CLI PLUG-IN GUIDE

Release 20.6

3HE 16119 AAAA TQZZA

Edition: 1

July 2020

Nokia — Proprietary and confidential.

Use pursuant to applicable agreements.

CLI PLUG-IN GUIDE

Release 20.6

Nokia is a registered trademark of Nokia Corporation. Other products and company names mentioned herein may be trademarks or tradenames of their respective owners.

The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a worldwide basis.

The information presented is subject to change without notice. No responsibility is assumed for inaccuracies contained herein.

© 2020 Nokia.

Contains proprietary/trade secret information which is the property of Nokia and must not be made available to, or copied or used by anyone outside Nokia without its written authorization. Not to be used or disclosed except in accordance with applicable agreements.

2

3HE 16119 AAAA TQZZA

Edition: 1

CLI PLUG-IN GUIDE

Release 20.6

Table of contents
1	Getting started ................................................................................	5
1.1	About this document....................................................................................	5
1.2	Summary of changes...................................................................................	5
1.3	Precautionary messages.............................................................................	5
1.4	Conventions.................................................................................................	6
2	Show routines.................................................................................	7
2.1	Create a show routine .................................................................................	7
2.1.1	Step 1: Build the SchemaNode ..................................................................	8
2.1.2	Step 2: Retrieve the state from the management server.............................	9
2.1.3	Step 3: Populate a data object ..................................................................	10
2.1.4	Step 4: Add formatter instances ................................................................	10
2.1.5	Step 5: Implement the callback method ....................................................	11
2.1.6	Show routine code example ......................................................................	11
2.1.7	Step 6: Use streaming to optimize reports ................................................	12
3	Managing CLI plug-ins .................................................................	15
3.1	Install a CLI plug-in....................................................................................	15
3.2	Modify a CLI plug-in...................................................................................	15
3.3	Remove a CLI plug-in................................................................................	16
4	Classes and utility functions .......................................................	17
4.1	Formatters ................................................................................................	17
4.1.1	ColumnFormatter.......................................................................................	18
4.1.2	TagValueFormatter....................................................................................	20
4.1.3	TagValueWithKeyLineFormatter ...............................................................	20
4.1.4	Indent.........................................................................................................	21
4.1.5	Border........................................................................................................	21
4.1.6	Header.......................................................................................................	22
4.1.7	Footer ........................................................................................................	23
4.1.8	Whiteline ...................................................................................................	23
4.1.9	FilteredFormatter.......................................................................................	24
4.2	Format utilities ..........................................................................................	25
4.2.1	ColumnPrinter............................................................................................	25
4.2.2	TagValuePrinter.........................................................................................	27
4.2.3	TagValueWithKeyLinePrinter ....................................................................	27
4.2.4	print_line....................................................................................................	28
4.2.5	print_double_line .......................................................................................	28
4.2.6	indent ........................................................................................................	29
4.2.7	format_value..............................................................................................	29
4.3	Data...........................................................................................................	29
4.4	DataChildrenOfType..................................................................................	33
4.5	SchemaNode.............................................................................................	35

Edition: 1

3HE 16119 AAAA TQZZA

3

CLI PLUG-IN GUIDE

Release 20.6

4

3HE 16119 AAAA TQZZA

Edition: 1

CLI PLUG-IN GUIDE	Getting started
Release 20.6

1 Getting started

This chapter provides an overview of this document, includes summaries of changes from previous releases, and lists precautionary messages and command conventions.

1.1About this document

The Nokia Service Router Linux (SR Linux) CLI is a python-based application that can load dynamic plug-ins. Plug-ins are custom show commands that you can create and run from the SR Linux CLI. This document describes how to create custom CLI plug-ins, and defines the classes and utility functions used to create them. It also defines how to install, modify, and remove a CLI plug-in.

This document is intended for network technicians, administrators, operators, service providers, and others who need to create and install custom show commands.

1.2Summary of changes

There are no changes since the last release.

1.3Precautionary messages

Observe all dangers, warnings, and cautions in this document to avoid injury or equipment damage during installation and maintenance. Follow the safety procedures and guidelines when working with and near electrical equipment.

Table 1 describes information symbols contained in this document.

Edition: 1

3HE 16119 AAAA TQZZA

5

Getting started	CLI PLUG-IN GUIDE
	Release 20.6

Table 1	Information symbols
Symbol		Meaning	Description
		Danger	Warns that incorrect handling and installation could result in bodily injury.
			An electric shock hazard could exist. Before beginning work on this
			equipment, be aware of hazards involving electrical circuitry, be familiar
			with networking environments, and implement accident prevention
			procedures.
		Warning	Warns that incorrect handling and installation could result in equipment
			damage or loss of data.
		Caution	Warns that incorrect handling may reduce component or system
			performance.
		Note	Notes contain suggestions or additional operational information.

1.4Conventions

Nokia SR Linux documentation uses the following command conventions.

•Bold type indicates a command that the user must enter.

•Input and output examples are displayed in Courier text.

•An open right angle bracket indicates a progression of menu choices or simple command sequence (often selected from a user interface). Example: start > connect to

•Angle brackets (< >) indicate an item that is not used verbatim. For example, for the command show ethernet <name>, name should be replaced with the name of the interface.

•A vertical bar (|) indicates a mutually exclusive argument.

•Square brackets ([ ]) indicate optional elements.

•Braces ({ }) indicate a required choice. When braces are contained within square brackets, they indicate a required choice within an optional element.

•Italic type indicates a variable.

Generic IP addresses are used in examples. Replace these with the appropriate IP addresses used in the system.

6

3HE 16119 AAAA TQZZA

Edition: 1

CLI PLUG-IN GUIDE	Show routines
Release 20.6

2 Show routines

This chapter provides a tutorial on how to create a routine, or set of instructions, that results in a custom show command. It also provides a detailed description of all the classes and utility functions used to create custom show commands.

Before creating a show routine, the following is recommended:

•Whenever you receive Data from the server, print it using: print(str(data))

This makes it easier to visualize the data hierarchy.

•While building the SchemaNode and populating the Data structure, do not focus on the layout of your show routine. Instead, use the output of the following:

show <your-routine> | as json

This JSON output contains all the information currently in your show routine, in the correct hierarchy. Once the JSON output looks correct, then plan how to format it.

2.1Create a show routine

To create a show routine, you perform the following high-level steps:

Step 1. Build a SchemaNode to describe the data’s data model the show routine will construct.

Step 2. Retrieve the state from the management server using state.server_data_store.get_data(<path>)

Step 3. Populate a Data object with all the data (keys/fields/…) of the show routine. Step 4. Add Formatter instances to determine how the data will be formatted.

Step 5. Implement the callback method to pass the Data structure to the output.print_data command.

Step 6. Use streaming to optimize reports when working with large amounts of data.

Edition: 1

3HE 16119 AAAA TQZZA

7

Show routines	CLI PLUG-IN GUIDE
	Release 20.6

The following is an output example once all steps are completed. As you perform the steps in this section, you will be able to see how this example is built.

======================================

name : interface-1 description: The first interface admin-state: enable

--------------------------------------

Child-Id Is-Cool

=================

24	no
42	yes

======================================

name : interface-2 description: The second interface admin-state: disable

--------------------------------------

Child-Id Is-Cool

=================

1337 yes

======================================

2.1.1Step 1: Build the SchemaNode

Schema nodes describe a data model. Similar to the output of the tree command or the content of a YANG file, they indicate what lists, containers, keys, fields, and leaflists can be created.

To build a SchemaNode, start with a FixedSchemaRoot()

then add your top-level list/container using FixedSchemaNode.add_child() as shown in the SchemaNode reference.

For example:

from srlinux.schema import FixedSchemaRoot

def _get_my_schema(self): root = FixedSchemaRoot()

interface = root.add_child( 'interface', key='name',

fields=['description', 'admin-state']

)

child = interface.add_child( 'child',

key='Child-Id', fields=['Is-Cool']

)

The code above generates a data model for the following YANG model:

8

3HE 16119 AAAA TQZZA

Edition: 1

CLI PLUG-IN GUIDE	Show routines
Release 20.6
	list interface {
	key "name";
	leaf "description";
	leaf "admin-state";
	list child {
	key "Child-Id";
	leaf "Is-Cool";
	}
	}
	Ensure that the filter auto-completes all fields by passing the schema node into the
	add_command call when you install the plug-in. This ensures that the filter operator
	(|) can auto-complete all fields. For example:
	class Plugin(CliPlugin):
	'''
	Adds a fancy show report.
	'''
	def load(self, cli, **_kwargs):

cli.show_mode.add_command( Syntax('report').add_unnamed_argument('name'), update_location=False,

callback=self._print, schema=self._get_my_schema(),

)

2.1.2Step 2: Retrieve the state from the management server

To retrieve the state, use build_path() to populate a path of the key you need to retrieve, and call get_data.

This returns a Data object pointing to the root of the data returned by the management server:

from srlinux.location import build_path

def _fetch_state(self, state, arguments):

path = build_path('/interface[name={name}]/ subinterface[index=*]', name=arguments.get('name'))

return state.server_data_store.get_data(path, recursive=True)

Edition: 1

3HE 16119 AAAA TQZZA

9

Show routines	CLI PLUG-IN GUIDE
	Release 20.6

2.1.3Step 3: Populate a data object

With the data from the management server and a data model, populate the Data object:

from srlinux.data import Data from srlinux import strings

def _populate_data(self, server_data): result = Data(self._get_my_schema())

for interface in server_data.interface.items(): data = result.interface.create(interface.name) data.description = interface.description data.admin_state = interface.admin_state

self._add_children(data, interface.subinterface)

return result
def _add_children(self,	data, server_data):
# server_data is an	instance of DataChildrenOfType
for subinterface in	server_data.items():
child = data.child.create(subinterface.index)
cool_ids = [42,	1337]
is_cool = subinterface.index in cool_ids
child.is_cool =	strings.bool_to_yes_no(is_cool)

2.1.4Step 4: Add formatter instances

To format the output, assign Formatter instances to the different Data objects. The type of Formatter determines whether the output is formatted using key: value pairs, as a grid-based table, or using a custom format.

from srlinux.data import Border, ColumnFormatter, Data, TagValueFormatter, Borders, Indent

def _set_formatters(self, data): data.set_formatter(

'/interface',

Border(TagValueFormatter(), Border.Above | Border.Below | Border.Between, '='))

data.set_formatter( '/interface/child',

Indent(ColumnFormatter(ancestor_keys=False, borders=Borders.Header), indenta

tion=2))

A list of all the built-in formatters is in the Formatters section.

10

3HE 16119 AAAA TQZZA

Edition: 1

CLI PLUG-IN GUIDE	Show routines
Release 20.6

2.1.5Step 5: Implement the callback method

The following example shows how to implement the callback method which can then be invoked to complete the routine:

def _print(self, state, arguments, output, **_kwargs): server_data = self._fetch_state(state, arguments) result = self._populate_data(server_data) self._set_formatters(result) output.print_data(result)

2.1.6Show routine code example

Once you have completed Steps 1 - 5 (in sections 2.1.1 - 2.1.5), the show routine first shown in section 2.1 Create a show routine is now complete.

The following is an example of the complete show routine code:

from srlinux import strings

from srlinux.data import Border, ColumnFormatter, TagValueFormatter, Borders, Data, Indent

from srlinux.location import build_path from srlinux.mgmt.cli import CliPlugin from srlinux.schema import FixedSchemaRoot from srlinux.syntax import Syntax

class Plugin(CliPlugin):

def load(self, cli, **_kwargs): cli.show_mode.add_command(

Syntax('report').add_unnamed_argument('name'), update_location=False,

callback=self._print, schema=self._get_my_schema(),

)

def _print(self, state, arguments, output, **_kwargs): server_data = self._fetch_state(state, arguments) result = self._populate_data(server_data) self._set_formatters(result) output.print_data(result)

def _get_my_schema(self): root = FixedSchemaRoot()

interface = root.add_child( 'interface', key='name',

fields=['description', 'admin-state']

)

child = interface.add_child( 'child', key='Child-Id', fields=['Is-Cool']

Edition: 1

3HE 16119 AAAA TQZZA

11

Show routines	CLI PLUG-IN GUIDE
	Release 20.6
	)
	return root
	def _fetch_state(self, state, arguments):
	path = build_path('/interface[name={name}]/
	subinterface[index=*]', name=arguments.get('name'))

return state.server_data_store.get_data(path, recursive=True) def _populate_data(self, server_data):

result = Data(self._get_my_schema())

for interface in server_data.interface.items(): data = result.interface.create(interface.name) data.description = interface.description data.admin_state = interface.admin_state

self._add_children(data, interface.subinterface)

return result

def _add_children(self, data, server_data):

# server_data is an instance of DataChildrenOfType

for subinterface in server_data.items():

child = data.child.create(subinterface.index)

cool_ids = [42, 1337]

is_cool = subinterface.index in cool_ids child.is_cool = strings.bool_to_yes_no(is_cool)

def _set_formatters(self, data): data.set_formatter(

'/interface',

Border(TagValueFormatter(), Border.Above | Border.Below | Border.Between

, '='))

data.set_formatter( '/interface/child',

Indent(ColumnFormatter(ancestor_keys=False, borders=Borders.Header), ind

entation=2))

2.1.7Step 6: Use streaming to optimize reports

The previous steps detail how to obtain data, and then separately print a report. With streaming, data is retrieved and begins printing immediately. This is useful for reports that have large amounts of data (for example, route tables) because printing begins immediately instead of waiting for the entire data collection to complete.

Perform the following to implement streaming:

1.Enter state.server_data_store.stream_data(<path>) instead of state.server_data_store.get_data(<path>) to retrieve server data

12

3HE 16119 AAAA TQZZA

Edition: 1