\documentclass{ictlab}
%\documentclass[slides,12pt]{lect2}

\usepackage{verbatim,alltt,acro,rcs}
\RCS $Revision: 1.1 $
%\slidesmag{3}
%\renewcommand*{\thepage}{\arabic{page}}
\providecommand*{\revision}{\RCSRevision}
\usepackage[pdfpagemode=None,pdfauthor={Nick Urbanik}]{hyperref}

\providecommand*{\SMI}{\acro{SMI}\xspace}
\providecommand*{\ASN}{\acro{ASN}\xspace}
\providecommand*{\BER}{\acro{BER}\xspace}
\providecommand*{\MIB}{\acro{MIB}\xspace}
\providecommand*{\MDB}{\acro{MDB}\xspace}
\providecommand*{\RFC}{\acro{RFC}\xspace}
\providecommand*{\OID}{\acro{OID}\xspace}
\providecommand*{\NMS}{\acro{NMS}\xspace}
\providecommand*{\SNMP}{\acro{SNMP}\xspace}

%% \newcommand*{\labTitle}{Tutorial Exercises on the Structure of Management
%%   Information (SMI)}
\newcommand*{\labTitle}{The Structure of Management
  Information (SMI)}

\begin{document}
\Large

\section{Background}

The \SNMP protocol is called ``simple'' because the protocol itself is
quite simple.  However, the difficulty is in applying it to actually
managing systems and networks.

There are many terms and standards involved; it is necessary to
understand enough of them to make sense of the \MIB{}s that define the
objects that you want to monitor and manage.  If you can make sense of
the \MIB files, you can identify the objects that you want to monitor.


\subsection{Management Information Base (MIB)}
\label{sec:mibs}

The \MIB{}s define the objects that you can manage.

When you installed the Net \SNMP software package, you installed some
\MIB files into the directory
\texttt{/usr\allowbreak/share\allowbreak/snmp\allowbreak/mibs/}.  You
can list them all with:
\begin{verbatim}
$ rpm -ql ucd-snmp | grep snmp/mibs/.*\.txt
\end{verbatim}%$

