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

=head1 NAME

App::Netdisco::Manual::ReleaseNotes - Release Notes

=head1 Introduction

This document will list only the most significant changes with each release of
Netdisco. You are B<STRONGLY> recommended to read this document each time you
install and upgrade. Also see the Changes file, for more information.

=head1 Migrating from Netdisco 1.x

This distribution (App::Netdisco) is a complete rewrite of the Netdisco
application. Users often ask whether they can run both versions at the same
time, and whether the database must be copied. Here are the guidelines for
migrating from Netdisco 1.x:

=over 4

=item *

You can run both Netdisco 1.x and App::Netdisco web frontends at the same
time, using the same database (if "C<safe_password_store>" is set to
"C<false>").

=item *

Only enable the backend daemon and discovery jobs from I<either> Netdisco 1.x
I<or> App::Netdisco.

=item *

You can share a single database between Netdisco 1.x and App::Netdisco. The
deploy script for App::Netdisco will make some schema changes to the database,
but they are backwards compatible.

=back
=head1 2.036000

=head2 Health Advice

In this release the apps C<netdisco-daemon> and C<netdisco-daemon-fg> have
been renamed to C<netdisco-backend> and C<netdisco-backend-fg> respectively.

This better reflects the function of the two programs. If you still have
scripts using C<netdisco-daemon> or C<netdisco-daemon-fg> commands, they
should continue to work, as these apps still exist and simply exec() to the
new scripts on start.

However, it would be best if you replace any custom management config to
point to the new app names, going forward. Remember to do this on upgrade:

 ln -s ~/perl5/bin/{localenv,netdisco-*} ~/bin/

=head1 2.035007

=head2 General Notices

This release builds a Perl SSL interface which requires OpenSSL development
files (headers) on your system.

On Ubuntu/Debian:

 root:~# apt-get install libssl-dev

On Fedora/Red-Hat:

 root:~# yum install openssl-devel

On BSD these headers are usually installed with the openssl port itself.

Netdisco will otherwise fail to upgrade/install (it will fail building
L<IO::Socket::SSL> or L<Net::SSLeay>). If you get stuck or confused, you are
looking for the package including the file C<openssl/err.h>.

=head1 2.034000

=head2 General Notices

This release changes the way the application tracks web sessions for logged-in
users, from on-disk files, to encrypted browser cookies. As a result, on
upgrade (after running C<netdisco-deploy> and restarting C<netdisco-web>), all
users will need to log in again.

There may be a pause after restarting C<netdisco-web> as old web session files
on disk are purged.

=head1 2.032003

=head2 General Notices

The algorithm for selecting the canonical IP/name of a device has changed in
this release. No longer is the OSPF Router ID taken into account. The default
IP/name of a device will be either the IP specified for manual discovery, or
the IP reported to a neighbor port during automatic discovery. For the latter
you can often influence this through device configuration (LLDP advertise...).

=cut

# Via configuration there are two further settings. C<reverse_sysname> tells
# Netdisco to take the SNMP System Name and do a reverse DNS lookup for the
# canonical IP. The new configuration setting C<device_identity> allows you to
# set rules for picking the canonical interface from a device based on any of
# its properties (model, vendor, OS, OS version, etc).
#
# Typical use would be either to leave Netdisco to use the discovered IP, or use
# C<device_identity> to control the canonical IP/name for classes of device
# based on model/vendor, etc.

=head1 2.032000

=head2 General Notices

The identification of IP Phone hansets and Wireless APs is now configurable,
using the CDP/LLDP information from the device. See
L<documentation|App::Netdisco::Manual::Configuration> for:

 phone_capabilities
 phone_platforms
 wap_capabilities
 wap_platforms

=head1 2.031006

=head2 General Notices

When displaying device ports, Netdisco will now avoid showing VLAN Membership
if it looks like there are a large number of VLANs on many ports. This is an
average of the VLANs per port, configurable in C<devport_vlan_limit>. The
default is 150.

=head1 2.031005

=head2 General Notices

The C<netdisco-do> command's C<delete> option now uses the C<-p> parameter to
set node archive mode (previously it was a hack on C<-e>). For example:

 ~netdisco/bin/netdisco-do delete -d 192.0.2.1 -e 'older than the sun' -p yes

=head1 2.031003

=head2 Health Advice

This release will I<once again> remove from the database spurious Node
(workstation, printer, etc) entries on vlan 0, which were causing dupliate
entries in the web interface. We advise that you back up the database prior to
upgrade:

 /usr/bin/pg_dump -F c --create -f netdisco-pgsql.dump netdisco

=head2 General Notices

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 2.031002

=head2 General Notices

