newscache.conf(5)

📦 version 1.2, in fedora 43, fedora 44

💖 newscache.conf 💖

okay so bestie, this is the newscache.conf(5) File Formats Manual page and honestly it's a whole meal. grab a snack, we're doing this. 🍓

✨ NAME ✨

newscache.conf — that's literally it, that's the name, she's simple, she's iconic. 👑

🌸 SYNOPSIS 🌸

/etc/newscache.conf

🦋 DESCRIPTION 🦋

so the file /etc/newscache.conf is where all of NewsCache's configuration options live. periodt. it's also the file that updatenews(8) reads — that's the program responsible for submitting articles from the outgoing spool directory and prefetching newsgroups — and it's what newscacheclean(8) reads too, and that one cleans up the Cache. 🧹

NewsCache is a free cache server for USENET News, no cap. to news-reading clients it acts like a news server, EXCEPT (and this is the plot twist 💀) it only stores those articles that have been requested by at least one client. it's out here targeting the problems of the current News System like network bandwidth consumption and the IO load caused by news clients. and to the upstream news server? it acts like a news reader programm. two-faced in the most slay way. 💅

it supports the following modes (for the full tea, read the ServerSpec Configuration Options section below):

  • cached — NewsCache stores every retrieved article in his internal cache. if this article is retrieved by another news reader client, then NewsCache can get the article from his cache instead of retrieving this article again from the upstream newsserver. obsessed. ✨
  • not-cached — NewsCache acts as a "proxy" and doesn't store retrieved article in his local cache. this is useful for combined multiple local newsserver configuration.
  • offline — NewsCache doesn't connect to the upstream newsserver. only the specified newsgroups are retrieved by updatenews(8) and stored in the cache. this is useful in dialup configurations. the news reader clients can only access this newsgroups.
  • semi-offline, cached — the overview informations are loaded with updatenews(8) and the articles retrieved by NewsCache, if a news reader client requests it. the article is stored in the internal cache.

🎀 General Configuration Options 🎀

  • ConfigVersion version — specifies the syntax version of the configuration file. this manual page describes version 3. this lets NewsCache detect a configuration file from an older NewsCache version. if you're gonna specify it, it should be specified as the first configuration option. 👑
  • ServerType type — this may be either standalone for a standalone server, or inetd if NewsCache is started from inetd. a standalone server has the advantage that the configuration file will be read once only, for the cost of an extra process running all the time. usually you use a standalone server if NewsCache is frequently accessed. the default value is standalone.
  • PidFile filename — on startup NewsCache will write its PID to the given file. this can then be used by system scripts to gracefully stop NewsCache by sending a SIGTERM to the parent process. no default value. 🫶
  • Username username — change the user id to username as soon as NewsCache has bound to CachePort. no default value.
  • Groupname groupname — change the group id to groupname as soon as NewsCache has bound to CachePort. no default value.
  • Admin email-address — the email address of this NewsCache's administrator. 📧
  • AccessList { AccessSpec AccessSpec ... } — client access configuration.
  • NewsServerList { ServerSpec ServerSpec ... } — defines a list of news servers and the newsgroups to retrieve from which news server. for a detailed description of ServerSpec see the ServerSpec Configuration Options section below.
  • Timeouts active-db group-description — timeouts in seconds for the retrieval of the active database (first parameter) and the description of the newsgroups (second parameter). if a client requests "list active", then newscache checks if the active database timeout is reached and first requests the active informations from the upstream servers before returning the data to the client.
Note: if the ServerSpec section contains the Options offline or semioffline, then the data will be not downloaded from the upstream server. you need updatenews(8). 😭

