1Net::CLI::Interact::ManUusaelr::CTounttorriibault(e3d)PNeertl::DCoLcIu:m:eInnttaetriaocnt::Manual::Tutorial(3)
2
6 Net::CLI::Interact::Manual::Tutorial - Guide for new users
7
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 • SSH, Telnet and Serial-Line connections
14 • Unix and Windows support
16 • Reusable device command phrasebooks
18 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
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 use Net::CLI::Interact;
30 my $s = Net::CLI::Interact->new({
32 transport => 'Serial',
33 personality => 'cisco',
34 });
35 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 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 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 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 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 my $s = Net::CLI::Interact->new({
58 transport => 'Telnet',
59 connect_options => { host => 'my.server.example.com' },
60 personality => 'cisco',
62 });
63 See the manual page of the transport module for the option details.
65 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 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 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
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
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 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 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 However if you need to set it manually, do the following:
110 $s->set_prompt('friendly_name');
112 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 $s->find_prompt($wake_up);
118 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 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 my $output = $s->cmd('show ip interfaces brief');
132 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 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 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 # saves config, accepting the default "startup-config" when prompted
149 $s->macro('write_mem');
150 # logs in, passing a username and password at the prompts
152 $s->macro('to_user_exec', {
153 params => ['my_username', 'my_password'],
154 });
155 # simply a parameterized command
157 $s->macro('show_interfaces_x', {
158 params => ['GigabitEthernet 3/4'],
159 });
160
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 If the Phrasebook user guide says your personality has a named default
167 Continuation for handling paged output, then set it like so:
168 $s->set_default_continuation('friendly_name');
170
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.
176perl v5.36.0 2023-0N1e-t2:0:CLI::Interact::Manual::Tutorial(3)