My Classifieds SQL (version 3.2)

Please read everything but
consult our forum if
(1) you do not understand
(2) you get it running (so I can check it out and put up a link to your site).
In this README:
REQUIRES
SUMMARY
FEATURES
DISTRIBUTION / LICENSE
INSTALLATION WITH SHELL ACCESS
INSTALLATION WITH FTP ACCESS
HOW TO USE
TROUBLESHOOTING
CHANGES
TODO
REQUIRES    back to top
  • 1. web server (tested on apache 2.0.44 on UNIX and LINUX)
  • 2. Perl (tested with 5.8.0)
  • 3. MySQL (tested with 12.18)
  • 4. DBI - you can get it here: search.cpan.org
  • 5. Digest::MD5 - you can get it here: search.cpan.org

    Digest::MD5 and DBI are very common and probably are already installed on any system you will be using, unless you run your own webserver using an obscure or light UNIX/Linux install. If you don't have this, please contact your system administrator.
  • SUMMARY    back to top
    This Classifieds script will quickly and easily allow you to host your own classifieds forum on your site. Users can browse the ads, but must log in with their email and password before being allowed to post an ad. Users can securely email the ad's owner and the webmaster from within a form, protecting the integrity of the users' and admin's email addresses. The admin can specify whether or not to allow users to upload pictures or to link to pictures hosted on other servers. All of these features are wrapped up in a fully customizable, templateable interface that is intuitive and clean.
    FEATURES    back to top
  • Post an unlimited number of ads.
  • Admin can allow or disallow uploading of pictures and linking to pictures.
  • Admin can specify how long an ad can remain before being automatically deleted, or specify forever.
  • Admin can specify categories for the ads.
  • Admin can delete users, ban users, and change user's passwords.
  • Admin can delete and edit ads.
  • Admin can choose from one of our language modules, or create his own language module.
  • Specify your own colors.
  • Use your own template.
  • DISTRIBUTION / LICENSE    back to top
    This software is released under the GPL. Please see the included LICENSE file. Copyright (C) 2003 Erin Spiceland This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Use this script at your own risk! I make no warranties that it is hack proof!
    INSTALLATION WITH SHELL ACCESS    back to top

    1. Upload the .zip or .tar.gz file directly into your cgi-bin directory. Almost all folders will be created automatically for you. Do this on commandline:
    $ unzip filename.zip        *** or***
    $ tar -zxvpf filename.tar.gz
    2. Check your file permissions. Your directory structure will now look like this. Listed out to the side are the permissions for each file. If you used the tar.gz file, your permissions will automatically be set, because tar saves them. If you used the zip file, you will need to set these permissions yourself. A quick way to do this is with the following:
    $ chmod 755 *.cgi *.pm protected/*.cgi
    If you are on a Windows server, use your control panel to give the 755 files execute permissions.

    classifiedsmysql/drwxr-xr-x-chmod   755
    classifiedsmysql/autodelete.pl-rwxr-xr-x-chmod   755
    classifiedsmysql/email.cgi-rwxr-xr-x-chmod   755
    classifiedsmysql/index.cgi-rwxr-xr-x-chmod   755
    classifiedsmysql/lib/drwxr-xr-x-chmod   755
    classifiedsmysql/lib/functions.pm-r-wr--r---chmod   644
    classifiedsmysql/lib/sitevariables.pm-r-wr--r---chmod   644
    classifiedsmysql/lib/common.pm-r-wr--r---chmod   644
    classifiedsmysql/LICENSE-r-wr--r---chmod   644
    classifiedsmysql/makeadstable-r-wr--r---chmod   644
    classifiedsmysql/makepeopletable-r-wr--r---chmod   644
    classifiedsmysql/protected/drwxr-xr-x-chmod   755
    classifiedsmysql/protected/index.cgi-rwxr-xr-x-chmod   755
    classifiedsmysql/README-r-wr--r---chmod   644
    classifiedsmysql/readme.html-r-wr--r---chmod   644
    classifiedsmysql/send.pl-rwxr-xr-x-chmod   755
    classifiedsmysql/template.html-r-wr--r---chmod   644

    3. Make sure all these files are owned by the right user. If you are on a server that is not your own, you are most likely ok. Ask your system administrator if you think you may need to change the ownership of these files. If you are on your own webserver, sometimes you will have to change the ownership to "apache" or "nobody" to get the scripts to run. Do this with:
    $ chown apache:apache * -R
    4. Edit lib/sitevariables.pm to suit your needs. You will need to specify your preferences on colors, a font, a template, your classifieds categories, the help email address, and whether or not to allow picture uploads and links. There are also two very important things in sitevariables.pm that affect how your picture uploading and displaying will work. Make sure $htmlurl and $htmlsystempath are correct for your server's directory structure. They should point to a directory NOT inside your cgi-bin directory where images will be stored for your ads. The default will create a directory "~/html/classifieds/pictures" to store the pictures in, where ~ represents your home directory. There are examples in the file of how to format your settings for these two variables. You also need to specify your MySQL settings here, near the bottom of the file. $mysqldb is your database name, $mysqluser is the user you access the database as, and $mysqlpass is your mysql password. Usually, your username and password are the same that you log in as. Ask your system administrator if you aren't sure what to put for these settings.

    5. Choose your language. My Classifieds is automatically set up to use English. If you are using another language that is already supported by My Classifieds, just rename your appropriate language file to be named "lang.pm," like this:
    $ cd lib/
    $ cp francais.pm lang.pm
    cp: overwrite 'lang.pm'?  y
    $ cd ../

    If you end up creating your own language file for a language that My Classifieds does not already have, please send me a copy of your lang.pm named according to its language (francais.pm, not french.pm, please). To create your own, open "lib/lang.pm" and only change phrases that are between quotes. If you change anything else, like the "our" or the phrase following $ , which makes up the variable name, you could break the script. Example:
    our $please_choose_a_category = "Please Choose a Category"; # English
    our $please_choose_a_category = "S'il vous Plait, Choisissez une Categorie"; # French
    6. Set up your MySQL tables. We will be making two tables, one called "people" for our users and their passwords, and one called "ads" for our actual data. If you can use MySQL on commandline, do this:
    $ mysql databasename < makepeopletable
    $ mysql databasename < makeadstable

    If not, you will need to use your control panel to create the tables. It is very important that the fields be created in the same order as what you see here. Here is how they should be set up:

    Ads
    Field NameData Type
    emailvarchar(255)
    categorymediumtext
    subjectvarchar(255)
    adtypevarchar(255)
    urlvarchar(255)
    adindexint(11)
    descripmediumtext
    weburlvarchar(255)
    datenumint(11)

    People
    Field NameData Type
    emailchar(255)
    passmd5char(255)
    7. You may need to modify the first line of index.cgi, email.cgi, autodelete.pl, send.pl, and protected/index.cgi to point to where perl is located on your server. Basically, its just pound, exclamation point, then the path to the perl executable.
    #!/usr/bin/perl (most common, and the default for this script)
    #!/usr/local/bin/perl
    #!/soft/script/bin/perl (University of Tennesse Knoxville)
    8. Password protect the "protected" directory, so others cannot administrate your classifieds. If you are on a UNIX or Linux server, you can use htaccess to do this. Contact your system administrator or google for "htaccess" to find out how. Also, no matter what kind of server you are on, you may have a tool in your control panel to password protect files and directories. I cannot stress how important it is that you password protect the administration portion of this script. Because this script is open source, meaning anyone can see my code, anyone who has used this script will know how to access the administration panel. Your only hope for security is to password protect it.
    INSTALLATION WITH FTP ACCESS    back to top

    1. Unzip or untar the archive file into a directory on your computer.

    2. Edit lib/sitevariables.pm to suit your needs. You will need to specify your preferences on colors, a font, a template, your classifieds categories, the help email address, and whether or not to allow picture uploads and links. There are also two very important things in sitevariables.pm that affect how your picture uploading and displaying will work. Make sure $htmlurl and $htmlsystempath are correct for your server's directory structure. They should point to a directory NOT inside your cgi-bin directory where images will be stored for your ads. The default will create a directory "~/html/classifieds/pictures" to store the pictures in, where ~ represents your home directory. There are examples in the file of how to format your settings for these two variables. You also need to specify your MySQL settings here, near the bottom of the file. $mysqldb is your database name, $mysqluser is the user you access the database as, and $mysqlpass is your mysql password. Usually, your username and password are the same that you log in as. Ask your system administrator if you aren't sure what to put for these settings.

    3. Choose your language. My Classifieds is automatically set up to use English. If you are using another language that is already supported by My Classifieds, just rename your appropriate language file to be named "lang.pm," like this:
    $ cd lib/
    $ cp francais.pm lang.pm
    cp: overwrite 'lang.pm'?  y
    $ cd ../

    If you end up creating your own language file for a language that My Classifieds does not already have, please send me a copy of your lang.pm named according to its language (francais.pm, not french.pm, please). To create your own, open "lib/lang.pm" and only change phrases that are between quotes. If you change anything else, like the "our" or the phrase following $ , which makes up the variable name, you could break the script. Example:
    our $please_choose_a_category = "Please Choose a Category"; # English
    our $please_choose_a_category = "S'il vous Plait, Choisissez une Categorie"; # French
    4. You may need to modify the first line of index.cgi, email.cgi, autodelete.pl, send.pl, and protected/index.cgi to point to where perl is located on your server. Basically, its just pound, exclamation point, then the path to the perl executable.
    #!/usr/bin/perl (most common, and the default for this script)
    #!/usr/local/bin/perl
    #!/soft/script/bin/perl (University of Tennesse Knoxville)
    5. Upload the files to the server. Make sure the directory structure is the same (all the folders are in the same place as they werewhen you unzipped the file.) You should put all the files in your cgi-bin directory. Make sure you upload them in ASCII mode, NOT binary mode. Uploading them in binary mode will turn all the files into useless garbly goop that cannot be executed.

    6. Make sure all the executable files have execute permissions. Use your control panel to give all .cgi and .pl files executable permissions. If you do not know how to do this, contact your system administrator.

    7. Password protect the "protected" directory, so others cannot administrate your classifieds. If you are on a UNIX or Linux server, you can use htaccess to do this. Contact your system administrator or google for "htaccess" to find out how. Also, no matter what kind of server you are on, you may have a tool in your control panel to password protect files and directories. I cannot stress how important it is that you password protect the administration portion of this script. Anyone who has used this script will know how to access the administration panel. Your only hope for security is to password protect it.

    8. Now set up the MySQL tables. You will need one called "people" and one called "ads" as illustrated below. Use your control panel to create these tables with the listed fields and data types. It is very important that the fields be created in the same order as what you see here. If you do not know how to do this on your server, contact your system administrator.

    Ads
    Field NameData Type
    emailvarchar(255)
    categorymediumtext
    subjectvarchar(255)
    adtypevarchar(255)
    urlvarchar(255)
    adindexint(11)
    descripmediumtext
    weburlvarchar(255)
    datenumint(11)

    People
    Field NameData Type
    emailchar(255)
    passmd5char(255)
    9. Now just point your browser at it! http://fuzzymonkey.net/cgi-bin/classifiedsmysql/index.cgi.
    HOW TO USE    back to top
    First, access the front page by going to the url (ex, http://www.yoursite.com/cgi-bin/classifiedsmysql/index.cgi). Click the "Register" link and create a login and password by registering. Begin placing ads. Everything is very straightforward. You can read other people's ads and contact them by clicking the "Email the Seller" link in the upper righthand corner. You will be able to email them but will not be able to see their email address.

    TROUBLESHOOTING    back to top
    If you get an internal server error, run it from command line so that you can see what is going wrong and check your server logs for helpful error messages. For instance, if its index.cgi that's giving you problems, do:
    $ ./index.cgi
    If it's running correctly, it will return alot of html code. If it does anything else, its obviously broken. Look at the output and see if you can make sense of it. Here are some sample errors and explanations on what they mean and how to fix it.
    $ ./index.cgi
    Can't locate SOMETHING in @INC (@INC contains: /usr/lib/perl5/5.8.0/i386-linux-thread-multi /usr/lib/perl5/5.8.0 /usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-multi /usr/lib/perl5/site_perl/5.8.0 /usr/lib/perl5/site_perl /usr/lib/perl5/vendor_perl/5.8.0/i386-linux-thread-multi /usr/lib/perl5/vendor_perl/5.8.0 /usr/lib/perl5/vendor_perl .) at ./index.cgi line 29. BEGIN failed--compilation aborted at ./index.cgi line 29.
    This can mean one of two things. Its looking for a perl module to load. It either means that you do not have that perl module installed, or that it is installed into the wrong directory and perl can't find it. If SOMETHING is common.pm, sitevariables.pm, lang.pm, or functions.pm, then you are missing the lib/ directory or one of the files in it, and you need to download and reinstall My Classifieds. If it is DBI.pm, CGI.pm, or Digest/MD5.pm, you do not have a perl module that is required to run My Classifieds SQL. You can get around not having DBI.pm by using the non-MySQL version of My Classifieds, but if you do not have one of the other perl modules, you must install it. Contact your system administrator and request that they add that module to the server, or do a local install of it.
    $ ./index.cgi
    bash: ./index.cgi: Permission denied
    Again, this error message means one of two things. Either index.cgi does not have execute permissions, or it is not owned by the correct user. See the installation instructions above to determine which of these is the case.
    $ ./index.cgi
    bash: ./index.cgi: /usr/bin/perl: bad interpreter: No such file or directory
    This means that your shebang line (the first line in any perl script) does not point to where perl actually resides on your server. See the installation instructions on the importance of this and how to fix it.

    If you receive any other error messages, feel free to email them to me, and I will do my best to explain what they mean and how to remedy the situation. These are the three most common error messages you may get, and they are all easily fixable.
    CHANGES    back to top
    04.18.03version 3.2Admin can now customize time zone by specifying how many hours to add to or subtract from Greenwich Mean Time. Cleaned more code.
    12.07.03version 3.11Fixed a bug prohibiting users to use emails in the format erin.spice@fuzzy.monkey.org.
    11.09.03version 3.1Admin can now change passwords to whatever he/she wants. Also, new language module allows admin to define his own language and theme for My Classifieds, making it more customizable than ever. Also enhanced the readme to explain more possible scenarios and go over installation in more detail.
    10.19.03version 3.0Major feature enhancements. Added features allowing the admin to edit and delete ads and to delete and ban users and reset their passwords.
    10.18.03version 2.13Fixed security issue that allowed MySQL insertion.
    09.16.03version 2.12Fixed bug that updated/added ad even if the uploaded picture is larger than the admin's specifications.
    09.08.03version 2.11Fixed bug that caused ads to be deleted if $autodelete was set to 0.
    07.23.03version 2.1Fixed a bug that causes all ads in a category to be deleted when one ad in that category is deleted.
    07.23.03version 2.02OK -- this time the uploading bugs really are fixed.
    06.02.03version 2.01Fixed bugs with uploading pictures and sending email.
    05.29.03version 2.0Complete overhaul. The script was completly rewritten - none of the code is the original. Added features are the ability to search through all the ads, templatability, and emailing is done via a script and thus promotes privacy.
    01.9.02version 1.2Fixed security hole. All users are encouraged to update immediately.
    11.26.00version 1.1Fixed the bug causing every ad to be repeated when a user updates an ad. Added two variables. $checkphonenumber allows webmaster to specify whether to check for a valid phone number or not. $allowpictureurls allows webmasters to specify whether or not to allow users to post picture urls. Do some checking to strip out malicious html. Please DO NOT test this on my server! Do this on your server if you must.
    08.06.00version 1.0I changed to version 1.0 because I think it has all of the features necessary to serve most people's purposes.
    07.31.00version 0.8Added picture url when placing and viewing ads. Added section for users to delete their ad with the password emailed/displayed when they place the ad. Added capability to edit ads also. This is done by first deleting the old ad, then placing a new one.
    07.13.00version 0.7Fixed a problem with placing an ad when reading in categories.
    06.14.00version 0.6Made categories editable from @categories array instead of from a file.
    06.12.00version 0.5Added error checking to check for bad people not filling in the form right.
    05.05.00version 0.4Fixed bug where the script would break if user did not enter an email and emailing was turned on.
    04.07.00version 0.3Added email link to preview and add pages. Fixed line breaks in emails. Added file locking to prevent multiple access to the same file by different users.
    04.06.00version 0.2Added email to user and to webmaster capabilities and also made ads expire.
    03.21.00version 0.1Added logging capabilities.
    TODO    back to top
    I need to do help with the following items
  • Add capability to email webmaster/user upon every new ad.
  • Let webmaster approve or delete ads before they are posted.
  • Create user control panel where they can change their password, change preferences, etc.
  • If you have suggestions of other features, please email me!
  • Send questions or comments to support@fuzzymonkey.net

    Thanks,
    Mike and Erin Spice