NAME

DESCRIPTION

Some of the things you can do with Netdisco:

• Locate a machine on the network by MAC or IP and show the switch port it lives at
• Turn off a switch port, or change the VLAN or PoE status of a port
• Inventory your network hardware by model, vendor, software and operating system
• Pretty pictures of your network

App::Netdisco provides a web frontend with built-in web server, and a backend daemon to gather information from your network, and handle interactive requests such as changing port or device properties.

• See the demo at: <https://netdisco2-demo.herokuapp.com/>
• Docker images <https://store.docker.com/community/images/netdisco/netdisco> are also available

We have several other pages with tips for installation tips <https://github.com/netdisco/netdisco/wiki/Install-Tips>, understanding and troubleshooting Netdisco <https://github.com/netdisco/netdisco/wiki/Troubleshooting>, notes for specific device vendors <https://github.com/netdisco/netdisco/wiki/Vendor-Tips>, and all the configuration options <https://github.com/netdisco/netdisco/wiki/Configuration>.

You can also speak to someone in the "#netdisco@freenode" IRC channel, or on the community email list <https://lists.sourceforge.net/lists/listinfo/netdisco-users>. Before installing or upgrading please always review the latest Release Notes <https://github.com/netdisco/netdisco/wiki/Release-Notes>.

Dependencies

On Ubuntu/Debian:

 root:~# apt-get install libdbd-pg-perl libsnmp-perl libssl-dev libio-socket-ssl-perl curl postgresql build-essential

On Fedora/Red-Hat:

 root:~# yum install perl-core perl-DBD-Pg net-snmp-perl net-snmp-devel openssl-devel curl postgresql-server postgresql-contrib make automake gcc
 root:~# postgresql-setup initdb
 root:~# systemctl start postgresql
 root:~# systemctl enable postgresql

On openSUSE:

 root:~# zypper refresh
 root:~# zypper install curl automake gcc make postgresql postgresql-server openssh openssl net-snmp perl perl-DBD-Pg perl-SNMP

On BSD systems please see our BSD tips <https://github.com/netdisco/netdisco/wiki/BSD-Install>.

With those installed, please check that your system's clock is correct.

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 (at least version 9.4) 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

You may wish to amend the PostgreSQL configuration <https://github.com/netdisco/netdisco/wiki/Install-Tips#enable-md5-authentication-to-postgresql> so that local connections are working. The default PostgreSQL configuration can also use tuning for modern server hardware. We recommend that you use one of the following tools to tune your "postgresql.conf" file:

postgresqltuner <https://github.com/jfcoz/postgresqltuner>

Script that will check your operating system resources and settings as well as your running PostgreSQL database and will make recommendations based on actual load. Works on new netdisco installs but will make the best suggestions once the database contains a bigger dataset.

pgtune (fork) <https://pgtune.leopard.in.ua>

A web based application which will recommend which parameters to change.

pgtune <https://github.com/elitwin/pgtune>

Program to auto-tune your "postgresql.conf", regretfully not updated in a while.

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 ("~/perl5"):

 su - netdisco
 curl -L https://cpanmin.us/ | perl - --notest --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 (it's just a test - you'll start the daemons properly, later on):

 ~/bin/netdisco-backend status

Configuration

 mkdir ~/environments
 cp ~/perl5/lib/perl5/auto/share/dist/App-Netdisco/environments/deployment.yml ~/environments
 chmod 600 ~/environments/deployment.yml

Edit the file (""~/environments/deployment.yml"") and change the database connection parameters to match those for your local system (that is, the "name", "user" and "pass").

In the same file uncomment and edit the "domain_suffix" setting to be appropriate for your local site. Change the "community" string setting if your site has different values.

Have a quick read of the other settings to make sure you're happy, then move on. See Configuration <https://github.com/netdisco/netdisco/wiki/Configuration> for further details.

Initialisation

 ~/bin/netdisco-deploy

If this is a new installation of Netdisco 2, answer yes to all questions. If you wish to deploy without Internet access, see the Deployment <https://github.com/netdisco/netdisco/wiki/Install-Tips> documentation.

Startup

 ~/bin/netdisco-web start

The web app listens on port 5000 (for example "http://localhost:5000/" or "http://yourhost.example.com:5000/").

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

 ~/bin/netdisco-backend start

First Run

Either go to the web interface and enter an IP or fully qualified domain name, OR perform the following step at the command line:

 ~/bin/netdisco-do discover -d {name or IP address of a switch or router}

Further Reading

You can also speak to someone in the "#netdisco@freenode" IRC channel, or on the community email list <https://lists.sourceforge.net/lists/listinfo/netdisco-users>. Before installing or upgrading please always review the latest Release Notes <https://github.com/netdisco/netdisco/wiki/Release-Notes>.

Upgrading from 2.x

 # upgrade Netdisco
 ~/bin/localenv cpanm --notest App::Netdisco
 ln -sf ~/perl5/bin/{localenv,netdisco-*} ~/bin/
 
 # apply database schema updates, update MIBs and Vendor MACs
 ~/bin/netdisco-deploy
 
 # restart web service (if you run it)
 ~/bin/netdisco-web restart
 
 # restart the backend workers (wherever you run them)
 ~/bin/netdisco-backend restart

Furthermore, whenever you upgrade your Operating System, you must delete the "~/perl5" directory and re-run the following command, to update Netdisco's C library bindings:

 curl -L https://cpanmin.us/ | perl - --notest --local-lib ~/perl5 App::Netdisco

Tips and Tricks

 ~/bin/netdisco-do -D discover -d 192.0.2.1

 ~/bin/localenv nd-import-topology /path/to/netdisco-topology.txt

AUTHOR

CONTRIBUTORS

Original development by Max Baker, with significant contributions from Mark Boolootian and Jim Warner (through whose ideas Netdisco was born and shaped), Bill Fenner, Jeroen van Ingen, Eric Miller, Carlos Vicente, and Brian de Wolf.

Other contributions (large and small) by Mike Hunter (UCB), Brian Wilson (NCSU), Bradley Baetz (bbaetz), David Temkin (sig.com), Edson Manners (FSU), Dmitry Sergienko (Trifle Co, .ua), Remo Rickli (PSI, Switzerland), Jean-Philippe Luiggi (sagem.com), A.L.M Buxey (Loughborough University, UK), Kevin Cheek (UMICH), John Bigrow (bnl.gov), George Pavel (llnl.gov), Charles Goldsmith (wokka.org), Douglas M. McKeown (saintmarys.edu), Revital Shvarzman (York U, Ontario), Walter Gould (Auburn U), Lindsay Druet and Colin Palmer (U of Waikato, Hamilton NZ), Dusty Hall (Auburn U), Jon Monroe (center pointe), Alexander Barthel, Bill Anderson, Alexander Hartmaier (t-systems.at), Justin Hunter (Arizona State U), Jethro Binks (U of Strathclyde, Glasgow), Jordi Guijarro (UAB.es), Sam Stickland (spacething.org), Stefan Radman (CTBTO.org), Clint Wise, Max Kosmach, Bernhard Augenstein and Nick Nauwelaerts (aquafin.be).

We probably forgot some names - sorry about that :-(.

Deep gratitude also goes to the authors and communities of all the other software that Netdisco is built upon.

COPYRIGHT AND LICENSE

 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.