Netdisco web and backend daemons will now rotate their log files
("C<~netdisco/logs/netdisco-{web,daemon}.log>"). This happens when they reach
about 10MB in size and seven historical log files will be maintained in the
same directory. The first time this happens you may notice the daemons
restarting due to having to deal with the large initial logfile.

Two missing features from Netdisco 1 have been implemented: CLI device delete
and renumber (canonical IP change). They are available using the
C<netdisco-do> utility.

The Device Port Log comment feature from 2.030000 has been disabled as it is
incomplete, pending a review of how to handle authorization to the feature.

=head1 2.029014

=head2 General Notices

The node archiving behaviour of Netdisco 2 has until now been accidentally
different to that in Netdisco 1. This has now been fixed. See the new
"C<node_freshness>" configuration setting if you wish to revert or tune this
behaviour.

=head1 2.029010

=head2 General Notices

When upgrading you will encounter a current incompatibility between Netdisco
and one of its components. To work around this, issue the following command:

 ~/bin/localenv cpanm --notest --force Dancer@1.3126 DBIx::Class@0.08270

=head1 2.029008

=head2 General Notices

When upgrading you will encounter a current incompatibility between Netdisco
and one of its components. To work around this, issue the following command:

 ~/bin/localenv cpanm --notest --force Dancer@1.3126

=head1 2.029002

=head2 General Notices

The backend polling daemon has been rewritten and as a result your
configuration can be simplified. Some keys have also been renamed. Our advice
is to remove (or comment out) the complete C<workers> configuration which
enables auto-tuning.  If you do wish to control the number of worker
processes, follow this pattern:

 workers:
   tasks: 'AUTO * 2'  # this is the default, twice the number of CPUs

=head1 2.029001

=head2 Health Advice

This release will remove from the database spurious Node (workstation,
printer, etc) entries on vlan 0, which were causing dupliate entries in the
web interface. We advise that you back up the database prior to upgrade:

 /usr/bin/pg_dump -F c --create -f netdisco-pgsql.dump netdisco

=head2 General Notices

The configuration item C<reports> is now a list (used to be a dictionary).
Each item in the list must have a C<tag> entry which was previously the
dictionary key. For example, now use:

 reports:
   - tag: power_inventory
     category: Device
     label: 'Power Supply Inventory'
     columns:
       - {name: 'Name'}
       - {ps1_type: 'PS1 Type'}
       - {ps1_status: 'PS1 Status'}
     query: |
       SELECT d.name, d.ps1_type, d.ps1_status
         FROM device d
         WHERE d.ps1_type IS NOT NULL
       ORDER BY name

Old configuration will be continue to work, but we recommend you reconfigure
anyway.

=head1 2.028000

=head2 Incompatible Changes

The daemons can be started from init scripts, as root. They will drop back
from the root user to C<netdisco> before opening logs. However a limitation is
that the web frontend might temporarily keep root status to bind to a specific
port (e.g. 80) - the logs will then be created as root user. Sorry about that.

You might also find when upgrading that previous logs were owned by root and
Netdisco now wants to write to them as non-root (C<netdisco>) user. Please
either remove the logs before restarting, or alter their ownership.

Logs can be found in the C<logs> subdirectory of Netdisco's home area.

=head2 General Notices

The configuration item C<housekeeping> has been renamed to C<schedule>. Old
configuration will continue to work, but we recommend you now rename this key
in your configuration anyway.

=head1 2.025001

=head2 General Notices

The Web and Backend daemons (C<netdisco-web> and C<netdisco-daemon>
respectively) will now watch your C<deployment.yml> configuration file, and
restart themselves whenever it is changed.

The Web and Backend daemons will also now drop privilege to the same user and
group as their files on disk. This allows use of run control (init) scripts
whilst maintaining non-root privilege status (see
L<Deployment|App::Netdisco::Manual::Deployment> documentation for details).

The housekeeping task C<expiry> has been renamed to C<expire>. Old
configuration will continue to work, but we recommend you rename this part of
your C<housekeeping> configuration anyway.

=head1 2.023000

=head2 Incompatible Changes

This release will automatically migrate user passwords to have stronger
hashing in the database (a good thing!). This is incompatible with Netdisco
1.x web frontend, so if you must maintain backward-compatibility, set the
following in your C<deployment.yml> file:

 safe_password_store: false

=head2 General Notices

The number of parallel DNS queries running during node discovery has been
reduced to 10 for maximum safety, but resulting in lower macsuck performance.
If you have a robust DNS infrastructure, you can probably put it back up to
something like 50 or 100:

 dns:
  max_outstanding: 100

=head1 2.021000

=head2 Incompatible Changes

SNMP community strings provided in the C<community_rw> configuration setting
will I<no longer> be used for I<read> actions on a device (despite having
"C<rw>" in the setting name).

