MacHTTP Technical Reference

This document is intended to provide a reference to MacHTTP features and capabilities. Detailed tutorials and "how to" information can be found in the "Tutorials" folder.

MacHTTP World Wide Web Server for Macintosh

Table of Contents

1.0 Introduction

What is it?

MacHTTP 2.0 is a server for Macs participating in the World Wide Web (WWW). It allows you to serve hypertext documents to other WWW users from your Macintosh. MacHTTP allows you to serve text documents (like HyperText Markup Language documents) as well as binary files (GIFs, JPEGs, etc.). In addition, MacHTTP supports the execution of AppleScripts and other applications that cooperate with MacHTTP and can return HTML or other data to WWW clients. This allows you to integrate applications like FileMaker Pro, AppleSearch, HyperCard, or any custom application with MacHTTP. This server works with all WWW clients ands supports the HTTP/1.0 standard.

The server places a relatively small load on your Mac, both in memory and CPU requirements. It should run fine in the background on any Mac with MacTCP installed and System 7. MacHTTP runs in native mode on both 680x0 and Power Macs and is distributed as a "fat binary."

Many applications have been created to work with MacHTTP, including tools for supporting clickable maps, free text searches, fill-in forms, and other WWW functions. Information about these tools, additional examples, product update information, and the latest versions of MacHTTP can always be found on the MacHTTP Home Page. There is also a very active mailing list dedicated to MacHTTP, machttp_talk. Information on subscribing to this mailing list can be found on the MacHTTP Home Page as well. See the Support section below for more details.

What's New?

Version 2.0 of MacHTTP includes an incredible number of new features from version 1.3. A few of these include:

2.0 Installing MacHTTP

System Requirements: MacHTTP requires System 7 and MacTCP. If you want to take advantage of advanced features like searchable documents and clickable maps, you also need to have AppleScript installed. MacHTTP will run on any Macintosh that meets these criteria and has at least 600k of free memory. MacHTTP is a "fat binary" which means it will run on either 680x0 Macs or Power Macs and will run at full speed in native mode on either platform.

Installing MacHTTP is extremely easy. Simply unarchive the MacHTTP distribution archive using a relatively recent version of something like Stuffit Expander or UnStuffit. The resulting folder already has everything installed in the proper places. You may place this folder on any disk, in any location.

Once you have MacHTTP unstuffed, simply double-click the application to activate the server. Use a WWW client like Mac Mosaic or NetScape to connect to the following URL, substituting your Mac's host name or IP address in place of "":

You're now officially a part of the World Wide Web. It's important to read the rest of this documentation and examine the example files in order to get the most out of MacHTTP. The World Wide Web is a complicated system, so don't get discouraged if things don't work right on the first try. Look on the bright side. Without MacHTTP, you'd be forced to do this on a Unix box!

Installing AppleScript is relatively straight forward. Simply copy the contents of the "Apple's Scripting System" folder to the locations specified by the folder names. Specifically, inside the "Apple's Scripting System" folder are two folders. The contents of these folders should be copied to your Extensions folder inside your System folder. Do not copy the contents of the Power Mac folder if you aren't running MacHTTP on a Power Mac. If you are using a Power Mac, copy the contents of both folders to your Extensions folder. Installing the Frontmost extension is optional and it is not required for use with MacHTTP.

Once you have copied all of the scripting extensions and the Scripting Additions folder to your Extensions folder, you must reboot your Mac.

3.0 Configuring MacHTTP

MacHTTP is configured by making changes to the "MacHTTP.config" file found inside the MacHTTP application folder. Some changes may be made via menu selections when MacHTTP is running, or by sending AppleEvents to MacHTTP as well. The configuration file consists of a series keywords and arguments that adjust various parameters affecting how MacHTTP runs. MacHTTP.config is a plain text file that can be modified using any text editor, including TeachText.

MacHTTP Settings File

When run for the first time, MacHTTP creates a file in the same folder as the application called "MacHTTP Settings." This file stores things like the position and size of the MacHTTP Status window, usernames and passwords for security settings, and menu selection settings from MacHTTP's Option menu.

Data in this file is stored in the resource fork of the settings file, so there is no way that a remote WWW client can access this information.

MacHTTP stores the settings file in the same folder as the application, rather that placing it in the preferences folder inside your System folder. This allows you to run multiple copies of MacHTTP in different folders on the same Mac. There are several times when this is a good idea, such as running a secure server on a different port than a public access one.

Configuration File Reference

This section details the commands that can be entered in the MacHTTP.config file to modify MacHTTP's behavior. Each section describes keywords, their arguments, and provides examples of their use. Open and read the comments in the MacHTTP.config file for more information and examples.

Each command in the config file must start on a line by itself and each line should start with a keyword. Lines that don't start with a recognized keyword are considered as comments. Arguments specified inside angle brackets ("<", ">") should be replaced with the appropriate value for your server in the config file, omitting the angle brackets.

