Chapter 9. The Lire DLF Schema Markup Language

Table of Contents

The Lire DLF Schema Markup Language
The dlf-schema element
extended-schema element
derived-schema element
field element

The Lire DLF Schema Markup Language

The Lire DLD Schema Markup Language (LDSML) is used describe the fields used by DLF records of a specific schema like www, email or msgstore.

DLF schemas are defined in one XML document that should be installed in one of the directories that is included in the schema path (usually HOME/.lire/schemas and prefix/share/lire/schemas ). This document must conforms to the LDSML DTD which is described here. Elements of that DTD are defined in the namespace http://www.logreport.org/LDSML/ which will be usually mapped to the lire prefix (altough other prefixes may be used).

The latest version of that DTD is 1.1 and its public identifier is -//LogReport.ORG//DTD Lire DLF Schema Markup Language V1.1//EN™. Its canonical system identifier is http://www.logreport.org/LDSML/1.1/ldsml.dtd.


<!--                    Namespace prefix for validation using the
                        DTD                                        -->
<!ENTITY % LIRE.xmlns.pfx    "lire"                                  >
<!ENTITY % LIRE.pfx          "%LIRE.xmlns.pfx;:"                     >
<!ENTITY % LIRE.xmlns.attr.name "xmlns:%LIRE.xmlns.pfx;"             >
<!ENTITY % LIRE.xmlns.attr
  "%LIRE.xmlns.attr.name; CDATA #FIXED
                        'http://www.logreport.org/LDSML/'">

  

This DTD uses the common modules lire-types.mod which defines the data types recognized by Lire and lire-desc.mod which is used to include a subset of DocBook in description and text elements.

  

<!ENTITY % lire-types.mod PUBLIC
    "-//LogReport.ORG//ENTITIES Lire Data Types V1.0//EN"
    "lire-types.mod">
%lire-types.mod;

<!ENTITY % lire-desc.mod PUBLIC
    "-//LogReport.ORG//ELEMENTS Lire Description Elements V2.0//EN"
    "lire-desc.mod">
%lire-desc.mod;
   
  

The top-level element in XML documents describing a DLF schema will be either a dlf-schema, extented-schema or derived-schema depending on the schema's type. DLF schemas are used as base schema for one superservice. For example, the DLF schema of the www superservice is named www. An extended schema is used to define additional fields which values are to be computed by an analyser.

Extended schemas are named after the schema which they extend. For example, the www-attack extended schema adds an attack field which contains, if any, the “attack” that was attempted in that request.

Derived schemas are used by another type of analysers which defines an entirely different schema. Whereas in the extended schema the new fields will be added to all the DLF records of the base schema, the derived schema will create new DLF records based on the DLF records of the base schema. An example of this is the www-session schema which computes users' session information based on the web requests contained in the www schema. Like for the extended-schema case, derived schemas are named after the base schema from which they are derived.

The fields that makes each schema are defined using field elements.

  
<!-- Prefixed names declaration.                                   -->
<!ENTITY % LIRE.dlf-schema   "%LIRE.pfx;dlf-schema"                  >
<!ENTITY % LIRE.extended-schema "%LIRE.pfx;extended-schema"          >
<!ENTITY % LIRE.derived-schema  "%LIRE.pfx;derived-schema"           >
<!ENTITY % LIRE.field        "%LIRE.pfx;field"                       >
  

  

The dlf-schema element

The dlf-schema element is used to define the base schema of a superservice. It should contains optional title and description elements followed by field elements describing the schema structure.

The title is an optional text string that will be used to in the automatic documentation generation that can be extracted from the schema definition. The description element should describe what is represented by each DLF records (one web request, one email delivery, one firewall event, etc.)

dlf-schema's attributes

superservice

This required attribute contains the name of the superservice described by this schema. This will also be used as the base schema's identifier.

timestamp

