NAME
App::Netdisco - An open source web-based network management tool.
Introduction
The content of this distribution is the next major version of the
Netdisco network management tool. Pieces are still missing however, so
if you're a new user please see <http://netdisco.org/> for further
information on the project and how to download the current official
release.
* See the demo at: <http://demo-ollyg.dotcloud.com/netdisco/>
App::Netdisco provides a web frontend and a backend daemon to handle
interactive requests such as changing port or device properties. There
is not yet a device poller, so please still use the old Netdisco's
discovery, arpnip, and macsuck.
If you have any trouble getting the frontend running, speak to someone
in the "#netdisco" IRC channel (on freenode).
Dependencies
Netdisco has several Perl library dependencies which will be
automatically installed. However it's *strongly* recommended that you
first install DBD::Pg and SNMP using your operating system packages. The
following commands will test for the existence of them on your system:
perl -MDBD::Pg\ 999
perl -MSNMP\ 999
With those two installed, we can proceed...
Create a user on your system called "netdisco" if one does not already
exist. We'll install Netdisco and its dependencies into this user's home
area, which will take about 250MB including MIB files.
root:~# useradd -m -p x -s /bin/bash netdisco
Netdisco uses the PostgreSQL database server. Install PostgreSQL and
then change to the PostgreSQL superuser (usually "postgres"). Create a
new database and PostgreSQL user for the Netdisco application:
root:~# su - postgres
postgres:~$ createuser -DRSP netdisco
Enter password for new role:
Enter it again:
postgres:~$ createdb -O netdisco netdisco
Installation
To avoid muddying your system, use the following script to download and
install Netdisco and its dependencies into the "netdisco" user's home
area ("~netdisco/perl5").
su - netdisco
curl -L http://cpanmin.us/ | perl - --notest --quiet \
--local-lib ~/perl5 \
App::cpanminus App::local::lib::helper App::Netdisco
Link some of the newly installed apps into the "netdisco" user's $PATH,
e.g. "~netdisco/bin":
mkdir ~/bin
ln -s ~/perl5/bin/{localenv,netdisco-*} ~/bin/
Test the installation by running the following command, which should
only produce a status message (and throw up no errors):
~/bin/netdisco-daemon status
Configuration
Make a directory for your local configuration and copy the configuration
template from this distribution:
mkdir ~/environments
cp ~/perl5/lib/perl5/auto/share/dist/App-Netdisco/environments/development.yml ~/environments
chmod +w ~/environments/development.yml
Edit the file and change the database connection parameters to match
those for your local system (that is, the "dsn", "user" and "pass").
Optionally, in the same file uncomment and edit the "domain_suffix"
setting to be appropriate for your local site.
Bootstrap
The database either needs configuring if new, or updating from the
current release of Netdisco (1.x). You also need vendor MAC address
prefixes (OUI data) and some MIBs if you want to run the daemon. The
following script will take care of all this for you:
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-deploy
If you don't want that level of automation, check out the database
schema diff from the current release of Netdisco, and apply it yourself:
~/perl5/lib/perl5/App/Netdisco/DB/schema_versions/App-Netdisco-DB-2-3-PostgreSQL.sql
Startup
Run the following command to start the web-app server as a daemon (port
5000):
DANCER_ENVDIR=~/environments ~/bin/netdisco-web start
Run the following command to start the job control daemon (port control,
etc):
DANCER_ENVDIR=~/environments ~/bin/netdisco-daemon start
You should (of course) avoid running this Netdisco daemon and the legacy
daemon at the same time.
Upgrading
Simply install this module again, then upgrade the database schema:
~/bin/localenv cpanm --quiet --notest App::Netdisco
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-deploy
Tips and Tricks
Searching
The main black navigation bar has a search box which is smart enough to
work out what you're looking for in most cases. For example device
names, node IP or MAC addreses, VLAN numbers, and so on.
SQL and HTTP Trace
For SQL debugging try the following commands:
DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
DANCER_ENVDIR=~/environments ~/bin/localenv plackup ~/bin/netdisco-web-fg
DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
DANCER_ENVDIR=~/environments ~/bin/localenv netdisco-daemon-fg
Deployment
Other ways to run and host the web application can be found in the
Dancer::Deployment page. See also the plackup documentation.
User Rights
With the default configuration user authentication is disabled and the
default "guest" user has no special privilege. To grant port and device
control rights to this user, create a row in the "users" table of the
Netdisco database with a username of "guest" and the "port_control" flag
set to true:
netdisco=> insert into users (username, port_control) values ('guest', true);
Database API
Bundled with this distribution is a DBIx::Class layer for the Netdisco
database. This abstracts away all the SQL into an elegant, re-usable OO
interface. See the App::Netdisco::Developing documentation for further
information.
Plugins
App::Netdisco includes a Plugin subsystem for building the web user
interface. Items in the navigation bar and the tabs on pages are loaded
as Plugins, and you have control over their appearance and ordering. See
App::Netdisco::Web::Plugin for further information.
Developing
Lots of information about the architecture of this application is
contained within the App::Netdisco::Developing documentation.
Caveats
Some sections are not yet implemented, e.g. the *Device Module* tab.
Some menu items on the main black navigation bar go nowhere.
None of the Reports yet exist (e.g. searching for wireless devices, or
duplex mismatches). These will be implemented as a plugin bundle.
The Wireless, IP Phone and NetBIOS Node properies are not yet shown.
AUTHOR
Oliver Gorwits <oliver@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 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:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Netdisco Project nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE NETDISCO DEVELOPER TEAM BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.