“genDevConfig” Reference
                       The Cricket device profile generator
This document is provided as-is for i...
Using genDevConfig from the command-line.............................................................................9
  H...
Many contributors helped get the script where it is now, consult the CREDITS file in the genDevConfig
distribution to view...
Cricket components diagram with genDevConfig

Here is the diagram which illustrates the Cricket components with genDevConf...
•   Cisco CSS 11000 load-balancer
   •   Nortel Accelar switches
   •   Nortel Contivity VPN concentrators
   •   Cisco wi...
How can Cricket and genDevConfig integrate with my other network
management systems

Cricket, thanks to genDevConfig can e...
•   lib/genConfig/File.pm                        # Utility library for genDevConfig
    •   lib/genConfig/SNMP.pm         ...
Generating your first device profile

### Step 1

Find out the community string and IP address of the device you want to r...
Additional installation resources for genDevConfig
Additional resources have been created by genDevConfig users to help in...
How to get information necessary to create a plugin

A simple plugin that can be used as a starting point: NortelAccelar
C...
- $script : Brief online description of what devices this plugin tries to cover.


- sub can_handle : Here you can choose ...
$nortelbox = 1;

Example code from NortelAccelar.pm.


Handling custom interface statistics

Then, in the non-interface ta...
All rights reserved by Francois Mikus.
genDevConfig documentation
Upcoming SlideShare
Loading in …5
×

genDevConfig documentation

415 views
381 views

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
415
On SlideShare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
3
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

genDevConfig documentation

  1. 1. “genDevConfig” Reference The Cricket device profile generator This document is provided as-is for informational purposes only. Francois Mikus, nor Acktomic are responsible for damages that may result from using this documentation. Written by: Francois Mikus ; fmikus at the domain called acktomic dot com. Summary genDevConfig is a profile generator for use with the Cricket network management system. It will create a unique profile based on the type of device being targeted and its services. genDevConfig is a versatile and extensible network script that exploits the power of Cricket to provide a fast and simple way to manage hundreds of network devices. The premier profile generator for Cricket is genDevConfig for the following reasons: • Flexible options to cover varied collection needs • Integrates seamlessly with threshold collection • Writing and sharing device recognition plugins with others has never been easier • Distributed with cricket itself (currently in cricket CVS) • Hierarchical output for devices with hundreds of interfaces • Device agnostic; creates profiles for servers, ups's, switches, routers, firewalls • Replaces the other profile generators meant to be used with cricket such as: listinterfaces, genCatConfig, genRtrConfig and CHIRP. The two notable exceptions are perfmon for windows based devices and a number of devices that have not been integrated from CHIRP. • Support for many common devices out of the box. Table of Contents Summary.......................................................................................................................................1 Table of Contents..........................................................................................................................1 Why use a profile generator for Cricket.......................................................................................2 Where does genDevConfig fit within the Cricket network management system.........................2 Cricket components diagram....................................................................................................3 Cricket components diagram with genDevConfig...................................................................4 Cricket detailed device configuration life cycle.......................................................................4 What devices or platforms does genDevConfig support..............................................................4 How can Cricket and genDevConfig integrate with my other network management systems....6 Obtaining genDevConfig..............................................................................................................6 Elements of genDevConfig.......................................................................................................6 Installation................................................................................................................................7 Generating your first device profile..........................................................................................8 Output from a device profile generation...................................................................................8 Additional installation resources for genDevConfig....................................................................9
  2. 2. Using genDevConfig from the command-line.............................................................................9 How to develop a new plugin.......................................................................................................9 Development guidelines...........................................................................................................9 How to get information necessary to create a plugin.................................................................10 Writing a basic genDevConfig plugin........................................................................................10 Instructions on setting up a basic plugin.................................................................................10 Handling the device discovery................................................................................................11 Handling custom interface statistics.......................................................................................12 Handling custom non-interface statistics................................................................................12 Following the genDevConfig target creation process................................................................12 Why use a profile generator for Cricket First a little bit of background on Cricket. It is a configuration, polling, and data-display engine wrapped around the RRD tool by Tobias Oetiker. There are three user-visible pieces to Cricket: the collector, the grapher, and the config tree. The collector runs from cron and fetches data from a number of devices according to the info it finds in the config tree. The grapher is a CGI application that allows users to traverse the config tree from a web browser and see the data that the collector recorded. To use Cricket you need to do these things: * make a config tree * setup the collector to run on a regular basis * setup the grapher to let you look at the data Cricket is a network management system that includes a very powerful hierarchical configuration system with built-in inheritance. The configuration system is similar to XML, yet is much simpler to understand and use. This flexibility provides the means to collect information of simple devices and complex devices without having to create hundreds of big configuration files. Once a device’s characteristics are defined, it is only its specific details which need to be input, things like its name, ip address, snmp community and other attributes. While cricket itself does a wonderful job in using the configuration tree, it is not so good at actually filling in the device specific information in the configuration tree itself. To maintain up to date system information on hundreds of different devices of varied type and capability becomes a somewhat onerous task. Such information as new services enabled, changes in interface descriptions, snmp-community or interfaces state changes. The profile generator meets this need of creating full featured configurations tree branches and leaves that contain all the information that you need from your devices. Cricket can then do what it does best, use the configuration tree information to collect statistics from all types of services using local files, SNMP, scripts and even local functions. And ultimately to display this information in a very fast and reliable web interface. Where does genDevConfig fit within the Cricket network management system The cricket network management system collects and displays information about devices. genDevConfig facilitates the configuration portion so that Cricket can collect the information. genDevConfig also enables collecting and displaying more detailed and accurate information about the devices themselves.
  3. 3. Many contributors helped get the script where it is now, consult the CREDITS file in the genDevConfig distribution to view get a full list as well as a description of its origins. It is important to mention that without earlier the work of Mike Fisher and Tobias Oetiker genDevConfig would not exist. Cricket components diagram Here is a diagram which illustrates the Cricket components including user interaction:
  4. 4. Cricket components diagram with genDevConfig Here is the diagram which illustrates the Cricket components with genDevConfig including user interaction Cricket detailed device configuration life cycle Here is a more detailed diagram showing a typical configuration cycle for a device. N/A What devices or platforms does genDevConfig support Supports a wide range of networked devices • Cisco IOS series routers (800, 1x00, 2x00, 3x00, 4500, 7xxx, 7500VIP, GSR, CRS-1) • Cisco IOS Catalysts (5K, with RSM/MSFC2) • Cisco CatOS Catalysts (4K, 5K, 6K) • Cisco IOS series switches (1900, 29x0, 3x50, etc.) • Cisco Altiga VPN concentrators (3015, 3030, 3060) • Cisco PIX firewalls (Full line 501, 501E to 535, ASA, FWSM)
  5. 5. • Cisco CSS 11000 load-balancer • Nortel Accelar switches • Nortel Contivity VPN concentrators • Cisco wireless Aironet access points and bridges • Juniper Routers • Foundry ServerIron load-balancers and switches • Packeteer traffic shaping appliances • Netscreen firewalls • Sensatronic environmental monitors • Unix server hosts with the UCD-SNMP / NetSNMP host MIB Supports all network devices using standard MIB-II • System Description • Contact Information • Location • Basic interface stats (octets, packets and errors) • Global packet per second statistics • Interface descriptions based on ifAlias or ifName • Threshold application and monitoring Recognizes the following features in compliant network devices • Disk space usage • Server CPU usage • 802.1Q/ISL trunked interfaces • Frame-relay, ISDN, HDLC interfaces • Ethernet, FastEthernet, GigabitEthernet, ATM • Serial interfaces (DS1/T1/E1, DS3/T3/E3, TDM) • Service Assurance Agents or RTR using ICMP, HTTP, FTP, Jitter, udp-echo • Sub-interfaces • Chassis statistics (CPU, Memory, Temperature) • Layer2 switch fabric statistics(Cisco CatOS, Cisco IOS) • VPN Tunnels statistics • Wireless communication statistics (Cisco Wireless products) • Firewall statistics • Intelligent High-Capacity counters for high speed interfaces • CAR based QoS shaping statistics • Class based QoS shaping statistics • VIP/Server statistics for load-balancers • MPLS statistics • Voice over ip dial-peer statistics • Environmental data for probes
  6. 6. How can Cricket and genDevConfig integrate with my other network management systems Cricket, thanks to genDevConfig can easily provide data integration with other network management systems. It can do this by making data accessible within the cricket infrastructure itself using standardized tools. genDevConfig provides the following facilities - storage of user defined data(URLs, pager groups, device classes, support information, etc) directly from the command-line - data can be stored in both the interface targets and the chassis target - automated application of threshold monitoring based on device classes, interfaces, technologies and configurable parameters - centralized configuration of monitoring rules - logically organizing device data under a common format Cricket also has built-in capabilities which can ease the integration with other management systems - all alarms are directly accessible using a standard config-tree access script (or piece of code) - all alarm events are available immediately after the collection process has been completed - device data can be consulted using a standard config-tree access script (or piece of code) - all alarms can be exported in near real-time using SNMP, user defined functions or by email. - the web based interface can tie back into other systems using URLs - authoritative data can be shared with other systems or imported into Cricket via the APIs or genDevConfig Obtaining genDevConfig The configuration profile generator is included in Cricket versions above 1.05. If you are not running the latest cricket version; get genDevConfig from the Cricket CVS or from www.acktomic.com. Elements of genDevConfig All the directories and file categories contained in the genDevConfig distribution. • util/genDevConfig # The script • util/CHANGES # Functional changes • util/CREDITS # Thank you notes to contributors • util/INSTALL # How to install this script in Cricket • sample-config/genConfig/Defaults # The cricket config-tree Defaults • sample-config/genConfig/Defaults.* # The cricket config-tree module Defaults
  7. 7. • lib/genConfig/File.pm # Utility library for genDevConfig • lib/genConfig/SNMP.pm # Utility library for genDevConfig • lib/genConfig/Utils.pm # Utility library for genDevConfig • lib/genConfig/plugin.pm # Utility library for genDevConfig • lib/genConfig/pluginUtils.pm # Utility library for genDevConfig • lib/monitorConfig # The configuration file for Cricket monitor thresholds • plugins/genConfig/ # The plugin directory containing plugins • plugins/genConfig/CiscoIOS.pm # A plugin • plugins/genConfig/CatalystCatOS.pm # Another plugin • plugins/genConfig/... Installation ### Step 1 Copy genDevConfig to your $CRICKET/util directory. Make sure the genDevConfig script is executable by your user. And that all files are owned by your cricket user. ### Step 2 Copy the libraries from lib/genConfig/* to your $CRICKET/lib/genConfig directory Copy the plugins from plugins/genConfig/* to your $CRICKET/plugins/genConfig directory ### Step 3 (Optional) If this is the first time you install genDevConfig 2.0.x and higher Copy /lib/monitorConfig to your $CRICKET/lib directory If this is not your first time, do a diff between the monitorConfig file and your own local copy. ### Step 4 (Copying the Defaults file to your cricket-config tree) If you use the genDevConfig Defaults files included in this release within your Cricket config-tree (see the example below). You should replace the Defaults files with the new versions. Note: If you do *NOT* use a vanilla version of the genConfig Defaults file, then you must copy the changes from the new Defaults file to your own custom Defaults. Example of creating and copying the Default files: # For lazy bash users $ export CRICKET=/path/to/cricket-base $ cd $CRICKET/cricket-config $ mkdir telecom-tree $ cp $CRICKET/sample-config/genConfig/Defaults* CRICKET/cricket-config/telecom-tree/
  8. 8. Generating your first device profile ### Step 1 Find out the community string and IP address of the device you want to reach ### Step 2 Add the hostname to your servers /etc/hosts file or into DNS. It is recommended to use a local host file to make sure there is no delay introduced by DNS lookups during collection. Do not forget to keep the local host file synchronised with you DNS. This may or may not be an issue if you are generating your configurations on a different host than the collector. ### Step 3 Do a test call of the device before anything else ./genDevConfig -C community-name HOSTNAME You can consult the genDevConfig POD or use genDevConfig -h for more information on how to call genDevConfig from the command-line. There are also some dated examples are available from the genRtrConfig online manual page, your mileage may vary as some options have changed. ### Step 4 Verify the creation of the configuration for chassis, interfaces.. vi HOSTNAME/targets Output from a device profile generation genDevConfig will generate a Cricket config tree for a network device. For the given device, generate a Cricket config tree directory. Within this directory place a "targets" file which will contain the following logical information: device-name chassis_target custom_target1 ... custom_targetN interface_target1 ... interface_targetN
  9. 9. Additional installation resources for genDevConfig Additional resources have been created by genDevConfig users to help install and use genDevConfig. Follow these links if the installation instructions are unclear or do not match your local unix, linux or windows installation. - Installation and basic configuration of genDevConfig on Debian Etch by Ray Burkholder from oneunified Using genDevConfig from the command-line You can browse all the command-line arguments by executing genDevConfig. ./genDevConfig –h How to develop a new plugin Download the genDevConfig source code from CVS. See instructions on the cricket.sourceforge.net web page on getting access and connecting to the cvs server. Follow the development guidelines. Once completed and tested, submit your plugin as a patch to the sourceforge.net/projects/cricket patches tracker. Notify users on the mailing-list (developers and/or users of the new patch). Development guidelines Guidelines which must be followed to maintain project coherence 1. Do not modify genDevConfig unless the changes are compatible with existing plugins. 2. Document properly your plugin. 3. Use built in facilities, do not re-invent the wheel. (Ex. register_oids($OIDS), etc) 4. Do not obfuscate your perl code. 5. Write clear, concise and legible code. genDevConfig does not need to be a speed demon. 6. Use meaningful variables. 7. Use functions for code that may be re-usable. Place your functions in the lib/genConfig libraries or in your own code if it is very specific. 8. Make sure to use the logging facilities which are built-in to genDevConfig and Cricket. 9. Do not piss off other developers 10. Credit code taken from other open-source developers or projects. See above. 11. Use the cricket-dev mailing list if you have any questions, its people are friendly and willing to help.
  10. 10. How to get information necessary to create a plugin A simple plugin that can be used as a starting point: NortelAccelar Complex plugins that can be used to explore more advanced processing: CiscoIOS, CatOS, and NetSNMP. Some existing config tree templates are available through these means: • On the cricket-users mailing list; sourceforge.net/projects/cricket • On the cricket contrib site. It is way out of date, but there are quite a few templates. • Patches section of the cricket project at: sourceforge.net/projects/cricket • CHIRP recognition modules for devices: get an archived copy from the Acktomic web site www.acktomic.com • Cricket user websites • MRTG templates For additional information consult the device vendors MIBs. Writing a basic genDevConfig plugin This is a description of what is necessary to create a genDevConfig plugin in the PERL programming language. Start from a copy of the NortelAccelar.pm plugin. Instructions on setting up a basic plugin. Update the values of these variables - package name - This is the name of the perl package and is how it will be referred to by the cricket main script. You do not need to add this anywhere, genDevConfig will automatically recognize all valid plugins. - version - Indicate a version. This is useful if ever a version of genDevConfig requires a minimal version of this plugin. - OIDs : that you want to query during runtime of genDevConfig (not to be confused with OIDs needed for collector) - @types : to tell it how to recognize the device you wish to query. You can check out other plugins as well, different ways to match. SysObjectID and SysDescr are what is commonly used to recognize devices.
  11. 11. - $script : Brief online description of what devices this plugin tries to cover. - sub can_handle : Here you can choose against what you want to match, sysObjectID or sysDescr. Two examples areprovided that cover using a regex and an OID. - sub discover : The NortelAccelar.pm is a basic plugin in this respect. If you want to look at more advanced discovery look at the CiscoIOS plugin. Handling the device discovery - $opts->{class} This is a variable used to identify the device class for automated collection by rancid(www.shrubbery.net/rancid). Rancid does supports lots of network related devices. :-) (This variable is optional) - $opts->{model} This is the model version of the device. - vendor_soft_version if you know how to get it. This value could be parsed from sysDescr or from a specific OID) - If you want to beautify the sysDescr you can do it here As it is displayed automatically in the target view of the device in grapher.cgi. - vendor_descr_oid : Important to figure out what OID is used for interface descriptions. If you do not know, leave this empty and genDevConfig will try to find a best match (Could be ifAlias, ifName, vendor specific, etc.) - ttype is an informational variable to understand the device subtype - chassisname : Important that this match what you have defined for your chassis targetType in the Defaults.vendor file. - Then you have feature promotion for stuff that these devices support. These are usually used later in the plugin or in the main script. If you promote a feature, genDevConfig will try to build configs for it! - usev2c is if you think this device should support snmp v2c. If you find that some subtype does not support v2c, you can even force demotion here. (Say model x reboots when you try and get v2c OIDs, then you would disable it here.) - devicebox = 1; This last variable would be local to the plugin. As the main script(genDevConfig) really does not care what this device is. $opts->{vendor_descr_oid} = "ifName"; $opts->{sysDescr} .= " " . $opts->{vendor_soft_ver} . " " . $opts->{sysLocation}; $opts->{class} = 'nortel'; $opts->{ttype} = 'Nortel-Passport-8xxx'; $opts->{chassisname} = 'Chassis-Nortel-Passport'; # Default feature promotions for Nortel Devices $opts->{usev2c} = 1 if ($opts->{req_usev2c});
  12. 12. $nortelbox = 1; Example code from NortelAccelar.pm. Handling custom interface statistics Then, in the non-interface targets or interface targets you can do interesting stuff for vendor specific targets you want to create. See other plugins for inspiration. Except for Net-SNMP, which does a little too much non-standard stuff... Handling custom non-interface statistics Then, in the non-interface targets or interface targets you can do interesting stuff for vendor specific targets you want to create. See other plugins for inspiration. Except for Net-SNMP, which does a little too much non-standard stuff... Following the genDevConfig target creation process This is a rough draft of the genDevConfig processing structure. It provides enough detail to get a background on what the script is actually doing. You can also run the script in debug mode using the “--loglevel debug” logging option. This provides feedback on what the script is doing and when, which complements the processing structure diagram.
  13. 13. All rights reserved by Francois Mikus.

×