new Troubleshooting documentation

Netdisco/Changes

@@ -1,3 +1,10 @@
+2.031004 - 2015-02-05
+
+  [ENHANCEMENTS]
+
+  * New Troubleshooting documentation
+  * Renamed --reset to --redeploy-all in netdisco-db-deploy
+
 2.031003 - 2015-02-04
 
   [NEW FEATURES]

Netdisco/MANIFEST

@@ -150,6 +150,7 @@ lib/App/Netdisco/Manual/Configuration.pod
 lib/App/Netdisco/Manual/Deployment.pod
 lib/App/Netdisco/Manual/Developing.pod
 lib/App/Netdisco/Manual/ReleaseNotes.pod
+lib/App/Netdisco/Manual/Troubleshooting.pod
 lib/App/Netdisco/Manual/WritingPlugins.pod
 lib/App/Netdisco/SSHCollector/Platform/ACE.pm
 lib/App/Netdisco/SSHCollector/Platform/BigIP.pm

Netdisco/bin/netdisco-db-deploy

@@ -50,7 +50,7 @@ netdisco-db-deploy - Database deployment for Netdisco
 
 This script upgrades or initialises a Netdisco database schema.
 
- ~netdisco/bin/netdisco-db-deploy [--reset]
+ ~netdisco/bin/netdisco-db-deploy [--redeploy-all]
 
 This script connects to the database and runs without user interaction. If
 there's no Nedisco schema, it is deployed. If there's an unversioned schema
@@ -63,7 +63,7 @@ name must match those configured in your environment YAML file (default
 C<~/environments/deployment.yml>).
 
 If you wish to force the redeployment of all database configuration, pass the
-C<--reset> argument on the command line.
+C<--redeploy-all> argument on the command line.
 
 =head1 VERSIONS
 
@@ -91,7 +91,7 @@ Version 17 onwards deploys schema upgrades for Netdisco 2
 
 my $schema = schema('netdisco');
 