There are many other \MIB{}s that are not included here; you can
download others from somewhere such as
\url{http://www.simpleweb.org/ietf/} and include them into your Net
\SNMP clients as explained at
\url{http://net-snmp.sourceforge.net/FAQ.html#How_do_I_add_a_MIB_} and
at
\url{http://net-snmp.sourceforge.net/tutorial/commands/mib-options.html}.

\subsection{Management Database (MDB)}
\label{sec:mdb}

The \MIB{}s define what actual information the \MDB may contain.  The
management database is a real database, and holds the actual data,
whos format is defined by the \MIB, stored in the agent or manager.
It contains the measured or administratively configured values of the
elements of the network.

\subsection{Structure of Management Information}
\label{sec:smi}
\begin{figure}[hb]
  \centering%
  \includegraphics[width=\linewidth]{smi-object-tree}
  \caption{The Structure of Management Information Object Tree.}
  \label{fig:smi-tree}
\end{figure}
\SMI is a definition of the structure of the \MIB{}s, how they are
connected together into a tree, as shown in figure~\vref{fig:smi-tree}.
See the \RFC{}s below in section~\vref{sec:standards}.  It specifies
which part of \ASN.1 will be used to define \MIB{}s.  The \MIB that
defines \SMI is shown here:
\begin{verbatim}
RFC1155-SMI DEFINITIONS ::= BEGIN

EXPORTS -- EVERYTHING
        internet, directory, mgmt,
        experimental, private, enterprises,
        OBJECT-TYPE, ObjectName, ObjectSyntax, SimpleSyntax,
        ApplicationSyntax, NetworkAddress, IpAddress,
        Counter, Gauge, TimeTicks, Opaque;

 -- the path to the root

 internet      OBJECT IDENTIFIER ::= { iso org(3) dod(6) 1 }

 directory     OBJECT IDENTIFIER ::= { internet 1 }

 mgmt          OBJECT IDENTIFIER ::= { internet 2 }

 experimental  OBJECT IDENTIFIER ::= { internet 3 }

 private       OBJECT IDENTIFIER ::= { internet 4 }
 enterprises   OBJECT IDENTIFIER ::= { private 1 }

 -- definition of object types

 OBJECT-TYPE MACRO ::=
 BEGIN
     TYPE NOTATION ::= "SYNTAX" type (TYPE ObjectSyntax)
                       "ACCESS" Access
                       "STATUS" Status
     VALUE NOTATION ::= value (VALUE ObjectName)

     Access ::= "read-only"
                     | "read-write"
                     | "write-only"
                     | "not-accessible"
     Status ::= "mandatory"
                     | "optional"
                     | "obsolete"
 END

    -- names of objects in the MIB

    ObjectName ::=
        OBJECT IDENTIFIER

    -- syntax of objects in the MIB

    ObjectSyntax ::=
        CHOICE {
            simple
                SimpleSyntax,
    -- note that simple SEQUENCEs are not directly
    -- mentioned here to keep things simple (i.e.,
    -- prevent mis-use).  However, application-wide
    -- types which are IMPLICITly encoded simple
    -- SEQUENCEs may appear in the following CHOICE

            application-wide
                ApplicationSyntax
        }

       SimpleSyntax ::=
           CHOICE {
               number
                   INTEGER,
               string
                   OCTET STRING,
               object
                   OBJECT IDENTIFIER,
               empty
                   NULL
           }

       ApplicationSyntax ::=
           CHOICE {
               address
                   NetworkAddress,
               counter
                   Counter,
               gauge
                   Gauge,
               ticks
                   TimeTicks,
               arbitrary
                   Opaque

       -- other application-wide types, as they are
       -- defined, will be added here
           }

       -- application-wide types

       NetworkAddress ::=
           CHOICE {
               internet
                   IpAddress
           }

       IpAddress ::=
           [APPLICATION 0]          -- in network-byte order
               IMPLICIT OCTET STRING (SIZE (4))

       Counter ::=
           [APPLICATION 1]
               IMPLICIT INTEGER (0..4294967295)

       Gauge ::=
           [APPLICATION 2]
               IMPLICIT INTEGER (0..4294967295)

       TimeTicks ::=
           [APPLICATION 3]
               IMPLICIT INTEGER (0..4294967295)

       Opaque ::=
           [APPLICATION 4]          -- arbitrary ASN.1 value,
               IMPLICIT OCTET STRING   --   "double-wrapped"

       END
\end{verbatim}

\subsection{Abstract Syntax Notation One (ASN.1)}
\label{sec:asn.1}

\ASN.1 is widely used for many things other than \SNMP.  See
\url{http://asn1.elibel.tm.fr/en/uses/} for a list of some of the
applications of \ASN.1.  There is a
web site dedicated to providing information about it at
\url{http://asn1.elibel.tm.fr/}.


\subsection{Basic Encoding Rules (BER)}
\label{sec:ber}

The \emph{basic encoding rules} is an \ISO standard.  It describes a
method for encoding values of each \ASN.1 type as a string of octets.

\subsubsection{ASN.1 Keywords used in SNMP}
\label{sec:keywords}

Table~\vref{tab:keywords} lists some frequently used \ASN.1 keywords.
\begin{table}[hb]
  \begin{tabularx}{\linewidth}[t]{@{}>{\ttfamily}lY@{}}
    \toprule%
    \textbf{Keyword} & \textbf{Brief Description} \\
    \midrule%
    BEGIN & Start of an \ASN.1 module\\
    CHOICE & List of alternatives; used in defining \SMI{}v1 and
    \SMI{}v2 (\texttt{RFC1155-SMI} and \texttt{SNMPv2-SMI}) to define
    classes of datatypes (\texttt{SimpleSyntax} and
    \texttt{ApplicationSyntax}), and in \SMI{}v2. \\
    DEFINITIONS & Definition of a data type or managed object \\
    END & End of an \ASN.1 module \\
    EXPORTS & Data types that can be exported to other modules \\
    IDENTIFIER & A sequence of non-negative numbers \\
    IMPORTS & Data types defined in external modules that are used in
    this module \\
    INTEGER & A 32-bit integer (i.e., in the range $-2^{31}$ to
    $2^{31}-1$). \\
    MACRO & Required for defining macros, such as the
    \texttt{OBJECT-TYPE} macro defined in \texttt{RFC1155-SMI} \\
    OBJECT IDENTIFIER & Used to uniquely identify an
    object with an \OID \\
    OCTET & An eight-bit binary value, used with \texttt{STRING} \\
    OCTET STRING & A string of bytes \\
    OF & Used with \texttt{SEQUENCE} \\
    SEQUENCE & An ordered list of data, somewhat like a
    \texttt{struct} in the C language, usually used to represent a row
    in a table \\
    SEQUENCE OF & A table of data.  Somewhat like an array of
    \texttt{struct} in C \\
    STRING & used with \texttt{OCTET} for strings of binary bytes \\
    TYPE NOTATION & used in \texttt{MACRO} definitions to define the
    syntax of the new types \\
    VALUE NOTATION & used in \texttt{MACRO} definitions to define the
    syntax of the new values \\
    \bottomrule
  \end{tabularx}
  \caption{\ASN.1 Keywords.}
  \label{tab:keywords}
\end{table}

\subsubsection{ASN.1 Symbols and Operators}
\label{sec:asn.1-symbols}

Table~\vref{tab:symbols} lists the \ASN.1 symbols.
\begin{table}[htb]
  \begin{tabular}{@{}>{\ttfamily}ll@{}}
    \toprule%
    \textbf{Symbol} & \textbf{Meaning} \\
    \midrule%
    ::= & ``defined as'', or assignment \\
    \textbar & or, alternatives, options of a list \\
    - & signed number \\
    -- & introduces a comment \\
    \{ \} & start and end of a list \\
    {[ ]} & start and end of a tag \\
     ( ) & start and end of a subtype \\
    .. & range \\
    \bottomrule
  \end{tabular}
  \caption{The \ASN.1 symbols.}
  \label{tab:symbols}
\end{table}

\subsubsection{ASN.1 Data Types used in SNMP}
\label{sec:data-types}

There are three ``base types'' of data defined in \ASN.1 used in \SMI:
\texttt{INTEGER}, \texttt{OCTET STRING}, and \texttt{OBJECT IDENTIFIER}.

%% \subsection{What we are doing today}
%% \label{sec:today}

%% We will examine the specification for \texttt{mib-2}, on your machine
%% at
%% \texttt{/usr\allowbreak/share\allowbreak/snmp\allowbreak/mibs%
%%   \allowbreak/RFC1213-MIB.txt} and understand the structure of it.

\subsection{Syntax of a Managed Object Definition}
\label{sec:syntax-of-object-definition}

Every object definition in \SMI has the format:
\begin{alltt}
\emph{name} OBJECT-TYPE
    SYNTAX \emph{datatype}
    ACCESS \emph{either} read-only, read-write, write-only. \emph{or} not-accessible
    DESCRIPTION
        "Some text that describes this managed object."
    ::= \{ \emph{unique object ID that defines this object} \}
\end{alltt}
We will refer to this later in our activities.


\section{The MIB-II Definition}
\label{sec:mib-ii}

Here I will refer to my edited version of \texttt{RFC1213-MIB.txt},
available at
\url{http://nicku.org/snm/lectures/smi/RFC1213-MIB.txt}.  The
full specification  for \texttt{mib-2} is on your machine
at
\texttt{/usr\allowbreak/share\allowbreak/snmp\allowbreak/mibs%
  \allowbreak/RFC1213-MIB.txt}.
\begin{verbatim}
RFC1213-MIB DEFINITIONS ::= BEGIN

IMPORTS
        mgmt, NetworkAddress, IpAddress, Counter, Gauge,
                TimeTicks
            FROM RFC1155-SMI
        OBJECT-TYPE
                FROM RFC-1212;
\end{verbatim}
The first line defines the name of the \MIB, here
\texttt{RFC1213-MI}\@.  The format of this definition is always the
same.

The \texttt{IMPORTS} section of the \MIB is sometimes called the
\emph{linkage} section.  It lets you import definitions of datatypes and
\OID{}s from other \MIB{}s.  Here we get the definition of:
  \begin{itemize}
  \item \texttt{mgmt}
  \item \texttt{NetworkAddress}
  \item \texttt{IpAddress}
  \item \texttt{Counter}
  \item \texttt{Gauge}
  \item \texttt{TimeTicks}
  \end{itemize}
from \texttt{RFC1155-SMI}, the \MIB from the \RFC that defines
\SMI{}v1.

It also imports \texttt{OBJECT-TYPE} from \texttt{RFC-1212}, the
\emph{Concise MIB Definition}, which defines how \MIB files are written.
\begin{verbatim}
mib-2      OBJECT IDENTIFIER ::= { mgmt 1 }
\end{verbatim}
The line above says that the \OID of \texttt{mib-2} is 1.3.6.1.2.1.
\texttt{RFC1155-SMI} defines \texttt{mgmt} as the \OID 1.3.6.1.2.
\begin{verbatim}
-- groups in MIB-II

system       OBJECT IDENTIFIER ::= { mib-2 1 }
interfaces   OBJECT IDENTIFIER ::= { mib-2 2 }
at           OBJECT IDENTIFIER ::= { mib-2 3 }
ip           OBJECT IDENTIFIER ::= { mib-2 4 }
icmp         OBJECT IDENTIFIER ::= { mib-2 5 }
tcp          OBJECT IDENTIFIER ::= { mib-2 6 }
udp          OBJECT IDENTIFIER ::= { mib-2 7 }
egp          OBJECT IDENTIFIER ::= { mib-2 8 }
transmission OBJECT IDENTIFIER ::= { mib-2 10 }
snmp         OBJECT IDENTIFIER ::= { mib-2 11 }
\end{verbatim}
So here the \texttt{system} group is defines as the \OID
1.3.6.1.2.1.1, and so on.  A comment is a line starting with
\texttt{--}.
\begin{verbatim}
-- the Interfaces table

-- Implementation of the Interfaces group is mandatory for
-- all systems.

ifNumber OBJECT-TYPE
    SYNTAX  INTEGER
    ACCESS  read-only
    STATUS  mandatory
    DESCRIPTION
            "The number of network interfaces (regardless of
            their current state) present on this system."
    ::= { interfaces 1 }
\end{verbatim}
The \texttt{ifNumber} above tells how many entries there are in the
table.

\begin{verbatim}
-- The Interfaces table contains information on the entity's
-- interfaces.  Each interface is thought of as being
-- attached to a `subnetwork'.  Note that this term should
-- not be confused with `subnet' which refers to an
-- addressing partitioning scheme used in the Internet suite
-- of protocols.

ifTable OBJECT-TYPE
    SYNTAX  SEQUENCE OF IfEntry
    ACCESS  not-accessible
    STATUS  mandatory
    DESCRIPTION
            "A list of interface entries.  The number of
            entries is given by the value of ifNumber."
    ::= { interfaces 2 }
\end{verbatim}
This is the first managed object shown here.  \texttt{ifTable}
represents a table of network interfaces on a managed device.  Notice
that object names are defined with mixed case, the first letter is
lowercase.

Notice that this follows the format of an \texttt{OBJECT-TYPE} in
section~\vref{sec:syntax-of-object-definition}.

The \texttt{SYNTAX} of \texttt{ifTable} is \texttt{SEQUENCE OF
  IfEntry}\@.  The object is \texttt{not-accessible}, which means that
you cannot query the agent for the value of this object.  It has a
\texttt{STATUS} of \texttt{mandatory}, which means that if an agent
complies wiht the \acro{MIBB-II} specification, then it must implement
this object.  The \texttt{DESCRIPTION} tells you what this object is.
The unique \OID is 1.3.6.1.2.1.2.2, or
\texttt{iso.org.dod.internet.mgmnt.interfaces.2}.

  
Next, let's look at the \texttt{SEQUENCE} definition, which is used
with the \texttt{SEQUENCE OF} type in the \texttt{ifTable} definition.
\begin{verbatim}
IfEntry ::=
    SEQUENCE {
        ifIndex
            INTEGER,
        ifDescr
            DisplayString,
        ifType
            INTEGER,
        ifMtu
            INTEGER,
        ifSpeed
            Gauge,
        ifPhysAddress
            PhysAddress,
        ifAdminStatus
            INTEGER,
        ifOperStatus
            INTEGER,
        ifLastChange
            TimeTicks,
        ifInOctets
            Counter,
        ifInUcastPkts
            Counter,
        ifInNUcastPkts
            Counter,
        ifInDiscards
            Counter,
        ifInErrors
            Counter,
        ifInUnknownProtos
            Counter,
        ifOutOctets
            Counter,
        ifOutUcastPkts
            Counter,
        ifOutNUcastPkts
            Counter,
        ifOutDiscards
            Counter,
        ifOutErrors
            Counter,
        ifOutQLen
            Gauge,
        ifSpecific
            OBJECT IDENTIFIER
    }
\end{verbatim}
The name of the \texttt{SEQUENCE} (\texttt{IfEntry}) is mixed-case, but the
first letter is capitalised, which is different from the object
definition for \texttt{ifTable}.  A \texttt{SEQUENCE} is a list of
objects that go into one row of a table.  After this, we must have
\texttt{OBJECT-TYPE} definitions that define each of these variables.
A table can have any number of rows.  Tha agent manages the number of
rows.  An \NMS can also add rows to a table using a \emph{set}
operation.

\texttt{IfEntry} is the data type; rather like a \texttt{struct}
definition in the C language.

Let's look at \texttt{ifEntry}, the definition of what we find in the
table, the actual rows of the table themselves.  It looks almost the
same as the definition for \texttt{ifTable}, except that it has a new
clause, \texttt{INDEX}\@.  The index is a unique value that identifies
a single row in the table, like an array index.  A table is rather
like an array of \texttt{struct}s in C\@.  The agent assigns these
index values.  If a router has eight interfaces, then \texttt{ifTable}
will contain eight rows.
\begin{verbatim}
ifEntry OBJECT-TYPE
    SYNTAX  IfEntry
    ACCESS  not-accessible
    STATUS  mandatory
    DESCRIPTION
            "An interface entry containing objects at the
            subnetwork layer and below for a particular
            interface."
    INDEX   { ifIndex }
    ::= { ifTable 1 }
\end{verbatim}

Here we now look at the definition for \texttt{ifIndex}, the first
item in \texttt{IfEntry}\@.  Notice that indexes start from 1.
\begin{verbatim}
ifIndex OBJECT-TYPE
    SYNTAX  INTEGER
    ACCESS  read-only
    STATUS  mandatory
    DESCRIPTION
            "A unique value for each interface.  Its value
            ranges between 1 and the value of ifNumber.  The
            value for each interface must remain constant at
            least from one re-initialization of the entity's
            network management system to the next re-
            initialization."
    ::= { ifEntry 1 }
\end{verbatim}
This object is \texttt{read-only}, which means that you can see the
value, but not change it.

Here is the last object we look at from this table:
\begin{verbatim}
ifDescr OBJECT-TYPE
    SYNTAX  DisplayString (SIZE (0..255))
    ACCESS  read-only
    STATUS  mandatory
    DESCRIPTION
            "A textual string containing information about the
            interface.  This string should include the name of
            the manufacturer, the product name and the version
            of the hardware interface."
    ::= { ifEntry 2 }

END
\end{verbatim}
\texttt{ifDescr} is just a textual description of the interface.

The \MIB definition finishes with \texttt{END}\@.

%% \section{Questions}
%% \label{sec:questions}

%% \begin{enumerate}
%% \item Use the information above to get a copy of the Printer-MIB.
%% \item How many tables are there in the Printer-MIB?
%% \item The pagecount of pages printed by a printer is given by
%%   \texttt{prtMarkerLifeCount.1.1}, an entry in a table
%%   \begin{enumerate}
%%   \item What is the name of the table that this is part of?
%%   \item What is the \OID of the managed object that gives the pagecount?
%%   \end{enumerate}
%% \end{enumerate}


\subsection{Where can I get the standards documents from?}
\label{sec:standards}

The standard for \acro{SMI}v1 can be downloaded from
\url{ftp://ftp.rfc-editor.org/in-notes/rfc1155.txt}, and for |SMI{}v2
at \url{ftp://ftp.rfc-editor.org/in-notes/rfc2578.txt}.  The standards
for \acro{ASN}.1 and \acro{BER} can be downloaded from
\url{http://asn1.elibel.tm.fr/en/standards/}.

\end{document}