lots of docs

Netdisco/bin/nd-dbic-versions

@@ -22,7 +22,7 @@ use Getopt::Long;
 
 nd-dbic-versions - Create DB Schema Versions for Netdisco
 
-=head2 USAGE
+=head1 USAGE
 
 This script creates SQL DDL files of the Netdisco database schema.
 
@@ -33,7 +33,7 @@ If called with the "-p <version>" option, upgrade SQL DDL command files
 are created between the specified version and the current DBIx::Class
 specification.
 
-=head2 New Version
+=head1 NEW VERSION
 
 =over 4
 

Netdisco/bin/nd-import-topology

@@ -23,11 +23,11 @@ use Try::Tiny;
 
 nd-import-topology - Import a Nedisco 1.x Manual Topology File
 
-=head2 USAGE
+=head1 USAGE
 
- ./nd-import-topology /path/to/netdisco-topology.txt
+ ~/bin/localenv nd-import-topology /path/to/netdisco-topology.txt
 
-=head2 DESCRIPTION
+=head1 DESCRIPTION
 
 This helper script will read and import the content of a Netdisco 1.x format
 Manual Topology file into the Netdisco 2.x database's C<topology> table.

Netdisco/bin/netdisco-db-deploy

@@ -21,7 +21,7 @@ use Try::Tiny;
 
 netdisco-db-deploy - Database deployment for Netdisco
 
-=head2 USAGE
+=head1 USAGE
 
 This script upgrades or initialises a Netdisco database schema.
 
@@ -35,7 +35,7 @@ interaction. If there's no Nedisco schema, it is deployed. If there's an
 unversioned schema then versioning is added, and updates applied.  Otherwise
 only necessary updates are applied to an already versioned schema.
 
-=head2 Versions
+=head1 VERSIONS
 
 =over 4
 

Netdisco/bin/netdisco-deploy

@@ -50,7 +50,7 @@ use Try::Tiny;
 
 netdisco-deploy - Database, OUI and MIB deployment for Netdisco
 
-=head2 USAGE
+=head1 USAGE
 
 This script deploys the Netdisco database schema, OUI data, and MIBs. Each of
 these is an optional service which the user is asked to confirm.

Netdisco/bin/netdisco-do

@@ -16,6 +16,71 @@ use App::Netdisco;
 use Dancer qw/:moose :script/;
 use Dancer::Plugin::DBIC 'schema';
 
+=head1 NAME
+
+netdisco-do - Run any Netdisco poller job from the command-line.
+
+=head1 USAGE
+
+ ~/bin/netdisco-do <action> [-D] [-d <device> [-p <port>] [-e <extra>]]
+
+Regardless of Netdisco configuration, debug level logging is enabled if the
+C<-D> flag is given.
+
+=head1 DESCRIPTION
+
+This program allows you to run any Netdisco poller job from the command-line.
+
+Note that some jobs (C<discoverall>, C<macwalk>, C<arpwalk>) simply add
+entries to the Netdisco job queue for other jobs, so won't seem to do much
+when you trigger them.
+
+=head1 ACTIONS
+
+=head2 discover
+
+Run a discover on the device (specified with C<-d>).
+
+=head2 macsuck
+
+Run a macsuck on the device (specified with C<-d>).
+
+=head2 arpnip
+
+Run an arpnip on the device (specified with C<-d>).
+
+=head2 set_location
+
+Set the SNMP location field on the device (specified with C<-d>). Pass the
+location string in the C<-e> extra parameter.
+
+=head2 set_contact
+
+Set the SNMP contact field on the device (specified with C<-d>). Pass the
+contact name in the C<-e> extra parameter.
+
+=head2 set_portname
+
+Set the description on a device port. Requires the C<-d> parameter (device),
+C<-p> parameter (port), and C<-e> parameter (description).
+
+=head2 set_portcontrol
+
+Set the up/down status on a device port. Requires the C<-d> parameter
+(device), C<-p> parameter (port), and C<-e> parameter ("up" or "down").
+
+=head2 set_vlan
+
+Set the native VLAN on a device port. Requires the C<-d> parameter (device),
+C<-p> parameter (port), and C<-e> parameter (VLAN number).
+
+=head2 set_power
+
+Set the PoE on/off status on a device port. Requires the C<-d> parameter
+(device), C<-p> parameter (port), and C<-e> parameter ("true" or "false").
+
+=cut
+
 info "App::Netdisco version $App::Netdisco::VERSION loaded.";
 
 use Try::Tiny;
