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
Thats all. Now you see the device once you login into the Percival
as user guest.
konfne -af --ip <your router ip> --community <snmp community> cfg /Tree/Routers/dummyname
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''.
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:
- has system wide settings such as skin, location of rrd
files and others
- has default system profile. The only way to change administrator
username or password is to edit this file.
- contains settings for all system services. overlord.pl
is the preferred way to manage it.
- 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.
- directory contains all currently configured network devices.
It also contains instructions how devices should be processed.
- is root of preconfigured guest profile.
NOTE: remember to run kompile if you changed database manually.
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:
- device might be snmp scanned
- device global configuration is placed under /Devices according
to element classes. For example Router may have interfaces and chassis.
Interfaces are placed under /Devices/Interfaces/<routername>/
and chassis configuration is placed under /Devices/Routers/.
Some devices, such as report, may not have global configuration.
- If global configuration already exists, it is updated.
- Links and other needed device elements are created in the specified
konfne has following basic commands:
- 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.
- show help for specified device or path. To get help
for profile configuration you can do:
konfne help Devices::Virtual::Profile
konfne help /Tree
- will configure new device or update already configured
- deletes profile visible device configuration. Device
is still collected.
- 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.
- deletes device configuration from profile, from
the database and removes all collected data.
- check if device is responding to SNMP
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:
- Nested profiles are not allowed
- All devices, except folders, must be created under profile
- Profiles with the same root are not allowed
- Profile name must be unique
Device Devices::Virtual::Profile provides all necessary profile management.
- Profile name. In this document it is also referred as user name.
- Profile password
- Profile root. The closes analogy to profile root is user home directory
Profile has following device specific options:
Example of creating new profile foobar with the root at /MyProfiles/FoobarTree:
- specifies profile name
- specifies profile authentication mode. Only local
mode, which is a default, is supported in the Percival
- if option is present and equal to true profile
user can use Merlin to manage profile.
- can be either true or false. If present and
is true then graph legend is displayed under the graph in MRTG like
- 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.
konfne --device Devices::Virtual::Profile -t profile=foobar -t password=secret -t 'alt-legend=true' cfg /MyProfiles/FoobarTree
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
Every Percival device must support following standard options:
- if specified it overrides device name specified
in the path. Unlike path it may have embedded HTML tags and spaces.
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
- configure only named interfaces. That is interfaces
which have description set in ifAlias.
- 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.
- 64 bit counters can be used if interface
speed is greater then specified threshold. Speed is given in megabits.
Default speed value is 100M.
- 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.
- 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.
- only configure interfaces that match given
- 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.
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
CISCO routers are configured with the Devices::Routers::Cisco device.
The devices has following options:
- normally PPTP sessions are ignored unless
the value of this option is true.
- 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.
- normally interfaces with the world ``virtual''
in ifDescr are skipped unless this option is true.
- user on the router for doing login. This is
needed for configuring either BGP or Pings.
- password of the user that was specified
with previous option
- configure pings from Cisco router. The option accepts
coma separated list of ips or hostnames.
CISCO IOS switches are configured with Devices::Switches::IOS. The
device does not have any specific options.
CISCO Catalyst switches are configured with Devices::Switches::Catalyst.
There are no device specific options.
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
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
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:
- gather service uptime statistics. Accepts
coma separated list of services.
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.
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
- report type. There are several builtin reports:
- 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.
- sort interfaces by error count over the period of
time. Presence of errors on the interface usually indicates hardware
- 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.
- show interfaces that are consistently utilized
with over 70% of capacity.
- inverse of previous report.
- how many results to show. Must be positive number.
- detailed report description. HTML tags may be used
- how to process data. Can be either AVERAGE or MAX.
- sort report in either ascendant or descendant order.
Can be either asc or desc.
- range of report in seconds.
- specifies on what devices to report. Subtrees
are specification is absolute to the configuration root. Subtrees
are in coma separated list.
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:
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.
- defines long description of the total. HTML tags
and spaces are allowed.
- list of subtrees to search for report targets.
- match target name based on given regexp. Must be
used with the subtree tag.
- coma separated list of targets.
- report type. Can be one of the following:
- show small graphs for every interface or other target
on one page.
- show graph that sums all information.
- show stack graph for all interfaces
- show graph that averages all information.