[ Previous ] [ Contents ] [ Index ] [ Next ]

The Setup Server

The setup server is built into AOLserver and enabled by default when AOLserver is started. You can use the setup server when you perform a bootstrap installation to configure any virtual servers, modules, database pools, and database drivers. After this initial configuration, you can access the setup server at any time while your AOLserver is running to make changes to your configuration.

Accessing the Setup Server

The setup server is configured by default to listen on port 9876 on all IP addresses on the system. To configure AOLserver with the setup server, just access the URL http://your-server-name:9876 from AOLpress or any other browser. The Setup page is displayed, and you can then change your configuration and restart AOLserver to see the effects of your changes. This diagram illustrates how the setup server and the virtual servers can be accessed:

Note that you can configure the setup server to listen on a port other than Port 9876. (See the "Configuring the Setup Server" section.) In this case, you must specify the appropriate port number other than 9876.

By default, the setup server is enabled even if you startup AOLserver and an error occurs while starting one or more of the virtual servers. This will allow you to access the setup server and correct the configuration problem. Note that you can configure the setup server so that it does not automatically run if a startup attempt fails. (See the "Configuring the Setup Server" section.) In this case, you need to access the setup server in an alternative way.

If you are having more serious trouble with your configuration, for example, a new module which crashes the server when loaded, you can start AOLserver with only the setup server by using the -S switch on the command line: 

    Unix:
    cd AOLserver-install-directory
    bin/nsd -S -c nsd.ini

    NT:
    cd AOLserver-install-directory
    bin\nsd -S -c nsd.ini

You can then access the setup server and reconfigure your AOLserver to correct the problem.

Using Setup Server Quick Start

If you access the setup server and you have not yet defined any virtual servers (which is the case when you are installing the server for the first time), a page is displayed allowing you to choose the Quick Start Setup or the Standard Setup.

You will not have this option if any virtual servers are defined. If virtual servers are defined, you will automatically be given access to the standard setup server.

The quick start setup server is designed to get you up and running with one virtual server as quickly and easily as possible. If you follow the Quick Start Setup link, a page is displayed allowing you to configure one virtual server by defining four parameters:

Hostname: The hostname to use for self-referential URLs. If this parameter is left blank, AOLserver will attempt to determine the hostname when it starts.
Port: The port number this virtual server will listen on.
User: (Unix only) Username for a Unix user to access the server if a privileged port (a port numbered below 1024 such as the traditional HTTP port 80) was specified.
Administrator Password: The nsadmin password for the new virtual server and the setup server. By default, there is no password for nsadmin.

Once you have defined these four parameters, click the Go! button and a virtual server (named server1) is automatically defined in the configuration file. Just restart AOLserver and access your virtual server.

Using the Standard Setup Server

Once you have accessed the setup server as described in the "Accessing the Setup Server" section, you can configure any of AOLserver's parameters. There are several groups of parameters that can be configured, each represented by a link on the AOLserver setup page:

Follow any of these links to set the associated parameters. The parameter fields on each form contain the current setting for each parameter. If you are using the setup server for the first time or have not modified any of the parameters, the default settings for the parameters are displayed.

Getting Help With the Light Bulb Icon


There is a light bulb icon at the top of every page in the setup server. If you click on the icon so that the light bulb is on, instructions for using the page and each parameter or module on the page are displayed. Click on the icon again to turn off the light bulb and display only the parameters or modules with no instructions.

Basic and Advanced Parameters Icon


Because very few of the many configurable parameters for AOLserver need to be set in most cases, only the basic and required parameters are shown by default on the parameters pages. You can click the "Basic" icon at the top of the page so that it becomes the "Expert" icon if you want to set the optional advanced parameters. The default settings for the advanced parameters are appropriate for most situations, so you do not normally need to view or set these parameter at all. If the advanced parameters are already displayed, you click the "Expert" icon so that it becomes the "Basic" icon to hide them again.

