Simple Commands

Simply send the command you wish to execute to the session. If not already done, a connection to the device will be established automatically:

 $s->cmd('show ip int br');

Normally this matches against a default prompt, which has been discovered automatically, or set by you:

 $s->set_prompt('user_prompt');

It's also possible to pass in a custom prompt for this command only:

 $s->cmd('show ip int br', { match => qr/special prompt>$/ });

However be aware that a side effect of this is that the custom prompt becomes the new default prompt for subsequent commands or macros.

Macro Commands

Call a predefined Macro from the phrasebook using this method:

 $s->macro('write_mem');

Sometimes the Macro needs parameters:

 $s->macro('to_priv_exec', { params => ['my_password'] });

You can't really create a Macro on the fly very easily, but with suitable use of "cmd()", "set_prompt()", and the "match" option to "cmd()" it's possible to achieve some simple flexibility.

Phrasebook

It's possible to load a new phrasebook by the following method, which must be passed at least the name of the personality:

 $s->set_phrasebook({ personality => 'ios' });

You can pass any options which the Phrasebook module itself would take.

Prompt

The current prompt can be changed by passing the name of the new Prompt as it is known by the phrasebook:

 $s->set_prompt('name');

If you want to test whether the current prompt matches a different named Prompt from the phrasebook, this method can be used:

 $s->prompt_looks_like('name');

Destinations

The default configuration sends logging messages to standard output. Let's say you also want to append them to a log file:

 my $s = Net::CLI::Interact->new({
     log_config => {
         dispatchers => ['screen','file'],
         screen => {
             class => 'Log::Dispatch::Screen',
             min_level => 'warning',
         },
         file => {
             class => 'Log::Dispatch::File',
             min_level => 'debug',
             filename => '/var/log/myapp.log',
             mode => 'append',
             format => '[%d] %m',
         },
     },
     # etc...
 });

Note that some keys are required, such as the "class" and "min_level" but others depend on the particular class being used. See Log::Dispatch::Config for more details.

Log Levels and Categories

Each log message has a standard log level ("debug", "warning", etc) but also a category which is a concept local to this module. Categories allow more filtering of what is logged. Each time a message is logged through "$s->logger->log(...)" it has a level and category.

Messages are only emitted if they pass the specific level set for that category. In this way we can suppress messages about the transport but, for example, show messages about prompt-matching at a debug level.

You can very easily set the log level for all categories using either the "set_global_log_at" option to "new()", or the "NCI_LOG_AT" environment variable.

To configure these filters, use the "log_flags" option together with the list of default log categories used by "Net::CLI::Interact". For example:

 my $s = Net::CLI::Interact->new({
     log_flags => {
         (map {$_ => 'notice'} Net::CLI::Interact->default_log_categories()),
         dialogue => 'info',
     },
     # etc...
 });

This example would set all categories to "notice" level except for the "dialogue" category, which is set to "info" level to get more output (on what is sent and received by each command).

Prompts

These are nothing more than named regular expressions:

 prompt configure
     match /\(config[^)]*\)# ?$/

Macros

This example waits for the device to ask "[startup-config]?" and then responds with the text "startup-config". Remember, there is an implicit "match" statement added at the end, which is the current prompt.

 macro copy_run_start
     send copy running-config startup-config
     match /Destination filename \[startup-config\]\?$/
     send startup-config

To send instead a "press" of the Return key (output record separator), use:

 macro write_mem
     send copy running-config startup-config
     match /Destination filename \[startup-config\]\?$/
     send ''

To instead allow the user to pass in the file name, use a "sprintf" format.

 macro save_to_file
     send copy running-config startup-config
     match /Destination filename \[startup-config\]\?$/
     send %s

The user must then pass a parameter to the "macro" call, even if it's an empty string:

 $s->macro('save_to_file', { params => ['file_name'] });
 # or
 $s->macro('save_to_file', { params => [''] });

Continuations

These are Macros which start with a match instead of a send:

 macro more_pages
     match / --More-- /
     send ' '

Note that the parameter of the "send" is not sent with a Return character (output record separator) appended.

When included in a macro, the continuation can be in-line, like this:

 macro show_ip_route
     send show ip route
     follow / --More-- / with ' '