Special Files

There are several commands in the config file that define the names of special files used by MacHTTP.

INDEX <file name>: specifies the Home Page or Index for the server. This is the default document returned if a WWW client accesses your server and specifies the document "/" or no document at all. A default index document may be present in every folder within the MacHTTP directory hierarchy. Simply name the local index file the same as the INDEX file specified in the config file.

Important note, the name of the INDEX file must be a simple file name. You may not specify a path or partial path as you can for other special files.

The INDEX file may be a HTML file, or it can also be the name of a script or application to execute.

If omitted, the default INDEX file name is "Default.html" (no quotes).

ERROR <file name>: specifies the file returned by the server if an error occurs. This is usually an information message informing the user that a requested file cannot be found.

If omitted, the default file name is ":Error.html" (no quotes).

LOG <file name>: specifies the log file for the server. A log of all client accesses is maintained in this file. See the <Log File section below for more details.

If omitted, logging is disabled and no log file will be created. Logging may also be disabled by selecting the Suspend Logging menu choice from the Options menu.

NOACCESS <file name>: specifies the file to be returned by the server if a client that is not authorized to access the server attempts to request a file. This file is only returned for clients that violate IP address or domain name security restrictions. See the Security section below for more details.

If omitted, the default file name is ":NoAccess.html" (no quotes).


ERROR   :Error.html
INDEX   Default.html
LOG     :MacHTTP.log
NOACCESS :NoAccess.html

File names that begin with a ":" tell MacHTTP to look within the same folder as the MacHTTP application for the files. While not required, it's a good idea to make sure the ":" is included for security reasons. Do NOT do this for the INDEX file!

Suffix Mapping

MacHTTP needs to know the difference between text, binary, script, application, and CGI files in order to use the appropriate file transfer method when returning data to a WWW client. For example, HTML (HyperText Markup Language) are text files and need to be converted before transmission to a WWW client because the Macintosh TEXT file format (CR at the ends of lines) is unsuitable for many WWW clients, which expect CR/LF at the ends of lines.

Also, some files like QuickTime movies and GIF images need to be transmitted to the client as byte for byte copies of the original file, using a "binary" transfer mode. In order to help MacHTTP distinguish which transfer method to use, you may specify an unlimited number of "suffix mappings" in the config file. These mappings tell MacHTTP whether to use a text or binary file transfer when sending a file, or to execute the script or application, based on the suffix of the file's name.

MIME Types and HTTP/1.0.MacHTTP returns information to WWW clients specifying the content type of the requested document using the headers and MIME types defined as part of the HTTP/1.0 specification. Without these MIME type specifications, WWW clients may not know what to do with the data received from MacHTTP. The syntax of the following commands allows you to define the MIME types associated with a particular file name suffix, Mac file type, or creator.

MacHTTP uses the Mac file type and creator information in addition to the suffix portion of the file name to help determine which MIME type to return to a client. MacHTTP examines the file's suffix first. If it fails to find a match, MacHTTP then looks at the Mac file type and creator information in an attempt to find a suffix mapping to use. Failing this, MacHTTP uses the default transmission and MIME types.

The MacHTTP.config file contains the most commonly used suffix definitions and MIME types. You can examine these entries and the associated comments for more details on how to add your own suffix mappings and MIME types. Your MIME types must match the MIME types specified in your WWW client's "helper applications" configuration in order for documents to be opened correctly by the client.

The syntax of a suffix mapping entry in the config file is as follows:

<transfer type> <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype>

Transfer type describes the operation MacHTTP will perform on a file that matches a particular suffix mapping. For example, a text-only or binary file transfer operation may be indicated (TEXT or BINARY transfer types), or MacHTTP may actually launch another program and communicate with it (SCRIPT, CGI, ACGI types).

Suffix is the actual suffix of a file's name that will be matched to determine the MIME type and transfer type for a file.

Mac File Type & Mac Creator are used in addition to help match a file to the correct MIME and transfer type. If these values contain special characters, you may encode them using the %xx encoding scheme used in URLs.

MIME Type is the information that MacHTTP conveys to WWW clients to indicate what type of file is being returned, using standard types and subtypes such as text/html or application/mac-binhex40.

Unknown or unspecified parameters should be replaced with "*" as a placeholder. If the client supports HTTP/1.0, the appropriate MIME header will be constructed when appropriate and returned, based on the suffix mapping info. Note that scripts are responsible for generating their own HTTP/1.0 headers!!!

There is no limit to the number of suffix mappings that can be defined in the config file. If none, or fewer than 20 mappings are provided, MacHTTP uses internal defaults to supply the missing mappings.

Commands for defining suffix mappings in the config file:

TEXT <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> : Files matching the specified suffix, file type, and/or creator will be sent as text-only files to the client.

BINARY <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> : Files matching the specified suffix, file type, and/or creator will be sent to the client without modification to the file's contents. Only the data fork of the file is transmitted.

