Table of Contents
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
and
HOME
/.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).
prefix
/share/lire/schemas
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 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
This required attribute contains the name of the superservice described by this schema. This will also be used as the base schema's identifier.
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; >
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
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.
This required attribute contains the identifier of the schema that is extended.
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.
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; >
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
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.
This required attribute contains the identifier of the schema from which this derived schema's data is derived.
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.
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.
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; >
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
This required attribute contains the name of the field.
This required attribute contains the the field's type.
This attribute is obsolete and will be removed in a future Lire release.
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 >