
Frequently Asked Question About Lire

Joost van Baal

Egon L. Willighagen

Francis J. Lacoste

   Copyright  2001 Stichting LogReport Foundation

   This document 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 20020214 $Date: 2002/02/06 20:23:50 $
   $Id: faq.dbx,v 1.14 2002/02/06 20:23:50 vanbaal Exp $
     _________________________________________________________________

   1 Problems Installing Lire On Specific Platforms

        1.1 Installing Under Debian GNU/Linux

              1. What .deb packages are required by Lire?

        1.2 Installing Under Red Hat Linux

              1. What RPM packages should I install to run Lire? 

        1.3 Installing Under SuSE Linux

              1. What RPM packages should I install to run Lire? 
              2. I have installed all the requirements but I get the
                      following errors when trying to generate an HTML
                      report:
                      /usr/bin/jade:/home/lire/logreport/share/lire/sgml/
                      stylesheet/dsssl/\ html.dsl+:1:73:W: cannot
                      generate system identifier for public text\
                      "-//James Clark//DTD+DSSSL Style Sheet//EN What
                      does this means ? 

        1.4 Installing Under OpenBSD

              1. Which ports should I install to run Lire? 

        1.5 Installing Under Solaris

              1. Which packages should I install to run Lire? 
              2. Is it hard to install the needed libxslt?
              3. How do I install OpenJade?
              4. How do I install Jade? 
              5. While trying to generate an HTML report using
                      lr_log2report -o html, I get the error following
                      error all all lr_tag-20011013213208-983 lr_xml2html
                      err docbook.dsl \ file '' does not exist! all all
                      lr_tag-20011013213208-983 lr_xml2html err Please
                      install \ Norman Walsh's DocBook DSSSL Stylesheets.
                      all all lr_tag-20011013213208-983 lr_xml2html err
                      Consult the Lire \ User's Manual for more
                      informations. How do I fix this problem ? 

              6. I installed the necessary DocBook stuff, but generation
                      of HTML reports still fails with the message: bogus
                      message: cat: cannot open
                      /usr/home/flacoste/tmp/lr_xml2html.6050/\
                      lr_xml2html.html www combined
                      lr_tag-20011013215447-6006 lr_log2report err
                      lr_xml2html failed How do I solve this problem? 

        1.6 Installing Under MacOS X

              1. Can I run Lire under MacOSX? 

   2 Licensing

        1. I wanna contribute code, and would like it to get distributed
                as a part of Lire, what should I do, license-wise?

        2. Why is Lire licensed under the GPL?
        3. If I make a contribution to Lire do I have to put my code
                under the GPL? 

        4. We want to write a DLF converter for the users of our
                proprietary product, can we distribute it under the same
                proprietary terms as our other products? 

        5. Can I distribute my XML report specifications under other
                terms than the GPL? 

        6. I want to reuse your file formats (DLF format, XML report) in
                my project, but I want to release this project under a
                MIT X-like license, may I? 

1 Problems Installing Lire On Specific Platforms

   In this section, you will find answers to common installation problems
   on various platforms.

1.1 Installing Under Debian GNU/Linux

   1. What .deb packages are required by Lire?

   The Lire .deb has the proper Suggests and Depends tags that will give
   you the proper dependencies. But if you would like to install Lire
   from source, read on.

   To run a minimum Lire installation, you will need the following
   packages (those are from Woody):
     * libxml-parser-perl

   and its other dependencies.

   To run a Lire installation with all the output format supported, you
   will also need:
     * jade or openjade
     * docbook-xml
     * docbook-dsssl
     * docbook-xsl-stylesheets
     * xsltproc
     * jadetex
     * libgd-graph-perl

   and their other dependencies.

   If you want to run an online responder, you will also need the
   following packages in addition to your Mail Transport Agent (exim,
   sendmail, postfix or qmail):
     * mpack

1.2 Installing Under Red Hat Linux

   1. What RPM packages should I install to run Lire?

   To install a minimum Lire installation, you will need the following
   packages:
     * perl-XML-Parser

   along with its required dependencies.

   To run a Lire installation with all the output format supported, you
   will also need:
     * openjade
     * docbook-dtd412-xml
     * docbook-style-dsssl
     * docbook-style-xsl
     * libxslt
     * jadetex

   and their other dependencies.

   In order to generate charts, you will need to install the following
   perl modules from a CPAN mirror:
     * GD
     * GDGraph

   To compile those modules, in addition to the usual development
   packages, you will need:
     * gd
     * gd-devel

   In order to run an online responder, you will have to install Mpack
   from source. There doesn't seems to be any RPM package for Red Hat
   Linux. You can download Mpack from
   ftp://ftp.andrew.cmu.edu/pub/mpack/.