Seeing the Effects of Your Changes

Each time you make changes to a page in the setup server and commit your changes, AOLserver will perform some error-checking on your changes. For example, if you specify a directory location for the pages directory, AOLserver will check to see if the directory exists. If no such errors are found, the changes will be written to the configuration file. However, you will not see the effects of your changes until you restart the server.

If errors are found in any of your changes, AOLserver will inform you, and it will not write any of your changes to the configuration file. You must then change the incorrect parameter(s) and commit your changes again.

If You Configure Something Incorrectly

AOLserver does check your changes for some kinds of errors before writing them to the configuration file. AOLserver checks that any directories you specify exist, and it also checks that integer parameters contain integer values. However, AOLserver cannot check for all kinds of errors in the configuration parameters you set.

For example, if you specify a permissions directory in the nsperm module, AOLserver will check to see that the directory exists. However, it does not check whether the permissions files within the directory are corrupt. If they are corrupt, that virtual server will not start.

By default, the setup server is run automatically if you startup AOLserver and an error occurs while AOLserver attempts to startup one of your virtual servers. The Setup page is displayed, and you can then change your configuration and attempt to restart AOLserver again. You can look at the server log to see any errors that occurred. (See the "Viewing the Server Log" section for information.)

Note that you can configure the setup server so that it does not automatically run if a startup attempt fails. (See the "Configuring the Setup Server" section.) In this case, you need to access the setup server in one of the alternative ways described in the "Accessing the Setup Server" section.

Editing AOLserver Configuration Sections

If you have the "Expert" icon on to enable advanced parameters, a link to List AOLserver Configuration Sections is also displayed at the bottom of the AOLserver setup page. This link lets you edit or add configuration file parameters by the name of the section in the configuration file. (The "Configuration File Reference" section describes the configuration file sections and provides a reference for the parameters in them.)

The List AOLserver Configuration Sections link is useful when you want to:

After you follow the List AOLserver Configuration Sections link, a page listing all sections currently in the configuration file is displayed. You can follow the section name link to edit or add any of the parameters in those sections.

At the bottom of the page, you can fill in the name of a new configuration file section and click Add to define parameters for the new section.

Viewing the Server Log

At the bottom of the AOLserver setup page, there is the text "Show last 2048 bytes from the server log" followed by a Show button. You can edit the number of bytes of the server log to view if you want to see more or less than 2048 bytes. You can then click Show to see the specified portion of the server log.

Setup Server Tutorials

This section contains a set of tutorials for performing many common configuration tasks. The simplest tasks are listed first, but you can perform them in any order according to your need. The following tutorials are provided:

For instructions on configuring the CGI module or the SHTML (server-parsed HTML) module, see the "CGI Interface" and "Server-Parsed HTML" chapters, respectively, in the CGI Developer's Guide.

Configuring the Setup Server

The following instructions describe how to configure the setup server.


Configure the Setup Server:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Configure the Setup Server link.

  3. Edit the parameters you want to change and click Update. The parameters allow you to configure any of the following setup server characteristics:

  4. To see the effects of your changes, you must restart AOLserver.

Adding and Configuring a New Virtual Server

To add a new virtual server, you must define the parameters for the virtual server, specify the modules to be loaded into it, and configure each of those modules. It is important to note that when you add a new virtual server, you must give the virtual server a different Port or IP address from the existing virtual servers. If you configure AOLserver such that two virtual servers have the same Port/IP address combinations, you will not be able to start up AOLserver. Complete instructions are provided below.


