some documentation fixes (#640)

* a few more files to ignore

* the pgtune we reference seems to be dead, provide
a few alternatives.

* steal pod syntax check from snmp::info, but don't bother with checking Test::Pod version.
we want 1.22 or later, which was released in 2005

* reference the release notes in our wiki. changes you need to make manually during upgrades are documented there.

* add pod test to manifest

* term was defined around line 111 and then again at line 209, rename the second one

MANIFEST

@@ -508,6 +508,7 @@ share/views/sidebar/search/device.tt
 share/views/sidebar/search/node.tt
 share/views/sidebar/search/port.tt
 xt/00-compile.t
+xt/01-local-pod.t
 xt/10-sort_port.t
 xt/11-portsort.t
 xt/20-checkacl.t

META.json

@@ -4,7 +4,7 @@
       "Oliver Gorwits <oliver@cpan.org>"
    ],
    "dynamic_config" : 1,
-   "generated_by" : "Module::Build version 0.4224",
+   "generated_by" : "Module::Build version 0.4229",
    "license" : [
       "bsd"
    ],
@@ -39,6 +39,7 @@
             "App::cpanminus" : "1.6108",
             "App::local::lib::helper" : "0.07",
             "Archive::Extract" : "0",
+            "Authen::Radius" : "0",
             "CGI::Expand" : "2.05",
             "DBD::Pg" : "0",
             "DBIx::Class" : "0.082841",
@@ -143,7 +144,7 @@
       },
       "App::Netdisco::DB" : {
          "file" : "lib/App/Netdisco/DB.pm",
-         "version" : "58"
+         "version" : "59"
       },
       "App::Netdisco::DB::ExplicitLocking" : {
          "file" : "lib/App/Netdisco/DB/ExplicitLocking.pm"
@@ -268,6 +269,9 @@
       "App::Netdisco::DB::Result::Virtual::GenericReport" : {
          "file" : "lib/App/Netdisco/DB/Result/Virtual/GenericReport.pm"
       },
+      "App::Netdisco::DB::Result::Virtual::LastNode" : {
+         "file" : "lib/App/Netdisco/DB/Result/Virtual/LastNode.pm"
+      },
       "App::Netdisco::DB::Result::Virtual::NodeIp4" : {
          "file" : "lib/App/Netdisco/DB/Result/Virtual/NodeIp4.pm"
       },
@@ -804,7 +808,7 @@
       },
       "homepage" : "http://netdisco.org/",
       "license" : [
-         "http://opensource.org/licenses/BSD-3-Clause"
+         "http://opensource.org/licenses/bsd-license.php"
       ],
       "repository" : {
          "url" : "https://github.com/netdisco/netdisco"
@@ -813,5 +817,5 @@
       "x_MailingList" : "https://lists.sourceforge.net/lists/listinfo/netdisco-users"
    },
    "version" : "2.042010",
-   "x_serialization_backend" : "JSON::PP version 2.97001"
+   "x_serialization_backend" : "JSON::PP version 4.02"
 }

META.yml

@@ -14,7 +14,7 @@ configure_requires:
   DBIx::Class: '0.082810'
   Module::Build: '0.42'
 dynamic_config: 1
-generated_by: 'Module::Build version 0.4224, CPAN::Meta::Converter version 2.150010'
+generated_by: 'Module::Build version 0.4229, CPAN::Meta::Converter version 2.150010'
 license: bsd
 meta-spec:
   url: http://module-build.sourceforge.net/META-spec-v1.4.html
@@ -38,7 +38,7 @@ provides:
     file: lib/App/Netdisco/Configuration.pm
   App::Netdisco::DB:
     file: lib/App/Netdisco/DB.pm
-    version: '58'
+    version: '59'
   App::Netdisco::DB::ExplicitLocking:
     file: lib/App/Netdisco/DB/ExplicitLocking.pm
   App::Netdisco::DB::Result::Admin:
@@ -121,6 +121,8 @@ provides:
     file: lib/App/Netdisco/DB/Result/Virtual/DuplexMismatch.pm
   App::Netdisco::DB::Result::Virtual::GenericReport:
     file: lib/App/Netdisco/DB/Result/Virtual/GenericReport.pm
+  App::Netdisco::DB::Result::Virtual::LastNode:
+    file: lib/App/Netdisco/DB/Result/Virtual/LastNode.pm
   App::Netdisco::DB::Result::Virtual::NodeIp4:
     file: lib/App/Netdisco/DB/Result/Virtual/NodeIp4.pm
   App::Netdisco::DB::Result::Virtual::NodeIp6:
@@ -483,6 +485,7 @@ requires:
   App::cpanminus: '1.6108'
   App::local::lib::helper: '0.07'
   Archive::Extract: '0'
+  Authen::Radius: '0'
   CGI::Expand: '2.05'
   DBD::Pg: '0'
   DBIx::Class: '0.082841'
@@ -556,7 +559,7 @@ resources:
   MailingList: https://lists.sourceforge.net/lists/listinfo/netdisco-users
   bugtracker: https://github.com/netdisco/netdisco/issues
   homepage: http://netdisco.org/
