Kiosk Web Site and Kiosk Bundle customers can take advantage of an
incredibly powerful feature of our Kiosk service, the ability to 
install your own CGIs.  CGIs are any programs (written in any language)
which can be executed from your Web pages.

CGIs, unlike some other Web scripting environments such as JavaScript,
have access to the UNIX tools and filesystem on The World (although
security is tight enough that CGIs can access only specific items)
and because they run on our high-end server (not on your visitor's
computer) they run very rapidly.

We offer a couple of "standard" CGIs (mailto.pl and Count.cgi) but it
is recommended that you take advantage of this opportunity to install
your own CGIs for your Kiosk.  Why don't we offer more standard CGIs?
Because (1) most CGIs warrant customization for every site they are
used on, and these changes usually involve editing the CGI files,
and (2) for security reasons, you really don't want to share something
like a "shopping cart" CGI with everyone else!

+-----------------------------------------------------------------+
|  CGI installation and debugging normally involves the use       |
|  of the UNIX command line (as in 'telnet'.)  If you are         |
|  unfamiliar with basic UNIX commands such as 'cd' and 'chmod',  |
|  you should brush up on basic concepts before attempting to     |
|  install your own CGI programs on our UNIX server.  Custom      |
|  CGIs are an advanced topic and require a working knowledge     |
|  of UNIX to configure properly.  Our Web site includes a basic  |
|  UNIX tutorial; go to http://www.TheWorld.com, go to "Help",    |
|  then look for "Beginner's Guide".                              |
+-----------------------------------------------------------------+

You can write your own CGIs (they can be as basic as three lines of
'sh' script, or you could use perl, python, C, awk, or another language)
or install ones you've gotten from elsewhere.  Some places to find
CGIs you can use include:

  Matt's Script Archive (huge collection of CGIs):
  http://worldwidemart.com/scripts/

  CGI Resources (also huge):
  http://www.cgi-resources.com

  CGI Collection (ITM):
  http://www.itm.com/cgicollection/

  CGI Archive (TechnoTrade):
  http://technotrade.com/cgi/

  Extropia CGIs (formerly Selena Sol's archive):
  http://www.extropia.com/products.html

  Adam Gaffin's examples of Kiosk scripts for boston-online.com:
  http://www.TheWorld.com/web/scripts.shtml

If you are using mailto.pl, we suggest you see our advice on its
use (and where to get your own copy):

  The World's tips on mailto.pl
  http://www.TheWorld.com/web/help/mailto-pl-tips.shtml

Installation

CGI scripts or programs should be placed in your Kiosk's /cgi-bin
directory, and we suggest a filename ending with '.cgi'.  (They will
likely work if you use a different name, too, but we suggest following
standard procedure.)  The CGI should be permission mode 755
('chmod 755 file.cgi'.)  We suggest you review the "Troubleshooting"
section below with regards to the details of what to watch out for.

Using Your CGI

If your CGI generates an entire page of HTML, you can call it with:

  <A HREF="...">
  <FORM ACTION="..." METHOD="POST or GET">

If your CGI generates an image (as Count.cgi does), you can call it with:

  <A HREF="...">
  <IMG SRC="...">

If your CGI generates part of a page of HTML, or plain text, or no
output at all, you can embed it in an HTML page with:

  <!--#include virtual="..." -->

Please read point 6 under "Troubleshooting" (below) to determine
what URL you should use for your CGI.

Troubleshooting

The six things to verify, in brief (detailed below this summary) are:

 +---------------------------------------------------------------------+
 | 1.)  CGI scripts such as Perl or sh files must be uploaded as TEXT. |
 +---------------------------------------------------------------------+
   2.)  The CGI file and /cgi-bin/ are both permission mode 755.
   3.)  The program's name ends with ".cgi".
   4.)  The CGI indicates that it requires a particular program
        and the program is installed under that name and path.
   5.)  The CGI executes when you run it from the UNIX command line,
        and outputs a "Content-type:" header followed by a blank line.
   6.)  You are using the correct path to call the CGI from your
        Web page.

