WebNews Documentation

[ Home Documentation CVS Download Mailing Lists ]

Prerequisites for installation

WebNews is written in Perl. You will need Perl 5.005_03 or later installed. The most recent version of WebNews has been tested with Perl 5.8.4. Earlier versions have been known to work with Perl 5.6.1.

WebNews is a CGI script. You will need a web server which understands user authentication and which can authenticate users appropriately for your setup. I have tested this script with Apache 1.3.12 and 1.3.19, and Boa 0.94.11 and 0.94.13. I know of people who are running it successfully with Apache 2.0.x. I am interested to hear about any problems with other web servers.

I have tested this script with Apache's mod_perl version 1.24_01. See below for details.

You'll need to install the following Perl modules:

The quickest way to get these Perl modules is from the CPAN list of modules by name. Or you can use the Perl "CPAN" module, e.g.,

	# perl -MCPAN -e 'install News::NNTPClient'

Installation

Unpack the source tar file somewhere inside your WWW document root. Make sure everything is readable and executable by your web user. Or, with Apache, set it up in the UserDir of a user dedicated to webnews (and use suEXEC.) Note: WebNews must be able to write the active file active.txt and its users directory, both in the $WNDIR directory (see the configuration file).

Modify index.cgi to redirect users to your webnews.cgi script.

Or, if you intend to use a separate cgi-bin directory, then delete index.cgi, and move webnews.cgi to your cgi-bin directory.

Copy webnews.conf.example to webnews.conf, and edit it to suit your installation. There are comments in the file which should help.

Change the line that mentions 'webnews.conf' at the beginning of webnews.cgi to have the correct, full pathname of your webnews.conf file.

Make sure webnews.cgi can be run by your perl installation. (Change the #! line at the top of the file to have the full pathname of your perl interpreter.) Try "perl -wc webnews.cgi" and see if you get "webnews.cgi syntax OK". After all, compilation is half the battle.

Set up an .htaccess or other file which will force users who attempt to access webnews.cgi to provide authentication. All access to WebNews facilities requires that they go through the webnews.cgi script.

Testing

In your browser, go to the URL which corresponds to index.cgi (if you're using it), or go to the webnews.cgi URL itself. You should arrive at the WebNews main screen after authenticating yourself to the server.

Assuming that the web server appropriately sets the REMOTE_USER CGI environment variable, this should result in your being logged in to WebNews, with an initial newsrc containing a subscription to news.announce.newusers. This will take some time -- be patient!! The first time you run WebNews, the client has to download the active file from the webserver; this is how it knows which newsgroups are valid.

Try subscribing to and unsubscribing from some newsgroups, reading news, posting news, etc. If you are worried about people finding your address on Usenet when all you want to do is post a test message, you can set the SPAMFILTER variable in webnews.conf to 1, which will result in your e-mail address being changed to spamfilter@yourdomain.com (or something like that...this is obviously not a good option to turn on in general use.)

Having trouble? Read our list of common troubleshooting tips.

Use with mod_perl

I have recently had the chance to experiment with WebNews 1.2.1 and mod_perl 1.24_01. It seems to work if you make the following changes:

0. Let's say your mod_perl setup has aliased location /perl to the directory /services/http/perl. Install webnews in /services/http/perl/webnews.

1. Change the permissions on the webnews and webnews/users directories to be writable by the web server user and group.

2. Suppose you have the following in your Apache httpd.conf:

  Alias /perl/ /services/http/perl/
  <Location /perl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options +ExecCGI
  </Location>

2a. Change "SetHandler perl-script" to "AddHandler perl-script .cgi", so that non-Perl stuff can be accessed from the WebNews installation directory.

2b. Add the following so that your .htaccess can be read:

  <Directory "/services/http/perl">
    AllowOverride All
  </Directory>

I am interested in improving this documentation by hearing bug reports or other users' experiences.

Caveats and Known Bugs

WebNews does very little caching, and so if you have a slow news server or a slow connection to your news server, WebNews will be slow, too.

Users cannot add their own headers to messages.

WebNews assumes that it can look up users' real names with getpwnam; if this isn't true, you'd probably want to change the gecos_name function in webnews.cgi to look them up out of a database or do whatever is appropriate for your site.


Maintained by Brian R. Gaeke