1 Netdot exercise

2 Introduction

The Network Documentation Tool (Netdot) is an open source software designed to help network administrators collect, organize and maintain network documentation. Netdot was developed at the University of Oregon.

2.1 Goals

In these exercises we will install Netdot and demonstrate some of its most important features.

2.2 Notes

3 Installation

Netdot may already be installed in your campus server. Ask the instructor.

Log in to your virtual machine as the sysadm user.

3.1 Clone the repository

$ cd
$ git clone https://github.com/cvicente/Netdot.git
$ cd Netdot

3.2 Install dependencies:

$ sudo apt install build-essential
$ sudo make apt-install

Which RDBMS do you plan to use as backend: [mysql|Pg]? mysql

We need to add a temporary repository of Netdot dependencies until all packages 
are in Debian/Ubuntu official repositories.
Would you like to continue? [y/n] y

This will download a lot of packages. Be patient.

(If you had not installed mysql-server, you'll be asked for a DBA password. Ask the instructor for the Mysql root password).

Say yes to the two following questions:

We will install the MIB files now. Continue? [y/n] y
A new /etc/snmp/snmp.conf needs to be installed to point to the newly 
installed MIB files. The current file will be backed up. Continue? [y/n] y

At the end of the installation you will see a list of Perl modules that have been installed (OK). If any did not install you will see "MISSING".


NOTE If packages show as MISSING, do not continue. Ask your instructor for help. Probably you will need to go back and repeat the last section (sudo make apt-install) and look for errors.


3.3 Initialize the site configuration:

$ cp etc/Default.conf etc/Site.conf
$ editor etc/Site.conf

Find and change the following values:

NETDOTNAME => 'hostX.campusY.ws.nsrc.org',
DB_DBA_PASSWORD => '(the password you used when installing mysql)',
DEFAULT_SNMPCOMMUNITIES  =>  ['NetManage', 'public'],
NMS_DEVICE => 'hostX.campusY.ws.nsrc.org',
DEFAULT_DNSDOMAIN  => 'ws.nsrc.org',
DEVICE_NAMING_METHOD_ORDER => [ 'sysname', 'snmp_target' ],

Save and exit from the file.

3.4 Install the application and initialize the database.

It's finally time to run the installation!

$ sudo make installdb
$ sudo make install APACHEUSER=www-data APACHEGROUP=www-data
$ sudo ln -s /usr/local/netdot/etc/netdot_apache24_local.conf \
    /etc/apache2/conf-available/netdot.conf
$ sudo a2enconf netdot
$ sudo systemctl restart apache2

If you get an error when trying to restart apache2 see the next section to patch your Netdot installation.

Install the cron jobs for automated tasks

$ sudo cp netdot.cron /etc/cron.d/netdot

3.5 Patch installation

When running on Ubuntu 16.04 or later, these patches are necessary:

https://github.com/cvicente/Netdot/issues/48#issuecomment-297634200

We provide separate files for you to download and then apply the required patches. To do this we will download the patch files in to /home/sysadm/patches.

$ cd
$ mkdir patches
$ wget http://www.ws.nsrc.org/downloads/netdot/perl.patch
$ wget http://www.ws.nsrc.org/downloads/netdot/apache2.patch

Now that you have the patch files we will apply these patches to your apache2 webserver initialization script and the Perl DBI module.

$ sudo patch /etc/init.d/apache2 apache2.patch
$ sudo patch /usr/share/perl5/Class/DBI.pm perl.patch

You should now be able to start the Apache2 webserver again:

$ sudo systemctl daemon-reload
$ sudo systemctl restart apache2

4 Operation

4.1 Log into the web interface

In your browser, go to:

http://hostX.campusY.ws.nsrc.org/netdot

Log in with username: admin and password: admin

4.2 Changing default passwords

Netdot comes with three default user accounts. You should change the default passwords on those.

Go to the "Contacts" tab, then search for "Admin". You should see the details for the Admin user. Click on [edit], and find the Password field. Type the password you used to log in to your server, then click on the "Update" button.

Repeat the same steps for the other default users:

4.3 Discovering devices

If you have not done so yet, configure SNMP on your server and your router.

Ask the instructor to provide you with instructions for configuring SNMP on Cisco routers and Linux

Now back to Netdot. Let's create a file with all the devices in the lab network that respond to SNMP:

$ editor /home/sysadm/discoverme.txt

Copy and paste the list below. You will need to change "Y" to your campus number

bdr1.campusY.ws.nsrc.org
core1.campusY.ws.nsrc.org
dist1-b1.campusY.ws.nsrc.org
dist1-b2.campusY.ws.nsrc.org
host1.campusY.ws.nsrc.org
host2.campusY.ws.nsrc.org
host3.campusY.ws.nsrc.org
host4.campusY.ws.nsrc.org
host5.campusY.ws.nsrc.org
host6.campusY.ws.nsrc.org
srv1.campusY.ws.nsrc.org

Now, tell Netdot to discover those devices:

$ cd /usr/local/netdot
$ sudo bin/updatedevices.pl -E /home/sysadm/discoverme.txt -IAF

When that is done, go to the web interface and navigate to

Management -> Devices

Leave the search box empty, and click on the "Find" button.

You should see all the discovered devices in that list. Go to the link for your group's router (e.g. rtrX.ws.nsrc.org)

4.4 Finding a computer in your network

Netdot will show you which devices were seeing that MAC address the last time that it discovered the network.

4.5 Managing IP address space

Go to Management -> Address Space

You should see a list of IP blocks. Some of these come pre-installed in Netdot, and some (Subnets) are discovered from routers.

4.5.1 Create a container to include all the group subnets

In the section called "Address Space Tasks" on top, click on the "[new]" button and enter the following:

You should now see the new Container page. It shows a graphical representation of the block. All the existing subnets are shown in red. The green space represents unused or available address space.

4.6 Polling devices

Periodically you will want to connect again to your routers and switches to fetch their interface list, ARP and forwarding tables etc. You can run the command which does this:

$ sudo /usr/local/netdot/bin/updatedevices.pl -DIFAT

To avoid having to run this by hand, you can install a crontab which will do it automatically at set times of day. We installed the crontab file in /etc/cron.d previously. If you look in /etc/cron.d/netdot you will see that this command executes once each hour by default.

5 More information

Official Netdot Website

6 Appendx: Netdot Patches (you can create apache2.patch and perl.patch from these)

Patch to /etc/init.d/apache2

--- apache2.orig    2017-03-21 13:36:56.712133397 +0000
+++ apache2 2017-03-21 13:37:35.928572194 +0000
@@ -159,8 +159,12 @@
    fi

    if apache_conftest ; then
+       # Utterly horrible workaround for https://osl.uoregon.edu/redmine/issues/1904
+       a2disconf netdot
            $APACHE2CTL start
            apache_wait_start $?
+       a2enconf netdot
+       $APACHE2CTL graceful
            return $?
    else
            APACHE2_INIT_MESSAGE="The apache2$DIR_SUFFIX configtest failed."

Patch to /usr/share/perl5/Class/DBI.pm

# Needed for mysql 5.7
# https://osl.uoregon.edu/redmine/issues/1911
# Patch taken from:
# https://rt.cpan.org/Public/Bug/Display.html?id=118491

--- Class/DBI.pm.orig   2007-10-04 21:27:07.000000000 +0000
+++ Class/DBI.pm    2017-03-24 12:01:07.829877222 +0000
@@ -597,6 +597,7 @@

 sub _auto_increment_value {
    my $self = shift;
+   my $sth = shift;
    my $dbh  = $self->db_Main;

    # Try to do this in a standard method. Fall back to MySQL/SQLite
@@ -607,6 +608,7 @@
    my $id = $dbh->last_insert_id(undef, undef, $self->table, undef)    # std
        || $dbh->{mysql_insertid}                                         # mysql
        || eval { $dbh->func('last_insert_rowid') }
+       || $sth->{'mysql_insertid'} # Added for MySQL 5.7
        or $self->_croak("Can't get last insert id");
    return $id;
 }
@@ -623,7 +625,7 @@
        $self->_bind_param($sth, \@columns);
        $sth->execute(values %$data);
        my @primary_columns = $self->primary_columns;
-       $data->{ $primary_columns[0] } = $self->_auto_increment_value
+       $data->{ $primary_columns[0] } = $self->_auto_increment_value($sth)
            if @primary_columns == 1
            && !defined $data->{ $primary_columns[0] };
    };