1.3 Installing Under SuSE Linux

   1. What RPM packages should I install to run Lire?

   To install a minimum Lire installation, you will need the following
   packages that are available from your SuSE Linux installation CD:
     * perl-XML-Parser

   along with its required dependencies.

   To run a Lire installation with all the output formats supported, you
   will also need the following packages (all included on the
   installation CD):
     * openjade or jade_dsl
     * docbook_4
     * docbook-dsssl-stylesheets
     * docbook-xsl-stylesheets
     * jadetex

   and their other dependencies.

   You will also need to install an RPM for libxslt and libxml2 that
   aren't packaged with SuSE Linux. You can install the ones distributed
   by the author of libxslt and available from ftp://xmlsoft.org/

   In order to generate charts, you will need to install the following
   perl module from a CPAN mirror:
     * GDGraph.

   Before installing that module, you will have to install the following
   packages from the SuSE Linux CD:
     * perl-GD
     * gd
     * gd-devel

   In order to run an online responder, you will have to install Mpack
   from source. There doesn't seems to be any RPM package for SuSE Linux.
   You can download Mpack from ftp://ftp.andrew.cmu.edu/pub/mpack/.

   2. I have installed all the requirements but I get the following
   errors when trying to generate an HTML report:
/usr/bin/jade:/home/lire/logreport/share/lire/sgml/stylesheet/dsssl/\
 html.dsl+:1:73:W: cannot generate system identifier for public text\
 "-//James Clark//DTD+DSSSL Style Sheet//EN


   What does this means ?

   The SGML environment isn't properly set when using openjade under SuSE
   Linux. You will have to set the SGML_CATALOG_FILES environment
   variable to the following:
$ export SGML_CATALOG_FILES="/usr/share/sgml/CATALOG.db41xml:\
>/usr/share/sgml/CATALOG.docbook-dsssl-stylesheets:\
>/usr/share/sgml/openjade/catalog"


   Please report this as a packaging bug to SuSE Linux.

1.4 Installing Under OpenBSD

   1. Which ports should I install to run Lire?

   Many of the softwares required to run Lire are part of the OpenBSD 2.8
   ports collection.

   Unfortunately, the minimum requirements to run aren't included in the
   ports collection. You will need to install both expat and XML::Parser
   from source.

   To run a Lire installation with all the output format supported, the
   following ports can be installed:
     * openjade
     * docbook-modular
     * jadetex
     * p5-GD-Graph

   and their other dependencies.

   You will also need to install the following from source:
     * libxslt 1.0.4 and its required library: libxml2.
       You will need to use GNU make to install libxml2 because it breaks
       with OpenBSD's native make.
     * The DocBook XML DTD and Norman Walsh's DocBook XSL stylesheets.

   If you want to run an online responder, you will also need the
   following port in addition to your Mail Transport Agent (exim,
   sendmail, postfix or qmail):
     * mpack

   OpenBSD 2.9 and 2.10 ports collection contains more required sofwares.

   To run a minimum Lire installation, you can install the following
   port:
     * p5-XML-Parser

   To run a Lire installation with all the output formats supported, the
   following ports can be installed:
     * openjade
     * docbook
     * docbook-modular
     * jadetex
     * p5-GD-Graph

   and their other dependencies.

   Although libxslt and libxml2 are included in the ports collection,
   they are older versions which aren't supported by Lire.

   You will need to install libxslt 1.0.4 from source.

   You will need to use GNU make to install libxml2 because it breaks
   with OpenBSD's native make.

   You will also need to install Norman Walsh's DocBook XSL stylesheets
   from source.

   If you want to run an online responder, you will also need the
   following port in addition to your Mail Transport Agent (exim,
   sendmail, postfix or qmail):
     * mpack

