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.
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.
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.
The following commands are only available within the Tcl configuration file, evaluated once at server start-up.
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.
Set the given key and value in the currently active section. Keys need not be unique. Key matching is case-insensitive by default.
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 }