NAME¶
Net::CLI::Interact::Manual::Tutorial - Guide for new users
Introduction¶
Automating command line interface (CLI) interactions is not a new idea, but can
be tricky to implement. Net::CLI::Interact aims to provide a simple and
manageable interface to CLI interactions, supporting:
- •
- SSH, Telnet and Serial-Line connections
- •
- Unix and Windows support
- •
- Reusable device command phrasebooks
The module exists to support developers of applications and libraries which must
interact with a command line interface. The SYNOPSIS section of
Net::CLI::Interact has an overview of the commands demonstrated in this
document.
Getting Started¶
Like many other Perl modules, you need to load the library and then create a new
Net::CLI::Interact instance (which is $s in the example, below):
use Net::CLI::Interact;
my $s = Net::CLI::Interact->new({
transport => 'Serial',
personality => 'cisco',
});
Your application can have multiple independent instances (that is, connect to
different devices at the same time); simply repeat the above example more
times for variables other than $s.
Note that at the time you create the instance, as in the example above, the
library
does not connect to the device. That comes later.
There were two options provided to the "new" call, above, both of
which are required for all new instances. Let's look at them in turn:
- transport
- How do you want to connect to your CLI? The current choices
are Telnet, SSH and a Serial line (that is, a console cable). In this
option you need to tell the library which underlying transport is to be
used.
Some of the transports have additional options that are either required, or
optional. For example, the Telnet and SSH transports both need to know
which post name or IP address should be contacted. You pass this in
another option to "new", like so:
my $s = Net::CLI::Interact->new({
transport => 'Telnet',
connect_options => { host => 'my.server.example.com' },
personality => 'cisco',
});
See the manual page of the transport module for the option details.
- personality
- What language does the connected device speak? For instance
one common format is Cisco's IOS, which is widely cloned on other vendor
equipment CLIs. In this option you need to pass the name of a personality
that's used to load a Phrasebook.
A phrasebook is simply a library, or dictionary, of pre-configured phrases
you can use on the CLI. This makes life simple, because Net::CLI::Interact
then can automate some of the more difficult tasks. For example, if you
issue a command and the output is "paged" so you hit Space or
Return to see the next page, the phrasebook can tell Net::CLI::Interact
how to slurp all these pages into one body of output before returning it
to you.
See the Phrasebook user guide for a list of the possible values for the
"personality" option.
Connecting¶
This is done automatically for you the first time you send a command to the
device, so skip this step and move on!
Sending Commands¶
But first, Prompts¶
The idea of sending a command is, usually, to see some output. The most
important part of this process is knowing when the output has all been sent,
otherwise the library would sit forever, waiting to gather more text!
Between each command sent, the connected device prints a CLI
Prompt. This
prompt is where you type commands, and it's what tells us that all the output
has been sent from our last command. Prompts are loaded in the phrasebook, and
given friendly names.
If your personality's phrasebook is sufficiently mature, then the prompts might
be fully automated, and just like the Connecting step above, you can skip
doing anything manually. Consult the Phrasebook user guide for details.
However if you need to set it manually, do the following:
$s->set_prompt('friendly_name');
Sometimes you might not know what state the CLI is in; typically this applies to
Serial lines. In that case you can ask to find the matching prompt:
$s->find_prompt('wake_up');
The option "wake_up" asks to "hit the Return key", to make
the device spit out its prompt. That is only done if needed, and you can
remove "wake_up" to skip this step.
Literal Commands¶
There's not a lot to it. Remember that with a mature personality loaded, you
were probably able to skip the previous prompt step and go straight to:
my $output = $s->cmd('show ip interfaces brief');
Here you will get all the output from the command together in one variable,
$output. If you prefer an array where each item is one line of output, simply
use @output instead in the above example.
Macros¶
Life gets more complicated when your command has things like confirmation steps
(e.g. reboot), other prompts (e.g. extended ping), etc. For these situations
we have
Macros in the phrasebook.
A macro is simply a sequence of commands we could issue using
"$s->cmd()", bundled together and given a friendly name. Macros
are also smart enough either to handle simple confirmation steps themselves,
or to allow you to pass in parameters. Some examples probably help:
# saves config, accepting the default "startup-config" when prompted
$s->macro('write_mem');
# logs in, passing a username and password at the prompts
$s->macro('to_user_exec', {
params => ['my_username', 'my_password'],
});
# simply a parameterized command
$s->macro('show_interfaces_x', {
params => ['GigabitEthernet 3/4'],
});
Slurping Output¶
As mentioned above, output at the CLI is often "paged" with the user
hitting Space or Return to show the next page. Most macros can deal with this
automatically if well implemented.
If the Phrasebook user guide says your personality has a named default
Continuation for handling paged output, then set it like so:
$s->set_default_continuation('friendly_name');
Disconnecting¶
This is nothing more fancy than issuing the appropriate CLI commands to close
the network connection. In the case of the Serial line transport you can
usually only log out, and not fully disconnect. Simply end your application
and the library will tidy things up as best it can.