doc/pod/ninpaths.pod

   1 =head1 NAME
   2
   3 ninpaths - Report Usenet Path statistics (new inpaths)
   4
   5 =head1 SYNOPSIS
   6
   7 B<ninpaths> B<-p> B<-d> I<dumpfile>
   8
   9 B<ninpaths> B<-r> I<site> B<-u> I<dumpfile> [B<-u> I<dumpfile> ...] B<-v>
  10 I<level>
  11
  12 =head1 DESCRIPTION
  13
  14 This is an efficient and space-saving inpaths reporting program.  It works
  15 as follows:  you feed it the Path lines via an INN channel feed or some
  16 other similar method, and from time to time the program writes all its
  17 internal counters accumulated so far to a dump file.  Another instance of
  18 the program picks up all the dump files, adds them up and formats them
  19 into the report.  The purpose of the final report is to summarize the
  20 frequency of occurrence of sites in the Path headers of articles.
  21
  22 Some central sites accumulate the Path data from many news servers running
  23 this program or one like it, and then report statistics on the most
  24 frequently seen news servers in Usenet article Path lines.  The
  25 B<sendinpaths> shell script can be run once a month to mail the
  26 accumulated statistics to such a site and remove the old dump files.
  27
  28 You can get a working setup by doing the following:
  29
  30 =over 4
  31
  32 =item 1.
  33
  34 Create a directory at I<pathlog>/path (replacing I<pathlog> here and in
  35 all steps that follow with the full path to your INN log directory).
  36
  37 =item 2.
  38
  39 Set up a channel feed using an entry like:
  40
  41     inpaths!:*:Tc,WP:ninpaths -p -d <pathlog>/path/inpaths.%d
  42
  43 if your version of INN supports WP (2.0 and later all do).  Replace
  44 <pathlog> with the full path to your INN log directory.
  45
  46 =item 3.
  47
  48 Enter into your news user crontab something like:
  49
  50     6 6 * * *   ctlinnd flush inpaths!
  51
  52 (the actual time doesn't matter).  This will force B<ninpaths> to generate
  53 a dump file once a day.
  54
  55 =item 4.
  56
  57 Once per month, run the B<sendinpaths> script, which collects the dumps,
  58 makes a report, and then deletes the old dumps.  (You can generate a
  59 report without mailing it and without deleting it with C<sendinpaths -n>.)
  60
  61 =back
  62
  63 =head1 OPTIONS
  64
  65 =over 4
  66
  67 =item B<-d> I<dumpfile>
  68
  69 Save dumps in I<dumpfile>.  Any C<%d> in I<dumpfile> will be replaced with
  70 the current system time when the dump is made.  This option should be used
  71 with B<-p>.
  72
  73 =item B<-p>
  74
  75 Read Path lines from standard input.
  76
  77 =item B<-r> I<site>
  78
  79 Generate a report for I<site>.  Generally I<site> should be the value of
  80 I<pathhost> from F<inn.conf>.
  81
  82 =item B<-u> I<dumpfile>
  83
  84 Read data from I<dumpfile>.  This option can be repeated to read data from
  85 multiple dump files.
  86
  87 =item B<-v> I<level>
  88
  89 Set the verbosity level of the report.  Valid values for I<level> are 0,
  90 1, and 2, with 2 being the default.
  91
  92 =back
  93
  94 =head1 NOTES
  95
  96 If your INN doesn't have the WP feed flag (1.5 does not, 1.6 does, 1.7 I
  97 don't know, 2.0 and later all do), use the following newsfeeds entry:
  98
  99    inpaths!:*:Tc,WH:ginpaths
 100
 101 where B<ginpaths> is the following script:
 102
 103     #!/bin/sh
 104     exec egrep '^Path: ' | ninpaths -p -d <pathlog>/path/inpaths.%d
 105
 106 replacing <pathlog> as above.
 107
 108 =head1 SEE ALSO
 109
 110 newsfeeds(5), sendinpaths(8)
 111
 112 This is a slightly modified version of Olaf Titz's original ninpaths
 113 program, which is posted to alt.sources and kept on his WWW archive under
 114 L<http://sites.inka.de/~bigred/sw/>.
 115
 116 =head1 HISTORY
 117
 118 B<ninpaths> was written by Olaf Titz <olaf@bigred.inka.de>.
 119
 120 The idea and some implementation details for ninpaths come from the
 121 original inpaths program, but most of the code has been rewritten for
 122 clarity.  This program is in the public domain.
 123
 124 =cut