|
||||||||
Soupermail Frequently Asked QuestionsHere are some questions that I guess I'd want to ask, and a couple of other people have asked about. If you have any other questions (and even more usefully, answers), please let me know. Installation Problems
Soupermail runs, but...
Features
General
Installation ProblemsThe Soupermail zip or tar files are corrupt when I downloadIf you can't download the files, mail me and I'll forward them to you. I'm getting a 500 Server Error, Malformed Header Error or Internal Server Error back when I run Soupermail. What's happening?Errors in the 500-600 range for webservers mean that the script or server is misbehaving. If other CGI scripts are working on your server, this probably means Soupermail has been misconfigured. Here's a list of things to check for which should help you figure out what's going on (if you mail me about 500 errors, please, please, please try and look for this information first).
If you are still in the dark, mail me, and I'll try and help, but please provide the following information:
If you do not know the answers to any of the above question, then FIND OUT from someone who does. Public domain CGI scripts can open horrible security holes on your servers - always try and be 100% sure about what you're installing. I'm getting a 405 Server Error back when I run Soupermail. What's happening?405 errors are caused by trying to run Soupermail from a directory that is not configured to run CGI scripts. This is a problem with YOUR webserver configuration - not Soupermail. If you are using Apache, you should ensure the directory is configured as a script directory. If you are using IIS, you should ensure the directory running Soupermail has script execute rights enabled. If the above doesn't make sense, contact your server's support staff, who should give you information specific to your server. If you are the support staff for your server - READ YOUR WEBSERVER'S MANUAL (which you've already done ;-?). I cannot provide help with 405 errors since this is down to your webserver's configuration - the only way I can is if you provide me with remote access to your server. No matter what I do, I always get a "Cannot find config file" errorFirstly, have you read AND followed the installation instructions for
Soupermail that come in the Secondly, are you specifying a config file to use? Remember, every
form that Soupermail controls needs a config file. This is simply a text
file that usually sits in the same place as your form, and contains
Soupermail commands. You usually tell Soupermail where to find your
config file by setting the 90% of errors are due to Under some UNIX webservers, setting
The install helper is a first shot at trying to make it easier to determine what settings you need - however, its not guaranteed to work on all systems.. if it does give you problems, please let me know (providing as much information as possible too). The installer tries to check for common files and paths, and should be your first step in configuring Soupermail. If you're running under a cgi-wrapped environment, you will probably have to use absolute path names to config files (ie. paths that start with a / character) rather than relative paths. I'm getting a "Not explicitly allowed to read files in the given directory" Why?This error is created when Soupermail is run in paranoid mode. In this mode, Soupermail will not read any file from a directory unless the directory contains a file called soupermail.allow. The soupermail.allow file does not need to contain anything, it just needs to exist. I get an "Unrecognised config line 'my $relVersion" errorThis is probably down to your server running scripts under a cgiwrapped environment. Make sure that you are setting SoupermailConf in your form. How do I install MIME::Lite?Download the latest MIME::Lite module from CPAN and extract the MIME directory into your cgi-bin directory (or wherever soupermail.pl is installed). The following answer shows a resulting directory structure. Remember that the directories and files are Case Sensitive! Haveing Mime/lite.pm is incorrect - it has to be MIME/Lite.pm. How do I install libnet/Net::SMTP on NT?Read the last section of the install.txt document. If you follow the third method of installing remember to keep the directory structure that the zip file contains... this is IMPORTANT! The following is an example directory structure showing how the files can be installed:
c:\inetpub\
|
|--- wwwroot\ <-------------------- this is $serverRoot
| |
| `--- souperfinder.html
|
|
`--- cgi-bin\
|
|--- soupermail.pl
|
|
|--- MIME\
| |
| `--- Lite.pm
|
|
`--- Net\
|
`--- SMTP.pm
I've found that libnet does not always install perfectly first time - you may have to try installing it a couple of times before things pan out. Ahh, the joys of NT. How do I install DBI?To install and use Soupermail's database support, you will need to install the DBI module (all other Soupermail functions work fine without it though). It is very unlikely that you'll be able to install the DBI module in your cgi-bin area - generally, it has to be installed by the server's administrator. In addition to the DBI module, you'll also need a database driver module (DBD), specific to your database. Once again, these modules will probably have to be installed by your server's administrator. You should note that the DBD driver will need to support Placeholders and Bind Values. Your server's support staff will be able to give you more information about the modules installed on the server and their capabilities. If you can't install DBI, don't worry, as Soupermail will run perfectly well without it - it just means Soupermail's SQL functions won't work. The example files are full of gibberish when I view them in notepadThese are just UNIX linefeeds which confuse the hell out of notepad. Use wordpad instead and all should be well. (Actually, if you're sick in the head like me, you can use the Windows port of vim :) Where are the example filesGo to the download page to get them. They are well worth the effort. You can also view a subset online. Soupermail runs, but...Soupermail won't send emailIf you are on an NT box:
If you are on UNIX:
Whatever operating system you are using, LOOK AT YOUR MAILSERVER'S LOG FILES. I cannot stress how useful log files are for fixing things. If you do not use log files, you must like pain. How can I set the From: address in emails?It is VITALLY important to remember that Soupermail uses the field called "Email" (with a capital E) in your form to determine who is sending the form. You MUST use this field if you want emails to the mailto: address to have a proper From: address. This field is also used to determine who to send the sender emails to. Can it use blat.exe or sendmail.exe to send email?Apparently, Sendmail for Windows from IndigoSTAR does work with Soupermail, though I have only heard this - not tried it myself. YMMV with other sendmail ports. As for blat, it requires an SMTP server to work anyway, so you should be able to configure Soupermail using that server. Mail is being sent out from a strange email addressIf you are getting email's being sent from an address like
nobody@myhost.com its likely you're using sendmail. There's no
work around for this, its a behavior of sendmail (unless you can muck with
your sendmail configuration). The best thing to do is ensure you've set a
Soupermail won't upload any filesTwo things to remember when using Soupermail for uploads:
If you don't have the things listed above done, all your form will return is the pathname to the file selected, and not the actual file. For more information on how browsers handle file uploads, look at RFC 1867. If Soupermail doesn't send any email when you send attachments, but
usually works, its possible there's a missing feature in your Perl
port where the operators -T and -B are not implemented on FileHandles.
Certainly, FreeBSD users will run into this. The solution is to change the
value of the Soupermail won't upload large filesThere's an inbuilt limit of 100k allowed for uploaded files. I've done this
to stop potential denial of service attacks where soupermail spends a lot of
time encoding large uploads as attachments. If you know that your users are
a sensible bunch, and that your server can handle the load, change the setting
of You should also check that the server has an up to date copy of CGI.pm installed. There's an open bug (#105964) about Soupermail's MIME encoding of binary files. It is proving tricky to trace down, as it seems server dependent. Any help in squashing this bug would be appreciated. ReturnToSender isn't workingFirstly, have you checked that you have a form field called Email that starts with a CAPITAL 'E'? This field is assumed to be the email address of the person sending the form. Soupermail isn't psychic, and can't figure out which one of your own field names is meant to be their email address, so please use the one provided for you. Also see How can I set the From: address in emails?. Soupermail can't find the config file when using some browsersSome browsers don't set the Referrer HTTP header properly. If this happens, then Soupermail can't figure out where to base relative paths to the config files from. The way to get around this is to use absolute paths from the webserver's root to the config files. eg. The choice of relative verses absolute paths is yours. For absolute safety, use absolute paths, because that way you don't depend on a browser sending the referer field (eg. some internet content filters will block this being sent - some proxy servers may also do this). My configuration file is not workingGood question, but I don't know :) The best thing to do is look at your configuration file line by line, adding a single line a step of the time, and making sure its behaving as it should be. I know its time consuming and all, but I'm not guaranteed to answer questions because:
If you're totally stumped, you could mail me, with the URLs for the form, the configuration file and what operating system and web server you're running. Including a debug file will also help. Remember, the more information you provide, the more likely you'll get an answer. I may or may not reply and have a look and give you some ideas, but like it says in the GPL, there's no promise that this software does what it should. Sorry. If you are desperately stuck, sending me beer and/or money may improve chances of me doing stuff. Why are my graphics and links broken in templates?When you have relative links in a page (a relative link is a link that doesn't start with '/' or 'http://') your web browser guesses the correct location of the links based on the page you're at. However, if your page is generated by a template, then the browser thinks you're in something like the /cgi-bin/ directory... not very helpful. The best way to get round this is to add a BASE element in your HTML templates which will let the browser know where it should generate links from. The easiest thing to do is add this in the <HEAD> section of your template: <base href="<output name="http_referer">"> This has the effect of saying all the links on the page should be made relative to the location of the original form. There are some subtleties when making multipart forms and the best way to find out about them is to look at the examples supplied with Soupermail. Can I use PGP for Windows NT?Under UNIX, there's a PGP command line utility (pgpe) which does the encryption. However, under NT, PGP 5 is GUI based only. PGP 6.5.1 brings back the command line, but I haven't got it to work in conjunction with Soupermail yet. All is not lost though, as you can use the DOS version of PGP 5 under NT. A couple of caveats;
It is possible to use The GNU Privacy Guard compiled for Windows NT, but as of writing, this is in alpha release stage. Can I use GPG on Solaris?On things like Solaris, where there's no random number device, you may or may not be able to get GPG running. If you have managed to get it working, especially if you're using egd, please let me know. Better still, if you have a spare Sparc box kicking around, why not send it to me so I can develop first hand :) What filename extensions should I use?If you look at the example files, you will see that I use a number of filename extentions for various files. As a general rule of thumb, filename extensions for your forms and config files are unimportant to Soupermail. However, here are some issues to consider:
* <rant> FeaturesHow do I customise things?OK, take a deep breath, and repeat "Customising Soupermail is done with templates" a few times. EVERYTHING that Soupermail outputs (emails, HTML, XML, PDFs, etc) is customised by using templates, almost nothing is fixed in the code, and the config file simply controls the logical flow. Really look at the examples and the manual and see how templates are used. So, to change the formatting of the email that gets sent out, you would make a template for your email, and specify it with a mailtemplate:the config command. You should try out the template tutorial for more information. How do I use the installer?The installer is a CGI designed to help you get all the settings for Soupermail correct. To use it, place soupermail.pl and souperinstall.pl in your CGI area, and then place souperfinder.html in your website. View souperfinder.html in a web browser, and follow the instructions in it. If all goes well, the installer will detect all of the settings for your box, and return a page that lets you create a customised soupermail.pl for your site. Why do you need a configuration file?Most form->email handling scripts are controlled by fields hidden in the form. However, because of this, people can call the script from anywhere on the web, using their own forms. Obviously, this sort of freeloading isn't very polite, and needing to use a configuration file stops people doing this, because it means they must have write access to the webserver. There is also the issue of the order that configuration statements are run. Form elements from a browser can be read by a CGI in any order, so the idea of an ordered set of rules goes haywire. By placing the rules in a file, the order that they are run is precisely defined. You should try the Config file tutorial if you want to learn more. What is paranoid mode?Soupermail can read any file from your website and use it as a template. Usually, you control which files are read through your config files. However, if someone else can write a config file to your server, they could use it to read sesnitive files from your server. In normal situations, nobody else can write files to your website, but sometimes, with things like bulletin boards and forums, other people can create files on your server. Paranoid mode is used as a saftey feature in Soupermail, preventing it from reading files from directories unless you have allowed Soupermail to read from the directory. To do this, you need to create a file called soupermail.allow and place it in the directories that you want Soupermail to read from. Can I use Soupermail with mod_perl?No. At the moment, Soupermail defines a bunch of globals, and calls explicit
Does Soupermail run on XYZ operating system?Maybe. I've personally tested under Linux, Solaris, SunOS, OpenBSD and Windows NT 4. Other folk have reported success on BSDi, FreeBSD and IRIX. Your mileage may vary with others. Please let me know if you have any success or failure with other OSs. You probably won't have any luck running Soupermail on Windows 95/98/Me. However, this is a good thing as, IMHO, they are not really sensible operating systems for webservers. Can Soupermail write a form's contents to a database?Yes! Soupermail uses Perl's DBI/DBD database interface to run SQL commands at databases. An example of a small Soupermail database application is included with the example files. Can Soupermail be used with Cgiwrap?Yes, probably. You will have to specify the path to your config files with absolute paths though. eg: <input type="hidden" name="SoupermailConf" value="basic.con"> probably work work. Use: <input type="hidden" name="SoupermailConf" value="/examples/basic.con"> instead. There may be issues with getting PGP working correctly in cgiwrapped environments. I haven't tracked this down yet. Can Soupermail handle multiple document roots?No. Soupermail assumes that there's only one document root at play, and its probably an unnecessary leak of information letting people specify full path information in the configuration files. The upshot of this is that people who are trying to put their configuration files in their own personal directories on UNIX boxes and trying to refer to them with an initial '~' will be disappointed. Can I stop people reading my config files?Depends on your webserver. If you've got Apache for instance, you can stop
people reading files with the A more unpleasant method of hiding your config files is to wrap them up as something that is already handled by the webserver (eg. an .asp file on IIS or a .php). eg. Concealing the config as an .asp file: Version 1.0.8 has a private configuration path, allowing you to store config files outside your webserver tree. How do I create a debug file?When Soupermail's not installing correctly, a good way to find out
what's happening is to generate a Soupermail debug file. To do this,
open the code for soupermail.pl and file the line setting
$debug = "${tempDir}soupermaillog";
Now when you call Soupermail, you'll get a file written to the temp directory saying what Soupermail's doing. Once you've got everything working, remember to comment out the debug option, or you'll wind up with a massive log file growing on your server. If you don't know what's an appropriate temp directory, ask your server's administrator, or hosting service's support people. Remember, they may have rules about what and where CGI's write to the server. How do I use Soupermail's maths features?As of v.1.0.6, Soupermail's had the ability to do simple maths on form
elements using <output name="fred" math="fred * wilma"> Would display the value of form field 'fred' multiplied by the value
of form field 'wilma'. See How do I stop Soupermail sorting the email alphabetically?There are two options here. One is to use the alphasort config command to prevent the alphabetical sorting, the other is to make your own mailtemplate. See the email tutorial to see it in action. Why doesn't Soupermail have XYZ feature?Time constraints for the most part, but if you do have a killer feature you'd like to see in there, feel free to let me know what you'd like to see, and maybe I'll try and add it. Even better, if you've got patches, they'd be most welcome. The very best thing to do if you have a feature request is to raise it at the Soupermail bug tracking page. What's in future versions?At the moment, I'm pondering 1.0.9. A few ideas I'm kicking about are listed below, but as always, if you have any ideas, raise a bug, and I'll see what I can do. Thoughts to date (though by no means guaranteed to work and should be considered as vapourware):
http://soupermail.sourceforge.net/downloads/dev/ contains a snapshot of work in progress on Soupermail. Anything downloaded from here should be treated with caution, as much horkage is usually introduced while I'm writing Soupermail. Can I make output tags appear in Dreamweaver?Yes, download this taglib zipfile
and extract the files into your Dreamweaver/Configuration/ThirdPartyTags
directory. Dreamweaver will then show a little
GeneralWhy is it called Soupermail?Soupermail started off life as a bunch of stuff added to a script called genmail. Because it was more than generic, it was in fact 'super', I called it supermail. However, someone else had this name, so I changed it to Soupermail. What is Perl?Perl is a pretty damn funky programming language that is very popular on the internet because of its power and ease of use. However, if you didn't know this, I'd suggest you not attempt to install Soupermail yourself. If you go installing things on a webserver you don't know anything about, you deserve all the punishment your sysadms can dole out to you. Sorry it sounds harsh, but a silly mistake in server configuration is a pain in the butt to track down and can have all kinds of unpleasant consequences. What version of Perl do I need?A version of Perl greater than 5.004 is needed to run Soupermail, so check that your version's up to date by running the following at the command line: perl -v The latest versions of Perl can be downloaded from http://www.perl.com/ or, if you're running Windows NT, from http://www.activestate.com/. Do I need to know Perl to use Soupermail?Other than editing a few lines of the Soupermail script to install it, you shouldn't have to know anything about Perl to run Soupermail. All the Soupermail templates are text based, and don't rely on Perl knowledge. However, many ISPs will want to security vet any CGI that goes onto their server (and very sensible they are too for doing so), so it best that you read the Soupermail manual page well before asking your ISP to install it for you. HOWEVER, if you are a webmaster, are maintaining a website, and have permissions to install Perl CGI programs, I strongly suggest you make an effort to learn some Perl. Its not hard, and it will save you a lot of grief in the long run (believe me, I've been there and done it). Read the next answer for some pointers. I'm new to CGI, where can I find out more?Good, you're showing initiative :) Firstly, READ AND BOOKMARK the WWW Security FAQ. Anybody who is running a website MUST read this - if you don't you are a fool, and a wastrel and deserve to be pelted with rotten eggs. Really - people who don't do this, and expect their website to be secure really get up my nose. Right, now I've got that out of my system, there are a number of CGI tutorials littering the web - try looking in the CGI Tutorial section of CGI Resources. If you're going to write your own CGI programs, read more about the CGI Specification. Its dead useful to know the basics of CGI when writing stuff. If you are going to be writing Perl programs, go visit CPAN. Perl has loads and loads of useful modules that make life a lot easier - these modules are almost always distributed at CPAN. Especially, learn about Lincoln Stein's CGI module - its fab! How secure is Soupermail?Soupermail is as secure as I know how to make it. However, this is no guarantee that its perfect, or that I've not made some dumb mistake in the code. As with all things you install on a server, check through the code yourself, just to see what its doing. Remember, Soupermail will only be as secure as the rest of your system, so if you're worried about security, check that your server's fully patched/hotfixed up, that its configured securely, that you know what all your CGIs are doing, and that all external executables haven't been tampered with. If you don't do this, don't blame anybody else for security problems on your system. If you do find a security hole in the code, please let me know FIRST, before alerting any security lists. Email me at vittal.aithal@bigfoot.com, with Soupermail in the Subject, letting me know what system you're running on, what the security hole is, and ideally an example of it in action. This'll let me provide a fixed version on the site before script kiddies get their grubby little hands on an exploit. Why should I use Soupermail?Soupermail is one of the most feature rich (or bloaty, depends on your mood) form handlers around. For making multipart forms, sending encrypted mail, file saving flexibility, fully controlling the output of everything, Soupermail pretty much does it all. The ability to make neat stuff like PDFs makes it a hoot. Why should I not use Soupermail?For the same reasons listed above. Soupermail is not a simple form handler to
get to grips with. You'll have to get your head around templates and the
Who uses Soupermail?I'm not really sure :) I suspect some people are, based on the email I get, and the votes its got at CGI Resources, but I don't have a list of sites using Soupermail. So, if you've developed something with Soupermail, and would like to show off to the rest of the world, mail me and I'll announce it on the Soupermail News page. Some sites I've done using Soupermail: How do I get help in using Soupermail?You could ask me, but I'm sort of stacked out with stuff most of the time so replys can take forever. Try asking the forums on SourceForge. And, if you can, try answering too :) I'm now also using the Sourceforge Support Manager to track stuff (however, don't assume that because its there I offer support ;-) If you do email me, please, please, please, please, please provide as much information as possible about the problem, the server, what steps you did to reach the stage you're at, a debug file if possible, a link to the misbehaving URL, etc. I really do need this information in order to help you. I think Soupermail rocksExcellent, glad you like it. Here are some things you can do to show your appreciation: Good Causes
Not so good Causes
I think Soupermail sucksOh well, sorry. If you think there's a bug in Soupermail, email me, or raise a bug at the SourceForge project page and I'll see if I can fix it. Better still, since this is open source, YOU fix it. How do I send you beer?Easy, pick some bottled beer from BeerRitz and get them delivered to: Ion Global UK, 2-4 Old Street, London, EC1V 9AA. UK. +44 (0) 20 7549 5800 Yum! (They do some really excellent mixed cases.. hint hint :-) Free lunch?During the week, I'm usually slaving away over a couple of computers in central London, and generally forgetting to eat. So, you could get the bods at Deliverance to send over some Sushi. (BTW - my mum thinks this is a better idea than the beer, because I'm a skinny geezer :) You're kidding, people really don't send you beer?Yep, really. Many thanks to:
For the beer, the excellent suggestions, and beta testing. |
icon for output tags next time its started.