"Fossies" - the Fresh Open Source Software Archive

Member "formmail_compat-3.14c1/README" (11 Aug 2004, 26277 Bytes) of package /linux/www/old/formmail_compat-3.14c1.tar.gz:

The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    4 FormMail Version 3.14c1
    5 Copyright 2001-2003 London Perl Mongers, All rights reserved
    9 This script is free software; you are free to redistribute it
   10 and/or modify it under the same terms as Perl itself.
   12 URL
   14 The most up to date version of this script is available from the nms
   15 script archive at  <http://nms-cgi.sourceforge.net/>
   19 formmail is a script which allows you to receive the results of an
   20 HTML form submission via an email message.
   22 FILES
   24 In this distribution, you will find the following files:
   26 FormMail.pl                     - The main Perl script
   27 README                          - This file. Instructions on how to install and use formmail
   28 EXAMPLES                        - Some worked examples of ways to set up formmail
   29 ChangeLog                       - The change history of these files
   30 MANIFEST                        - List of files
   34 There are a number of variables that you can change in FormMail.pl which
   35 alter the way that the program works.
   37 $DEBUGGING          - This should be set to 1 whilst you are installing
   38                       and testing the script. Once the script is live you
   39                       should change it to 0. When set to 1, errors will
   40                       be output to the browser. This is a security risk and
   41                       should not be used when the script is live.
   43 $emulate_matts_code - When this variable is set to a true value (e.g. 1)
   44                       formmail will work in exactly the same way as its
   45                       counterpart at Matt's Script Archive. If it is set
   46                       to a false value (e.g. 0) then more advanced features
   47                       are switched on. We do not recommend changing this
   48                       variable to 1, as the resulting drop in security
   49                       may leave your formmail open to use as a SPAM relay.
   51 $secure             - When this variable is set to a true value (e.g. 1)
   52                       many additional security features are turned on.  We
   53                       do not recommend changing this variable to 0, as the
   54                       resulting drop in security may leave your formmail
   55                       open to use as a SPAM relay.
   57 $allow_empty_ref    - Some web proxies and office firewalls may strip
   58                       certain headers from the HTTP request that is sent
   59                       by a browser.  Among these is the HTTP_REFERER that
   60                       the program uses as an additional check of the
   61                       requests validity - this will cause the program to
   62                       fail with a 'bad referer' message even though the
   63                       configuration seems fine.  In these cases setting
   64                       this variable to 1 will stop the program from
   65                       complaining about requests where no referer header
   66                       was sent while leaving the rest of the security
   67                       features intact.
   69 $max_recipients     - The maximum number of e-mail addresses that any
   70                       single form should be allowed to send copies of the
   71                       e-mail to.  If none of your forms send e-mail to more
   72                       than one recipient, then we recommend that you
   73                       improve the security of FormMail by reducing this
   74                       value to 1.  Setting this variable to 0 removes all
   75                       limits on the number of recipients of each e-mail.
   77 $mailprog           - The system command that the script should invoke to
   78                       send an outgoing email. This should be the full path
   79                       to a program that will read a message from STDIN and
   80                       determine the list of message recipients from the
   81                       message headers. Any switches that the program
   82                       requires should be provided here.
   84                       A $mailprog setting that works for many UNIX-like
   85                       hosts is:
   87                         $mailprog = '/usr/lib/sendmail -oi -t';
   89                       Some other UNIX-like hosts need:
   91                         $mailprog = '/usr/sbin/sendmail -oi -t';
   93                       If your web server lacks a sendmail binary, you can
   94                       use an SMTP relay instead, by setting $mailprog like
   95                       this:
   97                         $mailprog = 'SMTP:mailhost.your.domain';
   99                       You will need to replace mailhost.your.domain with
  100                       the name or IP address of an SMTP server configured
  101                       to relay mail for the web server.
  103                       Your system administrator or hosting provider should
  104                       be able to tell you either the path to sendmail on the
  105                       web server or the name of a host that will act as an
  106                       SMTP relay for the web server.
  108 $postmaster         - The envelope sender address to use for all emails
  109                       sent by the script.  This address will recieve bounce
  110                       messages if any of the emails cannot be delivered.  If
  111                       in doubt, put your own email address here.
  113 @referers           - A list of referring hosts. This should be a list of
  114                       the names or IP addresses of all the systems that
  115                       will host HTML forms that refer to this formmail
  116                       script. Only these hosts will be allowed to use the
  117                       formmail script. This can be used to prevent others
  118                       from linking to FormMail.pl from their own HTML forms.
  120                       If you wish to turn off referer checking so that forms
  121                       that use this FormMail.pl can reside on any web server
  122                       then make this array empty, like this:
  124                         @referers = ();
  126 @allow_mail_to      - A list of the email addresses that formmail can send
  127                       email to. The elements of this list can be either
  128                       simple email addresses (like 'you@your.domain') or
  129                       domain names (like 'your.domain'). If it's a domain
  130                       name then *any* address at the domain will be allowed.
  132                       Example: to allow mail to be sent to 'you@your.domain'
  133                       or any address at the host 'mail.your.domain', you
  134                       would set:
  136                       @allow_mail_to = qw(you@your.domain mail.your.domain);
  138 @recipients         - A list of Perl regular expression patterns that
  139                       determine who the script will allow mail to be sent
  140                       to in addition to those set in @allow_mail_to. This is
  141                       present only for compatibility with the original
  142                       formmail script.  We strongly advise against having
  143                       anything in @recipients as it's easy to make a mistake
  144                       with the regular expression syntax and turn your
  145                       formmail into an open SPAM relay.
  147                       There is an implicit $ at the end of the regular
  148                       expression, but you need to include the ^ if you want
  149                       it anchored at the start.  Note also that since '.' is
  150                       a regular expression metacharacter, you'll need to
  151                       escape it before using it in domain names.
  153                       If that last paragraph makes no sense to you then
  154                       please don't put anything in @recipients, stick to
  155                       using the less error prone @allow_mail_to.
  157 %recipient_alias    - A hash for predefining a list of recipients in the
  158                       script, and then choosing between them using the
  159                       recipient form field, while keeping all the email
  160                       addresses out of the HTML so that they don't get
  161                       collected by address harvesters and sent junk email.
  163                       For example, suppose you have three forms on your
  164                       site, and you want each to submit to a different email
  165                       address and you want to keep the addresses hidden.
  166                       You might set up %recipient_alias like this:
  168                       %recipient_alias = (
  169                         '1' => 'one@your.domain',
  170                         '2' => 'two@your.domain',
  171                         '3' => 'three@your.domain',
  172                       );
  174                       In the HTML form that should submit to the recipient
  175                       'two@your.domain', you would then set the recipient
  176                       with:
  178                       <input type="hidden" name="recipient" value="2" />
  180                       The recipients in %recipient_alias are automatically added
  181                       to the allowed recipients list, so there's no need to list
  182                       them all in @allow_mail_to as well.
  184 @valid_ENV          - A list of all the environment variables that you want
  185                       to be able to include in the email. See 'env_report' below.
  187 $locale             - This determines the language that is used in the date - by
  188                       default this is blank and the language will probably be
  189                       english. The following a list of some possible values,
  190                       however it should be stressed that not all of these will
  191                       be supported on all systems and also this is not a complete
  192                       list:
  194                             Catalan           ca_ES
  195                             Croatian          hr_HR
  196                             Czech             cs_CZ
  197                             Danish            da_DK
  198                             Dutc              nl_NL
  199                             Estonian          et_EE
  200                             Finnish           fi_FI
  201                             French            fr_FR
  202                             Galician          gl_ES
  203                             German            de_DE
  204                             Greek             el_GR
  205                             Hebrew            he_IL
  206                             Hungarian         hu_HU
  207                             Icelandic         is_IS
  208                             Italian           it_IT
  209                             Japanese          ja_JP
  210                             Korean            ko_KR
  211                             Lithuanian        lt_LT
  212                             Norwegian         no_NO
  213                             Polish            pl_PL
  214                             Portuguese        pt_PT
  215                             Romanian          ro_RO
  216                             Russian           ru_RU
  217                             Slovak            sk_SK
  218                             Slovenian         sl_SI
  219                             Spanish           es_ES
  220                             Swedish           sv_SE
  221                             Thai              th_TH
  222                             Turkish           tr_TR
  224 $charset            - The character set to use for output documents.
  226 $date_fmt           - The format that the date will be displayed in. This
  227                       is a string that contains a number of different 'tags'.
  228                       Each tag consists of a % character followed by a letter.
  229                       Each tag represents one way of displaying a particular
  230                       part of the date or time. Here are some common tags:
  232                       %Y - four digit year (2002)
  233                       %y - two digit year (02)
  234                       %m - month of the year (01 to 12)
  235                       %b - short month name (Jan to Dec)
  236                       %B - long month name (January to December)
  237                       %d - day of the month (01 to 31)
  238                       %a - short day name (Sun to Sat)
  239                       %A - long day name (Sunday to Saturday)
  240                       %H - hour in 24 hour clock (00 to 23)
  241                       %I - hour in 12 hour clock (01 to 12)
  242                       %p - AM or PM
  243                       %M - minutes (00 to 59)
  244                       %S - seconds (00 to 59)
  245                       %Z - the name of the local timezone
  247 $style              - This is the URL of a CSS stylesheet which will be
  248                       used for script generated messages.  This should
  249                       probably be the same as the one that you use for all
  250                       the other pages.  This should be a local absolute URI
  251                       fragment.  Set $style to '0' or the emtpy string if
  252                       you don't want to use style sheets.
  254 $no_content         - If this is set to 1 then rather than returning the
  255                       HTML confirmation page or doing a redirect the script
  256                       will output a header that indicates that no content
  257                       will be returned and that the submitted form should
  258                       not be replaced.  This should be used carefully as an
  259                       unwitting visitor may click the submit button several
  260                       times thinking that nothing has happened.
  262 $double_spacing     - If this is set to 1 (as it is by default) then a blank
  263                       line is printed after each form value in the e-mail.
  264                       Change this value to 0 if you want the e-mail to be
  265                       more compact.
  267 $wrap_text          - If this is set to 1 then the content of any long text
  268                       fields will be wrapped at around 72 columns in the
  269                       e-mail which is sent.  The way that this is done is
  270                       controlled by the variable $wrap_style
  272 $wrap_style         - If $wrap_text is set to 1  then
  273                       the text will be wrapped in such a way that the left
  274                       margin of the text is lined up with the beginning of the
  275                       text after the description of the field - that is to
  276                       say it is indented by the length of the field name
  277                       plus 2.  If it is set to 2 then the subsequent lines
  278                       of the text will not be indented at all and will be
  279                       flush with the start of the lines.  The choice of style
  280                       is really a matter of taste although you might find
  281                       that style 1 does not work particularly well if your
  282                       e-mail client uses a proportional font where the spaces
  283                       of the indent might be smaller than the characters in
  284                       the field name.
  286 $address_style      - If this is set to 0 ( or if $emulate_matts_code is set
  287                       to 1 ) then the address constructed for the person
  288                       filling in the form will be of the format 
  289                       "$email ($realname)".  If it is set to 1 then the format
  290                       will be "$realname <$email>".
  292 $send_confirmation_mail - If this flag is set to 1 then an additional email
  293                           will be sent to the person who submitted the
  294                           form.
  296                           CAUTION: with this feature turned on it's
  297                           possible for someone to put someone else's email
  298                           address in the form and submit it 5000 times,
  299                           causing this script to send a flood of email to a
  300                           third party.  This third party is likely to blame
  301                           you for the email flood attack.
  303 $confirmation_text      - The header and body of the confirmation email
  304                           sent to the person who submits the form, if the
  305                           $send_confirmation_mail flag is set. We use a
  306                           Perl 'here document' to allow us to configure it
  307                           as a single block of text in the script. In the
  308                           example below, everything between the lines
  310                             $confirmation_text = <<'END_OF_CONFIRMATION';
  312                           and
  314                           END_OF_CONFIRMATION
  316                           is treated as part of the email. Everything
  317                           before the first blank line is taken as part of
  318                           the email header, and everything after the first
  319                           blank line is the body of the email.
  321     $confirmation_text = <<'END_OF_CONFIRMATION';
  322   From: you@your.com
  323   Subject: form submission
  325   Thankyou for your form submission.
  331 Formmail is installed by copying the file FormMail.pl into your cgi-bin
  332 directory. If you don't know where your cgi-bin directory is, then please
  333 ask your system administrator.
  335 You may need to rename FormMail.pl to FormMail.cgi. Again, your system
  336 administrator will know if this is the case.
  338 You will probably need to turn on execute permissions to the file. You can
  339 do this by running the command "chmod +x FormMail.pl" from your command
  340 line. If you don't have command line access to your web server then there
  341 will probably be an equivalent function in your file transfer program.
  345 To make use of it, you need to write an HTML form that refers to the
  346 FormMail script. Here's an example which will send mail to the address
  347 'feedback@your.domain' when someone submits the form:
  349 <form method="post" action="http://your.domain/cgi-bin/FormMail.pl">
  350   <input type="hidden" name="recipient" value="feedback@your.domain" />
  351   <input type="text" name="feedback" /><br />
  352   Please enter your comments<br />
  353   <input type="submit" />
  354 </form>
  356 See how the hidden 'recipient' input in the example above told formmail who
  357 to send the mail to ? This is how almost all of formmail's configuration
  358 works. Here's the full list of things you can set with hidden form inputs:
  360 recipient               - The email address to which the form submission
  361                           should be sent. If you would like it copied to
  362                           more than one recipient then you can separate
  363                           multiple email addresses with commas, for
  364                           example:
  366                           <input type="hidden" name="recipient"
  367                                 value="you@your.domain,me@your.domain" />
  369                           If you leave the 'recipient' field out of the
  370                           form, formmail will send to the first address
  371                           listed in the @allow_mail_to configuration
  372                           variable (see above).  This allows you to avoid
  373                           putting your email address in the form, which
  374                           might be desirable if you're concerned about
  375                           address harvesters collecting it and sending
  376                           you SPAM. This feature is disabled if the
  377                           $emulate_matts_code configuration variable is
  378                           set to 1.
  380 subject                 - The subject line for the email. For example:
  382                           <input type="hidden" name="subject"
  383                                 value="From the feedback form" />
  385 redirect                - If this value is present it should be a URL, and
  386                           the user will be redirected there after a
  387                           successful form submission.  For example:
  389                           <input type="hidden" name="redirect"
  390                            value="http://www.your.domain/foo.html" />
  392                           If you don't specify a redirect URL then instead
  393                           of redirecting formmail will generate a success
  394                           page telling the user that their submission was
  395                           successful.
  397 bgcolor                 - The background color for the success page.
  399 background              - The URL of the background image for the success
  400                           page.
  402 text_color              - The text color for the success page.
  404 link_color              - The link color for the success page.
  406 vlink_color             - The vlink color for the success page.
  408 alink_color             - The alink color for the success page.
  410 title                   - The title for the success page.
  412 return_link_url         - The target URL for a link at the end of the
  413                           success page. This is normally used to provide
  414                           a link from the success page back to your main
  415                           page or back to the page with the form on. For
  416                           example:
  418                           <input type="hidden" name="return_link_url"
  419                            value="/home.html" />
  421 return_link_title       - The label for the return link.  For example:
  423                           <input type="hidden" name="return_link_title"
  424                            value="Back to my home page" />
  426 sort                    - This sets the order in which the submitted form
  427                           inputs will appear in the email and on the
  428                           success page.  It can be the string 'alphabetic'
  429                           for alphabetic order, or the string "order:"
  430                           followed by a comma separated list of the input
  431                           names, for example:
  433                           <input type="hidden" name="sort"
  434                            value="order:name,email,age,comments" />
  436                           If "order:" is used you must supply the names of
  437                           all of the fields that you want to be in the body of
  438                           the mail message.
  440 print_config            - This is mainly used for debugging, and if set it
  441                           causes formmail to include a dump of the
  442                           specified configuration settings in the email.
  443                           For example:
  445                           <input type="hidden" name="print_config"
  446                            value="title,sort" />
  448                           ... will include whatever values you set for
  449                           'title' and 'sort' (if any) in the email.
  451 required                - This is a list of fields that the user must fill
  452                           in before they submit the form. If they leave
  453                           any of these fields blank then they will be sent
  454                           back to the form to try again.  For example:
  456                           <input type="hidden" name="required"
  457                            value="name,comments" />
  459 missing_fields_redirect - If this is set, it must be a URL, and the user
  460                           will be redirected there if any of the fields
  461                           listed in 'required' are left blank. Use this if
  462                           you want finer control over the the error that
  463                           the user see's if they miss out a field.
  465 env_report              - This is a list of the CGI environment variables
  466                           that should be included in the email.  This is
  467                           useful for recording things like the IP address
  468                           of the user in the email. Any environment
  469                           variables that you want to use in 'env_report' in
  470                           any of your forms will need to be in the
  471                           @valid_ENV configuration variable described
  472                           above.
  474 print_blank_fields      - If this is set then fields that the user left
  475                           blank will be included in the email.  Normally,
  476                           blank fields are suppressed to save space.
  478 As well as all these hidden inputs, there are a couple of non-hidden
  479 inputs which get special treatment:
  481 email    - If one of the things you're asking the user to fill in is their
  482            email address and you call that input 'email', formmail will use
  483            it as the address part of the sender's email address in the
  484            email.
  486 realname - If one of the things you're asking the user to fill in is their
  487            full name and you call that input 'realname', formmail will use
  488            it as the name part of the sender's email address in the email.
  492 * Confusion over the qw operator
  494 In the configuration section at the top of FormMail, we set
  495 the default list of allowed referers with this line of code:
  497    @referers = qw(dave.org.uk localhost);
  499 This use of the qw() operator is one way to write lists of
  500 strings in Perl.  Another way is like this:
  502    @referers = ('dave.org.uk','','localhost');
  504 We prefer the first version because it allows use to leave out
  505 the quote character, but the second version is perfectly valid
  506 and works exactly the same as the qw() version.  You should
  507 use whichever version you feel most comfortable with.  Neither
  508 is better or worse than the other.
  510 What you must not do is try to mix the two, and end up with
  511 something like:
  513    @referers = qw('dave.org.uk','','localhost');
  515 This will not work, and you will see unexpected behavior.  In
  516 the case of @referers, the script will always display a
  517 "bad referer" error page.
  519 * Sendmail switches removed
  521 In the configuration section at the top of FormMail, we set
  522 the default mail program to sendmail with this code:
  524    $mailprog          = '/usr/lib/sendmail -oi -t';
  526 This is actually two different pieces of information; the
  527 location of the sendmail binary (/usr/lib/sendmail) and
  528 the command line switches that must be passed to it in order
  529 for it to read the list of message recipients from the
  530 message header (-oi -t).
  532 If your hosting provider or system administrator tells you that
  533 sendmail is /usr/sbin/sendmail on your system, then you must
  534 change the $mailprog line to:
  536    $mailprog          = '/usr/sbin/sendmail -oi -t';
  538 and not:
  540    $mailprog          = '/usr/sbin/sendmail';
  545 For support of this script please email:
  547   <nms-cgi-support@lists.sourceforge.net>