System-wide Configuration
The System-Wide Configuration table is the starting point for administering iTools. It contains buttons for each of the major areas of iTools administration. Clicking on a button will present a table with forms for that specific area. Each of the areas and their tables and forms are discussed below.
Server Defaults
There are two key tables in iTools that control important configuration information for both the default server and any virtual hosts being served -- the Server Defaults table and the Virtual Host Configuration table. Certain items in the Virtual Host Configuration table may be inherited from the initial entries in the Server Defaults table.
The Server Defaults settings apply to incoming requests for any virtual host name if the corresponding setting is inherited (i.e., not explicitly set in that Virtual Host Configuration table). See section See Virtual Host Configuration.
The Aliases, Redirects and Error Files buttons at the top of the Server Defaults table are discussed in sections See Error File Settings, See Alias Settings and See Redirect Settings.
To change the Server Defaults , modify an existing option or group of options, and click on the Save Server Defaults button. If you have not yet saved your changes, use the Reset button to restore the information in your browser's page to what it was when the page was first accessed. Note that the Reset button does not make any changes to the server's settings; it simply undoes any typing you may have incorrectly entered into this page.
ServerAdmin
The ServerAdmin setting is an email address. This address is included in messages sent to a browser whenever a Web server error occurs. Users are encouraged to, and typically do, use this address to notify Webmasters of any problems they are experiencing with a Web server. The established convention is to use the email address " webmaster@your_domain.com ", but any valid email address is acceptable. The email address must be an existing email address on some e-mail server.
In the case of a virtual host, ServerAdmin is initially set to the email address " webmaster@virtualhost ", where " virtualhost " is replaced by the virtual host name. Alter this setting to reflect the email address of the Webmaster for this virtual host, or the Webmaster for this iTools system. Many Web sites follow the convention of using an email address " webmaster@virtualhost ". To preserve this convention for your iTools server, add this address to your email server, or make this address an alias to another existing email account on your email server.
If ServerAdmin is not set for a particular virtual host, the See ServerAdmin setting is inherited from the Server Defaults . In this case, the ServerAdmin entry in the Virtual Host Configuration table will be flagged with the Inherited indicator.
DirectoryIndex
The DirectoryIndex setting controls which file is returned when serving a request for a URL that points to a directory (i.e., ending with a "/"). When such a request is made, the DirectoryIndex is substituted for the URL, pointing the client request to a default file or CGI. If the DirectoryIndex is null, the contents of the directory will be listed on the returned page.
The iTools default DirectoryIndex is " default.html index.html" . This list is searched in order from left to right for a file with the corresponding name. Other Macintosh servers use "default.html" , while the typical Apache setting is "index.html" . The iTools default is chosen to accommodate the Mac OS webmaster in transition to Mac OS X Server.
ErrorLog
The ErrorLog entry in both the Server Defaults table and the Virtual Host Configuration table is the name of the file iTools uses to log information about Web server errors. If an ErrorLog file is not specifically set for a virtual host, the ErrorLog file setting in the Server Defaults table will be used.
TransferLog
The TransferLog setting is the name of the file iTools uses to log information about incoming requests. If TransferLog is not set for a particular virtual host, it will be inherited from the Server Defaults , and flagged accordingly. The transfer log is stored in the iTools.log file in the top level Logs directory.
For more information on the TransferLog see See Logs .
LogFormat
The LogFormat setting is a string that controls the format of the log file. The log file can include literal characters copied from the log format setting and detailed information specific to the actual request that is being logged. Details are encoded using a percent sign ("%") followed by a letter. For example:
Each "%" followed by a letter is a directive to the Web server for a specific piece of information about the request being logged. For example, "%h" logs the name of the remote host placing the request. The order and set of literal characters and details included in the transfer log explicitly follow the order and set of literals and "%" letters in the LogFormat setting.
ApacheSSL provides a " c " symbol for custom logging, thus iTools can be configured with custom SSL log entries using the " c " symbol. For example, a LogFormat string to include the SSL version used in an access and the encryption algorithm or cipher used in an access should use:
If the TransferLog is not customized for a particular virtual host, the LogFormat setting will be inherited from the Server Defaults . This results from the TransferLog itself being inherited and utilizing the Server Defaults' LogFormat .
The cache will keep the log if the accelerator cache is "On". (This is the default.) As such, the LogFormat option entered into the Administration Server is not passed to the cache, and the LogFormat has no effect.
For more information on logging in iTools, see chapter See Logs.
ScriptLog
The ScriptLog setting is the name of the file used to log information about errors in CGI scripts. This feature is meant to be used as an aid in debugging CGI scripts, and should not be used continuously on an active server. It is therefore not entered on default, but can be activated by specifying a file in the given form field.
HostnameLookups
The HostnameLookups setting controls whether reverse DNS lookups are performed for each incoming request using the originator's IP address. Enabling HostnameLookups will generally increase the time necessary to satisfy each request, and thus increase the load on your server. However, without HostnameLookups , See Access Controls can be based only on IP addresses, not on host names or domain names. If HostnameLookups is disabled, IP addresses will be used in the apache access logs, but these addresses can subsequently be resolved into host names, if necessary.
Proxy Settings
The Proxy Settings table contains some options that control the proxy capabilities of Apache. For more information on Apache and proxy service, see the on-line Apache documentation.
ProxyRequests
The ProxyRequests setting controls whether the proxy service is "On" or "Off". This setting is "Off" by default. If ProxyRequests is set to "On", the Squid Accelerator Cache should be turned off.
CacheSize
The CacheSize setting controls the disk space, in Kbytes, that the proxy cache files may consume. The proxy service may periodically use disk space beyond this setting, but the proxy "garbage collection" scheme will recover this space after the fact.
CacheGcInterval
The CacheGcInterval setting controls the time, in hours, that the proxy "garbage collection" scheme waits between checks to see if the proxy cache size has exceeded its CacheSize setting. If it has, files are deleted from the proxy cache until its disk space consumption is less than the CacheSize setting.
CacheMaxExpire
The CacheMaxExpire setting controls the time, in hours, that a file in the proxy cache may be retained without checking with its origin server. This setting enforces a maximum time that a file may be out of date, even if an expiry date was supplied with the original file.
CacheLastModifiedFactor
If the origin HTTP server did not supply an expiry date for the document, estimate one using the following formula:
expiry-period = time-since-last-modification * <factor>
For example, if the document was last modified 10 hours ago, and "< factor >" is 0.1, then the expiry period will be set to 10*0.1 = 1 hour.
If the expiry period would be longer than that set by CacheMaxExpire , the latter takes precedence.
CacheDefaultExpire
If the document is retrieved via a protocol that does not support expiry times, use "< time >" hours as the expiry time. CacheMaxExpire does not override this setting.
NoCache
The NoCache directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP and anonymous FTP documents matching any words, hosts or domains are not cached by the proxy server. During startup, the proxy module will also attempt to determine IP addresses of any list items which may be host names. These IP addresses will also be cached for use in the match list. In the following example:
NoCache some_host.co.uk widgets.doodads.com
" widgets.doodads.com " would also be matched if referenced by IP address. Note that " doodads " would also be sufficient to match " doodads.com ". Note also that " NoCache * " disables caching completely.
Remote Proxies
Remote proxy servers are other proxy servers that this proxy server may interact with to satisfy a proxy request.
ProxyRemote
The ProxyRemote setting specifies which remote proxy servers are accessible to this proxy server. Each line in the ProxyRemote text edit field defines a " <match> " string and a " <remote-server> " to service URLs that match that string. The match string and the remote server are separated by a space.
The " <match> " string is either the name of a URL scheme that the remote server supports, a partial URL for which that remote server should be used, or an asterisk (" * ") to indicate that server should be contacted for all requests.
The " <remote-server> " field is the URL for the remote proxy server. Its syntax is " http://<hostname>[:port] ". Here are some example entries in the Remote Proxies table:
http://goodguys.com/ http://mirrorguys.com:8000
ftp http://ftpproxy.mydomain.com:8080
In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which will then handle them as FTP requests.
ProxyPass
The ProxyPass setting allows remote servers to be mapped into the space of the local server. The local server does not act as a proxy in the conventional sense, but appears to be a mirror of the remote server.
Each line in the ProxyPass text edit field defines a "< local url >" and a "< remote server >". These fields are separated by a space character.
The "< local url >" is the name of a local virtual path. The "< remote server >" is the URL for the remote server. Suppose the local server has address " http://wibble.org ". Typing the following:
will cause a local request for:
http://wibble.org/mirror/foo/bar
Proxy Access
The Proxy Access settings control two things. The Domain Name Restrictions control which hosts may use this iTools server as a proxy server. The ProxyBlock acts as a censor list by restricting access to certain URLs, such as pornographic material.
Domain Name Restrictions
The Domain Name Restrictions control which hosts may use this iTools server as a proxy server. These restrictions are applied the same way as iTools domain name restrictions are applied to any file or directory. See section See Domain Name-Based Restrictions for more information.
ProxyBlock
The ProxyBlock directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP, HTTPS and FTP document requests to matched words, hosts or domains are blocked by the proxy server. The proxy module will also attempt to determine IP addresses of list items which may be host names during startup, and cache them for match test as well. For example, if the ProxyBlock table contained:
Access to any URL containing the words " nudes " or " games " and to " some_host.com " would be restricted. " some_host.com " would also be matched if referenced by IP address. Note that referencing " some_host " would also be sufficient to match " some_host.com ". Note also that the wild card " * " blocks connections to all sites.
Server Controls
The Server Controls table provides some useful information about the current state and version numbers of the Web and cache servers. The buttons on the Server Controls page provide a means for the iTools administrator to examine and control certain aspects of the iTools server.
The Server Controls page first checks on the current state of the Web server. If the server is active, its version number is displayed in the top row of the table; otherwise the word "unavailable" appears. Similarly, if the accelerator cache is active, its version number is displayed in the next row. If the cache has been explicitly turned off in the Cache Settings , that row is not displayed in the table.
Start/Stop Server
If the Web server is active, the Stop Server button is provided in the row of buttons above the Server Controls table. Clicking on this button will stop the Web server.
If the Web server is not active, the Start Server button is provided in the row of buttons above the Server Controls table. Clicking on this button will start the Web server.
Server Status
The Server Status button provides a connection to Apache's internal status information. This information includes details about the server's version, the current memory available in the system, the time the server was started, CPU usage, and current connections states.
Cache Status
The Cache Status button provides a connection to Squid's internal status information. Squid's information is divided into a pull-down list of categories pertaining to all aspects of Squid's operation.
Server Info
The Server Info button provides a connection to Apache's current configuration information. This information includes details about which modules are included in this instance of Apache and what its current configuration settings are for each module.
Restart Server
The Restart Server button is shown only if the Web server is currently active. Clicking on this button will cause the Web server to completely restart its operation, without shutting down and restarting iTools. Restarting the server reloads the Apache and Squid configuration files, as well as any plug-ins in the Plug-Ins directory. If changes are made directly to these files without using the iTools Administration Server, or if plug-ins are added to the Plug-Ins directory, it is necessary to restart the server in order for these changes to take effect.
Flush Cache
The Flush Cache button is shown only if the Web server is currently active and the cache is configured to be "On". Clicking on this button will cause the Web server to completely restart its operation, including a flush of the contents of the accelerator cache.
Messages
During startup, the Web server creates a log file which records the loading of apache. It also records informational Web system messages.
Clicking on the Messages button will display the contents of the iTools.status file in the WebServer/tenon/logs directory.
Startup Log
During normal startup, iTools maintains a log file of the startup activities. Under normal circumstances there is little need to examine this file; however, in the event of startup problems, some useful information may be found here.
Clicking on the Startup Log button will display the contents of the Startup Log file.
System Errors
This log file is a cumulative record of Web server system errors. Under normal circumstances, there is little need to examine this file; however, errors that may cause the Web server to misbehave or stop serving Web content are recorded here. Clicking on the System Errors button will display the contents of the iTools.syserrs file in the tenon/logs directory.
Config Log
iTools's preferences are checked each time iTools is started. If there have been any changes to the preference settings since the last time iTools was started, iTools does some additional startup actions which pass those changes on to the iTools configuration files. These additional startup actions are recorded in the iTools.config file in the WebServer/tenon/logs directory.
Under normal circumstances there is little need to examine this file; however, some useful information concerning startup and configuration problems may be found here.
iTools Version Number
iTools's version number is recorded in the iTools.updates file in the /WebServer/tenon/logs directory. This file records the initial version of iTools that was installed, as well as any updates that are applied.
The iTools Messages, Startup Log, System Errors, Config Log and version number files are available via the following password-protected URLs:
http://host.domain/iTools_msgs/iTools.status
http://host.domain/iTools_msgs/iTools.startup
http://host.domain/iTools_msgs/iTools.config
Action Handlers
Action Handlers are an entity internal to Apache. They are used to map files with certain MIME extensions, or files with certain suffixes, to specific actions.
Action Handlers Table
These actions may be internal to Apache, or they may be external actions (i.e., CGIs). Before a MIME type or a suffix can be mapped to an action, a handler for that action must be defined. iTools includes several internal handlers for specific actions. These handlers are displayed in the lower portion of the table and cannot be changed. User-defined handlers can be created for any of the existing MIME types. Use the pull-down list of MIME types or type in a user-defined name. Enter the path to the external action (CGI), and click on the Save Handlers button to submit your changes. The external actions (CGIs) associated with user-defined handlers must be explicitly added to iTools.
MIME Extensions
There are two MIME Extensions tables -- the User-Defined MIME Extensions table and the Built-In MIME Extensions table. Both MIME Extensions tables map a file name, by its extension, to a MIME type. The extension or MIME type is then mapped to one of the action handlers to control what actions should be taken when any file with this extension is requested. Action handlers can be defined for both MIME types and extensions. If a handler is defined for a specific extension, it overrides any handler specified for that extension's MIME type.
To map a new extension to a MIME type or action handler, enter the new extension into the empty text edit field in the top line of the User-Defined MIME Extensions table. Then enter the corresponding MIME type or select a handler from the pull-down list, or do both. Click Save MIME Extensions to submit the changes.
MIME Extensions Table
To change an existing extension, its MIME type, or its handler, modify the extension or MIME type in the text edit field or select a different handler from the pull-down list. Then click on Save MIME Extensions to submit the changes.
iTools includes a long list of well-known extensions and their corresponding MIME types. These extensions are displayed in the Built-In MIME Extensions table, accessible via the Built-In Extensions button, and cannot be explicitly changed. However, these default extensions can be overridden by entering the extension in the empty text edit field in the User-Defined MIME Extensions table, and assigning it a different MIME type. This extension will then appear in that table, and the default setting will no longer appear in the Built-In MIME Extensions table. If this extension is subsequently removed, the default setting will remain and will reappear in the Built-In MIME Extensions table. Overriding the default extensions in the Built-In MIME Extensions table is not recommended, as this setting affects all files with this extension on this server. To explicitly override the default MIME type settings for a specific file or directory, see section See MIME Type Overrides.
MIME Languages
The MIME Languages table provides a means for mapping a file name, by its extension, to a language. The Web server takes no special action based on the language, but the given language is passed back to the client (in the HTTP header) for any specific interpretation in the browser.
To map a new file name extension to a language, enter the extension in the empty text edit field in the first row of the table, and select a language from the pull-down list. Then click Save MIME Languages to submit the new setting.
To change an existing setting, either modify the extension in the text edit field or select a new language from the pull-down list. Then click Save MIME Languages to submit the changes.
MIME Encodings
The MIME Encodings table provides a means for mapping a file name, by its extension, to a MIME encoding. The Web server takes no special action based on the encoding, but the given encoding is passed back to the client (in the HTTP header) for any specific interpretation in the browser.
To map a new file name extension to an encoding, enter the extension in the empty text edit field in the first row of the table, and enter an encoding in the second text edit field. Then click Save MIME Encodings to submit the new setting.
To change an existing setting, modify the extension or the encoding its respective text edit field. Then click Save MIME Encodings to submit the changes.
Users
A Mac OS X Server user has a number of capabilities that include: 1) logging onto the system through a console login sequence (or over the network via telnet or rlogin) with full program execution capabilities, 2) logging onto the system via FTP (File Transfer Protocol) to exchange file data, and 3) partial login from which electronic mail can be sent or received with a known set of user criteria.
iTools users include several classes that offer subsets of these capabilities. iTools users may be created from either the Admin Server interface, or, if WEBmail is installed, via the WEBmail_adduser page. As you might expect, users create from each of these user classes have different limitations.
iTools provides a set of realm-based access controls that can restrict access to a particular file or directory based on user names and passwords. (See section See Realm-Based Requirements.) iTools also provides FTP service based on user names and passwords. User names and passwords for both realm-based access controls and FTP service are entered in the Users table.
To enter a new user name and password, type the user name into the empty text edit field in the first row of the table. Type a corresponding password into the second text edit field. The password will not be displayed as it is typed. Instead, bullet characters will be displayed (so type carefully). Click the Save Users button to submit the new user name and password.
Click on the FTP checkbox to enable FTP access for this user. If FTP access is enabled, select an FTP Home for this user. The FTP Home is the directory that this user will be given access to when they FTP into iTools. Using the pull-down menu, users can be restricted to access only a particular virtual host, only the anonymous FTP hierarchy, or they can be allowed access to all of the virtual hosts or all of the iTools directories, including the anonymous FTP hierarchy. Using the text edit field, a path to any valid directory can be entered for this user's FTP Home. If no FTP Home is selected, the default allows access to all of the virtual hosts. Of course, this is enabled only if the FTP checkbox is checked. The root directory of FTP Home is /Local/Library/WebServer. Adding users here creates an FTP only user in the Mac OS X Server (system) User database. Existing system users that are added to the iTools user databases are not changed to FTP only.
Once a user name and password have been entered, the new entry will show up in the table in alphabetical order. Passwords are always displayed as if they contain eight characters, regardless of how many characters are actually in the password. FTP Home directories are shown as paths.
Groups
iTools provides a set of realm-based access controls that can restrict access to a particular file or directory based on groups of users (each with their own password).
To enter a new group, type the group name into the empty text edit field in the first row of the table. Click the Save Groups button to submit the new group. Once a group has been entered, the new entry will show up in alphabetical order in the Groups table.
Groups Table
To change an existing group name, modify the name in the text edit field and click Save Groups to submit the change.
To select which users are to be members of a group, click on any button in the Group List column. The See Users in Group table will be displayed.
The iTools Administration Server uses a special group named iToolsAdmin . Members of this group are permitted access to the iTools administration pages, and may make changes to the iTools configuration, including adding and deleting users and groups. If the iToolsAdmin group is deleted, or if this group is empty, access to the iTools Administration Server is completely cut off. In this case, use the Admin menu item and follow the instructions in section See Changing the Administrator Password to add an initial user to this special iToolsAdmin group.
Users in Group
The Users in Group table controls which users are included in a specific group. To select users for inclusion in a group, click on each privileged user within the scrollable list of all users. Simply clicking on a user's name will select that individual user. Hold the <shift> key and click to select a series of users, or hold the <Apple> key (<control> key on non-Macs) to individually select any combination of users. When a user is selected for inclusion in the group, the user's name will be highlighted. Click on Save Users in Group to submit the selected users.
Import and Export
Import and Export provide a means to manage iTools's Users and Groups databases from a text file. The file contains one entry per line, listing a user's name, group, and password. Importing from such a file will read each line of the file, extract valid entries, and append them to the Users and Groups databases as appropriate. Conversely, exporting the Users and Groups databases creates a text file (suitable for editing and subsequent importing) containing a line for each entry in the current Users and Groups databases.
The Import Users and Export Users buttons are accessible from either the Users table or the Groups table. Clicking on these buttons presents a simple form for entering the name of the file to be imported from or exported to, and buttons to select either the Import or Export action.
Exporting
To export the current Users and Groups databases, type in a file name and click on the Export Users button. The exported file will be placed in the tenon directory and will overwrite any existing file of the same name. A table of exported entries is also displayed in your browser.`
Importing
To import a list of user names, groups and passwords, it is first necessary to create a file of the proper format. Typically, the easiest way to get started is to create a file by exporting the current Users and Groups databases. However, you can create an import file from scratch by following the format below.
Importing can either append the imported entries into the existing Users and Groups databases, or it can be an "exclusive" import. "Exclusive" imports completely replace the existing Users and Groups databases, and thus create only the entries found in the imported file.
Place the file to be imported in the /Local/Library/WebServer/tenon directory. If the import is to be an "exclusive" import, select the Exclusive Import checkbox. Type the name of the file into the Import/Export form and click on the Import Users button. A table reporting on the success of each imported entry is displayed in your browser. Imported entries are appended to the previously existing set of Users and Groups .
File Formats
Each line of the Import and Export files must be formatted as follows. Blank lines and lines beginning with a " # " (comment lines) are ignored.
username:groupname encrypted-password
username:groupname encrypted-password <ftp-home>
The user name field must begin in the first column of the file. Every user name in iTools must be unique. If a user is a member of more than one group, one line must exist (with the same user name and password) for each group to which the user belongs.
The ftp-home entry is optional. If it exists, FTP access is enabled for the user in the directory indicated by <ftp-home>. If the ftp-home entry is omitted, FTP access is disabled.
When iTools exports passwords, it writes out the passwords in the encrypted form. This is more secure than writing out passwords in unencrypted form, as anyone who reads or accesses the exported file will not have access to the user's passwords, and thus will not be able to access that user's realms. The encrypted passwords are, however, still acceptable for copying or modifying the user name and group entries before importing these changes back into the iTools system. Another advantage of providing encrypted passwords is that the user name and passwords can be plucked from an exported users list and entered (in the proper format) into a basic authentication password database file (.htpasswd). Also note that in a default iTools installation, access to the tenon directory is restricted. Therefore, exported files are not accessible to anyone browsing this server.
Cache Settings
Clicking the Cache button reveals a Cache Settings table. The Cache Settings table contains options that control the iTools memory cache. This cache is object-based and keeps the most recently accessed Web pages in memory, making these pages immediately accessible for subsequent requests.
After changing the Cache Settings , click on the Save Cache Settings button to preserve your changes.
AcceleratorCache
The AcceleratorCache setting controls whether the memory cache is "On" or "Off". The default setting is "On". Turning the cache to "Off" will save some memory, so this setting might be useful for servers that are running low on memory. Turning the cache to "Off" will also affect the performance of the server.
cache_mem
The cache_mem setting controls how much memory, in Mbytes, the cache will use. This setting represents the high-water mark for memory use. The cache will only consume as much memory as it needs, up to this value. The default setting is 4 Mbytes.
cache_swap
The cache_swap setting controls how much disk space, in Mbytes, the cache will use. This setting represents the high-water mark for disk usage. The cache will only consume as much disk space as it needs, up to this value. The default setting is 100 Mbytes.
swap_level1_dirs
The swap_level1_dirs setting controls how many level 1 (top level) directories the cache will use to organize its cached entries on the disk. The default setting is 2.
Advanced Settings
The Advanced Settings table contains some options that control the inner workings of the Web server. Your choice for these settings may be influenced by certain conditions, such as how much memory the iTools system has, the expected rate of "hits", the size of the average transfer, the number of simultaneous transfers, and the access bandwidth of the Web server or the clients.
StartServers
The StartServers setting controls how many Web server processes are created when the server is initially started. The number of Web server processes may be dynamically changed (depending on the server's load), so changing this setting has minimal effect once the server is up and has serviced its first few requests.
MaxClients
The MaxClients setting controls the number of requests that can be processed simultaneously. If the MaxClients are concurrently in progress, subsequent requests are not necessarily lost. Instead, they are queued until an existing request has completed.
MaxSpareServers
The MaxSpareServers setting controls the number of idle (i.e., not currently servicing any request) Web server processes. If the number of idle processes exceeds this number, the excess processes are terminated.
MinSpareServers
The MinSpareServers setting controls the number of idle (i.e., not currently servicing any request) Web server processes. If the number of idle processes is smaller than this number, extra Web server processes are instantiated at a rate of one per second.
MaxRequestsPerChild
The MaxRequestsPerChild setting controls the number of requests each Web server process will service. Web server processes service one request at a time. However, upon completing one request, they may begin servicing another.
Increasing the number of requests each Web server process services reduces the overhead of instantiating and terminating Web server processes. Restricting this number reduces the likelihood of accidental loss of system resources, as these resources are recovered when a process exits. Also, the dynamic control over the number of currently running processes responds to a reduction in load by allowing some Web server processes to exit without instantiating replacements. Therefore, in this case, a smaller number of MaxRequestsPerChild leads to a faster reduction in Web server processes.
If the MaxRequestsPerChild is set to zero, a Web server process will never expire.
Port
The Port setting controls on which port number the Web server accepts incoming connections. The Web server accepts incoming connections on all its IP addresses using the port number specified in the Port setting.
TimeOut
The TimeOut setting controls the maximum time (in seconds) that the Web server will wait for receipt of a complete incoming request once any initial part of an incoming request is received. The TimeOut setting also controls the maximum time the Web server will wait to completely send a response. If the sizes of the files used in the Web transfers are large, and the client's or server's network bandwidth is slow, the TimeOut setting must be increased to compensate.
KeepAlive
The KeepAlive setting controls whether or not the Web server permits multiple incoming requests (from a single client) in a single connection. Using KeepAlive reduces the overhead of connection establishment and termination for each incoming request.
MaxKeepAliveRequests
The MaxKeepAliveRequests setting controls the number of incoming requests a client may embed in a single connection. The MaxKeepAliveRequests setting is ignored if See KeepAlive is "Off".
KeepAliveTimeout
The KeepAliveTimeout setting controls the length of time (in seconds) the Web server will wait for additional incoming requests in a single connection. If the KeepAliveTimeout expires, a client can still send additional requests; however, a new connection establishment overhead is incurred. The KeepAliveTimeout setting is ignored if See KeepAlive is "Off".
Error File Settings
There is a button at the top of each page containing the Virtual Host Configuration table and the Server Defaults table that allows you access the Error Files settings. These settings specify the file to be returned to the client when a Web server error occurs. When such an error occurs, the originally requested page is not returned to the client; instead, the corresponding error file is returned.
To associate an error file to a specific error, select the error code from the pull-down list and type the path to the error file into the text field. Then click the Save Error Files button. To change an error code for an existing error file or to change the name of an error file, change the selection in the pull-down list or modify the error file name in an existing text edit field. Then click Save Error Files to submit the change.
Error Files Table
" 403: Access to the requested page is denied. "
" 404: The requested page does not exist. "
are usually mapped to files with simple messages explaining those errors. However, any of the error cases, from the most common to the most obscure, can be mapped to any URL (including a CGI) for advanced error logging and reporting.
Alias Settings
There is a button at the top of each of the Virtual Host Configuration and Server Defaults tables that allows you to access the Alias Settings for the corresponding virtual host or the default aliases for all virtual hosts.
Alias settings specify components of URLs that are "aliased" or mapped to different directories. When a request is received with a URL that contains one of the aliases, the data returned to the client comes from the specified directory or file.
Aliases may also specify a target directory that contains CGIs (or scripts) rather than normal data. In this case, the alias is referred to as a ScriptAlias and is represented in the Alias Settings table using a checkbox.
iTools's initial Server Default settings contain several Aliases used by the iTools Administration Server, the iTools documentation, and in the examples. These aliases all begin with the string " iTools_ ". The default cgi-bin is also specified in this table.
Alias Settings Table
To create a new alias, enter the component of the URL to be aliased into the URL Path field of the Alias Settings table and enter the path to the directory or file containing the aliased data in the Directory or File field. If the URL Path or the target represents a directory, it should begin and end with a "/". If it represents a file, it should not end with a "/". If the aliased directory contains CGI scripts, check the ScriptAlias checkbox. Click Save Aliases to save these settings.
The specified target may reside anywhere within the iTools hierarchy; it does not necessarily have to reside in the DocumentRoot directory for the virtual host servicing the request. The path to the target of the alias always begins in the iTools directory.
Redirect Settings
There is a button at the top of each of the Virtual Host Configuration and Server Defaults tables that allows you to access the Redirect Settings for the corresponding virtual host or the default redirects for all virtual hosts.
Redirect settings specify URLs that are "redirected" or mapped to different servers. When a request is received with a URL that contains one of the redirected entries, the client is instructed (via a return code) to access the data from a different server using the provided URL.
Redirect responses contain a reply code and may contain a URL. The reply code can be chosen from a pull-down list.
iTools does not initially contain any Redirect settings. The following picture shows an example Redirect Settings table with a single fictitious entry.
Redirect Settings Table
To create a redirect entry, select the redirect reply code from the pull-down list and enter the URL to be redirected into the URL Path field of the Redirect Settings table. If necessary, enter the new URL in the Destination URL field. Click Save Redirects to save these settings.
Some reply codes require a destination URL and some do not. If you select a reply code that requires a destination URL and do not provide one, an error will be reported. If you select a reply code that does not require a destination URL and one is provided, the destination URL will be discarded when the settings are saved.
Customizing iTools
The apache.conf, iTools.conf, and squid.conf files are the main configuration database files manipulated by the iTools Administration Server. Features available to Apache and Squid but not yet configurable in the Administration Server may be added to these files, creating a customized Web site configuration. Some common site customization examples are described below.
Creating Virtual Domain-Specific CGI-bin Folders
If a unique CGI-Executables folder is desired for each virtual host, a Finder duplicate copy of the CGI-Executables folder may be placed in the document root folder for each configured virtual host (see section See Virtual Host Configuration). A custom directive is then added to apache.conf:
Place the following directive in the relevant < VirtualHost > container:
ScriptAlias /cgi-bin/ /Local/Library/WebServer/WebSites/vhost.com/cgi-bin/
Adding Additional MIME Extension Mappings
This feature permits suffix mappings for Modules or CGIs beyond those registered by the Module at server start up. For example, to configure the WebCatalog Module to handle all .html files:
Overriding a Registered Suffix Mapping
This feature can be used to selectively disable an installed plug-in on a per-virtual host basis. Using WebCatalog as an example, we demonstrate how to prevent WebCatalog from serving .tmpl (the suffix automatically registered by WebCatalog) files accessed from VirtualHost 192.0.0.1.
Running CGIs Outside of CGI-bin
From the access controls page, set an action handler override to cgi-script for each directory where script execution is to be allowed.
Disabling Directory Indexing
Apache ignores Options directives inside "Virtual Host" containers. While Apache will syntactically accepts this, it doesn't use any of the settings.
The `Options -Indexes' directive used inside a <Directory></Directory> container tells Apache to disallow client-side browser indexing of the specified directory.
The approved method is to wrap any Options directives in a Directory
So, previous lines from the apache.conf file that may have been:
<VirtualHost 111.222.333.444:81>
ServerName MyVirtualHost.here.com
NameVirtualHost 111.222.333.444
DocumentRoot /Local/Library/WebServer/WebSites/MyVirtualHost.com
Options -Indexes FollowSymLinks IncludesNoExec
should be put into the< Directory></Directory> wrapper as in the example below:
<Directory /Local/Library/WebServer/WebSites/MyVirtualHost.com>
Options -Indexes FollowSymLinks IncludesNoExec
where the <Directory></Directory> wrapper is inside the <VirtualHost></VirtualHost> wrapper.