From 97030ee42499ab94d8c8041d5573a54af7be5e27 Mon Sep 17 00:00:00 2001 From: Oliver Gorwits Date: Sun, 17 May 2015 21:44:03 +0100 Subject: [PATCH] Improve documentation for netdisco-sshcollector --- Netdisco/Changes | 1 + Netdisco/bin/netdisco-do | 2 +- Netdisco/bin/netdisco-sshcollector | 281 +++++++++++++++-------------- 3 files changed, 149 insertions(+), 135 deletions(-) mode change 100644 => 100755 Netdisco/bin/netdisco-sshcollector diff --git a/Netdisco/Changes b/Netdisco/Changes index 99f110de..1f62b09c 100644 --- a/Netdisco/Changes +++ b/Netdisco/Changes @@ -7,6 +7,7 @@ [ENHANCEMENTS] * Allow "hidden" option to reports config + * Improve documentation for netdisco-sshcollector [BUG FIXES] diff --git a/Netdisco/bin/netdisco-do b/Netdisco/bin/netdisco-do index 4c765b9b..8b17a7fc 100755 --- a/Netdisco/bin/netdisco-do +++ b/Netdisco/bin/netdisco-do @@ -455,7 +455,7 @@ L (net-snmp) trace level (1, 2 or 3). =item C<-Q> -L trace enabled. +L trace enabled =back diff --git a/Netdisco/bin/netdisco-sshcollector b/Netdisco/bin/netdisco-sshcollector old mode 100644 new mode 100755 index 033fea04..e958cc70 --- a/Netdisco/bin/netdisco-sshcollector +++ b/Netdisco/bin/netdisco-sshcollector @@ -1,141 +1,8 @@ #!/usr/bin/env perl -# vim: set expandtab tabstop=8 softtabstop=4 shiftwidth=4: - -=head1 NAME - -netdisco-sshcollector - Collect ARP data for Netdisco from devices without -full SNMP support - -=head1 DESCRIPTION - -Collects ARP data for Netdisco from devices without full SNMP support. -Currently, ARP tables can be retrieved from the following device classes: - -=over 4 - -=item * L - Cisco ACE (Application Control Engine) - -=item * L - F5 Networks BigIP - -=item * L - Cisco IOS - -=item * L - Cisco IOS XR - -=item * L - PaloAlto devices - -=back - -The collected arp entries are then directly stored in the netdisco database. - -=head1 CONFIGURATION - -The following should go into your Netdisco 2 configuration file, "C<< -~/environments/deployment.yml >>" - -=over 4 - -=item C - -Data is collected from the machines specified in this setting. The format is a -list of dictionaries. The keys C, C, C, and C -are required. Optionally the C key can be used instead of the -C. For example: - - sshcollector: - - ip: '192.0.2.1' - user: oliver - password: letmein - platform: IOS - - hostname: 'core-router.example.com' - user: oliver - password: letmein - platform: IOS - -Platform is the final part of the classname to be instantiated to query the -host, e.g. platform B will be queried using -C. - -If the password is "-", public key authentication will be attempted. - -=back - -=head1 ADDING DEVICES - -Additional device classes can be easily integrated just by adding and -additonal class to the C namespace. -This class must implement an C method which returns -an array of hashrefs in the format - - @result = ({ ip => IPADDR, mac => MACADDR }, ...) - -The parameter C<$ssh> is an active C connection to the host. -Depending on the target system, it can be queried using simple methods like - - my @data = $ssh->capture("show whatever") - -or automated via Expect - this is mostly useful for non-Linux appliances which -don't support command execution via ssh: - - my ($pty, $pid) = $ssh->open2pty or die "unable to run remote command"; - my $expect = Expect->init($pty); - my $prompt = qr/#/; - my ($pos, $error, $match, $before, $after) = $expect->expect(10, -re, $prompt); - $expect->send("terminal length 0\n"); - # etc... - -The returned IP and MAC addresses should be in a format that the respective -B and B datatypes in PostgreSQL can handle. - -=head1 DEPENDENCIES - -=over 4 - -=item L - -=item L - -=item L - -=back - -=head1 COPYRIGHT AND LICENSE - - Copyright (C) 2013 by the Netdisco Project - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of the Netdisco Project nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE NETDISCO DEVELOPER TEAM BE LIABLE FOR ANY - DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - Initial Version for Netdisco 1.x - Copyright (C) 2013 by Christian Ramseyer (ramseyer@netnea.com) - I hereby grant full ownership of the code to the Netdisco Project - -=cut - use warnings; use strict; -our $VERSION = 2.001000; our $home; BEGIN { @@ -183,6 +50,27 @@ use Module::Load (); use Net::OpenSSH; use MCE::Loop Sereal => 1; +use Getopt::Long; +Getopt::Long::Configure ("bundling"); + +my ($debug, $sqltrace) = (undef, 0); +my $result = GetOptions( + 'debug|D' => \$debug, + 'sqltrace|Q+' => \$sqltrace, +) or pod2usage( + -msg => 'error: bad options', + -verbose => 0, + -exitval => 1, +); + +my $CONFIG = config(); +$CONFIG->{logger} = 'console'; +$CONFIG->{log} = ($debug ? 'debug' : 'info'); +$ENV{DBIC_TRACE} ||= $sqltrace; + +# reconfigure logging to force console output +Dancer::Logger->init('console', $CONFIG); + #this may be helpful with SSH issues: #$Net::OpenSSH::debug = ~0; @@ -270,5 +158,130 @@ sub store_arpentries { } } -__END__ +=head1 NAME +netdisco-sshcollector - Collect ARP data for Netdisco from devices without +full SNMP support + +=head1 SYNOPSIS + + # install dependencies: + ~netdisco/bin/localenv cpanm --notest Net::OpenSSH Expect + + # run manually, or add to cron: + ~/bin/netdisco-sshcollector [-DQ] + +=head1 DESCRIPTION + +Collects ARP data for Netdisco from devices without full SNMP support. +Currently, ARP tables can be retrieved from the following device classes: + +=over 4 + +=item * L - Cisco ACE + +=item * L - Cisco ASA + +=item * L - F5 Networks BigIP + +=item * L - Cisco IOS + +=item * L - Cisco IOS XR + +=item * L - Linux + +=item * L - Palo Alto + +=back + +The collected arp entries are then directly stored in the netdisco database. + +=head1 CONFIGURATION + +The following should go into your Netdisco 2 configuration file, "C<< +~/environments/deployment.yml >>" + +=over 4 + +=item C + +Data is collected from the machines specified in this setting. The format is a +list of dictionaries. The keys C, C, C, and C +are required. Optionally the C key can be used instead of the +C. For example: + + sshcollector: + - ip: '192.0.2.1' + user: oliver + password: letmein + platform: IOS + - hostname: 'core-router.example.com' + user: oliver + password: letmein + platform: IOS + +Platform is the final part of the classname to be instantiated to query the +host, e.g. platform B will be queried using +C. + +If the password is "-", public key authentication will be attempted. + +=back + +=head1 ADDING DEVICES + +Additional device classes can be easily integrated just by adding and +additonal class to the C namespace. +This class must implement an C method which returns +an array of hashrefs in the format + + @result = ({ ip => IPADDR, mac => MACADDR }, ...) + +The parameter C<$ssh> is an active C connection to the host. +Depending on the target system, it can be queried using simple methods like + + my @data = $ssh->capture("show whatever") + +or automated via Expect - this is mostly useful for non-Linux appliances which +don't support command execution via ssh: + + my ($pty, $pid) = $ssh->open2pty or die "unable to run remote command"; + my $expect = Expect->init($pty); + my $prompt = qr/#/; + my ($pos, $error, $match, $before, $after) = $expect->expect(10, -re, $prompt); + $expect->send("terminal length 0\n"); + # etc... + +The returned IP and MAC addresses should be in a format that the respective +B and B datatypes in PostgreSQL can handle. + +=head1 DEBUG LEVELS + +The flags "C<-DQ>" can be specified, multiple times, and enable the following +items in order: + +=over 4 + +=item C<-D> + +Netdisco debug log level + +=item C<-Q> + +L trace enabled + +=back + +=head1 DEPENDENCIES + +=over 4 + +=item L + +=item L + +=item L + +=back + +=cut