chiark / gitweb /
debugging for thing that crashed
[innduct.git] / doc / man / ninpaths.8
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "NINPATHS 8"
132 .TH NINPATHS 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 ninpaths \- Report Usenet Path statistics (new inpaths)
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBninpaths\fR \fB\-p\fR \fB\-d\fR \fIdumpfile\fR
138 .PP
139 \&\fBninpaths\fR \fB\-r\fR \fIsite\fR \fB\-u\fR \fIdumpfile\fR [\fB\-u\fR \fIdumpfile\fR ...] \fB\-v\fR
140 \&\fIlevel\fR
141 .SH "DESCRIPTION"
142 .IX Header "DESCRIPTION"
143 This is an efficient and space-saving inpaths reporting program.  It works
144 as follows:  you feed it the Path lines via an \s-1INN\s0 channel feed or some
145 other similar method, and from time to time the program writes all its
146 internal counters accumulated so far to a dump file.  Another instance of
147 the program picks up all the dump files, adds them up and formats them
148 into the report.  The purpose of the final report is to summarize the
149 frequency of occurrence of sites in the Path headers of articles.
150 .PP
151 Some central sites accumulate the Path data from many news servers running
152 this program or one like it, and then report statistics on the most
153 frequently seen news servers in Usenet article Path lines.  The
154 \&\fBsendinpaths\fR shell script can be run once a month to mail the
155 accumulated statistics to such a site and remove the old dump files.
156 .PP
157 You can get a working setup by doing the following:
158 .IP "1." 4
159 Create a directory at \fIpathlog\fR/path (replacing \fIpathlog\fR here and in
160 all steps that follow with the full path to your \s-1INN\s0 log directory).
161 .IP "2." 4
162 Set up a channel feed using an entry like:
163 .Sp
164 .Vb 1
165 \&    inpaths!:*:Tc,WP:ninpaths \-p \-d <pathlog>/path/inpaths.%d
166 .Ve
167 .Sp
168 if your version of \s-1INN\s0 supports \s-1WP\s0 (2.0 and later all do).  Replace
169 <pathlog> with the full path to your \s-1INN\s0 log directory.
170 .IP "3." 4
171 Enter into your news user crontab something like:
172 .Sp
173 .Vb 1
174 \&    6 6 * * *   ctlinnd flush inpaths!
175 .Ve
176 .Sp
177 (the actual time doesn't matter).  This will force \fBninpaths\fR to generate
178 a dump file once a day.
179 .IP "4." 4
180 Once per month, run the \fBsendinpaths\fR script, which collects the dumps,
181 makes a report, and then deletes the old dumps.  (You can generate a
182 report without mailing it and without deleting it with \f(CW\*(C`sendinpaths \-n\*(C'\fR.)
183 .SH "OPTIONS"
184 .IX Header "OPTIONS"
185 .IP "\fB\-d\fR \fIdumpfile\fR" 4
186 .IX Item "-d dumpfile"
187 Save dumps in \fIdumpfile\fR.  Any \f(CW%d\fR in \fIdumpfile\fR will be replaced with
188 the current system time when the dump is made.  This option should be used
189 with \fB\-p\fR.
190 .IP "\fB\-p\fR" 4
191 .IX Item "-p"
192 Read Path lines from standard input.
193 .IP "\fB\-r\fR \fIsite\fR" 4
194 .IX Item "-r site"
195 Generate a report for \fIsite\fR.  Generally \fIsite\fR should be the value of
196 \&\fIpathhost\fR from \fIinn.conf\fR.
197 .IP "\fB\-u\fR \fIdumpfile\fR" 4
198 .IX Item "-u dumpfile"
199 Read data from \fIdumpfile\fR.  This option can be repeated to read data from
200 multiple dump files.
201 .IP "\fB\-v\fR \fIlevel\fR" 4
202 .IX Item "-v level"
203 Set the verbosity level of the report.  Valid values for \fIlevel\fR are 0,
204 1, and 2, with 2 being the default.
205 .SH "NOTES"
206 .IX Header "NOTES"
207 If your \s-1INN\s0 doesn't have the \s-1WP\s0 feed flag (1.5 does not, 1.6 does, 1.7 I
208 don't know, 2.0 and later all do), use the following newsfeeds entry:
209 .PP
210 .Vb 1
211 \&   inpaths!:*:Tc,WH:ginpaths
212 .Ve
213 .PP
214 where \fBginpaths\fR is the following script:
215 .PP
216 .Vb 2
217 \&    #!/bin/sh
218 \&    exec egrep '^Path: ' | ninpaths \-p \-d <pathlog>/path/inpaths.%d
219 .Ve
220 .PP
221 replacing <pathlog> as above.
222 .SH "SEE ALSO"
223 .IX Header "SEE ALSO"
224 \&\fInewsfeeds\fR\|(5), \fIsendinpaths\fR\|(8)
225 .PP
226 This is a slightly modified version of Olaf Titz's original ninpaths
227 program, which is posted to alt.sources and kept on his \s-1WWW\s0 archive under
228 <http://sites.inka.de/~bigred/sw/>.
229 .SH "HISTORY"
230 .IX Header "HISTORY"
231 \&\fBninpaths\fR was written by Olaf Titz <olaf@bigred.inka.de>.
232 .PP
233 The idea and some implementation details for ninpaths come from the
234 original inpaths program, but most of the code has been rewritten for
235 clarity.  This program is in the public domain.