NEWSFISH(1) BSD General Commands Manual NEWSFISH(1)NAMEnewsfish — batch USENET news reader with filter capabilities
SYNOPSISnewsfish [-CFVhlv] [-f config] [-c group] [-m limit] [-n maxRequests]
[NNTP server]
DESCRIPTIONnewsfish reads all unread articles in one or more newsgroups. Articles
are then subjected to a set of user-defined filters, and those that pass
are saved to a file in mailbox format. For speed, only article headers
are tested.
The options are as follows:
-C Mark all articles in all newsgroups as read.
-F Force newsfish to connect, even if the precommand termi‐
nates abnormally.
-V Display version information and quit.
-h Display command line summary and quit.
-v Turns on the verbose flag.
-f config Specify an alternate server configuration file. The default
is $HOME/.newsfish-servers.
-c group Mark all articles in group as read. You may specify multi‐
ple -c group options.
-m limit Limits all output files to limit bytes each. If limit ends
with a ``b'', ``k'' or ``m'', then the actual byte limita‐
tion is limit times 512, 1024, or 1048576 respectively.
-l Display all available newsgroups on the server and quit.
-n maxRequests
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.
NNTP server 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 fil‐
ters to apply to their articles. The format of this file is fairly sim‐
ple. The file is divided into "blocks". Each "block" defines a set of
filters for a particular newsgroup and what file to save matching arti‐
cles to. Each "block" consists of:
1. The name of the newsgroup followed by a colon. (':') The newsgroup
name may contain asterisks, in which case the conditions for the
block are applied to all blocks that match the newsgroup pattern.
The wildcard matcher is fairly simple. It only supports wildcard
prefixes (comp.sys.*), suffixes (*.hardware.misc), or both
(*.hardware.*). You may also define a global match pattern ('*'),
which will apply the conditions of the block to each and every other
block.
2. Zero or more lines beginning with an asterisk ('*'), a space (' '),
followed by an egrep(1) style regular expression. The regular
expression is case-insensitive. Leading and trailing whitespace are
ignored. If more than one of these lines are defined, then an arti‐
cle's header must match all regular expressions in order for the
article to be saved. Having no regular expression lines matches each
and every article in the newsgroup. The sense of a regular expres‐
sion line can be inverted if it is prefixed with a '!'.
3. A filename relative to the directory from which newsfish is run. Use
of absolute filenames is OK and is encouraged to eliminate ambigu‐
ity. Alternatively, if the first non-blank character is a pipe ('|')
then the rest of the line names a program (and its arguments) that
will receive the article on its standard input. The program is exe‐
cuted by ``/bin/sh -c''.
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 dif‐
fering set of regular expression lines (the output files need not be dif‐
ferent). In any case, newsfish is smart enough to only process news‐
groups 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 ⟨someone@spam.net⟩, define the block:
foo.baz:
* !^From:.*someone@spam\.net
* ^Subject:.*stuff
another/file
ADVANCED CONFIGURATION
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 differ‐
ent 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:
1. 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 isn't 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 argu‐
ment NNTP server must match the name of an NNTP server block. If
not, the server is assumed to have the default configuration.
2. 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
SERVER ATTRIBUTES
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 con‐
figuration 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 speci‐
fies the password to use. If this is defined,
newsfish will attempt authentication with the
server. Otherwise, no authentication will be per‐
formed. Currently, newsfish only supports the
"original AUTHINFO" authentication scheme.
user username If the server requires authentication, this speci‐
fies 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 ver‐
batim to ``/bin/sh -c''. newsfish will wait for the
command to complete before continuing. If the com‐
mand 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.
NOTES
· 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 news‐
groups and simply quit.
ENVIRONMENT
NNTPSERVER The NNTP server to connect to. This must be defined if NNTP
server is not given on the command line.
FILES
$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 ALSOegrep(1), sh(1)HISTORY
See the file ChangeLog.
AUTHOR
This manual page was written by Allan Saddi ⟨allan@saddi.com⟩.
BUGS
See the file TODO.
BSD June 18, 2001 BSD