SCRIPT <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> : Files matching the specified suffix, file type, and/or creator will be loaded and executed as an AppleScript source file. The script is expected to generate HTML text and return it to MacHTTP as the result of script execution. This result will then be transmitted to the client as TEXT files above.

APPL <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> :
NOTE! This file type is considered obsolete and its use is strongly discouraged! Use the CGI and ACGI file types instead. Files matching the specified suffix, file type, and/or creator will be treated as an application and launched by MacHTTP. MacHTTP will then pass any arguments to the application using the "Search" AppleEvent. The application is expected to generate HTML text and return it to MacHTTP as the result of processing the AppleEvent. This result will then be transmitted to the client as TEXT files above. See the AppleEvents section below for more details.

CGI <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> :
Files matching the specified suffix, file type, and/or creator will be treated as an application and launched by MacHTTP. MacHTTP will then pass any arguments to the application using the "Search Doc" AppleEvent. The application is expected to generate a legal HTTP/1.0 header and any response information and return it to MacHTTP as the result of processing the AppleEvent. This result will then be transmitted to the client without modification. See the AppleEvents section below for more details.

ACGI <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> :
Files matching the specified suffix, file type, and/or creator will be treated as an application and launched by MacHTTP. MacHTTP will then pass any arguments to the application using the "Search Doc" AppleEvent and resume processing other requests. The application is expected to generate a legal HTTP/1.0 header and any response information and return it to MacHTTP as the result of processing the AppleEvent. When MacHTTP receives the event reply, it processes the result, which will then be transmitted to the client without modification. See the AppleEvents section below for more details.

DEFAULT <type> <MIME type>: "type" can be one of TEXT, BINARY, or SCRIPT. "MIME type" is the default MIME type to use if an exact match can't be found for a file's suffix, type, or creator. The DEFAULT command specifies the default file transfer type and MIME type to be used if a file's suffix doesn't match one of the 20 defined suffix mappings.

Example Config File Extension/Creator-Type/MIME Mappings

Text (ASCII)
    TEXT   .HTML   TEXT *    text/html
    TEXT   .TEXT   TEXT *    text/plain
    TEXT   .TXT    TEXT *    text/plain
Rich Text Format (RTF)
    TEXT   .RTF    RTFf MSWD text/richtext
    APPL   .EXE    APPL *    text/html
AppleScripts - SCRIPT
    SCRIPT .SCRIPT TEXT *    text/html
    SCRIPT *       TEXT ToyS text/html
Binary Hex - HQX
    TEXT   .HQX    TEXT BNHQ application/mac-binhex40
Stuffit - SIT
    BINARY .SIT    SITD *    application/x-stuffit
Zip Compressed
    BINARY .ZIP    pZIP *    application/zip
    BINARY .au     ULAW *    audio/basic
    BINARY .AIFF   *    *    audio/x-aiff
    BINARY .GIF    GIFf *    image/gif
    BINARY .PICT   PICT *    image/pict
    BINARY .JPG    JPEG *    image/jpeg
    BINARY .JPEG   JPEG *    image/jpeg
    BINARY .XBM    XBMm *    image/x-xbm
    BINARY .TIF    TIFF *    image/tiff
    BINARY .EPS    EPSF *    application/postscript
    BINARY .MOV    MooV *    video/quicktime
    BINARY .MOOV   MooV *    video/quicktime
MPEG Video
    BINARY .MPG    MPEG *    video/mpeg
Microsoft Word
    BINARY .WORD   WDBN MSWD application/msword
Microsoft Excel
    BINARY .XL     XLS3 *    application/excel
    BINARY .XLS    XLS3 *    application/excel
    [change the XLS3 to XLS4 if you are using Excel 4.0]

Note that in the case of SCRIPT, APPL, CGI, and ACGI types, the script or application is responsible for returning the correct MIME type as part of the HTTP/1.0 header. Please examine the sample scripts in the "Tutorials:Examples" folder or The "Extending MacHTTP" tutorial for more details on how to construct these headers. The "*" specifies that the missing parameter is to be ignored by MacHTTP when searching for the correct suffix mapping and MIME type.


Security can be provided by MacHTTP in two ways. The first way is on a host by host basis. You may specify hosts and networks to ALLOW or DENY access to. MacHTTP matches the IP address or domain name of a client requesting a file to a table of security directives. Based on the matches found, MacHTTP will either return the requested file to the client or issue a message (from the file specified by the NOACCESS command) saying access is denied.

The second way MacHTTP can limit access to files on the server is by username and password. Files are assigned to security "realms" and users are assigned a username and password to access a specific realm. In order to access any file in a specific realm, the remote user must specify a valid username and password. Otherwise, the client is informed by MacHTTP that the user does not have permission to access the file using standard error messages built into the HTTP protocol.

