Installation and Configuration
Installation
3q is installed by copying it into your web server's CGI directory. There is no standard CGI directory (but /usr/lib/cgi-bin is often used today) so check your web server documentation for details.
Script Customization
There are some things you can change in the 3q script code. All these settings are found at the top of the script inside the initial BEGIN block.
- program
-
defines the name of the script as it is used in futher script settings and error messages.
- configdir
-
is the directory where 3q expects all its configuration files. The default is /etc/3q.
- cfgsfx
-
suffix that is appended to a configuration key to get the configuration filename, default: -3q.conf.
- magicext
-
file extension for 3q script files, default: .3q.
- allownoconfig
-
enables or disables to run without a configuration, must be `
1' for using the apache action handler mode. Assuming the script defaults from above then /etc/3q/main-3q.conf would be the configuration file for the `main' (or default) configuration. - usefiles
- writes the encoded 3q script into a temporary file and passes this gawk in the execution phase instead of giving the source code directly on the command line.
Configuration
In normal (non action-handler) operation 3p expects a configuration file that is derived from the configuration key in the request URL. In case there is no key in the URL the default `main' is used.
The following configuration options are supported.
- dir directory
-
defines the base directory where the script files for this configuration are stored. 3q will server all files (script files or others) from this directory and all subdirectories. Excluded are file that start with a dot `.'.
This option is required.
- accept ipnum/mask ...
-
defines an IP-address based acl (access control list). Only clients in a network on the accept list are allowed to access. Any argument on the list can be prefixed with a minus `-' to deny access for that host or network. If the client matches more than one argument on the acl the one with the smallest network mask is applied (“best match”). If an acl is defined the default is to deny access.
- deny ipnum/mask ...
-
the opposite of accept.
- set var val defines the variable var which is later passed to the 3q or CGI script.
Unknown configuration options are reported to stderr.
Usually 3q is run with a minimal configuration which defines at least a base directory for your 3q script files (for operation as apache action handler see below). 3q supports separate configurations which are selected by an optional configuration key that is part of the request URL:
http://servername/path-to-cgi-dir/3q/configuration-key/path-to-file
where
- configuration-key
-
is an alphanumeric character string that is used as basename for the configuration file. If no configuration-key is given 3q assumes `main'.
- path-to-file
- is the path to the requested file under the base directory for that configuration. This is not limited to 3q script files.
Example: If your configuration key is `abc' then your configuration file would be /etc/3q/abc-3q.conf and the URL to this configuration's homepage /cgi-bin/3q/abc/.
The main configuration: For the configuration key `main' the configuration file is /etc/3q/main-3q.conf and the base URL /cgi-bin/3q/main/ and - by convention - /cgi-bin/3q/ too.
Using 3q as Apache Action Handler
3q can be used without configuration file as action handler script. For this make sure that the variable allownoconfig is set to 1 (you find this assignment at the beginning of the 3q script).
Furthermore configure 3q as an action handler, put
AddHandler 3q-file .3q Action 3q-file /cgi-bin/3q
somewhere into your apache configuration.
The action handler mode can be distinguished from “normal” mode by inspecting the CONFIG environment variable. If and only if 3q is called as action handler the CONFIG variable is empty.