Chapter 10. The Lire DLF Schema Markup Language
Prev | Part III. Developer's Reference | Next

## Chapter 10. The Lire DLF Schema Markup Language

## 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  >

Prev | Up | Next
Chapter 9. The Lire Report Configuration Markup Language | Home | Chapter 11. The Lire Report Specification Markup Language