Add and Configure a New Virtual Server:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Virtual Servers link. The Setup Virtual Servers page lists all of the virtual servers currently defined.

  3. Click Add Virtual Server.

  4. Enter a Name and a Description for the new virtual server and click Add. A page is displayed showing the virtual server parameters and a list of modules that can be loaded into the virtual server.

  5. Make changes in the parameter fields you want to change, and check the boxes of the modules you want loaded into this virtual server. You must choose at least one of the communications modules (sock or ssl).

  6. Click the Add button to add the new virtual server. AOLserver will perform some error-checking on your entries and, if no errors are detected, write the information to the configuration file. If errors are detected, AOLserver will inform you of the error and you will need to modify the parameters before the information will be written to the configuration file.

  7. On the confirmation page, follow the link to any of the modules loaded into the virtual server to configure the parameters for that module. Most of the parameters for the modules have defaults that will be satisfactory to you, so it is not essential that you configure parameters for a new module except for the nssock or nsssl modules.

    It is strongly recommended that you follow the link to either the nssock or the nsssl module, depending on which one you loaded into the new virtual server, to make sure that the Port and Address parameters are set so that they are unique from the other virtual servers. Having identical Port/Address combinations for any two virtual servers will result in AOLserver not being able to start up.

  8. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

Setting a Port or IP Address for a Virtual Server (nssock module)

Each virtual server must be configured to listen on a different port. Or, multiple virtual servers can listen on the same port if they use different IP addresses. The easiest way to configure multiple virtual servers is to have them use different port numbers. However, because port 80 is the conventional World Wide Web server number, it is often desirable to vary the IP address instead.

To vary the IP addresses, 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. Instructions for configuring your system to listen on multiple IP addresses are given on Configuring Your System for Multiple IP Addresses.

If you configure more than one virtual server with the same port and IP address, AOLserver will not start up, and you will need to reconfigure the port or IP address by following the instructions on If You Configure Something Incorrectly before you can restart AOLserver.


Set the Port or IP Address:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Virtual Servers link. The Setup Virtual Servers page lists all of the virtual servers currently defined. To the left of each server is either a right arrow or a down arrow.

  3. Decide which virtual server you want to set the port or IP address for. If the arrow next to it is a right arrow, click the right arrow so it becomes a down arrow. A list of the currently-defined parameters and currently-loaded modules for that virtual server is displayed.

  4. Follow the link to the nssock module for the virtual server.

  5. Modify either the Port parameter (to set a different port) or the Address parameter (to set a different IP address) for the virtual server.

  6. Set the Hostname parameter to the hostname which cooresponds to the Address you are using. This hostname will be used to refer to this virtual server, for example, when the AOLserver generates a redirect response. If left blank, the AOLserver will attempt to determine the hostname at startup.

  7. Click Update to commit your changes. Be sure that Port/IP address combination for this virtual server is unique among the other virtual servers. Having identical Port/Address combinations for any two virtual servers will result in AOLserver not being able to start up.

  8. Go back to the Setup Virtual Servers page and repeat the last four steps for any other virtual servers for which you want to set the port or IP address.

  9. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

Configuring Your System for Multiple IP Addresses

This section describes how to get your computer to listen to multiple IP addresses at the same time, which you will need to do if you plan to run several virtual servers and want them all to listen on port 80. The instructions vary by operating system.

Windows NT:

You can enter up to 5 IP addresses by pressing the Advanced button in the TCP/IP Protocol control panel (under Network). The Windows NT documentation states that the operating system supports up to 16 IP addresses and that you can configure your computer with this many IP addresses by editing the NT Registry directly with regedt32. For more information, see the Windows NT Resource Guide.

Solaris 2.5:

The Solaris operating system already has the necessary functionality to support multiple IP addresses on a single interface. Note that it is not supported by Sun, and not mentioned in the man pages. Here is the description from Casper Dik's FAQ for Solaris 2:

4.11) How can I have multiple addresses per interface?

Solaris 2.5 provides an undocumented feature in ifconfig that allows having more than one IP address per interfaces.

Syntax: 

    ifconfig IF:N ip-address up

where "IF" is an interface (e.g., le0) and N is a number between 1 and 255. Removing the pseudo interface and associated address is done with "ifconfig IF:N 0.0.0.0 down".

DEC OSF/1 (aka Digital Unix):

