Lire Developer's Manual

Joost van Baal

Egon L. Willighagen

Francis J. Lacoste

This manual 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 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.

You should have received a copy of the GNU General Public License along with this manual (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

Revision History
Revision 1.5 $Date: 2004/04/01 22:41:24 $
$Id: dev-manual.dbx,v 1.79 2004/04/01 22:41:24 wsourdeau Exp $

Table of Contents

Preface
What This Book Contains
How Is This Book Organized?
Conventions Used
If You Don't Find Something In This Manual
I. Lire Architecture
1. Architecture Overview
Lire's Design Patterns
Log File Normalisation
Log Analysis
Report Generation
Report Formatting and Other Post-Processing
Going Further
II. Using the Lire Framework
2. Writing a New DLF Converter
Prerequisites
The common_syslog Log Format
Creating the DLF Converter Skeleton
Adding a Constructor
The Meta-Data Methods
The DLF Converter Name
Providing Information To Users
Providing Information to the Framework
The Conversion Methods
Registering Your DLF Converter with the Lire Framework
DLF Converter API
3. Writing a DLF Schema
Designing the ftpproto schema
Creating The Schema File
Adding the Schema's Description
Defining the Schema's Fields
Installing The Schema
4. Writing a New Report
Filter Specification
III. Developer's Reference
5. Lire Data Types
Lire Textual Elements
Profiling Attribute
title element
DocBook Elements
description element
6. Common Textual Elements to All XML Formats
Lire Data Types Parameter Entities
Boolean Type
Integer Type
Number Type
String Type
Timestamp type
Time Type
Date Type
Duration Type
IP Type
Port Type
Hostname Type
URL Type
Email Type
Bytes Type
Filename Type
Field Type
Superservice Type
Chart Type
Related Types
7. The Lire Report Configuration Specification Markup Language
The Lire Report Configuration Specification Markup Language
config-spec element
summary element
Parameter Specifiations Elements
8. The Lire Report Configuration Markup Language
The Lire Report Configuration Markup Language
config element
global element
param element
9. The Lire DLF Schema Markup Language
The Lire DLF Schema Markup Language
The dlf-schema element
extended-schema element
derived-schema element
field element
10. The Lire Report Specification Markup Language
The Lire Report Specification Markup Language
report-spec element
global-filter-spec element
display-spec element
param-spec element
param element
Filter expression elements
Report Calculation Elements
11. The Lire Report Markup Language
The Report Markup Language
report element
Meta-information elements
Annotations Elements
section element
subreport element
missing-subreport element
table element
table-info element
group-info element
column-info element
group-summary element
group element
entry element
name element
value element
Charts-related elements
12. Schemas Reference
Schemas for the database Superservice
DLF Schema for Database service
Extended Schemas for the database Superservice
Schemas for the dialup Superservice
DLF Schema for Dialup service
Schemas for the dns Superservice
DLF Schema for DNS service
Schemas for the dnszone Superservice
DLF Schema for DNS Zone service
Schemas for the email Superservice
DLF Schema for Email service
Extended Schemas for the email Superservice
Schemas for the firewall Superservice
DLF Schema for Firewall service
Schemas for the ftp Superservice
DLF Schema for FTP service
Schemas for the msgstore Superservice
DLF Schema for Message Store service
Schemas for the print Superservice
DLF Schema for Print service
Extended Schemas for the print Superservice
Schemas for the proxy Superservice
DLF Schema for Proxy superservice
Schemas for the syslog Superservice
DLF Schema for Syslog superservice
Schemas for the www Superservice
DLF Schema for WWW service
Extended Schemas for the www Superservice
Derived Schemas for the www Superservice
IV. Lire Developers' Conventions
13. Contributing Code to Lire
14. Developers' Toolbox
Required Tools To Build From CVS
Accessing Lire's CVS
CVS primer
SourceForge
Mailing Lists
15. Coding Standards
Shell Coding Standards
Perl Coding Standards
16. Making Lire Test-infected
Unit Tests in Lire
PerlUnit
Writing Tests
Running Tests
Some Best Practices on Unit Testing
17. Commit Policy
CVS Branches
Hands-on example
Naming, what it looks like
Creating a Branch
Accessing a Branch
Merging Branches on the Trunk
18. Testing
19. Making a Release
Setting version in NEWS file, checking ChangeLog
Tagging the CVS
Building The "Standard" Tarball
Building The "Full" Tarball
Building The Debian Package
Building The RPM Package
Making sure the FreeBSD port gets updated
Uploading The Release
The LogReport Webserver
Advertising The Release
SourceForge
Freshmeat.net
20. Website Maintenance
Documentation on the LogReport Website
Publishing the DTD's
21. Writing Documentation
Plain Text
Perl's Plain Old Documentation: maintaining manpages
Docbook XML: Reference Books and Extensive User Manuals
UML Diagrams
UML Editing
Diagram Types
V. Implementation Details
22. Report Generation: AsciiDlf
23. Adding a New Superservice in Lire's Distribution
24. Issues with Report Merging
25. Overview of Lire scripts
26. Source Tree Layout
Glossary

List of Figures

1.1. Log Processing in the Lire's Framework
1.2. The Log Normalisation Process
1.3. The Log Analysis Process
1.4. Report Generation Process
1.5. XSLT Processing of the XML Report
1.6. Processing of the XML Report Using The APIs

List of Tables

10.1. weekly overview

List of Examples

10.1. timeslot with 1d unit
10.2. timeslot with 2m unit
3. DNS DLF Excerpts