NAME
    cliservstats - create reports on host or client usage

SYNOPSIS
    cliservstats -t *host|client* [-Vhcs --comments] [-m
    *YYYY-MM*[:*YYYY-MM*] | *all*] [-n *server(s)|client(s)*] [-r *report
    type*] [-l *lower boundary*] [-u *upper boundary*] [-g *group by*] [-o
    *order by*] [-f *output format*] [--filetemplate *filename template*]
    [--db *database table*] [--conffile *filename*]

REQUIREMENTS
    See "README" in doc.

DESCRIPTION
    This script create reports on newsgroup usage (number of postings from
    each host or using each client per month) taken from result tables
    created by gatherstats.pl.

  Features and options
   Time period and names
    The time period to act on defaults to last month; you can assign another
    time period or a single month (or drop all time constraints) via the
    --month option (see below).

    cliservstats will process all hosts or clients by default; you can limit
    processing to only some hosts or clients by supplying a list of those
    names by using the --names option (see below).

   Report type
    You can choose between different --report types: postings per month or
    all postings summed up; for details, see below.

   Upper and lower boundaries
    Furthermore you can set an upper and/or lower boundary to exclude some
    results from output via the --lower and --upper options, respectively.
    By default, all hosts/clients with more and/or less postings per month
    will be excluded from the result set (i.e. not shown and not considered
    forsum reports).

   Sorting and formatting the output
    By default, all results are grouped by month; you can group results by
    hosts/clients instead via the --group-by option. Within those groups,
    the list of hosts/clients (or months) is sorted alphabetically (or
    chronologically, respectively) ascending. You can change that order (and
    sort by number of postings) with the --order-by option. For details and
    exceptions, please see below.

    The results will be formatted as a kind of table; you can change the
    output format to a simple list or just a list of names and number of
    postings with the --format option. Captions will be added by means of
    the --caption option; all comments (and captions) can be supressed by
    using --nocomments.

    Last but not least you can redirect all output to a number of files,
    e.g. one for each month, by submitting the --filetemplate option, see
    below.

  Configuration
    cliservstats will read its configuration from newsstats.conf which
    should be present in etc/ via Config::Auto or from a configuration file
    submitted by the --conffile option.

    See doc/INSTALL for an overview of possible configuration options.

    You can override some configuration options via the --db option.

