![[charttype pie]](../../common/images/article218/t_art218_ftp1.png)
original in en Egon Willighagen
en to nl Hendrik-Jan Heins
Naast zijn werk voor het LinuxFocus-project, werkte Egon voor de Stichting Logreport tot de eerste november van dit jaar. Een deel van het doel van de stichting was het schrijven van software voor loganalyse met een GPL-licentie.
Dit artikel is het tweede in een serie over het gebruik van Lire om logbestanden van internet-serverapplicaties te analyseren. Dit artikel laat je zien hoe je de gegenereerde rapporten kunt aanpassen aan je eigen voorkeuren. Het eerste artikel uit deze serie legt uit hoe Lire moet worden geïnstalleerd.
![[illustration]](../../common/images/illustration213.png)
Dit artikel is gebaseerd op de laatste release van Lire, op dit moment is dat lire-20011017. Let erop dat de configuratie erg veranderd is sinds de vorige uitgave en dat in feite het eerste artikel uit de serie nu al verouderd is. Het idee van lr_config is echter niet veranderd.
Nieuwe features in deze release zijn, onder andere: twee nieuwe superservices (FTP en firewall), veel nieuwe rapporten (totaal > 68), nieuwe opmaakmethoden voor uitvoer (XHTML en RTF) en een heleboel bugfixes. Maar de belangrijkste verandering in deze uitgave zit onder de motorkap. Het rapport-generatieproces is compleet herschreven om gebruik te kunnen maken van XML technologie.
Dit artikel zal een van de XML-opmaakmethoden die nu in Lire gebruikt worden introduceren en uitleggen hoe deze gebruikt kunnen worden om rapporten te specificeren. Het zal geen handboek zijn over het maken van nieuwe rapporten maar het zal je laten zien hoe je de voorgedefiniëerde rapporten kunt veranderen op een laag niveau. Maar allereerst zal dit artikel uitleggen hoe je Lire kunt vertellen welke rapporten hij moet genereren en hoe de parameters voor deze rapporten moeten worden ingesteld.
Iedere superservice (bijvoorbeeld `email' is een superservice, de `postfix' en `sendmail' services behoren tot deze super service) heeft een aantal rapporten beschikbaar die extra informatie voor je uit de logs halen. De www superservice heeft bijvoorbeeld 31 rapporten. Niet alle rapporten zijn interresant voor iedereen; sommige zijn erg specifiek. Standaard worden de meeste van deze rapporten geselecteerd, maar het is handig om dit in te stellen naar je eigen wensen.
De rapporten die zullen worden gebruikt bij het genereren van een rapport worden ingesteld in het bestand <prefix>/etc/lire/<superservice>.cfg (aangenomen dat Lire geïnstalleerd is de directory <prefix>). Voor de FTP superservice bijvoorbeeld ziet het configuratiebestand er als volgt uit:
# Report configuration for the FTP super service
# Top X reports
top-remote-host hosts_to_show=10
#top-files files_to_show=10
top-files-in files_to_show=10
top-files-out files_to_show=10
top-users users_to_show=10
# By day reports
bytes-by-day
# Transfers by X reports
transfers-by-direction
transfers-by-type
De FTP-superservice heeft dus acht rapporten gedefiniëerd en alle behalve één zijn geselecteerd. De "top-files" wordt gedeselecteerd door gebruik te maken van het karakter "#". Het verwijderen van het karakter "#" zal het rapport opnieuw selecteren.
Let erop dat niet alle regels die beginnen met een "#" rapporten zijn. In dit configuratiebestand zijn de regels "Report configuration for the FTP super service", "Top X reports", "By day reports" en "Transfers by X reports" commentaar. Gelijkaardig commentaar kan je ook tegenkomen in de andere configuratiebestanden.
Ordenen is zeer eenvoudig. De volgorde waarin de rapportregels verschijnen in de configuratiebestanden is ook de volgorde waarin de rapporten zullen worden weergegeven in de uitvoer. Het herschikken van de regels in deze configuratiebestanden zal ze dus ook herordenen in de uitvoer. Bijvoorbeeld, in het bovenstaande voorbeeld zullen de 'transfers-by-type' als laatste worden weergegeven.
Veel rapporten kunnen gedeeltelijk worden aangepast aan de eigen wensen met de configuratiebestanden. Dit gaat zoals in het voorgaande deel is uitgelegd. Bijvoorbeeld deze DNS-superservice-configuratie:
# Rapport configuratie voor de DNS-superservice
# Top reports
top-requesting-hosts hosts_to_show=10
top-requesting-hosts-by-method hosts_to_show=10 method='recurs'
top-requesting-hosts-by-method hosts_to_show=10 method='nonrec'
top-requested-names names_to_show=10
top-requested-names-by-method names_to_show=10 method='recurs'
top-requested-names-by-method names_to_show=10 method='nonrec'
requesttype-distribution
requesttype-distribution-by-method method='recurs'
requesttype-distribution-by-method method='nonrec'
# By Day reports
requests-by-period period=1d
requests-by-period-by-method period=1d method='recurs'
requests-by-period-by-method period=1d method='nonrec'
# By Hour reports
requests-by-period period=1h
requests-by-period-by-method period=1h method='recurs'
requests-by-period-by-method period=1h method='nonrec'
Alle vijftien rapporten zijn geselecteerd, maar bovendien is het voor de rapporten met een top X output mogelijk het nummer X te definiëren. Met de bovenstaande configuratie geeft het rapport top-requesting-hosts een Top 10.
Deze rapporten worden gegenereerd uit slechts acht rapportspecificaties. Het gebruik van de parameters (period, method, hosts_to_show, en names_to_show) maakt dit mogelijk. Dit is een van de nieuwe krachtige eigenschappen van de nieuwe, op XML gebaseerde motor.
Belangrijk: alle instellingen van variabelen moeten op dezelfde regel worden geplaatst als de rapportnaam!
Een meer exotisch voorbeeld kan gegeven worden aan de hand van het WWW-superservice-configuratiebestand:
top-referers-by-page referer_to_show=5 page_to_show=10 referer_exclusion='^-$'
In dit voobeeld wordt een Perl reguliere expressie gebruikt als inhoud voor de referer_exclusion-variabele. Deze expressie komt overeen met alle referers "-". Zulke referers kunnen worden gevonden in het logbestand in gevallen waarbij bijvoorbeeld de URL van een web pagina is ingetikt door de gebruiker. (Wanneer gebruikers je pagina bezoeken door op een link in een pagina te klikken die doorverwijst naar je pagina, dan wordt de pagina waar de link vandaan komt gegeven in het refererveld.) Alle referers die hetzelfde zijn als "-" worden uit de analyse gehouden.
Deze nieuwe uitgave is het begin van een heel nieuwe tak van Lire. De rapportgeneratie en de specificatieprocessen zijn compleet herschreven om gebruik te kunnen maken van XML-technologie. Rapporten worden gespecificeerd in XML, maar de instelling van de variabelen werkt in gewoon ASCII-formaat. De vorige rapportspecificatie was een Perl-script dat zowel de opmaak van de invoer als die van de uitvoer moest kennen. Met de nieuwe XML-opmaak is de implementatie gescheiden van de specificatie en hoef je niet meer zowel de invoer- als de uitvoeropmaak te kennen maar alleen de gegevens die verwerkt kunnen worden.
Dus, als je rapporten op laag niveau aanpast, hoef je allen maar een beetje XML te kennen. Een voorbeeldrapport, genomen uit de <prefix>/share/lire/reports/firewall directory:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE lire:report-spec PUBLIC
"-//LogReport.ORG//DTD Lire Report Specification Markup Language V1.0//EN"
"http://www.logreport.org/LRSML/1.0/lrsml.dtd">
<lire:report-spec xmlns:lire="http://www.logreport.org/LRSML/"
superservice="firewall" id="bytesperfrom" charttype="bars">
<lire:title>Top Bytes per From-IP Report</lire:title>
<lire:description>
<para>
This report lists the IP addresses sending the highest data volume.
</para>
</lire:description>
<lire:param-spec>
<lire:param name="ips_to_show" type="int" default="10">
<lire:description>
<para>This parameter controls the number of sending IP adresses to
display in the report.
</para>
</lire:description>
</lire:param>
</lire:param-spec>
<lire:display-spec>
<lire:title>Volume per sending IP, Top $ips_to_show</lire:title>
</lire:display-spec>
<lire:report-calc-spec>
<lire:group sort="-rcvd_volume" limit="$ips_to_show">
<lire:field name="from_ip"/>
<lire:sum name="rcvd_volume" field="length"/>
</lire:group>
</lire:report-calc-spec>
</lire:report-spec>
Het eerste dat je zou moeten opvallen is dat vrijwel ieder XML-element in dit rapport begint met lire:. Dit wordt gebruikt om een naamruimte (namespace) toe te wijzen aan dat element. Ieder element met de lire-naamruimte is gedefiniëerd in XML DTD http://www.logreport.org/LRSML/1.0/lrsml.dtd (lege link!), die kan worden doorgespit op http://www.logreport.org/pub/docs/dtd/lrsml/.
Alle andere elementen zouden moeten toebehoren aan de DocBook XML 4.2 DTD. Zoals het element <para> op de tiende regel bijvoorbeeld.
Als je de titel die verschijnt in het rapport wilt wijzigen, dan moet je de <lire:title> inhoud in de <lire:display-spec> veranderen. Onthoud hierbij dat strings die starten met "$" Perlvariabelen zijn waar de naam correspondeert met een van de gespecificeerde parameters in de <lire:param-spec>-sectie.
Het lastige deel is dat je het juiste <lire:title> element moet nemen. Je moet het element nemen dat de inhoud is van de <lire:display-spec>-knoop. Dat element bevat de gegevens die verschijnen in het uitvoerrapport. Het eerste <lire:title>-element bevat de titel van het rapport die gebruikt wordt in de documentatie van de Lire-software.
Het volgende voorbeeld laat een fragment van de requests-by-result WWW-rapportspecificatie zien. Je kunt zien dat de <lire:display-spec> nu niet alleen een titel als uitvoer geeft, maar ook wat meer uitleg. Let er op dat alle inhoud in het <lire:description>-element geen gebruik maakt van de lire naamruimte, en dus DocBook-inhoud is.
<lire:display-spec>
<lire:title>Requests By HTTP Result</lire:title>
<lire:description>
<para>
The most common HTTP status codes are given below:
<variablelist>
<varlistentry>
<term>200</term>
<listitem>
<para>OK (The request has succeeded.)</para>
</listitem>
</varlistentry>
<!-- rest is cut out -->
</variablelist>
</para>
</lire:description>
</lire:display-spec>
Het rapport zal er ongeveer uitzien als (alleen het bovenste deel hier):
Requests By HTTP Result
The most common HTTP status codes are given below:
200 OK (The request has succeeded.)
201 Created (The request has been fulfilled and resulted in a new resource being created.)
206 Partial Content (The server has fulfilled the
De meeste rapporten bevatten afbeeldingen die afhankelijk zijn van de gegevens. Deze afbeeldingen worden gegenereerd met behulp van de gegevens en hun opmaak wordt bepaald door de rapportspecificatie. Neem bijvoorbeeld het volgende stuk uit het FTP transfers-by-type rapport.
Voor dit rapport worden de gegevens gevisualiseerd in een taartdiagram zoals te zien is aan het @charttype attribuut in de bovenstaande code. Het resultaat ziet er zo uit:
Door het diagramtype te veranderen in staaf zoals in 'charttype="bars"' verandert de uitvoer in:
![[charttype bars]](../../common/images/article218/t_art218_ftp2.png)
Let erop dat dit rapport een bug bevat. Het rapport gaat op het transfertype, niet over het bestandstype. Deze bug is al gemeld.
Meer specifieke informatie over de XML-taal die gebruikt is voor de rapportspecificatie kan worden gevonden op de LogReport web site. Je zult zien dat de taal vrij uitgebreid is, en voorlopig kan ik je aanraden om gebruik te maken van de rapportspecificatie die als gids bij de distributie wordt geleverd.
Elementen die niet besproken zijn in dit artikel maar die wel worden gebruikt in deze rapporten voor de specificatie van parameters zijn (<lire:param-spec>) en de berekening van de uitgedraaide gegevens (<lire:report-calc-spec>). Vooral de laatste heeft veel opties en maakt gebruik van bestaande kennis van het interne formaat (genaamd DLF) waarin de loggegevens worden opgeslagen. Dit zal worden besproken in een toekomstig artikel.
Dit artikel heeft de XML-gebaseerde rapport engine geïntroduceerd en uitgelegd hoe je de rapporten die je krijgt kan aanpassen. Meer informatie kan worden gevonden op de LogReport web site: http://www.logreport.org/.
Als je contact op wilt nemen met het team achter LogReport kun je IRC op gaan. De ontwikkelaars kunnen vaak worden gevonden op het #logreport kanaal op het OpenProjects.org IRC netwerk. Vragen, commentaar en ondersteuningsvragen zijn welkom. Als je liever gebruik maakt van e-mail kun je het team bereiken via de openbare mailinglijst questions@logreport.org.