MacHTTP Read MeMacHTTP Read MeThe server places a very 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."
MacHTTP is being written by Chuck Shotton. Questions can be addressed to cshotton@oac.hsc.uth.tmc.edu. The latest version of MacHTTP can FTPed from oac.hsc.uth.tmc.edu in the public/mac/MacHTTP directory.
Current information about MacHTTP can be found on the MacHTTP home page at http://www.uth.tmc.edu/mac_info/machttp_info.html. This WWW page contains up to date information about MacHTTP, the machttp_talk mailing list, and many examples on how to configure and use MacHTTP.
MacHTTP has been tested on Mac II and Quadra family CPUs and works fine. Unfortunately, MacHTTP doesn't work and play well with 68000-based Macs like SEs and PowerBook 100s. Anyone who figures out why will be rewarded with an immediate upgrade!
Installing MacHTTP is extremely easy. Simply unarchive MacHTTP 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 to connect to the following URL, substituting your Mac's host name or IP address in place of "your.host.name":
http://your.host.name/
Installing AppleScript is relatively straight forward. Simply copy the contents of the "Apple's Scripting System" folder to the appropriate locations. Inside this folder are two more 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.
Once you have copied all of the scripting extensions and the Scripting Additions folder to your Extensions folder, you must reboot your Mac.
"MacHTTP.config" file
found inside the MacHTTP folder. This 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.
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.
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.
If omitted, the default 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.
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. See the Security section below for more details.
If omitted, the default file name is ":NoAccess.html" (no quotes).
Examples:
ERROR :Error.html INDEX :Default.html LOG :MacHTTP.log NOACCESS :NoAccess.html
Note that the file names begin with a ":". This tells MacHTTP to look within the same folder as the application for the files. While not required, it's a good idea to make sure the ":" is included for security reasons.
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 up to 10 "suffix mappings" in the config file. These mappings tell MacHTTP whether to use a text or binary file transfer when sending a file, based on the suffix of the file's name.
Last of all, MacHTTP can execute AppleScripts and return the results of the script execution back to WWW clients. MacHTTP needs to be able to differentiate between files that are simply sent directly to the client (i.e., binary and text) and files that must be executed first (i.e., AppleScript).
MIME Types and HTTP/1.0. As of MacHTTP 1.2.4, the HTTP/1.0 protocol has been supported. This means that MacHTTP will return additional information to WWW clients, specifying the file type of the requested document using the headers and MIME types defined as part of the HTTP/1.0 specification. In order to handle the definition of this additional information, the syntax of the following commands has been expanded to include Mac file type and creator information, as well as MIME types.
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 Mosaic's "helper applications" section in order for documents to be opened correctly.
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>
Unspecified parameters should be replaced with "*". If the client supports HTTP/1.0, the appropriate MIME header will be constructed and returned, based on the suffix mapping info. Note that scripts are responsible for generating their own HTTP/1.0 headers!!!
There can be a maximum of 20 suffix mappings defined in the config file. If fewer than 20 mappings are provided, MacHTTP uses internal defaults to supply the missing mappings. When MacHTTP starts up, the status window displays the 20 suffix mappings plus the default file type for file names that don't match one of the 20 mappings.
TEXT <suffix> <Mac file type> <Mac creator> <MIME Type/MIME Subtype> : Files matching the specified suffix, file type, and/or creator will have carraige returns translated to carraige return/line feed before transmission 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. 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> : 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 custom AppleEvents. 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.
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.
TEXT .HTML TEXT * text/html
TEXT .TEXT TEXT * text/plain
TEXT .TXT TEXT * text/plain
Rich Text Format (RTF)
TEXT .RTF RTFf MSWD text/richtextApplications
APPL .EXE APPL * text/htmlAppleScripts - SCRIPT
SCRIPT .SCRIPT TEXT * text/html
SCRIPT * TEXT ToyS text/html
Binary Hex - HQX
TEXT .HQX TEXT BNHQ application/mac-binhex40Stuffit - SIT
BINARY .SIT SITD * application/x-stuffitZip Compressed
BINARY .ZIP pZIP * application/zipSUN UNIX Audio - AU
BINARY .au ULAW * audio/basicAIFF
BINARY .AIFF * * audio/x-aiffGraphics
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
Quicktime
BINARY .MOV MooV * video/quicktime
BINARY .MOOV MooV * video/quicktime
MPEG Video
BINARY .MPG MPEG * video/mpegMicrosoft Word
BINARY .WORD WDBN MSWD application/mswordMicrosoft 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 and APPL 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 "MacHTTP" or "AppleEvent Info" folders 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.
ALLOW <IP address>: Specifies the partial or complete IP address of a host (or hosts) that is allowed to access the server.
DENY <IP address>: Specifies the partial or complete IP address of a host (or hosts) that is denied access to the server.
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.
Examples:
ALLOW 129.106. DENY 129.106.3 ALLOW 129.106.30.1.
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 removes all clients with IP addresses that begin with "129.106.3" from the list of hosts that may 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 final ALLOW statement explicitly enables the host "129.106.30.1". 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 "."
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. Make sure that they are running on different PORTs (see the following section). One server can have no access restrictions while another restricts access to specified hosts.
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
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.
MAXUSERS <number>: Specify the maximum number of simultaneous users allowed to connect to MacHTTP. Values between 3 and 1000 are allowed. The default is 8 if this statement is omitted from the config file.
MAXLISTENS <number>: Defines the number of simultaneous listens for incoming client connections. Values between 3 and 50 are allowed. The default is 5.
TIMEOUT <seconds>: Specifies the maximum amount of idle time in seconds before MacHTTP disconnects a client's inactive connection. 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.
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.
HIDEWINDOW: If this command is present in the config file, MacHTTP's status window will be hidden when the application is running in the background.
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)
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 reource) for more details.
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: Works the same as the HIDEWINDOW command in the config file, described above.
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.
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.
This means that the "root" of MacHTTP's file system starts with the folder it resides in. Clients requesting documents from MacHTTP specify URLs as if MacHTTP was at the root of the file system.
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.
MacHTTP works well with HTTP/1.0 clients as well as older HTTP 0.9 clients. It supports query URLs and special character translation in URLs, but not returning data over alternate ports. It also supports returning binary data, and HTTP/1.0 headers, so it can be used with clients that support graphics, digital video, and any other data type that can be specified by a standard MIME type.
More information on URLs can be obtained from
http://www.ncsa.uiuc.edu/demoweb/url-primer.html.
Information on writing HTML documents for WWW can be obtained from
http://www.ncsa.uiuc.edu/demoweb/html-primer.html.
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
http://your.machttp.host/BigBucks.xcl
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.
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. Two 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.
http_request contains the complete HTTP request received from the WWW client.
http_search_args contains any search arguments passed by the WWW client to
MacHTTP as part of the request. This variable is useful for implementing clickable maps
and searchable documents. See the example script files in the MacHTTP distribution for
more details on how these variables are used.
http_search_args is a variable that is predefined by MacHTTP, prior
to script execution, that contains the search arguments passed by the WWW client.
< ISINDEX> is a HTML tag that indicates the following document is
searchable. Be careful not to confuse "ISINDEX" with the INDEX file specification
described above.
2. MacHTTP prefixes every source file with global variable definitions prior to passing it to AppleScript. A variable called "http_request" contains a string that is the actual argument passed to MacHTTP by the WWW client. This may be useful if you have a client that sends HTML1 requests and you want to do something with the extra arguments in AppleScript.
Another variable, "http_search_args", contains the search arguments, if any, that were passed as part of the client's request. This info is also contained in the http_request variable, but is extracted and provided for easier access here.
See the sample.script and search.script files for examples.
3. You must perform all HTML formatting inside the AppleScript file. MacHTTP only strips off the spurious quotes and converts special characters prior to sending script execution results to the client. Again, see the sample.script file for examples.
4. If MacHTTP is low on memory, scripts that use scripting extensions (OSAX's) will cause the program to hang. Make sure MacHTTP has enough memory (512K for script execution, 384K otherwise).
5. You may place alias files in your MacHTTP directory tree that point to script files. If the alias name ends with a suffix that is defined to be of type "SCRIPT", then the alias will be resolved and the file will be executed.
AppleEvents Received by MacHTTP
MacHTTP is now 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
Search: The "search" AppleEvent that is part of the MacHTTP suite is sent to applications when they are specified in a URL being requested by a WWW client. MacHTTP will launch the application, and then send this event. Here are the specifics on the search event:
on <<event WWW*srch>> search_args --remember, "*" is the omega char!
will be launched automatically, and the handler will be invoked with search_args appropriately defined. Note that "<<" and ">>" are the single characters obtained by typing option-\ and option-|, respectively.
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 10 entries defines a SCRIPT 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.
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).
Connections:
Memory:
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.
http://www.uth.tmc.edu/mac_info/machttp_info.html, the comp.infosystems.www
Usenet news group, and time permitting, from the author.The documentation covers just about everything there is to know about MacHTTP. So, 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.
Additional information about MacHTTP is available from
http://www.uth.tmc.edu/mac_info/machttp_info.html. 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
http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html.
Information on URLs can be obtained from
http://www.ncsa.uiuc.edu/demoweb/url-primer.html.
Added support for a config file (MacHTTP.config) that specifies suffix mappings to TEXT, BINARY, or SCRIPT types.
Fixed bug where CERN's Mac WWW client caused MacHTTP to crash.
Improved text file transmission performance.
Added support for default home pages (Default.html) and error messages (Error.html).
Added Options menu to enable/disable versbose debugging mode.
Added version info to About box.
Adjusted idle proc used for synchronous MacTCP calls to only yield background time to other apps every 5 ticks, rather than every time called. Increases performance for small file requests.
Modified processing of HTTP "GET" command to parse the file name correctly. It should allow the server to work with HTTP2 clients that send data after the file name. The parsing routine does NOT currently handle translating special character escapes.
Increased memory partition to handle more connections.