AW 3.0 Scripting Guide
~~~~~~~~~~~~~~~~~~~~~~

AW 3 has CGI-like scripting abilities available.



Writing Scripts
~~~~~~~~~~~~~~~

CGI scripts should be executable files in your HTML tree that
end with one of the extensions specified by cgiexts in your
awhttpd.conf file (See MANUAL for details).

Scripts are passed HTTP variables from the query string in 2
ways:

1) They are decoded by anti-web and stored in their own respective
   environment variables. Every CGI script is also run with the
   environment variables that were present when AW was initially
   run and clients are *NOT* permitted to overwrite these variables.
   (This could cause major security problems, particularly if
   clients could change the value of, for instance, PATH.)

   Note: As of 3.0.2 the HTTP variables passed to the server by the
   client are not stored in their respective environment variables
   because of potential security threats. We're working on a decent
   solution for this.

2) They are passed as a list of "&" separated, non-decoded
   key=value pairs in the first command-line argument. This
   is made use of by PHP, for instance.

If a script is requested with the POST method, the script
will have the client's output available on its standard input.



Getting PHP Working
~~~~~~~~~~~~~~~~~~~

It's possible to use PHP with AW3 with a few restrictions and
configuration steps.

The first step is to install a PHP version compiled as a CGI module.
This is very important. You can check that PHP is set up properly by doing
this:

Get the path of your php interpreter:

  whereis php

for instance, it might be /usr/bin/php

Typing this:

  echo | /usr/bin/php

Should look similar to this:

doug@saturn:~$ echo | /usr/bin/php
X-CGI-Powered-By: PHP/3.0.18
Content-type: text/html


doug@saturn:~$


If Those 2 lines (or similar ones) aren't printed and followed
by 2 blank lines, PHP is *not* installed correctly: make sure
you have a CGI PHP installation.


The next step is to ensure that cgi is enabled in your awhttpd.conf
file. You should see a line like this:

cgi on

And no lines like this:

cgi off


The next step is to enable php files in your awhttpd.conf
file:

Adding the line

cgiext .php

to your awhttpd.conf file tells AW to treat all files ending
in .php (or .PHP or .pHp etc) as CGI files.


The next step is to put the line

#!/usr/bin/php

At the top of all your .php files in your HTML tree.


The final step is to make all your php files executable:

chmod a+x my_file.php




Writing PHP Scripts for AW
~~~~~~~~~~~~~~~~~~~~~~~~~~

For the most part, PHP should work *as is*, but be aware you are
provided with only the enivronment variables mentioned in the
section "Environment Variables Provided" (and ones that the
user specifies of course).

PHP 3 accepts query variables in the environment of the calling
process and, as such, you can simply use them without any hassle.

PHP 4 requires you to use $_GET, $HTTP_GET_VARS, or getenv().

If you want to use a variable called blah, for instance:

$blah = $_GET["blah"];

or

$blah = getenv("blah");

See the provided php scripts for examples.




Environment Variables Provided
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

REMOTE_ADDR

Provides the IP address of the client. Will contain ':' characters if
client is connecting via IPv6.

AW_NUMUSERS

The number of users currently in the process of completing an HTTP
request with the server.

AW_VERSION

The awhttpd version. IE: "3.0.1"

AW_QUOTE

The quote awhttpd currently uses. IE: "Fear and loating on the WWW"
