diff --git a/Netdisco/Changes b/Netdisco/Changes index 464f9204..bde8186d 100644 --- a/Netdisco/Changes +++ b/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] diff --git a/Netdisco/MANIFEST b/Netdisco/MANIFEST index 079bfc45..aca60f52 100644 --- a/Netdisco/MANIFEST +++ b/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 diff --git a/Netdisco/bin/netdisco-db-deploy b/Netdisco/bin/netdisco-db-deploy index 5a3cef55..992d97de 100755 --- a/Netdisco/bin/netdisco-db-deploy +++ b/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) = @_; diff --git a/Netdisco/lib/App/Netdisco.pm b/Netdisco/lib/App/Netdisco.pm index cb8e366b..21d52427 100644 --- a/Netdisco/lib/App/Netdisco.pm +++ b/Netdisco/lib/App/Netdisco.pm @@ -56,9 +56,10 @@ See the demo at: L =back If you have any trouble getting installed or running, check out the -L notes, or speak to someone in -the C<#netdisco> IRC channel (on freenode). Before installing or upgrading -please always review the latest L and +L notes, or speak to +someone in the C<#netdisco> IRC channel (on freenode). Before installing or +upgrading please always review the latest L. =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. +L. If you think Netdisco isn't +behaving correctly, see also the +L 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 -the bundled L program. For example: +Most significant Device jobs and Port actions, as well as several +troubleshooting and housekeeping duties, can be performed at the command-ling +with the L program. For example: ~/bin/netdisco-do -D discover -d 192.0.2.1 +See the L for further details. + =head2 Import Topology Netdisco 1.x had support for a topology information file to fill in device diff --git a/Netdisco/lib/App/Netdisco/Manual/Deployment.pod b/Netdisco/lib/App/Netdisco/Manual/Deployment.pod index e208a952..6ef41f05 100644 --- a/Netdisco/lib/App/Netdisco/Manual/Deployment.pod +++ b/Netdisco/lib/App/Netdisco/Manual/Deployment.pod @@ -152,18 +152,6 @@ You are instead recommended to run C 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: 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 diff --git a/Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod b/Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod index e27c8846..619d74c4 100644 --- a/Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod +++ b/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 diff --git a/Netdisco/lib/App/Netdisco/Manual/Troubleshooting.pod b/Netdisco/lib/App/Netdisco/Manual/Troubleshooting.pod new file mode 100644 index 00000000..5a4ea42f --- /dev/null +++ b/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 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 logging and C 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 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