The Digital Unix operating system already has the necessary functionality to support multiple IP addresses on a single interface. You can use the ifconfig command to create as many aliases as needed with following syntax: 

    ifconfig interface alias address [netmask mask]

This command is well documented in the Digital Unix man pages.

HP-UX 10.x:

The HP-UX 10.x operating system already has the necessary support for multiple IP addresses per interface. If you want a solution supported by HP, you need to buy the ServiceGuard product. If you just want the functionality, a small program from Julian Perry will do the job. See the http://www.limitless.co.uk/hp_ifalias.html web site for detailed information.

SGI 5.3:

Multiple IP addresses on the same physical interface can be faked by using the ppp interface as documented at 

    http://www.your.net/multi-homed/sgi-config.html.

There is also additional information about this solution and an official software distribution/patch available from SGI at 

    http://www.sgi.com/Products/WebFORCE/IPAliases/.

Note that this is unsupported patch.

Linux:
  1. Load dummy device (if you do not have it compiled in): 

        % insmod dummy.o

  2. Configure the dummy device: 

        % ifconfig dummy different_IP

    (or dummy0 etc. if using insmod)

  3. Add an entry to your routing table: 

        % route add different_IP dev dummy

  4. Set up a proxy ARP entry: 

        arp -t ether -s different_IP your_ethernet_number pub"

    (Note that different_IP must be on the same subnet as your primary_IP)

    You can determine your_ethernet_number just by typing 

        % ifconfig

Setting the Location of the Pages Directories

The pages directory is the directory where the pages are stored on the server. Each virtual server can have a different pages directory. The location of the pages directory is defined by the PageRoot parameter for each virtual server. By default, the PageRoot parameter for each virtual server is set to the /servers/server-name/pages subdirectory under the AOLserver home directory. If you want to change this default, follow the instructions below.


Set the Location of the Pages Directories:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Virtual Servers link. The Setup Virtual Servers page lists all of the virtual servers currently defined. To the left of each server is either a right arrow or a down arrow.

  3. Decide which virtual server you want to set the pages directory for. If the arrow next to it is a right arrow, click the right arrow so it becomes a down arrow. A list of the currently-defined parameters and currently-loaded modules for that virtual server is displayed.

  4. On the Setup Virtual Servers page, follow the Parameters link under the virtual server you chose.

  5. Edit the directory location in the PageRoot field and click Update. AOLserver will verify that the directory you specified exists, and your changes will be written to the configuration file.

    If the directory doesn't exist, AOLserver will not write out the configuration file, and will inform you that you need to specify an existing directory in the PageRoot field.

  6. Go back to the Setup Virtual Servers page and repeat the last three steps for any other virtual servers for which you want to set the location of the pages directory.

  7. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

Adding and Configuring a New Module for an Existing Virtual Server

To add a new module to an existing virtual server, follow the instructions below.


Add a New Module to an Existing Virtual Server:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Virtual Servers link. The Setup Virtual Servers page lists all of the virtual servers currently defined. To the left of each server is either a right arrow or a down arrow.

  3. Decide which virtual server you want to add a module to. If the arrow next to it is a right arrow, click the right arrow so it becomes a down arrow. A list of the currently-defined parameters and currently-loaded modules for that virtual server is displayed.

  4. On the Setup Virtual Servers page, click the Add Module to server-name button.

  5. On the Add Module page, click the toggle by the module you want to add. (You can only add one at a time.) If the module you wish to add is not listed, switch to Expert mode, select Arbitrary Module, and enter the module name and filename. Click Add to add the module. A page showing the parameters for the module you added is displayed.

  6. Modify the values of any parameters you want to change, and click Add Module. If you do not see listed a parameter you need to set, switch to Expert mode and manually type in the parameter name and value. AOLserver will perform some error-checking on your changes and, if no errors are detected, write the information to the configuration file. (Note that not all errors can be detected.) If errors are detected, AOLserver will inform you of the error and you will need to modify the parameters before the information will be written to the configuration file.

  7. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

