Products Downloads Prices Support Company
Index FAQ Configs Feeds In Feeds Out Feeds Out  

DNewsWeb News Server Manual



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 set up on your server as containing CGI programs. You must read your server documentation if you don't currently know how to set up 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 groups whose 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 posts 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 the variables that you can use in these templates

Variable Description Typically 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)  
%%nitems:group.name%% Number of items in the specified group (5.5f2 and later)  
%%lastxhdr:header:group.name%% Header information from last article (5.5f2 and later - see below)  
%%from_down%%
%%from_up%%
Used by page up/down buttons to figure out where the next page up or down should start from, also used to decide if to show a page down button, if undefined then no button need be shown items.tpl
%%if%%xxx%%
%%else%%
%%endif%%
Classic if then else structure, be sure to put these on the beginning of a line, and the 'xxx' must be a template variable, the expression is TRUE if the variable has a non empty value.  
%%spaces%% Is defined as the number of spaces (or images) to use for indenting. Images can be set instead in dnewsweb.ini items.tpl

%%isbinary%%
Is defined if the item is larger than 'isbinary_size' defined in dnewsweb.ini items.tpl

%%sort_order%%
Is set to the current sort order when showing a list of items items.tpl

%%copyright%%
Displays NetWin CopyRight notice.  

%%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.

%%lastxhdr:header:group.name%% (5.5f2 and later)

This variable can be used to display the contents of a header from the last message in a given group. This is useful if you want to display information about the last post. E.g.

%%lastxhdr:date:comp.lang.c%% - Display the time and date of the last post to comp.lang.c
%%lastxhdr:from:comp.lang.c%% - Display the sender of the last post to comp.lang.c

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 its 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.

Alternate template set

ftp://ftp.netwinsite.com/pub/dnews/tpl.zip

dnewsweb_tpl2.gif (9305 bytes)


Version DNewsWeb 4.7 Features

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 authenticate 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.  You may need to add a TELLNEWS_PASS setting (see below) if DNews requires user authentication.
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.  You may need to add a TELLNEWS_PASS setting  (see below) if DNews requires user authentication.
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 roundabout way of checking that the user really exists, it is still not 100% secure but at least stops people pretending to be other than who they really are.
TELLNEWS_PASS xxx
Specifies that access.conf entries apply to DNewsWeb users and user authentication via DNews is possible for protected groups.  Where xxx is the contents of the tellnews.pass file located in the workarea directory as defined in dnews.conf. Ensure your Web server is configured to not permit downloading dnewsweb.ini if it contains you tellnews password.

 

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 templates first, then copy *.tpl into your templates directory


5.2 latest.tpl - Latest Articles Page

The latest.tpl template allows you to present a single web page which displays the latest few articles for several newsgroups you specify with optional links to the newsgroups or articles themselves. 

An example latest.tpl template is provided, to use it you setup a cron/at job to run DNewsWeb like this once a day:

    cd \inetpub\scripts
    .\dnewsweb -latest latest.tpl >d:\toppage.htm

This will generate a web page 'toppage.htm' which you can then use to hook users into your local disucssion groups.  This command is run like this because you may use this page for your top web site page and you don't want that to be running a cgi and reading multiple news groups, in this way it's extremely efficient.

If you require logins on your server then to get the latest process to login with a specific user so it can read the groups etc do this:

Add to latest.tpl at the top:

    %%auth_username%%fred%%

And in access.conf add a line:

    2.2.2.2:read,post:fred:fred:*

And in dnewsweb.ini add

    tellnews_pass xxxx (where 'xxxx' is from the tellnews.pass file in the DNews workarea)
    latest_ip 2.2.2.2

New latest.tpl template variables.

Variable Description
%%groups_to_show%%rec.humor,comp.lang.c%% Specifies a comma seperated list of groups that should have their latest articles displayed.
%%body_lines%%10%% Specifies the maximum number of lines to show of any single article before truncating it.
%%items_per_group%%3%% Specifies how many of the lastest articles in each newsgroup should be displayed.  e.g.  The example specifes that the last three articles in each group should be displayed.
%%begin_list%% Specifies the beginning of the article list.
%%end_list%% Specifies the end of the article list.
%%group_ref%% URL to the current items newsgroup.
%%item_ref%% URL to the current item

 

Item Formatting

If you don't wish to include <pre> tags around %%body%% in the template then you should set 'format_html true' in dnewsweb.ini to ensure articles are formatted correctly.