the default values are 3600 seconds for both parameters.

  • ClientTimeout t — terminate the connection after t seconds inactivity. the default value is 1200 seconds.
  • MaxConnections number — maximal number of simultanous connections. this parameter works only in standalone mode. the default number is 32.
  • SpoolDirectory directory — the directory where the cached newsgroups and articles should be stored. the default value is /var/cache/newscache.
  • Spoolsize KBytes — the maximum size of the spool area. this is controlled by the newscacheclean(8). the default value is 1048576 KBytes (1 GByte).
  • LogDirectory directory — directory where all the log-files should go. no default value.
  • LogStyle [strict-inn][hostname][ip-address] — StrictINN style logging; log client's hostname and or IP-address.
  • CachePort port — listen on port for incoming requests. port may be a valid service-name (ususally, listed in /etc/services) or a port number preceded by a #-sign. this directive is uneffective if NewsCache is started from inetd.
  • Retries number — specifies the number of retries for connecting to the news server. if this limit is exceded, NewsCache assumes that the news server is unreachable. 💀
  • PrefetchFile filename — specifies the filename. no default value.
  • NiceServer n — increment priority of the server process by n. see also nice(1). the default value is 0.
  • NiceClient n — increment priority of the client process by n. the client process communicates with the user program. see also nice(1).
  • NiceClean n — increment priority of the newscacheclean process by n. see also nice(1). the newscacheclean process is a housekeeping process. see also newscacheclean(8).
  • ListenTo specification — the address where NewsCache is listening, if running in standalone mode. in a multihomed environment the address of one NIC can be specified. the default Port is nntp from /etc/services. for the port-number an entry fom /etc/services or a port-number can be specified. 🌈

🧚 AccessSpec Configuration Options 🧚

Client [fqdn-or-part | ip-address/netmask]
{
     allow read post debug none authentication
     List NGSpecification
     Read NGSpecification
     PostTo NGSpecification
     Authentication authenticationSpecification
}
  • allow [read] [post] [debug] [none] [authentication] — allow read, post, debug for this Client. the default is none. if only authenticated users are allowed for this network, then authentication can be specified. see example "Only authenticated users".
  • List NGSpecification — permits client access to the specified newsgroups.
  • Read NGSpecification — allow reading specified newsgroups. same format as List.
  • PostTo NGSpecification — allow posting to specified newsgroups. same format as List.
  • NGSpecification — is a comma seperated list of newsgroups, where the last part of newsgroup may be substituted by * standing for any string. each newsgroup is retrieved from the news server with the longest match. examples: * (all newsgroups), at.* (the whole at. hierarchy), *,!alt.binaries.* (all newsgroups without the alt.binaries hierarchy).
  • Authentication — type of authentication plus authenication specific options. possible values are:
  • none — no further authentication necessary.
  • file:/path/to/file — formatdescription:
username:password:list:read:postto:allow

the additional access specification are added to the normal List, Read and PostTo parameters (see above and the example section). the password field is a encrypted password (md5crypt of crypt) or plaintext (configured with --enable-plainpass). htpasswd from the apache project can create such a password. in the allow field can be additional permission specified (example: authenticated user can be use the post command).

  • unix:list:read:postto:allow — use unix authentication (getpwnam or getspnam). the additional access specification are added to the normal List, Read and PostTo parameters and allow (see above and the example section). if only unix is specified, then all clients must step throuh the authentication. if further fields specified, then unauthenticated clients have the access specified with the parameter allow, List, ReadTo, PostTo and authenticated clients uses the arguments and modify the original parameters. it is also possible to specifiy empty fields, example: unix:::*:debug. which means, that the PostTo parameter is extended with *. what actual settings are used by NewsCache can be determined with the xdebug dump authorization command. 🔍
  • pam:list:read:postto:allow — use pam authentication. for additional description of the fields see: unix:list:read:postto:allow. the PAM Servicename can be specified with the configuration parameter PAMServicename.
  • pam+file:/path/to/file — the authentication is handled over pam and the additional permission values are taken from the file. the recordformats in the file are valid:
#this is a comment
hugo:at.test:at.test:at.test:post
@mygroup:de.*:de.*:de.*:post
*:us.*:us.*::

this mean, that after a succussfully authentication process, the user hugo can list at.test, read at.test, postto at.test and allow the use of post command. if the account is member of the group mygroup additionally allow list de.*, read de.* and postto de.*, also allowing the use of the post command. * means, that all users can list us.* and read us.* newsgroups. 💖

  • PAMServicename — this parameter specifiy the name of the PAM Service. the default is newscache. you can use different PAM settings for each Client network. for further explanation of PAM see the System administrators PAM Guide. this Guide can be downloaded from http://www.kernel.org/pub/linux/libs/pam/pre/doc/ 🎀

🛠️ ServerSpec Configuration Options 🛠️

