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".
- footer
- 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.
- html_footer_file
- 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.
- html_header_file
- 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.
innreport(8).