Configuring Database Services

Follow the instructions below to configure database services. Note that you must first install Illustra before configuring a database pool with an Illustra database.


Add and Configure a New Database Pool:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Database Pools link. The Setup Database Pools page lists all of the pools currently defined.

  3. Click Add Database Pool.

  4. Enter a Name and a Description for the new pool and click Add. A page is displayed showing the parameters for the database pool.

  5. The parameters listed below are required. The remaining parameters have defaults that you can change if you want.

  6. Click the Add button to add the new database pool. AOLserver will perform some error-checking on your entries and, if no errors are detected, write the information to the configuration file. (Note that not all errors can be detected.) If errors are detected, AOLserver will inform you of the error and you will need to modify the parameters before the information will be written to the configuration file.

  7. Any virtual server that has the nsdb module loaded can be configured to access your new database pool. Go back to Setup Home, and follow the Virtual Servers link.

  8. Decide on a virtual server that you want to access your new database pool. If the arrow to the left of the virtual server is a right arrow, click on the right arrow to change it to a down arrow and see the virtual server's parameters and loaded modules.

  9. Follow the Database Services (db) link.

  10. In the Pools parameter, specify the name of the new database pool in the list of accessible pools. If Pools is currently defined as "*", then all database pools are accessible to this virtual server. Otherwise, add the new database pool name to the existing list, separating the database pool names by commas.

  11. In the DefaultPool parameter, specify the name of the database pool you want to be accessed by default. The database pool you most recently created is set to be the DefaultPool by default. This pool is the one accessed in Tcl by the ns_db gethandle command when no pool name is specified and by the version 1.0 backwards-compatible ns_conn db command.

  12. Click Update to commit your changes.

  13. Repeat the previous seven steps for any other virtual server that you want to have access to your new database pool.

  14. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

  15. To test your database pool, access the Administration page for the virtual server that has the nsdb module loaded into it. Use the URL:

    http://server-name:port-number/NS/Admin

  16. Follow the Database Services link. The Database Services Administration page appears. It provides links for each of the database actions.

  17. Click the Add New Table button. The Create Table page appears.

  18. Select the name of the database pool you defined earlier and click the Create Table button.

  19. Create a new table by entering the following information into the appropriate fields on the Create New Table page:
    Table Name: namelist
    Column 1 Name: idnum
    Type: integer
    Not Null: true (checked)
    Index: true (checked)
    Column 2 Name: name
    Type text

  20. Click the Create Table button at the bottom of the page. The table is created in the database, and a confirmation page appears.

  21. Follow the enter new records link. Enter some values into the two fields on the page and click the Enter Record button.

  22. Follow the enter link on the confirmation page and enter another record into the database.

  23. Follow the search link on the confirmation page. Click the Search button without entering any search criteria to retrieve all records.

  24. Return to the AOLserver Administration page and follow the Database Services link. From this page, you can follow the links to perform additional database actions.

Configuring Full-Text Capabilities (nstext Module)

To enable full-text capabilities for a virtual server, you must load both the nsdb and nstext modules into the virtual server, and configure the nstext module so that it points to a database pool which connects to an Illustra database with the Text Datablade installed. Before configuring the nstext module, configure the database module by performing the steps on Configuring Database Services.


