view release on metacpan or  search on metacpan

lib/Alien/SNMP.pm  view on Meta::CPAN

Three kinds of user need that.

=over

=item Anyone installing outside the system perl

The Perl modules in a distribution's C<net-snmp> package are built for the
system perl and installed into system directories, so under perlbrew,
L<local::lib>, or any C<INSTALL_BASE> prefix they are simply not on C<@INC>.
This distribution builds them with the perl that is running the build and
installs them wherever that perl's install target points. See
L</BUNDLED PERL MODULES>.

=item Anyone parsing large MIB collections

Older Net-SNMP had fixed ceilings in the MIB parser: a maximum number of
Textual Conventions, and a maximum number of imports per module. Large vendor
MIB collections reached them, which is why patched Net-SNMP builds were once
needed for MIB development. Both limits are gone as of Net-SNMP 5.9, where the
Textual Convention list grows on demand and C<MAX_IMPORTS> is 512. A stock
build from this distribution needs no patching for that work.

=item Anyone shelling out to the Net-SNMP tools

The command line utilities are built here too, from the same source, and can be
put ahead of the system ones on C<PATH>. See L</COMMAND LINE UTILITIES>.

=back

=head1 BUNDLED PERL MODULES

The Net-SNMP source ships the C<SNMP> and C<NetSNMP::*> XS modules. They are
built against the library built here, by the same perl that is building this
distribution, and are installed along with it. A bare C<use SNMP;> therefore
works, and they follow whatever installation target you give L<Alien::SNMP>
itself (C<INSTALL_BASE>, C<PREFIX>, C<DESTDIR>, L<local::lib>).

They resolve C<libnetsnmp> from this Alien's share dir, so they coexist with an
operating system C<net-snmp> package: system tools keep using the system
library, while these modules use ours. That is arranged two ways: Net-SNMP bakes
the share dir into the XS modules' run-path, and this module additionally
preloads the share copy at use-time. Note that the run-path is emitted as
C<DT_RUNPATH>, which C<LD_LIBRARY_PATH> takes precedence over; the preload is
what makes the choice robust in that case.

On macOS the mechanism differs but the outcome does not: the XS modules record
C<libnetsnmp> by its absolute path in the installed share dir, so that is the
copy they load.

=head2 Shadowing an operating system packaged SNMP.pm

Some operating systems ship Net-SNMP's Perl modules as a package of their own,
installed into the system perl's vendor directories. Installing L<Alien::SNMP>
into that same perl, which is what happens when it is installed as root outside
perlbrew or L<local::lib>, puts our copy in the site directories. Those precede
the vendor ones in C<@INC>, so ours answers C<use SNMP;> for every script that
perl runs.

Nothing is overwritten. The two copies live in different directories, and
removing L<Alien::SNMP> brings the operating system packaged one back. But the
substitution is silent, and our copy looks in different places than the
operating system packaged one did:

=over

=item MIB files

The operating system packaged module searches the system MIB directory, usually
F</usr/share/snmp/mibs>. Ours does not. See L</MIBS>.

=item F<snmp.conf>

The operating system packaged module reads F</etc/snmp/snmp.conf>, where a site
keeps defaults such as C<defVersion>, C<defCommunity>, C<mibdirs> and C<mibs>.
Ours reads F<snmp.conf> from its own share directory and from F<~/.snmp>, never
from F</etc/snmp>, so those defaults stop applying. Set C<SNMPCONFPATH> to the
directories you want searched to get them back.

=back

Neither change reports anything: symbolic names quietly stop resolving and site
defaults quietly stop being read. Installing into a perlbrew or L<local::lib>
perl raises neither question, because nothing is shadowed.

=head1 MIBS

No MIB files are shipped, because Net-SNMP is configured here with
C<--disable-mibs> and C<--with-mibs="">. Out of the box both the Perl modules
and the command line tools work in numeric OIDs, and C<snmptranslate> reports
C<Cannot find module>.

The system MIB directory is not consulted either. The default search path is
F<~/.snmp/mibs> plus a directory inside this distribution's share, and nothing
else, whatever the operating system may have installed elsewhere.

That is a matter of supplying MIBs, not a missing capability. Symbolic names
resolve normally, in both directions, once a collection is on the search path.
Put one there with the C<-M> option or the C<MIBDIRS> environment variable, or
place files in F<~/.snmp/mibs>, which is on the default path:

 $ MIBDIRS=/path/to/mibs snmptranslate .1.3.6.1.2.1.1.3.0
 SNMPv2-MIB::sysUpTime.0

From Perl, C<SNMP::addMibDirs> and C<SNMP::loadModules> do the same job. Either
way that covers the modules Net-SNMP loads by default; anything outside that
list also needs naming, with C<-m> or the C<MIBS> environment variable.

=head2 The MIB index files are gone

Net-SNMP 5.9 removed the on-disk MIB index cache. It no longer writes or reads
the C<.index> files older versions left inside MIB directories, nor the numbered
files under C<SNMP_PERSISTENT_DIR>, and that variable now has no bearing on MIB
indexing at all. Parsing is unaffected: C<snmptranslate>, C<SNMP::addMibDirs>
and C<SNMP::loadModules> behave as they always did, and directories are simply
rescanned each run instead of being read from a cache.

What is gone is any way to ask Net-SNMP B<which file defines a given module>.
It still tracks that internally but exposes no accessor, so code that located a
module's file by reading an index directory will find nothing there. Derive the
mapping from the files instead, following Net-SNMP's own rule from
C<add_mibfile()> in F<snmplib/parse.c>: a file defines a module when its first