Subversion Repositories openrisc_2011-10-31

This is a port of UCD-SNMP-4.1.2

Originally this document said: See

http://ucd-snmp.ucdavis.edu/

for details.  And send them a postcard.

The project has since been renamed “net-snmp” and re-homed at

            http://net-snmp.sourceforge.net/

where various new releases (of the original, not eCos

ports) are available.

The original source base from which we worked to create the

eCos port is available from various archive sites such

as

            ftp://ftp.freesnmp.com/mirrors/net-snmp/

or

            ftp://sunsite.cnlab-switch.ch/mirror/ucd-snmp/

generally with this filename and details:

ucd-snmp-4.1.2.tar.gz. . . . . . Nov  2  2000   1164k

The SNMP/eCos package consists of two eCos packages;

the SNMP library and the SNMP agent.

The sources are arranged this way partly for consistency with

the original release from UCD, and so as to accommodate possible

future use of the SNMP library without having an agent present.

That could be used to build an eCos-based SNMP client application.

The library contains support code for talking SNMP over the

net - the SNMP protocol itself - and a MIB file parser (ASN-1) which

is not used in the agent case.

The agent contains the application specific handler files

to get information about the system into the SNMP world, together

with the SNMP agent thread

(snmpd in UNIX terms).

The standard set in MIB-II, together with the Ether-Like MIB, are supported

by default.  The MIB files used to compile the handlers in the agent and to

“drive” the testing (snmpwalk et

al under LINUX)

are those acquired from that same UCD distribution.

These are the supported MIBs; all are below mib2 == 1.3.6.1.2.1:

system        { mib2 1 }

interfaces    { mib2 2 }

              [ address-translation “at” { mib2 3 } is deprecated ]

ip            { mib2 4 }

icmp          { mib2 5 }

tcp           { mib2 6 }

udp           { mib2 7 }

              [ exterior gateway protocol “egp” { mib2 8 } not supported ]

              [ cmot { mib2 9 } is “historic”, just a placeholder ]

dot3          { mib2 10 7 } == { transmission 7 } “EtherLike MIB”

snmp          { mib2 11 }

On inclusion of SNMPv3 support packages, the following MIBs are added to the

default set of MIBs enumerated above :

snmpEngine    { snmpFrameworkMIBObjects 1 }  SNMP-FRAMEWORK-MIB, as described in

                                             RFC-2571 for support of SNMPv3

                                             framework.

usmStats      {           usmMIBObjects 1 }  SNMP-USER-BASED-SM-MIB, as

usmUser       {           usmMIBObjects 2 }  specified in RFC-2574 for support

                                             of user based security model in

                                             SNMPv3 management domains.

Small changes have been made in three areas:

Various hardware-specific ethernet drivers.

The generic ethernet device driver.

The OpenBSD TCP/IP networking package.

These changes were made in order to export information about the driver and

the network that the SNMP agent must report.  The changes were trivial in

the case of the network stack, since it was already SNMP-friendly.  The

generic ethernet device driver was re-organized to have an extensive header

file and to add a couple of APIs to extract statistics that the

hardware-specific device drivers keep within themselves.

There may be a performance hit for recording that data; disabling

a config option named something like

CYGDBG_DEVS_ETH_xxxx_xxxx_KEEP_STATISTICS

depending on the specific device driver will prevent that.

Not all platform ethernet device drivers export complete SNMP statistical

information; if the exported information is missing, SNMP will report zero

values for such data (in the dot3 MIB).

The interface chipset has an ID which is an OID; not all the latest greatest

devices are listed in the abailable database, so new chipsets may need to

be added to the client MIB, if not defined in those from UCD.

A routine to instantiate and start the SNMP agent thread in the default

configuration is provided in

PACKAGES/net/snmp/agent/VERSION/src/snmptask.c

It starts the snmpd thread at priority

CYGPKG_NET_THREAD_PRIORITY+1