The following commands are used to allow or deny access to the server based on a client's IP address or domain name. IP addresses are matched from left to right. Domain names are matched from right to left. See the Security tutorials in the "Tutorials" folder for more details.

ALLOW <address>: Specifies the partial or complete IP address or domain name of a host (or hosts) that is allowed to access the server.

DENY <address>: Specifies the partial or complete IP address or domain name of a host (or hosts) that is denied access to the server.

The next command is used to define security realms for username/password security:

REALM <match string> <menu name>: Defines a security realm, specifying the string to match in a URL which determines what security realm a file belongs to and provide a human-readble realm name for the Realm menu in MacHTTP's Edit Passwords dialog as well as the username/password dialog that WWW clients present. See the Security tutorials in the "Tutorials" folder for more details.

Security Examples

An unlimited number of security directives may appear in the config file. If none are present, then any client may access the server. If one or more directives is present in the config file, the directives are evaluated in the order they appear in the config file to determine whether a client is allowed to access the server.

If security directives are present in the config file, there is an implicit "DENY *" that is evaluated before any directives in the file. This means that all clients are denied and you must explicitly allow clients by using the ALLOW command to specify complete or partial addresses of clients which can access the server.


ALLOW 129.166.
DENY  129.166.3
ALLOW .edu

These example statements are evaluated as follows. First, the implicit "DENY *" is evaluated, implying that no hosts may access the server. The first ALLOW statement specifies that all clients with addresses that begin with "129.106." will be allowed to connect to the server. NOTE! "DENY *" is NOT legal syntax. MacHTTP logically does this internally. Specifying ALLOW * or DENY * in the config file will have NO effect.

The DENY statement says that all clients with IP addresses that begin with "129.106.3" are denied access the server. Important note: The DENY statement not only matches all hosts in the "129.106.3" subnet, but also all hosts in "129.106.30", "129.106.31", etc. If you wanted to only restrict hosts in the "129.106.3" subnet, you should add a trailing "." to the IP address (i.e., "129.106.3.").

The next ALLOW statement explicitly enables the host "". This statement matches only this specific host. MacHTTP always appends a trailing "." when comparing a client's IP address to the security entries. This means to match exactly one host with an ALLOW or DENY statement, the IP address argument must end with a "." Finally, the last two lines will match any domain name ending ".edu", allowing access and will deny access to any host in the domain.

Big Hint. If you want to have a WWW service that has some public and some private pages, the easiest way to do this is by running multiple MacHTTP servers on a single Mac or using REALM-based security. Make sure that multiple servers are running on different PORTs (see the following section). One server can have no access restrictions while another restricts access to specified hosts.

Realm-based security example

Suppose the following line is in the config file:
REALM private Private_Stuff

Any URL received by MacHTTP that contains the string "private" in the path name of the URL will cause MacHTTP to prompt the WWW client for a username and password. The WWW client will ask the user to enter a username and password for the realm "Private_Stuff". If there is a valid username and password in the MacHTTP Settings file that those supplied by the user for the "private" realm, MacHTTP will grant access to the requested file.

Examples of URL paths that would match the "private" realm are:

Use the Passwords... command under MacHTTP's Edit menu to define usernames and passwords.

Port Number

MacHTTP defaults to listening for all incoming connections on the standard HTTP port 80. It is possible to change this number, allowing multiple MacHTTP servers to run on one Mac on different ports. An example might include running a public access server on port 80 and a restricted access server on port 1080. Note, port numbers below 1024 are reserved for well known services such as telnet, FTP, HTTP, Gopher, etc. If you change the port number for MacHTTP, you should use a number above 1024.

PORT <number>: Specifies the port number that MacHTTP will listen to for all incoming connections. The default is port 80 if this line is omitted from the config file

User Limit

MacHTTP will allow you to define a maximum number of users that may be simultaneously connected to the server. This is useful for servers with limited resources or for extremely busy servers that need to limit the number of queued requests.

The minimum number of simultaneous users is 3. Because of the way MacHTTP handles incoming requests and terminates connections, it is possible for a single, fast client to create a new connection before the previous one is dropped by MacHTTP. This, coupled with the fact that MacHTTP always reserves one connection for listening for incoming client requests means that at least 3 connections should be provided for at a minimum.

The maximum number of users is arbitrarily limited to 1000. Since MacHTTP can only transmit the data for one request to a client at a time, all other clients' requests are queued and executed in turn. Setting the maximum number too high will result in intolerable delays for clients. These delays could exceed MacHTTP's timeout value for inactive connections, so it's probably a good idea to leave the maximum users setting somewhere between 8 and 20.

Incoming clients that exceed the maximum number of users will be informed that the server is too busy to handle their request. Note that MacTCP can only handle a maximum of 64 simultaneous connections. MacHTTP restricts the maximum number of connections to 48, leaving 16 connections available for other uses on the Mac.

