README.TXT

   1 nntp//rss - version 0.5
   2 -----------------------
   3
   4 October 25, 2004
   5
   6 Bridging the worlds of NNTP clients and RSS feeds, nntp//rss is an
   7 application that will enable you to use your existing NNTP
   8 newsreader to read your favourite RSS syndicated information channels.
   9
  10 Project Home Page: http://www.methodize.org/nntprss
  11 Source Forge Project Page: http://www.sourceforge.net/projects/nntprss
  12
  13 Email: nntprss@methodize.org
  14
  15 Requirements
  16 ============
  17
  18 - Java Runtime Environment
  19   (nntp//rss has been tested against JDK 1.3.1 and JDK 1.4.1 on
  20   Win32, and JDK 1.4.1 on Solaris, Red Hat Linux 7.2 and Mac OS X)
  21   Sun's Java Runtime Environment may be downloaded from:
  22   http://java.sun.com/j2se/downloads.html
  23
  24 - NNTP-based news reader
  25   nntp//rss has been tested with the following newsreaders:
  26     - Outlook Express 6
  27     - Netscape v4.7
  28     - Mozilla v1.2.1
  29     - Free Agent v1.92
  30     - MT-NewsWatcher v3.1 (Mac OS 9), v3.2 (Max OS X)
  31     - Tin 1.5.8 (RedHat 7.2) (ensure content type is set
  32         to text/plain in nntp//rss's System Configuration)
  33     - MacSoup 2.4.6 (Mac OS 9) (ensure content type is set
  34         to text/plain in nntp//rss's System Configuration)
  35     - Entourage (Office X - Mac OS X)
  36     - MicroPlanet Gravity v2.50
  37
  38
  39 Upgrading from version 0.3
  40 ==========================
  41
  42 nntp//rss v0.5 uses a new database persistence engine.  This
  43 provides greater performance, and reduces memory usage.  Follow the
  44 steps below if you wish to migrate your existing articles from
  45 nntp//rss v0.5.  Note that if you have a large database of articles,
  46 this process may take a some time.
  47
  48 If you do not want to migrate your existing articles, just follow the
  49 steps to export your channel configuration.  You can import this
  50 configuration directly into nntp//rss v0.5.
  51
  52 1. Backup your channel configuration.  Go into nntp//rss's web
  53    administration interface, select 'System Configuration', then
  54    click on 'Export Channel List'.  Save the nntprss-channels.xml
  55    file to a safe location.
  56
  57 2. Stop nntp//rss v0.3
  58
  59 3. Backup your current nntp//rss directory.
  60
  61 4. As v0.5 contains a number of additional libraries and files,
  62    the easiest way to upgrade is to unpack nntp//rss 0.5 to a
  63    separate directory, then copy over your nntp//rss 0.3 database
  64    files.  These files contain configuration and channel data.
  65
  66    i. Unpack v0.5 to a new directory
  67    ii. Copy the following files from the root (nntprss) directory of
  68    your nntp//rss v0.3 installation, to the root (nntprss) directory
  69    of your v0.5 installation:
  70
  71    nntprssdb.properties
  72    nntprssdb.data
  73    nntprssdb.script
  74    nntprssdb.backup
  75
  76 5. If you had changed the NNTP or administrative web interface
  77    listener ports, you should copy over the nntprss-config.xml
  78    from your previous version.
  79
  80    Also, if you had configured a users.properties file, for
  81    web interface security, you should copy this over from your
  82    previous installation.
  83
  84 6. Start nntp//rss v0.5
  85    (See below for startup information)
  86
  87 Your existing configuration will be kept.
  88
  89
  90 Installation
  91 ============
  92
  93 To install nntp//rss, simply unpack the distribution into a directory
  94 of your choice.
  95
  96
  97 Configuration
  98 =============
  99
 100 Configuration is only necessary at this stage if you want to
 101 change the port on which the NNTP server listens (default 119),
 102 or the port for the web admin interface (default 7810).
 103
 104 Both parameters are stored in the nntprss-config.xml file, found
 105 in the directory where you unpacked nntp//rss.
 106
 107 Simply change the 'port' attribute of either the nntp or admin
 108 elements to your desired port(s).  If you change either of the
 109 ports after nntp//rss has been started, you will need to stop
 110 and restart nntp//rss.
 111
 112
 113 Running nntp//rss
 114 =================
 115
 116 In the directory where you unpacked the nntp//rss distribution, execute
 117 the following command:
 118
 119 Windows:
 120
 121 nntprss.exe
 122
 123 Other Platforms:
 124
 125 java -jar nntprss-start.jar
 126
 127 This will start the nntp//rss server.  The first time the server is
 128 run, it will create and prepopulate a database with some sample feeds.
 129 These feeds can be changed through the web-based administration
 130 interface.
 131
 132 Note to Unix, Linux and Mac OS X users:
 133
 134 As nntp//rss starts an NNTP client listener on TCP port 119,
 135 if you are running on a Unix-based environment, the user under which
 136 nntp//rss runs will need to have the appropriate rights to open that port.
 137 If the user does not have those rights, you will see the following exception
 138 during startup:
 139
 140 19:38:44,527 [main] INFO  Main - Starting nntp//rss v0.4
 141 java.net.BindException: Permission denied
 142         at java.net.PlainSocketImpl.socketBind(Native Method)
 143         at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:331)
 144 ...
 145
 146
 147 Accessing nntp//rss from your existing news reader
 148 ==================================================
 149
 150 The configuration process varies from one news reader to another, so
 151 check the documentation for your news reader on this process.
 152
 153 When configuring a new news server within your newsreader for nntp//rss,
 154 specify the following as the news server's address:
 155
 156 127.0.0.1
 157
 158 e.g. In Outlook Express, you'll specify 127.0.0.1 as the value in
 159 the News (NNTP) Server field.
 160
 161 Once you have configured the news server, you will be able to
 162 download a list of the currently configured groups.
 163
 164 If you experience problems with a particular news reader, please
 165 send an email, containing details about your Operating System,
 166 news reader version, and the problem itself to nntprss@methodize.org
 167
 168
 169 Administration of nntp//rss
 170 ===========================
 171
 172 nntp//rss has a Web-based administration interface.  Point your web
 173 browser to the following location:
 174
 175 http://127.0.0.1:7810/
 176
 177 A list of the currently configured channels will be displayed.  From
 178 here you will be able add, delete, and check the status of existing
 179 channels.
 180
 181 System Configuration
 182
 183 Here you can alter the platform-wide polling interval.
 184 This defines how often nntp//rss will go out and check
 185 RSS feeds for updates.
 186
 187 In addition, you can export your current channel configuration,
 188 or import a previous configuration.
 189
 190 The final option in System Configuration defines how content
 191 is served to newsreaders.  You can either select multipart/alternative
 192 (plain text and html), text/plain or text/html.
 193
 194 Click on help within the web interface for more information.
 195
 196
 197 Shutting down nntp//rss
 198 =======================
 199
 200 Windows - Right click on the nntp//rss System Tray icon, and
 201 select Exit.  Confirm the shutdown by click on the OK button.
 202 The application will terminate all activity and cleanly shutdown.
 203 If nntp//rss has been configured to run as a Windows Service,
 204 use the stop button within Windows' Service Manager to shutdown
 205 nntp//rss.
 206
 207 Unix/Linux - If nntp//rss is running as a foreground process in a
 208 shell, issue a CTRL+C to cleanly shutdown the application.  If it
 209 is running as a background process, send a SIGTERM to the java
 210 process that is running nntp//rss.
 211
 212
 213 Securing access to the web interface
 214 ====================================
 215
 216 Access to the web admin interface can be password protected
 217 by creating a file named users.properties in the root directory of
 218 your nntp//rss installation.
 219
 220 This file takes the form:
 221
 222 username:password
 223
 224 e.g. sample user.properties
 225
 226 jason:mypassword
 227
 228 Multiple users can be configured by adding additional lines of
 229 usernames and passwords in the above format.
 230
 231 You will need to stop and restart nntp//rss for these changes
 232 to take effect.  The next time you access the web interface, you
 233 will be prompted to enter your user name and password.
 234
 235 To disable secure access, just delete or rename the users.properties
 236 file, and stop and restart nntp//rss.
 237
 238
 239 Running nntp//rss as a Windows Service
 240 ======================================
 241
 242 See the separate WINDOWS-SERVICE.TXT documentation for
 243 information on how to configure nntp//rss to run as a
 244 Windows service.
 245
 246
 247 Using MySQL as the underlying Database
 248 ======================================
 249
 250 nntp//rss v0.5 support MySQL as a database.  To use MySQL with
 251 nntp//rss, perform the following steps:
 252
 253 1. Create an empty database in MySQL, create a MySQL user, and
 254    assign it the appropriate rights for the new database.
 255 2. Edit nntprss-config.xml, and comment out the entire <db> element
 256    for the Derby database.
 257 3. Uncomment the <db> element for MySQL, and modify the connection
 258    string to match the database and user credentials for the
 259    database you created in step 1.
 260 4. Start nntp//rss as shown above.
 261
 262
 263 nntp//rss News Feed
 264 ===================
 265
 266 nntp//rss has a news feed containing the latest information
 267 about the project:
 268
 269 http://rss.methodize.org/nntprss.xml
 270
 271
 272 Support
 273 =======
 274
 275 If you have any questions, please email them to the following address:
 276
 277 nntprss@methodize.org
 278
 279 Please keep a close watch on the nntp//rss website for future updates.