innreport.conf - Configuration file for innreport
The file pathetc/innreport.conf permits configuring the
behaviour of innreport. It consists of a series of lines; blank lines
and what follows a number sign ("#") in a
line are ignored. The structure of this file is:
section default {
libpath "/path/to/libraries";
logpath "/path/to/logs";
module "innreport_inn";
display_conf_file "innreport-display.conf";
unwanted_log "unwanted.log";
text true;
html true; # Enable HTML reports.
# Other options to set.
};
Only this default section needs being configured. It begins
with "section default
{" and ends with "};". Each
line in the section consists of an option name followed with one or more
spaces or tabulations, its value and a semi-colon
";".
The display_conf_file option defines the name of the
display configuration file to use. This file, located in libpath, has
the same syntax as innreport.conf. If you want to use a custom
display configuration, just rename the default innreport-display.conf
file to another name, and set it in display_conf_file (otherwise,
innreport-display.conf will be overwritten each time you update
INN).
Sections defined in the display configuration file are used to
parameterize the display, how and what to report, but should not normally be
changed (unless you precisely know what you are doing). These sections are
written in a domain-specific language not intended to be modified (you may
break the reports, especially if changing data, double,
format, primary, sort, total or value
parameters). The easiest parameters to change, if needed, would be:
- title (the titles of sections in innreport),
- name (the names of the columns),
- color (the color of curves in the graphs),
- numbering (a boolean value to configure whether each row of HTML
reports is prefixed with a rank number),
- text, html, and skip (boolean values to configure
whether a given section should be present in respectively text, HTML or
both reports),
- top (the maximum number of values to display); you can specify
different values for text and HTML reports with top_text and
top_html.
The following options can be set in the default section of
the general configuration file innreport.conf:
- archive
- Sets whether HTML pages and graphs should be archived if HTML reports are
enabled. When this option is set to
"true", which is the default, a date
will be added in the file name of each report and each graph. Otherwise,
only the latest HTML report is kept.
Use of the -[no]archive flag with
innreport(8) takes precedence over the configuration file.
- casesensitive
- When this option is set to "true", which
is the default, case sensitive searches are done in news log files for
predetermined patterns.
Use of the -[no]casesensitive flag with
innreport(8) takes precedence over the configuration file.
- cycle
- Sets how many report files should be kept if HTML reports are enabled and
archived. The default is 0, meaning all archives
are kept. The value "none" also means
0.
Use of the -cycle flag with innreport(8) takes
precedence over the configuration file.
- display_conf_file
- Defines the display configuration file to use, located in the directory
set with the libpath option. The default is
"innreport-display.conf".
- encoding
- Specifies the character set to use in XML and Content-Type declarations of
HTML reports. The default is
"ISO-8859-1".
- Specifies a text to append to the end of the latest
"<div>" tag of each HTML report,
where the version of innreport is displayed. This option is unset
by default.
- graph
- If the Perl graphic library GD.pm is installed and HTML reports are
enabled, graphs are also generated in PNG if supported by
"GD", which is the case in modern
versions (GIF will otherwise be generated). This option is set to
"true" by default, meaning to enable
graph generation.
Use of the -[no]graph flag with
innreport(8) takes precedence over the configuration file.
- graph_bg
- Specifies the background colour of graphs in HTML reports as an HTML
hexadecimal colour value. The default is
"#FFFFFF" (white).
- graph_fg
- Specifies the foreground colour of graphs in HTML reports as an HTML
hexadecimal colour value. The default is
"#000000" (black).
- graph_width
- Sets the width in pixels of graphs in HTML reports. The default is
550.
- html
- This is a mandatory option with no default value. It serves two purposes:
generating HTML reports besides the plain text report printed to standard
output, and configuring in the sections other than default (in the
display configuration file) whether a section of the report should be
present in the HTML output.
If set to "true", and the
-nohtml flag not given when calling innreport, HTML
reports will be generated. These reports will not contain sections
individually having html set to
"false" in the display configuration
file (by default, everything is present in the HTML reports). Otherwise,
if the -nohtml flag is given, no HTML reports will be
generated.
If set to "false", and the
-html flag not given when calling innreport, no HTML
reports will be generated. Otherwise, if the -html flag is given,
HTML reports will be generated but only the sections individually having
html set to "true" in the
display configuration file will be present in the reports.
- html_body
- Specifies additional elements to append to the
"<body>" tag of HTML reports. This
option is unset by default.
Note that using this option leads to invalid XHTML. You should
provide a custom CSS file with the html_css_url option
instead.
- html_css_url
- Specifies the name of a CSS file to use to apply a custom style to HTML
reports. The file is located in the directory set with the html_dir
option. It may also be a URL, in which case the file may be in another
location.
If unset, which is the default, innreport creates a
default innreport.css custom style sheet in html_dir and
uses it for HTML reports.
In case you wish to supply your own style, take a look at what
is defined in the default CSS and the HTML reports, and adapt it for
your needs. Across several innreport releases that may change
classes, make sure to keep old class definitions for backward
compatibility with previously generated HTML reports still referring to
that custom file.
- html_dir
- Sets the directory for web pages if HTML reports are enabled. The default
is the value of pathhttp as set in inn.conf.
Use of the -dir flag with innreport(8) takes
precedence over the configuration file.
- html_file_extension
- Defines the file extension of generated HTML reports, if enabled. A dot
(".") should begin the extension. The
default is ".html".
You may want to use ".xhtml"
instead to let the web server serve correct MIME type, as
innreport generates XHTML 1.1 pages.
- Specifies the name of a file in html_dir whose contents will be
appended just before the "</body>"
tag of each HTML report. This option is unset by default.
- Specifies the name of a file in html_dir whose contents will be
appended just after the "<body>"
tag of each HTML report. This option is unset by default.
- html-unknown
- Whether to report unknown entries from news log files in HTML reports,
when set to "true". This option takes by
default the same value as the one for text plain reports (as set with the
unknown option).
Use of the -[no]html-unknown flag with
innreport(8) takes precedence over the configuration file.
- html_xsl_url
- Specifies the name of an XSL file to use to apply styling operations to
HTML reports. The file is located in the directory set with the
html_dir option. It may also be a URL, in which case the file may
be in another location.
This option is unset by default. When set, a corresponding XML
style sheet declaration is added to HTML reports. It may be useful for
XHTML compliance with older browsers (see
<https://www.w3.org/MarkUp/2004/xhtml-faq#ie>).
More generally, if you are interested in XSL transformation,
you may want to have a look at innreport-filter.xslt provided in
the contrib directory.
- img_dir
- Sets the web path for pictures in HTML pages if HTML reports are enabled,
and graphs are wanted. The path is relative to the directory set with the
html_dir option. The default is
"pics".
Use of the -webpath flag with innreport(8) takes
precedence over the configuration file.
- index
- Sets the name of the index web page if HTML reports are enabled. The
default is "index.html".
You may want to use
"index.xhtml" instead to let the web
server serve correct MIME type, as innreport generates
XHTML 1.1 pages.
Use of the -index flag with innreport(8) takes
precedence over the configuration file.
- libpath
- Defines the directory in which the Perl module set with the module
option is located. This option is mandatory, and usually set to the same
value as pathlib in inn.conf.
- logpath
- Defines the directory in which the log file for newsgroups not locally
carried by the news server, as set with the unwanted_log option, is
located. This option is mandatory, and usually set to the same value as
pathlog in inn.conf.
- max_unknown
- How many unrecognized entries from news log files to report, when the
unknown or html-unknown options are set. The default is
50. Using "-1"
means there is no limit.
Use of the -maxunrec flag with innreport(8)
takes precedence over the configuration file.
- module
- Defines the Perl module used by innreport to parse and summarize
log files. This option is mandatory, and usually set to
"innreport_inn". This value should not
normally be changed unless you know exactly what you are doing. The Perl
module that will be loaded is module.pm located in
the directory set with the libpath option.
- separator
- Sets the separator between hours, minutes and seconds in file names if
HTML reports are enabled and archived. The default is
"." as
":" may not be properly read by all web
browsers. Be careful not to use
"/" as a separator, and to use only a
valid file name character.
Use of the -separator flag with innreport(8)
takes precedence over the configuration file.
- text
- This is a mandatory option with no default value.
If set to "true",
innreport will print its text report to standard output. This
report will not contain sections individually having text set to
"false" in the display configuration
file (by default, everything is present in the text report).
If set to "false",
innreport will only print to standard output the sections
individually having text set to
"true" in the display configuration
file (by default, the text report will be empty).
- title
- Specifies the text to use as first words of text and HTML reports as well
as in the title of HTML reports. By default, "Daily
Usenet report" is used.
- transparent
- If set to "true", the background of
generated graphs in HTML reports will be transparent. The default is
"false".
- unknown
- Whether to report unknown entries from news log files in plain text
reports, when set to "true". This option
is enabled by default.
Use of the -[no]unknown flag with
innreport(8) takes precedence over the configuration file.
- unwanted_log
- Defines the name of the file used by innreport to maintain a count
of the number of articles that were rejected because they were posted to
newsgroups that do not exist in the active file of the news server.
This file is updated by innreport while processing the
news.notice log file and it is maintained in reverse numeric order
(the most popular rejected group first).
This option is mandatory, and usually set to
"unwanted.log". This value should not
normally be changed unless you know exactly what you are doing. The file
is located in the directory set with the logpath option.
Note that logtrash has to be set to true in
inn.conf for this file to be generated.
Written by Julien Elie for InterNetNews.