Next Up Previous Contents
Managing Devices

3.3 Managing Devices

By the time you get to this section you dont want to read anything about processes, commands, daemons and options. You want to add your new Cisco router to the Percival NOW. This is how you do it:

konfne -af --ip <your router ip> --community <snmp community> cfg /Tree/Routers/dummyname
Thats all. Now you see the device once you login into the Percival as user guest.

Percival configuration is based on the concept of the ``device''. Device can be a router, computer, switch or other network element. In this case we call it ``real'' device. There is another class of device such as reports, summary graphs(totals), profile etc... These devices can be created based only on information in the database. We call such devices ``Virtual''.

3.3.1 Configuration Database Basics

Percival keeps its configuration information in the hierarchical(tree) database. The database is completely text based. It makes it very easy to backup and you can modify it using standard Unix CLI tools. Each user has its own view of the database.4

Percival converts textual database into binary format. Lancelot uses alternative implementation of the database , called HDB, that works directly over text files. kompile converts database into binary form usable by Percival and konfne. konfne works on both binary and text database.Thus you don't need to worry about keeping database copies in sync with each other.

The database is located in /usr/local/percival/etc/lancelot-config directory. Directory in the filesytem represents directory in the database. However one file can have several database child nodes. Each database entry can have many properties in form of attribute=value pairs. Node attributes can be inherited. Database node may have a reference (link) to another node. It work pretty much as symbolic links in Unix or shortcuts in Windows.

Percival and Lancelot come with several preconfigured database entries:

Defaults
has system wide settings such as skin, location of rrd files and others
SysProfiles
has default system profile. The only way to change administrator username or password is to edit this file.
daemons
contains settings for all system services. overlord.pl is the preferred way to manage it.
profiles
contains definitions of Percival users. Percival comes with preconfigured with guest account with the root at /Tree. konfne is the preferred way to manage users.
/Devices
directory contains all currently configured network devices. It also contains instructions how devices should be processed.
/Tree
is root of preconfigured guest profile.

NOTE: remember to run kompile if you changed database manually.

3.3.2 konfne Basics

konfne will be your main tool for managing Percival. When you configure new or already existing devices several things happen:

konfne has several standard options:

--devlist
shows all available devices
--autotype or -a
guess device type automagically
--ip or -i
device ip address or hostname
--community or -c
device SNMP community. If not specified defaults to public
--fetchname or -f
fetch device name from sysName. Everything after the last / in the path is replaced by the fetched name
--recursively or -r
apply command to all devices in specified subtree. Usually used for automatic reconfiguration of already configured devices. For example, konfne -r /Tree will reconfigure whole guest profile.
--tag or -t <attribute>=<value>
apply device specific parameters. Each device may have specific configuration options.
konfne has following basic commands:

help
show help for specified device or path. To get help for profile configuration you can do:
konfne help Devices::Virtual::Profile
or

konfne help /Tree
cfg
will configure new device or update already configured device
del
deletes profile visible device configuration. Device is still collected.
DELETE
deletes profile visible device configuration and delete global device configurationtion. There is no concept of device usage count. So if you have device configured in other profiles it will stop working there. Already collected data are not removed.
DEMOLISH
deletes device configuration from profile, from the database and removes all collected data.
probe
check if device is responding to SNMP

3.3.3 Managing User Profiles

Percival supports concept of user. Each user must have different profile. For example, you can have one profile with the access to all of your routers. On the other hand your customer profile will give access only to specific router interface. Profile creation is governed by several simple rules:

Profile has three basic parameters:

  1. Profile name. In this document it is also referred as user name.
  2. Profile password
  3. Profile root. The closes analogy to profile root is user home directory in Unix.
Device Devices::Virtual::Profile provides all necessary profile management.

Profile has following device specific options:

profile
specifies profile name
auth
specifies profile authentication mode. Only local mode, which is a default, is supported in the Percival
editable
if option is present and equal to true profile user can use Merlin to manage profile.
alt-legend
can be either true or false. If present and is true then graph legend is displayed under the graph in MRTG like style.
su-allowed
user of this profile can switch to another profile without performing an authentication. This is mostly useful for large installation when you want to have 'master' account.
Example of creating new profile foobar with the root at /MyProfiles/FoobarTree:

konfne --device Devices::Virtual::Profile -t profile=foobar -t password=secret -t 'alt-legend=true' cfg /MyProfiles/FoobarTree

3.3.4 Automatic Configuration of Network Devices

Percival has ability to automatically detect type of the network devices and invoke correct device module. Auto-detection works in many cases and is the easiest way to add new equipment. The downside of auto-detection is that you can not pass device specific options to the konfne. The auto-detection will not work for virtual devices.

This is how you autodect device:

konfne --autotype --ip <ip> --community <secret> cfg /Tree/Routers/myrouter

3.3.5 Standard Device Options

Every Percival device must support following standard options:

display-name
if specified it overrides device name specified in the path. Unlike path it may have embedded HTML tags and spaces.

3.3.6 Configuring Generic MIB2 Device

Almost any SNMP manageable equipment implements MIB2. Percival uses MIB2 to obtain netwrok interface statistics. If there is no specific Percival device for your equipment you can use Devices::Routers::Generic to obtain traffic statistics.

Options supported by Devices::Routers::Generic must be supported by any other device dealing with network interfaces. Following options are supported:

