DNEWSWEB Installation and Upgrade instructions

# DNEWS News Server Manual

- Installing DNEWSWEB
- INI File Settings
- Templates Settings
- Input Forms
- Frames
- FAQ
- New Features in 4.7

### Installing DNEWSWEB

DNEWSWEB is a web to news gateway, it lets you merge your web pages and your news groups. By displaying usenet and local news groups on your web pages users can read and post news directly using their favourite web browser.

DNEWSWEB is provided FREE with your DNEWS News Server and is quick and simple to set-up.

You will have recieved the following DNEWSWEB files when you downloaded DNEWS:

dnews\dnewsweb.exe
dnews\dnewsweb.ini
dnews\dnewsweb.txt
dnews\web\*.tpl (directory of template html files)

templates d:/dnews/web

You must install DNEWSWEB on your WEB server, in a directory that you have already setup on your server as containing CGI programs, you must read your server documentation if you don't currently know how to setup a cgi program, typically you would copy the files to a directory like:

    SERVER_ROOT\cgi-bin\

Two files should be copied to this directory

    copy \dnews\dnewsweb.exe \SERVER_ROOT\cgi-bin
    copy \dnews\dnewsweb.ini \SERVER_ROOT\cgi-bin

In some instances you will have to place the .ini file in a different directory, this is dependent on your server software, sometimes the 'SERVER_ROOT' is the right directory. (DNEWSWEB will give an error if it can't find this file, in which case just try moving it somewhere else).

Now edit dnewsweb.ini and define: your news host, templates directory and news groups to display on your web page.

Example:

    notepad \SERVER_ROOT\cgi-bin\dnewsweb.ini

    Syntax: Parameter Value

Parameter | Value (Example) | Explanation
newshost | news.your.domain | The name or number of your DNEWS news server. Use an IP number to speed up the process.
templates | c:/dnewsweb | The directory where you have copied the *.tpl files, On UNIX this directory must be set so that dnewsweb can write to it. e.g. chown nobody /var/spool/dnewsweb
auto_subscribe | rec.humor, local.chat,local support | This setting allows you to list the news group who's names you want to appear on the subscribed list for new users. Generally you will want to list some Groups of particular interest or importance. For example you may have a local support news group or want everyone to see the rec.humor group or rec.chat
allow | local.*,rec.* | Groups to actually let people read: This setting allows you to specify which of all news groups you will allow access to via your website. For example allow rec.* allows all groups matching the rec.anything in the news header

Now copy the tpl files from the distribution directory to the directory you have defined for templates in dnewsweb.ini

    	cd /dnews/web
    	copy *.tpl /dnewsweb

If you wish, you can tailor the template files to give dnewsweb the same look and feel as your own web pages. It is assumed you know how to edit raw html files, in addition there are some variables that you can use. The list of variables depends on which page dnewsweb is showing. For example the `%%h_subject%%` variable only works when displaying an item, or directory listing.

Note: If you leave the template files in the /dnews directory, then they will be over-written next time you upgrade dnews, so it is best to move them if you wish to tailor the appearance.

Here is a list of the template files, and a brief description of each. In some cases alternate files have been included in the distribution, you may want to try one of these for an alternate layout, simply copy the alternate file over the top of the original.

File Name | Description
top.tpl | The first/top page shown when dnewsweb is run
list.tpl | A list of newsgroups at a given level in the tree
items.tpl | A single news group, listing articles in that group
item.tpl | A single article within a news group
follow.tpl | Used when user posts a FOLLOW-UP message
post.tpl | Used when a user post a NEW message
posted.tpl | To tell the user that the post was successful
required.tpl | To tell the user that a required field was not filled in
search.tpl | For searching the FTS database (if enabled)
results.tpl | Results of FTS search
xsearch.tpl | For searching a single news group
xresults.tpl | Results of searching single news group
postit.tpl | Template for messages posted using posting form
post_form.tpl | For posting with extra fields on form (replace post.tpl with this)

### Template Variables

Here is a list of some of the variables that you can use in these templates

Variable | Description | Typicall in
%%b_action%% | the cgi ref to dnewsweb needed for a form 'action' |
%%b_group%% | href to go to an individual group | top.tpl
%%b_search%% | href to go to the FTS search form | top.tpl
%%b_allgroups%% | href to go to the list of all news groups |
%%begin_dir%% | Starts list of all news groups at this tree level | list.tpl
%%end_dir%% | Ends list of news groups | list.tpl
%%ifdef%%var%% | Conditional inclusion if variable is defined |
%%b_related%% | List of related message | item.tpl
%%b_recent%% | Most recent articles in group | item.tpl
%%b_topgroups%% | Goes to top/main page of dnewsweb | item.tpl
%%b_allgroups%% | Goes to list of all news groups | item.tpl
%%b_follow%% | Goes to form for posting followup messages | item.tpl
%%b_post%% | Post a new message to this group | items.tpl
%%b_searchgrp%% | Search this group for text | items.tpl
%%b_next%% | Next page of this group | items.tpl
%%b_prev%% | Previous page of this group | items.tpl
%%indent%%1%% | Used to define each indent level for threaded display | items.tpl
%%begin_item%% | Starts definition of how each item in dir is displayed | items.tpl
%%end_item%% | Ends definition of each item | items.tpl
%%b_item%% | Goes to a particular item | items.tpl
%%h_subject%% | The subject for a given item | items.tpl
%%h_date%% | The date for a given item | items.tpl
%%h_date_trim%% | The date trimmed to be readable | items.tpl
%%h_from%% | The email address of the person who posted it | items.tpl
%%h_from_trim%% | The email address trimmed to be readable | items.tpl
%%h_lines%% | The number of lines in this message | items.tpl
%%h_content-type%% | The value of the mime content type header | items.tpl
%%h_scores%% | The score an item got in a search |
%%h_subject_30%% | The first 30 characters of the subject, also 40 and 60 | items.tpl
%%summary%% | The summary of a search result |
%%quote_body%% | Used in 'followup' to quote a previous message |
%%show_item%% | Used to show the actual item | item.tpl
%%begin_dir%% | Starts the list of items within a group | items.tpl
%%end_dir%% | Ends item list |
%%indent%% | Define the codes to indent and un indent | items.tpl
%%h_references%% | The references header |
%%h_message-id%% | The message id of a message |
%%h_newsgroups%% | The newsgroups it is posted to |
%%h_group%% | The current group being displayed. |
%%include%%file%% | Reads the named file in, (it cannot contain variables) |

### %%ifgroup%%comp.*%%

The %%ifgroup%%ListOfGroups%% can be used to change the appearance of pages based on the news group being displayed. (e.g. you might want to use a background image of little cars for a newsgroup devoted to cars)

### %%include%%advert.htm%%

Useful for displaying adverts, you would setup a cron job (or program that runs every 10 minutes) to change the advert file, thus displaying a new advert each time someone reads the group. By only changing the advert every 10 minutes you avoid the problem of people turning off the images because they are too slow.

### Table Layout

See the file items_t.tpl (or copy it to items.tpl) to see how a table can be used instead of the standard list format for news items.

### DNEWSWEB.INI settings

Symbol | Example | Explanation
newshost | news.your.domain | The name or number of your DNEWS news server
templates | c:/dnewsweb | The directory where you have copied the *.tpl files
groups | rec.humor, local.chat | Groups that will appear on the top dnewsweb page, this setting is obsolete, use the top.tpl file instead.
post_groups | local.*,rec.humor | List groups that users may post to using dnewsweb
post_users | 232.33.2.1,22.44.* | List IP addresses (not numbers) that may post
debug | True | Enables verbose debug output, (for NetWin use)
pagesize | 60 | Approx. number of items to show per page
allow | comp.lang.*,local.* | Groups to allow users read access too.
content_type | text/html | Used for some web servers which allow fancy features if the content type is changed to something non standard.
log_file | /var/log/dnewsweb.log | Allows you to specify a directory where dnewsweb has 'write' access to create it's log file.
sort_rev | true | Puts new messages at the top of each page instead of the bottom.
wrap_post | 60 | Wraps new posts at 60 characters
wrap_text | 60 | Wraps current existing articles at 60 characters

### Extended Form Feature

With DNEWSWEB you can define a posting form, with required and optional fields, these will be used to force the user into giving you specific information with every post, for example with a newsgroup that is used for technical support you would require that the user tells you what version of the software they are using etc. To try this out start switch to the example forms:

    	copy post_form.tpl post.tpl
    	copy postit_2.tpl postit.tpl

Then try posting a message.

In the post.tpl there are two hidden fields to tell dnewsweb what fields it should look for and which ones are required.

    	<input type=hidden name="required" value="os,version,reg">
    	<input type=hidden name="optional" value="keywords">

And then you can use normal form input fields to ask for the extra data, e.g.:

    	Operating System <input name="os" size=50 > (Required)<br>
    	Software Version <input name="version" size=50 > (Required)<br>
    	Registration Number <input name="reg" size=50 > (Required)<br>
    	Keywords <input name="keywords" size=50 > (Optional)<br>

And finally you need to define a file called postit.tpl which dnews will use to construct the actual layout of the message that will be posted to the news server, e.g.

    	Operating System: %%os%%
    	DNEWS Version: %%version%%
    	Customer Registration Code: %%reg%%
    	Keyword: %%keywords%%

    	%%message%%

### Using frames just like a Windows news reader.

The following example (frame.htm) can be used to run DNEWSWEB inside frames, the http address below needs to be changed to match your server.

    	<html>
    	<head>
    	<Title> DNEWSWEB using frames </title>
    	</head>
    	<frameset rows="50%,50%">
    	<frame src="http://your.web.server/cgi-bin/dnewsweb.exe" name="items">
    	<frame src="empty.htm" name="item">
    	</frameset>
    	</html>

Then in the templates items.tpl and item.tpl define the targets for buttons that should switch forms, for example the 'show item' href in items.tpl must point to the 'item' frame, e.g.

    <li><a href="%%b_item%%" target="item">%%h_subject%% </a> ...<br>

Make similar changes to the href buttons in item.tpl that should jump back to the "items" frame. (see items_f.tpl and item_f.tpl for examples.)

    <td><a href="%%b_related%%" target="items">Related Items</a>
    <td><a href="%%b_recent%%" target="items">Recent Items</a>
    <td><a href="%%b_topgroups%%" target="items">Standard Groups</a>
    <td><a href="%%b_allgroups%%" target="items">All Groups</a>
    <td><a href="%%b_follow%%">Post Followup</a>

This will display the directory of a group in the top window, and the actual items in the bottom window, just like a regular windows based news reader. This is totally implemented via the flexibility of dnewsweb templates.

### DNEWSWEB - FAQ

### HELP, It asked me where to save dnewsweb.exe?

This means you have failed to tell your web server that the directory cgi-bin/ contains CGI programs and not WEB pages. Go back to your web server administration window and look for help on CGI directories. (This is the single most common question we get !!)

### On NT it doesn't work, "DNEWSWEB.EXE - DLL Initialization failed

If dnewsweb doesn't work try running it by hand, e.g.

    	cd cgi-bin
    	./dnewsweb.exe

That may give a better indication of the problem, if you get the DLL Initialization failed error that means the process dnews is running as (your web user code) does not have read access to the winsock dll's to fix this change the security on your winnt and system32 directories.

Apache for NT has a fault with environment variables, basically it doesn't define them and that stops winsock from working, check the apache web site for a patch.

### Do I have to use it with DNEWS?

It will run with other news servers, however it is much faster with DNEWS and the 'list all newsgroups' function will only work with DNEWS. Also the buttons 'Related items' and 'Search' will not work.

### Full text search engine

To enable the full text searching button you need to add

    	search true

to dnewsweb.ini (as well as installing the xmit process to build the indexes, see the manual for details on doing this, NOTE: the FTS database is resource intensive, especially if you try and index your entire news spool, plan on doubling your RAM if you want to set this up)

#### The threading doesn't make sense, is it faulty?

If you are looking at a large news group, then the threading will 'break down' because all you can see are parts of many different threads. You can increase the page size to reduce the extent of this problem. Also news groups which come from mail clients will not thread properly for these use the 'subject' based sorting instead.

### Version DNewsWeb 4.7 Features

- New example templates, giving a uniform appearance, and buttons instead of links for most functions.
- User Authentication for protected / private news groups
- User Authenticatoin for posting (optional) via any POP server
- User Subscribed news groups
- New Search mechanism for finding a specific news group
- Config settings per user, (Sort order, signature, reply-to, full name)
- New sorting orders (Thread, Subject, Date), Use Subject for mailing list gatewayed groups.
- Improved handling of multi part and ecapsulated mime messages.

New ini settings:

WORKAREA d:\dnews\dmailweb
Defaults to the template directory, this directory is used to store information about each user, e.g. groups they are subscribed to, and config settings etc. The data is stored in hashed sub directories, this helps with performance. DNewsWeb MUST have write access to this directory, typically on unix you would need to do this: chown nobody /var/spool/dnewsweb
POP_HOST your.pop.server
Use this to authenticate users via your own specific pop server. If this is not defined then your nntp server will be used to authenticat users. However you should also define tellnews_pass
SORT_ORDER thread | subject | date
Specifies the default sorting order, new items will appear at the top of the list, and related items will appear indented and below the first item in that thread, threading on subject should be used for mailing lists where the references header is not defined correctly.
AUTO_SUBSCRIBE rec.humor,local.chat,comp.lang.c
This list of groups is automatically added to the subscription list of new users. (It does not affect existing users), use this to specify local interest groups
POST_DOMAIN your.domain
Specifies the default domain to use for From headers in messages posted from this system.
POST_REQUIRE_LOGIN true
If specified, then if a non logged in user attempts to post a message, then they will be asked to log in first.
REQUIRE_LOGIN true
If specified, then top.tpl is never shown, instead the login template is shown and no reading or posting is allowed until the user has logged in.
WEB_LOGIN true
If specified, this setting means dnewsweb will treat web authenticated users as being logged in, they will not have to login again. To authenticate a user via the web you must set your web pages to require login on your web server.
POP_AUTHENT true
If set, then the pop host entry field will be displayed when the user is asked to login, and DNewsWeb will authenticate the user via the specified pop server, this is a round about way of checking that the user really exists, it is still not 100% secure but at least stops people pretending to be other than whom they really are.

#### New Templates

login.tpl - Used when a user is asked to login
config.tpl - Used to set/modify user config options
grpsrch.tpl - Used when searching for news groups
user.tpl - Main form used to show a user their subscribed news groups.

### Upgrading DNEWSWEB

Copy DNEWSWEB.exe into your cgi-bin directory.

Particularly with version 4.7 you may want to try out the new templates provided. To do this copy your existing templaets first, then copy *.tpl into your templates directory

Products | Downloads | Prices | Support | Company
--- | --- | --- | --- | ---