Netshot user guide

Overview

Netshot is a network device manager.

With Netshot, you can:

Many of the most used network devices in the world are supported out-of-the-box and you can easily add your own drivers - this is a simple script file to write.

Main interface

Netshot is available through a Web application GUI.

First you have to authenticate. The authentication settings must have been defined by the administrator. If nothing has been done since the setup of the database, the default account is netshot/netshot.

Login box

Once logged in, you can start using Netshot. A the top of the page is the main button bar, which allows you to navigate between the sections.

Click on your login at the right of the page to see your current permission level. You can also change your password (if using a local account) from this dialog.

Devices

Using the Devices section, you can browse the devices that Netshot manage, search for them or their data, start tasks to refresh their status or configure them, etc.

A device is a network equipment as seen by Netshot. Which type of device is supported or not by Netshot (vendor, family, collected data, automatic discovery and snapshots) depends entirely on the loaded device drivers.

Adding devices

Before adding any device, you must have created the required credential sets in the Admin page. You must have a read-write role to be able to add devices.

To add a single device:

To add a bunch of devices:

Searching for devices

You can simply find devices based on their name (or virtual name, e.g. VDC), or their IP address: just type it in the Search... box and type Enter.

To remove the filter, click on the Clear (cross) button.

You can also build advanced searches. Open the Advanced search dialog, and use the buttons to write a logical search string. Note that by selecting a type of device, you can filter on the device fields which are specific to this type.

Device groups

You can create groups of devices.

You must have a read-write role to be able to add, edit or remove groups.

