Skip to main content.

General Information

Random Image Generator is a CGI script written in PERL that takes the contents of a specified directory and generates an html image tag by selecting a random file name in that directory.

It's advantages over most random image generators are:

Random Image Generator has been verified to work on the following configurations:

  • 5.0x
  • ActivePerl 5.6.1
OS and Web server
  • Unix/Linux running Apache 1.3.x
  • Solaris running Zues
  • Windows 2000 running Apache 1.3.2
  • Unix/Solaris running iPlanet

If you have Random Image Generator up and running on another platform please let us know so that we can update this list.

Our scripts are free in both the license and monetary sense. However, if you would like show your appreciation for the time and effort that has gone into creating these scripts, you may do so by clicking the button below. It will take you to PayPal but you do not have to have a PayPal account to donate. You can use your regular Visa, MasterCard, etc.

Revision History

2.1 2/19/2003 Minor documentation update to clarify SSI calls.
2.0 12/1/2002 Updated to allow call via <img> tag or via SSI
1.0 10/8/2002 Initial Release


The following demos help to illustrates how you can use Random Image Generator to generate images on your pages.

Installing Random Image Generator

Installation is pretty simple:

  1. Download the script.
  2. Decompress it using the software of your choice.
  3. Upload the random_image.cgi file to the desired directory on your web server. The file should be uploaded as ascii text.
  4. Set the file permissions to allow the server to execute the script. Generally speaking, you should set the permissions to the most restrictive that you can get away with. If you are not using a wrapper script (such as cgiwrap), or a directory that allows you to execute the script as the owner, you will probably have to set the permission so that Owner, Group, and Other can read and execute the file. The easiest way to do this is to execute the command chmod 755 random_image.cgi once the file has been uploaded to the server.


To run Random Image Generator on your server you must configure it's variables properly to match your web configuration.

The following script variables must be set for the script to run properly. As you'll be able to tell the most confusing part is knowing when and when not to include the trailing "/" in the path and directory names.

PERL path - The first line of the script must be changed to reflect the proper path to PERL on your web server unless, of course, your PERL path matches the default of "#!/usr/local/bin/perl".

$base_path - This parameter should be set to the absolute file path (not URL) to your base image directory. This parameter is used to get the contents of the specified directory.
You must INCLUDE the trailing "/".

Example: $base_path = "/home/username/www/";

$image_url - The URL to your image directory above. This parameter is used to create the <img> tag for the image to be displayed.
You must INCLUDE the trailing "/".

Example: $image_url = "http://www.your.domain/";


The Random Image Generator can be called via standard HTML <img> tag or via SSI. Syntax is dependent upon which method you are utilizing. Each method has it's advantages and disadvantages.

<img> Tag Format

This method uses a standard HTML image tag to call the script:

<img src="http://www.your.domain/your/path/to/script/random_image.cgi?path=directory_path" alt="some alternate text">


  • directory_path = the path to the directory you wish to list including the name of the directory itself. The path name cannot start with a "/", "\", ".", or ".."
    directory_path MUST BE SUPPLIED
SSI Format

This method uses Server Side Includes (SSI) to call the script:

<!--#include virtual="/your/path/to/script/random_image.cgi?method=ssi&path=directory_path&link=URL&alt_txt=img_alt_text"-->


  • method=ssi
    "method=ssi" MUST BE SPECIFIED if the script is being called via SSI.
  • directory_path = the path to the directory you wish to list including the name of the directory itself. The path name cannot start with a "/", "\", ".", or ".."
    directory_path MUST BE SUPPLIED
  • URL = the URL you wish to link the image to.
    URL is optional. If no URL is supplied the image will not be linked.
  • img_alt_text = value to applied to the alt attribute of the <img> tag.
    img_alt_text is optional. If not supplied the alt attribute will default to "Image".

Note that you should not include the "" portion of the URL to the script in the SSI. The URL will be relative to your document root.



Can't get the script to run? Continually getting an error message? Here's some troubleshooting tips:

Problem Possible Cause Solution
Server Errors File permissions set incorrectly for Random Image Generator script chmod 755 random_image.cgi
File not uploaded in ascii format Delete file and upload again using ascii format.
Script variables set incorrectly Make sure you have followed all the instructions layed out in the Configuration section.
Error Code 1 Missing path parameter in query string Make sure the call to Random Image Generator contains the "path=" variable and all parameter name/value pairs are separated by "&".
Error Code 2 A "/" or "\" or ".." or "." was used at the start of the path. For security reasons, "/", "\", "..", and "." are not allowed at the start of a path name.
Error Code 4 $base_path set incorrectly. $base_path must include a trailing "/" and represent an absolute path not a URL.
The path portion of the Random Image Generator call is incorrect. Correct the path portion of the Random Image Generator call.
Typos in path name Correct the typos. Remember, most of the time these names will be case sensitive.
Script runs but no images are displayed Empty directory or directory only contains non-image files. Add images to directory or delete non-image files.
An image is displayed but it's not the right one The path is incorrect. You've supplied the wrong path in the call to Random Image Generator.
$image_url is set incorrectly Set $image_url to the correct URL for your images.
Images not displaying $image_url is set incorrectly Set $image_url to the URL where the images are stored.
$image_url has a trailing "/" Remove the trailing "/" from $image_url.
"method=ssi" not included in call via SSI You must include "method=ssi" if calling the script via SSI