by default, ie. one step less important than the TCP/IP stack service

thread.

It also statically creates and uses a very large stack of around 100

KiloBytes.

To use that convenience function, this code fragment may be copied (in

plain C).

#ifdef CYGPKG_SNMPAGENT

{

                extern void cyg_net_snmp_init(void);

                cyg_net_snmp_init();

}

#endif

In case you need to perform initialization, for example setting up SNMPv3

security features, when the snmp agent starts and every time it restarts,

you can register a callback function by simply writing the global variable:

externC void (*snmpd_reinit_function)( void );

with a suitable function pointer.

The entry point to the SNMP agent is

externC void snmpd( void (*initfunc)( void ) );

so you can of course easily start it in a thread of your choice at another

priority instead if required, after performing whatever other

initialization your SNMP MIBs need.  A larger than default stacksize is

required.  The initfunc parameter is the callback

function mentioned above — a NULL parameter there is safe and

obviously means no callback is registered.

Note that if you call snmpd(); yourself and do

not call cyg_net_snmp_init(); then

that routine, global variable, and the default large stack will not be

used.  This is the recommended way control such features from your

application; create and start the thread yourself at the appropriate

moment.

Other APIs from the snmpd module are available,

specifically:

void SnmpdShutDown(int a);

which causes the snmpd to restart itself —

including the callback to your init function — as soon as possible.

The parameter a is ignored.  It is there because in

snmpd's “natural environment” this routine

is a UNIX signal handler.

The helper functions in the network stack for managing

DHCP

leases will call SnmpdShutDown()

when necessary, for example if network interfaces go down and/or come up

again.

To use the SNMP agent, the SNMP library and agent packages must be

included in your configuration. To incorporate the stack into your

configuration select the SNMP library and SNMP agent packages in the

eCos Configuration Tool, or at the command line type:

$ ecosconfig add snmplib snmpagent

After adding the networking, common ethernet device drivers,

snmp library and snmp agent packages, there is no configuration

required. However there are a number of configuration options

that can be set such as some details for the System MIB, and

disabling SNMPv3 support (see below).

Starting the SNMP agent is not integrated into network

tests other than snmpping below, nor is it

started automatically in normal eCos startup -

it is up to the application to start the agent when it is ready,

at least after the network interfaces are both ‘up’.

The default build supports all three versions of the SNMP protocol, but without

any dispatcher functionality (rfc 2571, section 3.1.1.2). This has the

following implications :

 1. There is no community authentication for v1 and v2c.

2. Security provided by v3 can be bypassed by using v1/v2c protocol.

To provide the dispatcher with rfc 2571 type functionality, it is required to

set up security models and access profiles. This can be provided in the normal

Unix style by writing the required configurations in snmpd.conf

file. Application code may setup profiles in snmpd.conf and

optionally set the environment variable SNMPCONFPATH to

point to the file if it is not in the usual location. The whole concept works

in the usual way as with the standard UCD-SNMP distribution.

The support of the trapsink command in the

snmpd.conf file is not tested

and there may be problems for it working as expected. Moreover, in systems that do not

have filesystem support, there is no way to configure a trap-session in the

conventional way.

For reasons mentioned above, applications need to initialize their own trap

sessions and pass it the details of trap-sink. The following is a small sample

for initializing a v1 trap session :

typedef struct trap {

        unsigned char ip [4];

        unsigned int  port;

        unsigned char community [256];

}

trap            trapsink;

unsinged char   sink [16];

...

...

if (trapsink.ip != 0) {

        sprintf (sink, "%d.%d.%d.%d",

                 trapsink[0], trapsink[1], trapsink[2], trapsink[3]);

        if (create_trap_session (sink,

                trapsink.port,

                (char *)trapsink.community,

                SNMP_VERSION_1,

                SNMP_MSG_TRAP) == 0) {

                log_error ("Creation of trap session failed \n");

        }

}

