Nets Developers Guide

3.1 Main distribution directory

When a Nets distribution file is unpacked (using tar/gzip or WinZip, depending on your platform), it creates a single directory containing the entire Nets software tree. The top of this distribution tree will be named something like Nets-2.1 , depending on exactly which version of Nets you have. This top level directory contains the Nets executable programs, some data files, and a number of important sub-directories described below.

The executable programs include netsmain.pl (the main Nets user program), plus some utility programs, netscreate.pl, netsload.pl, netsdump.pl and netspkginstall.pl. When Nets is installed, these executable programs are copied to the standard Perl binary directory (typically /usr/local/bin on Unix, or C:\Perl\bin on Windows).

In the following sections, <NetsDir> means the directory at the top of your Nets distribution.

3.2 <NetsDir>/Nets

This directory includes all the Nets Perl modules required by the Nets programs mentioned above. Each module has a .pm extension. When Nets is installed, these modules are copied to the standard Perl site library directory (typically /usr/local/lib/perl5/site_perl on Unix, or C:\Perl\site on Windows). You can add your own modules to Nets by adding them to this directory and reinstalling Nets.

3.3 <NetsDir>/images/icons

Contains the standard Nets icons, which are using on Nets Drawings and other parts of the Nets user interface.

3.4 <NetsDir>/images/drawings

Contains the background images for Nets Drawings

3.5 <NetsDir>/templates

Contains the standard templates, used for creating collections of interrelated Nets Objects.

3.6 <NetsDir>/plugins

Contains the standard Plug-ins provided as part of Nets.

3.7 <NetsDir>/scripts

Contains the standard Nets Scripting Language scripts provided with Nets.

3.8 <NetsDir>/goodies

A collection of contributed and unsupported files that developers may be interested in. See the README file for a brief description of each file.

FIGURE 1. Nets Object Hierarchy

The core Nets product includes the Perl classes shown below. In general, each Nets Perl class is defined by a Perl package (not to be confused with a Nets package), using conventional Perl object packages. You can add your own classes using Plug-ins, or by modifying the Nets code.

4.1 DBSQL

Provides a range of low level SQL database access routines for doing queries, inserts, updates and deletes. $main::db refers to the (usually) one instance of the DBSQL class.

4.2 DBUtil

Provides a range of routines for managing the contents of the SQL tables as described by Schema.pm. Uses the services of DBSQL to interact with the SQL database.

4.3 Object

This class provides "persistent objects", used to implement Nets Objects such as DEVICE, LINK, NETSUSER etc. Uses the services of DBUtil to save objects to and from the SQL database.

4.4 User

Subclass of Object used for storing information about Nets Users, including Preferences and Permissions.

4.5 GenericDialog

Provides a generalized Tk window class, with a number of common routines and data structures used by most Nets windows, including:

• Menu bar, with common standard menus
• A status bar, for user messages
• Configuring windows
• Storing and reloading window descriptions
• Window history, for implementing Forward and Back functions
• Message Box
• Running tools

4.6 GenericEdit

Subclass of GenericDialog adds features required by a range of object editors, such as OK, Cancel and Help buttons, object saving, and list of available objects.

4.7 ObjectEdit

Subclass of GenericEdit provides object editing services for most low-level Nets objects. Objects are displayed according to the user interface description for the Object class as described in UIDesc.pm. User permissions are observed.

4.8 IconEdit

Subclass of GenericEdit that provides preview and selection of icons from the <NetsDir>/images/icons directory.

4.9 FontEdit

Subclass of GenericEdit that provides preview and selection of fonts. Font names are represented with a platform independent font naming scheme.

4.10 UserEdit

Subclass of ObjectEdit that provides a specialized user interface for editing Nets User objects.

4.11 ObjectList

Subclass of GenericDialog that provides listing and searching for Nets objects. The displayed fields, and searchable fields are described in UIDesc.pm.

4.12 TemplateViewer

Subclass of GenericDialog that provides selection and loading of Templates, as well as click-through to the objects created by the Template.

4.13 AddressMap

Subclass of GenericDialog that provides a window for visualizing IPV4 address usage.

4.14 LogViewer