OPTIONS
    -V, --version
       Print out version and copyright information and exit.

    -h, --help
       Print this man page and exit.

    -t, --type *host|client*
       Create report for hosts (servers) or clients (newsreaders), using
       *DBTableHosts* or *DBTableClnts* respectively.

    -m, --month *YYYY-MM[:YYYY-MM]|all*
       Set processing period to a single month in YYYY-MM format or to a
       time period between two month in YYYY-MM:YYYY-MM format (two month,
       separated by a colon). By using the keyword *all* instead, you can
       set no processing period to process the whole database.

    -n, --names *name(s)*
       Limit processing to a certain set of host or client names. *names(s)*
       can be a single name (eternal-september.org), a group of names
       (*.inka.de) or a list of either of these, separated by colons, for
       example

          eternal-september.org:solani.org:*.inka.de

    -s, --sums|--nosums (sum per month)
       Include a "virtual" host named "ALL" for every month in output,
       containing the sum of all detected hosts for that month.

    -r, --report *default|sums*
       Choose the report type: *default* or *sums*

       By default, cliservstats will report the number of postings for each
       host/client in each month. But it can also report the total sum of
       postings per host/client for all months.

       For report type *sums*, the group-by option has no meaning and will
       be silently ignored (see below).

    -l, --lower *lower boundary*
       Set the lower boundary. See below.

    -l, --upper *upper boundary*
       Set the upper boundary.

       By default, all hosts/clients with more postings per month than the
       upper boundary and/or less postings per month than the lower boundary
       will be excluded from further processing. For the default report that
       means each month only hosts/clients with a number of postings between
       the boundaries will be displayed. For the sums report, hosts/clients
       with a number of postings exceeding the boundaries in all (!) months
       will not be considered.

    -g, --group-by *month[-desc]|name[-desc]*
       By default, all results are grouped by month, sorted chronologically
       in ascending order, like this:

           # ----- 2012-01:
           arcor-online.net :  9379
           individual.net   : 19525
           news.albasani.net:  9063
           # ----- 2012-02:
           arcor-online.net :  8606
           individual.net   : 16768
           news.albasani.net:  7879

       The results can be grouped by host/client instead via --group-by
       *name*:

           ----- individual.net
           2012-01: 19525
           2012-02: 16768
           ----- arcor-online.net
           2012-01: 9379
           2012-02: 8606
           ----- news.albasani.net
           2012-01: 9063
           2012-02: 7879

       By appending *-desc* to the group-by option parameter, you can
       reverse the sort order - e.g. --group-by *month-desc* will give:

           # ----- 2012-02:
           arcor-online.net :  8606
           individual.net   : 16768
           news.albasani.net:  7879
           # ----- 2012-01:
           arcor-online.net :  9379
           individual.net   : 19525
           news.albasani.net:  9063

       Sums reports (see above) will always be grouped by months; this
       option will therefore be ignored.

    -o, --order-by *default[-desc]|postings[-desc]*
       Within each group (a single month or single host/client, see above),
       the report will be sorted by name (or month) in ascending
       alphabetical order by default. You can change the sort order to
       descending or sort by number of postings instead.

    -f, --format *pretty|list|dump*
       Select the output format, *pretty* being the default:

           # ----- 2012-01:
           arcor-online.net :  9379
           individual.net   : 19525
           # ----- 2012-02:
           arcor-online.net :  8606
           individual.net   : 16768

       *list* format looks like this:

           2012-01 arcor-online.net 9379
           2012-01 individual.net 19525
           2012-02 arcor-online.net 8606
           2012-02 individual.net 16768

       And *dump* format looks like this:

           # 2012-01:
           arcor-online.net 9379
           individual.net 19525
           # 2012-02:
           arcor-online.net 8606
           individual.net 16768

       You can remove the comments by using --nocomments, see below.

    -c, --captions|--nocaptions
       Add captions to output, like this:

           ----- Report for 2012-01 to 2012-02 (number of postings for each month)
           ----- Names: individual.net
           ----- Threshold: 8000 => x (counting only month fulfilling this condition)
           ----- Grouped by Month (ascending), sorted by number of postings descending

       False by default.

    --comments|--nocomments
       Add comments (group headers) to *dump* and *pretty* output. True by
       default as logn as --filetemplate is not set.

       Use *--nocomments* to suppress anything except host/client names or
       months and numbers of postings.

    --filetemplate *filename template*
       Save output to file(s) instead of dumping it to STDOUT. cliservstats
       will create one file for each month (or each host/client, accordant
       to the setting of --group-by, see above), with filenames composed by
       adding year and month (or host/client names) to the *filename
       template*, for example with --filetemplate *stats*:

           stats-2012-01
           stats-2012-02
           ... and so on

    --db *database table*
       Override *DBTableHosts* or *DBTableClnts* from newsstats.conf.

    --conffile *filename*
       Load configuration from *filename* instead of newsstats.conf.

INSTALLATION
    See "INSTALL" in doc.

EXAMPLES
    Show number of postings per group for lasth month in *pretty* format:

        cliservstats --type host

    Show that report for January of 2010 and *.inka plus individual.net:

        cliservstats --type host --month 2010-01 --names *.inka:individual.net:

    Only show clients with 30 postings or less last month, ordered by number
    of postings, descending, in *pretty* format:

        cliservstats --type client --upper 30 --order-by postings-desc

    List number of postings per host for each month of 2010 and redirect
    output to one file for each month, named hosts-2010-01 and so on, in
    machine-readable form (without formatting):

        cliservstats -t host -m 2010-01:2010-12 -f dump --filetemplate hosts

FILES
    bin/cliservstats.pl
        The script itself.

    lib/NewsStats.pm
        Library functions for the NewsStats package.

    etc/newsstats.conf
        Runtime configuration file.

BUGS
    Please report any bugs or feature requests to the author or use the bug
    tracker at <https://code.virtcomm.de/thh/newsstats/issues>!

SEE ALSO
    - "README" in doc

    - l>doc/INSTALL>

    - gatherstats -h

    This script is part of the NewsStats package.

AUTHOR
    Thomas Hochstein <thh@thh.name>

COPYRIGHT AND LICENSE
    Copyright (c) 2025 Thomas Hochstein <thh@thh.name>

    This program is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

