"Fossies" - the Fresh Open Source Software Archive

Member "formmail_modules-3.14m1/README" (11 Aug 2004, 27648 Bytes) of package /linux/www/old/formmail_modules-3.14m1.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.

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