This required attribute contains the name of the field which contains the official event's timestamp. This field will be used to sort the DLF records for timegroup and timeslot report operations.

  

<!ELEMENT %LIRE.dlf-schema;  ( (%LIRE.title;)?, (%LIRE.description;)?,
                               (%LIRE.field;)+ )                     >
<!ATTLIST %LIRE.dlf-schema;
             superservice    %superservice.type;           #REQUIRED
             timestamp       IDREF                         #REQUIRED 
             %LIRE.xmlns.attr;                                       >
    

   

extended-schema element

This is the root element of an extended DLF Schema. Extended-schema defines additional fields that will be added to the base schema. It contains an optional title, an optional description and one or more field specifications.

dlf-schema's attributes

id

This required attribute contains the identifier of that schema. This identifier should be composed of the superservice's name followed by an hypen (-) and then an word describing the extended schema.

base-schema

This required attribute contains the identifier of the schema that is extended.

required-fields

This optional attribute contains a space delimited list of field names that must be available in the base schema for the analyser to do its job. If any of the listed field is missing in the DLF, extended fields for the base schema cannot be computed.

module

This required attribute contains the name of the analyser that is used to compute the extended fields. This is a perl module that should be installed in perl's library path.

    

<!ELEMENT %LIRE.extended-schema; 
                             ( (%LIRE.title;)?, (%LIRE.description;)?,
                               (%LIRE.field;)+ )                     >
<!ATTLIST %LIRE.extended-schema;
             id              NMTOKEN                       #REQUIRED
             base-schema     NMTOKEN                       #REQUIRED
             module          NMTOKEN                       #REQUIRED 
             required-fields NMTOKENS                      #IMPLIED
             %LIRE.xmlns.attr;                                       >
    
   

derived-schema element

This is the root element of a derived DLF Schema. The difference between a normal schema and a derived schema is that the data is generated from another DLF instead of a log file.

derived-schema's attributes

id

This required attribute contains the identifier of that schema. This identifier should be composed of the superservice's name followed by an hypen (-) and then an word describing the derived schema.

base-schema

This required attribute contains the identifier of the schema from which this derived schema's data is derived.

required-fields

This optional attribute contains a space delimited list of field names that must be available in the base schema for the analyser to do its job. If any of the listed field is missing in the DLF, the derived records cannot be computed.

module

This required attribute contains the name of the analyser that is used to compute the derived records. This is a perl module that should be installed in perl's library path.

timestamp

This required attribute contains the name of the field which contains the official event's timestamp. This field will be used to sort the DLF records for timegroup and timeslot report operations.

   
<!ELEMENT %LIRE.derived-schema; 
                             ( (%LIRE.title;)?, (%LIRE.description;)?,
                               (%LIRE.field;)+ )                     >
<!ATTLIST %LIRE.derived-schema;
             id              NMTOKEN                       #REQUIRED
             base-schema     NMTOKEN                       #REQUIRED
             module          NMTOKEN                       #REQUIRED 
             required-fields NMTOKENS                      #IMPLIED
             timestamp       IDREF                         #REQUIRED 
             %LIRE.xmlns.attr;                                       >

   

field element

The field is used to describe the fields of the schema. Each field is specified by its name and type. The field element may contain an optional description element which gives more information on the data contained in the field. Description should be used to give better information to the DLF converter implementors on what should appears in that field.

field's attributes

name

This required attribute contains the name of the field.

type

This required attribute contains the the field's type.

default

Warning

This attribute is obsolete and will be removed in a future Lire release.

label

This optional attribute gives the label that should be used to display this field in reports. Defaults to the field's name when omitted.


<!ELEMENT %LIRE.field;       (%LIRE.description;)?                   >
<!ATTLIST %LIRE.field;
             name            ID                            #REQUIRED
             type            (%lire.types;)                #REQUIRED
             default         CDATA                         #IMPLIED
             label           CDATA                         #IMPLIED  >