Example Configuration Files

This section provides examples of several configuration files so you can see how the parameters detailed in the previous sections are typically used. The examples show:

• Configuration for Multiple Virtual Servers

• Configuration for Multiple Database Pools

• Configuration for Virtual Hosting

• Configuring and Using ATG's Dynamo Server

• Configuring and Using the Java Servlet API

Configuration for Multiple Virtual Servers

This configuration file defines two virtual servers named default and other. A few things to note about this configuration file are:

Modules for each server: The default server contains several modules (nssock, nstext, nslog, and nsperm), while the other server contains only nssock. The other server has no defined database pools. It therefore cannot contain the nstext module, because the nstext module (which performs full-text capabilities such as AutoLinking, indexing, and archiving) requires an Illustra database pool. (See the [ns/server/server-name/modules] sections.)

CGI configuration for the default server: The CGI capability in the default server includes two maps: one for the GET method to scripts which end in .cgi and are located in the pages directory, and the other for the POST method which maps URLs which begin with /cgi to scripts in the /usr/local/cgi directory. In addition, the "myinterps" Interps section is defined so that before CGI programs are executed the AOLserver will check for a cooresponding interpreter program. In this case, any script which ends in .pl will be interpreted by the /usr/local/bin/perl program. Finally, the .pl interpreter map specifies the name of an environment section, perlEnv. Before invoking /usr/local/bin/perl, the AOLserver will set the PERLLIB and DATA environment variables in addition to the standard CGI environment variables.

Pages directories for each server: The pages for each server are stored in different directories. The pages for the default server are stored in the /servers/default/pages directory under the home directory, and the pages for the other server are stored in the /servers/other/pages directory under the home directory. Each virtual server will not be able to access pages stored by the other server. (See the pageroot parameters in the [ns/server/server-name] sections.)

Separate ports for each server: The two virtual servers are differentiated by port number. The default server uses port 8000, and the other server uses port 8001. (See the port parameter in the [ns/server/server-name/modules/nssock] sections).

