Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NEWSFISH(1)		  BSD General Commands Manual		   NEWSFISH(1)

     newsfish -- batch USENET news reader with filter capabilities

     newsfish [-CFVhlv]	[-f config] [-c	group] [-m limit] [-n maxRequests]
	      [NNTP server]

     newsfish 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, al-
		   lowing fuller utilization of	your link.  The	recommended
		   value is 10,	though you may want to tune it up or down de-
		   pending 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

     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

     2.	  Zero or more lines beginning with an asterisk	('*'), a space (' '),
	  followed by an egrep(1) style	regular	expression. The	regular	ex-
	  pression 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 ar-
	  ticle	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 "" on	the
     subject of	"garply", you would define the block:
	   * ^Subject:.*garply

     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 <>, define the block:

	   * !^From:.*someone@spam\.net
	   * ^Subject:.*stuff

     If	a server configuration file ($HOME/.newsfish-servers by	default) ex-
     ists, 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":

	   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.

	   host	localhost
	   port	1234
	   config .newsfishrc-myisp
	   newsrc .newsfishrc-newsrc-myisp
	   user	myusername
	   password mypassword
	   preconnect ssh -f -x	-L 1234:news:119 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	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 at-
			  tempt	to execute command.  command is	passed verba-
			  tim 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 in-
			  dicating 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 af-
			  ter newsfish disconnects from	the server.

     +o	 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!

     +o	 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.

     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.

     egrep(1), sh(1)

     See the file ChangeLog.

     This manual page was written by Allan Saddi <>.

     See the file TODO.

BSD				 June 18, 2001				   BSD


Want to link to this manual page? Use this URL:

home | help