To create a group, click on Add devices... drop down menu, and then on Add a group... When creating a group, you select the type of group, either static or dynamic (this can't be changed later). Then edit the group to start adding devices.

Select a group by clicking it in the group tree. The device list will be refreshed, and will display only the devices contained in the selected group. When a group is selected, the Edit and Delete buttons appear.

A static group needs each device to be manually selected and added. A dynamic group is based on a search logical expression. Dynamic groups are automatically refreshed whenever they are edited or devices change.

You can arrange your groups in a hierarchy: enter a folder path, e.g. Backbone A/Core devices/P routers. This will only affect only how groups will be displayed in the Devices page.

If you check the Hide this groups in reports box, the group can be used as any other group to filter devices or to apply compliance policies, but it won't appear in the reports.

You can delete a group, by clicking on the ad hoc button. Any associated policy or scheduled task would be deleted as well.

Device information

Click on a device in the left-hand side list to display it.

Device general information

The General tab gives the following information:

The Interfaces and Modules tabs are populated by the device driver during snapshots. The accuracy of this information will depend on how the specific driver for this device is coded and what be understood using the CLI of the device.

Configuration history

The Configurations tab gives the history of configurations of the device.

Configuration changes

Which items are contained by a configuration is defined by the device driver. Any information that may change over the time, and which changes are important to track should be stored there.

Click on a date to see the content of the configuration. Click on the Compare button to display the differences between two successive configurations, in a new window (ensure your browser is not blocking popups). Items of the configuration defined as comparable in the device driver are automatically compared and differences are displayed. You can navigate through successive changes by using the Previous and Next buttons at the top of the window. You can also compare two non-successive configurations: drag and drop the date of the two configuration entries onto the Drop to Diff targets on the right-hand side of the panel. Then click on the Compare button that should have appeared.

Differences between two configurations

Long text configuration items, like full running configuration of a Cisco IOS device, can be displayed in a new window by clicking on the View link, or can be directly downloaded as a file by using the Download link.

Device properties

You can edit some of the properties of the device by clicking on the Edit button (wrench icon) in the device view toolbar.

You must have a read-write role to be able to edit devices.

You can disable a device, by clicking on the relevant button in the device toolbar. No snapshot task will be executed over a disabled device. Click again on the button to enable the device back.

Snapshots

Scheduling snapshot tasks requires read-write permissions.

During a snapshot task, Netshot connects to the device (either by SSH or Telnet, depending on the available credentials, and also on what the specific driver supports.

Once connected to the device, Netshot delegates all the snapshot work to the driver.

Scheduling a device snapshot

Device compliance

The Compliance tab of the device view gives the compliance status of the device. The policies are defined in the Compliance main page.

Device compliance

There are several compliance parts:

The compliance status of a device is automatically refreshed after each snapshot however you can force it to be reevaluated by clicking on the Recheck compliance button and starting the task. This requires read-write role.

Device tasks

In the Taks tab of the device view, you can see the last tasks related to the device. You can see the details of a finished task, including its logs, and cancel a scheduled task before it is actually executed.

Selecting multiple devices

You can select multiple devices in the device list on the left:

Selecting multiple devices

When you select several devices in the device list, you get the Multiple devices selected panel in the right. There you can do actions that will apply to all selected devices. However you should note that applying actions to a very high number of devices (e.g. several hundreds or thousands) can be quite slow.

When scheduling a script to be run over several devices, you have to select the device type (driver) your script refers to. Only devices of this selected type, among the ones you've selected, will actually be processed.

Starting actions on multiple devices requires read-write permission level.

Running a script

Device scripts allows you to program commands to be sent to a device or a set of devices. The scripts are written in Javascript language, which is well documented over the Internet. Passing simple commands to a network equipment can be done with a few lines only, and doesn't require real programming skills.

To run a script over a device, click on the Run script icon in the device toolbar.

Running a script

Running scripts requires read-write permissions. Obviously, you have to be very cautious with the commands you run over your network devices. Netshot won't check anything, it will simply execute what you write, even if this breaks the target device.

The entry point in the script is the run function. This is what Netshot will call, with the following parameters:

For example, the Cisco IOS driver defines the configure macro which brings you to the configure well-known mode, where you can enter configuration commands that will apply to the running configuration. It also defines the end macro to quit the configure mode, and the save macro to copy the running to the startup configuration. Thus to change the description of interface GigabitEthernet0/0/16, run the following script:

function run(cli, device) { cli.macro("configure"); cli.command("interface GigabitEthernet0/0/16"); cli.command("description New description"); cli.macro("end"); cli.macro("save"); }

The following script gets the actual OSPF router-id and writes it into the device comments:

function run(cli, device) { cli.macro("enable"); var protocols = cli.command("show ip protocols"); var idPattern = /Routing Protocol is "ospf(.|\r|\n)+? Router ID ([0-9\.]+)/; var match; if (match = idPattern.exec(protocols)) { var rid = match[2]; device.set("comments", "OSPF Router ID = " + rid); } }

Policy, rule and compliance

The purpose of the Compliance section is to keep your devices in a mastered state: any device not conforming to your own policies will be flagged so you can act and fix it.

Once the rules are defined within Netshot, the status of a device is refreshed by running a Check compliance task. This can be done manually by scheduling such a task, and anyway this is automatic after each snapshot task, to ensure that a device becoming not compliant after a configuration change is immediately flagged.

The software compliance status can be seen in the Compliance tab of the device view, or at the global level in the Software compliance report.

Creating, deleting or modifying policies or rules requires read-write permissions.

Software rules

The software rules are simple rules which assign a level (Gold, Silver or Bronze) to a device, depending on its software version. The software version of a device, which can be seen in the General tab of the device view, is written by the device driver during the snaphots.

When evaluating the software compliance status of a device, the rules are processed in order (from top to bottom as seen in the Software version compliance table). The first rule whose criteria match the device's properties assigns its level to the device, and the process stops here.

If no rule is matched, then the device is non compliant.

To create a software rule, go to the Compliance main page, select the Software section then click on the +.

You can reorder the rules by dragging and dropping a line in the Software version compliance table.

Hardware rules

Hardware rules aim at following up the support status of the hardware components of devices. An hardware rule defines the end of sale and end of life (end of support) dates for a specific part number. To evaluate the hardware support status of a device, Netshot selects the earliest date for end of sale, and for end of life among the contained cards (hardware modules).

To create an hardware rule, go to the Compliance page, select the Hardware section, and click on + to add the rule.

Configuration policies and rules

Apart from software and hardware rules, you can create advanced rules that will check the configuration or other attributes of the devices.

First you need to create a policy, which will contain the actual rules. A policy applies to a group of devices. If you want to assign a policy to all devices, just create a dynamic group without criteria, so it will contain all devices.

To create a policy, click on the Create policy... button in the main toolbar. To edit or delete a policy, select it first, the buttons will appear.

Once you have the policy, select it and click on the + button to add a rule. Note that the new rule is disabled by default, you have to edit it to enable it.

To edit a rule, select it and click on the Edit (wrench icon) button. You can enable or disable it, and add exemptions. To add an exemption, enter the name of the device in the search field, select the device among the results, select the end-of-exemption date, and click on the arrow button.

A rule will check the device attributes and return one of the following:

There are two types of rules: text-based (or regular expression) rules and script-based (Javascript) rules.

Text-based rules

Text-based rules just check that a specific attribute of the device (most of the time, the running configuration) matches some text, or a regular expression.

Text-based rules

For example, in Cisco IOS if you want all interfaces to have a description, define a rule as follows:

Other example, in IOS-XR, if you want all GigabitEthernet interfaces of OSPF to be configured as point-to-point:

Script-based rules

The script-based rules are Javascript code.

Click on Edit the script... to open up the JavaScript editor. While you are writing your script, you can test it on a specific device by selecting a device at the bottom of the editor and clicking on Test.... Click on the underlined result to see the logs.

Here is a basic (and useless) rule, which will set all devices compliant:

function check(device) { return CONFORMING; }

The function check(device, [debug]) must exist in the code, this is the entry point, which will be called whenever the device must be validated by the rule.

The check function must return one of the following special values:

You can also return the same value along with a text message, that would appear in the device compliance status, mainly to indicate why the device was not compliant:

return { result: NONCONFORMING, comment: "VTY ACL not applied" };

Reports

The Reports section gives an overview of the network status by aggregating data collected by the other modules.

Configuration changes

The Configuration changes report shows the configuration changes detected by Netshot over the last hours or days, or on a precise day.

Configuration changes

Note that the change date/time is the moment when Netshot took the snapshot, not the precise time of the change itself. Even if the snapshot was automatically taken after a detection of the change, it occurred several minutes after the actual change. Also, if several changes were made to the configuration of the devices within a few minutes, Netshot probably saw a single change only.

Device access failures

The Device access failures report lists the devices which haven't been successfully backed up by a snapshot task for the last X days, where X can be selected using the numeric field (3 by default). Change the number of days and click the Update button to refresh the list.

The disabled devices are excluded from the list.

The purpose of this report is to easily identify which devices are not responding to Netshot snapshot attempts anymore.

Configuration compliance

This report gives the compliance percentage for device groups. A device is flagged as non compliant so long as it doesn't pass at least one rule.

If you click on a group, you'll see the list of non conforming devices.

If a group of devices doesn't appear in the compliance reports, this is probably because it was marked as hidden. Edit it in the Devices section to change this.

Software compliance

This report will give you, for each group of devices, the percentage of Gold, Silver, Bronze and non compliant devices, resulting from the software rules defined in the Compliance section.

Click on a category in the legends to display the matching devices at the bottom of the page.

Hardware support status

This report will give the trend of hardware support with time. This is based on end of sale and end of life dates that you have defined for part numbers in the Compliance section. When an hardware module becomes end of sale (or life), any device with such a module becomes itself end of sale (of life). The graph in the Hardware support report gives the number of end of sale and end of life devices, increasing with time. The milestones (dates when bunches of devices become end of sale or life) are listed below the table. If you click on the number of devices, you'll get the actual corresponding devices.

Data export

You can export data collected by Netshot into an Excel file.

The options are self-explanatory. Click on Download the result to generate and get the file. The generation of the file could take a few minutes if there are many devices in the database.

Tasks

In the Tasks section, you can see the current tasks, and also schedule global tasks.

You can see the running, scheduled (waiting), succeeded, failed, cancelled tasks, by clicking on the proper tab. For the passed tasks, today's tasks only are displayed by default, but you can select another day to see the history.

Click on the first button to refresh the list of tasks.

You can schedule a global task by clicking on Schedule... in the main toolbar.

If you want to look at the task history of a specific device, you can see it in the Task tab of the device in the Devices view.

Administration

Netshot configuration file

Some global options can be configured in the Netshot configuration file.

When started, Netshot will try to find and read a file called netshot.conf in the current directory, then /etc/netshot.conf if the first one wasn't found. If this file is not found at all, Netshot won't start.

In the configuration file, each line must be of the form:

parameter = value

If a line starts with #, it will be ignored.

Netshot needs to be restarted after a change to the configuration file so the new parameters are taken into account.

Logging configuration

Database configuration

Embedded HTTP server

Syslog server

The embedded Syslog server listens for Syslog messages to detect when changes are made on devices.

You can choose to make Netshot listen for Syslog on port 1514 (non root user) and use iptables to rewrite the destination port. See the installation guide.

SNMP trap receiver

The embedded SNMP trap receiver listens for SNMP traps to detect changes on devices.

You can choose to make Netshot listen for SNMP traps on port 1162 (non root user) and use iptables to rewrite the destination port. See the installation guide.

User authentication

Drivers

Snapshots

General

Authentication

Netshot supports both local and remote accounts. Local means the authentication process stays local to Netshot (the user is stored in the local database) while remote means that authentication is delegated to a RADIUS server.

When an user tries to log into Netshot, Netshot first looks for a local account in the database. If the local account exists, it checks the password and accepts or denies the user based on that, with the assigned permission level. If the local account doesn't exist, and at least one RADIUS server is configured, Netshot will try a RADIUS challenge. If RADIUS fails, then the user is rejected. If it succeeds, the user is allowed as visitor by default. If the RADIUS response contains a Service-Type attribute equals to AdministrativeUser (well known value), then the user is allowed as admin. If the Service-Type attribute equals to NASPromptUser then the user gets read-write permissions. However if the user exists in the database as remote user, and has been successfully authenticated by RADIUS, then the permission level locally assigned to the account will override the RADIUS-provided level.

To enable local authentication, simply create local accounts in the Admin page.

To enable RADIUS authentication, you have to declare the server(s) in the Netshot configuration file. You can have up to 3 servers. They will be tried one by one until one responds. For instance:

netshot.aaa.radius1.ip = 1.2.3.4 netshot.aaa.radius1.authport = 1812 netshot.aaa.radius1.secret = MyKey#1 netshot.aaa.radius2.ip = 1.2.3.5 netshot.aaa.radius2.authport = 1812 netshot.aaa.radius2.secret = MyKey#1

See the configuration section for more details.

Device domains

When adding a device to Netshot, you must associate it with a management domain. A management domain defines a set of parameters that will apply to the associated devices.

The device domains are created in the Admin page. A domain can't be deleted if it contains any device or is associated to a specific credential set.

Device credentials

The credentials used to access devices are globally managed from the Admin page.

You can create SNMP v1, SNMP v2c, Telnet and SSH (versions 1.5, 1.99 or 2.0) credential sets. SNMP v3 is not supported at the moment.

The SSH authentication can either use a simple password, or can be key-based. To add an SSH key credential set, you need the public and the private RSA key couple. Assuming you've generated the keys using ssh-keygen, just copy and paste the content of the files, ~/.ssh/id_rsa (private key) and ~/.ssh/id_rsa.pub (public key).

The credentials as stored in clear text in the Netshot database, so it's important to ensure the access to the Netshot database and to its hosting server is properly secured.

If you associate the credential set to a management domain, it will automatically be used only by the devices of the domain. If you don't specify a management domain, any device will be able to use it.

When adding a device to Netshot, the available credential sets will be tried in turn. The working credential set will be saved as the main one for the device.

Device types

The Admin page lets the administrator dynamically reload the Javascript driver files.

By clicking on the Reload the drivers button, the driver files will be scanned and reloaded, so any change made to them will be taken into account by Netshot.

Device drivers

Each supported type of device in Netshot rely on a single JavaScript file, which is often called driver. This file describes the special attributes of the device type (e.g. running config and configuration register for a Cisco IOS device), and contains runnable code that will be executed when interacting with the device (e.g. taking a snapshot of the device).

Driver location

The Netshot package (especially the .jar file) contains several built-in drivers for some well known network device operating systems. These drivers are automatically loaded from the package without further action, which makes Netshot able to manage most of the router and switch devices out of the box.

Netshot also automatically loads drivers from the file system, which allows you to add your own driver files, by placing them in the directory defined in the Netshot configuration file by netshot.drivers.path.

If you want to make changes to an existing built-in driver, you can extract it from the .jar file, and copy it to the driver directory. The driver loaded from the file system has priority over the built-in driver.

The drivers can be dynamically reloaded while Netshot runs from the Admin page.

Driver structure

A driver is a JavaScript file.

A driver must contain the following global objects: