Tree [b5f1ed] 2.001000_001 /
History



File Date Author Commit
Netdisco 2013-01-06 Oliver Gorwits Oliver Gorwits [b5f1ed] bump version to test new scheme
.gitignore 2012-12-26 Oliver Gorwits Oliver Gorwits [c8e741] update gitignore to ignore build files
DEVELOPING.pod 2013-01-06 Oliver Gorwits Oliver Gorwits [040fb1] moar DEVELOPING docs
LICENCE 2012-01-13 Oliver Gorwits Oliver Gorwits [0ba97a] add licence, readme and disable dns col in node_ip
README.txt 2013-01-06 Oliver Gorwits Oliver Gorwits [dbb2cb] update TODO README and Changes
TODO 2013-01-06 Oliver Gorwits Oliver Gorwits [dbb2cb] update TODO README and Changes

Read Me

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).

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 nedisco

    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:

     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

Tips and Tricks
    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.

    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

    Other ways to run and host the web application can be found in the
    Dancer::Deployment page. See also the plackup documentation.

    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);

Future Work
    Bundled with this app is a DBIx::Class layer for the Netdisco database.
    This could be a starting point for an "official" DBIC layer. Helper
    functions and canned searches have been added to support the web
    interface.

    The intention is to support "plugins" for additonal features, most
    notably columns in the Device Port listing, but also new menu items and
    tabs. The design of this is sketched out but not implemented. The goal
    is to avoid patching core code to add localizations or less widely used
    features.

Caveats
    Some sections are not yet implemented, e.g. the *Device Module* tab.

    Menu items on the main black navigation bar go nowhere, except Home.

    None of the Reports yet exist (e.g. searching for wireless devices, or
    duplex mismatches). These might 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.