htnews - E-mail robot for adding news items to a webpage.
htnews [-vh] | [ -a <configfile> | -c <configfile>]
With htnews you can very easily add news items to your
webpage. Simply send an e-mail to it, and htnews will do
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-
For example, if your system uses a virtual user table,
add a line like this to /etc/virtusertable:
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 especially usefull if you are running several
virtual webservers or want to provide htnews for
your customers as a special service.
Run htnews in cron-mode. It will not open a pipe
for reading an email. htnews can be used to
archive the news items of the last month with this
option. Note, that ARCHIV must be enabled (ARCHIV
YES). You have to run it every first day of every
"05 00 1 * * /usr/bin/htnews -a"
You have also to enable the option UseLastMonth !
Print a usage message to standard output then exit
Print version information to standard output then
You can specify some variables in the configfile, which
will parsed everytime htnews runs.
The format of a flag is as follows:
A parameter and its value must be separated with at
least one blank. The value must be defined with- out the <
and > characters used here in this man-page! You can
use tabs or blanks as you choose. If you do not want
to use a parameter, simply leave it blank, 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 com- ment. A line beginning
with # is a comment. Comments and blank lines will be
There are a few different types of parameters. To make
it easier for you to know, what a certain parameter
expects, the type is now included in the name of the
parameter itself. The following types are available:
o Bool: a boolean value, either "YES" or "NO". In
most cases htnews will assume "NO" if nothing is
o File: a file or a path. If it is a file, you
have to specify the whole path.
If it is a PATH, enter it without the leading "/"!
o Html: this must be valid HTML. htnews does not
validate your html-code!
o Value: various values. In most cases only pre-
defined values are allowed.
o Mail: a valid email-address.
Required! This is the e-mail address of htnews
itself. If the pro- gram has to send an e-mail
message (an error or a delivery notifica- tion),
then this adress will be used in the From: field of
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.
The person who will get delivery notifications. If
not specified, the originator will get the mes-
sage. If you set it to /dev/null , no response mes-
sage will be sent.
You may send a carbon copy of response messages to
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 pro-
gram. If not specified, everybody can use it.
htnews has a basic authentication mechanism built
in. If you specify a password here, the user would
have to add the password to the sub- ject line of a
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 program bla bla..."
Of course the password will be parsed out 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 spe- cial char-
acters in the subject field if authentication is
turned on. But I am working on this.
If not specified, authentication is disabled.
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
(on one line):
At this position the items will be inserted. Note
that the output will be written to a separate file,
specified within OUTPUT.
Required! htnews will write its output to this
file. Note that it will be overwritten every-
time it runs, so do not edit this file; edit the
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.
You may take a look to the section Storage file
Bool_Use_Html 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 this parameter 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: htnews currently does not understand
pure html mails!
You can specify some html code. htnews will add
this before inserting the whole item into the page
You can specify some html code. htnews will add
this after insert- ing the item into the page (e.g.
Value_Field1 ... Value_Field4 <fieldname>
Required! You can specify, in which order each item
of your message will be displayed to the output.
Each field consists either on one item. The fol-
For example, if you want to have Date displayed
first, then From, and then the Text, you could
You must specify at least ONE field, and it is required to
have the "Text" field!
Bool_Create_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:firstname.lastname@example.org">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 param- eter 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 dis- play an e-mail
address. Simply edit the "Field1 ... Field4"
to remove From. That's all. See also
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 Html_Date_Head and
"</b>" for Html_Date_Foot.
It is possible to protect your page against
spammers. htnews can insert blanks into the dis-
played address (i.e. "user @ foo.bar"). 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.
Bool_Make_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.
The html page where htnews will put the old news
items. If you want to store older items in a sepa-
rate file every month, you can run htnews from a
cronjob! If you do this, you must have the follow-
ing HTML-comment in your archiv-template:
htnews will insert at this position several links
to the monthly pages.
The template to use for generating the output file.
Again, the template must contain a comment,
where htnews will insert the news items:
Note: htnews will use all flags in htnews.conf for format-
ting every item field in the archive page. So, please take
care about which template you use and which flags you
Where old news items are stored. This file will
have the same for- mat as your main storage file.
The max n Number of items to be displayed on the
front page. Only the most recent items will
be displayed. Any older ones will be stored in the
The names of months htnews should use for display-
ing at the archiv output. It will assign the names
to a list starting at 1 and ending at 12. Therefore
the first name has to be the name of the first
month in a year, in english 'january'.
Bool_Use_Last_Month YES | NO
Usefull in for arching from a cronjob. You can run
it every 1st day of a month, if set to YES, htnews
will use the last month (month = currentmonth -
If set to NO or if it is not specified htnews will
use the name of the current month for archiv nam-
The monthly generated page can have a title with
the name of the month and the year. The title of
the archiv page can be customized: <h1>October
1999</h1>. The title will be inserted if htnews
finds the following comment in the file
This is usefull, if your archiv-directory differs
from your main html directory. You can leave it
blank if the archives are in the same directory
like the main page. This has to be a valid HTTP
URL (without filename!), i.e.:
"../news/archived/" The leading / is required!
Controls how the link to a certain archiv should
look. Possible values are:
TEXT - creates <a href="Nov_1999.html">November
using the the name of the month you specified
DIGIT - creates <a href="Nov_1999.html">11.1999</a>
C_TEXT - creates the same result as TEXT using
Html_Archiv_Link_Left and Html_Archiv_Link_Foot -
see below for details!
C_DIGIT - the same as C_TEXT using 11.1999 instead
The Default value is TEXT.
You can manipulate the look of the link to the
monthly pages. You need to specify either C_TEXT or
C_DIGIT if you want to use it! For example you can
define a custom font for the link or the like.
The template to use for generating the monthly
output of the cron- job (htnews -a config-file).
This template can contain a HTML-comment
<!--title-->. If this comment exists, htnews
will insert at this position the title of this
page. The title will look like this: "May 1999".
You can for- mat this title with the two
parameters Archiv_Title_Head and Archiv_Title_Foot
The complete unix-PATH to the directory, where
htnews can store the various monthly web-pages.
htnews must have write permissions to this direc-
tory. Note, that the links to these files will be
without any PATH!
So, it would be a very good idea, if this output
directory is the same as the root directory of the
Where should the archiv history be saved to. (a
list of filenames).
htnews will add a link to the archiv page to the
monthly page. With these parameters you can specify
some HTML-formatting, if you wish. It will be used
before or after the completed A tag.
Bool_Look_Detail YES | NO
Enable the "detail"-feature. htnews can create a
separate web-page for every news item with details
(like "read more..."). If enabled, all Detail_*
parameters must be configured! The program will
look for the first occurence of a HTML-comment
within the incoming mail:
separate new file.
The template to use for generating the detail-page.
It can also contain a HTML-comment:
, if it occurs, htnews will insert the subject at
The path to the output directory containing the
detailpages, it should be the same where the other
files are located. htnews will generate for every
news item (when the mail contained the detail-com-
ment) a new file. It uses the MessageID to create
a unique filename! Any occurence of "@", "$",
"%" or "*" will be replaced with "O".
Html_Detail_Link <link name>
How the link on the news item to the detail-page
should be named, i.e. "read more...".
If you specify Subject here, then the subject of
the item itself will be the link to the detail-
Html_Detail_URL <valid URL>
If you specify an URL here it will be used for the
detail-link. If you use nothing here, simply a
link the detail-file will be cre- ated. Note, that
DetailPATH and DetailURL must match.
This URL has to start with http:// or https:/. It
is not required to append a / to the URL, it will
be done automatically, if it is not there.
You can format the link to the detail-page, if you
You can use the supplied sample installation as a
basis for your own installation, also take a look
to the running samplepage at http://htnews.org.
htnews will send you back an email, if one or more param-
eters are incor- rect or something else is wrong. You can
use the script sanity.check (see below) to check if your
Insert a new news-item
You can insert a new item by sending an eamil to
the robot. The subject- line will be the title of
the item and the body of the message will be the
item itself. If the message becomes too
long, you can use the "Detail"-Feature:
Write a short description and on a line itself the
fol- lowing "tag": and then the complete message.
If this feature is turned on, htnews will create
a separate page with the text after the tag. You
can configure, how it will look, see above.
Updating the webpages
If you already have some items created, and you
have changed the configu- ration, 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 con-
figured) with the keyword refresh in the subject.
htnews will re-read the config-file and recreate
the output. Note that ONLY the adminstrator
can do this. You can specify who that is with the
"ADMIN" flag in the configuration. See above for
Currently there is no comfortable way to remove an
item. You have to edit the storage file. Read
below about the format of this file. You have to
delete all lines begining from "%From:" until
"%htnews_end" per item. After that you have to
refresh the output.
It is possible to test htnews from the command-
line. The source archiv contains a file named
fake.mail. This is a complete mail (header and
messagebody), the body is in MIME format and it
is quoted-printable formatted. Issue the following
cat fake.mail | htnews -c /where/ever/htnews.conf
Now see what happens.
You can view debugging output, if you invoke htnews
from the com- mandline. You have to compile it
with --enable-debugging. Additional you can use
README.sanity_check for more informations!
htnews sends small error messages back to the orig-
inator (or to the person you have specified with
"Mail_Rcpt"). There are two kinds of mes- sages.
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
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.
Additional please read the FAQ, perhaps there are
updated informations about other mailservers.
Currently, htnews can NOT handle attachments! If someone
sends an attach- ment to htnews, it will read its data
content as ascii data and display it as ascii. If you
require this feature, please be patient; I am working on
SUPPORTED MESSAGE FORMATS
htnews can currently process plain text mail and a sort of
MIME messages (multipart/alternative), also known as
html-mail. htnews "understands" two MIME-types:
text/plain and text/html.
You can choose, which one of these you want to use. If
you use the html-part, any occurence of a <body> -or
<html>-tag will be removed, because it may "destroy" the
ouptut, which is HTML and which con- tains already these
htnews is also capable of parsing quoted-printable e-
mails. If a message is quoted-printable formatted, then it
will be changed to html. A "=3D" will be changed to
"=", a "=20" to " "(blank), if after a "=20" a newline
follows it will be removed, and a "=" foolowed by a
newline will be replaced by a "" (nothing) without the
will be changed to:
<font size=2 face=arial>
htnews cannot handle pure html-mails! Pure HTML-Mails
will be handeled like plain textmails!
I have tested it with Netscape Messenger (both text and
text/html), Out- look Express, Outlook '97, pine, IMP
and kmail :-)
STORAGE FILE FORMAT
Every message will be stored in a plain textfile in an
certain format. Perhaps sometimes I will move to the mbox
How it looks:
%From: T.L. <email@example.com>
%Date: Sat Nov 6 21:31:51 1999
%Message: this is a testmessage!
Newer items will be stored on top of the file. This method
enables you to change the looking of the output every
time you like. Once you changed the look (via templates
and/or via the configuration) send a refresh message to
the robot - that's all.
htnews will replace any occurence of a "`" character
with a "'". So it will not be possible to let htnews exe-
cute any command while it calls sendmail for sending
the response message back to the originator. In ear- lier
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!
The followong features are planed for future versions:
o A webinterface to htnews. Both for configuring and
for using the program.
which points to the various postings instead a big
o automatically cutting signatures
o PGP capabilities
o newsletter functionality
Any help would be very appreciated!
Send bug reports and fixes to: firstname.lastname@example.org
o sendmail(1): read here to learn more about aliases
and mail processing.
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! ZeimoT made the logo of
htnews. Thank you very much! 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