CGI: Introduction: Difference between revisions

From The Uniform Server Wiki
Jump to navigation Jump to search
(Created page with "__NOTOC__ {{Nav CGI}} '''Coral-Mini Server''' Apache with the release of 2.2.18 made a small change, extract from the change log '''''Added shebang check for '! so that .vbs sc...")
 
m (Text replace - "projects/uniformserver" to "projects/miniserver")
 
(4 intermediate revisions by 2 users not shown)
Line 4: Line 4:
'''Coral-Mini Server'''
'''Coral-Mini Server'''


Apache with the release of 2.2.18 made a small change, extract from the change log '''''Added shebang check for '! so that .vbs scripts work as CGI''''' hidden in that statement is the ability not only to run VBScripts as CGI but also JavaScripts. A more profound implication is the ability to create dynamic web sites using Apache alone removing the bloat of PHP and MySQL. This tutorial revisits the mini-server series and updates the basic Apache server to include the new Apache 2.2.21 core and control architecture from Uniform Server Coral-8 series.
Apache, with the release of 2.2.18, made a small change. Quoting from the change log: "'''''Added shebang check for '! so that .vbs scripts work as CGI'''''." Hidden in that statement is the ability not only to run VBScripts as CGI but also JavaScripts. A more profound implication is the ability to create dynamic web sites using Apache alone, removing the bloat of PHP and MySQL. This tutorial revisits the mini-server series and updates the basic Apache server to include the new Apache 2.2.21 core, and the control architecture from The Uniform Server Coral-8 series.


This new mini-server, Coral-Mini is used for running tutorial examples. These examples provide an introduction to CGI scripting, they are written in VBScript and JavaScript. Before looking at CGI scripting the mini-server architecture is first covered.
This new mini-server, Coral-Mini, is used for running the examples for this tutorial. These examples provide an introduction to CGI scripting. They are written in VBScript and JavaScript. Before we look at CGI scripting, we will explore the mini-server architecture.


__TOC__
__TOC__
Line 24: Line 24:
* The server logs all web requests and errors.
* The server logs all web requests and errors.
* Includes only the minimum modules to meet specification.
* Includes only the minimum modules to meet specification.
'''''[[#top | Top]]'''''