namedonly
configure only named interfaces. That is interfaces which have description set in ifAlias.
config-v2c
if true, try to use 64 bit high performance counters (ifHCInOctets, ifHCOutOctets) for the high speed interfaces. Device checks if interface can really return high speed counters. In our experience ther are a lot of problems with 64 bit counters on CISCO routers. Care must be taken when invoking this option.
config-v2c-speed
64 bit counters can be used if interface speed is greater then specified threshold. Speed is given in megabits. Default speed value is 100M.
use-if-name
by default ifDescr is used to get interface names. Some devices may have identical ifDescr but different ifName. In this case this option should be set to true.
if-types
list of symbolic interface types that should be configured. Interface will not be configured if this option was specified and interface type does not match.
if-match-regexp
only configure interfaces that match given regexp.
keepabsent
do not remove interface from configuration if it does not present on router anymore. Instead the interface is marked as ``frozen''. It will have word frozen added to the description and its default graphs will display will end at the time the interface was ``frozen''. This feature is useful to keep graph of old lines.

3.3.7 Configuring CISCO Equipment

It is well known fact that majority of the network equipment is manufactured by CISCO. Percival and Lancelot have very good support for the CISCO routers and switches, including advanced features such as SAA, Netflow and Quality of Service monitoring.5

3.3.7.1 Cisco Routers

CISCO routers are configured with the Devices::Routers::Cisco device. The devices has following options:

setup-pptp-session
normally PPTP sessions are ignored unless the value of this option is true.
ppp-names
normally interfaces with ifType ppp are not configured. This option accepts a regular expression. If the expression match interface name as given in ifDescr and interface type is ppp then interface will be configured.
config-virtual
normally interfaces with the world ``virtual'' in ifDescr are skipped unless this option is true.
telnet-login
user on the router for doing login. This is needed for configuring either BGP or Pings.
telnet-password
password of the user that was specified with previous option
pings
configure pings from Cisco router. The option accepts coma separated list of ips or hostnames.

3.3.7.2 Cisco IOS Switches

CISCO IOS switches are configured with Devices::Switches::IOS. The device does not have any specific options.

3.3.7.3 Cisco Catalyst Switches

CISCO Catalyst switches are configured with Devices::Switches::Catalyst. There are no device specific options.

3.3.8 Configuring Linux

We support UCD-SNMP or NET-SNMP agents on linux. We have encountered problems with the packaged snmp agent on RedHat 7.3. You can download our build of NET-SNMP that fixed that proble from percival site on SourceForge.

Linux computers are configured with Devices::Computers::Linux. There are no device specific options. Linux device supports monitoring of CPU load average, memory and disk usage in addition to the interface monitoring.

3.3.9 Configuring Windows 2000

Percival can configure Windows2000 with Host MIB or with Compaq Insight Manager MIB. The correct MIB is auto-detected. Windows 2000 computers are configured with Devices::Computers::Win2000. Device supports monitoring of CPU, memory and disk usage.

The device has following options:

process-watchdog
gather service uptime statistics. Accepts coma separated list of services.

3.3.10 Configuring Windows NT

NT has very basic SNMP support. To get advanced statistics you must install SNMP4C from www.wtcs.org cess-watchdoghttp://www.wtcs.org. Windows NT computers are configured with Devices::Computers::WinNT. There e are no device specific options.

3.3.11 Configuring Reports

Reports in Percival provides you with high level system summary. Using reports you will be able quickly determine problems in your network and zoom to the problem area to view detailed statistics. Reports are configured with Devices::Virtual::Report. Following options are supported:

type
report type. There are several builtin reports:

utilization
compares network interface utilization over the period of time. Utilization is computed as traffic/bandwidthwhere bandwidth value is take from ifSpeed of the interface. Results will not be valid if your interface speed is set wrong.
errors
sort interfaces by error count over the period of time. Presence of errors on the interface usually indicates hardware problems.
discards
sort interfaces by discarded packets over the period of time. Packets are discarded when router queue is getting long. Presence of discard indicates routing problems or lack of bandwidth.
overloaded
show interfaces that are consistently utilized with over 70% of capacity.
idle
inverse of previous report.
limit
how many results to show. Must be positive number.
desc
detailed report description. HTML tags may be used here.
archive
how to process data. Can be either AVERAGE or MAX.
sort
sort report in either ascendant or descendant order. Can be either asc or desc.
range
range of report in seconds.
subtrees
specifies on what devices to report. Subtrees are specification is absolute to the configuration root. Subtrees are in coma separated list.

3.3.12 Configuring Totals

Percival has ability to combine several graphs into one. This is useful when you want to see average utilization of some several interfaces, or your total international traffic or to see all graphs on one page. Device Devices::Virtual::Total provides this functionality. It can be configured with following options:

long-desc
defines long description of the total. HTML tags and spaces are allowed.
subtrees
list of subtrees to search for report targets.
regexp
match target name based on given regexp. Must be used with the subtree tag.
selection
coma separated list of targets.
type
report type. Can be one of the following:

report
show small graphs for every interface or other target on one page.
sum
show graph that sums all information.
contrib
show stack graph for all interfaces
avg
show graph that averages all information.
Percival is smart enough to figure out how to aggregate information from different devices. The details of this process are out of the scope of this manual.


Next Up Previous Contents