NaviServer - programmable web server

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

# ns_config(n) 4.99.8 naviserver "NaviServer Built-In Commands"

## Name

ns_config - Configuration parameters

## Table Of Contents

## Synopsis

- ns_config ?-bool | -int? ?-min minint? ?-max maxint? ?-exact? ?-set? section key ?default?
- ns_configsection section
- ns_configsections
- ns_section section
- ns_param key value

## 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. This makes the default later retrievable via ns_config.

ns_configsection section

  Return the ns_set which contains all the parameter key-value pairs for the specified section of the configuration file. If there is no matching section, an empty string is returned.

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, interp, parameter, startup