===Download===
===Download===
Download the Coral-Mini server from SourceForge [http://sourceforge.net/projects/miniserver/files/MiniServer/Coral_MiniServer/ Project Page] save the file '''coral_mini_server.exe''' to any folder of your choice.
Download the Coral-Mini server from SourceForge [http://sourceforge.net/projects/miniserver/files/MiniServer/Coral_MiniServer/ Project Page] and save the file '''coral_mini_server.exe''' to any folder of your choice.


===Extract files===
===Extract the files===
Double click on coral_mini_server.exe, starts the extraction process. No need to change the folder destination. Click extract; this creates a new folder '''MiniServer''' containing four files and four folders.
Double click on coral_mini_server.exe, which starts the extraction process. No need to change the folder destination. Click extract; this creates a new folder '''MiniServer''' which contains four files and four folders.


'''Files:'''
'''Files:'''
# Start_Coral_Mini.exe - Double click to start the server
# Start_Coral_Mini.exe - Double click to start the server
# Stop_Coral_Mini.exe  - Double click to stop server
# Stop_Coral_Mini.exe  - Double click to stop the server
# tutorial.bat - Displays this tutorial in default browser
# tutorial.bat - Displays this tutorial in the default browser
# READ_ME.txt - Provides information for changing ports.
# READ_ME.txt - Provides information for changing ports.


'''Folders:'''
'''Folders:'''
# apache2 - Apache sever files and configuration
# apache2 - Apache server files and configuration
# control - File to start and stop server
# control - File to start and stop server
# docs - Tutorial and working scripts from tutorial. Licenses for server.
# docs - Tutorial and working scripts from tutorial. Licenses for server.
# www - Root folder. Apache servers files from this folder.   
# www - Root folder. Apache serves files from this folder.   


===Test===
===Test===
Line 49: Line 47:
Testing is straight forward.
Testing is straight forward.


# Start the server by double clicking on Start_Coral_Mini.exe (automatically configures server paths.)
# Start the server by double clicking on Start_Coral_Mini.exe This automatically configures the server paths.
# Start a web browser.
# Start a web browser.
# Type '''<nowiki>http://localhost:8081/</nowiki>''' into the browser address bar.
# Type '''<nowiki>http://localhost:8081/</nowiki>''' into the browser address bar.
# The index page index.html is displayed.
# The default page index.html is displayed.
# Stop the server by double clicking on Stop_Coral_Mini.exe
# Stop the server by double clicking on Stop_Coral_Mini.exe


==Apache modules==
==Apache modules==
Apache comes with a vast array of modules a full list and description can be found here [http://httpd.apache.org/docs/2.2/mod/ Apache Docs] Modules used in the Coral-mini server are listed below, note the core module is part of the main binary (program) and loaded by default.
Apache comes with a vast array of modules. A full list and description can be found in the [http://httpd.apache.org/docs/2.2/mod/ Apache Docs]. Modules used in the Coral-Mini server are listed below. Note that the core module is part of the main binary (program) and loaded by default.


Highlighted in bold are separate modules these are loaded using Apache's configuration file '''httpd.conf'''.  
Key modules are highlighted in bold. These are loaded using Apache's configuration file '''httpd.conf'''.  


{| cellpadding="4" cellspacing="1" style="background:#000000;"
{| cellpadding="4" cellspacing="1" style="background:#000000;"
Line 67: Line 65:


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|core||Core Apache HTTP Server features that are always available included in the binary (program).
|core||Core Apache HTTP Server features that are always available; included in the binary (program).


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|mpm_winnt.c||WinNT MPM part of the Windows Apache core. A Multi-Processing Module (MPM) it is the default for Windows NT operating systems. Uses a single control process which launches a single child process which in turn creates threads to handle requests. (This is the reason you will see two Apache processes in task manager)
|mpm_winnt.c||WinNT MPM is part of the Windows Apache core. A Multi-Processing Module (MPM), it is the default for Windows NT operating systems. It uses a single control process which launches a single child process which in turn creates threads to handle requests. (This is the reason you will see two Apache processes in task manager).


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|'''authz_host_module'''||Group authorizations based on host (name or IP address). Required to restrict access to folders etc.
|'''authz_host_module'''||Group authorizations based on host (name or IP address). Required to restrict access to folders, etc.


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|'''mod_dir'''||Provides for "trailing slash" redirects and serving directory index files. (Optional but nice to have otherwise a user needs to type index.html on entry to a folder or for initial web site access. It prevents this error message: The requested URL / was not found on this server.)
|'''mod_dir'''||Provides for "trailing slash" redirects and serving directory index files. (Optional, but nice to have. Otherwise a user needs to type index.html on entry to a folder or for initial web site access. It prevents this error message: The requested URL / was not found on this server.)


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 82: Line 80:


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|'''mod_mime'''||Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding) Note without this module the file will be served as plain text. DefaultType text/plain
|'''mod_mime'''||Associates the requested file name extension with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding) Note that without this module, the file will be served as plain text. The DefaultType is text/plain


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|'''mod_rewrite'''||Provides rewriting of requested URLs on the fly. Allows masking of file extensions for example a request for index.htm results in page index.vbs being run on the server and the result returned as index.htm
|'''mod_rewrite'''||Provides rewriting of requested URLs on the fly. Allows masking of file extensions; for example, a request for index.htm results in page index.vbs being run on the server and the result returned as index.htm


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
|'''mod_cgi'''||Provides an interface for running CGI scripts. Scripts that require running are targeted using the AddHandler directive this directive associates file extensions with CGI scripts.
|'''mod_cgi'''||Provides an interface for running CGI scripts. Scripts that require running are targeted using the AddHandler directive. This directive associates file extensions with CGI scripts.
|}
|}
'''''[[#top | Top]]'''''
 
==Configuring Apache==
==Configuring Apache==
On starting Apache it is supplied with the location and name of a configuration file this overrides the default location compiled into the program. Its common practice to name the file '''httpd.conf''' and place it in a sub-folder named '''conf''' Coral-mini uses this convention.
When Apache is started, it is supplied with the location and name of a configuration file. This overrides the default location compiled into the program. It's common practice to name the file '''httpd.conf''' and place it in a sub-folder named '''conf'''. Coral-Mini uses this convention.


Coral-Mini Server uses the following configuration file: MiniServer\apache2\conf\'''httpd.conf'''
Coral-Mini server uses this configuration file: MiniServer\apache2\conf\'''httpd.conf'''


'''Note:''' Apache’s example configuration file contains a lot of detailed information I personally find this confusing and prefer to remove this detail.
'''Note:''' Apache’s example configuration file contains a lot of detailed information. I personally find this confusing and have removed this detail.


{| cellpadding="4" cellspacing="1" style="background:#000000;"
{| cellpadding="4" cellspacing="1" style="background:#000000;"
Line 112: Line 110:
<nowiki>#</nowiki> V 1.0 20-9-2011  
<nowiki>#</nowiki> V 1.0 20-9-2011  
|
|
General information a reminder what the configuration is for.  
General information. A reminder what the configuration is for.  


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 129: Line 127:


'''Note:''' For some modules the order is important.<br />
'''Note:''' For some modules the order is important.<br />
'''Tip:''' Check Apache’s example files and list them in that order, avoids any problems.
'''Tip:''' Check Apache’s example files and list them in that order to avoid any problems.


Order of priority is from bottom to top; hence if a module is dependent on another it should come first in the list.  
Order of priority is from bottom to top; hence if a module is dependent on another it should come first in the list.  
Line 150: Line 148:
'''DirectoryIndex''' index.html index.htm
'''DirectoryIndex''' index.html index.htm
|
|
These settings are common to the main server. Most settings in this section have defaults however I like to see what I am using hence list them regardless.
These settings are common to the main server. Most settings in this section have defaults. However I like to see what I am using, hence list them regardless.


* '''Listen:''' Server listening port, standard is port 80 change this to move the server to another port.
* '''Listen:''' Server listening port. Standard is port 80 . change this to move the server to another port.
* '''ServerName:''' For reliability always specify a host name and port. Note: localhost is valid however if you have a DNS entry use your fully qualified domain name eg www.fred.com Alternatively you can leave this as localhost and use your fully qualified domain name in a Vhost section (not covered in this server example).
* '''ServerName:''' For reliability always specify a host name and port. Note: localhost is valid, however if you have a DNS entry, use your fully qualified domain name, eg www.fred.com. Alternatively you can leave this as localhost and use your fully qualified domain name in a Vhost section (not covered in this server example).
* '''ServerRoot:''' Path where the Apache program is located.
* '''ServerRoot:''' Path where the Apache program is located.
* '''DocumentRoot:''' Folder where your web-site will be served from.
* '''DocumentRoot:''' Folder where your web-site will be served from.
* '''DirectoryIndex:''' When a user requests a page supplying only a folder name (example fred.com) the index page is automatically returned by default. Note you can have more than one index page in the same folder with a different file extension. Order of priority left to right, first one found in the list is returned, all others are ignored.
* '''DirectoryIndex:''' When a user requests a page supplying only a folder name (example: fred.com), the index page is automatically returned by default. Note that you can have more than one index page in the same folder with a different file extension. Order of priority is left to right; first one found in the list is returned, all others are ignored.


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 170: Line 168:
MaxRequestsPerChild 0  
MaxRequestsPerChild 0  
|
|
Most settings in this section have defaults however again I like to see what I am using hence list them regardless.
Most settings in this section have defaults. However again I like to see what I am using, hence list them regardless.


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 197: Line 195:
Each directory to which Apache has access can be configured with respect to which services and features are allowed and/or disabled in that directory (including its sub-directories).
Each directory to which Apache has access can be configured with respect to which services and features are allowed and/or disabled in that directory (including its sub-directories).


Apache has access to all folders and files on the drive it is installed on
Apache has access to all folders and files on the drive where it is installed,
hence the '''first Directory''' directive is very restrictive:
hence the '''first Directory''' directive is very restrictive:


* '''Options None:''' Turns off, directory browsing, server side includes, CGI execution, follow symbolic links.
* '''Options None:''' Turns off directory browsing, server side includes, CGI execution, follow symbolic links.
* '''AllowOverride None:''' Turns off support for .htaccess files
* '''AllowOverride None:''' Turns off support for .htaccess files
* '''Deny from all:''' No one allowed access.
* '''Deny from all:''' No one allowed access.


Only way to gain access is to target each folder in turn and open it up as required second Directory directive targets folder www this contains your web site.
The only way to enable access is to target each folder in turn and open it up as required. Second Directory directive targets folder www which contains your web site.


* '''Options Indexes Includes:''' Turns on, directory browsing and server side includes.
* '''Options Indexes Includes:''' Turns on directory browsing and server side includes.
* '''AllowOverride All:''' Turns on support for .htaccess files
* '''AllowOverride All:''' Turns on support for .htaccess files
* '''Allow from all:''' Everyone allowed access to folder www and its sub-folders.
* '''Allow from all:''' Everyone is allowed access to folder www and its sub-folders.


The '''AccessFileName''' directive defines the file name to use for secondary configuration files by convention the name is '''.htaccess'''
The '''AccessFileName''' directive defines the file name to use for secondary configuration files. By convention the name is '''.htaccess'''
Access to these files is retricted using the '''Files''' directive. The regex also prevents '''.htpasswd''' files from being viewed by Web clients.  
Access to these files is restricted using the '''Files''' directive. The regex also prevents '''.htpasswd''' files from being viewed by Web clients.  


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 221: Line 219:
TypesConfig /usr/local/apache2/conf/mime.types  
TypesConfig /usr/local/apache2/conf/mime.types  
|
|
In conjunction with the mime_module the directive TypesConfig is used to specify a file which maps extensions onto MIME types. Note without the module and this file served pages will be in plain text.<br />
In conjunction with the mime_module, the directive TypesConfig is used to specify a file which maps extensions onto MIME types. Note that without the module and this file, served pages will be in plain text.<br />
Coral-Mini uses a greatly reduced mime.types file it contains only commonly used types.  
Coral-Mini uses a greatly reduced mime.types file; it contains only commonly used types.  


|-style="background:#f5f5f5;"
|-style="background:#f5f5f5;"
Line 245: Line 243:


|}
|}
'''''[[#top | Top]]'''''
 
==Configuring Apache CGI - Overview==
==Configuring Apache CGI - Overview==
The following provides a general overview how to configuring Apache to run CGI scripts. In order to run CGI programs Apache requires configuration directives to permit CGI execution. You can use one of the following methods to permit CGI execution
The following provides a general overview of how to configuring Apache to run CGI scripts. In order to run CGI programs, Apache requires configuration directives to permit CGI execution.  


'''''Note'':''' All three methods require the mod_cgi module to be enabled as shown below:
'''''Note'':''' All three methods require the mod_cgi module to be enabled as shown below:
Line 253: Line 251:
LoadModule cgi_module modules/mod_cgi.so
LoadModule cgi_module modules/mod_cgi.so
</pre>
</pre>
===Method 1 ScriptAlias===
 
The '''ScriptAlias''' directive tells Apache that a particular directory is set aside for CGI programs. Apache now assumes every file in this directory is a CGI program. When a page from this folder is requested Apache will attempt to execute it using the appropriate program.
You can select one of the following methods to permit CGI execution.
 
===Method 1: ScriptAlias===
The '''ScriptAlias''' directive tells Apache that a particular directory is set aside for CGI programs. Apache now assumes every file in this directory is a CGI program. When a page from this folder is requested, Apache will attempt to execute it using the appropriate program.


The ScriptAlias directive looks like:
The ScriptAlias directive looks like:
Line 260: Line 261:
ScriptAlias /cgi-bin "C:/UniServer/cgi-bin/"
ScriptAlias /cgi-bin "C:/UniServer/cgi-bin/"
</pre>
</pre>
The directive defines a URL prefix (cgi-bin) that is mapped to a particular folder (directory). ScriptAlias informs Apache everything under that URL prefix will be considered a CGI program.
The directive defines a URL prefix (cgi-bin) that is mapped to a particular folder (directory). ScriptAlias informs Apache that everything under that URL prefix will be considered a CGI program.


For example, if the URL <nowiki>http://localhost/cgi-bin/test.pl</nowiki> is requested, Apache will attempt to execute the perl file C:/UniServer/cgi-bin/test.pl and return the output.
For example, if the URL <nowiki>http://localhost/cgi-bin/test.pl</nowiki> is requested, Apache will attempt to execute the perl file C:/UniServer/cgi-bin/test.pl and return the output.
Line 266: Line 267:
Similarly, if the <nowiki>URL http://localhost/cgi-bin/test.vbs</nowiki> is requested, Apache will attempt to execute the VBScript file C:/UniServer/cgi-bin/test.vbs and return the output.
Similarly, if the <nowiki>URL http://localhost/cgi-bin/test.vbs</nowiki> is requested, Apache will attempt to execute the VBScript file C:/UniServer/cgi-bin/test.vbs and return the output.


===Method 2 Folders===
===Method 2: Folders===
On hosted sites for security reasons CGI programs are restricted to ScriptAlias'ed folders. However you can run CGI programs from any folder. As an alternative to ScriptAlias you can use the Options directive, inside your main server configuration file, to specify that CGI execution is permitted in a particular directory.
On hosted sites, for security reasons, CGI programs are restricted to ScriptAlias'ed folders. However you can run CGI programs from any folder. As an alternative to ScriptAlias you can use the Options directive (inside your main server configuration file) to specify that CGI execution is permitted in a particular directory.
<pre>
<pre>
<Directory "C:/UniServer/www/somedir/">
<Directory "C:/UniServer/www/somedir/">
Line 275: Line 276:
The Options ExecCGI directive informs Apache to permit the execution of CGI files.
The Options ExecCGI directive informs Apache to permit the execution of CGI files.


===Method 3 .htaccess===
===Method 3: .htaccess===
Using '''.htaccess''' files allow you to set configuration directives on a per-directory basis. Apache looks in a folder from which it is serving for this file and applies the directives found. To enable the use of .htaccess files edit the Apache configuration files as follows:
Using '''.htaccess''' files allow you to set configuration directives on a per-directory basis. Apache looks for this file in a folder from which it is serving and applies the directives found. To enable the use of .htaccess files, edit the Apache configuration files as follows:


Change or add the AllowOverride directive in a specific folder directive for example www as shown below:
Change or add the AllowOverride directive in a specific folder directive; for example, www as shown below:


<pre>
<pre>
Line 286: Line 287:
</Directory>
</Directory>
</pre>
</pre>
If not already included add the following block of code to prevent .htaccess and .htpasswd files from being viewed by Web clients:
If not already included, add the following block of code to prevent .htaccess and .htpasswd files from being viewed by Web clients:
<pre>
<pre>
<Files ~ "^\.ht">
<Files ~ "^\.ht">
Line 299: Line 300:
Options +FollowSymlinks
Options +FollowSymlinks
</pre>
</pre>
Which tells Apache that execution of CGI programs is permitted in this folder.
This tells Apache that execution of CGI programs is permitted in this folder.


'''''Note'':''' All Uniform Servers have been pre-configured to allow the use of .htaccess files.
'''''Note'':''' All of The Uniform Servers have been pre-configured to allow the use of .htaccess files.


'''''[[#top | Top]]'''''
===AddHandler===
===AddHandler===
Using either of the above methods Apache will attempt to execute every file as a CGI script this includes files such as css and images. Clearly these are not CGI scripts and would produce errors when executed. To resolve this you need to inform the server what files are genuine CGI scripts using the AddHandler directive.
Using either of the above methods, Apache will attempt to execute every file as a CGI script. This includes files such as css and images. Clearly these are not CGI scripts and would produce errors when executed. To avoid this you need to inform the server what files are genuine CGI scripts by using the AddHandler directive.
<pre>
<pre>
AddHandler cgi-script .cgi .pl .vbs
AddHandler cgi-script .cgi .pl .vbs
</pre>
</pre>
The above AddHandler directive informs the server to treat all files with a cgi, pl or vbs extension as CGI programs:
The above AddHandler directive informs the server to treat all files with a cgi, pl or vbs extension as CGI programs.
 


'''''[[#top | Top]]'''''
==Test folder and .htaccess==
==Test folder and .htaccess==
Tutorial examples require a test folder and .htaccess file.
The tutorial examples require a test folder and .htaccess file.
*In folder MiniServer\www create a new folder '''vbs_test''' this will contain your tutorial scripts.
*In folder MiniServer\www create a new folder '''vbs_test''' in which you will put your tutorial scripts.
*Inside this folder create a new '''.htaccess''' file with the following content:
*Inside this folder create a new '''.htaccess''' file with the following content:


Line 321: Line 321:
|'''Note:'''||'''.htaccess''' content
|'''Note:'''||'''.htaccess''' content
|-
|-
|If you have problems creating the .htaccess file copy the one from folder www.
|If you have problems creating the .htaccess file, copy the one from folder www.
Edit the file: Delete all lines and add the three lines shown on right and save.
Edit the file: Delete all lines and add the three lines shown on right and save.
|
|
Line 330: Line 330:
</pre>
</pre>
|}
|}
'''''[[#top | Top]]'''''
 
==Summary==
==Summary==
The above has shown how to configure Apache to run CGI scripts.
The above has shown how to configure Apache to run CGI scripts.
Line 340: Line 340:
Options +FollowSymlinks
Options +FollowSymlinks
</pre>
</pre>
Although tutorial examples specifically refer to the Coral-Mini Server they can be run on any Uniform Server that contains Apache 2.2.18 or above. Just create the test folder and add the .htaccess file described above.
Although tutorial examples specifically refer to the Coral-Mini Server they can be run on any of The Uniform Servers that contain Apache 2.2.18 or above. Just create the test folder and add the .htaccess file as described above.


'''''[[#top | Top]]'''''
==Where to next==
==Where to next==
 
The [[CGI: VBScript CGI|next page]] details how to format a VBScript for running as a CGI script.
[[CGI: VBScript CGI|Next page]] details how to format a VBScript for running as a CGI script.


----
----

Latest revision as of 16:10, 17 October 2012

Coral-Mini Server

Apache, with the release of 2.2.18, made a small change. Quoting from the change log: "Added shebang check for '! so that .vbs scripts work as CGI." Hidden in that statement is the ability not only to run VBScripts as CGI but also JavaScripts. A more profound implication is the ability to create dynamic web sites using Apache alone, removing the bloat of PHP and MySQL. This tutorial revisits the mini-server series and updates the basic Apache server to include the new Apache 2.2.21 core, and the control architecture from The Uniform Server Coral-8 series.

This new mini-server, Coral-Mini, is used for running the examples for this tutorial. These examples provide an introduction to CGI scripting. They are written in VBScript and JavaScript. Before we look at CGI scripting, we will explore the mini-server architecture.

Coral-Mini Server Specification

Coral-Mini Server has the following specification:

  • Server is portable and can be installed on a USB memory stick.
  • Server core uses Apache 2.2.21
  • Serves by default HTML pages.
  • Dynamic web pages implemented using either VBScript or JavaScript
  • Capability to use .htaccess files for configuration
  • Capability to include external pages.
  • Uses a file-based database.
  • Underlying technology used is hidden.
  • The server logs all web requests and errors.
  • Includes only the minimum modules to meet specification.

Download

Download the Coral-Mini server from SourceForge Project Page and save the file coral_mini_server.exe to any folder of your choice.

Extract the files

Double click on coral_mini_server.exe, which starts the extraction process. No need to change the folder destination. Click extract; this creates a new folder MiniServer which contains four files and four folders.

Files:

  1. Start_Coral_Mini.exe - Double click to start the server
  2. Stop_Coral_Mini.exe - Double click to stop the server
  3. tutorial.bat - Displays this tutorial in the default browser
  4. READ_ME.txt - Provides information for changing ports.

Folders:

  1. apache2 - Apache server files and configuration
  2. control - File to start and stop server
  3. docs - Tutorial and working scripts from tutorial. Licenses for server.
  4. www - Root folder. Apache serves files from this folder.

Test

Testing is straight forward.

  1. Start the server by double clicking on Start_Coral_Mini.exe This automatically configures the server paths.
  2. Start a web browser.
  3. Type http://localhost:8081/ into the browser address bar.
  4. The default page index.html is displayed.
  5. Stop the server by double clicking on Stop_Coral_Mini.exe

Apache modules

Apache comes with a vast array of modules. A full list and description can be found in the Apache Docs. Modules used in the Coral-Mini server are listed below. Note that the core module is part of the main binary (program) and loaded by default.

Key modules are highlighted in bold. These are loaded using Apache's configuration file httpd.conf.

Module Name Description
core Core Apache HTTP Server features that are always available; included in the binary (program).
mpm_winnt.c WinNT MPM is part of the Windows Apache core. A Multi-Processing Module (MPM), it is the default for Windows NT operating systems. It uses a single control process which launches a single child process which in turn creates threads to handle requests. (This is the reason you will see two Apache processes in task manager).
authz_host_module Group authorizations based on host (name or IP address). Required to restrict access to folders, etc.
mod_dir Provides for "trailing slash" redirects and serving directory index files. (Optional, but nice to have. Otherwise a user needs to type index.html on entry to a folder or for initial web site access. It prevents this error message: The requested URL / was not found on this server.)
mod_log_config Logging of the requests made to the server. (Not required for server operation however extremely useful to see what the server is doing.)
mod_mime Associates the requested file name extension with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding) Note that without this module, the file will be served as plain text. The DefaultType is text/plain
mod_rewrite Provides rewriting of requested URLs on the fly. Allows masking of file extensions; for example, a request for index.htm results in page index.vbs being run on the server and the result returned as index.htm
mod_cgi Provides an interface for running CGI scripts. Scripts that require running are targeted using the AddHandler directive. This directive associates file extensions with CGI scripts.

Configuring Apache

When Apache is started, it is supplied with the location and name of a configuration file. This overrides the default location compiled into the program. It's common practice to name the file httpd.conf and place it in a sub-folder named conf. Coral-Mini uses this convention.

Coral-Mini server uses this configuration file: MiniServer\apache2\conf\httpd.conf

Note: Apache’s example configuration file contains a lot of detailed information. I personally find this confusing and have removed this detail.

httpd.conf located in folder: *\MiniServer\apache2\conf Comments

# File name: http.conf
# Created By: The Uniform Server Development Team
# Edited Last By: Mike Gleaves (ric)
# Main Apache 2.2.21 HTTP server configuration file.
# V 1.0 20-9-2011

General information. A reminder what the configuration is for.

#=======================================================
# Modules
#=======================================================
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule dir_module modules/mod_dir.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule mime_module modules/mod_mime.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule cgi_module modules/mod_cgi.so

Lists all modules to be loaded.

Note: For some modules the order is important.
Tip: Check Apache’s example files and list them in that order to avoid any problems.

Order of priority is from bottom to top; hence if a module is dependent on another it should come first in the list.

# ========================================
# Basic settings
# ========================================
Listen 8081
ServerName localhost:8081
ServerAdmin fred@www.somedomain.com
UseCanonicalName Off
ServerSignature Off
HostnameLookups Off
ServerTokens Prod
ServerRoot "F:/coral_mini/MiniServer/apache2"
DocumentRoot "F:/coral_mini/MiniServer/www"
PidFile logs/httpd.pid
DirectoryIndex index.html index.htm

These settings are common to the main server. Most settings in this section have defaults. However I like to see what I am using, hence list them regardless.

  • Listen: Server listening port. Standard is port 80 . change this to move the server to another port.
  • ServerName: For reliability always specify a host name and port. Note: localhost is valid, however if you have a DNS entry, use your fully qualified domain name, eg www.fred.com. Alternatively you can leave this as localhost and use your fully qualified domain name in a Vhost section (not covered in this server example).
  • ServerRoot: Path where the Apache program is located.
  • DocumentRoot: Folder where your web-site will be served from.
  • DirectoryIndex: When a user requests a page supplying only a folder name (example: fred.com), the index page is automatically returned by default. Note that you can have more than one index page in the same folder with a different file extension. Order of priority is left to right; first one found in the list is returned, all others are ignored.

# ========================================
# HTTP and performance settings
# ========================================
Timeout 300
KeepAlive On
MaxKeepAliveRequests 100
KeepAliveTimeout 15
ThreadsPerChild 250
MaxRequestsPerChild 0

Most settings in this section have defaults. However again I like to see what I am using, hence list them regardless.

# ========================================
# Access control
# ========================================
<Directory />
  Options None
  AllowOverride None
  Order deny,allow
  Deny from all
</Directory>

<Directory "F:/coral_mini/MiniServer/www/">
  Options Indexes Includes
  AllowOverride All
  Order allow,deny
  Allow from all
</Directory>

AccessFileName .htaccess
<Files ~ "^\.ht">
  Order allow,deny
  Deny from all
</Files>

Each directory to which Apache has access can be configured with respect to which services and features are allowed and/or disabled in that directory (including its sub-directories).

Apache has access to all folders and files on the drive where it is installed, hence the first Directory directive is very restrictive:

  • Options None: Turns off directory browsing, server side includes, CGI execution, follow symbolic links.
  • AllowOverride None: Turns off support for .htaccess files
  • Deny from all: No one allowed access.

The only way to enable access is to target each folder in turn and open it up as required. Second Directory directive targets folder www which contains your web site.

  • Options Indexes Includes: Turns on directory browsing and server side includes.
  • AllowOverride All: Turns on support for .htaccess files
  • Allow from all: Everyone is allowed access to folder www and its sub-folders.

The AccessFileName directive defines the file name to use for secondary configuration files. By convention the name is .htaccess Access to these files is restricted using the Files directive. The regex also prevents .htpasswd files from being viewed by Web clients.

# ========================================
# MIME encoding
# ========================================
DefaultType text/plain
TypesConfig /usr/local/apache2/conf/mime.types

In conjunction with the mime_module, the directive TypesConfig is used to specify a file which maps extensions onto MIME types. Note that without the module and this file, served pages will be in plain text.
Coral-Mini uses a greatly reduced mime.types file; it contains only commonly used types.

# ========================================
# Logs: debug, info, notice, warn, error, crit
# ========================================
LogLevel warn
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
&\"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
LogFormat "%{Referer}i -> %U" referer
LogFormat "%{User-agent}i" agent
ErrorLog "logs/error_log"
CustomLog "logs/access.log" combined
# ========================================

This sets up the appropriate log format (what details are logged) and specifies the log file name and location.

Note: debug eats disk space hence warn is a reasonable setting.

Configuring Apache CGI - Overview

The following provides a general overview of how to configuring Apache to run CGI scripts. In order to run CGI programs, Apache requires configuration directives to permit CGI execution.

Note: All three methods require the mod_cgi module to be enabled as shown below:

LoadModule cgi_module modules/mod_cgi.so

You can select one of the following methods to permit CGI execution.

Method 1: ScriptAlias

The ScriptAlias directive tells Apache that a particular directory is set aside for CGI programs. Apache now assumes every file in this directory is a CGI program. When a page from this folder is requested, Apache will attempt to execute it using the appropriate program.

The ScriptAlias directive looks like:

ScriptAlias /cgi-bin "C:/UniServer/cgi-bin/"

The directive defines a URL prefix (cgi-bin) that is mapped to a particular folder (directory). ScriptAlias informs Apache that everything under that URL prefix will be considered a CGI program.

For example, if the URL http://localhost/cgi-bin/test.pl is requested, Apache will attempt to execute the perl file C:/UniServer/cgi-bin/test.pl and return the output.

Similarly, if the URL http://localhost/cgi-bin/test.vbs is requested, Apache will attempt to execute the VBScript file C:/UniServer/cgi-bin/test.vbs and return the output.

Method 2: Folders

On hosted sites, for security reasons, CGI programs are restricted to ScriptAlias'ed folders. However you can run CGI programs from any folder. As an alternative to ScriptAlias you can use the Options directive (inside your main server configuration file) to specify that CGI execution is permitted in a particular directory.

<Directory "C:/UniServer/www/somedir/">
  Options ExecCGI
</Directory>

The Options ExecCGI directive informs Apache to permit the execution of CGI files.

Method 3: .htaccess

Using .htaccess files allow you to set configuration directives on a per-directory basis. Apache looks for this file in a folder from which it is serving and applies the directives found. To enable the use of .htaccess files, edit the Apache configuration files as follows:

Change or add the AllowOverride directive in a specific folder directive; for example, www as shown below:

<Directory "C:/UniServer/www/">
  Options Indexes Includes
  AllowOverride All
</Directory>

If not already included, add the following block of code to prevent .htaccess and .htpasswd files from being viewed by Web clients:

<Files ~ "^\.ht">
    Order allow,deny
    Deny from all
    Satisfy All
</Files>

With the above directives in-place you can now use .htacces files. Create an .htaccess file in the folder where you want to run CGI scripts and add the following line:

Options +ExecCGI
Options +FollowSymlinks

This tells Apache that execution of CGI programs is permitted in this folder.

Note: All of The Uniform Servers have been pre-configured to allow the use of .htaccess files.

AddHandler

Using either of the above methods, Apache will attempt to execute every file as a CGI script. This includes files such as css and images. Clearly these are not CGI scripts and would produce errors when executed. To avoid this you need to inform the server what files are genuine CGI scripts by using the AddHandler directive.

AddHandler cgi-script .cgi .pl .vbs

The above AddHandler directive informs the server to treat all files with a cgi, pl or vbs extension as CGI programs.


Test folder and .htaccess

The tutorial examples require a test folder and .htaccess file.

  • In folder MiniServer\www create a new folder vbs_test in which you will put your tutorial scripts.
  • Inside this folder create a new .htaccess file with the following content:
Note: .htaccess content
If you have problems creating the .htaccess file, copy the one from folder www.

Edit the file: Delete all lines and add the three lines shown on right and save.

AddHandler cgi-script .vbs 
Options +ExecCGI
Options +FollowSymlinks

Summary

The above has shown how to configure Apache to run CGI scripts.

Running VBScripts requires an .htaccess file placed in the directory containing the scripts. This file enables script execution and has the following content:

AddHandler cgi-script .vbs 
Options +ExecCGI
Options +FollowSymlinks

Although tutorial examples specifically refer to the Coral-Mini Server they can be run on any of The Uniform Servers that contain Apache 2.2.18 or above. Just create the test folder and add the .htaccess file as described above.

Where to next

The next page details how to format a VBScript for running as a CGI script.