NaviServer Configuration(n) 4.99.2 ""

NAME

NaviServer Configuration - NaviServer Configuration Guide

    TABLE OF CONTENTS
    DESCRIPTION
    NaviServer Configuration
        What is a database pool?
        What are the default NaviServer capabilities?
        What is an NaviServer module?
    Configuration File Structure
    Configuration File Hierarchy
        Note on Boolean Parameter Values
    Example Configuration Files

NaviServer has many configurable parameters, all of which are set in the NaviServer configuration file. This chapter provides a reference of the configuration file structure and parameters so that you can edit the configuration file directly.

By modifying and/or adding NaviServer configuration parameters, you can:

Define multiple servers, one of which will run within each running NaviServer process.
Define multiple database pools with different data sources that can be accessed by any or all of the servers.
Configure various NaviServer capabilities or optionally-loaded modules for each of the servers.

What is a database pool?

A database pool is a set of connections to a database. NaviServer currently supports direct connections to the Sybase/MS SQL Server and Postgres databases. Third-party database drivers are available for Mysql, Oracle, Informix, and InterBase. As far as configuration is concerned, you simply specify a database (or data source) that you want NaviServer to access. NaviServer then manages a set of connections to the database that it uses internally to efficiently process database operations. You can also access these connections directly through the Tcl and C interfaces.

What are the default NaviServer capabilities?

The following capabilites are provided by default for every server and can be configured by manually editing the configuration file.

ADPs: This capability allows you to embed Tcl scripts within an HTML page. The pages are parsed and run on the server when the page is accessed.
db: This capability allows you to use NaviServer's database services. nsdb module needs to be loaded for database access.
tcl: This capability allows you to use NaviServer's Tcl API. See the Tcl Developer's Guide for information on Tcl.

What is an NaviServer module?

NaviServer modules are shared libraries or dynamically-linked libraries that provide specific sets of capabilities that you can load in your servers. The following standard modules are provided:

nscgi: This capability allows you to run CGI programs from NaviServer.
nscp: This module enables the control port interface that allows you to administer a running server.
nslog: This module enables access logging in the CERN Common Log Format. The nslog module can also log the Refer and User-Agent client headers.
nsperm: This module enables access control capabilities -- defining users, groups, and permissions.
nssock: This module enables communications using ordinary TCP/IP Internet sockets.
nsproxy: This module provides a simple, robust proxy mechanism to evaluate Tcl scripts in a separate, pipe-connected process.

Configuration File Structure

This section describes the format of the configuration file and provides detailed information on individual NaviServer parameters.

The configuration file is normally the nsd.tcl file in the NaviServer home directory (the directory where NaviServer was installed). You must specify the configuration file when you start up NaviServer with the -c command line flag.

The configuration file is a Tcl file that can be modified with a text editor such as vi or emacs on Unix. The file is made up of named sections with one or more parameters. Each section heading is of the form "ns/...". Each parameter is composed of a parameter name and a parameter value. The parameters of a section continue until a new section is defined or until the end of the file.

The ns_section and ns_param Tcl functions are used to define each section and the parameters for each section in the configuration file. The general format of the configuration file is as follows:

ns_section "ns/..." ns_param param-name param-value ...

Configuration File Hierarchy

Although there are a large number of configurable parameters for NaviServer, most of them are not required. Also, the parameters are organized into a hierarchy branching off of the following main sections, letting you configure NaviServer at a global level, configure each server, and configure each database you will be accessing. This hierarchy of sections allows you maximum flexibility to provide exactly the capabilities you need on each server, including where pages will be stored and which databases will be accessible.

