Table of Contents

In this tutorial, we'll show you how to add devices to Netdot, and how to use it to map and manage your IP address space.

Introduction

Network Documentation Tool (Netdot) is an open source tool which can help network administrators collect, organize, and maintain network documentation.

Basic capabilities:

  • Discover and poll devices using SNMP
  • Discover and build L2 topology using different sources: CDP, LLDP, STP, and switch forwarding tables
  • Asset management
  • IP address management for v4 and v6
  • DHCP management
  • DNS management
  • Cable management: closets, rooms, sockets, connections within and between buildings, etc.
  • Contact management: administrators, operators, departments, providers, vendors, etc.
  • Export settings for external tools: Nagios, RANCID, Cacti, BIND, etc.

See the Netdot project's site.

In this tutorial, we'll show you how to add devices to Netdot, and how to use it to map and manage your IP address space.

Prerequisites

Before you get started, make sure you've completed these steps.

  • Deploy a CentOS 7 Droplet
  • Add swap space to your server; the example 4 GB amount is fine
  • Install LAMP software, since Netdot requires web and database servers
  • Make a note of your root MySQL password; you'll need it in this tutorial
  • Enable the EPEL (Extra Packages for Enterprise Linux) repository:
				
					
wget http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-2.noarch.rpm

sudo rpm -ivh epel-release-7-2.noarch.rpm

More information about the EPEL repo is available fedoraproject.org.

  • Install these prerequisite tools that will allow you to compile other packages:
				
					
