Net::A...Session(3pm)

💖 Net::Appliance::Session 💖

okay so bestie, this is the manual page for Net::Appliance::Session from the User Contributed Perl Documentation (that's the Net::A...Session(3pm) situation, iykyk). Buckle up, we're going into network appliances and it's gonna be cute 🎀

---

🌸 NAME 🌸

Net::Appliance::Session — Run command-line sessions to network appliances 💅

---

✨ SYNOPSIS ✨

use Net::Appliance::Session;

my $s = Net::Appliance::Session->new({
    personality => 'ios',
    transport => 'SSH',
    host => 'hostname.example',
    privileged_paging => 1, # only if using ASA/PIX OS 7+
                            # and there are other behaviour options, see below
});

try {
    $s->connect({ username => 'username', password => 'loginpass' });

    $s->begin_privileged({ password => 'privilegedpass' });
    print $s->cmd('show access-list');
    $s->end_privileged;
}
catch {
    warn "failed to execute command: $_";
}
finally {
    $s->close;
};

or, try the bundled nas helper script (beta feature!):

nas --help

---

🦋 DESCRIPTION 🦋

Use this module to set up an interactive command-line session with a network appliance. It's giving main character energy for three specific things: moving into "privileged" mode, moving into "configure" mode, and then sending commands to the connected device and getting the returned output back. 🫶

There are other CPAN modules covering similar ground, but ngl they're less robust and they do not handle native SSH, Telnet and Serial Line connections through a single interface on both Unix and Windows platforms. So like... this one ate. 💅

The built-in commands come from a phrasebook which supports so many network device vendors (Cisco, HP, etc) — or you can install a brand new phrasebook of your very own. Most phases of the connection are configurable, for different device behaviours. Obsessed. ✨

---

👑 METHODS 👑

Same as the synopsis up there — the first step is to create a new instance. 🌈

The recommended practice is to wrap all the other calls (except close()) in a try block, so you catch errors (typically time-outs while waiting for CLI response). This module exports the try/catch/finally methods (from Try::Tiny) into your namespace as a simpler alternative to using eval(). No cap. 🧚

For a full demonstration of usage, see the example script shipped with this distribution. 💖

---

🎀 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 are optional — let's vibe check them all:

• 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, bestie. ✨
• 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. Periodt. 💅

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. 💖

✨ CONFIGURATION ✨

okay so every single thing in this list? you can hit it two ways, bestie. either you pass it as a parameter in the options you hand to the new method, or you call it as a method all on its own and pass it the setting you want. If you're doing the second one — the method-call vibe — you gotta do it before you call connect. that's the rule. no exceptions. 💅

---

• do_login — defaults to true. Pass a zero (false) to turn off logging in to the device with a username and password — this is for when the device just gives you a command prompt the literal second you connect. no login era. 🎀
• do_privileged_mode — defaults to true. If, the moment you connect, your user is already sitting in "privieleged" mode (yes, that's the original spelling, iykyk, we keep it 💀), then set this to zero (false), and that permits immediate access to configure mode.
• do_configure_mode — defaults to true. Set this to zero (false) and the module assumes you're in configure mode immediately upon entering privileged mode. ngl the author literally says "I can't think why this would be useful but you never know" and honestly? iconic honesty. 🫶
• do_paging — defaults to true. Pass a zero (false) to disable the post-login reconfiguration of a device that avoids paged command output. Heads up: if you cleanly close the device connection then paging gets re-enabled. So use this option to suppress those steps.
• privileged_paging — defaults to false. On some series of devices — in particular the Cisco ASA and PIXOS7+ — you must be in privileged mode in order to alter the pager. If that's your device's whole situation, call this method with a true value to tell the module to better manage it. slay, adaptive. ✨
• pager_enable_lines — defaults to 24. The command that re-enables paging (on disconnect) typically takes a parameter which is the number of lines per page. Want a different number? Set it here.
• pager_disable_lines — defaults to zero. The command that disables paging typically takes a parameter which is the number of lines per page (zero begin to disable paging). If your device uses a different number in that spot, set it in this option.
• wake_up — so when you first connect, the most common scenario is that a Username (or some other) prompt shows up. BUT if no output is forthcoming and nothing matches, the enter key gets pressed, hoping to trigger the display of a new prompt. This is typically the most useful thing on Serial connected devices, fr fr.

Set this configuration option to zero to suppress that behaviour entirely, or set it to the number of times enter should be pressed and output waited for. The default is to press enter once.

---

🦋 ASYNCHRONOUS BEHAVIOUR 🦋

The standard, and recommended, way to use this module is exactly like above — where the application is blocked waiting for command response. But plot twist, you can also send a command and then separately come back later to ask for the output. main character scheduling energy. 👑

 $s->say('show clock');

This sends the command show clock to the connected device, followed by a newline character. cute and simple. 💖

 $s->gather();

This gathers and returns output, with behaviour similar to cmd(), above. Like, it blocks waiting for output and a prompt, it will timeout, and it accepts the same options. same vibes, different entry point.

You can still use last_response after calling gather — however, be aware that the command (from say) may be echoed at the start of the output, depending on device and connection transport. so don't be shook when you see it. 🙈

---

🔥 DIAGNOSTICS 🔥

Want a log of all the processes within this module, plus a copy of all data sent to and received from the device? call this method:

 $s->set_global_log_at('notice');

In place of notice you can have other log levels (e.g. debug for more, or info for less), and via the embedded Logger at $s->nci->logger it's possible to finely control the diagnostics. dial it in exactly how you like. ⭐

---

💜 INTERNALS 💜

See Net::CLI::Interact.

---

🌸 THANKS 🌸

Over several years I have received many patches and suggestions for improvement from users of this module. My heartfelt thanks to all, for their contributions. genuinely so sweet. 🥹

---

👑 AUTHOR 👑

Oliver Gorwits <oliver@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2019 by Oliver Gorwits.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie!! this beauty is from perl v5.36.0, dated 2022-12-09, and it's the Net::A...Session(3pm) manual — go forth and automate, you absolute legend 💅✨🦋