MAXUSERS <number>: Specify the maximum number of simultaneous users allowed to connect to MacHTTP. Values between 3 and 48 are allowed. The default is 8 if this statement is omitted from the config file.

Listening for Clients

Older versions of MacHTTP would listen for a single incoming connection. On busy servers, this often caused clients to receive "Unable to connect" errors because MacHTTP was unable to process an incoming connection and get ready for a new one quickly enough. MacHTTP now supports a configurable number of "listens", allowing the server to handle multiple, simultaneous, incoming connections.

MAXLISTENS <number>: Defines the number of simultaneous listens for incoming client connections. Values between 3 and 48 are allowed. The default is 5.


MacHTTP will disconnect any client that fails to interact with the server after a specified amount of idle time has passed. If it takes longer than the timeout period for MacHTTP to complete a client's request (i.e., the server is busy, or an AppleScript takes a long time to execute), the client will be disconnected as well. Therefore, it is important to monitor the average time that clients wait in the queue and adjust this value accordingly.

TIMEOUT <seconds>: Specifies the maximum amount of idle time in seconds before MacHTTP disconnects a client's inactive connection. This command also sets the amount of time MacHTTP will wait for a reply to an AppleEvent it has sent to an external application (CGI, ACGI, etc.). The minimum value is 15 seconds. The maximum value is 600 seconds and the default is 90 seconds if this statement is omitted from the config file.

Commands for Tuning MacHTTP's Performance

The following two commands can be used to adjust how MacHTTP performs over slow connections or on a Mac that isn't dedicated to server use only.

PIG_DELAY <ticks>: Specifies the number of ticks that MacHTTP will "steal" from other processes while sending data to clients. This equates directly to how much time MacHTTP will spend processing connections. Your Mac will effectively be dedicated to MacHTTP for this period of time. The argument is in "ticks", which are 60ths of a second. The default is .5 seconds (30 ticks). Values can range between 0 and 120 ticks.

DUMP_BUF_SIZE <bytes>: Specifies the chunk size that MacHTTP will divide file transfers into. The larger the chunk, the longer it will take to transmit over slow connections. The smaller it is, the more times MacHTTP will be able to swap between servicing multiple connections and freeing the Mac to work on other processes. The argument represents the max number of bytes to be sent in a single MacTCP write to the client. The min is 256, the max is 10240.

Note: PC-based WWW clients that use the Trumpet socket driver may experience problems with MacHTTP if the DUMP_BUF_SIZE is too large. Lowering the size or reconfiguring Trumpet to allow larger incoming buffers will solve the problem.

NO_DNS: Tells MacHTTP to avoid performing any domain name service look-ups and to only use IP addresses in all status reporting and logging. For some sites with slow domain name service, this can result in a substantial performance increase. MacHTTP caches recent domain name look-ups, so this command should only appear in the config file if DNS problems exist on your network.

Configuration File Version

Newer versions of MacHTTP require additional information to be included in the config file for proper operation. Using a new version of MacHTTP with an old config file can result in unpredictable behavior. Therefore, the VERSION command has been added and must be present in every config file to specify what version of MacHTTP it is tailored to.

MacHTTP uses this information to warn the user of potential version mismatches that could lead to problems in serving documents

VERSION <version number>: Specifies the version of MacHTTP that this config file is supposed to be used with. The version number should match the version of MacHTTP that is displayed in the "About MacHTTP" dialog box. (e.g., 1.3 or 2.0)

MacHTTP Menus

Most configuration of MacHTTP occurs in the config file. However, certain options that affect the status window or server behavior are implemented as menus. MacHTTP saves and restores the settings of these options across executions of MacHTTP in the MacHTTP Settings file. This section describes the functions contained in these menus.

All MacHTTP menu functions can be invoked via AppleEvents. So if MacHTTP is running on a "headless" Mac or you want to use AppleScript to control its behavior, you may execute any of the menu commands from another application. See the "Scripting and MacHTTP" section below or examine MacHTTP's AppleEvent dictionary (aete resource) for more details.

File Menu

This one is simple. All you can do is quit.

Edit Menu

MacHTTP allows the contents of the Status Window to be copied to the clipboard as text, so "Copy" and "Cut" are the only function edit commands available in this menu.

Passwords... This menu also contains the command for modifying username and password information that MacHTTP uses for realm-based security. Selecting "Passwords..." shows this dialog. To add a user, select a realm from the Realms pop-up menu at the bottom of the screen, enter a username and password in the appropriate text fields and click the Add button. To delete a user, select the user from the User/Realm scrolling list and click the delete button. To modify a user, delete it and add it again with the corrected information.

Options Menu

Functions under the Options menu allow you to change the behavior of MacHTTP. All selections made in this menu are saved in the MacHTTP Settings file and restored the next time MacHTTP is run.

