htnews - E-mail robot for adding news items to a webpage.
SYNOPSIS
htnews [-c configfile]
DESCRIPTION
With htnews you can very easily add news items to your
webpage. Simply send an e-mail to it, and htnews will do
the rest!
Since it is an e-mail robot, you have to create a special
e-mail address and an entry in /etc/aliases. If you do not
use sendmail, refer to the documentation of your
mailserver about sending mail to a program. htnews will
open a pipe, read the incoming message, and start to pro-
cess it.
For example, if your system uses a virtual user table, add
a line like this to /etc/virtusertable :
htnews@foo.bar robot
And add a line like this to /etc/aliases (you will have to
run newaliases afterward) :
robot: "|/usr/sbin/htnews"
Now you can send an e-mail to htnews@foo.bar, and it will
be passed through htnews. The program is highly config-
urable. See below for a detailed description of available
configuration flags.
OPTIONS
-c configfile
Opens the file configfile, instead of the default
/etc/htnews.conf. Since you can have as many
e-mail addresses as you want, you can have multiple
htnews robots running on your system. This is espe-
cially usefull if you are running several virtual
webservers or want to provide htnews for your cus-
tomers as a special service.
-h --help
Print a usage message to standard output then exit
successfully.
-v --version
Print version information to standard output then
exit successfully.
Configuration
You can specify some variables in the configfile, which will
parsed everytime htnews runs.
If you already have some items created, and you have
changed the configuration, then there is a way to force a
refresh of the output, without putting a new item on the
page. Simply send an e-mail to htnews (the address you
have configured) with the keyword refresh in the subject.
htnews will re-read the config-file and recreate the out-
put. Note that ONLY the adminstrator can do this. You can
specify who that is with the "ADMIN" flag in the configu-
ration. See below for details.
The format of a flag is as follows: PARAMETER value. A
parameter and its value must be separated with at least
one blank. You can use tabs or blanks as you choose. If
you do not want to use a parameter, simply leave it, or
you can delete the parameter itself. This is only possible
if the parameter is not required! If a parameter is
required, it is marked with comment. A line beginning with
# is a comment. Comments and blank lines will be ignored.
Configuration Flags
SENDER e-mail_address
Required! This is the e-mail address of htnews
itself. If the program has to send an e-mail mes-
sage (an error or a delivery notification), then
this adress will be used in the From: field of the
mail.
ADMIN e-mail_address
The server administrator, who will get any error
messages. If not specified, a default value will be
used. This default is defined in the source
htnews.cc. It is not required but recommended to
have this address and one person who really reads
mail from this box.
TO e-mail_address
The person who will get delivery notifications. If
not specified, the originator will get the message.
CC e-mail_address
You may send a carbon copy to someone.
Allow_From filename
You may specify a filename, where you have some
e-mail addresses (one per line) of users who are
allowed to use (send mail to) the htnews program.
If not specified, everybody can use it.
Auth_Code string
htnews has a basic authentication mechanism built
new mail. If, for example, the password is
"hucka13", and the subject you want to use is "New
update of program bla bla...", then the line in the
subject field must be "hucka13 New update of pro-
gram bla bla...".
Of course the password will be parsed before html
generation. It is important that you leave one
space after the password. This is required if you
want to use special characters in the subject (like
german "Umlauts"). Most e-mail clients format these
characters, and any blanks will be replaced with
"_". Currently, you cannot use special characters
in the subject field if authentication is turned
on. But I am working on this.
If not specified, authentication is disabled.
TEMPLATE filename
Required! You must specify a file that will be
used as a template for generating the resulting
webpage. This can be a normal html page. At the
position where you want htnews to add the news
item(s), you must have an html comment like this
(on one line): <!htnews at this position items will
be inserted. Note that the output will be written
to a separate file, specified within OUTPUT .
OUTPUT filename
Required! htnews will write its output to this
file. Note that it will be overwritten everytime it
runs, so do not edit this file; edit the template
instead.
STORE filename
Required! htnews will store all old news items in
this file. A new item will be added to the top of
the file. The format of this file is a little spe-
cific, so take a look to your store file to see how
it appears. Note that the "%<htnews" string is a
marker for the end of an item.
UseHTML YES | NO
It is possible to send mime formatted mails to
htnews, which are in the "multipart-alternative"
format, that means such a mail contains the message
in text format and in html format.
With the parameter UseHTML you can choose, which
of the two parts will be used. If set to "NO" or if
blank, the text part will be used.
Please note, that pure html mails are currently
NOT supported!
ITEM_HEAD html-code
"<tr><td>").
ITEM_FOOT html-code
You can specify some html code. htnews has to add
this after inserting the item into the page (e.g.
"</td></tr>").
Field1 ... Field4 fieldname
Required! You can specify the order that some
fields are displayed. One item consists of the fol-
lowing fields: Date, From, Subject, Text. For
example, if you want to have Date displayed first,
then From, and then the Text, you could specify:
Field1 Date
Field2 From
Field Text
You must specify at least ONE field, and it is
required to have the "Text" field.
Mailto YES | NO
You can, if you have coosen to display the From
field, specify how it is to be displayed. If you
set Mailto to "YES", then htnews will create a
"mailto:" link like this:
"<A HREF="mailto:user@foo.bar">Real Name</A>".
If there is no real name found in the from line of
your e-mail, then the e-mail address will be used
instead. If you set this parameter to NO , then
only the name will be displayed.
Since spammers get e-mail addresses especially
from websites (searched by the "mailto:" tag), you
may find it better not to display an e-mail
address. Simply edit the "Field1 ... Field4" to
remove From. That's all. See also SPAMPROTECT .
Date_HEAD and Date_FOOT
Subject_HEAD and Subject_FOOT
From_HEAD and From_FOOT
Text_HEAD and Text_FOOT
You may like to specify what kind of html will be
inserted BEFORE and AFTER a specific field. For
example, if you want to make the Date bold, you
have to specify "<b>" for Date_HEAD and "</b>" for
Date_FOOT.
SPAMPROTECT YES | NO
It is possible to protect your page against spam-
A spammer cannot use such an address. Note that
someone who wants to send an e-mail to an address
prepared this way must edit the address first.
ARCHIV YES | NO
If set to YES , all the following options are
required. This flag turns on the archive mecha-
nisms. htnews will only display the N most recent
messages on the front page. The other (older) ones
will be displayed on another page. Of course you
have to create a link to this page.
Archiv_Output filename
The html page where htnews will put the old news
items. Note: You can use the supplied script
called "htnews-arch.sh", if you want to have ONE
page per month or week. Please read the file
README.htnews-arch.sh for more information on this
topic!
Archiv_Template filename
The template to use for generating the output file.
Again, the template must contain a comment, where
htnews will insert the news items: <!archiv
Note: htnews will use all flags in htnews.conf for
formatting every item field in the archive page.
So, please take care about which template you use
and which flags you use.
Archiv_Store filename
Where old news items are stored. This file will
have the same format as your main storage file.
Archiv_MAXITEMS number
The max N Number of items to be displayed on the
front page. Only the most recent items will be dis-
played. Any older ones will be stored in the
archive.
again required parameters:
""SENDER", "TEMPLATE", "OUTPUT", "STORE", "Field1"
(with minimum one entry and >Text< MUST be there).
Testing
It is possible to test htnews from the command-
line. First, you have to create a "fake mail". It
is a file that should look like this:
---
From: user@foo.bar
To: htnews@foo.bar
Subject: any text here
Any text here. This is the message text.
---
Let's say the filename is "fake.txt". You then
have to issue the following command:
cat fake.txt | htnews -c /where/ever/htnews.conf
Now see what happens.
Debugging
You can edit the Makefile. There is a line #DEBUG =
-Ddebug . Remove the "#", and htnews will display
some information about what's happening during the
processing. Note that you will only see this infor-
mation if you run htnews from the command-line.
Error messages
htnews sends small error messages back to the orig-
inator (or to the person you have specified with
"TO"). There are two kinds of messages. The first
kind is a "delivery" message, sent when everything
works well. If something goes wrong, you will get
an error message. htnews will in most cases detect
and "know" what was wrong, so the error messages
will help you find the mistake (or what ever).
SMTP You may also have problems with your mailserver
configuration. Note that the given installation
procedure is only good for use with sendmail. If
you run another smtp server (like qmail, etc.) you
must refer to the documentation for that server on
how to configure it. If someone has experience with
some other mailservers, please drop me a line, so I
can add some tips for those users.
Attachments
Currently, htnews can NOT handle attachments! If
someone sends an attachment to htnews, it will read
its data content as ascii data and display it as
ascii. If you require this feature, please be
htnews can currently process plain text mail and a
sort of "multipart" message, also known as
html-mail. But only the plain text part of such a
message will be used. The html part will be
ignored, because it might contain something like
"<html>" or "</body>", which will destroy a web-
page!
htnews cannot handle pure html-mails! Also, some
formats like "quoted-printable" and so on, are not
parsed correctly.
I have tested it with Netscape Messenger (both
text and text/html), pine and kmail :-)
Security
Within version 0.6.0 htnews will replace any occurence of
a "`" character with a "'". So it will not be possible to
let htnews execute any command while it calls sendmail for
sending the response message back to the originator. In
earlier releases of htnews, it was possible, if one had
something like `cat /etc/passwd` into the message body.
If you need this "dangerous" character, then you must
edit the source of htnews. But I recommend you, NOT to do
it! It is dangerous and you cannot trust everybody!
Future Plans
I plan to provide a Web interface to htnews. With such an
interface, one could configure the program from his
browser. And I want to implement a system to handle
attachments (i.e. converting images to gif, etc.).
Author and download location
Author Author of htnews is Thomas Linden, tom@daemon.de ,
Munich Germany. Drop me a line if you have any com-
ments or questions.
Download location
http://uss.cybernet-ag.net/~tlinden/htnews.tar.gz
or ftp.daemon.de/pub/utils/htnews.tar.gz
Credits
Very special thanks to Jeff W. Bizzaro, who has corrected
many mistakes in the man-page. With his help, it is "nice"
english. Thanks a lot, Jeff!
Also thanks to all the people, who have reported bugs and
who have requested some additional features.
htnews is published under the terms of the GNU General
Public License. If you are running an operating system
like Linux or BSD, you should already have a local copy of
the document. If not, you can read it at
http://www.gnu.org/
Man(1) output converted with
man2html