1Net::CLI::Interact::ManUusaelr::CTounttorriibault(e3d)PNeertl::DCoLcIu:m:eInnttaetriaocnt::Manual::Tutorial(3)
2
3
4

NAME

6       Net::CLI::Interact::Manual::Tutorial - Guide for new users
7

Introduction

9       Automating command line interface (CLI) interactions is not a new idea,
10       but can be tricky to implement. Net::CLI::Interact aims to provide a
11       simple and manageable interface to CLI interactions, supporting:
12
13       •   SSH, Telnet and Serial-Line connections
14
15       •   Unix and Windows support
16
17       •   Reusable device command phrasebooks
18
19       The module exists to support developers of applications and libraries
20       which must interact with a command line interface. The SYNOPSIS section
21       of Net::CLI::Interact has an overview of the commands demonstrated in
22       this document.
23

Getting Started

25       Like many other Perl modules, you need to load the module and then
26       create a new Net::CLI::Interact instance (which is $s in the example,
27       below):
28
29        use Net::CLI::Interact;
30
31        my $s = Net::CLI::Interact->new({
32            transport   => 'Serial',
33            personality => 'cisco',
34        });
35
36       Your application can have multiple independent instances (that is,
37       connect to different devices at the same time); simply repeat the above
38       example more times for variables other than $s.
39
40       Note that at the time you create the instance, as in the example above,
41       the module does not connect to the device. That comes later.
42
43       There were two options provided to the "new" call, above, both of which
44       are required for all new instances. Let's look at them in turn:
45
46       transport
47           How do you want to connect to your CLI? The current choices are
48           Telnet, SSH and a Serial line (that is, a console cable). In this
49           option you need to tell the module which underlying transport is to
50           be used.
51
52           Some of the transports have additional options that are either
53           required, or optional. For example, the Telnet and SSH transports
54           both need to know which post name or IP address should be
55           contacted. You pass this in another option to "new", like so:
56
57            my $s = Net::CLI::Interact->new({
58                transport       => 'Telnet',
59                connect_options => { host => 'my.server.example.com' },
60
61                personality     => 'cisco',
62            });
63
64           See the manual page of the transport module for the option details.
65
66       personality
67           What language does the connected device speak?  In this option you
68           need to pass the name of a personality that's used to load a
69           Phrasebook.  For instance one common format is Cisco's IOS, which
70           is widely cloned on other vendor equipment CLIs.
71
72           A phrasebook is simply a library, or dictionary, of pre-configured
73           phrases you can use on the CLI. This makes life simple, because
74           Net::CLI::Interact then can automate some of the more difficult
75           tasks. For example, if you issue a command and the output is
76           "paged" so you hit Space or Return to see the next page, the
77           phrasebook can tell Net::CLI::Interact how to slurp all these pages
78           into one body of output before returning it to you.
79
80           This module ships with many phrasebooks which have been contributed
81           by other users over the years. You can also write and use your own
82           phrasebooks, which might replace, or add to, those shipped with the
83           module. See the Phrasebook user guide for a list of phrasebooks
84           shipped with this distribution, and their corresponding
85           "personality" names. See also the "add_library" option to new() for
86           specifying a path to your own phrasebooks.
87

Connecting

89       This is done automatically for you the first time you send a command to
90       the device, so skip this step and move on!
91

Sending Commands

93   But first, Prompts
94       The idea of sending a command is, usually, to see some output. The most
95       important part of this process is knowing when the output has all been
96       sent, otherwise the module would sit forever, waiting to gather more
97       text!
98
99       Between each command sent, the connected device prints a CLI Prompt.
100       This prompt is where you type commands, and it's what tells us that all
101       the output has been sent from our last command. Prompts are loaded in
102       the phrasebook, and given friendly names.
103
104       If your personality's phrasebook is sufficiently mature, then the
105       prompts might be fully automated, and just like the Connecting step
106       above, you can skip doing anything manually. Consult the Phrasebook
107       user guide for details.
108
109       However if you need to set it manually, do the following:
110
111        $s->set_prompt('friendly_name');
112
113       Sometimes you might not know what state the CLI is in; typically this
114       applies to Serial lines. In that case you can ask to find the matching
115       prompt:
116
117        $s->find_prompt($wake_up);
118
119       This method gets some output from the connected session and then tries
120       to match it against any loaded prompts, returning if successful. If not
121       successful, and the $wake_up value is non-zero, then "find_prompt" will
122       "hit the return key" to try to get some output. This process is retried
123       according to the value of $wake_up (i.e. 1, 2, 3, etc), and of not
124       successful will die.
125
126   Literal Commands
127       There's not a lot to it. Remember that with a mature personality
128       loaded, you were probably able to skip the previous prompt step and go
129       straight to:
130
131        my $output = $s->cmd('show ip interfaces brief');
132
133       Here you will get all the output from the command together in one
134       variable, $output. If you prefer an array where each item is one line
135       of output, simply use @output instead in the above example.
136
137   Macros
138       Life gets more complicated when your command has things like
139       confirmation steps (e.g. reboot), other prompts (e.g. extended ping),
140       etc. For these situations we have Macros in the phrasebook.
141
142       A macro is simply a sequence of commands we could issue using
143       "$s->cmd()", bundled together and given a friendly name. Macros are
144       also smart enough either to handle simple confirmation steps
145       themselves, or to allow you to pass in parameters. Some examples
146       probably help:
147
148        # saves config, accepting the default "startup-config" when prompted
149        $s->macro('write_mem');
150
151        # logs in, passing a username and password at the prompts
152        $s->macro('to_user_exec', {
153            params => ['my_username', 'my_password'],
154        });
155
156        # simply a parameterized command
157        $s->macro('show_interfaces_x', {
158            params => ['GigabitEthernet 3/4'],
159        });
160

Slurping Output

162       As mentioned above, output at the CLI is often "paged" with the user
163       hitting Space or Return to show the next page. Most macros can deal
164       with this automatically if well implemented.
165
166       If the Phrasebook user guide says your personality has a named default
167       Continuation for handling paged output, then set it like so:
168
169        $s->set_default_continuation('friendly_name');
170

Disconnecting

172       This is nothing more fancy than issuing the appropriate CLI commands to
173       close the network connection. In the case of the Serial line transport
174       you can usually only log out, and not fully disconnect. Simply end your
175       application and the module will tidy things up as best it can.
176
177
178
179perl v5.36.0                      2023-0N1e-t2:0:CLI::Interact::Manual::Tutorial(3)
Impressum