It is not necessarily obvious from the error message you get (or lack
of any output) what's wrong with your CGI, so we recommend walking through
these six steps in the order described below until you find the problem.
(If it persists, contact kiosk@TheWorld.com for CGI-related questions,
or support@world.std.com for general UNIX questions.)

By the way, if you see an "Error 500 - Server Misconfiguration" in
your Web browser, that's usually a sign of one of these problems.
They can also manifest themselves as "403" or "404" errors or blank pages.

Checklist in Depth:

1.)  This is the most common problem, so I'm going to say it in all caps:

WHEN UPLOADING A TEXT FILE (SUCH AS A PERL PROGRAM OR SH SCRIPT),
YOU *MUST* *MUST* *MUST* SET YOUR FTP PROGRAM TO "TEXT" ("ASCII") MODE,
NOT "BINARY", NOT "RAW DATA", NOT "MACBINARY", BUT "TEXT".
THIS GOES FOR ANYONE USING DOS, MICROSOFT WINDOWS, OR A MACINTOSH.

Why is this?  Well, UNIX-based computers such as The World (and the
sister computer that will run your CGI) use a different end-of-line
marker than DOS, Windows, or Mac OS.  And although most terminal programs
and word processors will show your file just fine if it has ^Ms at
the end of each line instead of ^Js, things like Perl will tell
you "Syntax error at line 1" if you have the wrong type of end-of-line
markers.  Uploading via FTP in "text" mode will convert the end-of-line
markers (and nothing else) to the proper characters.

+-----------------------------------------------------------------------------+
|  TEXT FILES MUST ALWAYS BE UPLOADED IN "TEXT" ("ASCII") MODE.               |
|  PICTURES AND SOUNDS MUST ALWAYS BE UPLOADED IN "BINARY" ("RAW DATA") MODE. |
+-----------------------------------------------------------------------------+

If you want to check your CGI for the presence of undesirable ^Ms,
try this:

  %  head myprogram.cgi | cat -v

  #!/usr/local/bin/perl
  # myprogram.cgi - Perl5 CGI by Kibo 9/8/02

  %  head badprogram.cgi | cat -v

  #!/usr/local/bin/perl^M# myprogram.cgi - Perl5 CGI by Kibo 9/8/02^M

If your file has ^Ms, delete it and upload it again correctly.
(There are other ways to fix this, but the easiest thing to do is to
upload it again.)





2.)  The next thing to check is the permissions of the CGI file itself.
It should be mode 755 (so that all users have "read" and "execute" 
access.  Example:

  %  cd /web/RodeoDrive/example/cgi-bin
  %  ls -l

  total 1104
  -rwx------    1 example  example     4830 Sep  8 21:58 myprogram.cgi
         ^^^
         the last three letters or dashes are what we're looking at

...if your CGI doesn't end with "r-x" (the last three letters are "r-x"
if it's readable and executable for other people) then you need to
set it to mode 755:

  %  chmod 755 myprogram.cgi
  %  ls -l

  total 1104
  -rwxr-xr-x    1 example  example     4830 Sep  8 21:58 myprogram.cgi
         ^^^
         now the program is runnable by other people

Many accounts are configured to create new files (as happens when a
CGI is uploaded) with permission mode 700 (rwx------) or 644 (rw-r--r--).
If your file comes out that way, you will need to set the mode to 755
after uploading.

Your cgi-bin directory itself should also be mode 755 (rwxr-xr-x)
but you should never need to tinker with it, we set them all up that way
to start with!

CGIs formerly executed as user "nobody", but now execute as a different
dummy user.  If your CGIs need to be able to read a particular data file,
you should make that file readable to others (mode 755 will work),
but if it needs to WRITE to a file, that's a trickier issue --
changing your file to mode 777 would let EVERYONE write to it, which is
A VERY BAD IDEA -- so if you have files that need to be written to by a CGI,
please ask kiosk@TheWorld.com to enable suexec
for your Kiosk.  We will set the server so that the CGIs will execute as
you, rather than as a dummy user, and thus you and the CGI will be able
to write to the data files and nobody else will.  There are restrictions:
To use suexec you must meet these conditions:

  a.) suexec only works with sites that have their own domain name
      (www.yourname.com), we can't enable it if you don't have your
      own domain name (www.TheWorld.com/~yourname).
  b.) The CGI must be in your /cgi-bin, not elsewhere.  (Subdirectories
      of /cgi-bin are allowed.)
  c.) The CGI's owner and group are you, not "nobody" or other.
  d.) The /cgi-bin directory's owner and group are you.
  e.) Neither the CGI file nor the directory is writeable to group or other users.
      (suexec will not work if your CGI or /cgi-bin is mode 777 or 775.)
  f.) Symbolic links are not permitted.
  g.) The CGI may not be owned by root, and may not have the setuid or setgid
      flags set.