Subclass of GenericDialog that provides a window for viewing Nets log messages in real time. (This class provides a working example of registering and deregistering Hooks).

4.15 Main

Subclass of GenericDialog implements the Nets main window. This window is always created when Nets starts up, and is always present.

4.16 Report

Subclass of GenericDialog that provides a window for selecting and viewing reports.

5.1 Schema.pm

This file contains the definitions of all the SQL tables used by Nets. The tables are described in a data structure, and in a database independent way. Changing Schema.pm allows you to easily add, change and remove tables and columns from your Nets database.

You might, for example wish to add new columns to a table in order to store some site-specific information that your organization needs. Note that you would normally also need to add something to the ObjectEdit user interface for that object, by modifying UIDesc.pm (see Section 5.2 ).

The database schema described in Schema.pm is used by Nets to load and save Nets Objects. It is also used by netscreate.pl when it creates (or recreates) a database table. You should note that altering Schema.pm will not, on its own, change the table in the database, it merely changes what tables and columns Nets will refer to. You might need to drop and recreate a table, or perhaps add or drop columns by hand, if dropping a table is not possible. The Nets utilities can provide some help with this. For example, you could dump your entire database with netsdump.pl, alter the schema, recreate the tables with netscreate.pl -dropfirst, then reload the data with netsload.pl.

If you are just adding a new table, it should be sufficient to just do netscreate.pl. By default, netscreate.pl does not drop any existing tables, so the new table will be created without affecting any existing table (Note, you will get a number of warning messages as netscreate.pl tries to create all the already existing tables).

Schema.pm defines the data structure %Nets::schema. This is a perl hash, containing an entry for each table used by Nets. Each entry defines the columns, keys and name for that table. Here is a typical example, which defines a table for network addresses.

