NaviServer Built-In Commands – 5.1.0
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.
Define or update a configuration sectionName and evaluate script in the context of that section. The commands ns_param and ns_section (nested) can be used inside script to populate the section.
Configuration sections are multi-maps: a key may occur multiple times with different values. This behavior is identical to ns_set.
When specified, inserting a key/value pair updates a potential pre-existing key if present. Without -update, new key/value pairs are added and existing keys are not replaced (multi-map semantics).
Inject the content of an already defined configuration section sectionName into the target section. The insertion semantics are identical to repeated ns_param operations for the target section and honor -update. The source section's underlying ns_set is used as input.
Inject the content of an ns_set identified by setId into the configuration section. The insertion semantics are identical to repeated ns_param operations for the target section and honor -update.
When both -from and -set are specified, the content from -from is applied first, followed by the content from -set. The script body is evaluated last and therefore can override injected values, subject to -update and multi-map semantics. The -from option is intended for reusing parameters from another configuration section, while -set is intended for reusing parameters collected programmatically in an ns_set.
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, multiple values may be associated with the same key. This powerful feature allows layered configuration but may also 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 associated with a key, use the -all option with ns_config or access the underlying ns_set directly.
The -update flag can be used with ns_section to indicate that parameters defined in the section should replace previously defined parameters with the same key, instead of simply appending new values. This affects how subsequent ns_param calls are handled for that section.
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
The -set option allows pre-populating a configuration section from an existing ns_set to simplify re-use of common blocks. Each key/value pair contained in the provided set is added to the section as if specified via individual ns_param calls.
Using -set is functionally equivalent to writing multiple ns_param commands and therefore preserves the multi-map semantics of ns_set, including duplicate keys.
set common [ns_set create a 1 b 2] ns_section -set $common foo { ns_param c 3 }
This behavior makes -set suitable as a concise shorthand for bulk parameter definitions (for example, shared defaults between sections), while still fully respecting NaviServer’s multi-map configuration model.
Sets the specified key to value in currently active section. Keys are matched in a case-insensitive manner, and duplicate keys are allowed, depending on the -update flag on the including section.
Turns the keys from the dict defaultConfig into Tcl variables in the caller's scope (the configuration file). Values are determined per key using the following precedence:
A variable already set in the configuration file (highest precedence).
An environment variable named ${prefix}$key.
The value from the dict defaultConfig (lowest precedence).
Values are processed via subst to allow references to previously defined variables such as $home inside dict values.
When the key setupfile exists in defaultConfig and resolves to a non-empty value, the referenced Tcl file is sourced after the variable assignment pass. This setup file is intended for instance-specific variable assignments (typically without ns_section blocks). A relative setupfile path is resolved against a configuration root directory (see -configRoot).
This command is typically used near the beginning of a configuration file to establish all configuration variables before ns_section blocks are evaluated.
set defaultConfig {
home /var/www
logdir {$home/logs}
httpport 8080
httpsport ""
setupfile ""
}
# Allow overrides via environment variables with prefix "oacs_"
ns_configure_variables "oacs_" $defaultConfig
With this configuration, the following invocation overrides the HTTP port and sources an instance-specific setup file:
oacs_httpport=8081 oacs_setupfile=instance.tcl nsd -t conf/openacs-config.d -f
Notes:
The command reports the origin of each variable value (default, environment variable, configuration file, or setup file) via the system log unless -silent is used.
Only scalar variables are processed; array variables are ignored.
This command is a core part of the shipped configuration framework and is used by the sample configurations provided with NaviServer.
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
}