-if (scalar @ARGV and $ARGV[0] and $ARGV[0] eq '--reset') {
+if (scalar @ARGV and $ARGV[0] and $ARGV[0] eq '--redeploy-all') {
     $schema->storage->dbh_do(
       sub {
         my ($storage, $dbh, @args) = @_;

Netdisco/lib/App/Netdisco.pm

@@ -56,9 +56,10 @@ See the demo at: L<http://netdisco2-demo.herokuapp.com/>
 =back
 
 If you have any trouble getting installed or running, check out the
-L<Deployment|App::Netdisco::Manual::Deployment> notes, or speak to someone in
+L<Deployment|App::Netdisco::Manual::Deployment> and
-the C<#netdisco> IRC channel (on freenode).  Before installing or upgrading
+L<Troubleshooting|App::Netdisco::Manual::Troubleshooting> notes, or speak to
-please always review the latest L<Release
+someone in the C<#netdisco> IRC channel (on freenode).  Before installing or
+upgrading please always review the latest L<Release
 Notes|App::Netdisco::Manual::ReleaseNotes>.
 
 =head1 Dependencies
@@ -190,7 +191,9 @@ daemon at the same time. Similarly, if you use the device discovery with
 Netdisco 2, disable your system's cron jobs for the Netdisco 1.x poller.
 
 For further documentation on deployment, see
-L<Deployment|App::Netdisco::Manual::Deployment>.
+L<Deployment|App::Netdisco::Manual::Deployment>. If you think Netdisco isn't
+behaving correctly, see also the
+L<Troubleshooting|App::Netdisco::Manual::Troubleshooting> page.
 
 =head1 Upgrading from 2.x
 
@@ -223,11 +226,14 @@ or MAC addreses, VLAN numbers, and so on.
 
 =head2 Command-Line Device and Port Actions
 
-To run a device (discover, etc) or port control job from the command-line, use
+Most significant Device jobs and Port actions, as well as several
-the bundled L<netdisco-do> program. For example:
+troubleshooting and housekeeping duties, can be performed at the command-ling
+with the L<netdisco-do> program. For example:
 
  ~/bin/netdisco-do -D discover -d 192.0.2.1
 
+See the L<netdisco-do documentation|netdisco-do> for further details.
+
 =head2 Import Topology
 
 Netdisco 1.x had support for a topology information file to fill in device

Netdisco/lib/App/Netdisco/Manual/Deployment.pod

@@ -152,18 +152,6 @@ You are instead recommended to run C<netdisco-web> behind a reverse proxy as
 described elsewhere in this document. Apache can easily act as an SSL reverse
 proxy.
 
-=head1 Debug Tricks
-
-You can see what HTTP Headers are received by Netdisco, and other information
-such as how it's parsing the config file, by enabling the Dancer debug plugin.
-First download the plugin:
-
- ~/bin/localenv cpanm --notest Dancer::Debug
-
-Then run the web daemon with the environment variable to enable the feature:
-
- DANCER_DEBUG=1 ~/bin/netdisco-web restart
-
 =head1 Database Backups
 
 We recommend you backup the Netdisco database regularly. You could put the
@@ -177,13 +165,6 @@ following commands into a shell script and call it nightly from C<cron>:
 This will keep 30 days of backups. You don't need to stop Netdisco during the
 backup.
 
-=head1 Database Schema Redeployment
-
-The database schema can be fully redeployed (even over an existing
-installation, in a safe way) using the following command:
-
- ~netdisco/bin/netdisco-db-deploy --reset
-
 =head1 Further Reading...
 
 Other ways to run and host the web application can be found in the

Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod

@@ -52,7 +52,7 @@ upgrade:
 The database schema can be fully redeployed (even over an existing
 installation, in a safe way) using the following command:
 
- ~netdisco/bin/netdisco-db-deploy --reset
+ ~netdisco/bin/netdisco-db-deploy --redeploy-all
 
 =head1 2.031002
 

Netdisco/lib/App/Netdisco/Manual/Troubleshooting.pod

@@ -0,0 +1,65 @@
+=head1 NAME
+
+App::Netdisco::Manual::Troubleshooting - Tips and Tricks for Troubleshooting
+
+=head1 Run a Polling Job with Debugging
+
+The C<netdisco-do> command has several debug flags which will show what's
+going on internally. Usually you always add C<-D> for general Netdisco
+debugging, then C<-I> for L<SNMP::Info> logging and C<Q> for SQL tracing. For
+example:
+
+ ~netdisco/bin/netdisco-do discover -d 192.0.2.1 -DIQ
+
+You will see that SNMPv2 community strings are hidden by default, to make the
+output safe for sending to Netdisco developers. To show the community string,
+set the C<SHOW_COMMUNITY> envinronment variable:
+
+ SHOW_COMMUNITY=1 ~netdisco/bin/netdisco-do discover -d 192.0.2.1 -DIQ
+
+=head1 Dump an SNMP object for a Device
+
+This is useful when trying to work out why some information isn't displaying
+correctly (or at all) in Netdisco. It may be that the SNMP response isn't
+understood. Netdisco can dump any leaf or table, by name:
+
+ ~netdisco/bin/netdisco-do show -d 192.0.2.1 -e interfaces
+ ~netdisco/bin/netdisco-do show -d 192.0.2.1 -e Layer2::HP::interfaces
+
+=head1 Interactive SQL terminal on the Netdisco Database
+
+Start an interactive terminal with the Netdisco PostgreSQL database. If you
+pass an SQL statement in the "-e" option then it will be executed.
+
+ ~netdisco/bin/netdisco-do psql
+ ~netdisco/bin/netdisco-do psql -e 'SELECT ip, dns FROM device'
+ ~netdisco/bin/netdisco-do psql -e 'COPY (SELECT ip, dns FROM device) TO STDOUT WITH CSV HEADER'
+
+The last example above is useful for sending data to Netdisco developers, as
+it's more compact and readable than the standard tabular output (second
+example).
+
+=head1 Database Schema Redeployment
+
+The database schema can be fully redeployed (even over an existing
+installation), in a safe way, using the following command:
+
+ ~netdisco/bin/netdisco-db-deploy --redeploy-all
+
+=head1 Debug HTTP Requests and Configuration
+
+You can see HTTP Headers received by Netdisco, and other information such as
+how it's parsing the config file, by enabling the Dancer debug plugin.  First
+download the plugin:
+
+ ~netdisco/bin/localenv cpanm --notest Dancer::Debug
+
+Then run the web daemon with the environment variable to enable the feature:
+
+ DANCER_DEBUG=1 ~/bin/netdisco-web restart
+
+A side panel appears in the web page with debug information. Be sure to turn
+this off when you're done (stop and start without the environment variable)
+otherwise secrets could be leaked to end users.
+
+=cut