Netdisco INSTALL -- Instructions for setting up Netdisco application.
Netdisco 0.94
PLEASE check the latest version of this document at http://netdisco.org/install.html in case of bugs.
Created by Max Baker.
See list at the end of README of all the contributors.
Netdisco was created at the University of California, Santa Cruz (UCSC), Networking and Technology Services (NTS) department. UCSC continues to support the development of Netdisco by providing development servers and financial support.
Netdisco is an Open Source project hosted by Source Forge.
Please use the netdisco-users mailing list for all help, problems and comments.
Developers, patches, and ideas are always welcome.
http://lists.sourceforge.net/lists/listinfo/netdisco-users
Please use the Bug interface from Source Forge page at :
http://sourceforge.net/projects/netdisco
Netdisco is built using lots of fine Open-Source tools:
5.8.1 on Mandrake 9.x may be a problem (if you get
an out of memory error, you may need to change to
5.6.1 or 5.8.3+).
Reported working for versions 7.2, 7.3, 7.4
Do not install version 1.99.
See INSTALL below for details on how to retrieve and install each one.
Netdisco was developed on a FreeBSD system but should work on any system that Postgres, Perl, Apache, and Net-SNMP run on.
Linux is a sure bet. Netdisco has been tested with Mandake 9.1 and includes specific notes to install with it. Successful installs have been reported under Redhat, Mandrake, Gentoo and Debian.
One user has reported getting Netdisco running on OS X.
Windows will take a lot of massaging but should be possible under Cygwin.
This is not a terribly easy install. If you aren't comfortable installing programs from source and using a text editor, get some help. Hopefully this will all be rolled up into an install script by the time Netdisco hits version 1.0.
Get the newest version from http://www.netdisco.org.
tar xvfz netdisco-x.xx.tar.gz
Create a directory for Netdisco
mkdir /usr/local/netdisco
Move files to that dir
mv netdisco-x.xx/* /usr/local/netdisco
If you plan to install to a directory other than /usr/local/netdisco then you must
change a couple files. Otherwise Skip down to Number 2.
sql/pg_run
sql/pg_init
sql/pg_back
bin/netdisco_daemon
home option in netdisco.conf.
/usr/local/netdisco in netdisco_apache.conf
to match your new directory.
/usr/local/netdisco in netdisco_apache_dir.conf
to match your new directory.
Create a user and group named netdisco
useradd -d /usr/local/netdisco netdisco
adduser netdisco
Give this user permission to the files:
chown -R netdisco.netdisco /usr/local/netdisco
Once Netdisco is up and running most administration can be done from the Web interface. Whoever will be doing the back-end administration will need to have write access and will need write access on Netdisco's files.
Add the unix account names of administrators that will modify the
source code or use the command line interface interface to the netdisco
group in /etc/groups.
Don't forget to logout and login after adding yourself to a group.
Netdisco runs Postgres as its database back-end. A mySQL and Oracle port are in development.
cd /usr/ports/database/postgresql7
make install
Next initialize the database :
more /usr/local/pgsql/post-install-notes
su -l pgsql -c initdb
urpmi postgresql postgresql-devel postgresql-server postgresql-docs
The files you will need to edit below are in /var/lib/pgsql/data.
If you lost / don't have install CDs :
The following line uses an FTP site that has the 9.0 RPMs because I lost the CDs. Check the current mirror list at http://www.mandrakelinux.com/en/ftp.php3 and choose a mirror close to you.
urpmi.addmedia ftpsite ftp://mirror.mcs.anl.gov/pub/Mandrake-old/9.0/i586/Mandrake/RPMS \
with ../base/hdlist.cz
Now you have to add --media ftpsite in each urpmi command like so :
urpmi --media ftpsite postgresql postgresql-devel
Remember this for the Apache setup too.
If you are installing Postgres from source you may have to run these two commands in order to install the DBD::Pg Perl module later on :
export POSTGRES_INCLUDE=/usr/local/postgres/include
export POSTGRES_LIB=/usr/local/postgres/lib
You may also have to modify your /etc/ld.so.conf to include your new POSTGRES_LIB directory.
Don't forget to run ldconf afterwards.
Netdisco's settings in PostgreSQL are
Database User : netdisco Database Name : netdisco Database Password : you choose it
Follow these steps to setup Netdisco in PostgreSQL.
For installation you must give the database user access to the template1 database.
The following line will give all users who have logon permissions in Unix access
to the template1 database.
local template1 all ident
Next you must give the netdisco database user access to the netdisco database.
The following line will give all database users access to a database that is the same
name as them. This line must be put above all the rest of the uncommented lines in the
pg_hba.conf file to take precedence.
local sameuser all md5
You may have to swap md5 for crypt, for old versions of Postgres.
Upgrade.
Finally if you would like to have root be able to access all databases, try this one :
local all root trust
Linux : one of these three
/etc/rc.d/init.d/postgresql restart
service postgresql restart
/etc/rc.d/postgresql restart
FreeBSD :
/usr/local/etc/rc.d/*pgsql* restart
If there are problems with this step you will receive an error that mentions something about pg_hba.conf.
Next, find out the name of your database user. The default name for
some Linux RPM versions is postgres and for some BSD installations pgsql.
Edit the files pg_init and pg_run to match your database user name in /usr/local/netdisco/sql/pg_init
vi /usr/local/netdisco/sql/pg_init
vi /usr/local/netdisco/sql/pg_run
As root run sql/pg_init to create the database and user for Netdisco.
The password you will be asked for twice is the new password for the database user you are creating. This is the same password you will be putting in netdisco_apache.conf and in netdisco.conf.
cd /usr/local/netdisco/sql
./pg_init
sql/pg_run. Enter the database user password given above.
cd /usr/local/netdisco/sql
./pg_run
sql/pg_all. Type in the database user password once
when prompted.
cd /usr/local/netdisco/sql
./pg_all
Specifically you really need to up the maximum connections and shared memory settings. After you have Netdisco running on a large installation it would be of great benefit to get a Postgres guru in there to tune things for you. See README for more info about how to speed things up now and again.
chkconfig postgresql on
/usr/local/etc/rc.d is alright.
VACUUM and REINDEX by hand if things get too slow.
db_Pg line in netdisco.conf.
db_Pg = dbi:Pg:dbname=netdisco;host=HOSTNAME;port=PORT;
On the Postgresql machine, allow your remote front end to contact the backend database. Here is a sample line in pg_hba.conf.
#TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD host netdisco netdisco 101.102.103.104 255.255.255.0 md5
Don't forget to restart Postgres after changing the pg_hba.conf file.
There are three components to setup for SNMP
Net-SNMP 5 lives at http://net-snmp.sourceforge.net.
See OS-specific notes below.
./configure, make sure you add the switch --with-perl-modules
./configure --with-perl-modules --enable-shared
make
make install
If you already have net-snmp installed, then go to the source directory and
in the perl subdirectory and run perl Makefile.PL
cd /path/to/net-snmp-5.1.x/perl
perl Makefile.PL
make
make install
********************************************************************
DO NOT INSTALL the SNMP:: modules off of CPAN or the NET::SNMP module off of CPAN.
********************************************************************
Reread the above line.
snmpconf
Make sure to set the MIB dir if non-standard or you are not using the MIBS that come with Netdisco.
(Textual mib Parsing -> Specifies directories to be searched for mibs)
Make sure this newly created snmp.conf lives in /usr/local/share/snmp or wherever you put a custom install.
OS Specific Notes :
cd /usr/ports/net/net-snmp && make install
For a recent version of BSD you should get the Perl modules installed automatically.
For a really old version of BSD, or for weird and multiple Perl installs do it by hand!
cd /usr/ports/net/net-snmp
make
cd work/net-snmp-5
./configure --with-perl-modules
make
make install
rpm -e net-snmp
Same goes for Debian. DO NOT use the apt-get version of Net-SNMP, install by hand (it's easy!).
This Perl module is an integral part of Netdisco. It is available from http://snmp-info.sourceforge.net. It requires that you have net-snmp installed first.
SNMP::Info holds all the device-specific code to retrieve data from network devices via SNMP. A wide variety of devices are supported. You may need to add support for other devices if they do not follow a standard interface. This is not too complex. See SNMP::Info for more details.
You have four different options in installing SNMP::Info
perl -MCPAN -e shell
o conf prerequisites_policy ask
install SNMP::Info
tar xvfz SNMP-Info-0.x.tar.gz
cd SNMP-Info-0.x
perl Makefile.PL
make install
make snmp
This will create the SNMP/ directory where SNMP::Info will live. Periodically you should re-run
make snmp
To update to the most current CVS version. For BSD or Solaris systems, use gmake instead
of make
cd /usr/ports/net-mgmt/p5-SNMP-Info
make install
MIBs that are required for SNMP::Info are included with Netdisco in the mibs/ directory.
They are also available as a separate download on source forge.
GraphViz is used to create the Network Map.
It lives at http://www.research.att.com/sw/tools/graphviz/.
cd /usr/ports/graphics/graphviz && make install
-devel packages are installed. If you see errors about not having a PNG
or JPEG library then install the -devel packages as needed.
urpmi libjpeg62-devel libpng3-devel
If you get some weird error in build about not having intl.la then
make sure you have the gettext packages installed :
urpmi gettext-devel
Make the JPEG and EXPAT libraries first and when making the JPEG library make sure you have
./configure --enabled-shared --enabled-static
DarwinPorts or you can check out http://www.phil.uu.nl/~js/graphviz/.
node_font in netdisco.conf to match.
cp /path/to/windows/fonts/lucon.ttf /usr/local/netdisco
You can grab arial.ttf or lucon.ttf out of the c:\windows\fonts directory of any Windows machine.
which twopi
which neato
After the Perl Modules step below, make sure the Graphviz Perl module got installed
perldoc GraphViz
NOTE: You can safely ignore all warnings about size too small for label.
Apache2 --
Until mod_perl 2.0 is released as stable, Mason will not run under Apache2. Netdisco will not run under Apache2 until that point.
See the following three links in addition to this document :
http://www.oreillynet.com/pub/a/mac/2002/11/05/apache_osx.html http://www.oreillynet.com/pub/a/mac/2002/12/18/apache_modssl.html http://www.oreillynet.com/pub/a/mac/2003/02/07/libapreq_update.html
Mandrake 9.1 comes with Apache2. It also has the option of installing a version of Apache1/mod_perl on a different port and then reverse-proxying it.
mod_ssl with Mandrake to come...
urpmi apache-devel-1 mod_perl-devel-1 apache-mod_perl-1 mod_perl-common-1
Mandrake 9.1 - Do this for the DB_File Perl module
ln -s /usr/include/db1/* /usr/include
ln -s /usr/lib/libdb1.so.2 /usr/lib/libdb.so
Mandrake 9.0 uses two Apache1 servers, while Mandrake 9.1 uses an Apache2 server that sits in front of the apache1/mod_perl server.
Configuration files for Mandrake live in /etc/httpd/conf
In the file httpd-perl.conf add the two Include lines:
Include /usr/local/netdisco/netdisco_apache.conf
Include /usr/local/netdisco/netdisco_apache_dir.conf
In the file httpd.conf (httpd2.conf for 9.1) add the final RewriteRule line:
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^proxy:.* - [F]
RewriteRule ^(.*\/perl\/.*)$ http://%{HTTP_HOST}:8200$1 [P]
RewriteRule ^(.*\/cgi-perl\/.*)$ http://%{HTTP_HOST}:8200$1 [P]
RewriteRule ^(.*\/netdisco\/.*)$ http://%{HTTP_HOST}:8200$1 [P]
</IfModule>
In the file commonhttpd.conf add the Alias line :
Alias /netdisco /netdisco/
/etc/rc.d/init.d/httpd restart
Install Apache 1.3.x and mod_perl 1.x and mod_ssl
Netdisco is designed to work in a secure (https) or non-secure environment. Due to the security and privacy concerned associated with this data, using a secure server is recommended.
Below is my method if you haven't installed apache and mod_perl before. I statically compile mod_perl, and mod_ssl then leave the rest of the modules as dynamically loadable objects (DSO).
Get mod_perl from http://perl.apache.org
Get mod_ssl from http://www.modssl.org
Unarchive all three to the same directory, maybe /usr/local/src
cd apache_1.3* ./configure
No need to make it yet.
The OpenSSL library is a prerequirement for mod_ssl and may or may not already be on your system. If not :
cd /usr/ports/devel/mm && make install
cd /usr/ports/security/openssl && make install
Setup mod_ssl :
cd /path/to/mod_ssl_1.x.x
SSL_BASE=SYSTEM \
./configure \
--with-apache=../apache_1.3.x \
--disable_rule=SSL_COMPAT
You will have to tell the OS to look for the Kerberos libraries used in this version of OpenSSL:
./configure \
--with-apache=../apache_1.3.x \
--disable_rule=SSL_COMPAT
make C_INCLUDE_PATH=/usr/kerberos/include
Thanks to David Martin for this info.
mod_ssl
SSL_BASE=/path/to/openssl-0.9.x \
./configure \
--with-apache=../apache_1.3.x \
--disable_rule=SSL_COMPAT
cd ../mod_perl-1.x
/usr/local/bin/perl Makefile.PL \
APACHE_SRC=../apache_1.3.x/src \
EVERYTHING=1 \
DO_HTTPD=1 \
USE_APACI=1 \
PREP_HTTPD=1
make
cd ../apache_1.3*
./configure \
--prefix=/usr/local/apache \
--enable-module=most \
--enable-shared=max \
--activate-module=src/modules/perl/libperl.a \
--with-perl=/usr/local/bin/perl \
--enable-module=ssl
make
make certificate
make install
cd ../mod_perl* make install
Add the following lines in your httpd.conf.
Your httpd.conf will live in /usr/local/apache/conf if you installed using my method.
httpd.conf not in a VirtualHost section.
Include /usr/local/netdisco/netdisco_apache.conf
Include /usr/local/netdisco/netdisco_apache_dir.conf
If you are not using Virtual Hosts, then add this line under the netdisco_apache.conf line.
Include /usr/local/netdisco/netdisco_apache_dir.conf
Make sure you have this include line for the secure server virtual host *:443 at the bottom of http.conf.
Set the mason data directory writable to the apache user that does the requests.
Assuming nobody is the user that apache requests run this as root :
chown nobody.netdisco /usr/local/netdisco/mason
The name of the user is listed in httpd.conf under the User directive.
Note: Some Linux distributions such as Redhat 6.x install mod_perl as
a Dynamic Shared Object (DSO). This is known to be unstable, especially
with Mason. Compile mod_perl statically using the method listed
above. If you suspect yours is not compiled in, run httpd -l and see if
mod_perl.c is listed (it should be).
Below is a list of required modules for Netdisco, freely available from CPAN http://www.cpan.org. Many of these modules have prerequisite modules.
Use the CPAN module that comes with Perl to install the modules and their prerequisites automatically:
perl -MCPAN -e shell
o conf prerequisites_policy ask
install Digest::MD5
install Bundle::DBI
install Apache::DBI
install DBD::Pg
install DB_File (for Apache::Session)
install Apache::Session
install Apache::Test (for Apache::Request, you may need to do a 'force install')
install Apache::Request
install HTML::Entities
install HTML::Mason
install MasonX::Request::WithApacheSession
install Graph
install GraphViz (you may need to do a 'force install')
install Compress::Zlib (probably already have this one)
Some of these you will probably already have installed. Others you may need to force
with force install ModuleName. Do Not include the comments in (parens)!
If you don't have Perl installed in /usr/bin, you will need to modify
the first lines of netdisco and bin/doc_munge.
See README for detailed configuration descriptions.
session_user_name
session_password
session_cookie_domain
Change center_network_device to a network device that is well connected to the main
segment by CDP/FDP/SONMP.
/usr/local/netdisco/netdisco -u joebob
Add more users from the web Admin Panel once Netdisco is up and running.
POD2TEXT lines in Makefile point to where your Perl binaries
are installed.
cd /usr/local/netdisco && gmake doc
chgrp netdisco /usr/local/netdisco/*.conf chmod 660 /usr/local/netdisco/*.conf
The Organizationally Unique Identifier (OUI) database allows Netdisco to identify the manufacture of a network card using the first 24 bits of a MAC address.
Run the following command to import the contents of oui.txt into your database.
cd /usr/local/netdisco
netdisco -O
The database of OUIs is needed by Netdisco and is available from the IEEE.
If you have lynx installed you can install the OUI database by:
cd /usr/local/netdisco
gmake oui
(gmake for BSD/Solaris)
Or do this by hand:
1. Download oui.txt from http://standards.ieee.org/regauth/oui/ 2. Run netdisco -O
Now that you have everything setup, (re)start the web-server.
Check Apache's error_log for possible errors.
/usr/local/apache/bin/apachectl start
/etc/rc.d/init.d/httpd restart
Also, double-check that Apache starts on its own at reboot.
Pick a device that you can access with the command snmpwalk.
Tell Netdisco to discover that device:
cd /usr/local/netdisco
./netdisco -d devicename
Make sure that this step actually works. This is a good metric that you have now installed Netdisco correctly. Add the -D flag to get copious debugging info.
See README for a description of Topology Information.
If your network is CDP/FDP/SONMP aware, pick a device that you consider close to the center of the network and start an auto-discovery from there:
cd /usr/local/netdisco
./netdisco -r myrouter
If your network is not CDP friendly, then see README for how to use the manual topology file netdisco-topology.txt.
You MUST supply Netdisco with a working topology or MAC addresses will show up on uplink ports instead of end ports.
First restart Apache so that netdisco will see the changes that you have made in netdisco.conf. Note that a graceful restart will not re-read the configuration file. A full restart is required.
/usr/local/apache/bin/apachectl restart
Point a browser to /netdisco on the server you have Netdisco installed on. If everything is working you should be able to login with the user name and password you added in Step 10. You should also be able to access the Admin Panel.
http://localhost/netdisco
If you have problems, check the error_log of apache for messages.
tail /usr/local/apache/logs/error_log
Once you're sure Netdisco is setup correctly, modify netdisco.crontab.
vi netdisco.crontab
center_network_device to one of your core routers or switches.
Once Netdisco has been running for a day, look at the BackEnd Log in the web
browser and see how long each of the jobs is taking to finish. If there is overlap,
for example if your arpnip is taking over 60 minutes or your macsuck is taking
over 120 minutes, then consider decreasing the frequency of these jobs as to not
cause extra load on your network devices.
Now set the crontab to the netdisco user (as root).
crontab -u netdisco /usr/local/netdisco/netdisco.crontab
The admin deaemon performs administration jobs that are requested from the web front-end. See README for a description of the admin daemon.
/usr/local/netdisco/bin/netdisco_daemon start
The daemon will be respawned daily in the Cron job listed above. This isn't 100% necessary, I just did in case the net-snmp libraries had any memory leaks.
If you would like the daemon to be started upon bootup, then do the following:
ln -s /usr/local/netdisco/bin/netdisco_daemon /etc/rc.d/init.d
chkconfig --add netdisco_daemon
chkconfig netdisco_daemon on
Now you should be able to use this command:
service netdisco_daemon {stop,start,restart,status}
ln -s /usr/local/netdisco/bin/netdisco_daemon /usr/local/etc/rc.d
/usr/local/netdisco/bin/netdisco_daemon start
Now that you have spent ten hours of your life installing this go drink a Beer, you deserve it.
Once you have or have not succeeded, come join the Netdisco User's mailing list at http://netdisco.org and pass on any hints you may have in the INSTALL process.
It's a good place to keep up on new features and releases, and it's the place to ask any questions.
If you find Netdisco useful please consider donating to its developer. Check out http://netdisco.org for a Source Forge donation page and Amazon wish list.