Jffnms Manual
Jffnms Manual
Jffnms Manual
1 Introduction 5
1.1 What is a NMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Polling and Consolidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Using JFFNMS 9
2.1 Overview of JFFNMS Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.1 Events Express Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 Performance Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4.1 Interface Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.4.2 Performance Trend Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Installing jffnms 15
3.1 Getting JFFNMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Required Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.1 Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.2 RedHat-like Packages RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3.3 Debian Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.4 Initial Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5 Cron Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.5.1 What does each task do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.6 Installing SNMP Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.7 JFFNMS Global Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.7.1 Basic Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.7.2 Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.7.3 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.7.4 Paths Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.7.5 PHP Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.7.6 GUI Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4 Administrating JFFNMS 23
4.1 Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.1.1 How JFFNMS calculates Total Availability . . . . . . . . . . . . . . . . . . . . . . . 23
5 Configuring JFFNMS 27
5.1 The Consolidation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6 Host Administration 29
6.1 Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.2 Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.3 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.4 Network Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3
4 CONTENTS
8 Event Configuration 37
8.1 Event Severities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.2 Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.3 Events from Syslog messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.3.1 Syslog Consolidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
8.4 Alarm States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9 SNMP Traps 41
9.1 How JFFNMS processes traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.2 SNMP Trap Receivers Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.3 Configuring New Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.3.1 Trap Setup Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
10 Polling Configuration 45
10.1 Interface Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
10.1.1 Interface Type Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
10.2 Poller Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
10.3 Poller Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
10.4 Backend Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
10.5 Graph Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
10.5.1 Aggregate Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
10.6 Autodiscovery Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
13 Expanding JFFNMS 59
13.1 Design Prework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
13.1.1 Discovery of new interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
13.1.2 Manual add of Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
13.1.3 Find the index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
13.1.4 Interface Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
13.1.5 Description Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
13.1.6 Values to collect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
13.1.7 Types of RRD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
13.1.8 Interface States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
CONTENTS 5
16 Interface Types 83
16.1 Apache Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
16.1.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
16.1.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
16.1.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
16.1.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.1.5 Configuring Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.2 BGP Peers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.2.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.2.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.2.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
16.2.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.3 Cisco SA Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.3.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.3.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.3.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.3.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.4 IIS Webserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.4.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.4.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.4.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
16.4.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.5 Windows System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.5.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.5.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.5.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.5.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.6 TCP Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.6.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.6.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.6.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
16.6.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.7 Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.7.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.7.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.7.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.7.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.8 Solaris System Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.8.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.8.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.8.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.8.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.9 Reachability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
16.9.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.9.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.9.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.9.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.10Physical Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.10.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.10.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.10.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.10.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.11blah . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.11.1 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.11.2 Status Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.11.3 Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16.11.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
CONTENTS 7
17 Satellites 89
17.1 Relationships between Satellites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
18 Error Messages 91
18.1 Running the components on the command line . . . . . . . . . . . . . . . . . . . . . . . . . 91
18.1.1 Poller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
18.1.2 Consolidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
18.1.3 Interface Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
18.1.4 RRD Analizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
18.2 Database Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
18.2.1 New installations running selinux . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
18.2.2 Query Failed . . . Table doesn’t exist . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
18.2.3 Query Failed . . . Can’t open file: ’tablename.MYI . . . . . . . . . . . . . . . . . . . . 95
18.3 Problems with PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
18.3.1 Modules for Apache PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
18.3.2 Modules for cli PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
18.3.3 Webserver displays PHP source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.3.4 Call to undefined function: mysql connect() . . . . . . . . . . . . . . . . . . . . . . 96
18.3.5 Text boxes not updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.4 Problems with Poller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.4.1 Poller returns with no hosts polled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.4.2 A lot of pollers return blank values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.5 Problems with Hosts Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18.5.1 No such variable errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.6 Problems with Consolidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.6.1 Consolidator wont raise alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.6.2 Email action returns 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.6.3 No events or Duplicate entry for key . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.7 Problems with Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.7.1 RRD files not created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.7.2 Apache Log shows problems with .dat files . . . . . . . . . . . . . . . . . . . . . . . 99
18.7.3 Apache Error Log shows .dat files have permission denied . . . . . . . . . . . . . . 99
18.7.4 Incompatible libpng version in application and library . . . . . . . . . . . . . . . . 99
18.7.5 Gaps in Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Introduction
JFFNMS stands for Just For Fun Network Management System. It uses the PHP scripting language to
collect and display the information about various devices that can be found in a computer network.
The main building block for JFFNMS is the Interface which are collected together by a Host .
The concept of interfaces is expanded from the usual meaning. While it does include physical net-
work ports, for JFFNMS it means something that either has a state, one or more values or both.
JFFNMS can report on the Interfaces condition via events, alarms, graphs or actions. It can be setup
so that an action, such as an email, is sent on a changed state of an interface, an event happening or
even when a value for an interface exceeds a specified level.
1.2 Features
JFFNMS is deceptive. Most people use it to satisfy a small set of requirements and initially use it for
those reasons alone. Then exploring JFFNMS you can see it does a lot more. Some of the features
include:
The types of devices, or “Interface Types” that JFFNMS can monitor is large and, thanks to the efforts
of the JFFNMS developers and users, growing all the time. For a list of what devices you can monitor,
see Interface Types in chapter 16 .
9
10 CHAPTER 1. INTRODUCTION
1.3 Definitions
It is important to understand the various entities and their relationships within JFFNMS. Many hours
of wasted debugging and configuration time can be saved if you understand what JFFNMS is trying to
do and the terminology used.
All network devices or network elements are called hosts. Hosts are basically a container for inter-
faces. Both hosts and interfaces can have IP addresses as well as other properties. Generally a host is
some device out on the network that has an IP address.
The definition of an interface is a bit more complex. It’s better to think of an interface as an attribute
or property of a host. More specifically, its something you want to monitor on the host. Each interface
has an interface type, which describes what information needs to be collected (by a poller group, what
information needs to be stored and how it is discovered. The easiest interface type to understand is
a physical interface on a router, switch or server; but a process, a TCP port or even a fan is also an
interface.
Using JFFNMS
If just want to use JFFNMS rather than configuring and expanding it, this is the chapter you are looking
for.
2.2 Profiles
The profile menu option allows user to setup preferences and extra information. An important option
is the email address of the user. You will need to set this if you want to receive alerts.
13
14 CHAPTER 2. USING JFFNMS
The viewer can be access via the view control either by itself or as a combination of an Map view. In
addition the viewer can appear from certain actions such as clicking on an interface icon.
By default the events are ordered by date, with the event at the top of the view being the most recent
and all events are displayed with the exception of the Unknown events.
The top of the event viewer has some icons to assist in filtering and moving around the events.
Table 2.1 shows the list of icons and their Functions.
On the far top-right of the event viewer there is a drop-down box that allows you to select from the
predefined filters. It is by default “All Events” but you can use this when you have consistent filtering
requirements.
Each event has the following column:
Ack Events that have been acknowledged get a green tick, otherwise they get a flashing light logo.
Clicking on the event gives an expanded view of that event. See below for more details about
acknowledgment
Icon Function
two up arrows Go to first (newest) event
two left arrows Go to previous event page
two right arrowssGot to next event page
Arrows in a circleRefresh current event page
+ Double the maximum number of visible events
− Halve the maximum number of visible events
all Show all events
Speaker Mute/Permit sounds for new events
Page with blue X Open another window that will export current events into CSV format
Funnel Open express filter - see Event Express Filter( section 2.3.1 )
2.4. PERFORMANCE GRAPHS 15
Type The event type. Should be a short description of the event or class of event.
Host & Zone The short names of the host and zone for the event. If there is no relevant host, for
example an event about JFFNMS itself, then this column is merged with the Type column.
Expanding the event shows the details of the 5 common event fields (Username, Interface, Severity,
State and Info). If you then click on one of the values for this field the event viewer is filtered by that
item. For example if the event has a Username field of value ‘jsmith’ then clicking on that will show all
events which have ‘jsmith’ as their username.
Customer This is the customer that has been assigned to the interface.
Map Submaps can be used to group interfaces in any way you want.
Host This option groups all interfaces found for a specific host.
Type Choose all interfaces that are the same interface type.
Selecting a group will then display a list below the group boxes that have all interfaces that match
that selection. You then have the choice of viewing all interfaces JFFNMS knows, viewing all interfaces
for that group or viewing some selected interfaces.
The interface list allows you to choose one or many interfaces. The way of choosing multiple inter-
faces is browser independent, but normally control-click will choose multiple interfaces while shift-click
will choose a group of interfaces. Obviously just clicking an interface de-selects others in the list and
chooses that one.
Click on either the links or the button to choose the interfaces.
The spanner icon will take you to the set of tools for this interface. The last icon is the report screen.
The next row have a box selecting the graph type you want to see, and then time selection. Time can
either be selected by a span, giving a start and finish time, or it can be selected by a preset time such as
“Last 6 Hours”.
Finally below the graph and time selection controls is the graphs. If multiple interfaces have been
selected then each interface will have its own graph. For graph types that permit aggregation, all inter-
faces of the same interface type will appear on the aggregated graph as well.
18 CHAPTER 2. USING JFFNMS
Chapter 3
Installing jffnms
This chapter describes the method to get and install JFFNMS. You probably also want to setup the
external programs too. To do this refer to the External Programs in chapter 15 for more information.
• net-snmp - Optional if you want SNMP alerts so you use snmptrapd. You can use an alternative
one if you prefer, but it has to be able to call an external program.
• MySQL - Need this for the libraries (eg to enable PHP MySQL) as well as to supply the main
database.
19
20 CHAPTER 3. INSTALLING JFFNMS
• tac-plus - TACACS+ Server for AAA. Optional but handy to have. (get it from the jffnms site)
• msyslog - Modular syslog daemon to insert syslog lines into MySQL or PostgreSQL databases.
(get it from the jffnms site)
• tac-plus - TACACS+ Server for AAA. Optional but handy to have. (get it from the jffnms site)
• msyslog - Modular syslog daemon to insert syslog lines into MySQL or PostgreSQL databases.
(get it from the jffnms site)
3.4. INITIAL CONFIGURATION 21
• msyslog - Modular syslog daemon to insert syslog lines into MySQL or PostgreSQL databases.
(get it from the jffnms site)
• tac-plus - TACACS+ Server for AAA. Optional but handy to have. Doesn’t need to be installed on
same server
• poller - Executes the Polling Plan every 5 minutes for each host in parallel, one ”thread” for each
host.
• autodiscovery interfaces - Executes the discovery scripts agains each host every 30 minutes and
evaluates if it has to add, modify or delete and interface, based on the applied Autodiscovery
Policy.
• rrd analizer - Evaluates SLA conformance based on the SLA Definition applied to each interface.
• tftp get host config - Gets the Host Configuration file via one plugin and stores it in the database.
Currently it works for Cisco Routers and Switches using TFTP and SNMP RW.
• cleanup raw tables - Deletes one week older ”raw” events from the trap, syslog and acct tables.
• tmpwatch.sh - Cleans the Temporary files folders and old logs in GNU/Linux/Unix systems.
22 CHAPTER 3. INSTALLING JFFNMS
Reload the snmpd so it takes the new configuration and you should be complete.
To test, use the snmpwalk program. For a remote host with IP address 192.168.1.22 using the com-
munity of public, the command is “snmpwalk -v 1 -c public 192.168.1.11 .1.3.6.1.4.1.2021.5001”. Also
try it with the last number of 5002. Both should return some tables.
If all is well, you should now have two new sets of interfaces if you do a manual discovery.
Webserver Path - This path is part of a URL for a webserver. It may map directly to a Filesystem
path or, using things like symbolic links or apache aliases for example, be just a virtual directory.
Webserver paths are accessed from a browser and JFFNMS sometimes calls them relative paths.
Absolute Path - The filesystem path to the top of the JFFNMS directory tree. Subdirectories of this path
would be things like htdocs, lib and engine. Both users need to read the files in the subdirectories.
Webserver Relative Path - The top of the webserver path or the directory part of the URL. If JFFNMS
is installed on a server called mynoc.example.net and you set this field to /jffnms then the URL
to get to JFFNMS would be http://mynoc.example.net/jffnms/
TFTP Server Files Path - The filesystem path where TFTP files will be temporarily put. The cron user
needs write access to this directory. When setting up the TFTP server its “root directory” needs to
be the same as this value.
RRD Files Path - The filesystem path where RRD (Round Robin Database) files will be stored. The
cron user needs write access and webserver user needs read access.
Engine Temp Files Path - A filesystem path for temporary files that the poller and other systems use.
Both users need write access.
Log Files Path - A filesystem path for the log files, if they are enabled. cron user needs write access.
Temp Images Absolute Path - A filesystem path for putting the temporary files that make the images,
such as the interface alarm icons. Needs to be writable by webserver user.
WebServer Temp Images Relative Path - The webserver path for the URLs for the images. In other
words the system should be setup so that requests for items that have this field in their URL will
get the webserver serving files from the “Temp Images Absolute Path” real directory.
PHP Executable Path - The full filename of the PHP executable. JFFNMS requires both the PHP mod-
ule and the separate executable. For most installations it would be either /usr/bin/php or /us-
r/bin/php4.
GraphViz Neato Executable Path - Full filename to the neato program which is part of the graphviz
package.
GNU Diff Executable Path - Full filename to the GNU diff program. The program is used for things
like displaying the differences in configurations of hosts.
NMAP Portscanner Executable Path - Full filename for the nmap program. Nmap is used for finding
TCP and UDP ports on remote hosts.
FPING Executable Path - Fping is an improved version of the ping program. This executable is used
for the reachability interfaces.
SMSClient for SMS via Modem - optional - The full filename for the smsclient program. You only
need this if you are going to send pagers via a telephone modem.
NTPQ Executable - optional - The full filename for the ntpq program. This is a query client for the
NTP protocol and with this you can check that local or remote hosts have their time server syn-
chronized.
Register Globals set to On - This means the globals are available everywhere. Most PHP versions now
ship with this turned off by default.
Allow URL fopen set to On - This option allows PHP programs to open connections to URLs (or re-
mote sites). Required for TCP Port content check to work.
SNMP Module Loaded - You need to have SNMP module loaded if you want to do any SNMP gets.
JFFNMS could be used without this module loaded but it would be severely limited in what it
could do.
Sockets Module Loaded - Used to make external connections to remote hosts.
GD Module Loaded - The GD module is used to generate some graphics, such as the hosts and inter-
faces alarm boxes.
optional MySQL Module Loaded - This module allows you to store the information in a MySQL database.
Either this module or the PgSQL module needs to be enable for JFFNMS to work.
optional PgSQL Module Loaded - The module to allow access to a PostgreSQL database.
Perl RegExps Module Loaded - If you want to use Perl Compatible Regular Expressions (PCREs) this
module needs to be loaded. PCREs are generally better and faster than the old POSIX REs.
optional - WDDX Module Loaded - This module can be used for transferring information from the
satellite servers. Recommended if you are using satellites but otherwise not needed.
GUI/Auth Login Method - Most people leave it as login screen, HTTP authentication means you get
the standard ugly login box instead.
Login Screen Image URL - The URL for the login graphic
Login Screen Image Link URL - The link the user will go to if they click the image.
Custom CSS Stylesheet URL - If you want to change from the default look, create a CSS Stylesheet
and put its URL here.
26 CHAPTER 3. INSTALLING JFFNMS
Chapter 4
Administrating JFFNMS
Apart from configuration, there are some tasks that the administrator may need or want to do with
JFFNMS. This chapter describes these tasks, when they are needed and what to do.
4.1 Reporting
JFFNMS can report on the availability of a system of a set of interface or on individual interfaces them-
selves. The reports are found at the Administration menu item Reports ⇒State & Availability. The
interface selector is like the one you see for the interface administration screen and the performance
screen.
For a report you select the interfaces you want to report on, using the interface selector and the time
period you want the report for. You can also choose what event types you will consider for an interface
being up and down.
In the top right corner, there is a view details option box. Clicking this box will show the details of
the alarms, including their start and stop times plus their duration.
For each interface selected, you get a report on: round trip time and packet loss (where relevant);
Unavailable time ; Availability. Unavailable time is the total time that the interface has been considered
in the down state for the selected time period. The availability is:
27
28 CHAPTER 4. ADMINISTRATING JFFNMS
Time InterfaceState
10:00hs A Down
11:00hs B Down
12:00hs B Up
13:00hs C Down
14:00hs A Up
15:00hs C Up
side effect of this is that all interfaces are assumed up at the start of the report and have to be up at the
finish of it (otherwise their stop time is past the end of the time period).
The table above shows a system outage of 5 hours long, starting at 10:00 when interface A went
down and finishing at 15:00 when interface C comes up. Using a method such as this one means you
get a Total Unavailable Time of 5 hours instead of 7, which is the sum of the 3 outage times. 5 hours is
correct, because this is the time that one or more of the interfaces being considered was down.
The Total Availability is now easily worked out using the Total Unavailable Time and Total Selected
Time
Configuring JFFNMS
There are a wide variety of objects (internally called structures) within JFFNMS. To really understand
JFFNMS, you have to get a good understanding of its objects and the relationships between them.
The objects are arranged in order as you would see them in the administration screens. This is done
to help you find the object you need and also the administration menus are arranged in a logical order.
31
32 CHAPTER 5. CONFIGURING JFFNMS
Chapter 6
Host Administration
Hosts are the reason for wanting JFFNMS in the first place. They are the devices that have interfaces that
need to be monitored. This could be an ethernet port, a program running or even some environmental
variable like temperature.
Hosts are grouped together in Zones but they also can be arbitarily grouped into one or more
submaps. The actual thing that is monitored on a host is called, within JFFNMS, an interface.
6.1 Zones
In earlier versions of JFFNMS, Zones were merely a grouping of Hosts( section 6.2 ) which could be done
in any way that made sense to you. Newer versions now use the Zones for Network Autodiscovery
policies. Zone configuration is found at Administration menu item Hosts and Interfaces ⇒Zones.
Table 6.1 describes the contents of the Zone table. The section on
The Seed CIDR parameter tells the Network Discovery where to initally go looking for hosts. There
can be multiple networks specified as long as they are separated by a comma. The CIDR notation
is network/bits. For example to scan all of the Class A 10.0.0.0 network and the Class C 172.16.1.0
network, the parameter would be 10.0.0.0/8,172.16.1.0/24
The Max Hops parameter is used to limit how far out JFFNMS goes looking for hosts. A level of
1 means only hosts contained in the CIDR block column will be scanned. 2 means all of level 1 but
also any immediately adjacent subnets would be scanned. 3 means everything 2 does, but also adjacent
subnets to the ones found in 2, or subnets that are 2 hops away from your seed subnets.
6.2 Hosts
Hosts are the actual servers or computers that you are monitoring. It’s essentially something that has
an IP address. Hosts are also containers for interfaces. A host has the following fields:
IP Address The IP address of the host that is used for the poller
Read Only Community The SNMP community string to get read only access
Visibility FIXME
Autodiscovery Policy The policy used for autodiscovery of interfaces for this host, see AD Policies in
section 10.6 for information.
33
34 CHAPTER 6. HOST ADMINISTRATION
Column Description
Zone Description or name of the Zone
Short Name Short name of the zone, often the same as Zone column
Image A location of a small icon for the zone that appears in the event view.
Image files are located at JF F N M S/htdocs/images.
Visibility Determines if the hosts and interfaces are Shown, Hidden or Marked
disabled.
ND Enabled If this box is checked, Network Discovery is enable for this zone.
Seeds CIDR Seed networks to start autodiscovery in CIDR (network/bits) notation.
Allow Private IP If checked, Network Discovery will include Hosts that use Private IP
addresses.
SNMP CommunitiesA comma-separated list of SNMP communities to try on newly found
hosts.
Max Hops How far wide to scan for networks?
Re-Scan How often to go and and re-scan the networks for new hosts.
AD Default Customer the customer that auto-discovery will assign to a newly discovered interface, if
you leave Unknown, you will see a message every 30 minutes saying that the interface setup is
incomplete. Customers have to be configured as described in the User Administration( section 7.2
).
Main Interface if the interface(s) selected here are down, the poller will only check them (and not all
other host interfaces) until they are up.
TFTP Server IP The server to transfer the configuration file to, this should be configured to the JFFNMS
server IP address from the Router point of view. Only used for hosts that you will be transferring
configuration files from.
Config Transfer Mode For Cisco routers and switches, which method to get the configuration.
Tacacs+ Source IP Useful when you run TACACS over tunnels or something (not the same IP for
polling) this is the Source IP of the TACACS request (could be the same as the IP if you have
configured your router that way).
Satellite Set to Local for most circumstances
Latitude
Longitude
You can either add the hosts here or get JFFNMS to do it automatically using Network Discovery(
section 6.4 ).
6.3 Interfaces
Interfaces in jffnms are not only the physical devices that connect a Host to the network. They also
include service/daemon ports or some SNMP parameter. You can think of an Interface as some attribute
of a host that you need to watch (can I ping this IP address, is the mail port up?)
Interfaces can be viewed by Administration menu Hosts and Interfaces ⇒Interfaces. This brings up
the Interface selector. You can then choose interfaces using various criteria.
After selecting a group of interfaces, the interface table appears in the middle frame. The table has
the following parameters
Customer This is the owner of the interface. The customer can also login and see their interfaces.
Poller Group The group of pollers/backend that is defined in the interface type. for instance the Cisco
Interface Poller Groups defines all the OID’s and the way to use them in the Physical Interface
Type.
Check Status
SLA The SLA that is used against the interface. See section 13.12 about SLAs.
Enable Sound Enables audible alerts on the Interfaces Screen if the interface changes states.
Show in Maps This option will determine if the interface is visible in the root map or not. You also
have the option of showing the interface disabled,which means it will be gray on the map.
The interface table will also display other columns that are specific for that interface type. These
columns will be different for different types of interfaces.
6.6 SubMaps
Submaps are a way of grouping the display of hosts or interfaces. They are in a hierachial tree setup
with the root of the tree being the map called “Root Map”. Each submap can be a direct child of the
Root Map or a child of another submap. A submap has a name and a background colour.
A User can optionally have a profile setting that gives them a base map. This means they will only
be able to see their base map and any of its decendants.
Clicking on the View item for a submap shows all the interfaces that are visible for that submap.
You can add more interfaces to a submap by clicking the add button above the SubMaps/Interfaces
Administration list or use the add to submap feature in the interfaces configuration.
6.7 Satellites
Satellites is the JFFNMS RPC (Remote Procedure Call) System, its used for Distributed (Load Balanced
and Fault Resistant) Polling, and also allows External programs to call JFFNMS public API’s, this is
useful to integrate JFFNMS with your other applications.
There are various protocols available, like HTTP/Serialize, SOAP, TCP/WDDX, etc.
36 CHAPTER 6. HOST ADMINISTRATION
Chapter 7
JFFNMS has two types of people that can have access to it: Customers and Users. Customers only
get the output or a view of what JFFNMS monitors while Users interact and change JFFNMS and the
monitoring itself.
Customers are the customers of the servers or services that you are providing. They will be inter-
ested in know how well a particular server or interface is performing and how often an interface has
gone offline. They get read-only access of the interfaces that they are the owners for.
Users are the administrators and operators of JFFNMS. With the exception of access levels or enabled
features, there is no distinct difference between users who are network operators and users who are
administers of JFFNMS itself.
7.1 Customers
Customers are people or organizations that own or use a service, which in JFFNMS is called an Interface
. You will need to make at least one customer (eg “Common” or “myISP”) so that other objects are
owned.
Customers may also have a Username and Password. This is not the same as a standard user but
gives a limited access to the system so the Customer can look at some performance graphs for their
equipment.
The Customer list is found in the Administration menu item Users and Customers ⇒Customers.
Each customer has the following properties:
JFFNMS allows Customers to login and view the performance graphs of interfaces that have been
assigned to them. To do this they need to login with the username and password that you have entered
into this table.
7.2 Users
Users are the operators and administrators of JFFNMS. These would be the people who are responsi-
ble for the ongoing maintenance and monitoring of the network elements, as well as the people who
configure and customize JFFNMS itself.
Unlike customers( section 7.1 ), Users cannot own interfaces. However if you want to limit the
interfaces they can see you can do this with Maps.
Selecting the Administration menu item Users and Customers ⇒Users shows the table of all config-
ured users. Each row of the table shows the following features of the user:
37
38 CHAPTER 7. USERS AND CUSTOMERS
Field Description
Action A combo box allowing you to perform various actions on this user
Username The username this user uses to login to JFFNMS
Password Password used to login to JFFNMS
Full NameFull name of the user
Router Used to link to modified TACACS. Users with this clicked will be able to
authenticate via the linked TACACS.
1. Bring up the Users Table (see Figure 7.1) by going to the Administration menu and selecting Users
and Customers ⇒Users.
2. Find the user in the table, on that row make sure the drop-down box is showing “View User
Triggers”.
3. Click the blue arrow immediately to the right of the drop-down box to view the triggers for this
user.
4. Click on the Add button at the top of the trigger table.
5. Choose the trigger you want to use
Event Configuration
Events are generated by the different consolidators that are run out of cron every minute. They are
some piece of information that has come into JFFNMS that it recognises.
Events come from pollers, syslog and SNMP traps. They have a type and a severity. Events then
may cause an interface to have an alarm or for an alarm on an interface to be removed.
Events have 4 fields; Username, Interface, State and Info. The Username and Info fields are just
generic containers to provide extra information about the event. Interface and State are used by the
consolidators to map an event to a specific interface and set the alarm severity of a subsequent alarm
respectively.
The event consolidator runs over the new list of events that have come in recently. An event that
has its type configured in the Event Types Table( section 8.2 ) to generate an alarm is then examined.
The Event needs to have an interface associated with it, which means there is a host defined and the
interface field in the event matches the name of one interface in the host. In addition the state field of
the event needs to match one of the Descriptions in the Alarm States Table( section 8.4 ).
Description A short description of the event. This will appear in the event viewer.
Severity The severity of the event chosen from the list defined in the Event Severities Table( section 8.1
)
Event Text A string template that will display in the message column of the event viewer.
Show in Event Viewer? An event can always be displayed, never be displayed or only displayed if the
filter specifies it.
Event Generates an Alarm? Check this is the event is supposed to generate an alarm for this interface
on the event.
Different Alarm for Up Event If you want the event to be different when the state is up change this to
the Up event, otherwise leave it as Unknown.
41
42 CHAPTER 8. EVENT CONFIGURATION
Field Description
DigitMatches the Nth captured subpattern, or the thing in brackets in PCRE
matches or the Nth word after the literal text.
∗ The field will have the whole syslog message
D Everything past the match
otherAnything else the field gets the value configured
Alarm Duration If the event generates the alarm, how long is the alarm for.
Show Host Field Some events have no host, such as internal JFFNMS events. Most events have this
item checked.
Event Text is a mixture of plain text and parameters derived from the event and the interface the
event has occurred on. Parameters are described in <> signs, eg < user > for the user field, the
following parameters are defined:
The standard set of fields that can come from all events are user, state, info which come from the
syslog or SNMP trap consolidation. If the event also is associated with an interface then the Interface
Parameters( section 13.14.1 ) can also be used in the template.
The “Show in Event Viewer?” means by default you will see the alarm. If you want to record the
event but don’t want to see it by default don’t click this option. You can use Filters(see Section 12.1) to
display the other events.
Field Value
Interface vty0
Username craig
Extra Info console
Event TypeConfiguration
Action ID Text Match Interface Field Username Field State Field Extra Info Field Event Type Position
Edit Del 10001 %SYS-5-CONFIG I: Configured from (\ S+) by (\ S+) on (\ S+) 3 2 1 Configuration 1
substring[3] = ”vty0”
We want the Interface field to be filled in with ”vty0”, so in the Syslog Message Rules, we put 3
the Interface Field column. That tells jffnms to fill in the Interface field with the first substring match.
Similarly, Username has 2 and Extra Info is 1. There is no need for the numbers to be sequential or even
for all of them to be there, however the number of bracket pairs must equal the highest index; eg in our
example putting 4 in any of the Fields columns is invalid.
We’re not using the State field here, so its column is blank.
The full syslog event line in JFFNMS will look like table 8.3.
You would then setup an event in the Event Types to display the information.
Column Description
Description A short description of the alarm level. This field is used by the event
consolidator to match the state field to an alarm state.
Alarm Level The importance of this level of state. The lower the number the more
important. For example, a down state is more important than an up, so
down has a default level of 10 and up has a level of 100. This means the
state of an interface, if it has both active events with a state of up and
down will be down.
Sound In If an interface goes into this alarm level, send this sound to the GUI.
Internal StateThe internal alarm state that this state should map to. There are only 4
alarm states, see table 8.5.
State Description
Up Interface is up and working and online
Down Interface is down or not working or offline
TestingInterface is testing or training, it cannot be currently used but is enabled
Alert Interface is up but has had some warning or degradation
Chapter 9
SNMP Traps
SNMP stands for Simple Network Management Protocol. The funnny thing about the name is that
SNMP is most definitely not simple! At pretty much any stage of understanding SNMP; from the
concepts, through to the data layout, right down to the coding; it is not simple. Fortunately you can
often ignore all the gritty complex detail and make vast simplifications.
One part of SNMP is a trap. A trap is a one-way message from a network element; such as a router,
switch or server; to the NMS. The messages are sent via UDP, which means they are not guaranteed to
arrive.
The most common messages are the 6 generic messages. The main ones being link up, link down
and agent reset (which usually means the device was rebooted). There are also whats called “enterprise
specific” traps, these are the ones the vendors create and can give a rich set of traps, if they will tell you
what they mean.
45
46 CHAPTER 9. SNMP TRAPS
Field Description
ID The internal ID of this rule, only needed for debugging
Position Releative position of this rule to the others in the table. JFFNMS pro-
cesses the rules from lowest position to highest.
Description Description of the trap of what this rule does.
Interface Type The Interface Type that this trap should apply to.
OID Match SNMP traps are identified by OID, traps that have this OID will be pro-
cessed by this rule.
Receiver CommandWhich script in the directory engine/trap recievers will be used to pro-
cess the varbinds into event fields.
Parameters Parameters passed to the Receiver Command script.
Backend What backend to process the output of the Receiver Command. They
are identical as the poller backends, see Backend Items( section 10.4 ) for
details about them.
Stop If Matches Do no more checks for this trap if the OID matches.
use the event backend plugin which will put a new row into the event database table. This new event
will then show on the operator screens.
• What is the OID of the trap? This identifies the trap from all other ones.
• What, if any, Interface Type would this trap apply to? A trap about a phyiscal interface down
would apply to the “Physical Interfaces” interface type.
• Are the varbinds going to be processed and if so what event fields will they become? For example
the first varbind might be the interface state
• What backend to use, or if the trap is received, what do you want to happen? Most people want
an event to be raised, in which case you use the event backend.
Most of this is pretty useless, we only really need to know something has happened and then to
what fan is it.
So we setup the event to fill in varbind 2 into the info field and then setup a new event which prints
Problem with fan at ¡info¿.
The idea with the SNMP traps is to plan forward but implement it backwards. A lot of the other
objects should be done this way too.
So start with the event first. Create a new event type, you can see this in the Event Types( section 8.2
) section. Note down the event ID.
Create a new Backend( section 10.4 ). The Backend Command will be “event” and the Paramter will
be the id of the new Event Type you created in the previous step.
You now need to create a Receiver Command. As it is infinitely easier for me to code one than
explain it ill just assume I wrote it for now. As we are mapping varbinds to variables, well assume it is
called mapping.
Finally create the new SNMP Trap Receiver( section 9.2 ). The OID is the OID of the trap. The
Receiver Command is mapping, while the parameters are info=2 (which means the event field called
info will get the contents of the second varbind). Backend is the backend you created previously.
48 CHAPTER 9. SNMP TRAPS
Chapter 10
Polling Configuration
This chapter describes all the backend collection and collation processes. It is used to describe new host
or interface types and is how you add new sorts of checks. Unfortunately it is pretty complicated to
wander your way around. The good news is you may not need to edit any of these tables for a default
JFFNMS setup.
At first there are pollers, that collect data, and backends, that do something with the data that are
collected by the poller. An interface type determines what values are stored and how autodiscovery is
used. Finally a Poller Group creates a type which is a single interface types and a collection of pollers.
FIXME - Poller Group and Interface types have a cross reference, why? FIXME - it was for filtering
ease, and Interface Types needs a Default PollerGroup and PollerGroups need to be filtered by Inter-
faceType on the Interfaces Screen.
49
50 CHAPTER 10. POLLING CONFIGURATION
Field Description
Index A field that is unique for this Interface Type for a particular host. This is
used by JFFNMS to determine which interface is what. For example, for
SNMP interfaces JFFNMS uses the ifIndex SNMP OID.
Boolean A value that can only be Yes or No.
Description Interface icons that appear in the maps have the value for the description
fields in them.
Other A text field that is not part of the Index or used for Description.
RRDTool DSA Data Source (DS) definition for a RRD file.
Have Tools If checked interfaces of this type have the tool icon displayed which takes the user to the
tools.
Have Graph Cosmetic Option, show a link to the performance (graph) system from the Interface Map.
Default Graph Cosmetic Option, which graph to show by default on the Performance Viewer, from
the Graph Types( section 10.5 ) Table.
Default SLA New interfaces of this type are given this SLA if discovered.
RRDTool Structure RRA A standard RRA definition as specified in RRDTool manual page. Try to use
RRA:AVERAGE:0.5:1:<resolution>
¡resolution¿ is replaced by the interface type resolution defined in the RRDTool Resolution Field.
RRDTool Resolution - this is RRDTool resolution (how many datapoints do we need to store) 103680
is one year of 5 minutes intervals.
RRDTool Step The step in a RRD file in seconds. This should be 300 (5 minutes) for almost all cases.
Description A simple description of the field. For fields of Description type this string is displayed in
the Interface icon on the maps.
Internal Name This string is used by things such as the poller name and interface fields.
Show This option will decide if the field is not shown anyway, shown in discovery and interface editing
tables or just the table.
Overwritable With this field checked, Administrators are able to overwrite the value
Tracked Fields with this value checked will cause alarms if the autodiscovery detects a change.
Default Value For most field types this is the value of the field if the autodiscovery does not fill it in.
For RRDTool DS types it is the definition of the data source.
As previously mentioned, the Position attribute sets the orders of fields of the same type. For De-
scription field types, it is the order of the fields that are displayed in the Interface maps. The top-most
field having the lowest position number.
RRDTool DS fields also use the Position attribute for ordering. Generally a Poller Group( section 10.2
) will collect information.
The definition of RRD files is out of the scope of this document, the general idea is the same for all
RRD files not just ones defined in JFFNMS. Each RRDTool DS field has 4 attributes that define the Data
Source.
The first is the DS type which uses the standard definitions of an RRD. The type can be Counter,
Gauge or Absolute. The Min field is for the minimal value. Any value under this minimum is not
added to the RRD.
Maximum value can be fixed or be derived from another field. If it is fixed then the value goes in
the box immediately to the right of the Max: label. For maximums that come from another field, put
the field name (Internal Name) in the Use box and check the “for Max:” checkbox.
1. Verify that the id of the interfaces is still correct using an interface specific poller and the ver-
ify interface number backend.
2. Check the status of the interface and use the alarm backend to signal if there is a problem (or there
was and now the interface is OK).
3. Collect some statistics about the interface, such as byte counts and store in temporal buffer.
• Name - This must match an RRD DS column that has been defined in the RRDTool Structure DEF
column in the Interface Types( section 10.1 ) table if you want this data to be stored on a RRDTool
file.
• Poller Command - What program in engine/pollers will be used, “.inc.php” is appended to the
name. See below to see what commands are already defined.
• Parameters - What parameters are passed to the command. This column is dependent on what
command you use. Predefined variables are explained further on.
52 CHAPTER 10. POLLING CONFIGURATION
Option Desctiption
Default Poller New interfaces use the default poller as defined by the interface’s Inter-
face Type( section 10.1 ). If this option is not used, then No polling will
be performed on new interfaces.
Permit Add Allow the Autodiscovery process to add new interfaces if an interface is
found but not in the database.
Permit Delete Allow the Autodiscovery process to delete existing interfaces when they
are not found in host.
Alert on Delete Create an event when deleting an interface.
Permit Modify Allow the Autodiscovery process to change interface attributes.
Permit Disable Allow the Autodiscovery process to disable an interface.
Skip Loopback Do not discover loopback interfaces (Interface name begins with “loop-
back”, “lo” or “null” or IP address is 127.0.0.1) .
Check State Only interfaces that are operationally up will be discovered.
Check Valid AddressInterfaces need a valid IP address before they are discovered.
Description The name of the graph. Appears in the drop-down box on the Performance pages.
Interface Type The Interface Type the graph is for.
Allow Aggregation Does this graph have permit an aggregation graph, that is a single graph that can
show multiple lines of data of the same type. For more information see Aggregate Graphs.
Graph 1 This is used to find the name of the file the graph definition is located. The filename will be
JF F N M S/engine/graphs/ < name > .inc.php
Width 1 Width of the first graph
Height 1 Height of the first graph
Graph 2 Filename of second graph
Width 2 Width of second graph
Height 2 Height of second graph
While they are two separate things, triggers and actions work together. There is no point in only having
one without the other. A trigger and action are like a sentence such as:
For example, you may light to send an email if an interface for a particular host goes down, the
sentence would read:
Triggers are part of the system for JFFNMS to send out notifications when certain specific things
happen. The most common example of a trigger is JFFNMS sending an email when either an event or
alarm occurs.
To setup a trigger, there are a few steps involved, this chapter will explain what those steps are and
how to get triggers working. In brief, they steps are:
55
56 CHAPTER 11. TRIGGERS AND ACTIONS
Column Description
Position Rules can be ordered within a trigger. They are evaluated from the low-
est position to the highest.
Field What value of the alarm or event is used for the matching? For example
selecting Host here will mean this row uses a set of hosts specified in the
Value table to determine if it matches.
Operator A comparison operator for comparing the value of the field with the
value given in the Value column.
Value The value that the Field is compared to. It may be a select box or a text
field depending if JFFNMS can determine the valid values.
Action Which Action to execute if this line matches. Set to No Action if there
are subsequent rules.
Parameters- Fill in the parameters Asked by this Action. These are defined in the
action table by the User Parameters field.
if Match This field determines if any more rules are evaluated if this rule matches.
Boolean The last column has no title, but is used to determine how the next row
compares to the last.
Column Description
Description A small description of what this action does.
Command Command name, used to determine what action plugin is included, see
notes above for details.
Internal ParametersA comma-separated list of key:value pairs. These values will be avail-
able to the action plugin. See Creating a New Action( section 13.11 ) for
details on how these values are used.
User Parameters Another commas-separated list of key:label pairs. They are used in the
Trigger Rules( section 11.2 ) table for the Parameters column.
Position Condition
10 A AND
20 B OR
30 C
However to fire the trigger if A happens or if B and C happen, then the table would be reconstructed
like this
Position Condition
10 B AND
20 C OR
30 A
11.3 Actions
Actions need to be defined in this table as well as created in the code. The action Description is ref-
erenced by the Trigger Rules( section 11.2 ) and gives a name of what the action is trying to do. The
command is used by the code to load the engine/actions/commandname.inc.php file and call the ac-
tion commandname() function.
Actions are define in the table found in the Administration menu Internal Configuration ⇒Triggers
& Filters ⇒Actions Definition. The table described in Table 11.2 appears.
11.4. PUTTING IT ALL TOGETHER 57
The Parameters can have tokens in them, so JFFNMS can fill in some specific details about the alarm
or event that trigged the action. The tokens are written as “¡object-parameter¿. For example, to print the
hostname of an interface, you would put “¡interface-host name¿”. The objects are interface, action and
event. The parameters are found Common Parameters( section 13.14 ) section.
To see how the various Parameter fields work together, consider the email action. It requires input
from the user for each trigger that uses that action. The input is the subject and a comment. The
User Parameters field is “subject:Subject,comment:Comment” meaning there will be two fields with
the labels Subject and Comment and the email action will receive the value of those fields in the array
value parameters[‘subject’] and parameters[’comment’].
1. Bring up the Triggers table by selecting Administration menu item Internal Configuration ⇒Triggers
& Filters ⇒Triggers Configuration.
2. Click Add at the top of the Triggers table, a new Trigger row opens in edit mode.
3. Enter “Claymore Interfaces” as the trigger Description
4. Make sure “Match Alarms“ is selected for the Type
5. Click the Save button.
6. The Triggers table show be redisplayed with the new Trigger you have just created, now it is time
to enter in the rules.
7. Click ”View Rules“ on the line showing the Trigger, a Triggers Rules table appears below the
Triggers table.
8. Click Add from the Triggers Rules table, a new Trigger Rule row opens in edit mode.
9. Change the Field column (the second one) to Host and then click Save. You have to edit the row
twice to get the list of Hosts. Leave everything else the same.
10. Click edit for the Trigger row, the row now changes to edit mode.
11. Choose the Host called Claymore from the list in the Value column.
12. Check that Action column is ”No Action“ and the last column is ”AND“. If so click the Save
button.
13. Click the Add from the Triggers Rules table, yet another new Trigger Rule opens in edit mode.
14. Change the Position column to 20.
15. Change the Field column to Type, this means we will be matching on Alarm type.
16. Change Action to ”Send Email“, the parameters are not shown at the moment.
17. Change ”if Match“ column to ”Stop this Trigger“.
18. Click on the Save button, the Value and Parameters columns change because the Field and Action
were changed respectively.
19. Click on the Edit button for the row just created (Position 20).
20. Select ”Interface Protocol“ from the Value column.
21. Put in some values in the Parameters column, perhaps giving some information about this host.
58 CHAPTER 11. TRIGGERS AND ACTIONS
You now have a new Trigger which will send email if an interface on the host Claymore changes
state. Your screen should look something like Figure 11.1.
Next you have to tell JFFNMS who will be getting these emails and what their email address is.
First of all, make sure that the user has an email address set. This is done in the User Profiles Table(
section 7.2.3 ) by entering in the user’s email address in the eMail option.
Next you need to apply the trigger to the user, this is explained in the User Triggers( section 7.2.4
) section, more specifically the part about adding a new trigger for a user. Your newly created trigger
should be in the list of available triggers when you click on the Add button.
1. Bring up the User Trigger table by selecting Administration menu item User and Customers
⇒Triggers Users.
2. Find the relevant row for the User and Trigger Pair.
3. Click on the Edit button, the row re-appears in edit mode.
4. Un-check the Active column so the tick disappears.
5. Click the Save button, the row reappears in view mode.
11.6. TRIGGER LOGS 59
To re-activate the Trigger, follow the above process only ensure that the Active column has a tick in
it.
19:10:22 ==================================================
19:10:22 alarm 16: T 3 - P 10 - R 3 If ’interface_host(2) = 3’ (0)
Stop
19:10:22 alarm 16: ---------------------------------------------------------------------
19:10:22 alarm 16: T 4 - P 10 - R 5 If ’any’ (1) Then email (1)
Each line shows, from left to right: localtime, alarm id, Trigger id, Position of rule in trigger group,
id of trigger rule, then the evaluation.
Alarm 16 has been raised (this is just the alarms internal ID). There are two triggers defined, one
with Trigger ID 3 and one with 4.
Trigger 3 has its first rule at position 10, which is rule number 3. This rule tries to match the host. It
wants to match to host with id 2, but the alarm is for host 3, therefore it is not a match (the “(0)”). In
addition the rule says to stop evaulating for this trigger.
Trigger 4 is rather simple, if there is something in the alarm, it is a match. Naturally this is only a
test alarm. As there is a match, the action is Then performed, which was the email action. The email
action returned 1, which means it was successfull.
11.7 Tools
The tools are links that can be found on the expanded view of the events table. Clicking on the flashing
light or tick icon will expand the relevant event.
A tool consists of a description, an URL, an optional image for an icon and a filter. The URL can
have the usual macros, e.g. ¡interface id¿. The filter is the same set as the express filters used on the
events viewer itself.
60 CHAPTER 11. TRIGGERS AND ACTIONS
Chapter 12
12.1 Filters
Filters are used to filter in or out different events based upon some fields in the event types. By default
all events that have had their “Show in Event Viewer?” option ticked are shown which is set in the
Event Types( section 8.2 ) table. They are also used for Tools to determine which tools are visible in the
expanded view.
Unlike SLAs, Filters do not use RPN logic but are written in a standard fashion. To access the
filters, select the Administration menu item Triggers & Filters ⇒Event Filters. You will get the table of
currently defined filters.
Filters are only a container that has a Description and is used to hold Filter Conditions( section 12.2
). The Description column is what appears in the Event Viewer. To see the the Filter Conditions, click
on the View button for the required Filter.
Field Description
Position Each condition within a filter is ordered. The conditions are evaluated
from the lowest position value to the highest.
Field The field that will be evaluated in the event against the value column.
OperatorHow the Field and Value columns are compared. The operators are:
equal; not equal; less than; more than.
Value The value that is compared to the Field, using the Operator.
61
62 CHAPTER 12. CONFIGURING EVENT FILTERS
Expanding JFFNMS
While JFFNMS comes with many interface types, the sad fact is that the world is filled with a large va-
riety of things you can monitor, graph and alarm. This chapter describes how you can expand JFFNMS
so it is able to monitor something new.
If you are happy with your creation and think others could benefit, it would be a nice idea to con-
tribute to JFFNMS by sending in your patches and SQL statements.
63
64 CHAPTER 13. EXPANDING JFFNMS
poller which changes the index field to match a fixed description field is an example of this corrective
poller. The TCP port number for the TCP port interfaces is the best sort of index field because the index
completely describes the interface; you cannot have TCP port 53 moving to TCP port 80.
Usually there can be some fallback index which is the order that the discovery plugin detects them.
This is definitely not recommended, especially for interfaces that can be dynamically added and re-
moved, but sometimes it is the only index you have. All interface types require an index.
Quite often it is easy to get these wrong. The absolute one is, in the authors experience, quite rare so
unless it is something very strange you are measuring then it won’t be this one.
If you are using a counter type and the values are going negative and they shouldn’t be (eg packets
per second) then this item is a gauge. Alternatively if your gauge item is steadily increasing and you
think it should be approximately level then you probably should be using a counter.
To illustrate how it all works we will use the Admin Status Change View backend which is used by
Physical interfaces. It has the Parameters of “show rootmap ,down=2—up=1,0”. This will mean that if
the field show rootmap is not already 0 and the poller output is “down” then show rootmap is changed
to 2. Similarly if the value is not already 0 but the poller output is “up” then show rootmap is set to
1. Finally if the show rootmap value is 0 or the poller output is not “down” or “up” then the field is
unchanged.
The backend returns 1 if there is a database change and -1 if there was none.
Field Description
host id The Host ID from the Hosts Table
host ip IP Address of the host.
rw community SNMP Read/Write Community from Host.
ro community SNMP Read-Only Community from host.
interface id Internal sequence number in database for this interface.
interface number IfNum column.
interface descriptionDescription column.
address IP Address of the interface.
peer Peer IP address (for BGP interfaces).
bandwidth in Incoming (downloading) bandwidth.
bandwidth out Outgoing (uploading) bandwidth.
poller name Name of poller from Pollers Table.
poller parameters Parameters column from Pollers table.
random Random number between 10 and 99.
time start Start time of poller, from time().
noerrors Has the No Poll Errors been selected. (deprecated)
lot are taken directly from the database and describe the interface being checked. They get their values
mainly from the Interfaces table.
The parameter can be described in any way, because is supplied to the poller in the poller parameters
variable of the options array and the poller has to parse it.
The poller function returns a value which is then directly sent to the backend which also gets the
same parameters described above. Useful values to return depend on the backend. For the alarm
backend ”up” and ”down” are generally used. For most others a number of the measurement is used.
Second’ ”.
Field Value
real serverIndex number from index row
interface IP address of real server
admin Administrative state of server
Oper Operational state of server
hostname Real Server name
Both commands run a snmpwalk on the device. The first loads all MIBs in the current directory
(where the Alteon MIB files are) and the common MIB directory. The second command shows the same
information but the OID is now numeric with the -On flag.
The hard slog is to work out what OIDS are useful and what are not. Quite often SNMP items are in
tables, and we find that the Real Servers are in two tables, so lets start documenting the information we
will require. I have only used the shortened SNMP information here.
Index: slbCurCfgRealServerIndex
Description: slbCurCfgRealServerName
IP address: slbCurCfgRealServerIpAddr
Maximum Connections: slbCurCfgRealServerMaxConns
Admin State: slbCurCfgRealServerState
Oper State: slbRealServerInfoState
Total Sessions: slbStatRServerTotalSessions
Octets: slbStatRServerHCOctetsLow32
We have a nice set of OIDs to work with, coming from the configuration, information and stat tables
of the real server. There is an explicit index field, but what should be the “Interface Name”?
The name should mean “this interface”, a unique property that sets it apart from all the other inter-
faces of this type. A real server is defined by its number and IP address, however it would be nice to
correlate the syslog messages into events and alarms. The messages look like
WebOS <slb>: cannot contact real server 10.20.100.3
WebOS <slb>: real server 10.20.100.3 operational
The syslog messages reference the server by its IP address, so this should be its name.
Description Name (Match RRD Struct DS) Poller Command (file) Parameters
Alteon RealServer Octets octets snmp counter .1.3.6.1.4 . . . 7.¡index¿
Alteon RealServer Sessions sessions snmp counter .1.3.6.1.4 . . . 8.¡index¿
bottomrule
The poller command is snmp counter and the Parameters are the SNMP OID you want to collect.
The Name comes from the Internal Name that you put in the Interface Type fields for your new interface
for the RRD fields. The OID also needs the instance or the row of the table’s column, put “.¡index¿” at
the end of the OID to get the right instance. Table 13.4 has the poller items, notice the Name column is
the same as the Internal Name column in Table 13.3.
Poller Backend
10 Alteon RealServer Admin Alteon Admin Status View
15 Alteon RealServer Oper Alarm Verify Operational
20 Alteon RealServer SessionsTemporal Buffer
25 Alteon RealServer Octets Temporal Buffer
90 No Poller RRDTool AllDSs
Actions Click the Edit or Del link to edit or delete an existing condition.
Description Description of the condition, appears in drop box when setting UP a SLA. It is a good idea
to put the set-point value in the description. For example, “Packet Loss” is no good because there
is no set point, “Packet Loss ¿ 10%” is better.
Show Info A small message about what SLA condition has been violated.
Condition This is the condition that the SLA event triggers on, it can use mathematical symbols as well
as numbers and values.
74 CHAPTER 13. EXPANDING JFFNMS
The three Show parameters are used to create the event. For example, if Show Info is “IN ¿ 90%”,
Show Expression is “(< in > /1024)” and Show Unit is “kbps” and assuming the value for in is 1024000
and the SLA triggers, the resulting message will look like “IN ¿ 90%: 1000 kbps”.
Action By clicking on the Edit or Del buttons you can edit or delete the SLA group. Clicking on the
View button will show the conditions within a group, see section 13.12.4 SLAs -SLA Condition
Relation for details of that table.
Description Description of SLA, used for drop down boxes in interface tables. Usually describes what
sort of customer or use the SLA is for.
Interface Type The type of interface the SLA applies for. In the interface table only the SLAs that match
the interface type will be shown.
Event Type The event type, taken from the Event Types( section 8.2 ) Event Types area for a list. Either
use the default SLA or the one you created in previous section.
Alarm State What level alarm the event should be, comes from the Alarm States(see Section 8.4) for a
list of states.
Event Text A string that is prepended to the event message. The SLA condition message follows this.
Threshold This value is used in Reports to discard measures above that percent of utilization. This is
useful to not count high packet loss measures on a saturated link for reports.
SLA The group name of this SLA. It is unlikely you will ever need to change this here.
Position The position is used to work out the order of evaluation for the RRD Analyzer.
Condition This is the condition used. It comes from the description column of the SLA Condition
Definition table.
Show Check this button if you want this SLA Condition to appear in the event if it fires.
13.13. HOST CONFIG COMMANDS 75
Position Condition
10 Input Error Rate > 10%
20 Output Traffic < 95%
30 Input Traffic < 95%
40 RoundTrip Time > 700ms
50 Packet Loss > 10%
60 Drops > 1%
70 OR
72 OR
73 AND
74 AND
75 OR
The logic used for the SLA Grouping is RPN. The group is evaluated in order of the Position column
and each item is placed onto the stack. If the item is an operator then some items may be removed from
the stack and replaced with the result. The only operators allowed are AND and OR.
For example, the “Customer Satellite Link” has the following logic Alarm if (((Drops > 1% ) OR
(Packet Loss > 10% ) OR (RTT > 700ms )) AND (Input Traffic < 95% ) AND (Output Traffic < 95%
)) OR (Input Error Rate > 10% ). In other words alarm if both input and output traffic are below 95%
at the same time there are large drops, packet loss or RTT. Alternatively alarm if the input error rate is
more than 10% .
The result would be like table 13.6. The lines are evaluated from the lowest ID to the highest. When
the SLA parser finds a Boolean Operator, it takes the last 2 values from the stack and apply the function,
the result is put back on the top of the stack.
All Individual Conditions return only TRUE or FALSE. (if their conditions are met or not)
The previous chapter described how to expand JFFNMS in some detail, but often it helps to have a
concrete example of what you are trying to do for illustration.
This chapter will guide you, step by step, through all the things needed to get a simple poller going.
Use this as a guide or a template for your own pollers.
We can see that the host responds with a value, and there have been 1397 incoming ICMP messages
for this host since the SNMP daemon was last started.
79
80 CHAPTER 14. ICMP INTERFACE EXAMPLE
4. Once you have typed in the right values, click the Save button on the left side of the row.
Remember what you have put into the Name column as that is used elsewhere in the setup. The De-
scription is just information for you so you know what the poller does.
1. Bring up the Poller Groups table by selecting Administration then the menu item Polling & Dis-
covery ⇒Poller Groups.
2. Click the Add button on the top of the table, a new poller item row is shown
3. Type a name, such as “ICMP InMsgs Counter” for the Group. The Interface Type will have to stay
as “No Interface Type” for now.
4. Click the Save button, which will take you back to the Poller Groups table.
5. Find your newly created group and click the “View” button. There will now be a split screen with
the groups up the top and an empty list of items down below.
6. At the top of the Pollers/Backend relation table (at the bottom pane) click the Add button.
• Position : 10
• Poller : The Name of the Poller Item you just created, we called ours “ICMP Incoming Msgs”
• Backend : RRD Individual Vale
8. Click the Save button and your poller group should have 1 row
1. Bring up the Interface Types table by selecting Administration menu item Internal Configuration
⇒Polling & Discovery ⇒Interface Types.
3. in the new dialog, type the following values. Anything not listed below just leave as the default.
14.6. ADDING INTERFACE TYPE FIELDS 81
1. Find the new Interface Type you just created in the previous step, click the Fields link to bring up
a new table below your Interface Types table. As it is a new Interface Type, there are no fields.
2. On the Interface Type Fields (the lower table) click Add
3. A new field row appears, enter the following parameters:
• Description : Index
• Internal Name : index
• Field Type : Index
4. Click Save to save the index row.
5. Next, to add the RRD file definition, again on the Interface Type Fields (the lower table) click Add
6. Another new row appears, enter the following parameters:
• Description : ICMP In Messages
• Internal Name : This must match the “Name” column for your Poller Item you created, it is
how JFFNMS knows to link the value found by the poller to the RRD file. In our case it is
icmp inmsgs
• Position : 20
• Field Type : RRDToolDS
7. You need to save this row before continuing. JFFNMS needs to know this row is a RRDToolDS
type before those RRD parameters appear, click Save.
8. Click Edit on the row for the RRDToolDS field, the Default Value column now has the RRD pa-
rameters.
82 CHAPTER 14. ICMP INTERFACE EXAMPLE
9. As what we are measuring is a counter, the only parameter to set is Max, so set it to some large
number, like 100000. You must have a value for Max.
10. Click Save.
Take note of the ID of the host. It is the number in bold immediately to the right of the white/blue
arrow. We will need this host ID in the next stage.
Click the checkbox on the left side of your interface, then click the button marked “Add Marked
Interfaces” right down the bottom of the interface table. This will change the windows to bring up an
Interface edit window. The interface has an ID, make note of that too. This interface ID is different to
the host ID.
The poller is working nicely, the rrd backend is sending the value 402 into the RRD file labelled
icmp inmsgs.
$opts_DEF = rrdtool_get_def($data,array("icmp_inmsgs"));
$opts_GRAPH = array(
"AREA:icmp_inmsgs#00CC00:’ICMP Messages ’",
"GPRINT:icmp_inmsgs:AVERAGE:’Average\:%4.0lf %sEps’",
"GPRINT:icmp_inmsgs:LAST:’Last\:%4.0lf %sEps\\n’");
The function name has to be whatever you call the filename with graph at the front of it. This
filename (without the .inc.php) is used in the GUI to create a new graph type.
• graph1 : icmp inmsgs (This is from the filename of the graph plugin)
• Width 1 : 500
• Width 2 : 150
As long as you have already checked the “Have Graph” box in the Interface Types table, you should
be able to see this graph in the Performance windows.
Chapter 15
JFFNMS is able to work with other programs to bring in different status information. This chapter
describes the various types of external programs and how to get them working with JFFNMS.
This tells snmptrapd to run that trap receiver program every time it gets a trap. See snmptrapd.conf(5)
manual page for details about what this does.
15.2 Syslog
There are two ways of working with syslog. The original way was to use a syslog program called
msyslog which is shipped from the same site as JFFNMS. The second is to use syslog-ng and make a
simple script to input the data.
Then you have to modify you syslog start script (/etc/init.d/syslog) to use the new server, and new
configuration, examples are provided in the docs/unix folder.
You need to start msyslog as something like:
You also need to configure your routers to send syslog messages to an specific facility (again exam-
ples are provided).
85
86 CHAPTER 15. WORKING WITH EXTERNAL PROGRAMS
destination d_jffnms {
pipe("/var/run/syslogmysql.pipe"
template("INSERT INTO syslog (date, date_logged, host, message) VALUES (’$YEAR-$MONTH-
};
Next you need to make the script, it essentially keeps the mysql client running. An example script
is:
#!/bin/sh
MYPIPE="/var/run/syslogmysql.pipe"
if [ ! -e $MYPIPE ] ; then
mkfifo $MYPIPE
fi
while [ -e $MYPIPE ] ; do
mysql -u jffnms --password=jffnms jffnms < $MYPIPE
done
Then you just need to run it. Once you checked it actually works, you can get it running from init,
by putting something like the following into /etc/inittab
N1:23:/usr/local/sbin/mysqlpipe.sh
15.3 Smokeping
Smokeping is a great program for measuring round trip times (RTT) and packet loss to remote desti-
nations. It not only prints these two figures but the distribution of the RTT so you can see if there is
variance in the ping times. Integration has been available since JFFNMS version 0.7.0. The best way
to use it is to create a new host specially for Smokeping with no IP address. For Smokeping to work,
JFFNMS needs to know the top of the data directory (where the RRDs are found). You tell JFFNMS by
setting the SNMP read-only community to the value of the top directory.
If you don’t know what your data directory is, look in the Smokeping configuration file and find the
line beginning with datadir. Once you have set the directory, you should see the Smokeping interfaces
when you use the “Get Interfaces” command from the host table.
To alarm a Smokeping interface, such as letting you know if the RTT or packet loss is too high, you
would use a SLA just like checking for any other interface parameter. Just like a normal interface, the
performance and reporting features are available.
Chapter 16
Interface Types
The various interface types in JFFNMS determine what sort of things can be monitored, graphed and
alarmed. A particular device, such as a Cisco router, consists of many interface types. Some of these
interface types will be specific for that class of equipment, such as Cisco CPU Load, while there could
also be generic interface types, such as a physical interface.
This chapter describes what interface types JFFNMS has, what JFFNMS can do with them and what
you will be able to see. Armed with that knowledge you will know how useful JFFNMS is for monitor-
ing a particular sort of equipment.
16.1.1 Discovery
Apache status is found by connecting to the HTTP port (TCP port 80) and successfully geting the URL
“/server-status?auto”.
• CPU Load
• Uptime of server
16.1.3 Graphs
The graphs get their data directly from the Apache status poller. Some values are combined into a single
graph to aid in comparison.
87
88 CHAPTER 16. INTERFACE TYPES
Graph Description
Hits Througput of the webserver in accesses per second
KBytes Throughput of the webserver in Bytes per second
Apache CPU LoadThe load that the Apache processes place on CPU
Bytes Per Request Bytes per Request. The average size of the web accesses
Workers A graph showing the red busy workers and green idle workers
16.1.4 Caveats
The target Apache webserver needs to be correctly setup to first enable the status module and then to
allow access from the JFFNMS server.
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from 192.168.1.10
</Location>
ExtendedStatus On
The Location clause can either go in the main section of the configuration file or into a virtual host.
The ExtendedStatus line needs to go into the main section.
16.2.1 Discovery
JFFNMS discovers BGP peers by determining if the BGP peer OIDs are valid. If they are each entry in
the BGP Peer table is a new interface.
16.2.3 Graphs
There is only one graph for BGP Interfaces. This graph shows the number of Inbound (peer to your
router) or outbound updates per 5 minutes. A large and sustained level of updates may mean route
flapping is occuring. Be careful if you have a large sustained level of outbound route updates because
you may be dampened.
16.3. CISCO SA AGENT 89
16.2.4 Caveats
None.
16.3.1 Discovery
Once a device that is capable of SAA is configured to start collecting information a new SNMP table is
created. The JFFNMS discovery engine, if it finds this table populated, will display new SAA interfaces.
16.3.3 Graphs
Interfaces of this type have 3 graphs. Round Trip Latency, Forward and Backward Jitter, and Forward
and Backward Packet loss (as a percentage).
16.3.4 Caveats
While there are many types of SAA probes, the only ones that are correctly detected and polled are the
jitter probes. Any other type of probe will be detected but will probably display graphs with 0 all the
time for all attributes.
There are many parameters that can go into the router configuration and you should check with
Cisco documentation about how to configure the router correctly so the probes do not cause any undue
performance hits. However a basic configuration, assuming the remote end has IP address 192.168.100.1,
would look like:
rtr 1
type jitter dest-ipaddr 192.168.100.1 dest-port 16384
rtr schedule 1 start-time now
16.4.1 Discovery
Discovery of an IIS server happens when the plugin is able to SNMP poll a certain OID that sits under
the Microsoft MIB. If the SNMP get was successful an IIS Webserver interface is created.
16.4.3 Graphs
There are 4 graphs for an IIS Webserver interface. One each showing the values for bytes received, CGI
requests and files sent. The number of GETs and POSTs are combined on one graph with a green area
for POSTs and then a blue area on top for GETs.
90 CHAPTER 16. INTERFACE TYPES
16.4.4 Caveats
Unline the Apache module, this one is dependent on SNMP setup correctly on both JFFNMS and the
target servers, as well as a path between them. Devices such as firewalls may allow HTTP traffic but
drop SNMP.
16.5.1 Discovery
SNMP is used for the discovery. Presence of the specific private OID is enough for the interface to be
found. The parameters tell which OID to look for to find the CPU.
16.5.3 Graphs
The poller collects information on the following: Average CPU Utilization, Number of Processes, Num-
ber of Users, Number of Active Opens, Number of Passive Opens, Number of Established connections.
The TCP information (active and passive opens, established connections) are graphed together on
the TCP Connection Status Graph. Likewise the number of users and processes are on the Process-
es/Users graph. Only CPU utilization gets its own graph.
16.5.4 Caveats
Currently the poller assumes there is a single CPU.
16.6.1 Discovery
The Auto-discovery parameters determine the range of TCP ports to probe. This range is then con-
nected by the nmap program. Any open ports are then created into interfaces.
16.6.3 Graphs
Response time is collected for all interfaces. If there is SNMP, the number of established connections is
also collected and graphed. That feature requires access to the tcpConnEntry table.
16.7. STORAGE 91
16.6.4 Caveats
The text sent needs to be a URL starting with http, https, ftp or ftps and the check is a simple needle in
haystack non-regular expression check.
16.7 Storage
The Storage interface is used to collect information about disks. It is for hosts that are running the
UCD/NET snmp daemon.
16.7.1 Discovery
Discovery is done by polling the specific UCD-SNMP OID. The number of blocks on the device, total
and used, are collected. In addition, the block size (to convert blocks to bytes) is also found.
16.7.3 Graphs
Values for Total and Used Blocks plus block size are regularly collected. The graph shows Total and
Used values in Bytes.
16.7.4 Caveats
16.8.1 Discovery
Interfaces of this type are discovered by polling the system OID and matching it to a list of known host
OIDs.
16.8.3 Graphs
The pollers collect information about the CPU, Swap, Memory and Load. The graphs are the same as
in the UCD Host interface type.
16.8.4 Caveats
It is assumed there is only one CPU.
16.9 Reachability
Reachability Interface types are ones that are used to ping remote hosts. The pings originate from the
server running the JFFNMS pollers so there needs to be an IP path from the polling server to the remote
location.
92 CHAPTER 16. INTERFACE TYPES
16.9.1 Discovery
If JFFNMS has been setup with the fping binary and it can execute it then any host with an IP address
has a Reachability interface.
16.9.3 Graphs
For each reachability interface JFFNMS can show graphs of the RTT and packet loss.
16.9.4 Caveats
16.10.1 Discovery
JFFNMS scans the ifTable SNMP interface table to discover Physical Interfaces.
Some interfaces, such as ATM aal5, ISL and 802.1q trunks have their descriptions slightly modified
to remove the identifier.
16.10.3 Graphs
16.10.4 Caveats
Problems are likely to occur if the description (ifDescr OID) is the same for different interfaces.
16.11 blah
16.11.1 Discovery
16.11.2 Status Polling
16.11.3 Graphs
16.11.4 Caveats
Chapter 17
Satellites
You can increase the capacity or the reliability of JFFNMS by using satellites. Satellites are other JFFNMS
installations that can either have a sibling or master/slave relationship.
By default, JFFNMS runs in Master mode with no satellite enabled. This means that it will not query
remote systems for interface status. At the same time it will not allow itself to be queried for status
FIXME - more stuff about what is passed to whom.
• Master
• Master Backup
• Satellite
93
94 CHAPTER 17. SATELLITES
Chapter 18
Error Messages
Quite often on the email lists users are getting the same error messages. The solutions are usually quite
simple but can the messages can initially be baffling. This chapter is here to list the more common
problems and their solutions.
18.1.1 Poller
The most common component to run on the command line is the poller. This is because most problems
stem from something not updating, such as a RRD file filled with NaN or the status of an interface not
changing. The poller command is run with the options:
Listing 2 PHP poller.php host id interface id sat id poller pos interface type
The IDs are not things like IP addresses, but the internal number that JFFNMS assigns. You can see
the ID form each interface and host by viewing the Host Table( section 6.2 ) or Interface Table( section 6.3
) and looking in the first column after the actions.
Any parameter that is 0 or is not specified means all of that particular type of things. For example, if
you want to poll all interfaces for a host, you would just specify that host’s id only and leave the other
fields blank. To poll host that has ID 42 but only its TCP ports (interface type 2), the command line
would be:
php poller.php 42 0 0 2
Each line starts with the local time. The first line for each host tells you what is the host ID and how
many interfaces there are. In the example we are polling host id 2 “H 2” and there are 43 interfaces.
A poller group is a series of poller item → backend pairs that are arranged in priority. Each pair is
displayed. The second line shows the following information.
95
96 CHAPTER 18. ERROR MESSAGES
• The polling is for host id 2 “H 2”, interface id 4 “I 4” and the poller priority is 10 “P 10”.
• the poller name is storage block size, this could be the RRD name too
• the poller parameters are cut short in the middle, but they have “.1.3..4.2”
• it took 19.17 and 0.16 microseconds to run the poller and backend, respectively.
The third line in the example, after the break, shows a typical response for a poller/backend pair for
putting the data into the RRD files. The first fields are like for any poller line. The important thing to
notice is that each field has a value and that the value makes sense for whatever you are counting.
Also notice that the storage block size value is the same value as was given in the snmp counter
poller. JFFNMS poller groups work by the poller item that fetches the value putting it into the buffer,
and then the RRD backend yanking the value out to put into the RRD file.
Notice the rrd has the asterix (or star) in the brackets. This means we have used the RRDTool All DS
backend. A common mistake is the use the RRD Individual Value poller here. That is only good if you
are directly taking a poller value and putting into a RRD file.
18.1.2 Consolidator
The consolidator takes one set of information and transforms it into another. Examples include events
to alarms and syslog messages to events. The consolidator can run with the following parameters:
The times parameter specifies the number of times the consolidators are run, with the default being
3 times to cover any things that need to be consolidated a few times.
Host ID : The numeric ID of the host you want to run discovery on.
Interface Type : ID for the Interface type, use 0 if you want to discover all types of interfaces.
Log Events : By default if the poller finds a new interface it will generate an event. Putting a 0 for the
loge vents parameter will suppress this event generation.
Now, let’s say you have created a new interface type and it has been given the ID of 10001. You have
already put your target host in JFFNMS which said it was host number 42. To check your discovery
plugin works, with no alarms raised for finding interfaces, run the command:
A common problem with this sort of testing is to test a host where you have autodiscovery turned
off. You don’t get very much useful information.
18.1. RUNNING THE COMPONENTS ON THE COMMAND LINE 97
There is nothing at all going on here, go back to the Hosts table in the GUI and enable autodiscovery.
You should then get some more information, like the following:
It’s found a new interface of type 10001, but nothing was done. Most likely the autodiscovery type
is notify or at least not automagic. The important thing is it has found your new interface type if you
get these messages.
Each line begins with the server time and the interface number. In this example, we have started the
analizer just after 8pm and it is showing the SLA applied to interface 90 (I90).
The first line is just a separator, so you know this group of evaluations is for this interface only. Line
two is displaying the time range (from 19:40:00 to 20:05:00) that this analisis will be for and that there
are 5 matching measurements. As each poll is done 5 minutes apart and the analysis is for 30 minutes,
it should always be 5.
Line 3 shows all the RRD values we have for this interface with the actual average value in brackets.
These are the measurements that we will be using. Line 4 is another separator with hyphens, and so it
is onto the RRD evaluation.
Before we get to line 5, it will make a lot more sense if we look at the actual SLA group we have
applied to Interface 90.
Interface 90 is a “Linux System Info” interface type. The SLA is the “Linux/Unix CPU” SLA. It’s
definition is in table 18.1
A simple enough definition. It triggers if the Load Average is above 5 or the CPU Utilization is about
80% (or both).
Now, re-list each sla line:
98 CHAPTER 18. ERROR MESSAGES
PositionCondition
10 Load Average > 5
20 CPU Utilization > 80%
30 OR
Almost always this is due to FC4’s botched implementation of selinux and you either need to fix
it (if you understand how) or disable it. For more information about Fedora and selinux, visit Fedora
Core 3 SELinux FAQ (http://fedora.redhat.com/docs/selinux-faq-fc3/) .
PHP is used by JFFNMS in both “Apache module” and “cgi” modes. Generally speaking if you are
trying to do something via a web page, it is running as a Apache module and everything else is via cgi.
The way that PHP is used changes the configuration file location. The following table shows the
locations of the main PHP configuration file, php.ini for the various types of systems:
System CGI directory Apache directory
Debian /etc/php/cgi/ /etc/php/apache/
2. Apache does not know it is supposed to use the PHP handler for those files
3. PHP ini setting shorto pent ag not set, see PHP core php.ini Directives .
extension=mysql.so
• Correct SNMP Write Community - JFFNMS needs to send some SNMP sets to tell the device to
write the file. If the community is missing or incorrect then the device will ignore the request.
18.6. PROBLEMS WITH CONSOLIDATOR 101
• Correct Config Transfer Mode - Different Cisco devices need different transfer mode (which means
the SNMP OID set that is used). See next section “No such variable errors” for more information.
• Correct TFTP Server IP - The host needs to have the IP address to send the configuration file. This
is almost always the IP address that the JFFNMS program sits on.
• TFTPd running - For TFTP to work, there has to be a server running on the JFFNMS host.
• TFTP server reachable - The device needs to be able to get back to the TFTP server. Firewalls need
to permit TFTP (UDP port 69) from the device to the server.
• TFTP directory writable - The directory that the configuration files need to be written to needs to
be writable by whatever user id you run the cron job as. Most likely it is either www-data, http or
jffnms.
• Cron job enabled - Make sure the cron configuration runs the tftp get host config script at some
regular intervals.
You can manually run the TFTP configuration collector, but make sure you do it as the right user id,
by running php4 -q tftp get host config.php . You need to be in the engine directory and the
PHP binary may be called php and not php4.
• The user that the trigger is applied to has no email address, check the user profiles.
• The PHP mail function is not available in PHP, due to how PHP was compilied
The important thing is the error message “‘Query Failed . . . Duplicate entry (some number) for key
1. This means you are trying to add a new line to the database and the value for the primary key is
already in there. The problem is that you are not specifying the primary key column (”id“), so how can
you be adding a duplicate?
The underlying problem is that the mysql table is corrupt and has forgotten what the next id number
should be. It’s gotten terribly confused and has one part of thinking the maximum value for id is
2581292 but another part thinking it is some other, higher number.
The solution is simple, login to mysql and repair the table:
Then re-run consolidator again and wait for the rush of new events. I have never heard of this
problem with PostgreSQL, if you do see it and are using PostgreSQL please let us know.
In this case there is a missing / (var instead of /var) that is causing the problem. To fix this edit the
config.ini either directly or via the System Setup menu.
No such file or directory means either the tempengine directory doesn’t exist or the file could not be
created.
18.7.3 Apache Error Log shows .dat files have permission denied
A related error message in the apache error logs is
ERROR: Opening ’/var/lib/jffnms/tempengine/3f6e92a0bf810.dat’ for write:
Permission denied
This means the user the web server is running under is unable to write files to that directory. Make sure
that whatever user or group the webserver is running as is able to write files into that directory.
$ ldd /usr/bin/rrdtool
librrd.so.0 => /usr/lib/librrd.so.0 (0x000002000002a000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x000002000005c000)
libgd-gif.so.1 => /usr/lib/libgd-gif.so.1 (0x00000200000ae000)
libm.so.6.1 => /lib/libm.so.6.1 (0x00000200000f6000)
libc.so.6.1 => /lib/libc.so.6.1 (0x0000020000184000)
libpng12.so.0 => /usr/lib/libpng12.so.0 (0x000002000031a000)
libz.so.1 => /usr/lib/libz.so.1 (0x000002000035a000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x0000020000000000)
libpng is linked twice in this case, and there are two different versions, namely libpng.so.2 and
libpng12.so.0. A setup such as this is almost guaranteed to give some sort of problems.
they were. This will occur around the 120-150Mbps mark where it will suddenly show traffic rates
in the small 10s of Mbps. This problem is caused by the SNMP counters wrapping around in the 5
minute polling interval ( 65535 ∗ 5 ∗ 60 = 19M Bps = 152M bps ). There is no simple solution to this
problem. Changing the polling rate, and associated RRD definitions to reflect the new rate, will fix it.
Later versions of JFFNMS will use the 64 bit counters to get around this problem, until 10,000 GigE
comes along.
Chapter 19
- there is some correlation, same events with all fields equal right after each other are joined.
105
106 CHAPTER 19. RANDOM STUFF, TO GO SOMEWHERE
Appendix
Chapter 20
Tables of values
107
108 CHAPTER 20. TABLES OF VALUES
This is free documentation; you may redistribute it and/or modify it under the terms of the GNU
General Public License in chapter 22 , version 2, as published by the Free Software Foundation; eiher
version 2 of the License, or (at your option) any later version.
This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the GNU General Public License for more details.
The copyright holders regard the LATEX form of this work as the Source Code of this Work for the
purposes of the GNU General Public License.
109
110 CHAPTER 21. ABOUT THIS DOCUMENT
Chapter 22
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it
is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to share and change it. By
contrast, the GNU General Public License is intended to guarantee your freedom to share and change
free software—to make sure the software is free for all its users. This General Public License applies to
most of the Free Software Foundation’s software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by the GNU Library General Public
License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses
are designed to make sure that you have the freedom to distribute copies of free software (and charge
for this service if you wish), that you receive source code or can get it if you want it, that you can change
the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or
to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give
the recipients all the rights that you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which
gives you legal permission to copy, distribute and/or modify the software.
Also, for each author’s protection and ours, we want to make certain that everyone understands that
there is no warranty for this free software. If the software is modified by someone else and passed on,
we want its recipients to know that what they have is not the original, so that any problems introduced
by others will not reflect on the original authors’ reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger
that redistributors of a free program will individually obtain patent licenses, in effect making the pro-
gram proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone’s
free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
111
112 CHAPTER 22. THE GNU GENERAL PUBLIC LICENSE
means either the Program or any derivative work under copyright law: that is to say, a work
containing the Program or a portion of it, either verbatim or with modifications and/or trans-
lated into another language. (Hereinafter, translation is included without limitation in the term
“modification”.) Each licensee is addressed as “you”.
Activities other than copying, distribution and modification are not covered by this License; they
are outside its scope. The act of running the Program is not restricted, and the output from the
Program is covered only if its contents constitute a work based on the Program (independent of
having been made by running the Program). Whether that is true depends on what the Program
does.
1. You may copy and distribute verbatim copies of the Program’s source code as you receive it,
in any medium, provided that you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to
this License and to the absence of any warranty; and give any other recipients of the Program a
copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer
warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work
based on the Program, and copy and distribute such modifications or work under the terms of
Section 1 above, provided that you also meet all of these conditions:
(a) You must cause the modified files to carry prominent notices stating that you changed the
files and the date of any change.
(b) You must cause any work that you distribute or publish, that in whole or in part contains or
is derived from the Program or any part thereof, to be licensed as a whole at no charge to all
third parties under the terms of this License.
(c) If the modified program normally reads commands interactively when run, you must cause
it, when started running for such interactive use in the most ordinary way, to print or dis-
play an announcement including an appropriate copyright notice and a notice that there is
no warranty (or else, saying that you provide a warranty) and that users may redistribute
the program under these conditions, and telling the user how to view a copy of this License.
(Exception: if the Program itself is interactive but does not normally print such an announce-
ment, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work
are not derived from the Program, and can be reasonably considered independent and separate
works in themselves, then this License, and its terms, do not apply to those sections when you
distribute them as separate works. But when you distribute the same sections as part of a whole
which is a work based on the Program, the distribution of the whole must be on the terms of this
License, whose permissions for other licensees extend to the entire whole, and thus to each and
every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written
entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or
with a work based on the Program) on a volume of a storage or distribution medium does not
bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code
or executable form under the terms of Sections 1 and 2 above provided that you also do one of the
following:
(a) Accompany it with the complete corresponding machine-readable source code, which must
be distributed under the terms of Sections 1 and 2 above on a medium customarily used for
software interchange; or,
113
(b) Accompany it with a written offer, valid for at least three years, to give any third party, for
a charge no more than your cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be distributed under the terms
of Sections 1 and 2 above on a medium customarily used for software interchange; or,
(c) Accompany it with the information you received as to the offer to distribute corresponding
source code. (This alternative is allowed only for noncommercial distribution and only if
you received the program in object code or executable form with such an offer, in accord
with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to
it. For an executable work, complete source code means all the source code for all modules it
contains, plus any associated interface definition files, plus the scripts used to control compilation
and installation of the executable. However, as a special exception, the source code distributed
need not include anything that is normally distributed (in either source or binary form) with the
major components (compiler, kernel, and so on) of the operating system on which the executable
runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated
place, then offering equivalent access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not compelled to copy the source
along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided
under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program
is void, and will automatically terminate your rights under this License. However, parties who
have received copies, or rights, from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it. However, nothing else
grants you permission to modify or distribute the Program or its derivative works. These actions
are prohibited by law if you do not accept this License. Therefore, by modifying or distributing
the Program (or any work based on the Program), you indicate your acceptance of this License
to do so, and all its terms and conditions for copying, distributing or modifying the Program or
works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient auto-
matically receives a license from the original licensor to copy, distribute or modify the Program
subject to these terms and conditions. You may not impose any further restrictions on the recip-
ients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by
third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other
reason (not limited to patent issues), conditions are imposed on you (whether by court order,
agreement or otherwise) that contradict the conditions of this License, they do not excuse you
from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your
obligations under this License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent license would not permit royalty-
free redistribution of the Program by all those who receive copies directly or indirectly through
you, then the only way you could satisfy both it and this License would be to refrain entirely from
distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance,
the balance of the section is intended to apply and the section as a whole is intended to apply in
other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right
claims or to contest validity of any such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is implemented by public license prac-
tices. Many people have made generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that system; it is up to the author/-
donor to decide if he or she is willing to distribute software through any other system and a
licensee cannot impose that choice.
114 CHAPTER 22. THE GNU GENERAL PUBLIC LICENSE
This section is intended to make thoroughly clear what is believed to be a consequence of the rest
of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents
or by copyrighted interfaces, the original copyright holder who places the Program under this
License may add an explicit geographical distribution limitation excluding those countries, so
that distribution is permitted only in or among countries not thus excluded. In such case, this
License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public
License from time to time. Such new versions will be similar in spirit to the present version, but
may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number
of this License which applies to it and “any later version”, you have the option of following the
terms and conditions either of that version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of this License, you may choose
any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution con-
ditions are different, write to the author to ask for permission. For software which is copyrighted
by the Free Software Foundation, write to the Free Software Foundation; we sometimes make ex-
ceptions for this. Our decision will be guided by the two goals of preserving the free status of all
derivatives of our free software and of promoting the sharing and reuse of software generally.
N O WARRANTY
11. B ECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE , THERE IS NO WARRANTY FOR THE PRO -
GRAM , TO THE EXTENT PERMITTED BY APPLICABLE LAW. E XCEPT WHEN OTHERWISE STATED
IN WRITING THE COPYRIGHT HOLDERS AND / OR OTHER PARTIES PROVIDE THE PROGRAM “ AS
IS ” WITHOUT WARRANTY OF ANY KIND , EITHER EXPRESSED OR IMPLIED , INCLUDING , BUT NOT
LIMITED TO , THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE . T HE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
YOU . S HOULD THE PROGRAM PROVE DEFECTIVE , YOU ASSUME THE COST OF ALL NECESSARY
SERVICING , REPAIR OR CORRECTION .
12. I N NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER , OR ANY OTHER PARTY WHO MAY MODIFY AND / OR REDISTRIBUTE THE PRO -
GRAM AS PERMITTED ABOVE , BE LIABLE TO YOU FOR DAMAGES , INCLUDING ANY GENERAL , SPE -
CIAL , INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO
USE THE PROGRAM ( INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS ), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES .
one line to give the program’s name and a brief idea of what it does.
Copyright (C) yyyy name of author
115
This program is free software; you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WAR-
RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this pro-
gram; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive
mode:
The hypothetical commands show w and show c should show the appropriate parts of the General
Public License. Of course, the commands you use may be called something other than show w and
show c; they could even be mouse-clicks or menu items—whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a
“copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:
This General Public License does not permit incorporating your program into proprietary programs.
If your program is a subroutine library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use the GNU Library General Public License
instead of this License.