Verbose Messages: Causes MacHTTP to produce much more status information about client requests and what the program is doing internally. You should enable this option if you are having trouble with MacHTTP and aren't sure what's going on. The cryptic nature of these messages is sure to help add to the confusion, since most pertain to internal MacTCP state information. However, some of the messages are useful for watching details of client requests, etc.

Suspend Logging: Temporarily closes MacHTTP's log file (if a log file is specified in the config file), allowing you to open and examine the log file with a text editor. All incoming connection information will not be logged to the file while this option is enabled.

Hide Window in Background: When MacHTTP is running in the background, the status window will be hidden if this menu choice is selected.

Refuse New Connections: This option allows busy servers to remain running, but not allow any new clients to connect. All currently queued clients will be served, but no new connections will be accepted. Clients will be notified that connections are being refused. This option is useful for gracefully shutting down a server, or allowing you to change HTML documents while the server is running.

4.0 Serving Documents

HTML documents, including file references, links, anchors, and naming conventions used by MacHTTP are 100% compatible with those used by Unix-based HTTP servers. MacHTTP communicates with WWW clients running on any platform.

It is important to note that MacHTTP can interpret both Unix and Mac file specifications. Typically, HTML documents are written using Unix path names, etc. while file names specified within MacHTTP's config file use Mac file naming conventions.

MacHTTP also understands Macintosh aliases. If you create an alias to a document for MacHTTP to serve, MacHTTP will use the name of the alias for suffix mapping, then translate the alias to find the original file's contents.

IMPORTANT NOTE!!!! MacHTTP only interprets aliases to files. Aliases to folders or disks will not be resolved correctly.

File Locations

MacHTTP always expects that the files requested by WWW clients will reside in the same folder as MacHTTP, or subfolders within this folder. This means that clients cannot explicitly request files that live outside of the folder tree where MacHTTP resides. MacHTTP behaves this way for security reasons, since this prevents people from requesting files on your Mac besides those you explicitly place within the view of MacHTTP.

This means that the "root" of MacHTTP's file system starts with the folder the MacHTTP application resides in. Clients requesting documents from MacHTTP specify URLs as if MacHTTP was at the root of the file system.

How MacHTTP interprets file names

MacHTTP goes through the following steps when interpreting a client's request for a specific file:

NOTE: While you can use aliases to original files that aren't contained within the MacHTTP directory tree, any URLs contained in these files must still provide paths that are relative to where MacHTTP resides. This is done for security purposes and isn't subject to change.

URL Examples

Assume the following. Suppose MacHTTP is installed on a drive called "Hard Disk", inside a folder called "WWW". In the "WWW" folder are the files from the MacHTTP distribution, a text document called sample.html, and a subfolder called More_Docs. Inside More_Docs is a text file called another.html.

To access your default home page, you'd specify the following URL:

To access "sample.html" :

To access "another.html" :

Note that all URLs are relative to the folder containing MacHTTP. No parent directories or disks are specified. MacHTTP handles spaces and special characters in folder and file names, but it's a good idea to avoid spaces and special characters in any file or folder names that MacHTTP will be serving when possible. Otherwise, you must encode the special characters in file names using the URL standard %xx encodings for each special character, where "xx" is actually the hexadecimal code for the character.

More information on URLs can be obtained from

Information on writing HTML documents for WWW can be obtained from

Serving Documents from Mac Applications

In addition to serving documents like HTML and GIF files, MacHTTP can serve documents from many other types of Mac applications with a few caveats:

Configuring MacHTTP to Serve Mac Documents

There is only one real configuration issue on the MacHTTP side of things to contend with. You must make sure your Mac documents (e.g, Word, Excel) are named with a suffix that is defined in the MacHTTP.config file as BINARY. Entering the appropriate Mac file type and creator codes in the suffix mapping make it possible to serve Mac-specific files without having to resort to renaming the files with special suffixes.

Here's an example. Suppose you have an Excel spreadsheet file called "BigBucks.xl". You must make sure that there is an entry in the MacHTTP.config file that looks like:

BINARY .XL XLS3 * application/excel

This tells MacHTTP to transfer files with names ending in ".xl" or files of type "XLS3" to the WWW client without any modifications. In addition, the HTTP/1.0 header returned to the client will include information telling the client that the MIME type for the Excel document is "application/excel". This allows clients like Mosaic to launch the appropriate "helper application" to view the data once the file has been received. The "*" specifies that the Mac creator information is to be ignored by MacHTTP when searching for the correct suffix mapping and MIME type.

Configuring your WWW client is the next step. If you are using Mac Mosaic, you need to define a file name extension mapping that maps the ".xl" suffix into a specific MIME type. You also need to map the specified MIME type (e.g., application/excel) to a particular "Helper Application." Once you've done this, selecting a URL like will cause MacHTTP to send the file and appropriate header info to the WWW client, and the client (Mosaic) will know which application to launch to view the document.

Scripting, AppleEvents, and MacHTTP

