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
Release 20.6
1 Getting started
1.1 About this document
Getting started
This chapter provides an overview of this document, includes summaries of changes
from previous releases, and lists precautionary messages and command
conventions.
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.2 Summary of changes
There are no changes since the last release.
1.3 Precautionary 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
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.
CLI PLUG-IN GUIDE
Release 20.6
1.4 Conventions
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
Release 20.6
2 Show routines
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.1 Create 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.1 Step 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
Release 20.6
Show routines
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.2 Step 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.3 Step 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.4 Step 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',
tion=2))
Indent(ColumnFormatter(ancestor_keys=False, borders=Borders.Header), indenta
10
A list of all the built-in formatters is in the Formatters section.
3HE 16119 AAAA TQZZA Edition: 1
CLI PLUG-IN GUIDE
Release 20.6
2.1.5 Step 5: Implement the callback method
2.1.6 Show routine code example
Show routines
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)
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
, '='))
entation=2))
data.set_formatter(
'/interface/child',
Indent(ColumnFormatter(ancestor_keys=False, borders=Borders.Header), ind
2.1.7 Step 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
Loading...