If you have trouble figuring out whether you are ready to use suexec, you
can ask us for help.  You will need to ask us to enable suexec if you want
your CGI to have access to your data files without requiring your data
files to be accessible to everyone.





3.)  The CGI's filename should end with ".cgi".  (It may also work with
other extensions or no extension, but ".cgi" is preferred.)





4.)  If the program is a script (such as perl or sh) its first line
must begin with a special "#!" comment which indicates what program
will run the script.  (This does not apply to compiled programs.)

Check the first line of the file to see what the path to the program
that will execute the CGI is, then check that the program it refers to
is there:

  %  head myprogram.cgi

  #!/usr/local/bin/perl
  # myprogram.cgi - Perl5 CGI - Kibo 9/8/02

  %  ls -l /usr/local/bin/perl

  lrwxr-xr-x    1 root    sys    10 Dec 28  2002 /usr/local/bin/perl -> perl-5.6.0

...if it says anything other than "No such file or directory" you're
okay.  (Note:  The computer which runs your CGIs is not the same computer
as the one you're logged into.  But in general the same programs are installed 
in the same places on the two.)

We have multiple versions of Perl installed.  As of this writing:

  /bin/perl, /usr/local/bin/perl, or /usr/local/bin/perl5
                                               is perl version 5.6.0

  /usr/local/bin/perl5.8.0                     is perl version 5.8.0

Our previous Web server had both perl4 and perl5 available, but the
current Web server only supports perl5.  (In general anything which
works under perl4 will work under perl5, although it may require
minor bug fixes.)

You can always get a current list of the installed versions of Perl by typing:

  %  ls -l /usr/local/bin/perl*

If you have any questions about what the correct paths for other
programs are, please ask.  (support@TheWorld.com can give you a fast 
answer for such simple questions;  more technical CGI-related questions 
should go to kiosk@TheWorld.com.)





5.)  Now is the time to test your CGI now that you're sure it's properly
uploaded and installed.  Because your CGI is an executable program, try
executing it directly from the UNIX command line by typing its name.
(This will give you direct feedback, eliminating the Web server and
the Web browser from the environment.)  It should spit out something
along these lines:

  %  myprogram.cgi

  Content-type: text/html

  <H1>Variables missing</H1>
  <P>You were supposed to supply a "name" variable.</P>

...that is correct, even though it's an error message.  (Most CGIs
require variables to be set from the Web browser.)  What we're looking
for here is:

    a.)  The output must be something other than
         "perl: Syntax error at line 1." or
         "perl: You're trying to divide by zero at line 58."
         or any other thing indicating that your program won't run.

    b.)  The output must begin with "Content-type: text/html" and
         TWO CARRIAGE RETURNS (a completely blank line).

If it spits out "Content-type: text/html" (and possibly some other
headers) followed by two carriage returns ("\n\n" in most languages)
you're all set.  The "Content-type" header is an HTTP header (not
HTML!) which is invisible to your site's visitors;  the blank line
is necessary to indicate the HTTP headers have ended and the HTML
is beginning.