Configure Full-Text Capabilities in a Virtual Server:
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. On the Setup AOLserver page, follow the Virtual Servers link. The Setup Virtual Servers page lists all of the virtual servers currently defined. To the left of each server is either a right arrow or a down arrow.

  3. Decide which virtual server you want to configure full-text capabilities for. If the arrow next to it is a right arrow, click the right arrow so it becomes a down arrow. A list of the currently-defined parameters and currently-loaded modules for that virtual server is displayed.

  4. Check to see whether the nstext module is loaded for the virtual server. If it's not loaded, follow the steps below:

    If the nstext module is already loaded for the virtual server, follow the nstext link to configure the nstext module. Enter the name of an Illustra database pool in the DbPool parameter. Set Archive on if you want your pages archived. Set Index on if you want to be able to perform full-text searches on the information in your pages. Set Searchable on if you want users to be able to perform full-text searches on your pages. (The nsadmin user can always perform full-text searches, regardless of the setting of this parameter.) Click Update.

  5. To see the effects of your changes, you must restart AOLserver. If you have inadvertantly made an error in configuration such that AOLserver will not start, follow the instructions on If You Configure Something Incorrectly.

Configuring MIME Type Specifications

To specify MIME types with the Setup Server, use the following instructions.


Specify MIME Types
  1. Access the setup server in one of the ways described in the "Accessing the Setup Server" section.

  2. Follow the Virtual Servers link on the Setup AOLserver page. A page listing all of the virtual servers currently defined is displayed.

  3. Click the right-arrow next the virtual server you want so it becomes a down-arrow and all the parameters for the virtual server are listed (if this hasn't been done already).

  4. Follow the MIME Type Mappings link under the virtual server..

  5. Specify the Extensions and MIME Types you want in the appropriate fields and click Update. The extensions and MIME types will be used to replace the default definitions or add new MIME type definitions. (If you click on the light bulb icon at the top of the page, the default MIME types are listed at the bottom of the page.)

Configuring URL to File Mappings

AOLserver allows you to create URL to file mappings in the configuration file. This capability was previously a module available as an example called Alias. It is now the default behavior of AOLserver. You do not need to load a separate module; you just need to specify aliases for URLs in the configuration file.

You can use the Setup Server to configure URL to File mappings. Follow the Virtual Servers link, and then the Aliases link under a virtual server:

Note: After you make changes to the aliases and restart your server, you may need to clear your browser's disk cache to see the effects of your changes.

Here are some simple examples of URL to file mappings:
URL Input File Path Output Comments
someplace harder/to/type/place The path specified in File Path Output is relative to the server's page root.
here/foo.html there/foo.html Files can be referenced explicitly.
old /usr/local/new The leading slash in File Path Output indicates an absolute path on the server file system.
/old new Leading slashes in the URL Input are optional, except for the special single slash case shown below.
/ /home/newroot This mapping overrides the PageRoot parameter defined for this virtual server and defines the implicit root for all of the relative paths specified in the other mappings. If both a PageRoot parameter and a mapping in the [ns/server/servername/aliases] of the this form exist, the explicit mapping will take precedence over the PageRoot setting.

Important Note: You must specify a file specification, not an URL, under File Path Ouput. You can only map an URL to a file, not an URL to another URL.

Here are some more advanced examples that incorporate users' home directories
URL Input File Path Output Comments
/user1 ~godzilla The initial "/user1" substring is replaced with the home directory of the godzilla user. E.g., /user1/heavy maps to /home/godzilla/heavy.

/user2 ~ The initial "/user2" substring is replaced with the home directory of the user specified in the component that follows "/user2". E.g., /user2/bambi maps to /home/bambi.

/~ ~/pages The initial "~"-prefaced username is replaced with the home directory of the user prepended to "pages". E.g., /~foot maps to /home/foot/pages and /~foot/specialplace maps to /home/foot/pages/specialplace.

.

Note on Backwards Compatibility:

The last example above obviates the need for the UserMapDir configuration parameter. To provide compatibility with the previous default URL to file aliasing, the new capability automatically inserts a mapping to reflect a UserMapDir parameter if it is set in the configuration file. If both a UserMapDir parameter and a mapping in the [ns/server/servername/aliases] of the form "/~=~/otherplace" exist, the explicit mapping will take precedence over the UserMapDir setting.

Top of Page

[ Previous ] [ Contents ] [ Index ] [ Next ]
Copyright © 1996 America Online, Inc.