NAME

       Net::CLI::Interact::Manual::Cookbook - Miscellaneous recipes

Windows Support

       The library works just fine under native windows (i.e use something like Strawberry Perl -
       no need for cygwin), for Telnet, Serial and SSH connections.  However one additional step
       is required for you to have success:

       You must download the "plink.exe" application, and pass its filesystem location in the
       "app" parameter to "new()". Do not try to use any other Telnet or SSH programs (for
       instance the Windows bundled "telnet") - they will not work. Here's an example, if
       "plink.exe" is on your Desktop:

        my $s = Net::CLI::Interact->new(
            personality => "cisco",
            transport => "Telnet",
            (Net::CLI::Interact::Transport::is_win32() ?
                (app => "$ENV{HOMEPATH}\\Desktop\\plink.exe") : () ),
        );

Unix Support

       The library works fine on most Unix platforms. It will try to use the native "telnet",
       "ssh" (openssh) and "cu" programs for Telnet, SSH and Serial connections, respectively. If
       you want to use another application, pass it in the "app" parameter to "new".

       In some Unix environments there can be zombie child processes left around after running
       your script. If this happens, set the "reap" option, like so:

        my $s = Net::CLI::Interact->new(
            personality => "cisco",
            transport => "Telnet",
            connect_options => {
               reap => 1,
           },
        );

Running Commands

   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.

Reconfiguring On-the-Fly

   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 diffrent named Prompt from the
       phrasebook, this method can be used:

        $s->prompt_looks_like('name');

Logging

       A generic logging service is available through the "$session->logger" object, which is
       based on Log::Dispatch. You can configure the logger at startup quite easily. See the
       Net::CLI::Interact::Logger manual page for details of the interface (config for any option
       can simply be passed to "Net::CLI::Interact->new()").

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

Phrasebook Libraries

       You can override or add to the device command phrasebooks which ship with this
       distribution. To start with, check the shipped dictionary for your device's current level
       of support, at Net::CLI::Interact::Manual::Phasebook.

       If you want to add either some prompts or macros, first read the documentation for these
       systems at Net::CLI::Interact::Phrasebook.

       All phrasebooks can inherit from others, and this is based on their location in a
       filesystem tree. See the phrasebooks bundled with the Net::CLI::Interact distribution for
       an example of this in action.

       If you wish to override a phrasebook entry, simply set "add_library" in your code, and
       then create a file at the same relative point beneath that library directory as the
       original version shipped with the "Net::CLI::Interact" module, for example
       ""<add_library>/cisco/pixos/pixos7/my_phrases"".

       The file itself ("my_phrases") does not have to be the same name as the original, and you
       can have more than one file if it helps. Only the directory is matched against your chosen
       "personality" and then all files in there, and higher in the "add_library" tree, and
       distribution "library" tree, are loaded.

       To check what phrasebooks and prompts/macros are loaded, run your script with debug level
       set to "notice". The easiest way to do this is by setting the environment variable
       "NCI_LOG_AT=notice".

Phrasebook Entries

   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 ' '