NAME
config - Configuration management for Safe Tcl.
SYNOPSYS
DESCRIPTION
COMMANDS
cfg::init baseName ?masterConfig? ?configDir?
cfg::allowed logToken config section arg arg...
cfg::getConstant logToken config section name
CONFIGURATIONS AND CONFIGURATION FILES
SECTION
ALLOW
DISALLOW
CONSTANT
ARGUMENT MATCHING
when expression
unless expression
ifallowed section arg arg...
EXAMPLE
SEE ALSO
KEYWORDS

NAME

config - Configuration management for Safe Tcl.

SYNOPSYS

package require cfg

cfg::init baseName ?masterConfigFile? ?configDir?

cfg::allowed logToken config section arg arg...

cfg::getConstant logToken config section name

DESCRIPTION

This manual entry describes the configuration management mechanism for Safe Tcl. It explains the syntax and structure of configuration files, and details how configuration and permission checking work at runtime.

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.

COMMANDS

cfg::init baseName ?masterConfig? ?configDir?
Applications that use the cfg configuration management package must call cfg::init before using any other procedure in the package. The baseName specifies the name of the application, and is stored in cfg::name for future use. If masterConfig is not given, the main configuration file name is baseName.cfg; otherwise it is masterConfig.cfg. If configDir is given, cfg::configDir is set to configDir and used in future operations. Otherwise, cfg::configDir is set to the sibling config directory of the tcl_library directory. For example, if tcl_library is /usr/joe/lib/tcl8.0 then cfg::configDir is set to /usr/joe/lib/config. After computing these settings, cfg::init sources the main configuration file and stores the settings defined therein for future use.

cfg::allowed logToken config section arg arg...
Applications invoke cfg::allowed to check whether a specific configuration option is allowed. It checks in the configuration config and section section whether the supplied arguments are allowed. The syntax of configuration files is explained in the next sections; here we briefly review how cfg::allowed decides whether a combination of arguments is allowed. See the documentation below for an explanation of the allow and disallow statements. The logToken must be a valid token for cfg::iget to use to retrieve attributes. See the plugin manual page for a discussion of cfg::iget. By convention, most callers of cfg::allowed give the name of the interpreter in which a Tclet is executing as the value of logToken when the caller is configuring access permissions on behalf of that Tclet. As explained below, this is used during the matching process to provide values for predefined variables that can be used to parameterize a match. The call to cfg::allowed returns 1 if the section section contains at least one allow statement whose arguments match the arguments supplied in the call, and if the section contains no disallow statement whose arguments match the call's arguments. If the section section was not found, or if no matching allow statement is found, or if a matching disallow statement is found, cfg::allowed returns 0. The rules for matching call arguments with arguments of allow and disallow statements are explained the section on ARGUMENT MATCHING.

cfg::getConstant logToken config section name
Applications invoke cfg::getConstant to get the value of a named constant declared with a constant statement in the section section in the configuration config. If a constant by that name was not declared in the section section in the configuration config, the call returns an error. The constant statement is explained below, in the section CONSTANT.

CONFIGURATIONS AND CONFIGURATION FILES

Configurations are named collections of configuration statements, organized in sections. Configurations are stored in configuration files, whose name is configuration.cfg. Configuration files are stored on the local file system in the directory cfg::configDir. For the Tcl plugin, this is the config directory in the plugin runtime library directory tree, as explained in the plugin manual page.

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.

SECTION

A configuration is organized into named sections. Each section starts with a section statement, and is followed by other configuration statements. A section lasts until the next section statement, and it scopes all the following configuration statements to this section.

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.

ALLOW

allow arg arg...

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.

DISALLOW

disallow arg arg...

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.

CONSTANT

constant name value

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.

ARGUMENT MATCHING

The arguments in a call to cfg::allowed are matched against the arguments of an allow or disallow statement according to the following rules:

[1]
Arguments are matched from left to right. Matching stops as soon as a mismatch is found. If no mismatch is found, a match is found. If matching runs out of arguments in the call to cfg::allowed, the rest of the arguments in the statement are evaluated as a Tcl expression, and a match is found if the result is not 0.

[2]
Label each argument to cfg::allowed as a, and each corresponding argument in a statement as c.

[3]
If c and a are equal as determined by string equal, matching proceeds to the next argument.

[4]
If c matches a when used as pattern in string match, matching proceeds to the next argument.

[5]
If c is of the form n1-n2, n1 and n2 are numbers, n1 is less than or equal to n2, and a is a number less than or equal to n2 and greater than or equal to n1, matching proceeds to the next argument.

[6]
If c is of the form >n, n is a number and a is a number greater than n, matching proceeds to the next argument.

[7]
If c is of the form <n, n is a number and a is a number less than n, matching proceeds to the next argument.

[8]
Otherwise a mismatch is found.

Several special forms are provided to express common cases in allow and disallow statements:

when expression
This evaluates to 1 if the value of expression as computed by expr is not 0.

unless expression
This evaluates to 0 if the value of expression as computed by expr is not 0.

ifallowed section arg arg...
This evaluates to 1 if the arguments are recursively allowed in the section section, and to 0 if they are not allowed. If the section is specified as config/section the section will be looked up in the given config instead of the current one by default.

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.

EXAMPLE

The following example is the actual configuration file for the home policy, interspersed with explanatory comments. It is one of the more complicated configuration files shipped with the Tcl plugin.

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 >1024
This 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.

SEE ALSO

safe, policy, plugin

KEYWORDS

allowed, allow, disallow, constant, configuration, Safe Base, Tclet
Tcl Plugin 2.0