newscache.conf man page

ConfigVersion version

Specifies the syntax version of the configuration file. This manual page describes version 3. This allows NewsCache to detect a configuration file of an older NewsCache version. If specified, 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 parameter.

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 alco 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.

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 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/

[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
}

to specify what newsgroups have to be retrived from which news server and which articles have to be submitted to which news server or ServerSpec may be:

NoServer { Read GroupSpec PostTo GroupSpec }

to specify what newsgroup has to be retrieved by no news server and to which newsgroups no articles should be posted to. Or:

Server news.host Service

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

Read NewsgroupList

The comma separated list specifiy the wildmat newsgroup specifications. Each element of the list will be 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 parameter can help you saving bandwidth. AccessSpec Configuration Options
. No default value.

PostTo NGSpecification

NewsCache post an article to the best matching upstream newsserver. If the article cannot be submitted immediately, it is kept for later transmission. See the example: Multiple Upstream NewsServer.

GroupTimeout seconds

specified how long the group information (for instance retrieved with the command GROUP at.linux) is valid (in seconds). Note: if the ServerSpec section contains the Options offline, then the data will be not downloaded from the upstream server. You need updatenews(8). The default value is 600 seconds.

Options flags

Specifies a list of options that should be turned on or off. The default flags are: cached setpostflag. Valid flags are:

	[not-]setpostflag
	[not-]cached
	[not-]offline
	semioffline

[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.

[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'.

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