=pod

=head1 NAME

Net::Appliance::Session::Cookbook::Recipe05 - Getting In To Enable Mode

=head1 NOTE

This Cookbook was contributed to the L<Net::Appliance::Session> project by
Nigel Bowden. Source code from the Cookbook is shipped in the C<examples>
folder of this module's distribution.

=head1 PROBLEM

You want to login to a Cisco device and get in enable mode to perform some
pivilege level 15 commands.

=head1 SOLUTION

Depending on the configuration of your Cisco device, there are a number of
possible combinations that need to be catered for in terms of
password/username combinations. Here is a table of (hopefully) the most common
combinations that will be encountered when trying to Telnet/SSH to a Cisco
device :

 #  Case                                 Prompts             Commands

 1  Simple password-only login dropped   Password: secret    $session_obj->connect(Password=> 'secret');
    straight in to priv 15               router#             $session_obj->do_privileged_mode(0);
    
 2  Username and password straight in    Username: nigel     $session_obj->connect(Name => 'nigel', Password=> 'secret');
    to priv 15                           Password: secret    $session_obj->do_privileged_mode(0);
 
 3  Password for login to priv level 1   Password: secret    $session_obj->connect(Password=> 'secret'); 
    followed by password for priv 15     router> enable      $session_obj->begin_privileged( 'cisco' );
                                         Password: cisco
                                         router#
 
 4  Username and password for priv       Username: nigel     $session_obj->connect(Name => 'nigel', Password=> 'secret');
    level 1, followed by pwd for priv    Password: secret    $session_obj->begin_privileged( 'cisco' );
    level 15                             router> enable
                                         Password: cisco
                                         router#
 
 5  Username and password for priv       Username: nigel     $session_obj->connect(Name => 'nigel', Password=> 'secret');
    level 1, followed by same user       Password: secret    $session_obj->begin_privileged();
    name & pwd for enable                router> enable
                                         Username: nigel
                                         Password: secret
                                         router#
                                            
 6  Username and password for priv       Username: nigel     $session_obj->connect(Name => 'nigel', Password=> 'secret');
    level 1, followed by different       Password: secret    $session_obj->begin_privileged( 'foo', 'bar');
    username & pwd for enable            router> enable
                                         Username: foo
                                         Password: bar
                                         router#

=head1 DISCUSSION

The table above is (hopefully) largely self explantory and should serve as a
useful lookup to adapt scripts to your particular environment.

However one point that needs some explanation potentially is the C<<
$session_obj->do_privileged_mode(0) >> statement. This is used in the
scenarios where the user is dropped straight in to enable mode (priv 15) upon
logging in.

Net::Appliance::Session does some internal checking to see if you are already
in enable mode before it will let you enter configure mode (using C<conf t> in
IOS). Unless you use the C<< $session_obj->do_privileged_mode(0) >> statement to
tell Net::Appliance::Session that we are already in enable mode (priv 15), it
will raise an error when we try to go in to configure mode (using the
C<< $session_obj->begin_configure() >>, which we haven't covered yet). So, it's best
to let Net::Appliance::Session know we are in enable mode once we have logged
in.

Finally, remember that unless you use the error handling recommended in the
last recipe, your scripts will fail at the point that any unexpected reposnses
are received during the login process.

=head1 SEE ALSO

=over 4

=item L<Net::Appliance::Session>

=back

=head1 AUTHOR

Nigel Bowden, with POD formatting by Oliver Gorwits.

=head1 COPYRIGHT & LICENSE

Copyright (c) Nigel Bowden 2007. All Rights Reserved.

You may distribute and/or modify this documentation under the same terms as
Perl itself.

=cut