If the program outputs an error message, or omits that
"Content-type: text/html" header, the Web server will display
a "500" error when attempting to use the script on your Web page.
Note that even a single error message -- even if it's below the
"Content-type: text/html" header -- can generate this "500".
The script must run with no errors.

If you want to test the CGI by passing it some variables, there are
ways of doing that from the shell, but they're cumbersome enough
that you might as well just do it from the Web browser.  What we
were checking by running it from the shell was just whether the
program could run at all (looking for syntax errors) and whether or
not the "Content-type: text/html" header was present and followed by
a blank line.





6.)  Now we can try using the program from the Web.  I assume you have
an HTML page set up that calls your CGI.  The most important thing to
check here is to make sure you are referring to it by the correct URL:

  http://www.example.com/cgi-bin/myprogram.cgi
           (full name you would use when linking to your CGI from
           an external site)
  or

  /cgi-bin/myprogram.cgi
           (abbreviated version you can use in links from
           HTML pages on the same site)

...although you can sometimes refer to your Web pages by other
paths, your cgi-bin directory (for security reasons) can normally be
accessed only as "http://www.example.com/cgi-bin/..." or "/cgi-bin/..."
(assuming you have your own domain name, of course.)  A few Kiosk sites
are currently configured slightly differently due to customer requests;
If you would like any changes in your cgi-bin setup (and if you're sure
you really understand  the issues involved) you can ask us to tinker
with the server's configuration by sending mail to kiosk@TheWorld.com.
(Again, this is only recommended if you understand exactly what's going
on at the Web server level.)

If you attempt to access the cgi-bin directory through an invalid
path, or you get the name of the CGI itself wrong, you may get
a "Permission Denied" error (403) or another error.

Your CGI should be accessed with one of these tags:

  <FORM ACTION="/cgi-bin/myprogram.cgi" METHOD="...">
  (the CGI will run when the form is submitted, and variables
  will be passed to it with the GET or POST method)

  <A HREF="/cgi-bin/myprogram.cgi">
  (the CGI will run when this link is clicked;  GET-method
  variables may be appended to the query string)

  <IMG SRC="/cgi-bin/myprogram.cgi">
  (only for those CGIs which output images, such as graphical
  counters;  GET-method data may be appended to the query.)

If you are passing GET data to the CGI via the query string,
the format to use will vary depending on the CGI.  An example:

  <IMG SRC="/cgi-bin/Count.cgi?df=login-name.dat|dd=B|frgb=FF9900">

...note that if you do that, you can't include any spaces or any
other funny characters (replace them with "%xx" notation, such as
"%2B" for "+".)  See the documentation for your CGI's specific
requirements as to what characters it will or will not accept.

If you are using Server-Side Includes (SSIs or XSSIs), then be sure
that your Web page's filename ends with ".shtml" (instead of ".html"),
and the syntax to execute the CGI as an "inline" item is:

  SSI include for CGI hosted at http://www.example.com/cgi-bin/myprogram.cgi :
  <!--#include virtual="/cgi-bin/myprogram.cgi" -->

...paths to your CGI, if you call it with an SSI #include command,
must begin with a slash, not a sitename.  This means that
the path is slightly different between <!--#include virtual="..." -->
and <A HREF="..."> because the #include never takes a sitename.

Note: If you're using <!--#exec cgi="..." -->, you must change this
to <!--#include virtual="..." -->, which will do the same thing
but is preferable for technical reasons.  <!--#exec cgi="..." --> is not
supported for security reasons.  You can use <!--#include virtual="..." -->
instead, which is an all-purpose tag which works with either a file
(text, .html, or .shtml) or the output of a CGI.












 
Comments?  Questions?  Problems? Contact us.


Page last modified July  7, 2003.


Web site contents & design Copyright © 2003 Software Tool & Die. Legal info.