App-Netsync
view release on metacpan or search on metacpan
=head1 NAME
App::Netsync - network/database synchronization utility/library
=begin HTML
<a href="https://travis-ci.org/dmtucker/netsync"><img src="https://img.shields.io/travis/dmtucker/netsync.svg" alt="Build Status"></a> <a href="https://metacpan.org/pod/App::Netsync"><img src="https://img.shields.io/cpan/v/App-Netsync.svg" alt="...
=end HTML
=head1 DESCRIPTION
netsync is a network synchronization tool that:
- maps network interfaces to their respective (potentially stacked) devices
- gathers interface-specific information from an asset management database
- sends the information it gathers to each device
- provides ways of producing useful information about the network
I<Note: All communication with network nodes is done using SNMP.>
B<Overview>
In a typical run, execution begins by parsing a configuration file (-c).
Next, Netsync searches for active network devices at each node.
Nodes may be specified by filename, DNS (-D), or the keyboard (STDIN).
Furthermore, nodes may be required to match a hostname pattern (-m).
Gathered information may be used to identify each device in a database.
A database may be specified using Database (-d) or DB in the configuration file.
Identified devices may then be updated (-u) with interface-specific information.
See F<doc/algorithm.svg> for corresponding visual guidance
(F</usr/share/netsync/algorithm.svg> after installation).
=head2 0 Installation
$ cpan App::Netsync
or
$ perl Makefile.PL
$ make
$ make test
$ make install
B<Modules>
=over 4
=item App::Netsync::Configurator
configuration file support
=item App::Netsync::Network
methods for manipulating network structures
=item App::Netsync::Scribe
I/O framework
=item App::Netsync::SNMP
SNMP framework
=back
=head2 1 Invocation
After installation, netsync may be invoked by name:
$ netsync
=item Cisco
=over 5
=item 1 portIfIndex
1.3.6.1.4.1.9.5.1.4.1.1.11
=item 2 portModuleIndex
1.3.6.1.4.1.9.5.1.4.1.1.1
=item 3 moduleSerialNumber
1.3.6.1.4.1.9.5.1.3.1.1.3
I<Note: moduleSerialNumberString (1.3.6.1.4.1.9.5.1.3.1.1.26) may be an alternate.>
=back
=item Brocade
=over 5
=item 1 snSwPortIfIndex
1.3.6.1.4.1.1991.1.1.3.3.1.1.38
=item 2 snSwPortDescr
1.3.6.1.4.1.1991.1.1.3.3.1.1.39
I<Note: Unit/Module/Interface (U/M/I) is assumed to map Unit to module IID.>
=item 3 snChasUnitSerNum
1.3.6.1.4.1.1991.1.1.1.4.1.1.2
=back
=back
=back
=head2 6 Probe Level 1
Probe Level 1 is specified using -p1 and updates Probe1Cache.
During Probe Level 1, only the discovery stage is executed.
It caches discovered nodes in Probe1Cache.
This cache is created in RFC1035-complaint format.
It may subsequently be passed as the Nodes parameter to skip inactive nodes.
$ netsync -Dm "sw[^.]+|hub[0-9]+" -p1
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using DBMS)... 480 nodes (10 skipped), 500 devices
$ netsync /var/cache/netsync/active.txt
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using /var/cache/netsync/active.txt)... 480 nodes, 500 devices
> identifying (using DBMS)... 498 synchronized (4 conflicts)
I<Note: Since the goal of Probe Level 1 is to save time later,
unrecognized nodes will not be included in Probe1Cache.>
=head2 7 Identification
Once netsync has a view of the network's hardware,
it requires a database to find information specific to each interface.
I<Note: Since netsync treats the database as read-only,
the table and fields must already be present in the database.>
The database may be provided one of two ways:
=over 3
=item DBMS
This must be preconfigured in the configuration file and on the DBMS.
=item Database (-d)
An RFC4180-compliant database file may be specified.
=back
netsync identifies the network interface referenced in each database entry.
A valid entry must not have missing DeviceField or InterfaceField information.
Valid rows are synchronized with the network while invalid rows are skipped.
Entries with unknown (not found) devices are skipped.
Entries are then checked for conflicts.
B<About RFC4180>
RFC4180 specifies a simple format (CSV) for database files.
This format is widely supported making it useful for importing and exporting.
Thus, for compatibility, this application is RFC4180-compliant.
DeviceField,InterfaceField,InfoField
A1B2C3D4E5F6,ethernet1/1/1,PoE Enabled
A1B2C3D4E5F6,ethernet1/2/1,Uplink
...
=head2 8 Synchronization
All conflicts are logged in ConflictLog and skipped.
B<Conflicts>
=over 3
=item Mismatch
This occurs when an InterfaceField value can't be found on an identified device.
=item Duplicate
This occurs when more than 1 entry for an interface exists in the database.
=item Unidentified
This occurs when hardware is found on the network but not in the database.
=back
=head2 9 Probe Level 2
Probe level 2 is specified using -p2 and updates Probe1Cache and Probe2Cache.
During Probe Level 2, only the discovery and identification stages are executed.
It caches identified nodes in Probe2Cache.
This cache is created in RFC4180-complaint format.
It may be passed as Nodes in subsequent runs to skip synchronization.
$ netsync -Dm "host[0-9]+" -a -p2
> configuring (using /etc/netsync/netsync.ini)... done
> discovering (using DNS)... 480 nodes (10 skipped), 500 devices
> identifying (using DBMS)... 498 synchronized (4 conflicts)
> Do you want to resolve conflicts now? [y/n] n
$ netsync -d /var/cache/netsync/synced.csv /var/cache/netsync/active.txt
> configuring (using /etc/netsync/netsync.ini)... done
> discovering (using /var/cache/netsync/active.txt)... 480 nodes, 500 devices
> identifying (using /var/cache/netsync/synced.csv)... 500 synchronized
I<Note: All unidentified hardware will be present in Probe2Cache.
This is so the output of Probe Level 2 can serve as a network snapshot.>
=head2 10 Updating
All modifications made to any device are logged in UpdateLog.
If probing is not used and the Update (-u) option is specified,
netsync attempts to actualize its internally synchronized network using SNMP.
It pushes gathered interface-specific information to the devices on the network.
This information is stored in the device at the specified SyncOID,
and is overwritten anytime netsync updates it.
$ netsync -Dau
=head1 EXAMPLES
$ netsync -Dm "sw[^.]+|hub[0-9]+" -au
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using DNS)... 780 nodes (50 skipped), 800 devices (10 stacks)
> identifying (using DBMS)... 670 synchronized (4 conflicts)
> updating... 670 successful
Z<>
$ dig axfr domain.tld | egrep ^(sw[^.]+|hub[0-9]+) | netsync -a
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using STDIN)... 780 nodes (50 skipped), 800 devices
> identifying (using DBMS)... 670 synchronized (4 conflicts)
Z<>
$ netsync -Dm "sw[^.]+|hub[0-9]+" -p1
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using DBMS)... 780 nodes (50 inactive), 800 devices
$ netsync /var/cache/netsync/active.txt
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using /var/cache/netsync/active.txt)... 780 nodes, 800 devices
> identifying (using DBMS)... 670 synchronized (4 conflicts)
Z<>
$ netsync -Dm "sw[^.]+|hub[0-9]+" -a -p2
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using DNS)... 780 nodes (50 skipped), 800 devices
> identifying (using DBMS)... 670 synchronized (4 conflicts)
$ netsync -d /var/cache/netsync/synced.csv /var/cache/netsync/active.txt
> configuring (using /etc/netsync/netsync.ini)...
> discovering (using /var/cache/netsync/active.txt)... 780 nodes, 800 devices
> identifying (using /var/cache/netsync/synced.csv)... 800 synchronized
=head1 AUTHOR
David Tucker, C<< <dmtucker at ucsc.edu> >>
=head1 BUGS
Please report any bugs or feature requests to C<bug-netsync at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Netsync>. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc App::Netsync
You can also look for information at:
=over 4
=item * RT: CPAN's request tracker (report bugs here)
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Netsync>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/App-Netsync>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/App-Netsync>
=item * Search CPAN
L<http://search.cpan.org/dist/App-Netsync/>
=back
=head1 LICENSE
Copyright 2013 David Tucker.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See L<http://dev.perl.org/licenses/> for more information.
=cut
( run in 0.594 second using v1.01-cache-2.11-cpan-39bf76dae61 )