AppleScript is now distributed as part of the MacHTTP distribution. The copy of AppleScript extensions distributed with MacHTTP is for use with MacHTTP and cannot be copied to other machines if MacHTTP is not installed there.

If you have AppleScript installed on your Mac, MacHTTP can execute AppleScripts and return the results as a document to clients. MacHTTP supports scripts that are stored as text-only documents. It also supports launching scripts saved as applications as well as other applications that understand MacHTTP AppleEvents (like HyperCard.) To execute text-only AppleScripts, place a version of a script in a location where MacHTTP can find it. Make sure that the MacHTTP.config file contains an entry for SCRIPT files and that your script is named with the appropriate suffix.

Any WWW client accessing a SCRIPT document will cause MacHTTP to load the source for the script from the file specified in the URL. Several predefined AppleScript variables are created and prepended to the AppleScript source. MacHTTP will then pass the source code to AppleScript for compilation and execution. The result returned from AppleScript is then passed back to the client by MacHTTP.

MacHTTP AppleScript & AppleEvent Variables

MacHTTP assigns values to global variables which are available to all SCRIPT AppleScripts when they execute. The information contained in these variables is passed to CGI and ACGI scripts and applications as named parameters to an AppleEvent instead of global variables. These global variables and parameters correspond to the same arguments that are defined in the Common Gateway Interface (CGI) standard, which was originally developed as a mechanism for passing arguments from Unix server to shell scripts and applications on Unix hosts.

Variable Summary

All of these variables represent information passed to MacHTTP from a WWW client, or information known by MacHTTP and needed by CGI scripts and applications.
 http_search_args - arguments to the URL after a ?
 post_args - arguments to the URL after a $
 method - GET, POST, etc. Used to tell if post_args are valid
 client_address - IP address or domain name of remote client's host
 from_user - non-standard. e-mail address of remote user
 username - authenticated user name
 password - authenticated password
 server_name - name or IP address of this server
 server_port - TCP/IP port number being used by this server
 script_name - URL name of this script
 referer - the URL of the page referencing this document
 user_agent - the name and version of the WWW client software being used
 content_type - MIME content type of post_args
See the example script files in the MacHTTP distribution for more details on how these variables are used.

Searchable Documents, Maps, Forms, etc.

You can use the ability to execute scripts and external applications to implement searchable documents, clickable maps, fill-in forms and all sorts of other neat WWW applications. The tutorial documents in the Tutorials folder provide step by step details on how to build these types of scripts and applications.

Some important notes:

1. AppleScript SCRIPT files MUST be text files (Save as... Text only)

2. AppleScript applications (CGI, ACGI) must be saved as "applications" from the AppleScript Script Editor with the Keep Open and Never Show Startup Screen checkboxes selected. NEVER save AppleScripts in a "compiled" format for use with MacHTTP.

3. You must perform all HTML formatting inside the AppleScript file. MacHTTP expects you to generate and return a proper HTTP/1.0 header from your script or application and does no conversion on the return values from CGI and ACGI type files. SCRIPT type files have some processing done to strip spurious quotes and convert carraige returns returned by AppleScript.

MacHTTP and AppleEvents

MacHTTP supports the 4 required AppleEvents, plus a custom AppleEvent suite for communicating with MacHTTP while it is running. The 4 required events don't do much, since MacHTTP doesn't open or print any documents of its own. However, the custom event suite is very useful for operating MacHTTP under script control or from a remote Mac.

AppleEvents Received by MacHTTP

MacHTTP is completely scriptable and recordable. It supports several events for controlling MacHTTP remotely and requesting status information from a running MacHTTP application The following is a copy of MacHTTP's AppleScript dictionary. The event suite for the MacHTTP events is the same as the 4 character creator code for the MacHTTP application. This is three upper case "W"s, followed by the omega character (generated by typing option-Z). The event codes for each event are listed after each event description.

MacHTTP Suite: Events for communicating with MacHTTP

DoMenu: Execute the specified menu item from the MacHTTP menus.
	DoMenu  'char'  -- "<menu id>, <menu item>", ex. DoMenu "4,1"
    event code: menu

Verbose Messages: Toggle Verbose Messages on or off 
	Verbose Messages  boolean  -- True or False
    event code: fvrb

Hide Window: Toggle hiding status window in the background
	Hide Window  boolean  -- True or False
    event code: fwin

Status Report: Return status information about MacHTTP
	Status Report
	Result:   'char'  -- returns text info about MacHTTP
    event code: stat

Refuse Connections: Toggle incoming connections on or off
	Refuse Connections  boolean  -- True or False
    event code: fcon

Suspend Logging: Turn logging on or off
	Suspend Logging  boolean  -- True or False
    event code: flog

Add User: Add a user and password for a specific security realm
	Add User  'char'  -- username
		password  'char'  -- password
		realm  'char'  -- security realm
    event code: AUsr

Delete User: Delete specified user from a particular security realm
	Delete User  'char'  -- username
		realm  'char'  -- security realm
    event code: DUsr