1.5 Installing Under Solaris

   1. Which packages should I install to run Lire?

   Unfortunately, most of the required tools aren't available as Solaris
   packages. The only ones that you will find on SunFreeWare are:

   DB_File, db
          Needed if you want to anonimize logs before sending them an
          online responder.

   mpack
          Needed if you want to run an online responder.

   Fortunately, most development packages that you will need to build the
   other requirements are available as packages:
     * GNU make
       zlib
       gcc
       gd
       teTeX

   The following requirements will have to be compiled from source:
     * perl GD module
     * perl GDGraph module
     * libxslt
     * libxml2
     * jade
     * jadetex

   2. Is it hard to install the needed libxslt?

   We successfully installed libxslt on a SPARCstation-20 running SunOS
   5.7, using GNU make and gcc 2.8.1. We used libxml2-2.4.5.tar.gz and
   libxslt-1.0.4.tar.gz.

   Apart from having to set our LD_LIBRARY_PATH to
   /usr/lib:/usr/local/lib (our libz from zlib-1.1.3, in
   /usr/local/lib/libz.a and /usr/local/lib/libz.so), and to set our PATH
   to include /usr/ccs/bin (to find ranlib), no issues arose.

   3. How do I install OpenJade?

   There are some issues with OpenJade. In case you get hit by something
   like :
c++ -O2 -fno-implicit-templates -I. -I./../include -I./../generic \
  -DSTDC_HEADERS=1 -DHAVE_LIMITS_H=1 -DHAVE_ST_BLKSIZE=1 -DSIZEOF_SIZE_T=4 \
  -DSIZEOF_UNSIGNED_INT=4 -DSP_HAVE_BOOL=1 -DSP_HAVE_LOCALE=1 \
  -DSP_HAVE_GETTEXT=1 -DSP_ANSI_CLASS_INST=1 -DJADE_MIF=1 -DJADE_HTML=1 \
  -DSP_MULTI_BYTE=1 \
  -DDEFAULT_SCHEME_BUILTINS=\"/usr/local/share/builtins.dsl\" -c  -fPIC \
  -DPIC TranslateCodingSystem.cxx -o TranslateCodingSystem.lo
TranslateCodingSystem.cxx: In method \
 `TranslateDecoder::TranslateDecoder(class Decoder *, const class \
 ConstPtr&lt;CharMapResource&lt;short unsigned int&gt; &gt; &amp;)':
TranslateCodingSystem.cxx:28: Internal compiler error.
TranslateCodingSystem.cxx:28: Please submit a full bug report to \
 `bug-g++@prep.ai.mit.edu'.
make[2]: *** [TranslateCodingSystem.lo] Error 1


   there's a workaround, reported by Carlos Villegas on
   dssslist@lists.mulberrytech.com, which can be implemented by running:
$ CXXFLAGS=' ' ./configure
$ make
# make install


Note

   This problem may be specific to gcc 2.8.1.

   4. How do I install Jade?

   In case you're running something like SunOS 5.7, you're advised to not
   install OpenJade, but Jade. OpenJade is reported to segfault. We've
   successfully installed Jade on such a machine. In order to build jade,
   we modified the Makefile to feature:
prefix=/usr/local
XDEFINES=-DSP_HAVE_GETTEXT -DSP_DECLARE_H_ERRNO
RANLIB=ranlib


   Test your installation by running:
$ jade -t rtf -d demo.dsl demo.sgm


   and inspecting the generated demo.rtf.

   5. While trying to generate an HTML report using lr_log2report -o
   html, I get the error following error
all all lr_tag-20011013213208-983 lr_xml2html err docbook.dsl \
 file '' does not exist!
all all lr_tag-20011013213208-983 lr_xml2html err Please install \
 Norman Walsh's DocBook DSSSL Stylesheets.