Parameters: This part of the configuration file contains parameters that apply to the NaviServer process:
- ns/parameters specifies parameters such as the NaviServer home directory.
- MIME Types: This part of the configuration file lists global MIME types.
- ns/mimetypes maps file name extensions to content-type headers.
Servers: This part of the configuration file configures one or more servers, one of which that can be run within each NaviServer process. It is the top level in a hierarchy of sections for each server.
- ns/servers lists and names all of the servers.
- ns/server/servername configures an individual server.
- ns/server/servername/adp configures NaviServer Dynamic Pages (ADPs) for the server.
- ns/server/servername/db configures database connections used by the server.
- ns/server/servername/fastpath configures fastpath serving of static files.
- ns/server/servername/realms configures logging realms for individual modules.
- ns/server/servername/redirects configures redirects.
- ns/server/servername/tcl configures Tcl for the server.
- ns/server/servername/modules lists the modules available to each server.
ns/server/servername/module/nscgi configures CGI (Common Gateway Interface) for the server. See also the CGI interpreters and CGI environment configuration sections on page 48 for additional CGI configuration.
ns/server/servername/module/nscp configures the control port administration interface.
ns/server/servername/module/nscp/users configures the users allowed to access the control port administration interface.
ns/server/servername/module/nslog configures the access log module loaded into a server.
ns/server/servername/module/nsperm configures the permissions module loaded into a server.
ns/server/servername/module/nssock configures the sockets module loaded into a server.
Database Drivers and Pools: This part of the configuration file configures the database drivers (the type of database you will be using) and the database pools (connections to the database).
- ns/db/drivers lists the database drivers available to NaviServer. Currently internal database drivers are available for Sybase/MS SQL Server and Postgres.
- ns/db/driver/extname configures an external database driver.
- ns/db/pools lists the database pools available to NaviServer.
- ns/db/pool/pool-name configures a database pool, which determines the database to access and how many connections there will be to it.
CGI Interpreters: This section allows you to configure the interpreters to execute for CGI scripts that end with certain file extensions. For example, you can configure the perl.exe interpreter to be invoked for all CGI's that end in .pl.
- ns/interps/interps-name defines an interps section for CGI modules.
- CGI Environment: This section allows you to configure environment variables in addition to the standard CGI environment variables for all CGI's or specific CGI interpreters.
- ns/environment/environment-name defines an environment section for CGI modules.

Note on Boolean Parameter Values

There are several ways to specify a boolean parameter value. The reference tables below use "on" for true and "off" for false. However, any of the following values are valid:

For True : on, y, yes, t, true, 1 (one)

For False : off, n, no, f, false, 0 (zero)

Example Configuration Files

Default Configuration File

The default sample-config.tcl comes with NaviServer. There is one server defined, server1, which contains the nscp, nslog, and nssock modules. You can define multiple servers, but only one of them can be run with each command line execution. All this information is defined at the top of the file.

sample-config.tcl.txt

Configuration for Multiple Database Pools

This configuration file defines one server named default and two database pools named defdb and otherdb. A few things to note about this configuration file are:

Database pools: The defdb database pool is associated with an MS SQLServer database, and the otherdb database pool is associated with a PostgreSQL database. (See the driver parameters in the ns/db/pool/pool-name sections.)

MS SQLServer and Postgres drivers: The drivers used for all of the defined database pools are listed in the ns/db/drivers section.

Database pools accessible by each server: The pools parameter in the ns/server/default/db section specifies which database pool the default server has access to. In this example, the default server can access both the otherdb and the defdb database pools.

# # Database drivers # # Two pools are given here. MS SQLServer uses the FreeTDS client libraries, # PostgresSQL is freely available at www.postgresql.org. # ns_section "ns/db/drivers" ns_param sqlserver_driver nsdbtds.so ns_param postgres_driver nsdbpg.so ns_section "ns/db/pools" ns_param sqlserver_pool "SQLServer Pool" ns_param postgres_pool "Postgres Pool" ns_section "ns/db/pool/sqlserver_pool" ns_param driver sqlserver_driver ns_param connections 10 ns_param user cbill ns_param password cbill ns_param datasource Billing ns_param logsqlerrors true ;# Verbose SQL query error logging ns_param verbose false ;# Verbose error logging ns_param maxidle 600 ;# Max time to keep idle db conn open ns_param maxopen 3600 ;# Max time to keep active db conn open ns_section "ns/db/pool/postgres_pool" ns_param driver postgres_driver ns_param datasource HOSTNAME:PORT:database_name ns_param user user_name ns_param password password ns_param connections 1 ns_param logsqlerrors true ;# Verbose SQL query error logging ns_param verbose false ;# Verbose error logging ns_param maxidle 600 ;# Max time to keep idle db conn open ns_param maxopen 3600 ;# Max time to keep active db conn open # # Accessing DB pools # # In the case of virtual servers you can give different virtual # servers access to different databases, or you can let them access # them all. # ns_section "ns/server/${servername}/db" ns_param pools * ;# Wildcard gives access to all ns_param defaultpool sqlserver_pool