NaviServer Built-in Commands – 5.1.0
ns_server - Get state of the server's connection pools and queues
This command provides a way to examine the current server's connection pools and queues. The allowed options (which may be abbreviated) are:
Returns currently defined authorization chain. Each element of the list is a tcl dict containing type ("user" or "request"), authority (the authority label supplied at registration), and proc a string describing the C function or Tcl callback.
Returns the effective charset configuration for the selected virtual server. When the last argument is omitted, the command returns a dictionary with the keys output, url, and formfallback. When it is specified, it must be one of these keys and the command returns the corresponding charset value.
The returned values are the effective per-server values after applying configuration defaults. They may therefore differ from values read directly from ns/parameters or ns/server/$server with ns_config.
Returns a list of the currently defined filters.
Returns a list of the registered hostnames for this server. This result list can be used as a white-list of configured and therefore secure contents accepted in the host header field of a request.
Per default, returns the connection pool associated with the mapping specification (HTTP method and path). An empty value indicates the default connection pool. When the -all is specified, a dict is returned containing the keys pool and handler indicating the connection pool and the request handler handling this request.
When the option -exact is used, the inheritance is deactivated, and only the values are returned directly assigned to the URL. When the option -noinherit is specified, only values set with the -noinherit flag are returned, not the files below in the subtree.
Returns the path of the virtual server's page directory root.
Returns a list of the pools defined for this server.
Returns or sets the HTTP authentication "realm" for a server. The realm is the string presented in the browser’s login dialog (and in the WWW-Authenticate header) when Basic or Digest authentication is required-it identifies the protected area. When newrealm is specified, it updates the server’s realm to that value and returns the previous realm.
# Query the realm on the default server % ns_server realm Restricted Area # Change the realm to "Administrators" % ns_server realm "Administrators" Restricted Area ;# old value returned
Returns a list of the currently defined requestprocs (the registered procs for certain request patterns).
Returns the path of the virtual server's base directory. When the option -effective is used, the path based on the results of the serverrootproc callback is returned.
Returns the path of the virtual server's private Tcl library.
Returns a list of the currently defined traces.
Returns a list of the mappings from URLs to files.
Returns a Boolean value to indicate whether virtual hosting is enabled for this server. The setting of this value influences e.g. the result of ns_conn location.
These three commands return information about queued or running requests. For every request the command returns a list containing connection id, the peer address, state ("running" or "queued"), the request (HTTP method and url), running time, and bytes sent. The sub-command all returns the union of the running and queued requests.
When option -checkforproxy is given, it tries to return the peer address from "x-forwarded-for" header field. If this is not possible (not given, or empty, or having the value "unknown") it falls back to the physical peer address.
Returns the number of connection requests processed by this pool since startup.
When the optional mapping specification (argument mapspec) is provided add this mapping to the server and pool (as specified or default). As a consequence matching requests (based on HTTP method and path) will be mapped to this connection pool.
When the optional argument mapspec is not provided, the command returns a list of mappings for the (given or default) server and pool.
Query or set the maximum number of connection threads for this server and pool. The value must be large than minthreads and less than the maximum number of connections.
Query or set the minimum number of connection threads for this server and pool. The value must be between 1 and maxthreads.
Query or set the maximum transmission rate per connection when data is sent via writer threads. The value is provided as KB/s. 0 means no rate limit.
Query or set the maximum transmission rate for the pool when data is sent via writer threads. The value is provided as KB/s. 0 means no rate limit. When the pool rate limit is set, all connections in this pool are managed.
Returns a list of attribute value pairs containing statistics for the server and pool, containing the number of requests, queued requests, dropped requests (queue overruns), cumulative times, and the number of started threads.
Returns a list of attribute value pairs containing information about the number of connection threads for the server and pool.
Undoes the effect of a ns_server map operation. As a consequence formerly mapped requests will be served by the default connection pool.
Limitation: when the mapspec contains a context constraints (see below) this is ignored, all entries with the specified HTTP method and path are unmapped.
Returns the number of connections waiting (i.e. queued) to be processed.
The following example shows how connection pool mappings can be added at runtime based on the partial timing information of a request.
When a request takes longer than a configured threshold, the combination of HTTP method and request URL is mapped dynamically to a connection pool named slow. Later requests with the same method and URL are then handled by that pool.
ns_register_trace GET /* {
set pt [ns_conn partialtimes]
set req [list [ns_conn method] [ns_conn url]]
set ctime [expr {[dict get $pt runtime] + [dict get $pt filtertime]}]
if {$ctime > 3.0 && [ns_server mapped $req] eq ""} {
ns_server -pool slow map -noinherit $req
}
}
A mapping can be queried at runtime with ns_server mapped:
% ns_server mapped "GET /images/logo.png" fast
Connection thread pools are usually defined in the configuration file. The ns/server/$server/pools section defines the pool names, and each ns/server/$server/pool/$pool section configures one pool.
The map parameter maps requests to a pool. It is equivalent to an inheriting map. The map-noinherit parameter creates a mapping that does not inherit to more specific URL paths and corresponds to the -noinherit option of ns_server map.
ns_section ns/server/$server/pools {
ns_param fast "Fast lane pool"
ns_param slow "Slow lane pool"
ns_param bots "Bot pool"
}
ns_section ns/server/$server/pool/fast {
ns_param minthreads 4
ns_param maxthreads 4
ns_param rejectoverrun true
ns_param map "GET /*.png"
ns_param map "GET /*.jpg"
ns_param map "GET /*.pdf"
ns_param map-noinherit "GET /dotlrn/mt"
}
ns_section ns/server/$server/pool/slow {
ns_param minthreads 5
ns_param maxthreads 15
ns_param maxconnections 200
ns_param rejectoverrun true
}
ns_section ns/server/$server/pool/bots {
ns_param map "GET /* {user-agent *bot*}"
ns_param map "GET /* {user-agent *rawl*}"
ns_param map "GET /* {user-agent *pider*}"
ns_param map "GET /* {user-agent *baidu*}"
ns_param minthreads 2
ns_param maxthreads 2
ns_param rejectoverrun true
ns_param poolratelimit 1000
}
The bots pool demonstrates mapping with context constraints. A request is assigned to this pool when the HTTP method and URL pattern match and the incoming User-Agent header matches one of the configured wildcard patterns.