|-C||Mark all articles in all newsgroups as read.|
|-F||Force newsfish to connect, even if the precommand terminates abnormally.|
|-V||Display version information and quit.|
|-h||Display command line summary and quit.|
|-v||Turns on the verbose flag.|
|Specify an alternate server configuration file. The default is $HOME/.newsfish-servers.|
|Mark all articles in group as read. You may specify multiple -c group options.|
|Limits all output files to limit bytes each. If limit ends with a b, k or m, then the actual byte limitation is limit times 512, 1024, or 1048576 respectively.|
|-l||Display all available newsgroups on the server and quit.|
|Set the maximum number of outstanding NNTP requests. For values greater than 1, newsfish will pipeline requests, allowing fuller utilization of your link. The recommended value is 10, though you may want to tune it up or down depending on the speed of your link. The default value is 1, meaning no pipelining is performed.|
|The NNTP server to connect to. If this is specified, it will override the environment variable NNTPSERVER described below.|
The file $HOME/.newsfishrc defines what newsgroups to read and what filters to apply to their articles. The format of this file is fairly simple. The file is divided into "blocks". Each "block" defines a set of filters for a particular newsgroup and what file to save matching articles to. Each "block" consists of:
Blank lines and lines beginning with a pound-sign (#) are ignored. All leading and trailing whitespace on any line are also ignored.
Multiple blocks can be defined for the same newsgroup, each with a differing set of regular expression lines (the output files need not be different). In any case, newsfish is smart enough to only process newsgroups once.
For example, to save all articles from a group called "foo.bar" on the subject of "garply", you would define the block:
foo.bar: * ^Subject:.*garply some/file
As a more complex example, to save all articles from a group called "foo.baz" on the subject of "stuff", ignoring posts from anyone with the e-mail address of <firstname.lastname@example.org>, define the block:
foo.baz: * !^From:.*someone@spam\.net * ^Subject:.*stuff another/file
If a server configuration file ( $HOME/.newsfish-servers by default) exists, newsfish will attempt to read it. This file specifies per-server configuration details, allowing newsfish to easily switch between different servers. Like $HOME/.newsfishrc, this file is also divided into "blocks". Each "block" defines a set of entries for one particular server. Each consists of:
- The name of the NNTP server enclosed in square brackets ([, ]). This does not necessarily have to be the DNS name of the NNTP server. If it isnt the DNS name of the server, you must specify a valid "host" attribute, as explained below. When newsfish is run, either the environment variable NNTPSERVER or the command-line argument NNTP server must match the name of an NNTP server block. If not, the server is assumed to have the default configuration.
- Zero or more "attributes". Each "attribute" consists of a keyword and an argument, separated by one or more whitespace. See below.
As usual, all leading and trailing whitespace are ignored. Any line that begins with a pound-sign (#) is also ignored.
A simple example that defines a news server called "mynewsserver":[mynewsserver] host news.mynewsserver.com config .newsfishrc-mynewsserver newsrc .newsfishrc-newsrc-mynewsserver
A complex example that defines a news server called "myisp". The news server requires authentication. Rather than sending our password through the network in the clear, we set up an ssh(1) tunnel to a host local to the news server.[myisp] host localhost port 1234 config .newsfishrc-myisp newsrc .newsfishrc-newsrc-myisp user myusername password mypassword preconnect ssh -f -x -L 1234:news:119 shell1.myisp.com sleep 30
The following server attributes are currently understood by newsfish:
host NNTP-host The host to connect to. If unspecified, the default is the name of the NNTP server (the name within the square brackets). port NNTP-port The port to connect to. If unspecified, the default is 119. config config-file The filter definitions file to use. If unspecified, the default is $HOME/.newsfishrc. See the special note below regarding where newsfish finds its configuration files. newsrc newsrc-file The newsrc file to use. Defaults to $HOME/.newsfish-newsrc if left unspecified. Since article numbers typically differ by NNTP server, you must specify a unique newsrc file for each server. password passwd If the server requires authentication, this specifies the password to use. If this is defined, newsfish will attempt authentication with the server. Otherwise, no authentication will be performed. Currently, newsfish only supports the "original AUTHINFO" authentication scheme. user username If the server requires authentication, this specifies the username to use. Note that for some NNTP servers, the username is optional. In this case this should be left unspecified. preconnect command Before connecting to the server, newsfish will attempt to execute command. command is passed verbatim to /bin/sh -c. newsfish will wait for the command to complete before continuing. If the command exits with a non-zero result code (usually indicating error), newsfish will immediately exit. This behavior can be controlled with the -F option described above. Finally note that although newsfish strips leading and trailing whitespace, whitespace within command are preserved. postconnect command Similar to "preconnect", but command is executed after newsfish disconnects from the server.
- Unless a configuration filename is absolute (i.e. it begins with "/" or is relative to the current directory (i.e. it begins with "./" or "../"), newsfish expects its configuration files to be relative to your home directory. For example:
Filename Expected Location .newsfishrc $HOME/.newsfishrc ./myconfig ./myconfig (in the current directory) /tmp/someconfig /tmp/someconfig foo/bar $HOME/foo/bar
This mapping applies to the server configuration file, all filter definition files, and all newsrc files. Note that this mapping does not apply to files which newsfish saves articles to. Finally note that this mapping applies to the -f config option!
- If the -C or -c group options are specified, newsfish will not scan newsgroups as usual. Instead, it will catch up all matching newsgroups and simply quit.
NNTPSERVER The NNTP server to connect to. This must be defined if NNTP server is not given on the command line.
$HOME/.newsfish-servers Contains per-server configuration details. For an example, see dot.newsfish-servers.sample.
$HOME/.newsfishrc The file containing the filter definitions. See the file dot.newsfishrc.sample for an example.
$HOME/.newsfish-newsrc Contains the highest article number for each newsgroup already scanned by newsfish.
See the file ChangeLog.
This manual page was written by
.An Allan Saddi Aq email@example.com .
See the file TODO.