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 module 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 module 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 module 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? In this option you need to pass the name of a personality that's used to load a Phrasebook. For instance one common format is Cisco's IOS, which is widely cloned on other vendor equipment CLIs.

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.

This module ships with many phrasebooks which have been contributed by other users over the years. You can also write and use your own phrasebooks, which might replace, or add to, those shipped with the module. See the Phrasebook user guide for a list of phrasebooks shipped with this distribution, and their corresponding "personality" names. See also the "add_library" option to "new()" for specifying a path to your own phrasebooks.

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

 $s->set_prompt('friendly_name');

 $s->find_prompt($wake_up);

 my $output = $s->cmd('show ip interfaces brief');

 # 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 module will tidy things up as best it can.