manandbytes / nntprss-ng Goto Github PK

nntp//rss - version 0.5
-----------------------

October 25, 2004

Bridging the worlds of NNTP clients and RSS feeds, nntp//rss is an 
application that will enable you to use your existing NNTP 
newsreader to read your favourite RSS syndicated information channels.

Project Home Page: http://www.methodize.org/nntprss
Source Forge Project Page: http://www.sourceforge.net/projects/nntprss

Email: [email protected]

Requirements
============

- Java Runtime Environment 
  (nntp//rss has been tested against JDK 1.3.1 and JDK 1.4.1 on
  Win32, and JDK 1.4.1 on Solaris, Red Hat Linux 7.2 and Mac OS X)
  Sun's Java Runtime Environment may be downloaded from:
  http://java.sun.com/j2se/downloads.html
  
- NNTP-based news reader
  nntp//rss has been tested with the following newsreaders:
    - Outlook Express 6
    - Netscape v4.7
    - Mozilla v1.2.1
    - Free Agent v1.92
    - MT-NewsWatcher v3.1 (Mac OS 9), v3.2 (Max OS X)
    - Tin 1.5.8 (RedHat 7.2) (ensure content type is set
        to text/plain in nntp//rss's System Configuration)
    - MacSoup 2.4.6 (Mac OS 9) (ensure content type is set
        to text/plain in nntp//rss's System Configuration)
    - Entourage (Office X - Mac OS X)
    - MicroPlanet Gravity v2.50


Upgrading from version 0.3
==========================

nntp//rss v0.5 uses a new database persistence engine.  This 
provides greater performance, and reduces memory usage.  Follow the
steps below if you wish to migrate your existing articles from 
nntp//rss v0.5.  Note that if you have a large database of articles,
this process may take a some time.

If you do not want to migrate your existing articles, just follow the
steps to export your channel configuration.  You can import this
configuration directly into nntp//rss v0.5.

1. Backup your channel configuration.  Go into nntp//rss's web
   administration interface, select 'System Configuration', then
   click on 'Export Channel List'.  Save the nntprss-channels.xml
   file to a safe location.

2. Stop nntp//rss v0.3

3. Backup your current nntp//rss directory.

4. As v0.5 contains a number of additional libraries and files,
   the easiest way to upgrade is to unpack nntp//rss 0.5 to a 
   separate directory, then copy over your nntp//rss 0.3 database
   files.  These files contain configuration and channel data.

   i. Unpack v0.5 to a new directory
   ii. Copy the following files from the root (nntprss) directory of 
   your nntp//rss v0.3 installation, to the root (nntprss) directory
   of your v0.5 installation:
   
   nntprssdb.properties
   nntprssdb.data
   nntprssdb.script
   nntprssdb.backup

5. If you had changed the NNTP or administrative web interface
   listener ports, you should copy over the nntprss-config.xml
   from your previous version.
   
   Also, if you had configured a users.properties file, for
   web interface security, you should copy this over from your
   previous installation.

6. Start nntp//rss v0.5
   (See below for startup information)

Your existing configuration will be kept.


Installation
============

To install nntp//rss, simply unpack the distribution into a directory
of your choice.


Configuration
=============

Configuration is only necessary at this stage if you want to
change the port on which the NNTP server listens (default 119),
or the port for the web admin interface (default 7810).

Both parameters are stored in the nntprss-config.xml file, found
in the directory where you unpacked nntp//rss.

Simply change the 'port' attribute of either the nntp or admin
elements to your desired port(s).  If you change either of the 
ports after nntp//rss has been started, you will need to stop 
and restart nntp//rss.


Running nntp//rss
=================

In the directory where you unpacked the nntp//rss distribution, execute
the following command:

Windows:

nntprss.exe

Other Platforms:

java -jar nntprss-start.jar

This will start the nntp//rss server.  The first time the server is
run, it will create and prepopulate a database with some sample feeds.
These feeds can be changed through the web-based administration
interface.

Note to Unix, Linux and Mac OS X users:

As nntp//rss starts an NNTP client listener on TCP port 119, 
if you are running on a Unix-based environment, the user under which
nntp//rss runs will need to have the appropriate rights to open that port.
If the user does not have those rights, you will see the following exception 
during startup:

19:38:44,527 [main] INFO  Main - Starting nntp//rss v0.4
java.net.BindException: Permission denied
        at java.net.PlainSocketImpl.socketBind(Native Method)
        at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:331)
...


Accessing nntp//rss from your existing news reader
==================================================

The configuration process varies from one news reader to another, so
check the documentation for your news reader on this process.  

When configuring a new news server within your newsreader for nntp//rss,
specify the following as the news server's address:

127.0.0.1

e.g. In Outlook Express, you'll specify 127.0.0.1 as the value in
the News (NNTP) Server field.

Once you have configured the news server, you will be able to
download a list of the currently configured groups.

If you experience problems with a particular news reader, please
send an email, containing details about your Operating System,
news reader version, and the problem itself to [email protected]


Administration of nntp//rss
===========================

nntp//rss has a Web-based administration interface.  Point your web
browser to the following location:

http://127.0.0.1:7810/

A list of the currently configured channels will be displayed.  From 
here you will be able add, delete, and check the status of existing
channels.  

System Configuration

Here you can alter the platform-wide polling interval.  
This defines how often nntp//rss will go out and check
RSS feeds for updates.  

In addition, you can export your current channel configuration,
or import a previous configuration.

The final option in System Configuration defines how content
is served to newsreaders.  You can either select multipart/alternative
(plain text and html), text/plain or text/html.

Click on help within the web interface for more information.


Shutting down nntp//rss
=======================

Windows - Right click on the nntp//rss System Tray icon, and 
select Exit.  Confirm the shutdown by click on the OK button.
The application will terminate all activity and cleanly shutdown.
If nntp//rss has been configured to run as a Windows Service,
use the stop button within Windows' Service Manager to shutdown
nntp//rss.

Unix/Linux - If nntp//rss is running as a foreground process in a
shell, issue a CTRL+C to cleanly shutdown the application.  If it
is running as a background process, send a SIGTERM to the java
process that is running nntp//rss.


Securing access to the web interface
====================================

Access to the web admin interface can be password protected 
by creating a file named users.properties in the root directory of 
your nntp//rss installation.

This file takes the form:

username:password

e.g. sample user.properties

jason:mypassword

Multiple users can be configured by adding additional lines of
usernames and passwords in the above format.

You will need to stop and restart nntp//rss for these changes
to take effect.  The next time you access the web interface, you
will be prompted to enter your user name and password.

To disable secure access, just delete or rename the users.properties
file, and stop and restart nntp//rss.


Running nntp//rss as a Windows Service
======================================

See the separate WINDOWS-SERVICE.TXT documentation for  
information on how to configure nntp//rss to run as a 
Windows service.


Using MySQL as the underlying Database
======================================

nntp//rss v0.5 support MySQL as a database.  To use MySQL with
nntp//rss, perform the following steps:

1. Create an empty database in MySQL, create a MySQL user, and
   assign it the appropriate rights for the new database.
2. Edit nntprss-config.xml, and comment out the entire <db> element
   for the Derby database.
3. Uncomment the <db> element for MySQL, and modify the connection
   string to match the database and user credentials for the
   database you created in step 1.
4. Start nntp//rss as shown above.


nntp//rss News Feed
===================

nntp//rss has a news feed containing the latest information 
about the project:

http://rss.methodize.org/nntprss.xml


Support
=======

If you have any questions, please email them to the following address:

[email protected]

Please keep a close watch on the nntp//rss website for future updates.