%Nets::schema =
(
ADDRESS => {
'title' => 'Address',
'description' => 'One record for each address',
'columns' => {
ADDRESSTYPE => [ 'fk', 'ADDRESSTYPE.ID' ],
DESCRIPTION => [ 'varchar', 200],
DNSNAME => [ 'varchar', 50 ],
ID => [ 'id' ],
NAME => [ 'varchar', 50 ],
NETMASK => [ 'varchar', 50 ],
OVERSION => [ 'version' ],
},
'primary_key' => [ 'ID' ],
},

As can be seen, the hash entry for ADDRESS is in fact an anonymous hash with entries for title, description, columns and primary_key. The following types are supported:

5.2 UIDesc.pm

This file defines the user interface for each type of Nets object. It is used by the ObjectEdit and ObjectList classes to construct the right type of user interface for each type of Nets object. In general terms, for each type of object, it specifies which database columns are to be displayed to the user, and how to display them. Many features of the user interface can be customized and controlled by changing the entries in UIDesc.pm

UIDesc.pm defines 2 hashes: %Nets::UIDesc::editors , and %Nets::UIDesc::listers . Editors defines the user interface for editing objects, used by ObjectEdit.pm. Listers defines the user interface for listing objects, used by ObjectList.pm. If there is no entry for a given object type, then no editing window or search/list window (as the case may be) can be created.

5.3 Site.pm

This file contains the initial values of various configuration variables that can be set within Nets. The Nets configuration in Site.pm can be overridden by a range of per-user and per-host sources, such as configuration files, command-line arguments, and User preferences in the database. Changing the configuration variables allows you to configure the default behaviour of Nets. Changing them in Site.pm makes those changes apply to all users who run Nets on the hosts where your Site.pm is installed, but still allows them to be overridden on a per-user or per-site basis.

Site.pm is amongst the last of the Nets support modules loaded when Nets starts up. It can therefore be used to override most functions and data within Nets.

You can also add site-specific code to Site.pm, and use that code to establish Hooks, change the user interface definitions or schema or change or override any code that is part of Nets. However, unless special conditions exist, we recommend that site-specific code be put in a Nets Plug-in (see Section 7.0 ).

6.1 obj_pre_load

Called just before an object is loaded from the database:

hook($type, $where, $order, ....)

• $type is the name of the object type (and also the database table name)
• $where is the SQL where clause that will be used to select the required object (typically something like ID=nnn)
• $order is an optional SQL order by clause

6.2 obj_post_load

Called just after an object is loaded from the database and a new Nets::Object instance created to hold the contents:

hook($type, $where, $order, $self, ....)

• $type is the name of the object type (and also the database table name)
• $where is the SQL where clause that will be used to select the required object (typically something like ID=nnn)
• $order is an optional SQL order by clause
• $self is a reference to the newly created Nets::Object

6.3 obj_pre_insert

Called just before a new object is inserted into the database:

hook($self, ....)

• $self is a reference to the object about to be inserted. $self->value(`ID') will not be set until after the object has been inserted.

6.4 obj_post_insert

Called just after a new object is inserted into the database:

hook($self, ....)

• $self is a reference to the object that has been inserted. $self->value(`ID') is set to the ID of the new object.

6.5 obj_pre_update

Called just before an existing Nets object is updated in the database:

hook($self, $oldobj, ....)

• $self is a reference to the new version of the object
• $oldobj is a reference to the state of the object the last time it was read from the database.

6.6 obj_post_update

Called just after an existing Nets object is updated in the database:

hook($self, $oldobj, ....)

• $self is a reference to the new version of the object
• $oldobj is a reference to the state of the object the last time it was read from the database.

6.7 obj_pre_delete

Called just before a Nets object is deleted from the database:

hook($self, ....)

• $self is a reference to the object that is about to be deleted

6.8 obj_post_delete

Called just after a Nets object is deleted from the database:

hook($self, ....)

• $self is a reference to the object that has just been deleted.

6.9 audit_insert

Called just before an event record is added to the Audit Trail (EVENT) table:

hook($etype, $otype, $oid, $desc, ....)

• $etype is the event type. See $Nets::Audit::ET_*
• $otype is the integer object type, which matches an entry in the OBJECTTYPE table
• $oid is the ID of the object that was affected by the event
• $desc is some descriptive text saying what the event was about

6.10 db_connect

Called just before a Nets::DBSQL connects to its SQL database:

hook($dbsource, $dbusername, $dbauth, ....)

• $dbsource is the DBI database source string, typically something like: `dbi:mysql:nets'.
• $dbusername is the username that will be used to log in to the nets SQL database
• $dbauth is the password that will be used to log in to the nets SQL database

6.11 log

Called when a Nets log event occurs:

hook($p, $s, ....)

• $p is the priority level of the log message, between $main::LOG_ERR and $main::LOG_DEBUG
• $s is the message associated with the event

7.1 Deferred loading of Plug-ins

Often a Nets Plug-in requires many other files to be ` require 'd or ` use 'd in order to support its features. This can have an impact on the time required for Nets to load and start running. You can reduce the effect of slow loading of large Plug-ins by using deferred loading. Using deferred loading, the Plug-in includes a single function that loads the main part of the Plug-in only when it is needed. You can then put the main part of the Plug-in in a second file (without the .npm) extension) and load it manually when your Plug-in function is called:

# mytestplugin.npm
$main::top->{file_menu}->command
(-label => 'Just testing',
-command => my_test_fn,
);
sub my_test_fn
{
require 'plugins/xxx.pm'; # Deferred loading
return Nets::XXX->new(@_);
}

8.1 File Format

A Load File is an ASCII text file that contains a sequence of multiline records. Here is a typical example:

# Nets database export Tue Mar 7 11:10:41 2000
Type:DEVICETYPE
ID:1
NAME:Cisco 3000

Type:DEVICE
ADDRESS:1
ASSET:A00001
COMMISSIONDATE:936280800
DESCRIPTION:Main router for Melbourne
DEVICETYPE:1
ID:1
INSTALLDATE:933602400
INTERNALTO:
LOCATION:1
MAINTAINER:
MANUFACTURER:
NAME:melcor1
NOTES:Leased from Cisco\nsecond line
OPERATINGSYSTEM:IOS 11.3
PURCHASEDATE:930924000
RACK:
SUPPLIER:

Any line beginning with a hash (`#') is ignored.

The first line specifies the type of record that follows:

Type:DEVICE

The record type must be one of the tables defined by Schema.pm, otherwise the rest of the record will be silently ignored.

The record is terminated by a blank line.

Following the record type line, there is one line for each column value. Columns that are defined in Schema.pm, but which are not present in the record are set to NULL. Columns that are defined in the record, but which are not defined in Schema.pm are silently ignored.

Each column consists of a column name followed by the data for that column:

COLUMNNAME:here is the data

Any `\n' that appears in the data will be replaced by a newline character.

8.2 Unique IDs

Most tables in the Nets database are defined in Schema.pm with one column of type `id'. Such ID columns are automatically maintained by Nets so as to ensure that column can serve as a unique identifier for each row in the table. When a database load file is loaded, Nets handles such ID columns specially.

If the load record does not specify a value for the ID column, Nets will automatically allocate a new unique ID for the new row.

If the load record does specify a value for the ID column, Nets will replace any existing row in the database of the same ID with the new record.

This mechanism means that you can choose whether to replace an existing record with the same ID, or to add the new record, regardless of what records are already in the database.

Using the idForName macro, you can also arrange to replace a record where you know the name, but not necessarily the ID:

Type:DEVICETYPE
ID:idForName(`Cisco 3000')
NAME:Cisco 3000

This code will replace any existing row in the DEVICETYPE table that has a NAME column of `Cisco 3000'.

8.3 Macros: Making relations between records

Nets load files permit a number of special macros for automatically setting IDs and foreign keys. These macros are intended to help in setting up relations between records in the SQL database. This allows you to ensure that when you create a DEVICE and its INTERFACES, for example, the DEVICE column in each INTERFACE refers to the ID of the newly created DEVICE. That way you can ensure mutual consistency between all the records created by a load file.

The following macros are supported:

10.1 DESCRIPTION File Format

Package DESCRIPTION files are ASCII text files that describe the Package, and specify what files are to be installed where, and what actions are to be taken at install time.

Line beginning with hash (`#') are ignored.

The file consists of a series of "keyword value" lines.

The following keywords are supported:

10.2 Bundling

A Nets Package consists of a directory containing a number of files, including at least a DESCRIPTION file.

It is common to want to send a Package to another Nets user, so that they can install the Package into their Nets system. The recommended way of bundling a package is in a gzipped tar file (also known as a tarball or tgz file). The bundle should be set up so that when the recipient untars it, it unpacks the package directory into the current directory. This can best be achieved by tarring the package from the next highest directory level. For example, imagine that you have made a Package that adds new network visualization tools to Nets. The Package consists of a number of file in the directory `visualiser' (including of course the DESCRIPTION file that says what is to be installed and where). If you are currently in the visualiser directory:

$ cd ..
$ tar cvf - visualiser|gzip -c >visualiser.tgz
visualiser/
visualiser/DESCRIPTION
visualiser/.....
.....
$

You can then send the visualiser.tgz file to anyone else to install into their Nets system. The recipient can then unpack and install the package with something like:

$ gunzip -c visualiser.tgz|tar xvf -
visualiser/
visualiser/DESCRIPTION
visualiser/.....
...
$ netspkginstall.pl visualiser
$

10.3 Examples

Here is an example that installs a new template file into the NetsDir templates file, and then adds a corresponding entry to the TEMPLATES table

• DESCRIPTION

# Example Nets package DESCRIPTION file
Name Example Package
Vendor Open System Consultants
Revision 1.1
Description Simple example of a Nets package

NetsDir templates/tnt.dat
PostInstall postinstall.pl

• postinstall.pl

# This is the postinstall perl script, which will be run
# after the files are installed. Adds an entry to TEMPLATES
# using a database load file
&Nets::Util::load
("$main::current_package->{InstallBase}/addtemplate.dat");

• addtemplate.dat

# addtemplate.dat
# Adds an entry to the TEMPLATES table
Type:TEMPLATE
DESRIPTION:A sample template which makes an Ascend TNT
FILENAME:tnt.dat
NAME:TNT device

• tnt.dat

# This template creates a TNT device
Type:DEVICE
DESCRIPTION:Ascend TNT
......

11.1 File Format

Nets scripts are ASCII text files containing Nets Scripting Language (NSL) commands. The conventional filename extension is .nsl , but scripts can be given any name you wish.

The following NSL commands are supported: