SellaNMS 2.0
Administrator’s Manual
SellaNMS 2.0 Administrator’s Manual v1.0
Copyright © Digital Genesis Software 2005, 2006.
All rights reserved.
Last
Update
Table of Contents
1 Introduction 7
1.1 Overview 7
1.2 About The Manual 7
1.3 Conventions 7
1.4 Features 8
1.5 How To Help 9
1.5.1 Feedback 9
1.5.2 Donate Hardware 9
1.5.3 Become A Developer 10
2 Support 11
2.1 Mailing List 11
2.2 Forums 11
2.3 Professional Services 11
3 Installation 12
3.1 Requirements 12
3.1.1 Operating System 12
3.1.2 Compiler 12
3.1.3 Net-SNMP 12
3.1.4 MySQL 13
3.1.5 libdbi 13
3.2 Extracting 14
3.3 Building 14
3.4 Installing 15
3.5 Configuring 15
3.5.1 Network Element Configuration 15
3.5.2 System Configuration 15
3.6 Starting 16
3.6.1 Startup 16
3.6.2 Processes 16
3.6.3 Discovery 17
3.7 Shutdown 18
4 Configuration 20
4.1 Network Element 20
4.1.1 ICMP 20
4.1.2 SNMP 20
4.1.2.1 Juniper 21
4.1.2.2 Cisco 21
4.1.2.3 Extreme 21
4.1.2.4 Net-SNMP (Linux/BSD/Solaris) 22
4.1.3 SNMP Trap 22
4.1.3.1 Juniper 22
4.1.3.2 Cisco 23
4.1.3.3 Extreme 23
4.1.3.4 Net-SNMP (Linux/BSD/Solaris) 24
4.1.4 Syslog 24
4.1.4.1 Juniper 24
4.1.4.2 Cisco 24
4.1.4.3 Extreme 24
4.1.4.4 syslogd (Linux/BSD/Solaris) 25
4.2 Syntax 25
4.2.1 Configuration Style 25
4.2.2 Comments 26
4.2.3 Includes 27
4.2.4 Merging 27
4.3 Files/Directories 28
5 Modules 30
5.1.1 Overview 30
5.1.2 sella_nms Configuration 30
5.1.3 Common Configuration 31
5.1.4 System 31
5.1.4.1 System Overview 31
5.1.4.2 system 33
5.1.4.2.1 Syntax 33
5.1.4.2.2 Hierarchy 33
5.1.4.2.3 Description 33
5.1.4.2.4 Options 33
5.1.4.3 storage 34
5.1.4.3.1 Syntax 34
5.1.4.3.2 Hierarchy 34
5.1.4.3.3 Description 34
5.1.4.3.4 Options 34
5.1.4.4 snmp-mib 36
5.1.4.4.1 Syntax 36
5.1.4.4.2 Hierarchy 36
5.1.4.4.3 Description 36
5.1.4.4.4 Options 36
5.1.4.5 default 37
5.1.4.5.1 Syntax 37
5.1.4.5.2 Hierarchy 37
5.1.4.5.3 Description 37
5.1.4.5.4 Options 37
5.1.4.6 Schedule 39
5.1.4.6.1 Syntax 39
5.1.4.6.2 Hierarchy 39
5.1.4.6.3 Description 39
5.1.4.6.4 Options 39
5.1.5 discovery 40
5.1.5.1 Syntax Overview 40
5.1.5.2 discovery 41
5.1.5.2.1 Syntax 41
5.1.5.2.2 Hierarchy 41
5.1.5.2.3 Description 41
5.1.5.2.4 Options 41
5.1.5.3 icmp 43
5.1.5.3.1 Syntax 43
5.1.5.3.2 Hierarchy 43
5.1.5.3.3 Description 44
5.1.5.3.4 Options 44
5.1.5.3.5 Policies 44
5.1.5.4 snmp 45
5.1.5.4.1 Syntax 45
5.1.5.4.2 Hierarchy 46
5.1.5.4.3 Description 46
5.1.5.4.4 Options 46
5.1.5.4.5 Policies 46
5.1.5.5 topology 47
5.1.5.5.1 Syntax 47
5.1.5.5.2 Hierarchy 47
5.1.5.5.3 Description 47
5.1.5.5.4 Options 48
5.1.5.5.5 Policies 49
5.1.6 monitor 49
5.1.6.1 Syntax Overview 49
5.1.6.2 monitor 50
5.1.6.2.1 Syntax 50
5.1.6.2.2 Hierarchy 50
5.1.6.2.3 Description 50
5.1.6.2.4 Options 50
5.1.6.3 icmp 52
5.1.6.3.1 Syntax 52
5.1.6.3.2 Hierarchy 53
5.1.6.3.3 Description 53
5.1.6.3.4 Options 53
5.1.6.3.5 Policies 55
5.1.6.4 snmptrap 57
5.1.6.4.1 Syntax 57
5.1.6.4.2 Hierarchy 58
5.1.6.4.3 Description 58
5.1.6.4.4 Options 58
5.1.6.4.5 Policies 58
5.1.6.5 syslog 60
5.1.6.5.1 Syntax 60
5.1.6.5.2 Hierarchy 60
5.1.6.5.3 Description 61
5.1.6.5.4 Options 61
5.1.6.5.5 Policies 61
5.1.6.6 state 63
5.1.6.6.1 Syntax 63
5.1.6.6.2 Hierarchy 63
5.1.6.6.3 Description 63
5.1.6.6.4 Options 64
5.1.6.6.5 Policies 64
5.1.7 output 64
5.1.7.1 Syntax Overview 64
5.1.7.2 output 65
5.1.7.2.1 Syntax 65
5.1.7.2.2 Hierarchy 65
5.1.7.2.3 Description 65
5.1.7.2.4 Options 65
5.1.7.3 gui 67
5.1.7.3.1 Syntax 67
5.1.7.3.2 Hierarchy 67
5.1.7.3.3 Description 67
5.1.7.3.4 Options 68
5.1.7.3.5 Policies 68
5.1.7.4 email 69
5.1.7.4.1 Syntax 69
5.1.7.4.2 Hierarchy 70
5.1.7.4.3 Description 70
5.1.7.4.4 Options 70
5.1.7.4.5 Policies 71
5.1.7.5 syslog 73
5.1.7.5.1 Syntax 73
5.1.7.5.2 Hierarchy 73
5.1.7.5.3 Description 73
5.1.7.5.4 Options 74
5.1.7.5.5 Policies 74
5.1.8 internal 74
5.1.8.1 Syntax Overview 74
5.1.8.2 internal 75
5.1.8.2.1 Syntax 75
5.1.8.2.2 Hierarchy 75
5.1.8.2.3 Description 75
5.1.8.2.4 Options 75
5.1.8.3 tidy 76
5.1.8.3.1 Syntax 76
5.1.8.3.2 Hierarchy 76
5.1.8.3.3 Description 76
5.1.8.3.4 Options 77
5.1.8.3.5 Policies 77
6 Policy Framework 78
6.1 Overview 78
6.2 Syntax Overview 78
6.3 Variable Substitution 78
6.4 Policy Statements 80
6.4.1 term 80
6.4.1.1 from clause 80
6.4.1.2 then clause 81
6.4.1.2.1 set 81
6.4.1.2.2 output 82
6.4.1.2.3 evaluate 83
6.4.1.2.4 apply-map 83
6.4.1.2.5 action 84
6.4.1.2.6 apply-format 84
6.5 Format Statements 85
6.5.1 term 85
6.5.1.1 from clause 85
6.5.1.2 then clause 86
6.6 Map Statements 87
6.6.1 term 87
6.6.1.1 from clause 87
6.6.1.2 then clause 88
6.6.1.2.1 query 88
6.6.1.2.2 set 89
7 Troubleshooting 90
7.1 Logging 90
7.2 trace-options 90
8 Advanced Topic 92
8.1 Distributed Installs 92
9 Appendix 94
9.1 Limitations 94
9.2 Licenses 94
9.2.1 GNU General Public License 94
This section of the manual covers an overview of SellaNMS, details the conventions used within this manual, touches on the features of SellaNMS and explains how you can help with this project.
SellaNMS is an open source Network Management System designed to be an extendable carrier grade solution for networks of all sizes.
It will discovery and monitor nearly any SNMP aware device (router, switch, server, etc.) and will accept input from undiscovered elements. It is known to work with Juniper*, Cisco*, Extreme*, Lucent/Livingston* routers/switches, Net-SNMP configured servers and Linux based servers. Additionally, it has been used with Arbor Networks* Peakflow products.
The newest versions of SellaNMS are available at:
http://www.digitalgenesis.com/software/sella_nms/
*Juniper Networks, JUNOS, JUNOSe, NetScreen, and ScreenOS are registered trademarks of Juniper Networks, Inc. Cisco and Cisco IOS are registered trademark of Cisco Systems, Inc. Extreme Networks is a registered trademark of Extreme Networks, Inc. Arbor Networks and Peakflow are registered trademarks of Arbor Networks, Inc. Lucent and Livingston are registered trademarks of Lucent, Inc.
All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
This manual covers the administration and configuration of SellaNMS. This includes building, configuring, startup and shutdown of the SellaNMS system and its modules. Basic steps to configure several common network elements to work with SellaNMS are also included.
SellaNMS GUIs are independant projects. The administration and configuration of SellaNMS GUIs are covered in their respective manuals.
Throughout the manual, the SellaNMS application is also referred to as "the system", "the NMS" or "SellaNMS". Each of these refer to the SellaNMS application and should be interpreted as such.
To aid the reader in interpreting the manual, the following visual cues are used:
blue text – Used to denote configuration samples, commands and hyperlinks.
bold – Used to highlight sections of a configuration example related the previous description. Also used to highlight items in a list, if a description follows.
italics – Used to highlight significant SellaNMS terms such as module names, subsystem names and configuration sections. In syntax blocks it is used to denote replaceable values. Also used for references to sections of the manual and notes.
single quotes - Used to highlight SellaNMS configuration keywords. Also used for executable scripts and programs within a description.
double quotes - Used to highlight items that may be confusing to the reader without some form of separation such as filename, directories or suggested substitutions such as ".tar.*".
NOTE: These visual cues with the exception of bold are not used within example configuration snippets.
Commands are listed after the typical command prompt symbol of the mode the user should be in. The following is a list of prompts used within the manual.
$ - Server shell prompt for a normal (non-root) user.
# - Server shell prompt for the root user, Juniper configuration edit mode, Extreme CLI prompt and Cisco CLI prompt.
> - Juniper router prompt for the CLI (not edit mode).
(config)# - Cisco configuration edit mode.
mysql> - Interactive MySQL CLI prompt.
SellaNMS has a wide variety of features making it an ideal solution for many networks.
Flexibility - Modules have a wide variety of configuration options that adjust how they operate and perform. Additionally, the policy framework provides a great deal of flexibility on how the system processes data and correlates external data sources.
Extendable Design - Modules can be written to extend the functionality of the system. The core application and libraries have a C++ API and work is being done to provide a Perl API, making it easier to write modules for the system.
Reliability - Modules are separated into different processes and run independently of each other. This isolates the impact of bugs and errors to the affected module. Should a module fail, the remainder of the system continues and the watchdog process recovers the failed module.
Scalability - SellaNMS is a multi-threaded and multi-process system written with highly optimized low memory algorithms. This allows the system to handle large workloads on average servers and take full advantage of servers with multiple CPUs. Additionally, the system can be configured to run it’s modules distributed across multiple servers. This provides scalability to handle the largest of networks.
Portability - The core application, libraries and modules are written in C and C++ and compile with GCC. This allows the system to be ported to a wide variety of UNIX based systems.
Open System - The full source code for the system is available under the GPL license. The core application, libraries and modules are all available for examination and modification. Data is stored within a MySQL database and can be accessed via third-party applications.
There are many ways to help the SellaNMS project. Below we cover a few of them.
Providing feedback, both positive and negative, is a huge help to the project. Without sufficient feedback, it will take us longer to move the project towards what end-users need.
If you run into problems compiling or running SellaNMS please report those issues to the Forums or Mailing List (see Support). Additionally, if you successfully install and run the system, we’d like to know.
If you have hardware you would like to donate to the project, we will gladly accept it. We can use any additional manageable networking gear (Juniper, Cisco, Foundry, Extreme, Force10, Riverstone, etc.) to improve our test network. AC powered units are preferred. We can also use additional server platforms to aid us in porting.
Contact us via the Mailing List (see Support) if you are interested in donating.
Become a SellaNMS developer and contribute directly to the project. This can mean writing new modules, developing policies for new network elements, providing MIBs, improving documentation or even writing a SellaNMS GUI.
Contact us via the Mailing List (see Support) if you’re interested in becoming a developer.
This section of the manual covers the available sources for SellaNMS support.
The SellaNMS User Mailing List is available at:
http://mailman.genesismuds.com/mailman/listinfo/sella_nms-user
The SellaNMS Developer Mailing List is available at:
http://mailman.genesismuds.com/mailman/listinfo/sella_nms-developer
The Support and Development Forums are available at:
http://www.digitalgenesis.com/support/forum/
Professional services are available for installation support, policy development and configuration support and development of new features and modules.
If you are interested in our professional services, please contact us by emailing sellanms@digitalgenesis.com.
This section of the manual covers requirements, configuration, building and starting SellaNMS.
SellaNMS was designed and implemented on RedHat Linux and Fedora Core distributions. It was implemented to be compatible with UNIX based system, however has not been tested or ported to any other platforms to date.
The system is know to run on:
Fedora Core 4
Fedora Core 2
RedHat ES4
RedHat ES3
RedHat 9
RedHat 8
Debian Linux
SellaNMS currently requires the GCC C/C++ compiler to build. The system is known to build with versions 2.95.3, 3.x and 4.0.1. Any version of GCC past 3.0 should build properly.
Work has been put into making the system compile with Intel’s C/C++ compiler, however the current release does not build with it.
SellaNMS requires the Net-SNMP libraries and headers to build. It is known to build with versions 4.2.6, 5.0.6, 5.0.8 and 5.2.1. Nearly any version of Net-SNMP should be compatible.
Net-SNMP can be downloaded from:
On Fedora Core systems, you can install the required packages by running (as root):
# yum install net-snmp net-snmp-devel net-snmp-libs net-snmp-utils
On RedHat ES4 systems, you can install the required packages by running (as root):
# up2date -i net-snmp net-snmp-devel net-snmp-libs net-snmp-utils
Please consult the MySQL manual to find details on how to configure the MySQL administrator login and start it up.
SellaNMS requires the MySQL client libraries and a working MySQL database. The system interacts with MySQL via the the libdbi abstraction layer. It is known to be compatible with versions 3.23.48, 4.0.13, 4.0.18 and 4.1.13a.
Any version of MySQL beyond 3.23.32 MySQL should be compatible, however we suggest at least the newest 4.0.x release, since the query cache feature provides a performance enhancement.
MySQL can be downloaded from:
On Fedora Core systems, you can install the required packages by running (as root):
# yum install mysql mysql-server mysqlclient10
On RedHat ES4 systems, you can install the required packages by running (as root):
# up2date -i mysql mysql-server mysqlclient10
Please consult the MySQL manual to find details on how to configure the MySQL administrator login and start it up.
SellaNMS requires the libdbi and libdbi-drivers libraries and headers to build. It is known to work with versions 6.7, 0.7.1, 0.7.2 and 0.8.1. We recommend version 0.8.0 or better since, the library contained a memory leak in earlier versions.
If you build libdbi and libdbi-drivers from scratch, be sure to build with MySQL driver support.
The libdbi package can be downloaded from:
http://libdbi.sourceforge.net/
The libdbi-drivers package can be downloaded from:
http://libdbi-drivers.sourceforge.net/
On Fedora Core systems, you can install the required packages by running (as root):
# yum install libdbi libdbi-devel libdbi-dbd-mysql libdbi-dbd-mysql libdbi-drivers
On RedHat ES4 systems, you can install the required packages by running (as root):
# up2date -i libdbi libdbi-devel libdbi-dbd-mysql libdbi-dbd-mysql libdbi-drivers
Before you can extract the distribution archive, make sure you have the newest copy from:
ftp://ftp.digitalgenesis.com/pub/sella_nms/
With the newest archive, you can extract the archive by running (replacing "2.x.x" with the proper filename):
$ tar xvzf sella_nms-2.x.x.tar.gz
Or if you downloaded the BZ2 archive, by running:
$ tar xvjf sella_nms-2.x.x.tar.gz2
The archive will extract the distribution into a directory that matches the filename, minus the ".tar.*" extension.
To build SellaNMS, change to the distribution directory and run the configure script by running:
$ cd sella_nms-2.x.x
$ ./configure
The configure script may take a few minutes to complete. Without any arguments specified it will use the default settings to generate the Makefiles to compile the system.
If the configure script encounters any errors or finds that the required software is not installed, it will abort with an message reporting what it encountered. If the message isn’t descriptive enough, check the end of the configure log file which is found in "src/config.log" for hints.
Next, compile the system by running:
$ make all
Compiling will take between 5 and 30 minutes depending on the speed of your server. If you encounter any errors during the compiling process please report them (see Support).
Once compiling has completed, installing is the next step. You can install SellaNMS by running (as root):
$ su -
# make install
Once the system is installed, it will startup a configuration script to walk you though the configuration of the system itself. This script can be run at any time by running ’config-sella_nms.sh’ (installed in "/usr/local/sella_nms/sbin/" by default).
Make sure to configure your PHP enabled web server (Apache) to serve up the Web GUI (installed in "/usr/local/sella_nms/html" by default). The Web GUI will be deprecated in an upcoming release in favor of a stand alone GUI. Visit http://www.digitalgenesis.com for details.
Before starting up SellaNMS, you’ll want to verify that your routers, switches, and servers have been properly configured to allow incoming ICMP and SNMP requests from your SellaNMS server. See the Configuration section of the manual for more information on this.
If you elected to not run the configuration script (during ’make install’), you will need to load the SellaNMS database schema into your MySQL server and finish configuring your sella_nms.conf configuration file.
You can run the configuration script again to take care of the configuration details for you by running (as root):
# /usr/local/sella_nms/sbin/config-sella_nms.sh
If you would prefer to manually prepare and configure SellaNMS, follow the next steps.
For MySQL 4.x run (from the top of the SellaNMS distribution):
$ mysql -u root -p sella_nms < support/sella_nms-mysql.sql
$ mysql -u root -p mysql
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,LOCK TABLES,CREATE
TEMPORARY TABLES,CREATE,DROP ON sella_nms.* TO
sella_nms@localhost IDENTIFIED BY 'password';
For MySQL 3.23.x run (from the top of the SellaNMS distribution):
$ mysql -u root -p sella_nms < support/sella_nms-mysql.sql
$ mysql -u root -p mysql
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON sella_nms.*
TO sella_nms@localhost IDENTIFIED BY 'password';
Edit your configuration file by running (as root):
# cd /usr/local/sella_nms/etc
# vi sella_nms.conf
Run the following commands (as root) to startup SellaNMS:
# cd /usr/local/sella_nms/sbin
# ./sella_nms
SellaNMS will fork into the background and begin starting up its configured modules. See the Troubleshooting section if SellaNMS fails to startup or work as expected.
Starting up SellaNMS launches several modules each of which run as separate daemons.
You can view these processes by utilizing the ’admin-sella_nms.sh’ script (as root). Below is an example:
# cd /usr/local/sella_nms/sbin/
# ./admin-sella_nms.sh -p
nobody 10665 0.0 0.5 10620 5748 ? SN Nov30 0:00 sella_nms [running]
nobody 10666 0.0 0.5 11472 6120 ? SN Nov30 0:07 int.tidyd [running]
nobody 10669 0.1 1.1 26068 11568 ? SN Nov30 19:53 out.guid [running]
nobody 10670 0.0 0.8 22436 8848 ? SN Nov30 6:58 mon.stated [running]
nobody 10672 0.7 1.3 35992 14360 ? SN Nov30 97:18 mon.syslogd [running]
nobody 10676 0.8 5.1 85004 17434 ? SN Nov30 96:30 mon.SNMP trapd [running]
nobody 20866 1.2 3.3 89988 18341 ? SN Nov30 99:19 mon.icmpd [running]
nobody 14229 0.0 0.7 13208 17812 ? SN Nov30 1:08 out.emaild [running]
nobody 15558 2.5 0.6 11968 16556 ? SN Nov30 0:12 out.syslogd [running]
Optionally, you can use the ’ps’ command to view these processes. Below is an example:
$ ps auxw | grep -E 'sella_nms|dsc\.|mon\.|out\.|int\.'
nobody 10665 0.0 0.5 10620 5748 ? SN Nov30 0:00 sella_nms [running]
nobody 10666 0.0 0.5 11472 6120 ? SN Nov30 0:07 int.tidyd [running]
nobody 10669 0.1 1.1 26068 11568 ? SN Nov30 19:53 out.guid [running]
nobody 10670 0.0 0.8 22436 8848 ? SN Nov30 6:58 mon.stated [running]
nobody 10672 0.7 1.3 35992 14360 ? SN Nov30 97:18 mon.syslogd [running]
nobody 10676 0.8 5.1 85004 17434 ? SN Nov30 96:30 mon.SNMP trapd [running]
nobody 20866 1.2 3.3 89988 18341 ? SN Nov30 99:19 mon.icmpd [running]
nobody 14229 0.0 0.7 13208 17812 ? SN Nov30 1:08 out.emaild [running]
nobody 15558 2.5 0.6 11968 16556 ? SN Nov30 0:12 out.syslogd [running]
If you need SellaNMS or an individual module to reread its configuration, you can send the HUP signal. If the ’sella_nms’ daemon is signaled, every module will reread its configuration and restart. However, if you only need one module to reread its configuration, you can signal the individual module, resulting in less disruption to the system.
Part of the startup process is to begin the discovery modules. This behavior can be stopped by removing the ’startup’ keyword from the discovery schedule section in the "sella_nms.conf" configuration file. One removed, the discovery modules will only run on the configured schedule.
The discovery process will first scan the prefixes provided in the "sella_nms.conf" configuration file with ICMP. It will then use SNMP to poll each device that responded to ICMP. Finally, the data polled via SNMP is processed by the topology module to build the network topology and populate the database. This process will take a different amount of time on each network. For smaller networks, discovery should complete in just a few minutes. Larger networks (300+ elements) may take over 30 minutes.
The progress of the discovery modules can be monitored by using the ’admin-sella_nms.sh’ script. The "-d" option, will display a discovery summary and the last 5 entries (by default) in the ICMP and SNMP discovery tables. Below is an example.
# cd /usr/local/sella_nms/sbin/
# ./admin-sella_nms.sh -d 1
[Discovery Information]
Discovery started; 360 ICMP hosts located, 9882 SNMP OIDs collected.
Previously completed discovery contains 329 elements, 31999 interfaces and 32107 IPs
Displaying the last 1 records (out of 360) from table discovery_icmp (descending order).
*************************** 1. row ***************************
id: 14233
timestamp: 2005-12-09 04:00:09
ip: 12.34.56.1
Displaying the last 1 records (out of 9882) from table discovery_snmp (descending order).
*************************** 1. row ***************************
id: 9794980
timestamp: 2005-12-09 04:06:41
ip: 12.34.56.40
variable: .1.3.6.1.2.1.15.3.1.4.66.192.246.226
value: 4
Since SellaNMS modules each run as separate daemons, shutting down the system needs to be performed in a specific way.
To shutdown SellaNMS and all of its modules, send the TERM (-15) signal (the default signal) to the ’sella_nms’ daemon using the ’kill’ command (as root). This will cause all of the modules to shutdown cleanly. Below is an example:
$ su -
# ps auxw | grep sella_nms
nobody 10665 0.0 0.5 10620 5748 ? SN Nov30 0:00 sella_nms [running]
# kill 10665
NOTE: Do not use the KILL (-9) signal to shutdown the ’sella_nms’ daemon. This will cause the SellaNMS modules to continue running and will require you to manually shutdown each of them.
After issuing the ’kill’ command to the ’sella_nms’ daemon, SellaNMS will signal each of its modules asking them to shutdown cleanly. Any modules that do not fully shutdown within 10 seconds will be forcefully terminated. Finally, the ’sella_nms’ daemon will finish shutting down.
Should the ’sella_nms’ daemon be terminated uncleanly, you may need to shutdown its modules manually. If this happens, send a TERM (-15) signal to each of the SellaNMS modules. If any modules fail to shutdown after 10 seconds, use the KILL (-9) signal to forcefully terminate them. The Processes section has an example of how to get the process IDs for all of the SellaNMS modules.
This section of the manual walks though the various aspects of configuring SellaNMS and configuring your network elements (routers, switches, etc.) to work with the system. You may need to consult your equipment vendors documentation to properly configure them.
Your network elements may need to be configured to get the full benefit of SellaNMS. This section will walk you though some of the common configuration changes.
Most manageable network elements respond to ICMP or ping. If you filter incoming traffic to your network elements, you’ll need to verify that your SellaNMS server is allowed to send ICMP echo requests to it.
You can test if ICMP echo requests are being accepted by your network element by using the ’ping’ command. In the example below, replace 12.34.56.1 with the IP of the network element you’re testing:
$ ping 12.34.56.1
PING 12.34.56.1 (12.34.56.1) 56(84) bytes of data.
64 bytes from 12.34.56.1: icmp_seq=0 ttl=254 time=0.392 ms
64 bytes from 12.34.56.1: icmp_seq=1 ttl=254 time=0.395 ms
64 bytes from 12.34.56.1: icmp_seq=2 ttl=254 time=0.387 ms
Most manageable network elements support SNMP queries. These network elements usually need to be configured to accept incoming queries. If you filter incoming SNMP traffic to your network elements, you’ll need to verify that your SellaNMS server is allowed to communicate.
If you have the Net-SNMP utilities installed on your SellaNMS server you can use the ’snmpwalk’ command to test this. In the example below, replace "my_comm" with your community and 12.34.56.1 with the IP of the network element you’re testing.
$ snmpwalk -c my_comm 12.34.56.1 system
SNMPv2-MIB::sysDescr.0 = STRING: Juniper Networks, Inc. t320 internet router, kernel JUNOS 7.2-20050831.0 #0: 2005-0 Build date: 2005-08-31 08:00:21 UTC Copyright (c) 1996-2005 Juniper Networks, Inc.
SNMPv2-MIB::sysObjectID.0 = OID: SNMPv2-SMI::enterprises.2636.1.1.1.2.7
SNMPv2-MIB::sysUpTime.0 = Timeticks: (266827794) 30 days, 21:11:17.94
SNMPv2-MIB::sysContact.0 = STRING: support@domain.com
SNMPv2-MIB::sysName.0 = STRING: KYTO-CORE-01
SNMPv2-MIB::sysLocation.0 = STRING: Kyoto, Japan
SNMPv2-MIB::sysServices.0 = INTEGER: 4
SNMP is disabled by default on Juniper routers. Below is a configuration snippet showing a valid SNMP configuration.
> show configuration snmp
snmp {
location "Kyoto, Japan";
contact "support@domain.com";
community my_comm {
clients {
/* Your SellaNMS server. */
192.168.0.55/32;
}
}
Below are the set commands needed to build this configuration:
> edit
# set snmp location "Kyoto, Japan"
# set snmp contact "support@domain.com"
# set snmp community my_comm clients 192.168.0.55/32
# commit
SNMP is disabled by default on Cisco routers and switches. Below are example commands to enable SNMP for a specific host. You should verify that "access-list 10" is not already in use.
# conf t
(config)# access-list 10 permit 192.168.0.55
(config)# snmp-server location Kyoto, Japan
(config)# snmp-server contact support@domain.com
(config)# snmp-server chassis-id KYTO-CORE-01
(config)# snmp-server community my_comm RO 10
(config)# exit
# write
Below are example commands to enable SNMP for a specific host.
# configure snmp sysName "KYTO-CORE-01"
# configure snmp sysLocation "Kyoto, Japan"
# configure snmp sysContact "support@domain.com"
# configure snmp add community readonly my_comm
# configure access-profile "PERMIT_SNMP" mode permit
# configure access-profile "PERMIT_SNMP" add 5 permit ipaddress 192.168.0.55/32
# configure snmp access-profile readonly PERMIT_SNMP
# save configuration
If you build Net-SNMP from the source code, it will walk you though the configuration. If you need to manually configure Net-SNMP, edit the "snmpd.conf" configuration file (default "/etc/snmp/snmpd.conf"). You will need to set the following options:
rocommunity my_comm 127.0.0.1
rocommunity my_comm 192.168.0.55/32
syslocation "Kyoto, Japan"
syscontact support@domain.com
After making these configuration changes to "snmpd.conf", send a HUP (-1) signal to ’snmpd’ to have the changes take effect.
Most manageable network elements are able to generate SNMP Traps. These network elements need to be configured with the host name or IP address of a SNMP trap collector.
Below is a configuration snippet showing a valid SNMP trap configuration.
> show configuration snmp
snmp {
location "Kyoto, Japan";
contact "support@domain.com";
trap-group my_comm {
version v2;
categories {
chassis;
link;
remote-operations;
routing;
startup;
rmon-alarm;
}
}
targets {
/* Your SellaNMS server. */
192.168.0.55;
}
}
Below are the set commands needed to build this configuration:
> edit
# set snmp location "Kyoto, Japan"
# set snmp contact "support@domain.com"
# set snmp trap-group my_comm version v2
# set snmp trap-group my_comm categories chassis
# set snmp trap-group my_comm categories link
# set snmp trap-group my_comm categories remote-operations
# set snmp trap-group my_comm categories routing
# set snmp trap-group my_comm categories startup
# set snmp trap-group my_comm categories rmon-alarm
# set snmp trap-group my_comm targets 192.168.0.55
# commit
Below is a configuration snippet showing a valid SNMP trap configuration.
# conf t
(config)# snmp-server enable traps snmp authentication linkdown linkup coldstart warmstart
(config)# snmp-server enable traps config
(config)# snmp-server enable traps envmon fan shutdown supply temperature status
(config)# snmp-server enable traps rf
(config)# snmp-server enable traps bgp
(config)# snmp-server host 192.168.0.55 my_comm
(config)# exit
# write
Below is a configuration snippet showing a valid SNMP trap configuration.
# configure snmp add trapreceiver 192.168.0.55 port 162 community "my_comm" mode enhanced
# save configuration
Net-SNMP’s ’snmpd’ daemon is capable of generating SNMP traps for authentication failures, cold start traps and user defined traps. See the man page for "snmpd.conf" to see how to configure Net-SNMP for SNMP traps.
Most manageable network elements are able to log to remote syslog servers. These network elements need to be configured with the host name or IP address of a remote syslog server.
Below is a configuration snippet showing a valid syslog configuration.
> show configuration system syslog
system {
syslog {
/* Your SellaNMS server. */
host 192.168.0.55 {
any any
}
}
}
Below are the set commands needed to build this configuration:
> edit
# set system syslog host 192.168.0.55 any any
# commit
Below is a configuration snippet showing a valid syslog configuration.
# conf t
(config)# logging trap debugging
(config)# logging 192.168.0.55
(config)# exit
# write
Below is a configuration snippet showing a valid syslog configuration.
# conf syslog add 192.168.0.55 local0
# enable syslog
# save configuration
The syslog daemon on most Linux/BSD/Solaris servers can be configured to send logs to remote syslog servers. The configuration file for syslogd is usually "/etc/syslog.conf". If your server uses a different syslog daemon such as syslog-ng, your configuration file may be elsewhere and will require different configuration changes.
For RedHat Linux and Fedora Core, you can direct syslog messages to a remote server by adding a line with the facility and priority followed by a host name with the "@" symbol prepended to it. Example below:
*.info;mail.none;authpriv.none;cron.none @192.168.0.55
authpriv.* @192.168.0.55
After adding these lines to your configuration, restart the syslog daemon by running (as root):
# /etc/rc.d/init.d/syslog restart
The SellaNMS configuration files are based on a hierarchy or tree structure. The basic style follows a 'keyword value' pair, or a 'keyword block' pair. All 'keyword value' pairs are terminated by a semicolon as shown below:
order 10;
All "key block" pairs are a keyword followed by a "{ }" block or a "[ ]" block set. Either style of blocks may be used in place of the other. The two are purely available for cosmetic reasons.
Each block main contain a series of "keyword value" pairs, "keyword block" pairs, values or a mix.
Below is an example from the "sella_nms.conf" configuration file:
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
order 10;
disable;
prefix {
192.168.0.0/24;
192.168.10.0/24;
}
policy {
input [ EXAMPLE_IN1 EXAMPLE_IN2 ];
output [ EXAMPLE_OUT1 EXAMPLE_OUT2 ];
}
}
}
Bash, C, C++/Java and SQL comment styles are supported within the
configuration files.
Below is an example of a bash style comment (pound):
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
order 10;
#disable;
}
}
Below is an example of a multi-line C style comment (/* ... */ block):
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
/*
order 10;
disable;
*/
}
}
Below is an example of a C++/Java comment (double slashes):
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
order 10;
//disable;
}
}
Below is an example of an SQL comment (double dashes):
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
order 10;
--disable;
}
}
The configuration files support file and directory includes and nested inclusions. Nesting is supported up to a depth of 255. If needed, the limit can be altered by editing FLATFILE_MAXDEPTH within "flatfile.h" and recompiling.
This feature is useful for creating user specific policies outside of the policies included with SellaNMS. This makes it easier to identify which are specific to your installation.
Below is an example of a file include statement:
#include "/usr/local/sella_nms/etc/policy-statements.conf"
Below is an example of a directory include statement:
#include "/usr/local/sella_nms/etc/policy.d"
All files within the directory "/usr/local/sella_nms/etc/policy.d" will be included as if they were each specified separately.
Configuration merging is a feature of the SellaNMS configuration system. If a configuration hierarchy overlaps at the same level with another configuration hierarchy, they will be automatically (and silently) merged.
This feature is primarily available to allow sections of the policy-options hierarchy to be broken into separate more manageable files. This allows for the easy addition of policies for new vendor equipment.
Below is an example of overlapping configuration hierarchy:
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
prefix {
192.168.0/24;
}
prefix {
192.168.10.0/24;
}
policy {
input [ EXAMPLE_IN1 ];
output [ EXAMPLE_OUT1 ];
}
policy {
input [ EXAMPLE_IN2 ];
output [ EXAMPLE_OUT2 ];
}
}
}
The SellaNMS configuration system will automatically merge and use the previous configuration snippet as:
discovery {
icmp {
description "Polls and records ICMP reachability for discovery";
executable "dsc.icmpd";
prefix {
192.168.0/24;
192.168.10.0/24;
}
policy {
input [ EXAMPLE_IN1 EXAMPLE_IN2 ];
output [ EXAMPLE_OUT1 EXAMPLE_OUT2 ];
}
}
}
The SellaNMS configuration is separated into individual configuration files and directories to make them easier to maintain. Below, we detail out the various files and directories used.
sella_nms.conf – This is the top level configuration file. It contains system and module specific configuration options used to adjust how the modules run and which policies are applied to them. Most general user configuration changes take place within this file.
policy-statements.conf – The primary policy statement configuration file. It contains the generic non-vendor specific policies.
policy.d – Directory containing vendor specific policy, format and map statement configuration files. Any file within this directory will be included into the configuration.
format-statements.conf – The primary format configuration file. It contains generic non-vendor specific format statements which are applied to policy statements to define how variables function and enforce proper input and output for modules.
map-statements.conf – The primary map configuration file. It contains generic non-vendor specific map statements which are applied to policies and formats to map external data to the data provided by a module, as a policy is evaluated.
This section of the manual covers the syntax and options for the configuration of the SellaNMS subsystems and modules.
Modules make up the majority of SellaNMS. They are the workers of the system, each responsible for performing a different set of tasks. Each module is grouped into one of SellaNMS’s subsystems; discovery, monitor, output and internal.
Each module has a set of ’sella_nms’ (watchdog process) configuration options, a set of common configuration options, and a set of unique configuration options.
The ’sella_nms’ daemon is responsible for starting and stopping the system’s modules based on a schedule. It is also responsible for monitoring the health of the modules and restarting them should they fail or behave beyond the configured thresholds. While it shares some source code in common with the systems modules, it is technically a watchdog process and not a module.
Every module’s configuration block may contain any of the following options, which are read by the ’sella_nms’ daemon:
config-file – The configuration file to be used by the module (default: use compiled in value).
description – A description field used to describe the module (default: none).
disable – Disable (don’t run) the module (default: not set).
environment – The environment variables to set before running the module (default: none).
executable – The executable for this module (default: none).
facility – The syslog facility to log messages from this module. (default: local0).
group – The UNIX group to run the module as. (default: use primary group associated with the user).
nice – The niceness at which to run this module (default: 5).
order – The order in which to start this module, relative to the order of other modules. Lower numbered modules are started before higher numbered modules. Modules at the same order are started at the same time. All modules at the current order must be started and complete (shutdown) before moving to the next order with the exception of order 0. Order 0 is treated as a non-order and will not block the startup of other orders.
pid-file – The file used to store the process ID (PID) of the module (default: use value compiled into module).
restart – Restart the module if it stops running (default: active).
no-restart – Do not restart the module if it stops running (default: not active).
restart-limit – The number of times to restart the module before automatically disabling it (default: ULONG_MAX)
schedule – The schedule at which to run the module (default: none). See the ’system default schedule’ portion of the Modules section of the manual for more information.
stat-file – The file to store the module stats in (default: use value compiled into module).
user – The user to run the module as (default: current user).
The majority of SellaNMS modules use the ’system’ section of the configuration to specify how to connect to the database and which SNMP MIBs to read in.
Most SellaNMS modules support the following configuration options within the module specific section of their configurations:
trace-options – Enables a set of trace (debug) options used to troubleshoot a module. See the Troubleshooting section of the manual for more information.
policy input – Specify a set of input policies for the module. Input policies are primarily used to reject unwanted incoming data.
policy output – Specify a set of output policies for the module. Output policies are primarily used to manipulate data and specify what data should be passed to the output subsystem.
The ’system’ section of the configuration file contains general options that apply to SellaNMS and its modules.
The following block details the top level configuration syntax for the ’system’ section of the configuration:
system {
trace-options [ ... ];
storage {
database-server-name {
debug;
driver (mysql | pgsql);
driver-directory path-to-driver-directory;
server (localhost | host-name | ip-address);
port port-number;
socket path-to-unix-socket;
compression;
tty tty;
options options;
database database;
username username;
password password;
pool {
debug;
timeout milliseconds;
trim-delay seconds;
min-size size;
max-size size;
}
}
snmp-mib {
path-to-mib-directory;
...
}
default {
config-file path-to-configuration-file;
description description;
directory path-to-binary-directory;
disable;
environment environment-variables;
executable path-to-executable-file;
facility facility;
group unix-group;
launch-delay seconds;
nice niceness;
order run-order;
pid-file path-to-process-id-file;
(restart | no-restart);
restart-limit limit;
schedule {
startup;
delay seconds;
cron enhanced-vixie-cron-format;
second second;
minute minute;
hour hour;
day day;
day-of-week day-of-week;
month month;
day-of-month day-of-month;
}
stat-file path-to-stats-file;
user unix-user;
}
}
system {
trace-options [ ... ];
storage { ... }
snmp-mib { ... }
default { ... }
}
top
The ’system’ section of the configuration contains general options that apply to SellaNMS and its modules.
trace-options – The trace-options to apply to the ’sella_nms’ daemon (default: none). See the Troubleshooting section for more information on how to use this option.
storage – The storage related configuration options (default: none).
snmp-mib – The SNMP MIB related configuration options (default: none).
default – The default options for modules started by the ’sella_nms’ daemon (default: none).
storage {
database-server-name {
debug;
driver (mysql | pgsql | driver-name);
driver-directory path-to-driver-directory;
server (localhost | host-name | ip-address);
port port-number;
socket path-to-unix-socket;
compression;
tty tty;
options options;
database database;
username username;
password password;
pool {
debug;
timeout seconds;
trim-delay seconds;
min-size size;
max-size size;
}
}
}
system { ... }
Contains one or more database configuration sets.
server-database-name – A descriptive name for the configuration set. Multiple configuration sets may be specified using different server-database-names (default: none).
debug – Enable debug output for the storage library, excluding the connection pool code. (default: not active).
driver – The libdbi driver to use to connect to the database (default: mysql).
mysql – The mysql libdbi driver.
pgsql – The PostgresSQL libdbi driver (untested).
driver-name – The libdbi driver name.
driver-directory – The libdbi driver directory to search for the specified driver (default: use directory compiled into libdbi).
server – The database server to connect to (default: localhost).
localhost – Connect to the local server via a UNIX socket.
host-name – Connect to host-name via a TCP socket.
ip-address – Connect to IP address via a TCP socket.
port – TCP port to use to connect to the database sever (default: use driver default port).
socket – The UNIX socket to use to connect to the database (default: use driver default socket). This option is only available when using the MySQL driver.
compression – Enable compression of the database between SellaNMS and the database server (default: not active). This option is only available when using the MySQL driver.
tty – The tty to use to connect to the database (default: use driver default tty). This option is only available when using the PostgreSQL driver.
options – The options to use when connecting to the database (default: none). This option is only available when using the PostgreSQL driver.
database – The database name to use (default: sella_nms).
username – The username to use when connecting to the database (default: none).
password – The password to use when connecting to the database (default: none).
pool – The storage library’s connection pool provides a dynamic set of active connections to the database. It improves performance for modules that need to frequently open and close connections to the database and prevents file descriptor depletion (default: enabled).
pool debug - Enable debug output for the storage libraries connection pool code. (default: not active).
pool timeout – The number of seconds a database connection must be idle before the connection pool will reconnect it (default: 300 seconds).
pool trim-delay – The number of seconds a database connection must be idle before the connection pool will consider it for removal from the pool (default: 30 seconds).
pool min-size – The minimum number of connections the connection pool will maintain with the database (default: 2).
pool max-size – The maximum number of connections the connection pool will maintain with the database (default: 32).
snmp-mib {
path-to-mib-directory;
...
}
system { ... }