Alternatively, you can differentiate the servers by IP address with the address parameter. To use different IP addresses on the same host, you must have either additional physical network cards installed on your system, or support from the operating system to provide IP address aliases for a single physical interface.

    [ns/parameters]
    home=/home/mary/ns
    
    [ns/servers]
    default=The Default Server
    other=The Other Server
    
    [ns/server/default]
    directoryfile=index.htm
    verbose=y
    pageroot=/servers/default/pages
    
    [ns/server/default/modules]
    nssock=nssock.so
    nstext=nstext.so
    nslog=nslog.so
    nsperm=nsperm.so
    
    [ns/server/default/module/nssock]
    port=8000
    
    [ns/server/default/module/nstext]
    dbpool=defdb
    index=y
    archive=y
    searchable=y
    
    [ns/server/default/module/nslog]
    maxsizekb=100
    maxbackup=5
    
    [ns/server/default/module/nsperm]
    model=small
    
    [ns/server/default/db]
    pools=*
    
    ; Configure CGI to execute .cgi scripts in the pages
    ; directory with the GET method and to execute scripts
    ; in the /usr/local/cgi directory with the POST method.
    
    [ns/server/default/cgi]
    map=GET /*.cgi
    map=POST /cgi /usr/local/cgi
    interps=myinterps
    
    ; CGI scripts which end in .pl will be executed by perl.
    [ns/interps/myinterps]
    .pl=/usr/local/bin/perl(perlEnv)
    
    ; Before perl is invoked, set the PERLLIB and DATA environment
    ; variables.
    [ns/environment/perlEnv]
    PERLLIB=/usr/local/lib/perl
    DATA=/usr/local/data
    
    [ns/server/other]
    directoryfile=index.htm
    minthreads=1
    maxthreads=1
    pageroot=/servers/other/pages
    
    [ns/server/other/modules]
    sock=nssock.so
    
    [ns/server/other/module/nssock]
    port=8001
    
    [ns/db/drivers]
    illustra=nsill.so
    
    [ns/db/driver/illustra]
    ;miparams=
    
    [ns/db/pools]
    defdb=The Default Database Pool
    
    ; Define the defdb pool which connects to the nsdb
    ; Text Datablade database on the default Illustra server.
    [ns/db/pool/defdb]
    driver=illustra
    connections=2
    datasource=default:nsdb
    user=nsadmin

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:

Illustra and SOLID database pools: The defdb database pool is associated with an Illustra database, and the otherdb database pool is associated with a SOLID database. (See the driver parameters in the [ns/db/pool/pool-name] sections.)

Illustra and SOLID drivers: The drivers used for all of the defined database pools are listed in the [ns/db/drivers] section. There is one configuration parameter for the Illustra driver (in the [ns/db/driver/illustra] section, but there are no configuration parameters for a SOLID driver.

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 pool for the nstext module: The nstext module must access an Illustra database pool. In this example, the dbpool parameter in the [ns/server/default/module/nstext] section specifies the defdb database pool, which is an Illustra database pool.

    [ns/parameters]
    home=/home/mary/ns
    
    [ns/servers]
    default=The Default Server
    
    [ns/server/default]
    directoryfile=index.htm
    verbose=y
    pageroot=/servers/default/pages
    
    [ns/server/default/modules]
    nssock=nssock.so
    nstext=nstext.so
    nslog=nslog.so
    nsperm=nsperm.so
    
    [ns/server/default/module/nssock]
    port=8000
    
    [ns/server/default/module/nstext]
    dbpool=defdb
    index=y
    archive=y
    searchable=y
    
    [ns/server/default/module/nslog]
    maxsizekb=100
    maxbackup=5
    
    [ns/server/default/module/nsperm]
    model=small
    
    [ns/server/default/db]
    pools=*
    
    [ns/db/drivers]
    illustra=nsill.so
    solid=nssolid.so
    
    [ns/db/pools]
    defdb=The Default Database Pool
    otherdb=The Other Database Pool
    
    [ns/db/pool/defdb]
    driver=illustra
    connections=2
    datasource=default:nsdb
    user=nsadmin
    
    ; Define the otherdb database pool
    [ns/db/pool/otherdb]
    driver=solid
    connections=4
    datasource=TCP/IP hostname 1313

Configuration for Virtual Hosting

Web sites generally require a separate IP address for each distinct hostname with different content. That is, if you have www.bar.com and www.baz.com, and want to serve different content for each, you need two IP addresses. The reason is that HTTP/1.0 does not require browsers to inform the server which name they looked up to find the site, and thus both requests look identical. To get around this problem, HTTP/1.1 and most modern web browsers (inc. Netscape and Internet Explorer versions 3.0 and above) now send an extra HTTP header called Host that identifies the host that was looked up by the browser. The nsvhost module lets you exploit this header and serve different content based on this header.

Note that you cannot use virtual hosting for virtual servers that use SSL. All of the virtual servers involved must use nssock instead of nsssl.

Configuration Steps

1. Create a virtual server for each host you want to serve different content. Make sure each has at least one communications driver (nssock or nsssl), and specify the hostname and IP address.

       [ns/servers]
       master=The Master Server 
       bar=Another Server
       baz=Yet Another Server
       [ns/server/bar/modules]
       nssock=nssock.so
       [ns/server/baz/modules]
       nssock=nssock.so
       [ns/server/bar/module/nssock]
       port=0
       hostname=www.bar.com
       [ns/server/baz/module/nssock]
       port=0
       hostname=www.baz.com
   

   If you specify port=0, as shown above, the virtual server will not listen on any port, and the only way for visitors to access the content on that server will be through the "master" server. Alternatively, if you specify a valid port number, visitors will have access to that virtual server's content both through that port number and through the "master" server.

2. One of the virtual servers will be the "master" virtual server, and when connections come to it, it will route them to the appropriate virtual server. Add the nsvhost module to this server.

       [ns/server/master/modules]
       nsvhost=nsvhost.so
   

3. In the section [ns/server/masterservername/module/nsvhost], add a line for each virtual server in the form hostname=handle:

       [ns/server/master/module/nsvhost]
       www.bar.com=bar
       www.baz.com=baz
   

4. Now add a section for each of these that will bind it to the appropriate virtual server; the below examples assume that virtual servers named bar and baz have been defined.

       [ns/server/master/module/nsvhost/bar]
       server=bar
       Driver=nssock
       [ns/server/master/module/nsvhost/baz]
       server=baz
       Driver=nssock
   

Note: If the master virtual server has different parameter settings for nssock than the other virtual servers, the settings for the master virtual server will be used if the content is accessed through the master virtual server connection, and the settings for the other virtual server will be used if the content is accessed through that virtual server's connection.

Configuring and Using ATG's Dynamo Server

The nsdynamo module provides a communications interface to ATG's Dynamo Server that enables support for the following:

Java-embedded HTML: Developers may embed Java into their HTML documents to create dynamic documents. Check the ATG's Product Requirements page for supported platforms and other important information.

Configuring the nsdynamo Module

1. For your platform, download and install the Java Development Kit (1.1 or higher). If you will not be using the compiler, debugger, or tools for that  platform, then you can download and install the Java Run-time Environment (1.1 or higher) instead. These distributions include the Java Virtual Machine, Java Core Classes, and other supporting files.

   To download a copy of the Java Virtual Machine for your platform, please visit:

   • Sun's JDK Port Listing (at http://java.sun.com/cgi-bin/java-ports.cgi) for a listing of known JDK ports

   • Sun's JDK (at http://www.javasoft.com/products/jdk/1.1/) for Solaris and Windows 95

   • Blackdown's JDK (at http://www.blackdown.org/java-linux/Mirrors.cgi) for Linux

   • SGI's JDK (at http://www.sgi.com/Fun/Free_webtools.html) for SGI

   • Digital's JDK (at http://www.digital.com/java/) for Digital UNIX V4.0x

   • HP's JDK (at http://hpcc997.external.hp.com/gsyinternet/hpjdk/) for HP-UX

2. Download and install the Dynamo Devloper's Kit (DDK) (2.6.1 or higher).
   • Dynamo Download Page (at http://www.atg.com/develop/download/)

   After downloading the DDK, refer to ATG's documentation (at http://www.atg.com/develop/docs/) for installation and configuration.

3. Edit the nsd.ini configuration file for your server, and add the nsdynamo module to the modules section of one the virtual servers:

       [ns/server/server-name/modules]
       nsdynamo=nsdynamo.so
   

4. Add a configuration section  in your nsd.ini file for the nsdynamo module for the virtual server:

       [ns/server/server-name/module/nsdynamo]
   

   Specify any or all of the parameters in the nsdynamo module configuration section described on page 94.

   For example:

       [ns\server\server1\module\nsdynamo]
       DynamoHost=myhost1.hostname.com. myhost2.hostname.com, 
   myhost3.hostname.com
       DynamoPort=20000, 20000, 30000
       DynamoUrl=/dynamo
       DynamoTimeout=30
       DynamoVerbose=On
   

5. Re-start the server so that your configuration changes will take effect.

Using the nsdynamo Module

After the JDK, DDK, and AOLserver are configured correctly, there are several ways to invoke and use a Dyamo document.

Within an URL:

http://myhost.hostname.com/nsdynamo/first.jhtml

Within an URL with arguments:

http://myhost.hostname.com/nsdynamo/second.jhtml?name=value

Within an HTML document:

<A HREF=http://myhost.hostname.com/nsdynamo/third.jhtml>DynamoTest</A>

Configuring and Using the Java Servlet API

The nsservlet module provides an interface to the Java Servlet API that enables support for server-side "applets" called servlets. With this newly added capability, plug-in modules may be written in Java to extend the functionality of AOLserver. With the extensive Servlet API, many classes and member functions are available for quick and easy use. This allows web developers to use Java for the following:

• Application development: Developers may create custom applications in Java that are not server API dependent or specific.

• Dynamic content: Developers may dynamically generate client content based on request headers and other conditionals.

• Fast CGI development: Developers may use Java to handle CGI-type request with improved performance and with cross-platform compatibility.

Configuring the nsdynamo Module

1. For your platform, download and install the Java Development Kit (1.1 or higher). If you will not be using the compiler, debugger, or tools for that  platform, then you can download and install the Java Run-time Environment (1.1 or higher) instead. These distributions include the Java Virtual Machine, Java Core Classes, and other supporting files.

   To download a copy of the Java Virtual Machine for your platform, please visit:

   • Sun's JDK Port Listing (at http://java.sun.com/cgi-bin/java-ports.cgi) for a listing of known JDK ports

   • Sun's JDK (at http://www.javasoft.com/products/jdk/1.1/) for Solaris and Windows 95

   • Blackdown's JDK (at http://www.blackdown.org/java-linux/Mirrors.cgi) for Linux

   • SGI's JDK (at http://www.sgi.com/Fun/Free_webtools.html) for SGI

   • Digital's JDK (at http://www.digital.com/java/) for Digital UNIX V4.0x

   • HP's JDK (at http://hpcc997.external.hp.com/gsyinternet/hpjdk/) for HP-UX

2. Download and install the Java Servlet Devlopment Kit (1.0.1 or higher).
   • Servlets Download Site (at http://jserv.javasoft.com/products/java-server/servlets/index.html)

   The Servlet Download Site may indicate that the Servlet Development Kit is only avaible for Solaris and Windows, but it will work with any platform.

3. Edit the nsd.ini configuration file for your server, and add the nsservlet module to the modules section of one the virtual servers:

       [ns/server/server-name/modules]
           nsservlet=nsservlet.so
   

4. Add a configuration section in your nsd.ini file for the nsservlet module for the virtual server:

       [ns/server/server-name/module/nsservlet]
   

   Specify any or all of the parameters in the nsservlet module configuration section on page 104.

   For example:

       [ns\server\server1\module\nsservlet]
       JavaHome=/usr/local/java 
       JavaClassPath=/usr/local/java/classes
       NcgiTimeout=30
       ServletAPIHome=/usr/local/jsdk
       ServletAPIClassPath=/usr/local/jsdk/lib
       ServletUrl=/myservleturl
       ServletHome=/opt/jsdk/servlets
       ServletVerbose=On
       NcgiClassPath=/usr/local/jsdk/lib/sun/servlet/apache
       NcgiEnvPath=/usr/local/java:/usr/local/jsdk:/opt/jsdk/servlets
   
   

5. Re-start the server so that your configuration changes will take effect.

Obtaining more information

For more information concerning installation, configuration, examples, or use of servlets, please visit the JavaServer website site at http://jserv.javasoft.com/.