The main purpose of this document is to help users of other Macintosh-based web server products transition to iTools on Mac OS X and Mac OS X Server. This document covers the transition to iTools for those who own existing Tenon products, such as WebTen and iTools 5.0 for Mac OS X Server 1.2, and competing Mac OS web server products such as WebSTAR.
Since WebSTAR is not Apache based, Apache-specific transition issues will not apply to WebSTAR users. Instead, WebSTAR users can use the guidelines and principles in this document to aid their transition. WebSTAR users can skip over the sections that refer to specific technical Apache aspects of the configuration since the iTools Administration Server will isolate them from hand-editing configuration files.
Many sites wish to move their content and virtual host structure from an existing WebTen, iTools, or WebSTAR site to an iTools Mac OS X or Mac OS X Server installation. This document contains the distilled experience of several successful conversions, and aims to cover every aspect of the conversion process.
In general, the process of moving to iTools on Mac OS X is straightforward and generally a matter of making the old structure available within the correct directories on a new system. However, due to the differences between Mac OS 8/9 and Mac OS X, the process is not as simple as it first may appear. WebTen and WebSTAR have a method of handling linebreaks and character case that enable easy management of web-based content in a Macintosh environment. Since these provisions are not available under Mac OS X, changes may be necessary.
This document assumes an operational installation of an existing web server and a new iTools installation. For details on WebTen or iTools, refer to the respective User Guides for each product.
This document assumes full knowledge of both the Mac OS 8/9 and Mac OS X User Interfaces. Previous knowledge of the command line is not required and any command-line instructions will be described fully. Knowledge of fundamental network, web server concepts, and knowledge of DNS are also assumed so, if any of these topics are not familiar to you, please contact Tenon for special assistance.
Throughout this upgrade process, be sure to test each change at each step of the way to make sure that it had the desired effect. Testing at each step of the way will help determine what went wrong if some configuration setting causes your server to fail.
Keeping a log is an extremely important tool. It might be helpful to print these instructions and make notes on them as you go along. If you get stuck at any point in the process and there is no documentation that seems to answer your question, contact Tenon Technical Support and pass on a copy of the notes that you have made. This will help them to more quickly identify and resolve your specific issue.
Inline text that is presented in fixed-width typeface
represents commands that a user can type on the Unix command line. In
Mac OS X, the Unix command line can be accessed by opening the
"Terminal" application located in the "Utilities"
folder inside of the "Applications" folder.
Text that is offest and presented in a fixed-width typeface represents elements from configuration files or scripts. An example of this construct follows.
This type of text represents an element from a configuration file or a script.
Care will be taken to include a marker at the beginning of each section to indicate whether that section will apply to users transitioning from WebTen, WebSTAR, or previous versions of iTools.
In order for a transition to iTools to be successful, it is important that you plan out the steps in advance and ask questions of Tenon Technical Support for any issues that are confusing or need additional explanation.
Mac OS provides HFS and HFS+ filesystems. Mac OS X allows the user to choose between HFS+ and UFS filesystems. The UFS filesystem is a true Unix filesystem that provides additional features such as built-in fragmentation resistance, long filenames (up to 255 characters), increased robustness, and support of Unix hard links. Another advantage of UFS is that it does not require specially-configured access control parameters to accomodate the case-insensitivity of HFS+ for file access under Mac OS X. See Section 4.7.2 Case Sensitivity Issues for more information.
Apple's implementation of UFS in Mac OS X and Mac OS X Server results in lower performance than HFS+. Apple has given HFS+ fragmentation resistance, long filename support, and support for Unix soft links (but not hard links). To further drive users away from UFS, certain Mac OS X Applications (such as Netscape) do not work properly when installed on UFS volumes.
At the time of this writing, Apple recommends that Mac OS X and Mac OS X Server users use HFS+. Fortunately, either filesystem works well with iTools.
Throughout the course of computer history, different operating-system developers developed differing ideas of how to terminate the end of a line. The creators of Unix chose the most logical line termination character -- a single character called a "newline" that performs the functional purpose of a carriage return and a line feed. The newline character is commonly represented as "\n". IBM and Microsoft, in the creation of DOS, chose to use both carriage return and linefeed characters to delineate the end of a line. This was convenient for early dot matrix printers. Apple decided to use only the carriage return to end a line.
Although modern text editors on all platforms can convert between the different line termination formats with ease, the same cannot be said for shell scripts, Perl scripts, and configuration files such as those used by Apache. Most WebTen users are diligent in their adherence to Tenon's recommendation to edit Tenon-related scripts and configuration files in an application such as BBEdit that can save files with Unix linebreaks. If there are any scripts or configuration files that have not been converted to Unix linebreaks, you will want to do this before continuing. WebTen provides a conversion utility called "Unix<->Text" to convert files with Mac linebreaks to files with Unix linebreaks. This utility program is found in the "tenon/utilities" folder.
Since HTML is not parsed on a line-by-line basis, it is completely agnostic of the existence of linebreaks at all. There is no need to convert any HTML content to Unix linebreaks.
An issue of significant importance is how to transfer content from your existing server to your new iTools server. It is possible to transfer the files via FTP, but this is often a tedious process that can result in a significant amount of frustration.
The easiest way to transfer content is by using a method such as Apple File Sharing (AFP). Using AFP, both a Mac OS computer and an iTools server running Mac OS X can easily share files.
Each website administrator has his own hardware considerations. Some webmasters choose to physically move the hard drive with the necessary content. Other webmasters like to start clean and move only the necessary content files. Regardless of what method you choose, make a note of where on the filesystem your current content is located, what CGI scripts you or your clients run, and the names of the virtual hosts currently configured on your system.
It is recommended that you perform a clean install of both Mac OS X and iTools in order to reduce the potential for issues. There may be issues that these instructions do not account for if you start with an existing pre-configured Mac OS X system -- you may have to modify these instructions according to your specific configuration needs.
If you have an already-configured Apple-delivered Apache, you may wish to simply apply iTools. iTools will keep your existing Apache configuration intact.
This section gives a brief description of the issues involved in preparing a Mac OS X Installation for iTools. Please refer to Apple's Mac OS X Documentation and Apple's website for definitive information on installing Mac OS X.
It is best to prepare your server for Mac OS X by starting with a cleanly-formatted HFS or HFS+ partition or partitions (depending on your needs). The easiest way to do this is by booting from a Mac OS 8 or Mac OS 9 CD and running the "Apple Drive Setup" application.
Once the Mac OS X Installer has started, navigate to the place where the installer asks where the operating system should be installed. You will notice a checkbox near the bottom of the screen asking whether or not the drive that you have selected should be reformatted to use the UFS filesystem. As described above, both the HFS+ and UFS partition types have specific advantages and disadvantages based on your particular situation and needs. Based on your transition plan and the description of the two filesystem types given above, in Section 2.1 Target Filesystem, either check this box or leave it unchecked.
It will be easiest to adequately test your new iTools installation if you do a clean install of Mac OS X on a computer dedicated for the task of running the web server and accessible via the Internet. Ideally, this computer should have a dedicated external IP address and both forward and reverse DNS should be provided on your network. Make sure that all of the applicable network settings are correct for your computer including IP address, DNS server IP address, domain name, subnet mask, and router address.
Using the Mac OS X Software Update Utility, upgrade to the latest version of Mac OS X. Due to the nature of Apple's update process and what version of Mac OS X that you installed, it may be necessary to run the update program as many as four times in order for your server to reach the latest version of Mac OS X. The latest version of Mac OS X at the time of this writing is 10.1.5.
Beginning the iTools installation process is as easy as double-clicking the "iTools.mpkg" file in the iTools directory of the installation CD-ROM. You will need Administrator Access in order to install iTools.
Please refer to the iTools User Guide for a detailed step-by-step walkthrough of the installation procedure.
In order to install iTools without the Installation CD-ROM, you must first download the necessary packages from Tenon's website. In order to download iTools, you must follow the "download" link from the following URL:
http://www.tenon.com/products/itools-osx/
At this point, take the time to download all of the applicable iTools documentation as well. Refer to the iTools User Guide for a detailed step-by-step walkthrough of the installation procedure.
Before migrating any content or configuration over from WebTen, it is important to verify and test the new iTools installation to make sure that it is set up and configured properly. Not only should you check to make sure that you can access your new website from an IP address external to your web server's internal network, but you should also make sure that you can access the iTools Administration Server to make sure that you can access its features. At this time, do not make any Admin Server changes.
This section covers the most important, time consuming, and tedious process of the WebTen to iTools transition. Fortunately, converting the WebTen configuration files to a format that iTools can understand is significantly easier the entering in a large amount of configuration information manually. Due to the similarities between WebTen and iTools, there is generally a 1:1 correspondence between the configuration parameters in use by the two products.
You should have a good idea of how your WebTen site is configured, and you answer the following questions to try to get an understanding of how to proceed at this point.
If your site has a small number of virtual domains and relatively few configuration setting changes, it would be advantageous to use the Administration Server to make these changes and not worry about importing, modifying, or debugging hand-edited changes to text files.
You may find it extremely helpful to record your current WebTen or iTools server configuration by viewing each Administration Server page in succession and print out the current settings of each section. This approach is advantageous whether you are using those settings as a basis for updating the iTools configuration using the Admin Server exclusively, or you are trying to verify that your hand-merged changes take effect and show up in the Admin Server.
WebSTAR users may want to take screenshots of the relevant configuration screens to use as a reference when entering settings into iTools.
Using this approach, view each successive area of the Admin Server and enter in the same settings that you had printed out from your WebTen configuration setup. While iTools has additional features and, in some cases, the configuration options have been relocated, you will find that the two interfaces are very much alike.
If you have an extremely large number of virtual hosts, access controls, and name server configuration, it will save many hours entering in virtual hosts and configuration settings by simply moving over the text configuration directives from the configuration files and making the required changes.
Before you continue on with this section, locate the Apache configuration file, httpd.conf, in the "tenon/apache/conf" folder of your WebTen installation. You should also locate the httpd.conf file in your iTools installation. In iTools, the httpd.conf file is locate in the "/etc/httpd" directory.
The Squid configuration file, squid.conf, is located in the "tenon/squid/etc" folder of your WebTen installation. In iTools, the squid.conf file is located in the "/Library/WebServer/tenon/squid/etc" directory.
The nameserver configuration is located in the "tenon/etc/named" folder of your WebTen installation. The "/etc/named" directory of your iTools installation contains the corresponding files.
The basic process for converting the VirtualHost containers from WebTen to iTools is to open up the WebTen and iTools httpd.conf files side-by-side (this can be done either on the Mac OS 8/9 server or on the Mac OS X server. In Mac OS 8/9, BBEdit works well as a text editor. In Mac OS X, the TextEdit application works well. Use whatever method described in Section 2.3 File Transfer Strategy works best for you to transfer the configuration file from one server to the other.
In order to grasp the task at hand, open the httpd.conf file in BBEdit on the WebTen server and search for "VirtualHost".
A VirtualHost container in WebTen 2.x looks like the following:
<VirtualHost 209.17.253.75:81> ServerName www.fac.org DocumentRoot /usr/local/etc/httpd/WebSites/www.fac.org Options Indexes FollowSymLinks IncludesNoExec </VirtualHost>
In order to modify this VirtualHost container for iTools, you must perform three basic steps that are outlined below.
The corresponding VirtualHost container in iTools looks like the following:
<VirtualHost 209.17.253.75:81> ServerName www.fac.org DocumentRoot /Local/Library/WebServer/WebSites/www.fac.org <Directory /Local/Library/WebServer/WebSites/www.fac.org> Options Indexes FollowSymLinks IncludesNoExec </Directory> NameVirtualHost 209.17.253.75 </VirtualHost>
A VirtualHost container in WebTen 3.x looks like the following:
<VirtualHost 209.17.253.75:81> ServerName www.fac.org DocumentRoot /usr/local/etc/httpd/WebSites/www.fac.org <Directory /usr/local/etc/httpd/WebSites/www.fac.org> Options Indexes FollowSymLinks IncludesNoExec </Directory> NameVirtualHost 209.17.253.75 </VirtualHost>
In order to modify this VirtualHost container for iTools, you only need to update the paths so that they use the prefix "/Local/Library/WebServer" instead of "/usr/local/etc/httpd".
It is possible that your VirtualHost containers look different than what is shown above. Oftentimes, VirtualHost containers contain directives such as "ServerPath", "ServerAdmin", and "ServerAlias" directives (among others). These can be moved straight across from WebTen to iTools without modification
It is also valid for Realm Protection or Access Control configuration to be included within the VirtualHost container. See Section 4.3.3 Realm Protection Transfer for information on identifying these directives. In most cases, Realm Protection directives within VirtualHost containers can be moved across without modification.
Realm Protection, the Apache method of protecting certain URL paths, files, or directories with a login and password, requires a number of Apache Configuration file directives in order for it to operate properly. Fortunately, the iTools Admin server performs a significant amount of work to shield the user from the complexities of Apache Realm Protection.
In order to transfer the necessary Realm Protection directives by hand, it may be necessary to understand how they work in order to successfully move the required directives to iTools so that they work properly. If you have a large number of Realm Protection schemes in place, you will find that understanding and transfering them will save you time. If you have a small number of Realms Protection schemes in place, you may find it easier just to re-enter them into the Admin Server.
These Realm Protection directives must be contained within a <Directory> container and apply only to the specified directory. These directives must be declared before the access controls can be enabled for a particular URL path, file, or directory by the "require" and "AuthName" directives.
These Realm Protection directives can be located in a <Location> container, a "Directory" container, or a <Files> container. While the aforementioned directives set up or configure Realm Protection, the following directives actually enable it for the URL path, file or directory specified.
require user adminrequire group iToolsAdminIt is important to note which directives exist within VirtualHost containers and which exist without being surrounded by VirtualHost containers -- make sure that this organization is maintained when moving them. Due to the increased restrictions and features of Apache 1.3 (on which WebTen 3.x and iTools are based), additional precautions must be taken with WebTen 2.x Realm Protection directives to make sure that they are wrapped by "Directory", "Location" or "Files" containers where where appropriate.
For more information on this topic, please see the Apache Documentation or the iTools Users Guide. You may also want to contact Tenon Technical Support for further assistance.
Apache's Access Control system provides a method for webmasters to deny users access to certain URL paths, files, or directories based on a flexible set of criteria. For example, a webmaster may choose to deny access to files with certain extensions, or he may deny access to his site from users with a certain IP address or hostname.
An example of an Apache Access Control used to prevent users from downloading critical WebCatalog ".db" files follows.
<Location ~ "/.*\.db($|.*\?)"> deny from all </Location>
It is important to look for these and transfer them to your iTools httpd.conf file. These directives can be moved to iTools' Apache without modification.
Squid's Access Control system is similar to the one that Apache uses and is implemented using Access Control Lists or ACLs. In order to ensure the security of your websites, iTools creates a corresponding Access Control both for Apache and Squid. This features makes it possible for your site content to be protected whether Squid is enabled or disabled. An example of a Squid ACL that corresponds to the Apache Access Control listed above follows.
acl all_db urlpath_regex/.*\.db($|.*\?) http_access deny all_db all
The process of moving these squid.conf directives from the old WebTen installation to the new iTools installation is straightforward and no modification to these directives is needed.
Provided that the new iTools server is replacing a WebTen server for DNS, no changes need to be made to any of the files in the "named" directory. All of the files can be moved straight across to iTools without modification.
If you are changing the way that your site hosts its DNS records, it may be necessary to make additional changes. For example, if you wanted to have your WebTen server do backup DNS for your domain and make your new iTools server the primary DNS server for your domain, then you may want to thoroughly read both the iTools User's Guide and the O'Reilly book DNS and BIND to fully understand how this process should be done.
iTools provides built-in tools for importing users to and exporting users from the Admin Server. This section explains the process of migrating both iTools users and users of the (optional) WEBmail product that Tenon sells to accompany and extend the features of iTools.
In order to import your WebTen users into iTools, you must first export your users using the export feature of the WebTen Administration Server. Refer to the WebTen User's Guide for additional information.
Before these users can be imported into iTools directly, it is important to edit the file and change the occurrances of the group "WebTenAdmin" to "iToolsAdmin". The purpose of this change is to make sure that the users who were given access to the Admin Server retain this ability and users who were not given that access do not have it.
Once this file has been exported, it can be moved to the iTools server and imported with the import feature of the iTools Admin Server. It is important to decide whether a conventional import or an "exclusive" import is the right choice for your situation. Please refer to the iTools User's Guide for additional information.
WEBmail database files can be safely moved between WebTen and iTools without modification. These database files are located in the "tenon/webmail" folder in WebTen and they need to be placed into the "/Local/Library/WebServer/WebMail/webmail directory under iTools.
WebTen 2.x uses Apache 1.2. WebTen 3.x and iTools use Apache 1.3. Mac OS X provides a different user experience than Mac OS 8/9. There are many variables in a successful transition from WebTen to iTools to account for. This section attempts to tie up any loose ends.
It is impossible to account for the vast number of differing configurations with a web server as powerful and flexible as Apache. Though the instructions given to move Apache Configuration directives between the httpd.conf from WebTen and the httpd.conf from iTools tries to account for all of the possibilities, you may have a unique situation that accounts for additional changes.
In order to make it easy to find any configuration file mistakes,
Apache has provided a way to find out any configuration syntax errors
before you try to run Apache. Once you have merged all of your WebTen
changes into the iTools httpd.conf file (and modified the WebTen
configuration as necessary), run the command apachectl
configtest on the command line of Mac OS X. The
"command-line" refers to the place where commands can be
entered in a window of the Mac OS X Terminal application.
If apachectl configtest reports any errors that you
don't understand, double-check your httpd.conf file for any obvious
typos, and review the above instructions. If you still cannot
understand what the problem is, contact Tenon Technical Support.
It is important to keep in mind that HFS/HFS+, the file sytem of Mac OS, is a case-insensitive for file access. Like all Unix file systems, UFS, the native filesystem of Mac OS X and Mac OS X Server, is case-sensitive.
Apache, originally developed for Unix systems, assumes that the underlying filesystem is case-sensitive. If you have chosen HFS+ as your filesystem of choice instead of UFS, then you have to make additional accomodations so that if a user varies the case of a URL he cannot sidestep your access controls.
In order to make the accomodations for HFS+, implement regular expressions that will account for both upper and lower-case variants of the directory or file in question. The following example illustrates this.
<Directory~"/MacHD/WebSites/www.fac.org/[Ff][Aa][Cc]-[Aa][Dd][Mm][Ii][Nn]"> AuthName "FACAdmin" require group FAC-Admin </Directory>
The above example will require the user to be presentin the
"FAC-Admin" group when he tries to access
http://www.fac.org/FAC-ADMIN,
http://www.fac.org/fac-admin, or any combination of upper
and lower-case letters including
http://www.fac.org/FaC-AdMiN.
In WebTen, file ownership and permissions issues are largely kept away from the average user. Advanced WebTen users often use the Unix-like features of WebTen for fine-grained control of FTP access.
Mac OS X brings the power of file ownership and permissions out to the user. The Finder now allows both ownership and permissions to be set without resorting to the command-line (as long as the user has the permission to change the permissions on the file or files in question).
The power that Mac OS X's Unix file ownership and permissions abilities provides also requires that users be more aware of file ownership and permissions. Generally speaking, the iTools configuration files such as httpd.conf, squid.conf, and the named configuration files should be owned by "root" and they should be associated with the group "wheel".
Additional information as it pertains to the correct file ownership and permissions settings for iTools Content will be given in Section 5.0 Transfer of WebTen Content.
iTools and Mac OS X cannot execute AppleScripts as acgis out of the box. Mac OS X Server provides a proprietary module to support this feature, so if your site uses a large number of AppleScript acgis, then it would make sense to use iTools on Mac OS X Server and use Apple's Apache module for running AppleScripts.
Your existing AppleScripts should run in Mac OS X (though Mac OS X Server is required to run them as acgis) without modification, though there are some differences between AppleScript in Mac OS 8/9 and Mac OS X. Refer to Apple's website for more information on AppleScript compatibility.
There are software programs that can aid Mac OS X users run their AppleScript applications on Apache. One example of such an application is acgi dispatcher written by James Sentman.
WebSTAR plugins are not supported under iTools. In virtually all cases, there are equivalent commercial and open-source solutions that can provide better performance and improved features over the WebSTAR plugin equivalents.
Longtime users of WebSTAR may have gotten used to using the non-standard WebSTAR convention of using the dollar sign ($) in order to specify direct arguments to CGI scripts. Any scripts that use this notation must be updated to use the standard CGI query-string notation in order for them to work properly.
The following example shows the non-standard WebSTAR convention that will work on WebTen and WebSTAR.
http://www.fac.org/Search.tmpl$Search?db=catalog.txt&eqskudata=123
The proper convention for specifying CGI parameters required by iTools is shown in the following example.
http://www.fac.org/Search.tmpl?Command=Search&db=catalog.txt&eqskudata=123
If your site has a large number of Perl or other CGI scripts, it is likely that there are paths hard-coded into the script necessary to accomplish certain tasks. In WebTen, these paths use the prefix "/usr/local/etc/httpd". In iTools, the equivalent prefix is "/Library/WebServer". Likewise, the path to the cgi-bin directory in WebTen was "/usr/local/etc/httpd/cgi-bin". The path to the corresponding directory in iTools is "/Library/WebServer/CGI-Executables".
Under WebTen, website content is located in the "WebSites" folder inside of the WebTen folder. Site-wide CGI scripts in WebTen are also located in the "cgi-bin" folder inside of the WebTen folder. In iTools, website content is located in the "/Library/WebServer/WebSites" directory, and CGI scripts are located in the "/Library/WebServer/CGI-Executables" directory.
In WebTen, each virtual host's content is contained within a folder called the name of the virtual host. iTools follows this same convention. Transfering the content from WebTen to iTools is as straightfoward as copying all of the folders from the WebSites folder on WebTen to the WebSites directory in iTools.
Copying CGI scripts from the cgi-bin folder in WebTen to the CGI-Executables directory on iTools is as easy as transfering the HTML content.
In iTools, there are two main classifications of FTP access: anonymous and user. Anonymous users are those who are allowed to log in to the FTP server generally only giving their e-mail address for access. FTP users have a system account on the server and are assigned a home directory. This home directory could be in the conventional "/Users" directory on Mac OS X, or it could be in the "WebSites" directory so they can update the content of a website.
In WebTen, anonymous FTP content was located in the FTP folder inside of the WebTen folder. In iTools, the corresponding location is inside of the "/Users/ftp" directory.
Generally speaking, content made available for anonymous FTP is to be downloaded only -- not to be changed. In order to make sure that your anonymous FTP content is protected, it is a good idea to change the ownership of the FTP content to make sure that it is secure. Since Mac OS X's ability to change ownership of files is limited, the following commands must be executed on the command line in ther Terminal application that comes with Mac OS X.
cd /Users/ftp sudo chown -R root:wheel *
Note: The sudo command will prompt you for your
password. It will execute the chown command once you've
entered your password correctly.
It is often desirable for users to upload content directly to the web server using FTP. In order for this to work properly, the permissions on the web content files need to allow FTP access. The Mac OS X finder allows changing the permissions and ownership of files, but there are certain restrictions that make it difficult to achieve the desired result.
In order to proceed, you should familiarize yourself with the
concept of changing directories on the command line. This is done
with the cd command. Use the cd command to
change to the directory that you want and use the chown and chmod
commands to adjust the permissions and ownership for the files in
question. Example of how to do this follows.
cd /Library/WebServer/www.tenon.com chown www:ftpguest *html chmod 664 *html
Provided that a user has been granted access to upload CGI scripts, the following commands will update the permissions necessary for executing and uploading Perl CGI scripts in the main CGI-Executables directory.
cd /Library/WebServer/CGI-Executables chmod 755 *pl
All of the changes in the previous sections have described, in detail, how to migrate from WebTen to iTools. For users with smaller websites, it is not a timesaving strategy to manually edit configuration files and merge in the settings to the new iTools configuration files. For larger sites, this ability is a welcome bonus. No matter what strategy you chose, careful execution of the above instructions should result in a working system.
If you encounter any problems, be sure to check your error logs. Check both the Apache and Mac OS X system and error logs. Make sure that your network settings are correct. Make sure that there are not any typos in any of the hand-edited configuration that you may have dealt with.
This document was written by Erik Lotspeich and the Tenon Technical Support Department. Helpful suggestions for content from Ed Pastore and Jody McAlister, who are WebTen/iTools users, were also integrated.