The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Netdisco-2.005000_004
River stage one • 1 direct dependent • 1 total dependent
16 ++
/ App::Netdisco

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.

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). Before installing or upgrading please review the latest Release Notes.

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

The following is a general guide which works well in most circumstances. It assumes you have a user netdisco on your system, that you want to perform an on-line installation, and have the application run self-contained from within that user's home. There are alternatives: see the Deployment documentation for further details.

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 --verbose --local-lib ~/perl5 App::Netdisco

Link some of the newly installed apps into a handy location:

 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/deployment.yml ~/environments
 chmod +w ~/environments/deployment.yml

Edit the file and change the database connection parameters to match those for your local system (that is, the dsn, user and pass).

In the same file uncomment and edit the domain_suffix setting to be appropriate for your local site. Optionally, set the no_auth value to true if you wish to skip user authentication in the web interface.

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:

 ~/bin/netdisco-deploy

Startup

Run the following command to start the web-app server as a backgrounded daemon (listening on port 5000):

 ~/bin/netdisco-web start

Run the following command to start the job control daemon (port control, etc):

 ~/bin/netdisco-daemon start

You should take care not to run 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 --notest App::Netdisco
 ~/bin/netdisco-deploy
 ~/bin/netdisco-web restart

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.

User Rights

When user authentication is disabled (no_auth) the default username is "guest", which 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);

Deployment Scenarios

More documentation on how to deploy the application in other scenarios, for example behind a web proxy, is in the Deployment documentation.

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.