If you have the same community string for read and write access, then you must
set both C<community> and C<community_rw> in your C<deployment.yml> file. In
any case, we recommend using the new C<snmp_auth> configuration format which
supercedes both these settings.

=head2 Health Advice

This release includes support for Device and Node expiry from your database.
This is an important part of housekeeping for your installation, and our
recommendation is to enable this feature such that suitably old Devices and
Nodes are expired nightly.

Add the following to your "C<housekeeping>" configuration in
C<deployment.yml>, to have a nightly check at 11:20pm:

  housekeeping:
    expire:
      when: '20 23 * * *'

You should also configure one or more of C<expire_devices>, C<expire_nodes>,
and C<expire_nodes_archive> to a number of days. See the
L<Configuration|App::Netdisco::Manual::Configuration> documentation for
further details.

=head2 General Notices

If you use an Apache reverse proxy, we recomment increasing the timeout from
our previous example of 5 seconds to, perhaps 60. This is because some reports
do take more time to run their queries on the database. See
L<Deployment|App::Netdisco::Manual::Deployment> documentation for details.

=head1 2.020000

=head2 General Notices

If you were using the C<X::Observium> plugin, you'll now need to install
the separate distribution L<App::NetdiscoX::Web::Plugin::Observium>.

=head1 2.019000

=head2 General Notices

This release fixes a number of issues with the poller, and is a recommended
upgrade.

During Arpnip, Node IPs are resolved to DNS names in parallel. See the C<dns>
configuration option for details. Note that the C<nodenames> configuration
items from release C<2.018000> are no longer available.

This release includes new support for SNMPv3 via the C<snmp_auth>
configuration option. Please provide feedback to the developers on your
experience.

=head1 2.018000

=head2 General Notices

The previous mentioned bug in Macsuck is now fixed.

=head1 2.017000

=head2 General Notices

There is a bug in Macsuck whereby in rare circumstances some invalid SQL is
generated. The root cause is known but we want to take more time to get the
fix right. It should only be a few more days.

The C<no_port_control> configuration setting is now called C<check_userlog>
and its logic is inverted. Don't worry if this is not familiar to you - the
option is only used by Netdisco Developers.

=head1 2.016000

=head2 General Notices

The dangerous action log messages are now saved to the database. In a future
version there will be a way to display them in the web interface.

=head1 2.015000

=head2 Health Advice

Some of the "dangerous action" confirmation dialogs offer to take a log
message (e.g. Port Control, Device Delete). Currently the log messages are
B<not saved>. This feature will be added in the next release.

=head1 2.014000

=head2 General Notices

The backend poller daemon is now considered stable. You can uncomment the
C<housekeeping> section of the example configuration and thereby enable
regular device (re-)discovery, arpnip and macsuck.

=head1 2.013000

=head2 General Notices

You can now configure LDAP authentication for users.

=head1 2.012000

=head2 Security Notices

The read-write SNMP community is now stored in the database, when used for the
first time on a device. If you don't want the web frontend to be able to
access this, you need to:

=over 4

=item *

Have separate C<deployment.yml> files for web frontend and daemon, such that
only the daemon config contains any community strings.

=item *

Use separate PostgreSQL users for web frontend and daemon, such that the web
frontend user cannot SELECT from the C<community> DB table.

=back

=head1 2.011000

=head2 General Notices

Users can be managed through the web interface (by admins only).

=head1 2.010000

=head2 General Notices

You can now simplify database configuration to just the following, instead of
the more verbose C<plugins/DBIC> setting which was there before:

 database:
   name: 'netdisco'
   host: 'localhost'
   user: 'someuser'
   pass: 'somepass'

Also, the C<REMOTE_USER> environment variable and C<X-REMOTE_USER> HTTP Header
are now supported for delegating authentication to another web server. See the
Deployment and Configuration documentation for further details.

=head1 2.008000

=head2 Health Advice

This release contains the first version of our new poller, which handles
device and node discovery. Please make sure to backup any existing Netdisco
database before trying it out.

=head2 General Notices

You can remove any settings from C<~/environments/deployment.yml> which you
didn't edit or add to the file yourself. All defaults are now properly
embedded within the application.  See the new C<deployment.yml> sample which
ships with this distribution for an example.

=head1 2.006000

=head2 Incompatible Changes

The default environment configuration file C<develpment.yml> has been renamed
to C<deployment.yml>. This better reflects that users are not developers, and
also fits with the default for PSGI compatible cloud deployment services.

Please B<rename or copy> your environment file:

 mv ~/environments/development.yml ~/environments/deployment.yml

=head2 General Notices

The installation is now relocateable outside of a user's home directory by
setting the C<NETDISCO_HOME> environment variable. This defaults to your own
home directory.

=cut