@@ -52,6 +117,8 @@ if (!length $action) {
   with 'App::Netdisco::Daemon::Worker::Poller::Device';
   with 'App::Netdisco::Daemon::Worker::Poller::Arpnip';
   with 'App::Netdisco::Daemon::Worker::Poller::Macsuck';
+  with 'App::Netdisco::Daemon::Worker::Interactive::DeviceActions';
+  with 'App::Netdisco::Daemon::Worker::Interactive::PortActions';
 }
 my $worker = MyWorker->new();
 

Netdisco/lib/App/Netdisco.pm

@@ -183,9 +183,27 @@ or MAC addreses, VLAN numbers, and so on.
 When user authentication is disabled (C<no_auth>) the default username is
 "guest", which has no special privilege. To grant port and device control
 rights to this user, create a row in the C<users> table of the Netdisco
-database with a username of C<guest> and the C<port_control> flag set to true:
+database with a username of C<guest> and appropriate flags set to true:
 
- netdisco=> insert into users (username, port_control) values ('guest', true);
+ netdisco=> insert into users (username) values ('guest');
+ netdisco=> update users set port_control = true where username = 'guest';
+ netdisco=> update users set admin = true where username = 'guest';
+
+=head2 Command-Line Device and Port Actions
+
+To run a device (discover, etc) or port control job from the command-line, use
+the bundled L<netdisco-do> program. For example:
+
+ ~/bin/netdisco-do -D discover -d 192.0.2.1
+
+=head2 Import Topology
+
+Netdisco 1.x had support for a topology information file to fill in device
+port relations which could not be discovered. This is now stored in the
+database (and edited in the web interface). To import a legacy topology file,
+run:
+
+ ~/bin/localenv nd-import-topology /path/to/netdisco-topology.txt
 
 =head2 Deployment Scenarios
 
@@ -202,10 +220,8 @@ documentation for further information.
 
 =head2 Plugins
 
-App::Netdisco includes a Plugin subsystem for building the web user interface.
-Items in the navigation bar and the tabs on pages are loaded as Plugins, and
-you have control over their appearance and ordering. See
-L<App::Netdisco::Web::Plugin> for further information.
+App::Netdisco includes a Plugin subsystem for customizing the web user
+interface. See L<App::Netdisco::Web::Plugin> for further information.
 
 =head2 Developing
 

Netdisco/lib/App/Netdisco/Manual/Configuration.pod

@@ -273,10 +273,23 @@ Value: List of Strings. Default:
    - Control Plane Interface
    - SPAN (S|R)P Interface
    - StackSub
+   - netflow
+   - Vlan\d+-mpls layer
+   - BRI\S+-Bearer Channel
+   - BRI\S+-Physical
+   - BRI\S+-Signalling
+   - Embedded-Service-Engine\d+\/\d+
+   - Virtual-Template\d+
+   - Virtual-Access\d+
+   - (E|T)\d \d\/\d\/\d
+   - Vlan1
 
-If present, device ports matching any of the items in this list will be
-ignored by the discovery process. Note this may have side effects - connected
-devices and nodes on those ports will in turn also not be discovered.
+If present, device ports whose names match fully any of the items in this list
+will be ignored by the discovery process.
+
+Note this may have side effects - connected devices and nodes on those ports
+will in turn also not be discovered. Also note that backslashes must be
+doubled in the YAML format.
 
 =head3 C<ignore_private_nets>
 

Netdisco/share/config.yml

@@ -78,6 +78,24 @@ portctl_uplinks: 0
 portctl_nophones: 1
 portctl_vlans: 1
 
+ignore_interfaces:
+  - 'EOBC'
+  - 'unrouted VLAN'
+  - 'StackPort'
+  - 'Control Plane Interface'
+  - 'SPAN (S|R)P Interface'
+  - 'StackSub'
+  - 'netflow'
+  - 'Vlan\\d+-mpls layer'
+  - 'BRI\\S+-Bearer Channel'
+  - 'BRI\\S+-Physical'
+  - 'BRI\\S+-Signalling'
+  - 'Embedded-Service-Engine\\d+\\/\\d+'
+  - 'Virtual-Template\\d+'
+  - 'Virtual-Access\\d+'
+  - '(E|T)\\d \\d\\/\\d\\/\\d'
+  - 'Vlan1'
+
 # sleep time between polls of the database job queue
 daemon_sleep_time: 5
 

TODO

@@ -9,6 +9,7 @@ FRONTEND
 BACKEND
 =======
 
+* db connect params as separate settings
 * new DBIC multi-prefetch
 * PING from workers
 
@@ -20,16 +21,13 @@ CORE
 
 * VRF support
 * import legacy config file
-* deploy should drop mib files in mibhome
 * list of string settings should use index()
-* default ignore_interfaces
 
 DOCS
 ====
 
 * Scheduler
 * Discover/Refresh jobs
-* netdisco-do
 * new X:: plugin namespace
 * observiumsparklines plugin
 * port column plugins