Configuring CL-HTTP for MCL

Basic Configuration

Physical Memory

CL-HTTP runs well with 9192K bytes of memory and virtual memory turned off. You may want to set the preferred size of MCL using Get Info from the File Menu in the Finder on the MCL Application. You may be able to run with 6-8 megabytes if you do not intend to compile or use much space.

Networking Software

Macintosh computers offer two network software packages: OpenTransport TCP/AppleTalk and the legacy MacTCP/AppleTalk. OpenTransport runs natively on both PowerPC and 68K architectures, whereas MacTCP runs natively only on 68k machines. OpenTransport (version 1.1.1 or later) is recommended for use with CL-HTTP.

Load Server

On a Macintosh, http:mcl;sysdcl.lisp will just load the server while http:mcl;start-server.lisp will load the server and start it running by automatically performing steps 3-5.

Set Configuration Switches

Load Configuration.lisp or equivalent to initialize a number of variables controlling the operation of the server. The comments describe the significance of the various parameters. Consider enabling email so that automatic bug reporting and other programmatic email transmission can work.

Export URLs

Use http:export-url function to make URLs available through the server. At first, load the examples in Exports.lisp. Then, you can adapt or extend these examples to meet your own needs.

Start Server

Evaluate the function http:enable-http-service to start the server.

Stop Server

Evaluate http:disable-http-service to stop the server. In MCL 2.0.1 or earlier, use Command-. before evaluating http:disable-http-service.

Production Configuration

Once you are ready to open up your server to production level loads, you can improve server performance by making the following changes to your version of Configuration.lisp:

Keep Lisp in Foreground

MCL CL-HTTP is able to control the amount of the machine allocated to HTTP service most effectively when the CL-HTTP application is in the foreground. When it is in the background, scheduling depends on the whims of other applications running on the Macintosh. In general, fewer competing applications will mean better HTTP performance.

Turn off Virtual Memory

Load up your server with enough physical memory so that you can run MCL without virtual memory turned on. This will reduce disk contention.

Serve Static Pages From RAM

Major performance improvements can come by eliminating moving parts from your server, most notably the disk drive. There are two ways to reduce or prevent disk accesses during Web service:

1. Increase RAM Allocated to Disk Caching: In the memory control panel off the Apple Menu, increase the amount of RAM used for disk caching to between 1 and 5 megabytes, or more. Larger RAM disk caches reduce the likelihood that the server must retrieve static web data from the file system. Thus, web server performance from disk access speeds, which are normally much slower than network speeds. For maximum performance, allocate enough RAM for the disk cache to hold all the frequently-accessed pages on your server plus 5 or so megabytes for other disk accesses (e.g., file logging).

2. Move Static Web Pages into a RAM Disk: In the memory control panel off the Apple Menu, create an appropriately-sized RAM disk and check the box to save. on shutdown. Move the folder containing static Web pages onto the RAM disk. Export the pages from the folder on the RAM disk.

Assuming sufficient RAM is available to hold all static Web pages, both approaches should achieve the same results, although the disk caching approach can conserve memory because it works with memory less than the total size of all static pages.

Disable Log Domain Resolution

Set the variable http:*resolve-ip-addresses-for-log* to NIL or your machine will be bogged down trying to resolve client domain names.

Disable Log Notifications

Turn off log notifications on the console with http:log-notifications-on.

Tune Simultaneous Connections

Adjust the number of simultaneous connections that you allow with http:set-maximum-number-of-connections.

Enable Email Interface

Set the variable smtp:*network-mail-host* to the primary store-and-forward mail host at your site, and provide some alternates on smtp:*store-and-forward-mail-hosts* in case the primary mailer is unavailable. This will enable automatic bug reporting via www-utils:report-bug and allow response functions to send email during www-utils:send-mail-from.

AppleTalk & Standalone Configuration

CL-HTTP can run standalone or over an isolated AppleTalk network. This describes the configuration with or without domain name resolution service (DNS).

When DNS is available from a server such as Apple's MacDNS, set TCP to connect via AppleTalk.,enable AppleTalk, and use the Basic Configuration with the standard configuration file, Configuration.lisp or equivalent.

