Net::Appliance::Session->new( \%options )

 my $s = Net::Appliance::Session->new({
     personality => 'ios',
     transport => 'SSH',
     host => 'hostname.example',
 });

Prepares a new session for you, but will not connect to any device. Some options are required, others optional:

"personality => $name" (required)

Tells the module which "language" to use when talking to the connected device, for example "ios" for Cisco IOS devices. There's a list of all the supported platforms in the Phrasebook documentation. It's also possible to write new phrasebooks.

"transport => $backend" (required)

The name of the transport backend used for the session, which may be one of Telnet, SSH, or Serial.

"app => $location" (required on Windows)

On Windows platforms, you must download the "plink.exe" program, and pass its location in this parameter.

"host => $hostname" (required for Telnet and SSH transports)

When using the Telnet and SSH transports, you must provide the IP or host name of the target device in this parameter.

"timeout => $seconds"

Configures a global default timeout value, in seconds, for interaction with the remote device. The default is 10 seconds. You can also set timeout on a per-command or per-macro call (see below).

"connect_options => \%options"

Some of the transport backends can take their own options. For example with a serial line connection you might specify the port speed, etc. See the respective manual pages for each transport backend for further details (SSH, Telnet, Serial).

"add_library => $directory | \@directories"

If you've added to the built-in phrasebook with your own macros, then use this option to load your new phrasebook file(s). The path here should be the directory within which all your personalities are located, such as:

 ${directory}/cisco/ios/pb
 ${directory}/other/device/pb
    

Usually the phrasebook files are called ""pb"" and to the "personality" option you pass the containing directory name, for example "ios" or "device" in the examples shown. See Net::CLI::Interact::Manual::Tutorial for further details.

"nci_options => \%options"

Should you wish to reconfigure the Net::CLI::Interact instance used inside of "Net::Appliance::Session", perhaps for an option not supported above, this generic setting is available.

connect( \%options )

 $s->connect({ username => $myname, password => $mysecret });

To establish a connection to the device, and possibly also log in, call this method. Following a successful connection, paging of device output will be disabled using commands appropriate to the platform. This feature can be suppressed (see "CONFIGURATION", below).

Options available to this method, sometimes required, are:

"username => $name"

The login username for the device. Whether this is required depends both on how the device is configured, and how you have configured this module to act. If it looks like the device presented a Username prompt. and you don't pass the username a Perl exception will be thrown.

The username is cached within the module for possible use later on when entering "privileged" mode.

"password => $secret"

The login password for the device. Whether this is required depends both on how the device is configured, and how you have configured this module to act. If it looks like the device presented a Username prompt. and you don't pass the username a Perl exception will be thrown.

The password is cached within the module for possible use later on when entering "privileged" mode.

"privileged_password => $secret" (optional)

In the situation where you've activated "privileged paging", yet your device uses a different password for privileged mode than login, you'll need to set that other password here.

Otherwise, because the module tries to disable paging, it first goes into privileged mode as you instructed, and fails with the wrong (login) password.

begin_privileged and end_privileged

 $s->begin_privileged;
 # do some work
 $s->end_privileged;

Once you have connected to the device, change to "privileged" mode by calling the "begin_privileged" method. The appropriate command will be issued for your device platform, from the phrasebook. Likewise to exit "privileged" mode call the "end_privileged" method.

Sometimes authentication is required to enter "privileged" mode. In that case, the module defaults to using the username and password first passed in the "connect" method. However to either override those or set them in case they were not passed to "connect", use either or both of the following options to "begin_privileged":

 $s->begin_privileged({ username => $myname, password => $mysecret });

begin_configure and end_configure

 $s->begin_configure;
 # make some changes
 $s->end_configure;

To enter "configuration" mode for your device platform, call the "begin_configure" method. This checks you are already in "privileged" mode, as the module assumes this is necessary. If it isn't necessary then see "CONFIGURATION" below to modify this behaviour. Likewise to exit "configure" mode, call the "end_configure" method.

cmd( $command )

 my $config     = $s->cmd('show running-config');
 my @interfaces = $s->cmd('show interfaces brief');

Execute a single command statement on the connected device. The statement is executed verbatim on the device, with a newline appended.

In scalar context the response is returned as a single string. In list context the gathered response is returned as a list of lines. In both cases your local platform's newline character will end all lines.

You can also call the "last_response" method which returns the same data with the same contextual behaviour.

This method accepts a hashref of options following the $command, which can include a "timeout" value to permit long running commands to have all their output gathered.

To handle more complicated interactions, for example commands which prompt for confirmation or optional parameters, you should use a Macro. These are set up in the phrasebook and issued via the "$s->macro($name)" method call. See the Phrasebook and Cookbook manual pages for further details.

If you receive response text with a "mangled" copy of the issued command at the start, then it's likely you need to set the terminal width. This prevents the connected device from line-wrapping long commands. Issue something like:

 $s->begin_privileged;
 $s->cmd('terminal width 510');

close

 $s->close;

Once you have finished work with the device, call this method. It attempts to back out of any "privileged" or "configuration" mode you've entered, re-enable paging (unless suppressed) and then disconnect.

If a macro named "disconnect" exists in the loaded phrasebook then it's called just before disconnection. This allows you to issue a command such as "exit" to cleanly log out.