all all lr_tag-20011013213208-983 lr_xml2html err Consult the Lire \
 User's Manual for more informations.


   How do I fix this problem ?

   You need to install the following software:
     * DocBook XML DTD 4.1.2. Available from
       http://www.docbook.org/xml/4.1.2/docbkx412.zip.

     * Norman Walsh's DocBook DSSSL Stylesheets. You can download these
       from
       http://prdownloads.sourceforge.net/docbook/docbook-dsssl-1.73.tar.
       gz.

     * Norman Walsh's DocBook XSL Stylesheets. You can download these
       from
       http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.45.tar.gz

   You only have to unpack the files in a directory. Both the DocBook DTD
   distribution and the DSSSL stylesheets come with a OASIS catalog that
   you probably want to add to your SGML_CATALOG_FILES. (See next
   question for more informations.)

   Lire tries to find those components in `standard' places like
   /usr/share/sgml or /usr/lib/sgml. When configuring Lire, you should
   point it to the locations where you unpacked those files by using
   environmental variables:
$ DBK_XML_DTD="docbook_dtd_directory/docbookx.dtd" \
> DBK_DSSSL_STYLESHEETS="docbook_dsssl_directory" \
> DBK_XSL_STYLESHEETS="docbook_xsl_directory" \
./configure other-options


   6. I installed the necessary DocBook stuff, but generation of HTML
   reports still fails with the message:
bogus message: cat: cannot open /usr/home/flacoste/tmp/lr_xml2html.6050/\
 lr_xml2html.html
www combined lr_tag-20011013215447-6006 lr_log2report err lr_xml2html failed


   How do I solve this problem?

   This is probably because jade cannot find the DocBook DTD or the DSSSL
   stylesheets. You can set the DEBUG variable to 1 in your
   $HOME/.lire/etc/defaults file to make sure. If this is indeed the
   error, you will get the following in the messages output by Lire:
all all lr_tag-20011013215935-6210 lr_xml2html info /usr/local/bin/jade \
 says /usr/local/bin/jade:/usr/home/flacoste/lire-test/share/lire/sgml/\
 stylesheet/dsssl/html.dsl:1:73:W: cannot generate system identifier for \
 public text "-//James Clark//DTD DSSSL Style Sheet//EN"
all all lr_tag-20011013215935-6210 lr_xml2html info /usr/local/bin/jade \
 says /usr/local/bin/jade:/usr/home/flacoste/lire-test/share/lire/sgml/\
 stylesheet/dsssl/html.dsl:2:91:W: cannot generate system identifier for \
 public text "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"


   For jade to find the necessary `public identifiers', you will need to
   set your SGML_CATALOG_FILES to point to the necessary `OASIS
   catalogs'. This variable will need to contain at least the three
   following catalogs:
     * Catalog for DocBook XML DTD: it is in
       docbook_dtd_directory/docbook.cat.
     * Catalog that comes with Jade or OpenJade:
       jade_source_directory/dsssl/catalog.
     * Catalog that comes with Norman Walsh's DSSSL Stylesheets:
       docbook_dsssl_directory/catalog.

   So doing
$ export SGML_CATALOG_FILES="docbook_dtd_directory/docbook.cat:\
> docbook_dsssl_directory/catalog:\
> docbook_dsssl_directory/catalog"


   will probably fix the problem. Be sure to replace the
   docbook_dtd_directory and such with the actual directories where you
   installed the DocBook DTD.

1.6 Installing Under MacOS X

   1. Can I run Lire under MacOSX?

   Yes! Lire version 20011017 and later (some earlier versions too,
   probably) builds and runs under MacOSX 10.1. This has not been
   anywhere near fully tested and many features are dodgy at best.
   However, here's what you need to do to get the basic package cooking.
   This assumes some familiarity with the terminal application and
   command line interface. You'll also obviously need to have the
   developers tools installed.
     * Open a terminal window. Download and de-compress the latest lire
       package by typing the following:
$ curl http://www.logreport.org/pub/current.tar.gz
$ tar -xzvf current.tar.gz

       DO NOT decompress with StuffIt Expander. This will result in a
       broken package!
     * Then cd into the directory this creates (should be lire-20011205)
       and run the configuration utility with the --prefix option. Then
       make and make install. You can change this to wherever you want to
       install. This will create a logreport folder in your home
       directory which holds all the lire software. You might also try
       --prefix=$HOME/Applications/lire
$ ./configure --prefix=$HOME/logreport
<blah blah>
$ make
<blah blah>
$ make install

     * Now the software is in. The next step is to make your shell aware
       of it. Remember the prefix you picked above.
$ pico ~/.tcshrc

       Now add the following lines to the .tcshrc file (this is read by
       your shell whenever you log in). Then press ctrl+X to exit. Answer
       y for yes to save and hit return to write the file.
setenv PATH {$PATH}:$HOME/logreport/bin
setenv MANPATH {$MANPATH}:$HOME/logreport/man

     * Now close this shell and open a new one. You're ready to use lire.
       There are man pages to help, and a user manual is installed. The
       apache logs generated by default in OSX (in /var/log/httpd/) are
       readable by lire. You can analyze access_log as a www common file.
       This FAQ section will improve in the future as we are able to play
       with OS 10.1 more in the future.

2 Licensing

   In this section, you will find answers to common questions about
   various aspects of Lire's licensing, e.g. questions which might arise
   if you plan to extend Lire with your own code.

   Be aware that the LogReport team is very happy to include and maintain
   contributed code. We want to make this as easy as possible. See the
   first question. If you write code to be used with or as a part of
   Lire, please consider contributing it. This will not only benefit
   Stichting LogReport Foundation, but also you: the LogReport team will
   maintain and distribute your code, and will take care of handling bug
   reports.

Note

   Apply the usual disclaimers about the fact that this information
   doesn't represent `legal advice' and that you should consult an
   appropriate legal advisor for the definitive answers.

   1. I wanna contribute code, and would like it to get distributed as a
   part of Lire, what should I do, license-wise?

   As with any software, it's a good thing to add a copyright notice to
   your code, like

    Copyright (C) 2001,2002 Joe Hacker joe@example.org

   . This makes it easy to find out who holds the copyright of this
   particular piece of code. Furthermore, you should add a license
   notice, like e.g. the modified BSD license which reads

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions ar
   e met:
    1. Redistributions of source code must retain the above copyright not
   ice,
    this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
    3. The name of the copyright holder may not be used to endorse or pro
   mote
    products derived from this software without specific prior written
    permission.
    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
   IMPLIED
    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   IN NO
    EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL
   ,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMI
   TED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PR
   OFITS;
    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILI
   TY,
    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
   OR
    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN I
   F
    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   or a referal to the GPL, which reads

   This program 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 program 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 program (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.

   This makes it clear what people are allowed to do with your code. See
   the questions below for other licenses you could use. If you sent us
   code along with a copyright notice ans license notice as above, we
   have no problems licence-wise with your contribution.

   2. Why is Lire licensed under the GPL?

   The Stichting LogReport Foundation exists to develop, maintain and
   propagate tools as well as knowledge for log file processing and
   report generation (among other things). The Foundation's statutes
   mandate that all software owned by the Foundation should be made
   available under an open source license.

   The chosen license was the GNU General Public License (aka GPL)
   because it was one of most widespread "open source" licenses and it
   would allow integration of many existing code.

   You can find more about the Stichting LogReport Foundation on our
   website. Unfortunately, our articles of association are available in
   Dutch only at this time.

   3. If I make a contribution to Lire do I have to put my code under the
   GPL?

   The short answer: no. As copyright holder of your contribution, you
   are free to choose whatever license terms please you. Be aware though
   that to be included in Lire, your contribution must be made available
   under terms compatible with the GPL. Examples of licenses that have
   compatible terms are the GNU GPL, the modified BSD license, the X11
   license or the Clarified Artistic License (a list is on
   http://www.gnu.org/licenses/license-list.html).

   The more adequate answer is that it depends of the nature of your
   contribution. Contributions that cannot really be considered
   independent of Lire's distribution and thus have to be considered as
   "derived work" must be distributed under the GPL. This would include
   most patches to Lire's internals or to programs or reports included in
   Lire, but not additions of superservices, services or reports.

   4. We want to write a DLF converter for the users of our proprietary
   product, can we distribute it under the same proprietary terms as our
   other products?

   Yes. If your DLF converter doesn't include any code from Lire you are
   free to distribute it under the terms of your choice. Note that
   converters that use the publically defined DLF converter API include
   link to developer's documentation, aren't considered to be including
   or copying from Lire's code.

   Remember though that in this case, your DLF converter won't be able to
   be distributed as part of Lire.

   5. Can I distribute my XML report specifications under other terms
   than the GPL?

   Yes. The Lire Report Specification Markup Language used to define
   those reports is publically defined and no patent is held over it, so
   you are free to choose whatever license terms please you for them.

   Remember though that if your license terms aren't compatible with the
   GPL, your report specifications cannot be included in Lire's
   distribution.

   6. I want to reuse your file formats (DLF format, XML report) in my
   project, but I want to release this project under a MIT X-like
   license, may I?

   Yes. Those formats aren't protected by any patent so you are free to
   write software that read and write files in those formats if you find
   them convenient for your project.
