ns_config - Configuration parameters
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.
The following commands are available at run-time to retrieve information from the configuration file.
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.
Returns 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.
Returns 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.
The following commands are available only within the Tcl configuration file, which is evaluated once at server start-up.
Begins a new configuration section identified by the specified name. All subsequent calls to ns_param will add parameters to this section until another ns_section command is invoked with a different section name.
Multiple invocations of ns_section using the same name allow you to build the section incrementally. The following two snippets are equivalent:
Snippet 1:
ns_section foo {
ns_param x 1
ns_param y 1
}
Snippet 2:
ns_section foo {
ns_param x 1
}
ns_section foo {
ns_param y 1
}
All configuration data is stored internally in ns_set structures. Since ns_set is defined as a multi-map storage, multiple values can be associated with the same key. This powerful feature may lead to surprises: when a scalar value is requested and multiple values are stored for the same key, only the first value is returned (as with ns_set get). To retrieve all values for a key, use the -all option with ns_config or ns_set.
The -update flag can be used with ns_section to update an existing section by overwriting previous values instead of simply appending new ones.
ns_section foo {
ns_param x 1
}
# Later in the configuration file:
ns_section -update foo {
ns_param x 2
}
# Query the value of parameter 'x'
ns_config foo x
# Result: 2
Sets the specified key to value in the currently active section. Keys are matched in a case-insensitive manner, and duplicate keys are allowed.
The following example demonstrates 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
}
Alternatively, the section content can be specified without braces (old style):
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. In this case, the ns_config command checks for a boolean enabled parameter (defaulting to false). If enabled, it retrieves all values associated with the map key and registers a handler for GET requests on each corresponding URL:
set path ns/server/[ns_info server]/modules/foo if {[ns_config -bool $path enabled false]} { foreach url [ns_config -all $path map] { ns_register_proc GET $url foo_module_handler } }
The following example prints all configuration parameters from every section of the configuration file. It retrieves each section's ns_set via ns_configsections and uses ns_set array to list all key/value pairs:
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
}