package require cfg
cfg::init baseName ?masterConfigFile? ?configDir?
cfg::allowed logToken config section arg arg...
cfg::getConstant logToken config section name
First, the procedures defined by the cfg package are described in separate sections for each procedure. Then, the section CONFIGURATIONS AND CONFIGURATION FILES describes how configurations are organized and located on the local file system. The sections SECTION, ALLOW, DISALLOW and CONSTANT each describe one of the major constructs that can appear in a configuration. Next, the section on ARGUMENT MATCHING describes the process whereby the package decides whether a specific configuration option is allowed or not by this configuration. Finally, we close with an example configuration file that demonstrates how all aspects of the package work together.
Configuration are Tcl scripts, and they are sourced into the master interpreter of an application. The syntax and organization of configuration files has been designed to be as readable as possible for humans who may not be expert Tcl programmers.
When an application starts, the configuration package reads the configuration for the application to control how the application operates. The name of the application is available (and can be stored into) cfg::name. For the Tcl plugin, the application name is plugin, and the configuration file is plugin.cfg.
The following four sections, SECTION, ALLOW, DISALLOW and CONSTANT, describe the main configuration statements that can appear in a configuration.
The word section in a section statement is followed by an arbitrary number of other words that together make up the name of the section. Configuration statements in a section must contain at least the number of arguments given in the section statement.
The allow statement specifies that a call to cfg::allowed with matching arguments returns 1 if no matching disallow statements appear in this section. The section on ARGUMENT MATCHING explains the syntax of arguments to allow and the rules for matching arguments in the allow statement with arguments given in the call to cfg::allowed.
Each allow statement must have at least the number of arguments given in the section statement defining the section. Thus, an allow statement in a section named hosts ports must have two or more arguments.
The disallow statements says that a call to cfg::allowed with matching arguments returns 0. See the section on ARGUMENT MATCHING for an explanation of the matching rules and the supported syntax for arguments.
Each disallow statement must have at least the number of arguments given in the section statement defining the section in which it appears. Thus, a disallow statement in a section named redhex greenhex bluehex must have three or more arguments.
The constant statement declares a constant with name name and value value in this section. The value can be retrieved through a call to cfg::getConstant.
Several special forms are provided to express common cases in allow and disallow statements:
The arguments in an allow or disallow statement are substituted using subst before they are matched against corresponding arguments in cfg::allowed. The matching process provides several Tcl variables that have values retrieved from the attributes by the same name associated with the logToken in the call to cfg::allowed. As was explained above, by convention the logToken is the name of an interpreter in which a Tclet is executed. Thus during a call to cfg::allowed tclet1 ..., the value of the Tcl variable originURL is the canonical form of the URL from which the Tclet tclet1 was loaded. The variables originURL, originPageURL, originHomeDirURL, originProto, originHost, originSocketHost, originPort, originPath, originKey, browserArgs, script, windowGeometry, completeWindowGeometry, apiVersion, userAgent and Tk are predefined and will have useful values during the match process. These variables and their meanings are explained in the plugin manual entry.
section features
allow url
allow network
allow persist unless {[string match {UNKNOWN *} [getattr originURL]]}
This section is where the policy declares which features it wants to install. The third allow statement says that the persist feature should be installed unless the originURL attribute of the Tclet matches UNKNOWN. The pattern UNKNOWN is inserted in canonical URLs if any of the parts of the URL from which the Tclet was loaded are unavailable. The above statement therefore prevents the persist feature from being used by Tclets whose origin cannot fully be determined.
section aliases allow socket allow fconfigure allow open allow file allow close allow puts allow tell allow seek allow browser::getURL allow browser::displayURL allow browser::getForm allow browser::displayForm allow browser::status
This section defines which aliases are installed by the policy into the interpreter in which the Tclet is executing. Each allow statement matches exactly one string, the name of an alias to install.
section urls allow $originHomeDirURL*
The single allow statement in the urls section allows URLs whose directory portion matches the directory portion of the URL from which the Tclet was loaded. For example, if originHomeDirURL is http://sunlabs.sun.com:80/usr/home/joe/ then http://sunlabs.sun.com:80/usr/joe/tclets/tclet1.html matches, but http://sunlabs.sun.com:80/usr/jacob/tclets/tclet1.html does not match. Note that the caller must ensure that only canonical URLs are used in the matching process, otherwise unintentional matches may occur which lead to security holes. For example, the above originHomeDirURL matches http://sunlabs.sun.com:80/usr/joe/../jacob/tclets/tclet1.html. Converting all URLs to a canonical form takes care of this by eliminating the ...
section hosts ports allow $originSocketHost >1024This allow statement matches a call to cfg::allowed if the arguments are respectively the name of the host on which the server resides from which the Tclet was loaded, and a number greater than 1024. This section is used in the home policy to control access to ports on the home host via the socket command.