514 lines
16 KiB
Plaintext
514 lines
16 KiB
Plaintext
=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
|