sudo yum install make gcc gcc-c++ autoconf automake rpm-build openssl-devel git perl perl-CPAN perl-Inline
  • Install dnssec-tools manually (you may want to use a different method if you're concerned about skipping the certificate check):
				
					
wget --no-check-certificate https://www.dnssec-tools.org/download/dnssec-tools-2.1-1.fc22.src.rpm -O /tmp/dnssec-tools.src.rpm

rpmbuild --rebuild /tmp/dnssec-tools.src.rpm

cd ~/rpmbuild/RPMS/x86_64/

sudo rpm -ivh --nodeps dnssec-tools-*

Installation

netdot illustration for: Installation

In the first part of this tutorial, we'll install and access Netdot.

Step 1 — Clone the Netdot Repository

Get the latest source for Netdot from GitHub:

cd /usr/local/src/

sudo git clone https://github.com/cvicente/Netdot.git netdot

Step 2 — Install Dependencies

Now you need to install the dependencies. We'll do this with the script included with Netdot, which uses the package manager yum to install quite a few dependencies.

First navigate to the directory where you extracted the files from the Netdot repository:

cd /usr/local/src/netdot/

Run the installation script:

sudo make rpm-install

The prompt will ask you which database you want to use. The answer is marked in <^>red<^>:

Installing required RPM packages

/usr/bin/perl bin/perldeps.pl rpm-install

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

Then the script will install the necessary modules. At the end you'll see this summary, which shows that some installed and some didn't:

Complete!

===============RESULTS===============

RRDs……………………………………….ok

GraphViz……………………………………ok

Module::Build……………………………….ok

CGI………………………………………..MISSING

Class::DBI………………………………….MISSING

Class::DBI::AbstractSearch……………………MISSING

Apache2::Request…………………………….ok

HTML::Mason…………………………………MISSING

Apache::Session……………………………..MISSING

URI::Escape…………………………………ok

SQL::Translator……………………………..MISSING

SNMP::Info 2.06……………………………..ok

NetAddr::IP 4.042……………………………ok

Apache2::AuthCookie………………………….MISSING

Apache2::SiteControl…………………………MISSING

Log::Dispatch……………………………….ok

Log::Log4perl……………………………….ok

Parallel::ForkManager………………………..ok

Net::Patricia 1.20…………………………..MISSING

Authen::Radius………………………………MISSING

Test::Simple………………………………..MISSING

Net::IRR……………………………………MISSING

Time::Local…………………………………ok

File::Spec………………………………….ok

Net::Appliance::Session………………………MISSING

BIND::Config::Parser…………………………MISSING

Net::DNS……………………………………ok

Text::ParseWords…………………………….ok

Carp::Assert………………………………..ok

Digest::SHA…………………………………ok

Net::DNS::ZoneFile::Fast……………………..ok

Socket6…………………………………….ok

XML::Simple…………………………………ok

DBD::mysql………………………………….ok

If there are still any missing Perl modules, you can try:

make installdeps

So you have to install the missing Perl modules:

sudo make installdeps

The prompt will ask you some questions. Answers are marked in <^>red<^>:

Installing required Perl modules

/usr/bin/perl bin/perldeps.pl install

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

CPAN.pm requires configuration, but most of it can be done automatically.

If you answer 'no' below, you will enter an interactive dialog for each

configuration option instead.

Would you like to configure as much as possible automatically? [yes] <^>ENTER<^>

<install_help>

Warning: You do not have write permission for Perl library directories.

To install modules, you need to configure a local Perl library directory or

escalate your privileges. CPAN can help you by bootstrapping the local::lib

module or by configuring itself to use 'sudo' (if available). You may also

resolve this problem manually if you need to customize your setup.

What approach do you want? (Choose 'local::lib', 'sudo' or 'manual')

[local::lib] <^>ENTER<^>

Autoconfigured everything but 'urllist'.

Now you need to choose your CPAN mirror sites. You can let me

pick mirrors for you, you can select them from a list or you

can enter them by hand.

Would you like me to automatically choose some CPAN mirror

sites for you? (This means connecting to the Internet) [yes] <^>ENTER<^>

The script may ask you to create a fake password for testing purposes. You can skip that part.

This will take 10-15 minutes to complete. The script will install the missing modules. At the end, you should see that every module installed successfully:

===============RESULTS===============

RRDs……………………………………….ok

GraphViz……………………………………ok

Module::Build……………………………….ok

CGI………………………………………..ok

Class::DBI………………………………….ok

Class::DBI::AbstractSearch……………………ok

Apache2::Request…………………………….ok

HTML::Mason…………………………………ok

Apache::Session……………………………..ok

URI::Escape…………………………………ok

SQL::Translator……………………………..ok

SNMP::Info 2.06……………………………..ok

NetAddr::IP 4.042……………………………ok

Apache2::AuthCookie………………………….ok

Apache2::SiteControl…………………………ok

Log::Dispatch……………………………….ok

Log::Log4perl……………………………….ok

Parallel::ForkManager………………………..ok

Net::Patricia 1.20…………………………..ok

Authen::Radius………………………………ok

Test::Simple………………………………..ok

Net::IRR……………………………………ok

Time::Local…………………………………ok

File::Spec………………………………….ok

Net::Appliance::Session………………………ok

BIND::Config::Parser…………………………ok

Net::DNS……………………………………ok

Text::ParseWords…………………………….ok

Carp::Assert………………………………..ok

Digest::SHA…………………………………ok

Net::DNS::ZoneFile::Fast……………………..ok

Socket6…………………………………….ok

XML::Simple…………………………………ok

DBD::mysql………………………………….ok

All the necessary Perl modules are installed! Now you can proceed to the next step.

Step 3 — Configure the SNMP Service

We need to configure SNMP on this server so Netdot can monitor it. You'll need to configure SNMP on other networking devices that you want Netdot to monitor as well, but for this tutorial, we'll just monitor this Droplet itself.

First, you have to install Netdisco MIBs. Install SNMP supporting packages:

sudo yum install net-snmp net-snmp-utils

Download the Netdisco files and extract them:

wget http://downloads.sourceforge.net/project/netdisco/netdisco-mibs/latest-snapshot/netdisco-mibs-snapshot.tar.gz -P /tmp

sudo tar -zxf /tmp/netdisco-mibs-snapshot.tar.gz -C /usr/local/src

Make a new directory for Netdisco and move/copy the needed files:

sudo mkdir /usr/local/netdisco

sudo mv /usr/local/src/netdisco-mibs /usr/local/netdisco/mibs

sudo cp /usr/local/netdisco/mibs/snmp.conf /etc/snmp/

Edit the configuration file:

sudo vi /etc/snmp/snmp.conf

Comment out the lines with unnecessary vendors to save memory and time by adding a hash mark in front of them (#). You'll want to leave the netdisco lines active and comment out all the others:

. . .

mibdirs /usr/local/netdisco/mibs/rfc

mibdirs +/usr/local/netdisco/mibs/net-snmp

mibdirs +/usr/local/netdisco/mibs/cisco

. . .

. . .

Finally, you need to start the SNMP service:

sudo systemctl start snmpd.service

Learn more about SNMP in the tutorial series Monitoring and Managing your Network with SNMP. You'll want to consult that tutorial series when you add more devices to Netdot.

Step 4 — Configure Database Settings for Netdot

Netdot comes with a configuration file that you need to customize to your needs. Create a copy of <^>Default.conf<^> with the name <^>Site.conf<^>:

sudo cp /usr/local/src/netdot/etc/Default.conf /usr/local/src/netdot/etc/Site.conf

Then, you can modify the file <^>Site.conf<^> to reflect your specific options.

sudo vi /usr/local/src/netdot/etc/Site.conf

The complete file isn't shown here. You have to locate the following variables, and update them to match your settings:

DB_TYPE => 'mysql'

DB_DBA => 'root',

DB_DBA_PASSWORD => '<^>rootpass<^>',

DB_HOST => 'localhost',

DB_DATABASE => 'netdot',

DB_NETDOT_USER => 'netdot_user',

DB_NETDOT_PASS => '<^>netdot_pass<^>',

Most of the default settings are fine.

  • DB_DBA: The MySQL user which has the right to create databases; should be root in most cases
  • DB_DBA_PASSWORD: MySQL password for root
  • DB_DATABASE: Name of the database you want to create for Netdot
  • DB_NETDOT_USER: Netdot database user you want to create
  • DB_NETDOT_PASS: Set a unique password for the Netdot database user

You don't have to create the Netdot database or user manually. The installation process will read the values from this file and create the appropriate database and user.

> Note: If you modify the configuration file in the future, you must restart Apache for the changes to take effect.

>

> “`

> sudo systemctl restart httpd.service

> “`

Step 5 — Install Netdot

Initialize the database:

sudo make installdb

Then install Netdot:

sudo make install PREFIX=/usr/local/netdot APACHEUSER=apache APACHEGROUP=apache

Step 6 — Finish the Installation

The only thing left to configure after a successful installation of Netdot is the Apache server.

Copy the configuration file in the directory with the Apache settings:

sudo cp /usr/local/netdot/etc/netdot_apache24_local.conf /etc/httpd/conf.d/

Restart Apache:

sudo systemctl restart httpd.service

Step 7 - Set Up Cron Jobs

Netdot has several scripts that should be run periodically. Copy the sample crontab file to your cron.d directory:

sudo cp /usr/local/src/netdot/netdot.cron /etc/cron.d/netdot

The installation is complete.

Step 8 — Access Netdot

Launch your browser and go to the address http://<^>your_server_ip<^>/netdot.

Log in with the default user name and password, which are both admin.

Make sure you change the password right away!

Use Netdot to Document Your Network

In this section we'll introduce Netdot and show you how to add devices and use it to manage your IPs.

Once you are logged in you will see the following:

Netdot's interface is quite simple. Let's look at the basic tasks you can perform with it.

Collect Data from Devices

First we need to add your network devices. They can be added in several ways:

  • One at a time, using a script
  • By scanning devices in a given subnet
  • By scanning devices listed in a file
  • Manually using the Netdot control panel

Poll one device using a script

This is the method we'll use to add this Droplet's own information to Netdot.

This command will run the script to get the data from single host:

/usr/local/netdot/bin/updatedevices.pl -H <^>your_server_ip<^> -I -c <^>snmp community<^>

For example, you can add the server on which the Netdot is installed with this command:

/usr/local/netdot/bin/updatedevices.pl -H localhost -I -c public

Go ahead and run this command. You should see output like the following:

INFO – /usr/local/netdot/bin/updatedevices.pl started at Wed Nov 5 09:49:39 2014

INFO – Updating single device: localhost

INFO – Inserted new RR: localhost.defaultdomain

INFO – Inserting new Device: localhost

INFO – localhost.defaultdomain: SNMP target address set to 127.0.0.1

INFO – localhost.defaultdomain: Interface 1 (lo) updated

INFO – localhost.defaultdomain: Interface 2 (eno16777728) updated

INFO – localhost.defaultdomain [eno16777728]: Inserted new IP fe80::20c:29ff:fe20:4f53

INFO – localhost.defaultdomain [eno16777728]: Inserted new IP 192.168.176.128

INFO – Device::snmp_update: localhost.defaultdomain: Finished updating

INFO – /usr/local/netdot/bin/updatedevices.pl total runtime: 18 sec

Scan devices in a given subnet

This method uses the same script to scan all the devices in a given subnet:

/usr/local/netdot/bin/updatedevices.pl -B <^>111.111.111.0/24<^> -I -c <^>snmp community<^>

Scan devices listed in a file

You might find it helpful to list all of your devices in a simple text file. The file should contain a list of devices (hostnames or IPs) and their SNMP communities, one per line:

host1.sample community1

host2.sample community2

host3.sample community2

host4.sample community3

. . .

Then you can use the Netdot script to scan all the devices listed in the file:

/usr/local/netdot/bin/updatedevices.pl -E <^>/path/to/file<^>

You can use the following command to get the full list of the script parameters:

/usr/local/netdot/bin/updatedevices.pl -h

Add a device from the Netdot control panel

In the Netdot control panel, navigate to Management in the top navigation. Choose Management > Devices. Click the [new] link.

Enter the hostname or IP address of the device. Choose the SNMP version and community from the dropdown menus. Then, click Discover. Netdot will then poll the device using SNMP.

Device Documentation

Once you have created a device you can add more information about it. You can search for a device by its name, IP, or MAC address. Each information page contains several sections:

Basics:

In this section you can view and edit general information about the device: its owner, location, operating system, and management information. You can also add comments and custom attributes.

Some information can be obtained automatically, and some information must be entered manually.

You can get help on any of the parameters by simply clicking on its title. For example, clicking on the title "First Discovered" you will see the following pop-up window:

Interfaces:

In this section you can view and edit information about a device's interfaces: name, speed, status, neighbor (directly connected device), etc.

You can also view detailed interface information by clicking on its number or its name.

IP info:

In this section you can view information about all the IP addresses found on the device together with the subnets they belong in, the device interface where they were found, and optionally their DNS names. You can also connect services (HTTP, DNS, MySQL, etc.) to the corresponding addresses.

Topology:

In this section you can see a graph of the device and its directly connected neighbors.

IP Address Management

One of the most useful features of Netdot is the address space management. You can plan, monitor, and manage IP addresses on your network.

Basic objects in the Netdot's address space are IP blocks. They can represent individual end-node addresses, as well as groups of addresses. The distinguishing characteristic is the prefix: the end-node address is an IP block with a prefix of /32, and a subnet of 126 end-node address is an IP block with a prefix /25.

For example, let's create the following simple structure:

104.236.38.0/24

104.236.38.0/25

104.236.38.128/25

104.236.38.128/26

104.236.38.192/26

Navigate to Management > Address space.

Click the [new] link.

Enter the 104.236.38.0/24 in the IP[/prefix] field. You can optionally specify the Owner and Used By. (You can add an item to the dropdown list by clicking on the [new] link, filling out the form, and refreshing the page.) From the Status dropdown menu, select Container. Enter a Description of this container.

Click Save.

Netdot supports the following statuses:

  • Container: Includes other containers or IP blocks
  • Subnet: Represents the actual subnets
  • Reserved: Blocks that should not be allocated for whatever reason
  • Static: Statically assigned

Next, create a new subnet for 104.236.38.0/25, selecting Subnet for Status:

You will see the following as a result:

To create the next container, you can click on the green bar area next to the red one at the bottom of the Usage for 104.236.38.0/24 section.

Then Netdot will ask for confirmation: The IP address or block 104.236.38.128/25 does not yet exist. Are you sure that you want to create it? After confirmation you will create a new container.

Within this container, you can add another subnet for 104.236.38.128/26 and another container for 104.236.38.192/26, and so on.

Now, take a look at the entire hierarchy you've set up. To do this, go to the primary container (104.236.38.0/24) and click the [Tree View] link on the far right. You'll see the following:

If you click one of the boxes in the diagram, you will see a detailed map of the appropriate subnet.

For example, it may look as follows:

This figure shows that the first and last addresses of the network are automatically reserved. The addresses 1 to 63 are used for DHCP. Addresses that have been statically assigned to hosts or device interfaces are marked red. Addresses that have not been assigned as static or dynamic, but have been seen on the network, are marked blue. Available addresses are marked green.

To add, reserve, or edit an address you have to click on it. Also, you can see the overall statistics on used and available addresses on the subnet in the Utilization field, which in this example are:

Used: 76 of 126 Available: 50 (39%)

Conclusion

Netdot is a powerful tool for documenting your network. After completing this tutorial you've got general understanding of how to install it, how to do basic setup, how to add new devices, and how to manage your address space.