=pod

=head1 NAME

Net::Appliance::Session::Cookbook::Intro - Getting Started

=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 THE INTRODUCTION

Hi, and just a few words about why I've put this Cookbook together.

I recently had a project that required a script to perform an SSH session to a
Cisco device and make some configuration changes. My favourite scripting
language is, of course, Perl.

I had previously written scripts using the C<Net::Telnet> module that would
Telnet to a device, detect various device prompts and send commands to the
device to change its configuration. So, I thought that this was going to be a
fairly straightforward case of just finding a suitable, similar module that
uses SSH instead of Telnet.

The other thing that I need to mention is that I am generally constrained to
using Win32 platforms (i.e. Windows 200, 2003, XP) due to the fact that most
client sites that I work on these days do not use Unix (or Linux), which is a
real pity in my opinion, but I don't set the corporate policies of my clients.

An initial glance of the available perl modules revealed a number of modules
which seemed to be just what I needed:

=over 4

=item * C<Net::Appliance::Session>

=item * C<Net::SSH::W32Perl>

=item * C<Net::SSH>

=back

So, I told my boss, "Yep, no problem" and set about pulling together a script
to SSH in to a remote device and send it some commands to change its
configuration.

After a day or so of trying various modules, I thought: "Hmmm, maybe this
isn't going to be as easy as I'd thought!'

Each of the modules I'd looked at seemed to have an issue when it came to using
it in a Windows environment. To summarise, here are the issues I found with
each module:

=over 4

=item Net::Appliance::Session

Has a dependency on C<IO::Pty>, which won't ever run on Windows.

=item Net::SSH::W32Perl

"getpwuid function is unimplemented" message when building from scratch. Older
PPD's found at L<http://www.soulcage.net/ppds.58> just don't seem to work, even
when installed in to the Activestate perl distribution

=item Net::SSH

Unix only.

=back

So, at this point, I was beginning to think that maybe this just wasn't going
to work at all on Windows...

Then, I remembered seeing a posting on Perl mongers where someone has mentioned
that they had used perl in cygwin to run one of the Net::* modules.

So, although the thought of having to download and install cygwin didn't
initially seem too appealing, I thought I'd give it a go as I had no where else
to go.

=head2 Cygwin

Cygwin is, well, let me quote directly from the cygwin web site:

 Cygwin is a Linux-like environment for Windows. It consists of two parts:

 A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing
 substantial Linux API functionality. A collection of tools which provide Linux
 look and feel.

 The Cygwin DLL currently works with all recent, commercially released x86 32
 bit and 64 bit versions of Windows, with the exception of Windows CE.

So, it allows you to run in a Linux-type environment, and sounds far more
promising for the various Net::* modules that I had been looking at.

Also, once the basic cygwin core is installed, it allows you to download and
install a whole host of other goodies, including perl!

So, I set about installing cygwin by downloading the 'setup.exe' file from the
cygwin home page and running it on my PC.

Cygwin provides a failrly intuitive GUI to let you select a mirror to download
files from, and which packages you would like to download.

Here are the packages that I installed beyond just the basic core cygwin
packages that are installed for you:

 gcc-core
 gnupg
 make
 ncftpget
 openSSH
 perl
 perl-ExtUtils
 wget
 zip

You can install others (in addition) if you like, but these did the job for me.

=head2 Perl

Once I had cygwin installed (including the Perl distribution that I included),
I was all set to add in the modules that I wanted to try to use (e.g.
L<Net::Appliance::Session>).

If you are familiar with Perl on Unix systems, then you will probably be very
familiar with the CPAN shell to add modules into your perl distribution. Under
cygwin, the process is exactly the same.

If you are used to using the Activestate version of perl, you are probably used
to using the Activestate PPM manager to add new modules to perl. Well, the bad
news is that under cygwin, you don't have a PPM manager, and you have to use
the CPAN shell, which is a little bit trickier to use if you aren't used to it.
The good news however, is that you will have access to far more Perl modules!

When you installed cygwin, it will have put an icon somewhere (either on your
desktop, quicklauch bar or start menu) so that you can launch the cygwin shell.

If you click the shell icon, you will get a nice cygwin shell open up where you
can type in various commands. You can think of it as a Unix shell to all
intents and purposes.

To load in the Perl modules you'll need, you need to enter C<cpan> at the
command prompt. This will allow you to load new modules in to your Perl
distribution.

Now, the first time you go in to the CPAN shell, it will aks you lots of rather
awkward questions about where various utilities are and which mirror you would
like to use. In the main, if you have installed the modules that I recommended
for cygwin, you can accept the defaults. (The mirror you will have to figure
out for yourself - it depends where in the world you are).

The only setting I would recommend you change from the default is the question
about whether you should be 'asked or follow' for pre-requisite modules - I
would go for 'follow' to save a lot of hassle.

Once you have your cpan shell open (you can tell, because you now have a
C<< cpan> >> prompt), you need to enter the following commands to load in some
perl modules that you will need:

 install LWP (accept all defaults to any questions asked)
 install Net::Appliance::Session

When you enter these commands, you will see lots of things flying up the screen
as the modules are installed for you.

=head2 Running Scripts

Well, at this point, we have taken a rather whirlwind tour through getting
cygwin and Perl instaled on your platform, but you should now be in a position
to run some Perl scripts.

We installed the Net::Appliance::Session module in to your perl distribution,
so that we can run perl scripts that will use it to give us either Telnet or
SSH sessions to a target device.

As we are running under the cygwin environment, we can now use this module on a
Windows platform - something we couldn't do by just installing Activestate
Perl, or even by compiling our own version of Perl under Windows. So, now, we
CAN run perl scripts that will allow us to perform SSH sessions to network
devices that only support SSH.

You may be wondering: "does that mean that I have to run my perl scripts from
the cygwin shell every time I need to run them ?". Well, the good news is that
no, you don't! As long as you call the cygwin Perl executable to run your
script, it will run fine from a DOS prompt (or system scheduler!). So, this
would work fine:

 c:\ c:\cygwin\bin\perl.exe myscript.pl

Anyhow, I guess that's enough to let you know how I cracked my particular
issue. I hope to cover all of this in a little more detail in future aritcles,
as well as providing more informatipon about how to use the incredibly useful
Net::Appliance::Session module to create some useful scripts to control and
configure your network devices.

=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
