1newscache.conf(5) File Formats Manual newscache.conf(5)
2
3
4
6 newscache.conf
7
8
9
11 /etc/newscache.conf
12
13
14
16 The file /etc/newscache.conf defines all the NewsCache 's configuration
17 options. It is also used for updatenews(8) ,which is responsible for
18 submitting articles from the outgoing spool directory and prefetching
19 newsgroups and newscacheclean(8), which cleans up the Cache.
20
21
22 NewsCache is a free cache server for USENET News. NewsCache acts to
23 news reading clients like a news server, except that it stores only
24 those articles that have been requested by at least one client. News‐
25 Cache targets problems of the current News System like network band‐
26 width consumption or the IO load caused by news clients. NewsCache acts
27 to the upstream news server like a news reader programm.
28
29
30 It supports principles the following modes (for a detailed description
31 read ServerSpec Configuration Options below):
32
33 cached NewsCache store every retrieved article in his internal cache.
34 If this article is retrieved by another news reader client, then
35 NewsCache can get the article from his cache instead of retriev‐
36 ing this article again from the upstream newsserver.
37
38 not-cached
39 NewsCache act as a "proxy" and does'nt store retrieved article
40 in his local cache. This is usefull for combined multiple local
41 newsserver configuration.
42
43 offline
44 NewsCache does'nt connect to the upstream newsserver. Only the
45 specified newsgroups are retrieved by updatenews(8) and stored
46 in the cache. This is usefull in dialup configurations. The news
47 reader clients can only access this newsgroups.
48
49 semi-offline, cached
50 The overview informations are loaded with updatenews(8) and the
51 articles retrieved by NewsCache, if a news reader client request
52 it. The article is stored in the internal cache.
53
54
55
56 General Configuration Options
57 ConfigVersion version
58 Specifies the syntax version of the configuration file. This
59 manual page describes version 3. This allows NewsCache to detect
60 a configuration file of an older NewsCache version. If speci‐
61 fied, it should be specified as the first configuration option.
62
63 ServerType type
64 This may be either standalone for a standalone server or inetd
65 if NewsCache is started from inetd. A standalone server has the
66 advantage that the configuration file will be read once only,
67 for the cost of an extra process running all the time. Usually,
68 you use a standalone server, if NewsCache is frequently
69 accessed. The default value is standalone.
70
71 PidFile filename
72 On startup NewsCache will write its PID to the given file. This
73 can then be used by system scripts to gracefully stop NewsCache
74 by sending a SIGTERM to the parent process. No default value.
75
76 Username username
77 Change the user id to username as soon as NewsCache has bound to
78 CachePort. No default value.
79
80 Groupname groupname
81 Change the group id to groupname as soon as NewsCache has bound
82 to CachePort. No default value.
83
84 Admin email-address
85 The email address of this NewsCache's administrator.
86
87 AccessList { AccessSpec AccessSpec ... }
88 Client access configuration.
89
90 NewsServerList { ServerSpec ServerSpec ... }
91 Defines a list of news servers and the newsgroups to retrieve
92 from which news server. For a detailed description of ServerSpec
93 see the ServerSpec Configuration Options section below.
94
95 Timeouts active-db group-description
96 Timeouts in seconds for the retrieval of the active database
97 (first parameter) and the description of the newsgroups (second
98 parameter). If a client requests "list active", then newscache
99 checks if the active database timeout is reached and first
100 requests the active informations from the upstream servers
101 before returning the data to the client. Note: if the ServerSpec
102 section contains the Options offline or semioffline, then the
103 data will be not downloaded from the upstream server. You need
104 updatenews(8). The default values are 3600 seconds for both
105 parameter.
106
107 ClientTimeout t
108 Terminate the connection after t seconds inactivity. The default
109 value is 1200 seconds.
110
111 MaxConnections number
112 Maximal number of simultanous connections. This Parameter works
113 only in standalone mode. The default number is 32.
114
115 SpoolDirectory directory
116 The directory, where the cached newsgroups and articles should
117 be stored. The default value is /var/cache/newscache.
118
119 Spoolsize KBytes
120 The maximum size of the spool area. This is controlled by the
121 newscacheclean(8). The default value is 1048576 KBytes (1
122 GByte).
123
124 LogDirectory directory
125 Directory, where all the log-files should go. No default value.
126
127 LogStyle [strict-inn][hostname][ip-address]
128 StrictINN style logging; log client's hostname and or IP-
129 address.
130
131 CachePort port
132 Listen on port for incoming requests. Port may be a valid ser‐
133 vice-name (Ususally, listed in /etc/services) or a port number
134 preceded by a #-sign. This directive is uneffective if News‐
135 Cache is started from inetd.
136
137 Retries number
138 Specifies the number of retries for connecting to the news
139 server. If this limit is exceded NewsCache assumes that the
140 news server is unreachable.
141
142 PrefetchFile filename
143 Specifies the filename. No default value.
144
145 NiceServer n
146 Increment priority of the server process by n. See also nice(1).
147 The default value is 0.
148
149 NiceClient n
150 Increment priority of the client process by n. The client
151 process communicates with the user program. See also nice(1).
152
153 NiceClean n
154 Increment priority of the newscacheclean process by n. See also
155 nice(1). The newscacheclean process is a housekeeping process.
156 See alco newscacheclean(8).
157
158 ListenTo specification
159 The Address, where NewsCache is listening, if running in stand‐
160 alone mode. In a multihomed environment the address of one NIC
161 can be specified. The default Port is nntp from /etc/services.
162 For the port-number an entry fom /etc/services or a port-number
163 can be specified.
164
165 AccessSpec Configuration Options
166 Client [fqdn-or-part | ip-address/netmask]
167 {
168 allow read post debug none authentication
169 List NGSpecification
170 Read NGSpecification
171 PostTo NGSpecification
172 Authentication authenticationSpecification
173 }
174
175
176 allow [read] [post] [debug] [none] [authentication]
177 Allow read, post, debug for this Client. The default is none. If
178 only authenticated users are allowed for this network, then
179 authentication can be specified. See example "Only authenticated
180 users".
181
182 List NGSpecification
183 Permits client access to the specified newsgroups.
184
185 Read NGSpecification
186 Allow reading specified newsgroups. Same format as List.
187
188 PostTo NGSpecification
189 Allow posting to specified newsgroups. Same format as List.
190
191 NGSpecification
192 is a comma seperated list of newsgroups, where the last part of
193 newsgroup may be substituted by * standing for any string. Each
194 newsgroup is retrieved from the news server with the longest
195 match. Examples: * (all newsgroups), at.* (the whole at. hier‐
196 archy), *,!alt.binaries.* (all newsgroups without alt.binaries
197 hierarchy).
198
199 Authentication
200 Type of authentication plus authenication specific options. Pos‐
201 sible values are:
202
203 none no further authentication necessary
204
205 file:/path/to/file
206 formatdescription:
207 username:password:list:read:postto:allow
208 The additional access specification are added to the normal List
209 Read and PostTo Parameters (see above and the example section).
210 The password field is a encrypted password (md5crypt of crypt)
211 or plaintext (configured with --enable-plainpass). htpasswd from
212 the apache project can create such a password. In the allow
213 field can be additional permission specified (Example: authenti‐
214 cated user can be use the post command).
215
216 unix:list:read:postto:allow
217 Use unix authentication (getpwnam or getspnam). The additional
218 access specification are added to the normal List Read and
219 PostTo Parameters and allow(see above and the example section).
220 If only unix is specified, then all clients must step throuh the
221 authentication. If further fields specified, then unauthenti‐
222 cated clients have the access specified with the parameter
223 allow, List, ReadTo, PostTo and authenticated clients uses the
224 arguments and modify the original parameters.
225 It is also possible to specifiy empty fields, example:
226 unix:::*:debug. Which means, that the PostTo parameter is
227 extended with *. What actual settings are used by NewsCache can
228 be determined with the xdebug dump authorization command.
229
230
231 pam:list:read:postto:allow
232 Use pam authentication. For additional description of the fields
233 see: unix:list:read:postto:allow The PAM Servicename can be
234 specified with the configuration parameter PAMServicename
235
236
237 pam+file:/path/to/file
238 The authentication is handled over pam and the additional per‐
239 mission values are taken from the file. The recordformats in the
240 file are valid:
241 #this is a comment
242 hugo:at.test:at.test:at.test:post
243 @mygroup:de.*:de.*:de.*:post
244 *:us.*:us.*::
245 This mean, that after a succussfully authentication process, the
246 user hugo can list at.test, read at.test, postto at.test and
247 allow the use of post command. If the account is member of the
248 group mygroup additionally allow list de.* read de.* and postto
249 de.*, also allowing the use of the post command. * means, that
250 all users can list us.* and read us.* newsgroups.
251
252
253 PAMServicename
254 This parameter specifiy the name of the PAM Service. The default
255 is newscache. You can use different PAM settings for each Client
256 network. For further explanation of PAM see the System adminis‐
257 trators PAM Guide. This Guide can be downloaded from
258 http://www.kernel.org/pub/linux/libs/pam/pre/doc/
259
260
261 ServerSpec Configuration Options
262 [Server | NoServer] news.host Service
263 {
264 Read GroupSpec
265 PostTo GroupSpec
266 GroupTimeout seconds
267 BindFrom address (FIXME)
268 Retris nr-of-retries
269 User username
270 Password password
271 Options flags
272 Commands commands
273 }
274
275 to specify what newsgroups have to be retrived from which news
276 server and which articles have to be submitted to which news
277 server or ServerSpec may be:
278
279 NoServer { Read GroupSpec PostTo GroupSpec }
280 to specify what newsgroup has to be retrieved by no news server
281 and to which newsgroups no articles should be posted to. Or:
282
283 Server news.host Service
284
285 news.host is the name of the news server and Service indicates
286 the port, where the news server is listening for connections.
287
288 Read NewsgroupList
289 The comma separated list specifiy the wildmat newsgroup specifi‐
290 cations. Each element of the list will be fetched with the list
291 active element. Example: Read at.*,de.* will send to the
292 upstream newsserver the following two commands: list active at.*
293 and list active de.*. For details see section 2.1.2 LIST ACTIVE
294 [WILDMAT] of RFC2980. These parameter can help you saving band‐
295 width. AccessSpec Configuration Options
296 . No default value.
297
298 PostTo NGSpecification
299 NewsCache post an article to the best matching upstream
300 newsserver. If the article cannot be submitted immediately, it
301 is kept for later transmission. See the example: Multiple
302 Upstream NewsServer.
303
304 GroupTimeout seconds
305 specified how long the group information (for instance retrieved
306 with the command GROUP at.linux) is valid (in seconds). Note: if
307 the ServerSpec section contains the Options offline, then the
308 data will be not downloaded from the upstream server. You need
309 updatenews(8). The default value is 600 seconds.
310
311 Options flags
312 Specifies a list of options that should be turned on or off. The
313 default flags are: cached setpostflag. Valid flags are:
314 [not-]setpostflag
315 [not-]cached
316 [not-]offline
317 semioffline
318
319
320 [not-]setpostflag
321 set postflag to n in the active database,
322 if posting to the news server is not
323 allowed. not-setpostflag, setpostflag indi‐
324 cates whether the postflag of newsgroups on
325 servers without posting permission should
326 be set to `n'.
327
328 [not-]cached
329 not-cached, cached indicate, whether groups
330 from this server should be cached or not.
331
332 [not-]offline
333 NewsCache does'nt connect to the upstream
334 newsserver. Only the specified newsgroups
335 are retrieved by updatenews(8) and stored
336 in the cache. This is usefull in dialup
337 configurations. The news reader clients can
338 only access this newsgroups.
339
340 semioffline
341 The overview informations are loaded with
342 updatenews(8) and the articles retrieved by
343 NewsCache, if a news reader client request
344 it. The article is stored in the internal
345 cache.
346
347 Commands commands
348 All commands are switched on by default and News‐
349 Cache tries itself to find out which of the com‐
350 mands are supported. In some situations it might
351 be necessary to deactivate a command manually (eg.
352 it is not implemented correctly by your news
353 server). To switch off, prepend the command with
354 not-support commands: listgroup, over
355
357 Reducing Load from a NewsServer - cached mode
358
359 ConfigVersion 5
360 ListenTo DEFAULT
361 AccessList {
362 Client 127.0.0.1/255.255.255.255 {
363 allow read post
364 # No xdebug command for unauthenticated
365 # clients.
366 List *
367 Read *
368 PostTo *
369 Authentication unix::::debug
370 # xdebug command for authenticated clients.
371 # the empty fields (:::) doesn't modify
372 # List, Read, PostTo parameters.
373 }
374 Default {
375 allow none
376 }
377 }
378 NewsServerList {
379 Server news.host nntp {
380 List at.*
381 Read at.*
382 PostTo at.*
383 GroupTimeout 1200
384 Options cached
385 Authentication unix:*:*:*
386 # Authenticated user see all groups
387 }
388 }
389
390
391
392 Local NewsGroups
393 Configuration to transparently include local News‐
394 groups. The local Newsgroups are not cached.
395
396 ConfigVersion 5
397 ListenTo DEFAULT
398 AccessList {
399 Client 127.0.0.1/255.255.255.255 {
400 allow read post debug
401 List *
402 Read *
403 PostTo *
404 Authentication none
405 }
406 Default {
407 allow none
408 }
409 }
410 NewsServerList {
411 Server upstream.newsserver nntp {
412 Read *
413 PostTo *
414 GroupTimeout 1200
415 Options cached
416 }
417 Server local.newsserver #120 {
418 Read *
419 PostTo *
420 GroupTimeout 1200
421 Options not-cached
422 }
423 }
424
425
426
427 Offline Mode
428 Offline Mode for ppp dialup connections. The News‐
429 group of interesst have to list in prefetch-file
430 and retrieved with the updatenews program.
431
432 ConfigVersion 5
433 ListenTo DEFAULT
434 AccessList {
435 Client 127.0.0.1/255.255.255.255 {
436 allow read post debug
437 List *
438 Read *
439 PostTo *
440 Authentication none
441 }
442 Default {
443 allow none
444 }
445 }
446 NewsServerList {
447 Server upstream.newsserver nntp {
448 Read *
449 PostTo *
450 GroupTimeout 1200
451 Options offline
452 }
453 }
454
455
456
457 Only Authenticated Users
458 Only authenticated users are allowed. This example
459 show how to setup.
460
461 ConfigVersion 5
462 ListenTo DEFAULT
463 AccessList {
464 Client 127.0.0.1/255.255.255.255 {
465 allow authentication
466 List !*
467 Read !*
468 PostTo !*
469 Authentication pam:*:*:*:read,post
470 }
471 Default {
472 allow none
473 }
474 }
475 NewsServerList {
476 Server upstream.newsserver nntp {
477 Read *
478 PostTo *
479 GroupTimeout 1200
480 Options cached
481 }
482 }
483
484
485
486 Multiple Upstream NewsServer
487 We are connected to the main upstream NewsServer
488 f.q.d.n and various other NewsServer. The new
489 Newsgroups after modifications of the
490 NewsServerList are available after the Timeout
491 ActiveDB Value. This can be forced with updatenews
492 -a (see manual page updatenews).
493
494 ConfigVersion 5
495 ListenTo DEFAULT
496 AccessList {
497 Client 127.0.0.1/255.255.255.255 {
498 allow authentication
499 List *
500 Read *
501 PostTo *
502 Authentication none
503 }
504 Default {
505 allow none
506 }
507 }
508 NewsServerList {
509 Server f.q.d.n nntp {
510 Read *
511 PostTo *
512 GroupTimeout 1200
513 Options cached
514 }
515 NewsServerList {
516 Server news.redhat.com nntp {
517 Retries 3
518 Read gated.*
519 PostTo gated.*
520 GroupTimeout 1200
521 Options cached
522 }
523 Server nntp.perl.org nntp {
524 Retries 3
525 Read perl.*
526 PostTo perl.*
527 GroupTimeout 1200
528 Options cached
529 }
530 Server news.php.net nntp {
531 Retries 3
532 Read php.*
533 PostTo php.*
534 GroupTimeout 1200
535 Options cached
536 }
537 }
538
539
540
542 telnet localhost 119 and the xdebug command
543 Note: in the configuration file the allow must
544 contain the debug option. The following example
545 show the a typical xdebug session."
546
547 telnet localhost 119
548 Trying 127.0.0.1...
549 Connected to faultier.
550 Escape character is '^]'.
551 200 NewsCache 1.2, accepting NNRP commands
552 xdebug dump authorization
553 xxx authorization data follows
554 127.0.0.1/255.255.255.255{
555 access_flags=4 ( debug)
556 list=at.*
557 read=at.*
558 postto=at.*
559 authentication=unix:*:*:*:post,read
560
561 }
562 authinfo user myusername
563 381 password please
564 authinfo pass mypassword
565 281 OK.
566 xdebug dump authorization
567 xxx authorization data follows
568 127.0.0.1/255.255.255.255{
569 access_flags=7 ( read post debug)
570 list=at.*,*
571 read=at.*,*
572 postto=at.*,*
573 authentication=unix:*:*:*:post,read
574
575 }
576 quit
577 205 Good bye
578 Connection closed by foreign host.
579
580
582 /etc/newscache.conf
583 /usr/sbin/newscache
584 /usr/sbin/newscacheclean
585 /usr/sbin/updatenews
586
587
589 newscache(8), newscacheclean(8), updatenews(8)
590
592 1997-2000 Thomas Gschwind <tom@infosys.tuwien.ac.at>
593 2001-2004 Herbert Straub <h.straub@aon.at>
594
595
597 Report bugs to <newscache@linuxhacker.org>.
598
599
601 NewsCache is released under the GNU General Public
602 License (GPL). There is NO warranty; not even for MER‐
603 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
604
605
606
607
608 Jun 2004 newscache.conf(5)