=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>" in the config file).
=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.
=item *
Only enable the backend daemon and discovery jobs from I<either> Netdisco 1.x
I<or> App::Netdisco.
=back
=head1 2.036002
This is a bug fix release since 2.036000. Please also read the 2.036000
release notes below, in full. Notable changes:
=over 4
=item *
Device Port report is much faster when displaying nodes
=item *
C<netdisco-do psql> now supports C<NETDISCO_DBNAME> environment variable
=item *
C<snmp_auth> configuration now supports C<only> and C<no> ACLs per stanza
=item *
New Duplicate Devices Report in case you get these appearing
=item *
Neighbor L2 topology map will show sysName if DNS is not available
=item *
Speed up ACLs featuring regualr expressions
=back
Plus lots more mentioned in the Changes file.
=head1 2.036000
This release has many significant new features and changes. Please read all
the release notes before upgrading.
=over 4
=item *
A new setting C<host_groups> allows for creating named Access Control Lists
which can be referred to in other host groups or in any of the settings taking
an ACL.
=item *
The new setting C<device_identity> allows configuring rules to select the
interface to use as a canonical (friendly) identity of a device in Netdisco.
=item *
The new settings C<devices_no> and C<devices_only> are shorthand for setting
C<discover_*>, C<macsuck_*>, C<arpnip_*>, and C<nbtstat_*> at once.
=item *
Netdisco now tracks SNMP connect failures and after 10 failed attempts will
pause trying to connect, for one week (see the C<max_deferrals> and
C<retry_after> settings). See also the "SNMP Connect Failures" admin report.
=item *
Documentation and support for access control lists has been overhauled. Most
"C<*_no>", "C<*_only>", and "C<only>" settings will accept ACLs as single
items or lists. ACLs now support negation and OR/AND modifier options.
=item *
A new setting C<site_local_files> is a shorthand for confguring paths in which
to install local Perl, template, javascript, and images files for overriding
or enhancing Netdisco.
=item *
The topology import script (C<nd-import-topology>) will now queue a "discover"
job for each new device it imports.
=item *
The C<netdisco-daemon> and C<netdisco-daemon-fg> scripts have
been renamed to C<netdisco-backend> and C<netdisco-backend-fg> respectively.
The old commands will still work but we recommend packagers to use the new
names to remain consistent with documentation. Run the following on upgrade:
ln -s ~/perl5/bin/{localenv,netdisco-*} ~/bin/
~/bin/netdisco-daemon stop
~/bin/netdisco-backend restart
=item *
SSL library headers are required to build Netdisco now that we retrieve
support files via HTTPS.
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
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
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...).
=head1 2.032000
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
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
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
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
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
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
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
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
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
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
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
The previous mentioned bug in Macsuck is now fixed.
=head1 2.017000
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
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
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
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
You can now configure LDAP authentication for users.
=head1 2.012000
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
Users can be managed through the web interface (by admins only).
=head1 2.010000
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