Using snmpd.conf requires the inclusion of one of the file-system packages

(eg. CYGPKG_RAMFS) and CYGPKG_FILEIO. With these two packages included, the

SNMP sub-system will read the snmpd.conf file from the location specified in

SNMPCONFPATH, or the standard builtin locations, and use

these profiles. Only the profiles specified in the ACCESS-CONTROL

section of snmpd.conf file have

been tested and shown to work. Other profiles which have been implemented in

UCD-SNMP-4.1.2's snmpd.conf may not work

because the sole purpose of adding support for the snmpd.conf file has been to

set up ACCESS-CONTROL models.

At startup, the SNMP module tries to look for file snmp.conf.

If this file is not available, the module successively looks for files

snmpd.conf, snmp.local.conf and

snmpd.local.conf at the locations pointed to by 

SNMPCONFPATH environment variable. In case SNMPCONFPATH

 is not defined, the search sequence is carried out in default directories.

The default directories are :/usr/share/snmp, 

/usr/local/share/snmp and $(HOME)/.snmp.

The configurations read from these files are used to control both, SNMP

applications and the SNMP agent; in the usual UNIX fashion.

The inclusion of snmpd.conf support is enabled by default when suitable

filesystems and FILEIO packages are active.

Currently only one test program is provided which uses SNMP.

"snmpping" in the SNMP agent package runs the ping test from

the TCPIP package, with the snmpd running also. This allows you

to interrogate it using host tools of your choice. It supports MIBs

as documented above, so eg. snmpwalk

<hostname> public dot3 under

Linux/UNIX should have the desired effect.

For serious testing, you should increase the length of time

the test runs by setting CYGNUM_SNMPAGENT_TESTS_ITERATIONS

to something big (e.g., 999999). Build the test

(make -C net/snmp/agent/current tests)

and run it on the target.

Then start several jobs, some for pinging the board (to make

the stats change) and some for interrogating the snmpd. Set $IP

to whatever IP address the board has:

# in a root shell, for flood ping

while(1)

date

ping -f -c 3001 $IP

sleep 5

ping -c 32 -s 2345 $IP

end

# have more than one of these going at once

setenv MIBS all

while (1)

snmpwalk -OS $IP  public

date

end

Leave to run for a couple of days or so to test stability.

The test program can also test snmpd.conf support. It tries to build a minimal

snmpd.conf file on a RAM filesystem and passes it to the snmp sub-system. With

this profile on target, the following snmp[cmd] (cmd=walk, get, set) should

work :

snmp[cmd] -v1 $IP crux $OID

snmp[cmd] -v2 $IP crux $OID

snmp[cmd] -v3 $IP -u root -L noAuthNoPriv $OID

snmp[cmd] -v3 $IP -u root -L authNoPriv -A MD5 -a md5passwd $OID

The following commands would however fail since they violate the access model :

snmp[cmd] $IP public $OID

snmp[cmd] -v1 $IP public $OID

snmp[cmd] -v2c $IP public $OID

snmp[cmd] -v3 $IP -u no_user -L noAuthNoPriv $OID

snmp[cmd] -v3 $IP -u root -L authNoPriv -A MD5 -a badpasswd $OID

SNMP clients may use these packages, but this usage is currently

untested: the reason why this port to eCos exists is to acquire

the SNMP agent.  The fact that that the SNMP API (for clients) exists

is a side-effect.  See the standard man page SNMP_API(3)

for details.  There are further caveats below about client-side

use of the SNMP library.

All of the SNMP header files are installed beneath .../include/ucd-snmp

in the install tree.  The SNMP code itself assumes that directory

is on its include path, so we recommend that client code does the

same.  Further, like the TCP/IP stack, compiling SNMP code

requires definition of _KERNEL and __ECOS,

and additionally IN_UCD_SNMP_SOURCE.

Therefore, add all of these to your compile lines if you wish

to include SNMP header files:

-D_KERNEL

-D__ECOS

-DIN_UCD_SNMP_SOURCE=1

-I$(PREFIX)/include/ucd-snmp

Currently, the filesystem and persistent storage areas are

left undone, to be implemented by the application.

The SNMP library package is intended to support client and

agent code alike.  It therefore contains lots of assumptions about

the presence of persistent storage ie. a filesystem.  Currently,

by default, eCos has no such thing, so those areas have been simply

commented out and made to return empty lists or say “no

data here.”

Specifically the following files have omitted/unimplemented code :

PACKAGES/net/snmp/lib/VERSION/src/parse.c

contains code to enumerate MIB files discovered in the system

MIB directories (“/usr/share/snmp/mibs”),

and read them all in, building data structures that are used by

client programs to interrogate an agent.  This is not required in

an agent, so the routine which enumerates the directories returns

an empty list.

PACKAGES/net/snmp/lib/VERSION/src/read_config.c

contains two systems:

The first tries to read the configuration file as described in the

snmpd.conf file section and

the second system contains code to record persistent data as files in a

directory (typically /var/ucd-snmp) thus preserving the

state permanently.

The first part is partially implemented to support multiple profiles and enables

dispatcher functionality as discussed in .

The second part is not supported at all in the default implementation. As required,

a cleaner interface to permit application code to manage persistent data will be

developed in consultation with customers.

In the directory

          /snmp/agent/VERSION/utils/mib2c,

there are the following files:

README-eCos             notes about running with a nonstandard

                        perl path.

README.mib2c            the README from UCD; full instructions on

                        using mib2c

mib2c                   the perl program

mib2c.conf              a configuration file altered to include the

                        eCos/UCD

mib2c.conf-ORIG         copyright and better #include paths; and

                        the ORIGinal.

mib2c.storage.conf      other config files, not modified.

mib2c.vartypes.conf

mib2c is provided BUT it requires the SNMP perl package SNMP-3.1.0,

and that in turn requires perl nsPerl5.005_03 (part of

Red Hat Linux from 6.0, April 1999).

These are available from the CPAN (“the Comprehensive

Perl Archive Network”) as usual;

http://www.cpan.org/

and links from there. Specifically:

PERL itself:

http://people.netscape.com/kristian/nsPerl/

http://people.netscape.com/richm/nsPerl/nsPerl5.005_03-11-i686-linux.tar.gz

SNMP.pl

http://www.cpan.org/modules/01modules.index.html

http://cpan.valueclick.com/modules/by-category/05_Networking_Devices_IPC/SNMP/

http://www.cpan.org/authors/id/G/GS/GSM/SNMP.tar.gz

(note that the .tar.gz files are not browsable)

For documentation on the files produced, see the documentation

available at

http://ucd-snmp.ucdavis.edu/

in general, and file AGENT.txt in particular.

It is likely that the output of mib2c will be further customized

depending on eCos customer needs; it’s easy to do this

by editing the mib2c.conf file to add or remove whatever you need

with the resulting C sources.

The UCD autoconf-style configuration does not apply to eCos.

 So if you add a completely new MIB to the agent, and support it

using mib2c so that the my_new_mib.c file contains

a init_my_new_mib() routine to register

the MIB handler, you will also need to edit a couple of control

files; these claim to be auto-generated, but in the eCos release,

they’re not, don’t worry.

PACKAGES/net/snmp/agent/VERSION/include/mib_module_includes.h

contains a number of lines like

#include “mibgroup/mibII/interfaces.h”

so add your new MIB thus:

#include “mibgroup/mibII/my_new_mib.h”

PACKAGES/net/snmp/agent/VERSION/include/mib_module_inits.h 

contains a number of lines like

init_interfaces();

init_dot3(); 

and so on; add your new MIB as follows:

init_my_new_mib(); 

and this should work correctly.

&net-snmp-agent-snmp-manpages-sgml