Download Documentation FAQ Related


htnews Manpage

       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
       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"


       -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 especially usefull if you  are  running  several
              virtual  webservers or want to  provide  htnews for
              your customers as a special service.

       -a <configfile>
              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 !
              (see below).

       -h, --help

              Print a usage message to standard output then  exit

              Print  version  information to standard output then
              exit successfully.


       You  can  specify  some variables in the configfile, which
       will parsed everytime htnews runs.
       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 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
              set (empty).

       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.

Configuration Flags

       Mail_Sender <e-mail_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 mail.

              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 <e-mail_address>

              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.

       Mail_Cc <e-mail_address>
              You  may send a carbon copy of response messages to

       File_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  pro-
              gram. If not specified, everybody can use it.

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

       File_Index_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
              (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.

       File_Index_Output <filename>

              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
              template instead.

       File_Index_Storage <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.
              You  may  take  a  look to the section Storage file

              format below.

       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!

       Html_Item_Head <html-code>

              You can specify some html  code.  htnews  will  add
              this  before inserting the whole item into the page
              (e.g. "<tr><td>").

       Html_Item_Foot <html-code>
              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
              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 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 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
              Bool_Spam_Protect .

       Html_Date_Head <html-code>

       Html_Date_Foot <html-code>

       Html_Subject_Head <html-code>

       Html_Subject_Foot <html-code>

       Html_From_Head <html-code>

       Html_From_Foot <html-code>

       Html_Text_Head <html-code>

       Html_Text_Foot <html-code>
              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.

       File_Archiv_Output <filename>
              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.

       File_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:

       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

       File_Archiv_Storage <filename>

              Where   old  news  items are stored. This file will
              have the same for- mat as your main storage file.

       Value_Archiv_Maxitems <number>
              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-

       Html_Archiv_Title_Head <html-code>

       Html_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):

       Html_Archiv_URL <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 <value>

              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
              in List_Archiv_Months.
              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
              of  "November1999".
              The Default value is TEXT.

       Html_Archiv_Link_Right <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 <filename>
              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

              (see below).

       File_Cron_Output_Path <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 <filename>

              Where should the archiv history  be  saved  to.  (a
              list of filenames).

       Html_Archiv_Link_Head <html-code>

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

       File_Detail_Template <filename>

              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
              this position!

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

       Html_Detail_Head <html-code>

       Html_Detail_Foot <html-code>
              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

       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.


              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!

       Error messages

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


       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
       <font size=3D2=20

       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 :-)


       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. <tom@daemon.de>
       %Subject:  NEW!
       %Date: Sat Nov  6 21:31:51 1999
       %Message-ID: 99911062031.VAA24254
       %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: tom@daemon.de


       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



Man(1) output converted with man2html