NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

ns_config(n) 4.99.30 naviserver "NaviServer Built-In Commands"

Name

ns_config - Configuration parameters

Table Of Contents

Synopsis

Description

The NaviServer process reads a Tcl configuration file (specified with the -t command line option) during early start-up. After it has changed to the correct user id and group id, bound to port 80, and possibly performed a chroot, it evaluates the configuration file as a Tcl script.

The configuration file may contain standard Tcl and NaviServer commands, plus the ns_section and ns_param commands used to define a configuration structure. Parameters are key-value pairs and are grouped into sections. Section names must be unique -- parameter keys may be duplicates.

The configuration is global and read-only. Parameters may be retrieved at run-time using ns_config, although usually configuration parameters are used by Tcl library files at start-up.

COMMANDS

The following commands are available at run-time to retrieve information from the configuration file.

ns_config ?-bool | -int? ?-min minint? ?-max maxint? ?-exact? ?-set? section key ?default?

Returns the parameter value associated with the given section and key from the configuration file. If the parameter is not found, then the optional default is returned, otherwise the empty string is returned.

Parameter keys are matched case-insensitively. The first parameter is returned if duplicate keys are present.

-bool

Specifies that the parameter should be a valid boolean value, using any form understood by string is boolean. An error will be thrown if this is not the case, unless a valid default is given.

-int

Specifies that the parameter should be a valid integer value, using any form understood by string is integer. An error will be thrown is this is not the case, unless a valid default is given.

-min minint

Specifies the lower bound for an integer parameter value. An error will be thrown if the parameter < minint, unless a valid default value is given.

-max maxint

Specifies the upper bound for an integer parameter value. An error will be thrown if the parameter > maxint, unless a valid default value is given.

-exact

Specifies case-sensitive parameter key matching. Not recommended.

-set

Specifies that the parameter is set to the default value, when this parameter was not provided earlier. When this is done, the default is later retrievable via ns_config.

ns_configsection ?-filter filter? section

Return the ns_set which contains the actual values for all parameters defined in the specified section. If there is no matching section, an empty string is returned.

The -filter can be used to return different kind of information about the parameters defined in this section.

-filter unread

return the parameter, which were set during configuration (i.e., in the configuration file) but which were not read in the startup phase of the server. This option is useful to determine e.g. typographical errors of specified parameter names.

-filter defaulted

return the parameter, from which the default values were read (i.e., which were not explicitly set)

-filter defaults

return the defaults of the parameter. This is useful for contrasting the actual values with the default values, e.g. in a web based interface.

ns_configsections

Return a list of ns_sets, one for every section in the configuration file. The sets contain the key-value pairs for the configuration section that the set represents. The ns_set name contains the section.

CONFIGURATION FILE COMMANDS

The following commands are only available within the Tcl configuration file, evaluated once at server start-up.

ns_section section

Begin a new section. Following calls to ns_param place their parameters in this section, until another call to ns_section with a different section.

Multiple calls to ns_section with the same section name may be used to build up a section in pieces.

ns_param key value

Set the given key and value in the currently active section. Keys need not be unique. Key matching is case-insensitive by default.

EXAMPLES

The following example shows how to set parameter values for the foo module.

 ns_section "ns/server/server1/modules/foo"
 ns_param   enabled   true
 ns_param   map       /some/url
 ns_param   map       /some-other/url

The following example shows how to read configuration parameters for the foo module. The ns_config command is used to check for a boolean enabled parameter -- it defaults to false. If enabled, the parameters in that section are iterated over and all the entries with the key map are used to register a handler for the url, which is the parameter value.

 set path ns/server/[ns_info server]/modules/foo
 
 if {[ns_config -bool $path enabled false]} {
 
    set section [ns_configsection $path]
 
    foreach {key value} [ns_set array $section] {
        if {$key eq "map"} {
            ns_register_proc GET $value foo_module_handler
        }
    }
 }

The following example prints out all configuration parameters in all sections of the configuration file.

 ns_register_proc GET /config-print {
 
    set config ""
 
    foreach section [ns_configsections] {
 
        append config "section: [ns_set name $section]\n"
 
        foreach {key value} [ns_set array $section] {
            append config "$key: $value\n"
        }
    }
 
    ns_return 200 text/plain $config
 }

See Also

ns_env, ns_info, ns_set

Keywords

configuration, global built-in, interp, parameter, startup