.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::CLI::Interact::Manual::Tutorial 3pm"
.TH Net::CLI::Interact::Manual::Tutorial 3pm "2017-11-08" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::CLI::Interact::Manual::Tutorial \- Guide for new users
.SH "Introduction"
.IX Header "Introduction"
Automating command line interface (\s-1CLI\s0) interactions is not a new idea, but
can be tricky to implement. Net::CLI::Interact aims to provide a simple and
manageable interface to \s-1CLI\s0 interactions, supporting:
.IP "\(bu" 4
\&\s-1SSH,\s0 Telnet and Serial-Line connections
.IP "\(bu" 4
Unix and Windows support
.IP "\(bu" 4
Reusable device command phrasebooks
.PP
The module exists to support developers of applications and libraries which
must interact with a command line interface. The \s-1SYNOPSIS\s0 section of
Net::CLI::Interact has an overview of the commands demonstrated in this
document.
.SH "Getting Started"
.IX Header "Getting Started"
Like many other Perl modules, you need to load the module and then create a
new Net::CLI::Interact instance (which is \f(CW$s\fR in the example, below):
.PP
.Vb 1
\& use Net::CLI::Interact;
\& 
\& my $s = Net::CLI::Interact\->new({
\&     transport   => \*(AqSerial\*(Aq,
\&     personality => \*(Aqcisco\*(Aq,
\& });
.Ve
.PP
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 \f(CW$s\fR.
.PP
Note that at the time you create the instance, as in the example above, the
module \fIdoes not\fR connect to the device. That comes later.
.PP
There were two options provided to the \f(CW\*(C`new\*(C'\fR call, above, both of which are
required for all new instances. Let's look at them in turn:
.IP "transport" 4
.IX Item "transport"
How do you want to connect to your \s-1CLI\s0? The current choices are
Telnet,
\&\s-1SSH\s0 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.
.Sp
Some of the transports have additional options that are either required, or
optional. For example, the Telnet and \s-1SSH\s0 transports both need to know which
post name or \s-1IP\s0 address should be contacted. You pass this in another option
to \f(CW\*(C`new\*(C'\fR, like so:
.Sp
.Vb 3
\& my $s = Net::CLI::Interact\->new({
\&     transport       => \*(AqTelnet\*(Aq,
\&     connect_options => { host => \*(Aqmy.server.example.com\*(Aq },
\& 
\&     personality     => \*(Aqcisco\*(Aq,
\& });
.Ve
.Sp
See the manual page of the transport module for the option details.
.IP "personality" 4
.IX Item "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 \fIPhrasebook\fR.  For
instance one common format is Cisco's \s-1IOS,\s0 which is widely cloned on other
vendor equipment CLIs.
.Sp
A phrasebook is simply a library, or dictionary, of pre-configured phrases you
can use on the \s-1CLI.\s0 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 \*(L"paged\*(R" 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.
.Sp
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
\&\f(CW\*(C`personality\*(C'\fR names. See also the \f(CW\*(C`add_library\*(C'\fR option to \f(CW\*(C`new()\*(C'\fR for
specifying a path to your own phrasebooks.
.SH "Connecting"
.IX Header "Connecting"
This is done automatically for you the first time you send a command to the
device, so skip this step and move on!
.SH "Sending Commands"
.IX Header "Sending Commands"
.SS "But first, Prompts"
.IX Subsection "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 module would sit forever, waiting to gather more text!
.PP
Between each command sent, the connected device prints a \s-1CLI\s0 \fIPrompt\fR. 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.
.PP
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.
.PP
However if you need to set it manually, do the following:
.PP
.Vb 1
\& $s\->set_prompt(\*(Aqfriendly_name\*(Aq);
.Ve
.PP
Sometimes you might not know what state the \s-1CLI\s0 is in; typically this applies
to Serial lines. In that case you can ask to find the matching prompt:
.PP
.Vb 1
\& $s\->find_prompt($wake_up);
.Ve
.PP
This method gets some output from the connected session and then tries to
match it against any loaded prompts, returning if successful. If not
successful, and the \f(CW$wake_up\fR value is non-zero, then \f(CW\*(C`find_prompt\*(C'\fR will
\&\*(L"hit the return key\*(R" to try to get some output. This process is retried
according to the value of \f(CW$wake_up\fR (i.e. 1, 2, 3, etc), and of not
successful will die.
.SS "Literal Commands"
.IX Subsection "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:
.PP
.Vb 1
\& my $output = $s\->cmd(\*(Aqshow ip interfaces brief\*(Aq);
.Ve
.PP
Here you will get all the output from the command together in one variable,
\&\f(CW$output\fR. If you prefer an array where each item is one line of output,
simply use \f(CW@output\fR instead in the above example.
.SS "Macros"
.IX Subsection "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 \fIMacros\fR in the phrasebook.
.PP
A macro is simply a sequence of commands we could issue using \f(CW\*(C`$s\->cmd()\*(C'\fR, 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:
.PP
.Vb 2
\& # saves config, accepting the default "startup\-config" when prompted
\& $s\->macro(\*(Aqwrite_mem\*(Aq);
\& 
\& # logs in, passing a username and password at the prompts
\& $s\->macro(\*(Aqto_user_exec\*(Aq, {
\&     params => [\*(Aqmy_username\*(Aq, \*(Aqmy_password\*(Aq],
\& });
\& 
\& # simply a parameterized command
\& $s\->macro(\*(Aqshow_interfaces_x\*(Aq, {
\&     params => [\*(AqGigabitEthernet 3/4\*(Aq],
\& });
.Ve
.SH "Slurping Output"
.IX Header "Slurping Output"
As mentioned above, output at the \s-1CLI\s0 is often \*(L"paged\*(R" with the user hitting
Space or Return to show the next page. Most macros can deal with this
automatically if well implemented.
.PP
If the Phrasebook user guide says
your personality has a named default \fIContinuation\fR for handling paged
output, then set it like so:
.PP
.Vb 1
\& $s\->set_default_continuation(\*(Aqfriendly_name\*(Aq);
.Ve
.SH "Disconnecting"
.IX Header "Disconnecting"
This is nothing more fancy than issuing the appropriate \s-1CLI\s0 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.