okay bestie, here's the whole shape of a server spec, take it in:

[Server | NoServer] news.host Service
{
     Read GroupSpec
     PostTo GroupSpec
     GroupTimeout seconds
     BindFrom address (FIXME)
     Retris nr-of-retries
     User username
     Password password
     Options flags
     Commands commands
}

This is how you tell NewsCache which newsgroups get retrieved from which news server and which articles get submitted to which news server. Or, ServerSpec can be:

NoServer { Read GroupSpec PostTo GroupSpec }

…which is the way to say no news server retrieves these newsgroups and no articles should be posted to these newsgroups. Or:

Server news.host Service

where news.host is the name of the news server, and Service is the port where the news server is listening for connections. 🫶

  • Read NewsgroupList — the comma-separated list specifies the wildmat newsgroup specifications. Each element of the list gets fetched with the list active element. Example: Read at.*,de.* will send to the upstream newsserver the following two commands: list active at.* and list active de.*. For details see section 2.1.2 LIST ACTIVE [WILDMAT] of RFC2980. These parameters can help you save bandwidth. AccessSpec Configuration Options . No default value.
  • PostTo NGSpecification — NewsCache posts an article to the best matching upstream newsserver. If the article can't be submitted immediately, it's kept for later transmission. Peep the example: Multiple Upstream NewsServer.
  • GroupTimeout seconds — how long the group information (like, say, what you got back from the command GROUP at.linux) stays valid, in seconds. Heads up: if the ServerSpec section contains the Options offline, then the data will not be downloaded from the upstream server. You need updatenews(8). The default value is 600 seconds.
  • Options flags — a list of options to turn on or off. The default flags are: cached setpostflag. The valid flags are:
