htnews - E-mail robot for adding news items to a webpage.
SYNOPSIS
htnews [-c | -C | -a | -A 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 | -C configfile
Opens the file configfile, instead of the default
/etc/htnews.conf. If you are using -c htnews will
look for old-style configuration parameters. If you
are using -C, it will use the new style. 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 run-
ning several virtual webservers or want to provide
htnews for your customers as a special service.
-a | -A configfile
will use the new style. 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 month:
05 00 1 * * /usr/bin/htnews -a
You have also to enable the option UseLastMonth !
(see below).
-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.
Please be aware of the config format you want to
use! Currently there are two formats available, the
new and the old style format. This is because the
format will completely change within version 0.7.
To make the migration process easier for you,
htnews 0.6.9 supports both formats. In the parame-
ter description below you will find the new parame-
ters first and the second parameters in () are the
old ones.
The format of a flag is as follows: PARAMETER <value>. A
parameter and its value must be separated with at least
one blank. The value must be defined without 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 parame-
ter, simply leave it blank, or you can delete the parame-
ter 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.
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: Bool, File,
Html, Value, Mail
Configuration Flags
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.
Mail_Admin (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.
Mail_Rcpt (TOsmtp) <e-mail_address>
The person who will get delivery notifications. If
not specified, the originator will get the message.
If you set it to /dev/null , no response message
will be sent.
Mail_Cc (CC) <e-mail_address>
You may send a carbon copy to someone.
File_Allow_From (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.
Value_Auth_Code (Auth_Code) <cipher>
htnews has a basic authentication mechanism built
in. If you specify a password here, the user would
have to add the password to the subject 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 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.
File_Index_Template (TEMPLATE) <filename>
Required! You must specify a file that will be
used as a template for generating the resulting
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
.
File_Index_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.
File_Index_Storage (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.
Bool_Use_Html (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.
Bool_Htmlize_Crlf (CRLF) YES|NO
htnews can, if you want,
"\n"......"<br>"
"\t"......8 x " "
more than one " " with n x " "
This is useful, if the postings should be dis-
played like the autor wrote them.
Note, that it will be turned off, if the message
is already in HTML-format and UseHTML is turned on!
Html_Item_Head (ITEM_HEAD) <html-code>
You can specify some html code. htnews has to add
this before inserting the item into the page (e.g.
"<tr><td>").
Html_Item_Foot (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>").
Value_Field1 ... Value_Field4 (Field1 ... Field4) <field-
name>
Required! You can specify the order that some
example, if you want to have Date displayed first,
then From, and then the Text, you could specify:
Value_Field1 date
Value_Field2 From
Value_Field3 Text
You must specify at least ONE field, and it is
required to have the "Text" field.
Bool_Create_Mailto (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 Bool_Spam_Pro-
tect(SPAMPROTECT) .
Html_Date_Head and Html_Date_Foot (Date_HEAD, Date_FOOT)
Html_Subject_Head and Html_Subject_Foot (Subject_HEAD,
Sub- ject_FOOT)
Html_From_Head and Html_From_Foot (From_HEAD, From_FOOT)
Html_Text_Head and Html_Text_Foot (Text_HEAD, 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.
Bool_Spam_Protect (SPAMPROTECT) YES | NO
It is possible to protect your page against spam-
mers. htnews can insert blanks into the displayed
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 (ARCHIV) YES | NO
If set to YES , all the following options are
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.
File_Archiv_Output (Archiv_Output) <filename>
The html page where htnews will put the old news
items.
If you want to store older items in a separate
file every month, you can run htnews from a cron-
job! If you di this, you must have the following
HTML-comment in your archiv-template: <!--cron--> .
htnews will insert at this position several links
to the monthly pages.
File_Archiv_Template (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.
File_Archiv_Storage (Archiv_Store) <filename>
Where old news items are stored. This file will
have the same format as your main storage file.
Value_Archiv_Maxitems (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.
List_Archiv_Months (Archiv_Months) <comma-separated
list of months>
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 (UseLastMonth) YES | NO
Usefull in for arching from a cronjob. You can run
If set to NO or if it is not specified htnews will
use the name of the current month for archiv nam-
ing.
Html_Archiv_Title_Head and
Html_Archiv_Title_Foot (Archiv_Title_Head,
Archiv_Title_Foot) <html-code>
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
File_Cron_Template (Cron_TEMPL): <!--title-->.
Html_Archiv_URL (ArchivURL) <html-code>
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!
Value_Archiv_Link_Type (Archiv_LinkType) <value>
Controls how the link to a certain archiv should
looks. Possible values are:
"TEXT" - creates <a href="Nov_1999.html">November
1999</a> using the the name of the month you speci-
fied in "List_Archiv_Months (Archiv_Months)".
"DIGIT" - creates <a
href="Nov_1999.html">11.1999</a>
"C_TEXT" - (Custom Text), creates the same as TEXT
using "Html_Archiv_Link_Left and
Html_Archiv_Link_Foot (Archiv_LinkHead,
Archiv_LinkFoot)" - see below for details!
"C_DIGIT" - the same as C_TEXT using 11.1999
instead of "November 1999".
The Default value is TEXT.
Html_Archiv_Link_Left and Html_Archiv_Link_Foot
(Archiv_LinkHead, Archiv_LinkFoot) <html-code>
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.
File_Cron_Template (Cron_TEMPL) <filename>
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 (see
below).
File_Cron_Output_Path (Cron_OUTPATH) <path>
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
other HTML-pages.
File_Cron_History (Cron_Hist) <filename>
Where should the archiv history be saved to. (a
list of filenames).
Html_Archiv_Link_Head and Html_Archiv_Link_Foot
(Cron_HEAD, Cron_FOOT) <html-code>
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.
Bool_Look_Detail (LookDetail) 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 con-
figured!
The program will look for the first occurence of a
HTML-comment within the incoming mail:
<!--detail--> , every stuff after this line will be
passed to a separate new file.
File_Detail_Template (Detail_TEMPL) <filename>
<!--title-->, if it occurs, htnews will insert the
subject at this position!
File_Detail_Output_Path (Detail_PATH) <PATH>
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-comment) a new file. It
uses the MessageID to create a unique filename! Any
occurence of "@", "$", "%" or "*" will be replaced
with "O".
Html_Detail_Link (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-page.
Html_Detail_URL (DetailURL) <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 created. Note, that Detail-
PATH 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.
Html_Detail_Head and Html_Detail_Foot (Detail_HEAD,
Detail_FOOT) <html-code>
You can format the link to the detail-page, if you
wish.
Hints
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 incorrect or something else is wrong. You can
use the script sanity.check (see below) to check if your
configuration is correct.
Again, use -C or -A if you want to use the new format and
htnews will not be able to read it! Therefore migrate now!
Usage
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"-Fea-
ture: Write a short description and on a line itself the
following "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 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 above for details.
Removing item(s)
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.
Trouble Shooting
Testing
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 mes-
sagebody), the body is in MIME format and it is
quoted-printable formatted.
Issue the following command:
cat fake.mail | htnews -c /where/ever/htnews.conf
You can view debugging output, if you invoke htnews
from the commandline. You have to compile it with
--enable-debugging.
Additional you can use the provided script san-
ity_check to force a check on you actual configura-
tion. Refer to the file README.sanity_check for
more informations!
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 con-
tent as ascii data and display it as ascii. If you require
this feature, please be patient; I am working on this.
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 contains
already these tags.
htnews is also capable of parsing quoted-printable
e-mails. If a message is quoted-printable formatted, then
follows it will be removed, and a "=" foolowed by a new-
line will be replaced by a "" (nothing) without the new-
line.
Example:
<font size=3D2=20
face=3Darial>
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), Outlook Express, Outlook '97, pine 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
format...
How it looks:
%From: Thomas Linden <tom@daemon.de>
%Subject: NEW!
%Date: Sat Nov 6 21:31:51 1999
%Message-ID: 99911062031.VAA24254
%Message: this is a testmessage!
%htnews_end
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.
Security
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!
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/
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!
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.
Copyright
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