-  license: http://opensource.org/licenses/BSD-3-Clause
+  license: http://opensource.org/licenses/bsd-license.php
   repository: https://github.com/netdisco/netdisco
 version: '2.042010'
 x_serialization_backend: 'CPAN::Meta::YAML version 0.018'

bin/netdisco-deploy

@@ -71,7 +71,7 @@ these is an optional service which the user is asked to confirm.
 Pre-existing requirements are that there be a database table created and a
 user with rights to create tables in that database. Both the table and user
 name must match those configured in your environment YAML file (default
-C<~/environments/deployment.yml>).
+F<~/environments/deployment.yml>).
 
 This script will download the latest MAC address vendor prefix data from the
 Internet, and update the OUI table in the database. Hence Internet access is
@@ -80,10 +80,17 @@ required to run the script.
 Similarly the latest Netdisco MIB bundle is also downloaded and placed into
 the user's home directory (or C<$ENV{NETDISCO_HOME}>).
 
+If you upgrade Netdisco make sure you run this script again to make sure
+your config remains compatible.
+
+Before each upgrade also review the
+L<Release notes|https://github.com/netdisco/netdisco/wiki/Release-Notes> since
+additional steps might be required!
+
 =cut
 
 print color 'bold cyan';
-say 'This is the Netdisco II deployment script.';
+say 'This is the Netdisco 2 deployment script.';
 say '';
 say 'Before we continue, the following prerequisites must be in place:';
 say ' * Database added to PostgreSQL for Netdisco';
@@ -92,6 +99,11 @@ say ' * "~/environments/deployment.yml" file configured with Database dsn/user/p
 say ' * A full backup of any existing Netdisco database data';
 say ' * Internet access (for OUIs and MIBs)';
 say '';
+say 'If you are upgrading Netdisco 2 read the release notes:';
+say 'https://github.com/netdisco/netdisco/wiki/Release-Notes';
+say 'There you will find required and incompatible changes';
+say 'which are not covered by this script.';
+say '';
 say 'You will be asked to confirm all changes to your system.';
 say '';
 print color 'reset';
@@ -194,13 +206,13 @@ sub deploy_db {
 }
 
 sub get_userpass {
-  my $term = shift;
+  my $upterm = shift;
-  my $name = $term->get_reply(prompt => 'Username: ');
+  my $name = $upterm->get_reply(prompt => 'Username: ');
-  my $pass = $term->get_reply(prompt => 'Password: ');
+  my $pass = $upterm->get_reply(prompt => 'Password: ');
 
   unless ($name and $pass) {
     say 'username and password cannot be empty, please try again.';
-    ($name, $pass) = get_userpass($term);
+    ($name, $pass) = get_userpass($upterm);
   }
 
   return ($name, $pass);
@@ -257,7 +269,7 @@ sub deploy_oui {
   print color 'reset';
 }
 
-# This subroutine is baed on Wireshark's make-manuf
+# This subroutine is based on Wireshark's make-manuf
 # http://anonsvn.wireshark.org/wireshark/trunk/tools/make-manuf
 sub shorten {
     my $manuf = shift;

lib/App/Netdisco.pm

@@ -116,14 +116,25 @@ application:
 You may wish to L<amend the PostgreSQL
 configuration|https://github.com/netdisco/netdisco/wiki/Install-Tips#enable-md5-authentication-to-postgresql>
 so that local connections are working.  The default PostgreSQL configuration
-also needs tuning for modern server hardware. We recommend that you use the
+can also use tuning for modern server hardware. We recommend that you use one of the following
-C<pgtune> Python program to auto-tune your C<postgresql.conf> file:
+tools to tune your C<postgresql.conf> file:
 
 =over 4
 
-=item *
+=item L<postgresqltuner|https://github.com/jfcoz/postgresqltuner>
 
-L<https://github.com/elitwin/pgtune>
+Script that will check your operating system resources and settings as well as your
+running PostgreSQL database and will make recommendations based on actual load. Works
+on new netdisco installs but will make the best suggestions once the database contains
+a bigger dataset.
+
+=item L<pgtune (fork)|https://pgtune.leopard.in.ua>
+
+A web based application which will recommend which parameters to change.
+
+=item L<pgtune|https://github.com/elitwin/pgtune>
+
+Program to auto-tune your C<postgresql.conf>, regretfully not updated in a while.
 
 =back
 
@@ -230,7 +241,7 @@ If you're running a version of Netdisco prior to 2.x then you should follow
 the full installation instructions, above. This process is for upgrading
 version 2.x only.
 
-Before upgrading please review the latest L<Release Notes|https://github.com/netdisco/netdisco/wiki/Release-Notes>.
+Before upgrading always review the latest L<Release Notes|https://github.com/netdisco/netdisco/wiki/Release-Notes>.
 Then the process below should be run for each installation:
 
  # upgrade Netdisco
@@ -333,7 +344,7 @@ built upon.
 
 =head1 COPYRIGHT AND LICENSE
  
-This software is copyright (c) 2011-2018 by The Netdisco Developer Team.
+This software is copyright (c) 2011-2019 by The Netdisco Developer Team.
  
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are met:

xt/01-local-pod.t

@@ -0,0 +1,8 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use Test::More;
+use Test::Pod;
+
+all_pod_files_ok();