%\documentclass[colorBG,slideColor,troispoints,pdf]{prosper}
\documentclass[colorBG,total,slideColor,ps]{prosper}
%\documentclass[colorBG,slideColor,ps]{prosper}

\usepackage{alltt,key,xr,cols,rcs,acro,meta,%
  graphicx,cpp,textcomp}
%\usepackage[nolineno,noindent]{lgrind}

%\definecolor{green}{rgb}{0,1,0}

% Copyright (c) 2003 by Nick Urbanik <nicku(at)vtc.edu.hk>.
% This material may be distributed only subject to the terms and
% conditions set forth in the Open Publication License, v1.0 or later
% (the latest version is presently available at
% http://www.opencontent.org/openpub/).

\RCS $Revision: 1.3 $

\externaldocument[pl-]{../perl/perl-slides}

\newcommand*{\bs}{\texttt{\char '134}} % Backslash `\'
%\newcommand*{\labTitle}{LDAP Directories}
\newcommand*{\subject}{Systems and Network Management}
\newcommand*{\emphcolour}[1]{\emph{\red#1}}

\providecommand*{\RPM}{\acro{RPM}\xspace}
\providecommand*{\CD}{\acro{CD}\xspace}
\providecommand*{\IPC}{\acro{IPC}\xspace}
\providecommand*{\UID}{\acro{UID}\xspace}
\providecommand*{\GID}{\acro{GID}\xspace}
\providecommand*{\SMP}{\acro{SMP}\xspace}
\providecommand*{\API}{\acro{API}\xspace}
\providecommand*{\OK}{\acro{OK}\xspace}
\providecommand*{\IETF}{\acro{OK}\xspace}
\providecommand*{\MS}{\acro{MS}\xspace}
\providecommand*{\VACM}{\acro{VACM}\xspace}
\providecommand*{\USM}{\acro{USM}\xspace}
\providecommand*{\IOS}{\acro{IOS}\xspace}
\providecommand*{\DES}{\acro{DES}\xspace}

% See page 49 of Graphics Companion
% #1, #2 x and y coordinates of reference point of brace in pt
% #3 rotation angle for large right brace in degrees: 90 faces down
%                              -90 faces up, 180 faces to the right
% #4 total height of brace in pt
\newcommand{\Bpara}[4]{%
  \begin{picture}(0,0)%
    \setlength{\unitlength}{1pt}%
    \put(#1,#2){\rotatebox{#3}{\raisebox{0mm}[0mm][0mm]{%
          \makebox[0mm]{$\left.\rule{0mm}{#4pt}\right\}$}}}}%
  \end{picture}%
}

\title{\mbox{}\blue{}Perl, Perl References, and SNMP}%
\subtitle{A Quick Guide to Using Perl with SNMP\\
  Includes a description of References in Perl}
\author{Nick Urbanik \texttt{<nicku(at)vtc.edu.hk> {\footnotesize\copyright{}} 2003}\\
  \footnotesize{}Copyright Conditions: Open Publication License (see
  \url{http://www.opencontent.org/openpub/})}%
\institution{Department of Information and Communications Technology}%
\slideCaption{SNM --- SNMP and Perl --- ver. \RCSRevision}
\Logo{\includegraphics[width=15mm]{ict-logo-smaller}}

\begin{document}
\maketitle

\begin{slide}{The Choices}
  \label{sld:choices}
  \begin{itemize}
  \item There are \emphcolour{three main choices} (but also many
    more!) if you want to {\blue{}write \SNMP code in Perl}:
    \begin{itemize}
    \item The Perl interface to the Net-SNMP library, called
      \texttt{SNMP}
      \begin{itemize}
      \item What you have when you install the software packages
        \texttt{net-snmp-perl} and \texttt{net-snmp-devel} on Fedora
        or Red Hat Linux
      \end{itemize}
    \item The \texttt{Net::SNMP} Perl library, together with
      \texttt{Net::SNMP::HostInfo} and \texttt{Net::SNMP::Interfaces}
      \begin{itemize}
      \item Install from \CPAN---see slide\S\pageref{sld:cpan}
      \end{itemize}
    \item Finally we have \texttt{SNMP\_Session}, from
      \url{http://www.switch.ch/misc/leinen/snmp/perl/}, used in the
      \texttt{cricket} application (at
      \url{http://cricket.sourceforge.net/})
    \end{itemize}
  \end{itemize}
\end{slide}

\begin{slide}{Advantages of Each Module --- 1}
  \label{sld:advantages-of-net-snmp}
  \begin{itemize}
  \item \texttt{Net::SNMP}
    \begin{itemize}
    \item Slowest of the three
    \item Easiest to install (from \CPAN or by \texttt{ppm})
    \item Supports \SNMP{}v3, plus new encryption schemes: Triple
      \acro{DES}, \texttt{AES}
    \item Very good documentation
    \item Good, simple to use extensions \texttt{Net::SNMP::HostInfo},
      \texttt{Net::SNMP::Interfaces}
    \end{itemize}
  \end{itemize}
\end{slide}  


\begin{slide}{Advantages of Each Module --- 2}
  \label{sld:advantages-of-snmp-snmp-session}
  \begin{itemize}
  \item \texttt{SNMP}
    \begin{itemize}
    \item Faster than the others, since it is linked against C
      libraries
    \item Supports \SNMP{}v3
    \item Harder to install on some platforms, e.g., Windows
    \end{itemize}
  \item \texttt{SNMP\_Session}
    \begin{itemize}
    \item Written in pure Perl, so very portable
    \item Fast, portable, used for Cricket, \acro{MRTG}
    \item Supports only \SNMP{}v1 and \SNMP{}v2c
    \end{itemize}
  \end{itemize}
\end{slide}

\begin{slide}{CPAN}
  \label{sld:cpan}
  \begin{itemize}
  \item See slide~\S\pageref{pl-sld:cpan} in the Perl lecture notes
  \item To install \texttt{Net::SNMP}:
\begin{alltt}\tiny
$ \textbf{sudo perl -MCPAN -e shell}
cpan shell -- CPAN exploration and modules installation (v1.7601)
ReadLine support enabled

cpan> \textbf{install Net::SNMP Net::SNMP::HostInfo Net::SNMP::Interfaces}
Running install for module Net::SNMP
Running make for D/DT/DTOWN/Net-SNMP-4.1.2.tar.gz
...
\end{alltt}%$
  \item List all \CPAN modules relating to \SNMP:
\begin{alltt}
cpan> \texttt{m /SNMP/}
\end{alltt}
  \end{itemize}
\end{slide}

\begin{slide}{PPM: installing on Windows}
  \label{sld:ppm-net-snmp}
  \begin{itemize}
  \item Just as easy to install into ActiveState Perl:
\begin{alltt}\tiny
D:\bs>\textbf{ppm}
PPM - Programmer's Package Manager version 3.1.
Copyright (c) 2001 ActiveState SRL. All Rights Reserved.
...

ppm> \textbf{install Net-SNMP}
====================
Install 'Crypt-DES' version 2.03 in ActivePerl 5.8.1.807.
====================
...
\end{alltt}
\item List all \SNMP Perl packages:
\begin{alltt}\tiny
ppm> \textbf{search snmp}
Searching in Active Repositories
   1. Apache-WebSNMP       [0.11] Embed SNMP get statements into HTML documents
...
\end{alltt}
  \end{itemize}
\end{slide}

\begin{slide}{References}
  \vspace*{0.1\slideWidth}

  \begin{center}\Large
    \mbox{}\blue{}Used with Nested Data Structures
 
    \vspace*{0.05\slideWidth}

    \ldots and with OO programming
 
    \vspace*{0.05\slideWidth}
 
    A Detour needed to understand Net::SNMP and Net::LDAP
  \end{center}
\end{slide}

\begin{slide}{References}
  \begin{itemize}
  \item I tried to avoid telling you about references, but you really
    need to know about them here
  \item Needed to implement nested data structures, i.e., arrays of
    arrays, or arrays of hashes of arrays of arrays of hashes\ldots
  \item An array element or a hash element must be a scalar
  \item A \emphcolour{reference} {\green{}is a scalar variable that
      refers to existing data}
    \begin{itemize}
    \item {\ldots\blue{}Such as an entire array or an entire hash} (or
      to just about anything else)
    \item Rather like a pointer in C
    \item Java implements references behind the scenes; Perl and \Cpp
      make them explicit
%%       \begin{itemize}
%%       \item When you assign to a variable in Java, you actually make a
%%         reference to it.
%%       \end{itemize}
    \end{itemize}
  \end{itemize}
\end{slide}

\begin{slide}{The backslash Operator}
  \begin{itemize}
  \item Create a reference to an existing variable using `\bs'
  \item Like ``address-of'' operator `\texttt{\&}' in C
  \item Examples:
\begin{verbatim}
$scalar_ref = \$foo;
$array_ref = \@array;
$hashref = \%hash;
$subroutine_ref = \&subroutine;
\end{verbatim}
  \end{itemize}
\end{slide}

\begin{slide}{Anonymous Array References}
  \begin{itemize}
  \item Often needed when constructing nested structures (and with
    Net::SNMP)
  \item Use square brackets:
\begin{verbatim}
my $array_ref = [ 1, 2, [ 'a', 'b', 'c' ] ];
\end{verbatim}%$
  \item Here we made a reference to an anonymous array of three
    elements, the last element of which is another anonymous array of
    three elements.
  \end{itemize}
\end{slide}

\begin{slide}{Anonymous Hash References}
  \begin{itemize}
  \item Use braces:
\begin{verbatim}
my $hash_ref = {
   Adam => 'Eve',
   Clyde => 'Bonnie',
};
\end{verbatim}%$
  \item See \texttt{perldoc perldsc} for cookbook examples of how to
    build arrays of hashes, arrays of arrays, hashes of hashes, hashes
    of arrays, \ldots
  \end{itemize}
\end{slide}

\begin{slide}{Using a Reference}
  \begin{itemize}
  \item Three methods: use a reference as the variable name, use
    block, use arrow method.
  \item First method: Access the value of a reference by putting the
    ``right'' funny character in front of the reference
  \item Examples:
\begin{verbatim}
print "value is $$scalar_ref\n";
foreach ( @$array_ref ) {
    print;
}
foreach my $key ( sort keys %$hash_ref ) {
    print "$key => $$hash_ref{$key}\n";
}
my $return_value = &$subroutine_ref( 1, 2 );
\end{verbatim}%$
  \end{itemize}
\end{slide}

\begin{slide}{Using a Block as a Variable Name}
  \begin{itemize}
  \item Method 2: use a block returning a reference where a variable
    name would be.
    \begin{itemize}
    \item Block returns a value either with the \texttt{return}
      statement, or returns the last value appearing in the block
    \end{itemize}
  \item Examples:
    {%\scriptsize
\begin{verbatim}
print "value is ${$scalar_ref}\n";
foreach ( @{$array_ref} ) {
    print;
}
my $return_value = &{$subroutine_ref}( 1, 2 );
${$array_ref}[0] = "January";
${$hash_ref}{key} = "value";
\end{verbatim}%$
    }
%% foreach my $key ( sort keys %{$hash_ref} ) {
%%     print "$key => ${$hash_ref}{$key}\n";
%% }
  \end{itemize}
\end{slide}

\begin{slide}{The Arrow Operator}
  \begin{itemize}
  \item Method 3: Used when reference expression complicated; often
    used to call \emphcolour{methods} in OO
    \begin{itemize}
    \item \ldots{} because a Perl object \emphcolour{is} a reference
    \end{itemize}
  \item The following are equivalent:
\begin{verbatim}
$ $array_ref  [0] = "January";
${$array_ref} [0] = "January";
  $array_ref->[0] = "January";
\end{verbatim}%$
    \begin{itemize}
    \item So are these:
    \end{itemize}
\begin{verbatim}
$ $hash_ref  {key} = "value";
${$hash_ref} {key} = "value";
  $hash_ref->{key} = "value";
\end{verbatim}%$
  \end{itemize}
\end{slide}

\begin{slide}{Documentation About References}
  \begin{itemize}
  \item The following documentation is provided with Perl:
    \begin{itemize}
    \item \texttt{perldoc \red{}perlreftut} is a short tutorial
      introduction to references
    \item \texttt{perldoc \red{}perldsc} is a tutorial cookbook with
      lots of examples showing how to build complex nested data
      structures
    \item \texttt{perldoc \red{}perlref} is the complete manual for
      Perl references
    \end{itemize}
  \item I suggest read them in that order
  \item {\mbox{}\blue{}\Large{}We have finished looking at References
      --- Now we return to \texttt{Net::SNMP}}
  \end{itemize}
\end{slide}

%% \begin{slide}{Net::SNMP}
%%   \vspace*{0.15\slideWidth}

%%   \begin{center}\Large
%%     \mbox{}\blue{}\ldots{} Continued
 
%%     \vspace*{0.1\slideWidth}

%%     End of the Detour
%%   \end{center}
%% \end{slide}

\begin{slide}{The \texttt{Net::SNMP} Package}
  \label{sld:intro-to-net-snmp}
  \begin{itemize}
  \item Provides an object-oriented interface to \SNMP
  \item One \texttt{Net::SNMP} object corresponds to one remote \SNMP
    agent or manager
  \item Each \texttt{Net::SNMP} object has either
    \emphcolour{blocking} or \emphcolour{non-blocking} properties
    \begin{itemize}
    \item Blocking: methods do not return until response received or
      timeout
    \item Non-blocking: queue requests.  Response comes back via a
      \emphcolour{callback} routine.
    \item We {\green{}only cover blocking operations here} because
      they are simpler, but do not be afraid to read the good
      documentation and use other methods; see
      slide~\S\pageref{sld:documentation-net::snmp}
    \end{itemize}
  \end{itemize}
\end{slide}

\begin{slide}{Results of Method Calls}
  \label{sld:results-of-method-calls}
  \begin{itemize}
  \item Methods that require a response return a \emphcolour{hash
      reference} containing query results
    \begin{itemize}
    \item Returns undefined value on failure
    \item \texttt{error()} method shows cause of failure
    \end{itemize}
  \item \emphcolour{key} in hash is dotted \OID
  \item \emphcolour{value} is, well, the value returned for that \OID
  \item The hash reference can also be obtained using the
  \texttt{var\_bind\_list()} method
  \end{itemize}
\end{slide}

\begin{slide}{Named Method Parameters}
  \label{sld:named-method-parameters}
  \begin{itemize}
  \item Method parameters used a dashed-option naming style:
\begin{verbatim}
$object->method( -argument => $value );
\end{verbatim}
  \item Use a hash as the parameter list, a common ideom in Perl
  \item The ``\texttt{=>}'' is just the quoting comma commonly used in
    initialising hashes, as explained in
    slide~\S\pageref{pl-sld:initialising-hash} in version 1.6 of my
    Perl slides
  \end{itemize}
\end{slide}

\begin{slide}{\texttt{session()} --- Create New Session}
\label{sld:session-1}
\tiny%
\vspace*{-3.5ex}\par
\hspace*{1.5cm}%
\begin{minipage}[t]{0.9\slideWidth}
\begin{verbatim}
($session, $error) = Net::SNMP->session(
     [-hostname     => $hostname,]
     [-port         => $port,]
     [-localaddr    => $localaddr,]
     [-localport    => $localport,]
     [-nonblocking  => $boolean,]
     [-version      => $version,]
     [-timeout      => $seconds,]
     [-retries      => $count,]
     [-maxmsgsize   => $octets,]
     [-translate    => $translate,]
     [-debug        => $bitmask,]
     [-community    => $community,]   # v1/v2c
     [-username     => $username,]    # v3
     [-authkey      => $authkey,]     # v3
     [-authpassword => $authpasswd,]  # v3
     [-authprotocol => $authproto,]   # v3
     [-privkey      => $privkey,]     # v3
     [-privpassword => $privpasswd,]  # v3
     [-privprotocol => $privproto,]   # v3
  );
\end{verbatim}%$
\end{minipage}
\end{slide}

\begin{slide}{\texttt{session()} --- Parameters}
\label{sld:session-parameters}
\begin{itemize}
\item \texttt{-version} parameter indicates security model
  \begin{itemize}
  \item Can be \texttt{1}, \texttt{2} or \texttt{3}, or the strings
    \texttt{'snmpv1'}, \texttt{'snmpv2c'} or \texttt{'snmpv3'}
  \end{itemize}
\item Read the section \emph{User-based Security Model Arguments} in
  \texttt{perldoc Net::SNMP} for details about \texttt{-username},
  \texttt{-authkey}, \texttt{-authpassword}, \texttt{-privkey},
  \texttt{-privpassword}, \texttt{-authprotocol},
  \texttt{-privprotocol} parameters
\end{itemize}
\end{slide}

\begin{slide}{\texttt{get\_request()}}
  \begin{itemize}
  \item send a \SNMP \texttt{get-request} to the remote agent
  \end{itemize}
\begin{verbatim}
$result = $session->get_request(
   [-contextengineid => $engine_id,] # v3
   [-contextname     => $name,]      # v3
   -varbindlist      => \@oids,
);
\end{verbatim}
  \begin{itemize}
  \item The square brackets mean the parameter is optional
  \item The parameter \texttt{-varbindlist} is a reference to a list
    of \OID{}s
  \item This is a reference to an array of strings that give the
    full numerical \OID of an \SNMP variable, such as
    \texttt{'1.3.6.1.2.1.1.3.0'}.
    \begin{itemize}
    \item See example in slide~\pageref{sld:get-request-example-1}
    \end{itemize}
  \end{itemize}
\end{slide}

\begin{slide}{\texttt{get\_next\_request()}}
  \begin{itemize}
  \item send a \SNMP \texttt{get-next-request} to the remote agent
  \end{itemize}
\begin{verbatim}
$result = $session->get_next_request(
   [-contextengineid => $engine_id,] # v3
   [-contextname     => $name,]      # v3
   -varbindlist      => \@oids,
);
\end{verbatim}
\end{slide}

\begin{slide}{\texttt{set\_request()}}
  \begin{itemize}
  \item send a \SNMP \texttt{set-request} to the remote agent
  \end{itemize}
\vspace*{-0.6\baselineskip}
\begin{verbatim}
$result = $session->set_request(
   [-contextengineid => $engine_id,] # v3
   [-contextname     => $name,]      # v3
   -varbindlist      => \@oid_value,
);
\end{verbatim}
\vspace*{-0.6\baselineskip}
  \begin{itemize}
  \item The \texttt{-varbindlist} parameter is a reference to an array
  of three values: a string representing the full numerical \OID, the
  type, and the value.
\item Here is an example:
\end{itemize}
\vspace*{-0.6\baselineskip}
{\tiny
\begin{verbatim}
my $sysContact = '1.3.6.1.2.1.1.4.0';
my $result = $session->set_request(
   -varbindlist => [ $sysContact, OCTET_STRING, 'Help Desk x911' ]
);
\end{verbatim}%
}
\end{slide}

\begin{slide}{\texttt{trap()}}
  \begin{itemize}
  \item send an \SNMP \texttt{trap} to the remote manager
  \end{itemize}
\begin{verbatim}
$result = $session->trap(
   [-enterprise      => $oid,]
   [-agentaddr       => $ipaddress,]
   [-generictrap     => $generic,]
   [-specifictrap    => $specific,]
   [-timestamp       => $timeticks,]
   -varbindlist      => \@oid_value,
);
\end{verbatim}%$
\end{slide}

\begin{slide}{\texttt{get\_bulk\_request()}}
  \begin{itemize}
  \item send a \texttt{get-bulk-request} to the remote agent
  \end{itemize}
\begin{verbatim}
$result = $session->get_bulk_request(
   [-contextengineid => $engine_id,] # v3
   [-contextname     => $name,]      # v3
   [-nonrepeaters    => $non_reps,]
   [-maxrepetitions  => $max_reps,]
   -varbindlist      => \@oids,
);
\end{verbatim}
\end{slide}  

\begin{slide}{\texttt{inform\_request()}}
  \begin{itemize}
  \item send an \texttt{inform-request} to the remote manager
  \end{itemize}
\begin{verbatim}
$result = $session->inform_request(
   [-contextengineid => $engine_id,] # v3
   [-contextname     => $name,]      # v3
   -varbindlist      => \@oid_value,
);
\end{verbatim}
\end{slide}  

\begin{slide}{\texttt{snmpv2\_trap()}}
  \begin{itemize}
  \item send a \texttt{snmpV2-trap} to the remote manager
  \end{itemize}
\begin{verbatim}
$result = $session->snmpv2_trap(
   -varbindlist      => \@oid_value,
);
\end{verbatim}
  \begin{itemize}
  \item Only works with \texttt{-version} corresponding to
    \texttt{'snmpv2c'}
  \item Net::SNMP does not support using this with \texttt{snmpv3}
  \end{itemize}
\end{slide}  

\begin{slide}{\texttt{error()}, \texttt{close()}}
  \begin{itemize}
  \item \texttt{error()} --- get the current error message from the
    object
    \begin{itemize}
    \item This method returns a text string explaining the reason for the last
      error.
    \item An empty string is returned if no error has occurred.
    \end{itemize}
\begin{verbatim}
$error_message = $session->error;
\end{verbatim}
  \item \texttt{close()} --- clear the Transport Layer associated with
    the object
\begin{verbatim}
$session->close;
\end{verbatim}%$
  \end{itemize}
\end{slide}

\begin{slide}{Example: \texttt{get-request} --- 1}
\label{sld:get-request-example-1}
\tiny
\begin{verbatim}
use Net::SNMP;

my ($session, $error) = Net::SNMP->session(
   -hostname  => shift || 'localhost',
   -community => shift || 'public',
   -port      => shift || 161
);

if (!defined($session)) {
   printf("ERROR: %s.\n", $error);
   exit 1;
}

my $sysUpTime = '1.3.6.1.2.1.1.3.0';

my $result = $session->get_request(
   -varbindlist => [ $sysUpTime ]
);
\end{verbatim}
\end{slide}

\begin{slide}{Example: \texttt{get-request} --- 2}
\tiny
\begin{verbatim}
if (!defined($result)) {
   printf("ERROR: %s.\n", $session->error);
   $session->close;
   exit 1;
}

printf("sysUpTime for host '%s' is %s\n",
   $session->hostname, $result->{$sysUpTime}
);

$session->close;

exit 0;
\end{verbatim}%$
\end{slide}

\begin{slide}{Documentation for \texttt{Net::SNMP}}
  \label{sld:documentation-net::snmp}%
  %\tiny
  \begin{itemize}
  \item The \texttt{perldoc} documentation for \texttt{Net::SNMP} is
    good, and with examples.  Read the following documents using
    either \texttt{perldoc} or, on Linux, \texttt{man} if you like:
    \begin{itemize}
    \item \texttt{Net::SNMP}
    \item \texttt{Net::SNMP::HostInfo}
    \item \texttt{Net::SNMP::HostInfo::IpAddrEntry}
    \item \texttt{Net::SNMP::HostInfo::IpNetToMediaEntry}
    \item \texttt{Net::SNMP::HostInfo::IpRouteEntry}
    \item \texttt{Net::SNMP::HostInfo::TcpConnEntry}
    \item \texttt{Net::SNMP::HostInfo::UdpEntry}
    \item \texttt{Net::SNMP::Interfaces}
    \item \texttt{Net::SNMP::Interfaces::Details}
    \end{itemize}
  \end{itemize}
\end{slide}  


\begin{slide}{Docs: \texttt{NetSNMP}, \texttt{SNMP\_Session}}
  \label{sld:documentation-net-snmp-snmp-session}%
  %\tiny
  \begin{itemize}
  \item For Net-SNMP (Yes, names are a little confusing; I mean the
    software from \url{http://net-snmp.sourceforge.net/}), read:
    \begin{itemize}
    \item \texttt{SNMP}
    \item \texttt{NetSNMP::ASN}
    \item \texttt{NetSNMP::OID}
    \end{itemize}
  \item For \texttt{SNMP\_Session} and \texttt{BER}, see
    \url{http://www.switch.ch/misc/leinen/snmp/perl/}
  \end{itemize}
\end{slide}
\end{document}