Virtual Hosts
Apache provides the capability to support multiple servers on a single machine, each differentiated by a unique host name. This feature is called virtual hosting. For example, it is often desirable for companies sharing a Web server to have their own domains, with Web servers accessible as " www.company1.com " and " www.company2.com ", without requiring the user to know any extra path information.
Virtual Hosts Table
The iTools Administration Server includes a table of virtual host names. This table initially will include a single virtual host, which is the fully qualified domain name of the system on which iTools is running. In "See Virtual Hosts Table", that name is " barney.tenon.com ". It also lists the virtual hosts " betty.tenon.com ", " fred.tenon.com ", and " holly.tenon.com ".
Adding Virtual Hosts
Additional virtual host names can be entered directly into the Virtual Hosts Table . Simply type the new virtual host name into the empty text edit field. The Domain Name Server is consulted to determine if the host name is an IP-based virtual host or a header-based virtual host. In either case, simply enter the host name, and the proper virtual host type will be created. Click on the Add Virtual Host button (or hit the <Return> key) to submit your new virtual host entry.
If you are using a host name, the new host name must be properly configured with your Domain Name Server before iTools will accept it. If necessary, an IP address can be used in place of a host name. Actual host names can be entered into the table after they have been configured in DNS. Using a host name is preferable to using an IP address, as users will remember a name more readily than a number.
Each virtual host has its own Virtual Host Configuration . These settings are accessible via the Virtual Host Config button. See section See Virtual Host Configuration for more information.
Deleting Virtual Hosts
To delete virtual hosts from the See Virtual Hosts Table , click on the Virtual Host Config button beside the virtual host you wish to delete. Select the Delete Virtual Host check box at the bottom of the Virtual Host Configuration table. Click on the Save Virtual Host Config button to submit the changes. The browser will return to the iTools Administration Server home page and the Virtual Hosts Table should no longer contain the deleted host name.
The default virtual host (the one with the same virtual host name as the fully qualified domain name of the machine running the Web server) does not have the Delete Virtual Host check box because it cannot be deleted.
Virtual Host Configuration
When a virtual host is added to the iTools configuration, the iTools Administration Server sets up an initial See Virtual Host Configuration for the new virtual host. These settings apply to incoming requests that explicitly use this virtual host's name. Each virtual host supported by the Web server corresponds to a unique directory that contains a unique set of Web pages. Client requests using the virtual host name are mapped to the corresponding directory. This prevents the client from unintentionally accessing other virtual hosts' Web pages. The client is unaware that its request is actually supported by a virtual host entry on a Web server with several virtual hosts. To access the Virtual Host Configuration table, click on the Virtual Host Config button beside the name of the virtual host you wish to configure.
For each directory or file within a virtual host's content, iTools permits unique See Domain Name-Based Restrictions , See Realm-Based Requirements , See MIME Type Overrides , and See Action Handler Overrides settings. These settings are accessible via the directory Contents button. See section See Folder Contents for more information on finding individual files or directories, and section See Access Controls for more information on setting access controls and other overrides for any file or directory served by iTools.
To change the virtual host settings, modify an existing setting or group of settings and click on the Save Virtual Host Config button. If you have not yet saved your changes, you can 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 virtual host's settings; it simply undoes any typing you may have incorrectly entered into this page.
The following entries in the Virtual Host Configuration table are also present in the Server Defaults table: ServerAdmin , ServerName , DirectoryIndex , ErrorLog , TransferLog , LogFormat and HostnameLookups . For more information on these items, please refer to the corresponding sections in section See Server Defaults.
The Aliases, Redirects and Error Files buttons are also present in the Server Defaults table. For more information on these items, please refer to the corresponding sections: See Error File Settings, See Alias Settings and See Redirect Settings.
VirtualHost
The VirtualHost entry displays the name of the virtual host to which the following settings apply. It is the same name that was entered in the iTools Administration Server home page in the See Virtual Hosts Table .
SSLSecurity
iTools optionally permits the configuration of secure connections on a per IP virtual host basis via the SSLSecurity directive. (For more information on SSL, refer to section See Adding SSL.) The SSLSecurity setting defaults to " Off" . To enable SSL for this virtual host, set SSLSecurity to "On". Before SSLSecurity can be enabled, it is necessary to generate a Server Certificate (see section See Server Certificate) using the SSL Settings page (see section See SSL Settings).
If iTools' SSL option is not installed, the SSL Security "On" and "Off" buttons will not be displayed. The message "Not Installed" will be displayed instead.
DocumentRoot
DocumentRoot controls which directory will be used as the base, or top level directory, for this virtual host's content. When a new virtual host is added (see section See Adding Virtual Hosts), a directory with the same name as the virtual host is automatically created within the WebSites directory. The DocumentRoot entry is set to the name of this directory. For example, if your Virtual Hosts Table includes two virtual hosts, " north.test.tenon.com " and " south.test.tenon.com ", your WebSites directory will contain two sub-directories with corresponding names. Place the content files to be published for this virtual host in this directory. If DocumentRoot is not set, the default DocumentRoot setting will be used. In this case, the DocumentRoot entry will be flagged with the Inherited indicator. See section See Inheritance for more information.
If you change the name of the virtual host's directory or decide to use some other directory, make the corresponding change to the Document Root setting for this virtual host.
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.
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.
ServerName
The ServerName setting corresponds to the host name of this server. It is only used in redirection URLs. If the ServerName setting is not set, a reverse DNS lookup of the server's IP address is used. Note that this reverse DNS lookup may not return the desired host name if, for example, the host's primary name is " fred.tenon.com " and the desired ServerName is " www.tenon.com ".
In the case of a virtual host, the ServerName is set to the same name as the virtual host. Typically, this setting does not need to be changed. It is only used in redirection URLs.
ServerAlias
The ServerAlias denotes which alternate host names should also apply to this virtual host. It is used with host header-based virtual hosts.
The Server Defaults do not include a setting for ServerAlias , so if the ServerAlias is not set, no alternate host names will apply to this virtual host.
ServerPath
The ServerPath is set initially to a path beginning with a slash ("/") followed by the virtual host name (e.g., /fred.tenon.com ). If this virtual host's home page was previously accessible via a non-virtual host URL, the old, or legacy URL, is entered here. Otherwise, this path should be blank.
When the Web server receives a request from a browser incapable of supporting host header-based virtual hosts, or from a browser requesting the now outdated legacy URL, this Web server will translate those requests to the proper See DocumentRoot via the ServerPath .
For example, if the new virtual host name is " company_A.com " and this data was previously located at " http://www.tenon.com/company_A/ ", the ServerPath should be set to " /company_A ".
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" .
See See Disabling Directory Indexing for information on turning indexes off for a specific directory.
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 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.
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. A complete mapping of the "%" directives is available in Appendix F. 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.
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 See ErrorLog and See TransferLog , but these addresses can subsequently be resolved into host names, if necessary.
If the HostnameLookups option is not specifically set, it will be inherited from the See Server Defaults and flagged accordingly.
SSLCertificateFile
The SSLCertificateFile is the name of the server certificate for an IP-based virtual server. Host header-based virtual hosts sharing a common IP address must share the same server certificate; however, multiple IP based hosts may also share a single "wildcard" certificate. This setting allows certificate "wildcarding" among several IP hosts.
Server certificates are stored in the /Local/Library/Webserver/tenon/ssl/certs directory.
SSLCertificateKeyFile
The SSLCertificateKey file is the private key associated with the server certificate. Keys generated by iTools during certificate signing request generation are normally stored in a secure area of the iTools internal file system; however, this field may be used for private keys of "wildcard" certificates or when a certificate and key are imported from another system.
Server certificates are stored in the /etc/ssl/private directory.
Virtual FTP Folder
The Virtual FTP folder is the path to the folder to be used for anonymous FTP access to this virtual host. If this field is not set, the top level or default FTP folder will be used. The Virtual FTP folder must be created before entering it in this text field. Refer to section See Virtual Anonymous FTP Service for further instructions on enabling virtual FTP service.
Folder Contents
The Virtual Hosts Table on the iTools Administration Server home page contains a button for Folder Contents .
The Folder Contents table contains an entry for each file and sub-directory of a given directory. The given directory may be the See DocumentRoot for a virtual host, or it may be a sub-directory of the DocumentRoot . To display the Folder Contents table for the DocumentRoot of a virtual host, click on the Folder Contents button for that virtual host in the See Virtual Hosts Table . To display the Folder Contents table for a specific sub-directory, simply click on that sub-directory's link in the Folder Contents table.
Folder Contents Table
When the Folder Contents table is displaying the contents of a directory other than the DocumentRoot directory, it displays a Parent Directory link as the first entry in the Directories column of the table. Clicking on the Parent Directory link will display a Folder Contents table for the directory in which the current directory resides.
Sub-directory Contents
Thus, the Folder Contents table provides a means for finding any file or sub-directory within a virtual host's hierarchy. To set any See Domain Name-Based Restrictions , See Realm-Based Requirements , See MIME Type Overrides , or See Action Handler Overrides for a specific directory, find that directory by using the Folder Contents table, then click on the See Access Controls button for that directory. To access settings for a specific file, find that file by using the Folder Contents table, and then click on that file's name.
Files
This column displays an alphabetical list of all files contained within the specified directory. To access any settings specific to a particular file, click on that file's name to display the See Access Controls for that file.
Folders
This column displays an alphabetical list of all sub-directories contained within the specified directory. To make any settings specific to a particular sub-directory, click on that directory's name to display a directory Contents table for that directory, and then click on the See Access Controls button for that directory.
Access Controls
The Access Controls settings can be set for any file or directory within a virtual host's hierarchy. The name of the file or directory to which these settings apply appears at the top of the table. This is a valid URL to this specific file or directory, complete with the proper virtual host name. Clicking on this URL will request this file or directory from the Web server in the exact same manner as any client browser. Thus, this link provides not only an explicit reference to the file or directory to which these controls apply, but also provides an easy way to test these settings and how the file or directory will be presented to normal incoming requests.
Domain Name-Based Restrictions
Domain Name-Based Restrictions specify which client IP addresses are permitted access to this URL, and which are denied. The Web server processes the Allow and Deny lists in the specified order to determine if a client request will be permitted.
Domain Name-Based Restrictions
The Allow and Deny lists can contain fully qualified domain names or IP addresses. They can also contain partially qualified domain names or ranges of IP addresses. If a fully qualified domain name or IP address is used, that specific host is allowed or denied access, as appropriate. If a partially qualified domain name is used, any host whose fully qualified domain name ends with the partially qualified name is allowed or denied, as appropriate.
If partially qualified domain names are used, any comparison will match whole components of domain names. For example, denying "non.com" denies "host1.non.com", but not "anyone.tenon.com".
HostnameLookups must be enabled for this virtual host, in order for domain names to be properly interpreted in the Allow and Deny lists. See section See HostnameLookups for more information.
A range of IP addresses may also be specified for a specific subnet by appending a slash ("/") and the number of bits in the subnet mask. For example, specifying " 192.30.20.128/25 " would mean all IP addresses from " 192.30.20.128 " to " 192.30.20.255 ", inclusive.
Remember, if Access Controls for sub-directories are not explicitly set, the sub-directory will inherit the Access Controls from its parent directory. If the Evaluation Order for a given file or directory is set to No Restrictions, but a parent directory does have explicit restrictions, the parent's restrictions also apply to this file or directory. In this case, the Access Controls table will show the inherited Access Controls as specified by the parent directory, and the Inherited indicator and the Evaluation Order setting will be displayed.
Realm-Based Requirements
Realm-based access controls determine who is permitted access to this URL, by means of a user name and a password. If the client fails to provide a correct user name and password, access is denied.
Realm-Based Requirements
The list of privileged users can be any one of the settings defined below:
|
Any user from the entire list of users is permitted access with the proper password for that user. |
|
|
Any highlighted user in the Users list is permitted access. For information on how to select a set of users, see section See Users in Group. |
|
|
Any user who is a member of any highlighted group in the Groups list is permitted access. |
If none of the Any Valid User , Selected Users or Users in Group settings are checked, no Realm-Based Access Controls explicitly apply to this file or directory. However, if a parent directory does have explicit Realm-Based restrictions, the parent's restrictions also apply to this file or directory. In this case, the Realm-Based Requirements table will show the inheritance as specified by the parent directory, and the Inherited flag will be displayed, along with the required setting.
If any of the Any Valid User , Selected Users , or Users in Group settings are checked, a Re alm Name must be entered. This name can be any word or compound word without spaces, such as " iToolsAdmin ". The Realm Name is passed to the browser and displayed to the client as a means of identifying which collection of users is permitted to access this file or directory. Many browsers cache this Realm Name and the entered user name and password to relieve the user from re-entering this information when another URL with the same Realm Name is requested.
MIME Type Overrides
MIME Type Overrides allow an explicit file, or directory of files, to be served without regard for the file name extensions. For example, if a directory contained only GIF files, but some (or all) of these files did not end with the " .gif " extension, the MIME Type Overrides could be set to " image/gif " to force all of these files to be treated as GIF files, without requiring any renaming of the files.
If the MIME Type Overrides setting is not given for a specific file or directory, but a parent directory does have an explicit setting, the parent's setting also applies to this file or directory. In this case, the table will show the inheritance (see section See Inheritance) as specified by the parent directory, and the Inherited indicator will be displayed along with the MIME Type Overrides setting. See section See MIME Extensions for more information.
Action Handler Overrides
Action Handler Overrides allow a specific file, or directory of files, to be passed to the overriding action handlers, without regard for the file name extensions or associated MIME types. See section See Action Handlers for more information. For example, if a directory contained only image map files, and some (or all) of these files did not end with the " .map " extension, the Action Handler Overrides could be set to " imap-file " to force all of these files to be passed to the image map handler, without requiring any renaming of the files.
If the Action Handler Overrides setting is not given for a specific file or directory, but a parent directory does have an explicit setting, the parent's setting also applies to this file or directory. In this case, the table will show the inherited overrides as specified by the parent directory, and the Inherited indicator and the Action Handler Overrides setting will be displayed.