Class application: MacHTTP application
	class code: capp
	dump_buf_size  small integer  -- Output buffer size for TCP/IP writes
to clients. (256-10240)
         property code: Dbuf

	pig_delay  small integer  -- Number of ticks to run MacHTTP before
relinquishing control to other apps (0-120)
         property code: PigD

	maxusers  small integer  -- Maximum number of simultaneous users.
         property code: MaxU

	no_dns  boolean  -- Toggle for domain name resolution by MacHTTP
         property code: Ndns

	time_out  small integer  -- Timeout value for idle MacHTTP connections
and AppleEvents in seconds (5-600)
         property code: TimO

	maxlistens  small integer  -- Maximum number of TCP/IP listens to
queue up (3-48)
         property code: MaxL

AppleEvents Sent by MacHTTP

If MacHTTP receives a query (GET) from a WWW client requesting a file whose suffix mapping is CGI, or ACGI (an executable application), MacHTTP will attempt to execute this application and communicate with it via custom AppleEvents. Currently, MacHTTP supports two AppleEvents for communication with traditional Mac applications or AppleScript applications.

Search Doc: This AppleEvent is how MacHTTP implements the Common Gateway Interface Standard.

If you are a C or Pascal programmer, the above information will make sense. If you are creating compiled AppleScript applications, see the scripting examples that come with MacHTTP for more details. The tutorial files in the Tutorials folder will provide step-by-step instructions for creating these types of scripts and applications.

Search: Use of the Search AppleEvent is discouraged. It is an older, less capable AppleEvent that is supported for backward compatibility with older versions of MacHTTP. The four character event code is 'srch'. It receives search arguments in the direct parameter and is expected to return a HTTP/1.0 response header and data in the reply parameter.

5.0 Administering MacHTTP

Security Considerations

Every effort has been made to ensure that no access to files outside the MacHTTP application folder can take place. MacHTTP only provides READ-ONLY access to files in its directory tree. HOWEVER, if you allow AppleScript execution, the burden falls on the script writer to make sure nothing naughty can happen.

If you don't want to allow script execution (or don't have AppleScript installed) you can make sure script execution is disabled by modifying the MacHTTP.config file so none of the entries defines a SCRIPT, APPL, CGI, or ACGI type.

As configured "out of the box", MacHTTP provides no restrictions on which hosts may access your server. Please review the section above that describes the ALLOW and DENY commands in the configuration file, which are used to restrict network access to MacHTTP. The Security tutorial in the Tutorials folder provides detailed information.

Log File

MacHTTP defaults to logging all transactions to a file in the same directory as the MacHTTP application. The standard name for this file is MacHTTP.log, but you may change this by modifying the configuration file entry (LOG).

Entries in the log file are separated by tabs, and individual entries are terminated with a carraige return. This format is the standard text-only import format used by most spreadsheet applications (e.g. Excel) and Mac data base applications like FileMaker.

To disable logging, simply delete the log file specification command from the config file (LOG :MacHTTP.log).

Status Window Information

At the top of MacHTTP's status window are 2 lines of information that provide statistics about incoming connections and MacHTTP memory usage. These statistics are provided to make it easier to tune the number of connections MacHTTP needs to allow (MAXUSERS) and how much memory MacHTTP needs to run. The stats are interpreted as follows:



6.0 Administrativia

License Information

MacHTTP is Copyright (c) 1991-1994, Chuck Shotton.

A software license for MacHTTP is included with the MacHTTP distribution in a file called "Licensing Info." This is the standard single user license. You must register MacHTTP and pay the appropriate license fee to activate this license. If you are interested in obtaining a site license for MacHTTP, please follow the MacHTTP ordering instructions contained within this file.

MacHTTP is NOT freeware or public domain software. No cost licenses can be made available to qualifying individuals and organizations according to details within the "Licensing Info" document. MacHTTP may not be included in software anthologies (e.g., CD-ROM collections) without written permission from the author.

The AppleScript system software included with MacHTTP is licensed from Apple Computer, Inc. for use with MacHTTP. You may not copy or install this software on computers for which you do not hold a valid license for MacHTTP.


MacHTTP is provided "as-is". Support is available through MacHTTP's home page,, the machttp_talk mailing list, the comp.infosystems.www.providers Usenet news group, and for registered users, direct e-mail support from the author.

The documentation covers the basic technical information for MacHTTP. Please make sure you've read everything in the documentation, sample files, scripts, configuration file, and MacHTTP home page before you ask a question in e-mail.

Other Info

MacHTTP is being written by Chuck Shotton. Questions from registered users can be addressed to Make sure you refer to your license number in any correspondence. The latest version of MacHTTP and additional information about MacHTTP is available from This site is the home of MacHTTP and always has the current version available for download.

Information on writing your own WWW documents (HTML) can be found at

Information on URLs can be obtained from