1newscache.conf(5)             File Formats Manual            newscache.conf(5)
2
3
4

NAME

6       newscache.conf
7
8
9

SYNOPSIS

11       /etc/newscache.conf
12
13
14

DESCRIPTION

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

EXAMPLES

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

THE xdebug COMMAND

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

FILES

582       /etc/newscache.conf
583       /usr/sbin/newscache
584       /usr/sbin/newscacheclean
585       /usr/sbin/updatenews
586
587

SEE ALSO

589       newscache(8), newscacheclean(8), updatenews(8)
590

AUTHORS

592       1997-2000 Thomas Gschwind <tom@infosys.tuwien.ac.at>
593       2001-2004 Herbert Straub <h.straub@aon.at>
594
595

REPORTING BUGS

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)
Impressum