[not-]setpostflag
[not-]cached
[not-]offline
semioffline
  • [not-]setpostflag — set postflag to n in the active database, if posting to the news server is not allowed. not-setpostflag, setpostflag indicates whether the postflag of newsgroups on servers without posting permission should be set to `n'.
  • [not-]cached — not-cached, cached indicate whether groups from this server should be cached or not.
  • [not-]offline — NewsCache does'nt connect to the upstream newsserver. Only the specified newsgroups are retrieved by updatenews(8) and stored in the cache. This is usefull in dialup configurations. The news reader clients can only access this newsgroups.
  • semioffline — the overview informations are loaded with updatenews(8) and the articles retrieved by NewsCache, if a news reader client request it. The article is stored in the internal cache.
  • Commands commands — all commands are switched on by default, and NewsCache tries itself to find out which of the commands are supported. In some situations it might be necessary to deactivate a command manually (eg. it is not implemented correctly by your news server). To switch off, prepend the command with not-; support commands: listgroup, over.

🌈 EXAMPLES 🌈

💖 Reducing Load from a NewsServer - cached mode 💖

ConfigVersion 5
ListenTo DEFAULT
AccessList {
     Client 127.0.0.1/255.255.255.255 {
          allow read post
          # No xdebug command for unauthenticated
          # clients.
          List *
          Read *
          PostTo *
          Authentication unix::::debug
          # xdebug command for authenticated clients.
          # the empty fields (:::) doesn't modify
          # List, Read, PostTo parameters.
     }
     Default {
          allow none
     }
}
NewsServerList {
     Server news.host nntp {
          List at.*
          Read at.*
          PostTo at.*
          GroupTimeout 1200
          Options cached
          Authentication unix:*:*:*
          # Authenticated user see all groups
     }
}

🦋 Local NewsGroups 🦋

Configuration to transparently include local Newsgroups. The local Newsgroups are not cached.

ConfigVersion 5
ListenTo DEFAULT
AccessList {
     Client 127.0.0.1/255.255.255.255 {
          allow read post debug
          List *
          Read *
          PostTo *
          Authentication none
     }
     Default {
          allow none
     }
}
NewsServerList {
     Server upstream.newsserver nntp {
          Read *
          PostTo *
          GroupTimeout 1200
          Options cached
     }
     Server local.newsserver #120 {
          Read *
          PostTo *
          GroupTimeout 1200
          Options not-cached
     }
}

🌸 Offline Mode 🌸

Offline Mode for ppp dialup connections. The Newsgroup of interesst have to list in prefetch-file and retrieved with the updatenews program.

ConfigVersion 5
ListenTo DEFAULT
AccessList {
     Client 127.0.0.1/255.255.255.255 {
          allow read post debug
          List *
          Read *
          PostTo *
          Authentication none
     }
     Default {
          allow none
     }
}
NewsServerList {
     Server upstream.newsserver nntp {
          Read *
          PostTo *
          GroupTimeout 1200
          Options offline
     }
}

🔐 Only Authenticated Users 🔐

Only authenticated users are allowed. This example shows how to set it up.

ConfigVersion 5
ListenTo DEFAULT
AccessList {
     Client 127.0.0.1/255.255.255.255 {
          allow authentication
          List !*
          Read !*
          PostTo !*
          Authentication pam:*:*:*:read,post
     }
     Default {
          allow none
     }
}
NewsServerList {
     Server upstream.newsserver nntp {
          Read *
          PostTo *
          GroupTimeout 1200
          Options cached
     }
}

👑 Multiple Upstream NewsServer 👑

We're connected to the main upstream NewsServer f.q.d.n and various other NewsServer. The new Newsgroups after modifications of the NewsServerList are available after the Timeout ActiveDB value. This can be forced with updatenews -a (see manual page updatenews).

ConfigVersion 5
ListenTo DEFAULT
AccessList {
     Client 127.0.0.1/255.255.255.255 {
          allow authentication
          List *
          Read *
          PostTo *
          Authentication none
     }
     Default {
          allow none
     }
}
NewsServerList {
     Server f.q.d.n nntp {
          Read *
          PostTo *
          GroupTimeout 1200
          Options cached
     }
     NewsServerList {
            Server news.redhat.com nntp {
          Retries 3
          Read gated.*
          PostTo gated.*
          GroupTimeout 1200
          Options cached
       }
       Server nntp.perl.org nntp {
              Retries 3
          Read perl.*
          PostTo perl.*
          GroupTimeout 1200
          Options cached
       }
       Server news.php.net nntp {
              Retries 3
          Read php.*
          PostTo php.*
          GroupTimeout 1200
          Options cached
       }
}

🔥 THE xdebug COMMAND 🔥

telnet localhost 119 and the xdebug command

Note: in the configuration file the allow must contain the debug option. The following example shows a typical xdebug session.
telnet localhost 119
Trying 127.0.0.1...
Connected to faultier.
Escape character is '^]'.
200 NewsCache 1.2, accepting NNRP commands
xdebug dump authorization
xxx authorization data follows
127.0.0.1/255.255.255.255{
  access_flags=4 ( debug)
  list=at.*
  read=at.*
  postto=at.*
  authentication=unix:*:*:*:post,read

}
authinfo user myusername
381 password please
authinfo pass mypassword
281 OK.
xdebug dump authorization
xxx authorization data follows
127.0.0.1/255.255.255.255{
  access_flags=7 ( read post debug)
  list=at.*,*
  read=at.*,*
  postto=at.*,*
  authentication=unix:*:*:*:post,read

}
quit
205 Good bye
Connection closed by foreign host.

📁 FILES 📁

  • /etc/newscache.conf
  • /usr/bin/newscache
  • /usr/bin/newscacheclean
  • /usr/bin/updatenews

👀 SEE ALSO 👀

newscache(8), newscacheclean(8), updatenews(8)

💜 AUTHORS 💜

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

🐛 REPORTING BUGS 🐛

Report bugs to <newscache@linuxhacker.org>.

Okay so legal bit, bestie, but it's important so we're paying attention 📜✨

NewsCache is released under the GNU General Public License (GPL). Slay, freedom software, we love to see it 💅

⚠️ And listen — there is NO warranty. Like, none. Not even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Nada. Zero. Don't come for them if it breaks, that's the deal 🫶

That's the whole thing. Short, sweet, very "we gave you the source code, now go be free" energy 🌈

And that's a wrap on newscache.conf(5) bestie!! 🎀 You made it all the way to the end, I'm so proud of you fr fr 💜

This page is from Jun 2004, and it's the man page for newscache.conf — section 5 of the manual. Go forth and configure responsibly, you absolute icon 👑💖

📦 where this page comes from