For standalone operation, the disconnected server talks to the browser via a AppleTalk loopback connection. However, running a DNS server may be too cumbersome for many standalone configurations. The main objective is to avoid resolving domain names. Thus, all references to URLs must use the IP address of the server. Any references to the local host in HTML should omit the host component so that URLs will be relative to the local host (IP address) serving the documents.

This configuration allows standalone service to clients running on the same host without a connection to a network. It also works for to clients running on other hosts and connecting to the server over an AppleTalk link (e.g., ethernet, LocalTalk cables, IrTalk wireless nets).

Network Configuration

Follow either OpenTransport or MacTCP configuration steps depending on which networking software is installed on your computer.

OpenTransport Configuration

Set MacTCP on both the server or client machines as follows:

1. AppleTalk Control Panel
   Create a LocalTalk configuration for AppleTalk (Command-K) and, using the basic AppleTalk configuration mode (Command-U), set it as follows:
   • Connect Via: Printer Port
   • Make sure AppleTalk is active.

2. TCP/IP Control Panel
   Create a LoopBack configuration for TCP/IP and, using the advanced OT configuration mode (Command-U), set it as follows:
   • Connect Via: AppleTalk (MacIP)
   • Configure: Using MacIP Manually
   • Select Hosts File: Macintosh HD:System Folder:Hosts
     See how to set host name mappings.
   • Ip Address: 127.0.0.3
     Any unique IP address will do. 127.x.x.x is the LoopBack IP subnet reserved for standalone applications whereas 10.*.*.* is reserved for private subnets not connected to the internet.
   • Implicit Search Path: AppleTalk.net
     Any unique domain name will do.
   • Make sure TCP/IP is active.

MacTCP Configuration

Set MacTCP on both the server or client machines as follows:

• Use AppleTalk.
• Obtain address Manually.
• Set IP Address uniquely.
• Make sure AppleTalk is active.

Domain Name Service

Proceed with the Basic Configuration except substitute the configuration file, Configuration-AppleTalk.lisp or equivalent.

Host Names

Domain names may be used after you have specified the mapping from the IP address to the host name in the Hosts file in your system folder. Here is an example of what might appear in your Macintosh HD:System Folder:Hosts file:

Local-Host.AppleTalk.Net A 127.0.0.3 ;AppleTalk operation (stand alone)
WWW.AppleTalk.Net CNAME Local-Host.AppleTalk.Net      ; canonical name

This can be used to give your host the name local-host so that you don't need to remember its IP address, or names might be given to any number of local talk hosts by providing the IP-DNS mappings in the hosts file of each machine.

PowerBook Configuration

Disconnected Operation

Use the AppleTalk Server Configuration.

Power Cycling

Disable the power saving feature whereby the computer conserves power by sleeping the computer.

Sleeping

Make sure that the processor cannot go to sleep while Web serving and while the network is active.

Saving Binary Images

You can save a binary image containing CL-HTTP in order to reduce the time required to launch the server. These server application images are easiest to manage if they are unconfigured and contain no URL exports. They can be booted and configured in any way without concern to data that might be cached in the image, such as local host information, configuration preferences, or exported URLs.

Load Server

Load the server without any configuration file or URL exports into a fresh MCL image.

(load "http:mcl;sysdcl")

Save Image

Save the application using:

(ccl:save-application "CL-HTTP-major.minor" :init-file "CL-HTTP-Init.lisp")

If you want to have the server launch automatically when the Lisp image is booted, CL-HTTP-Init.lisp should reload the logical pathname translations from http:mcl;translations.lisp, perform a standard server configuration, load an exports file, and enable HTTP service with http:enable-http-service. See the example init file in http;mcl;examples;cl-http-init.lisp. Otherwise, web configuration or the CL-HTTP toolbar item may be used to manually configure and launch the server.

When circumstances require saving configuration information and URL exports in lisp images, it is necessary to reconfigure the image and remap the URLs every time the image is booted on different host computers. Loading a configuration file like http:examples;configuration.lisp will update all the parameters, but it will be necessary to use url:remap-url-host to remap any local URLs from the old host to the new host.

When a server image is intended for users rather than developers, the binary image should be saved with the Digitool application generator in order to reduce the amount of disk space consumed by the application, and limit the facilities available to users.

If you have any questions or suggestions, send mail to www-cl@csail.mit.edu