iTools Transition Guide

Please see text links at bottom of page for navigation

1.0 Introduction
2.0 Planning
3.0 Install Software on a New Server
4.0 Verify Transferred Configuration
5.0 Transfer of Existing Content
6.0 Putting it All Together
7.0 Acknowledgements

1.0 Introduction

The purpose of this document is to help users of Apache web server products transition to iTools 7.1 on Mac OS X and Mac OS X Server. This document covers the transition to iTools 7.1 for those who own existing Tenon products, such as iTools 6.5, and competing Mac OS X web server products such as Apple Mac OS X Server.

Many sites wish to move their content and virtual host structure from an existing Mac OS X or Mac OS X Server installation to an iTools 7.1 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.

1.1 Required Knowledge

This document assumes an operational installation of an existing web server and a new iTools installation. For details on Mac OS X Server or iTools 6.5, refer to the respective User Guides for each product.

This document assumes full knowledge of the Mac OS X User interfaces. Previous knowledge of the command line is an advantage, but 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.

1.2 Transition Hints and Tips

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.

1.3 Conventions and Terminology Used in this Document

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 previous versions of iTools.

Back to Table of Contents

2.0 Planning

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.

2.1 Target Filesystem

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.

2.2 Linebreaks

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 iTools 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. Mac OS X provides a conversion utility called "tr" to convert files with Mac linebreaks to files with Unix linebreaks. This utility program can be executed from The Terminal like this:

tr '\r' '\n' < input.filename > output.filename

Since HTML is not parsed on a line-by-line basis, it is completely agnostic to the existence of linebreaks. There is no need to convert any HTML content to Unix linebreaks.

2.3 File Transfer Strategy

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 X 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.

Back to Table of Contents

3.0 Install Software on a New Server

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.

3.1 Installing Mac OS X

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.

3.1.1 Preparing Your Drives

It is best to prepare your server for Mac OS X by starting with a cleanly-formatted HFS+ partition or partitions (depending on your needs).

3.1.2 Filesystem Choice

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.

3.1.3 General Guidelines

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.

3.2 Installing Available Mac OS X Updates

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.2.8.

3.3 Moving existing server configuraiton

Before installing iTools 7.1, it is important to migrate existing configuration over from Mac OS X Server or iTools 6.5. The following directories should be copy over:

/etc/httpd/*
/etc/mail/*
/etc/named/*

(For iTools 6.5)
/Library/WebServer/tenon/etc/users.db
/Library/WebServer/tenon/etc/groups.db

Before installing iTools 7.1, it is important to verify and test the configuration files to make sure that it is set up and configured properly. Do not worry if Apache is unable to start up; if you were running iTools 6.5., httpd.conf might contain iTools 6.5 specific directives. They will be filtered and reconfigured to iTools 7.1 directives after iTools 7.1 is installed.

3.4 Installing iTools 7.1

3.4.1 Installing from CD-ROM

Beginning the iTools installation process is as easy as double-clicking the "iTools7.pkg" file in 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.

3.4.2 Installing from Download

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.

Back to Table of Contents

4.0 Verify Transferred Configuration

This section covers the most important, time consuming, and tedious process of the Mac OS X Server and iTools 6.5 to iTools 7.1 transition. Fortunately, converting the iTools 6.5 configuration files to a format that iTools can understand is significantly easier than entering in a large amount of configuration information manually. Due to the similarities between iTools 6.5 and iTools 7.1, there is generally a 1:1 correspondence between the configuration parameters in use by the two products.

4.1 General Guidelines

This section covers the details of how to configure your previous settings manually. iTools 7.1 installer will automatically import iTools 6.5 and Mac OS X server configuration. You only need to read this section, if iTools 7.1 fails to import your existing server configuration during the installation.

4.1.1 Analyzing Your Current Configuration

You should have a good idea of how your web site is configured, and you answer the following questions to try to get an understanding of how to proceed at this point.

How many Virtual Hosts do you have?
How many users and groups do you have in the respective "Users" and "Groups" section of the Admin Server?
How many configuration parameters have you changed? Cache options, access controls, Apache settings, MIME type and action handlers, and FTP settings are all examples of settings that might be changed to suit the needs of a website maintainer.

4.1.2 Choosing an Approach

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.

4.1.3 Recording Your Current Setup

You may find it extremely helpful to record your current iTools 6.5 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.

Mac OS X Server users may want to take screenshots of the relevant configuration screens to use as a reference when entering settings into iTools 7.1.

4.2 Configuration of iTools Apache Using the Administration Server

Using this approach, view each successive area of the Admin Server and enter in the same settings that you had printed out from your Mac OS X Server 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.

4.3 Importing Apache Configuration Manually

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.

4.3.1 Locating the Necessary Files

Apache Configuration Files

Before you continue on with this section, locate the Apache configuration file, httpd.conf, in the "/etc/httpd" folder of your old server installation. In iTools 7.1, the httpd.conf file is locate in the "/Library/Tenon/WebServer/Configuration" directory.

Nameserver (BIND) Configuration Files

The nameserver configuration is located in the "/etc/named" folder of your old server installation. The "/Library/Tenon/DNSServer/Configuration" directory of your iTools 7.1 installation contains the corresponding files.

4.3.2 Virtual Host Transfer

The basic process for converting the VirtualHost containers from Apache to iTools 7.1 is to open up the Apache and iTools 7.1 httpd.conf files side-by-side BBEdit works well as a text editor. 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.

Locating the VirtualHost Containers

In order to grasp the task at hand, open the httpd.conf file in BBEdit on the old server and search for "VirtualHost".

Converting the VirtualHost Containers from Apache

A VirtualHost container in Apache 1.3 looks like the following:

<VirtualHost    209.17.253.75:80>
ServerName      www.fac.org
DocumentRoot    /Library/WebServer/WebSites/www.fac.org
<Directory /Library/WebServer/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 "/Library/Tenon/WebServer" instead of "/Library/WebServer". Extract the entire VirtualHost container and create a file based on the virtual hostname. Place the file in "/Library/Tenon/WebServer/Configuration/vhosts". For example:

www.fac.org:80.conf

Edit /Library/Tenon/WebServer/Configuration/vhosts.conf and insert a line like this:

Include /Library/Tenon/WebServer/Configuration/www.fac.org:80.conf

Additional Notes on VirtualHost Containers

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 Apache 1.3 to iTools 7.1 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.

4.3.3 Realm Protection Transfer

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.

Common Realm Protection Setup Directives

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.

AllowOverride: The AllowOverride directive declares that the Apache Configuration (httpd.conf and its included files) cannot be overriden by directives in .htaccess files.
AuthType: The AuthType directive defines the authentication method for the server to use when authenticating the client.
AuthDBMUserFile: The AuthDBMUserFile directive specifies the location of the file that contains username/password authentication information.
AuthDBMGroupFile: The AuthDBMGroupFile directive specifies the location of the file that contains username/group associations for authentication pruposes.
AuthDBMFormatNCSA: The AuthDBMFormatNCSA directive specifies whether or not the User and Group files are in NCSA DBM format.
AuthDBMAuthoritative: The AuthDBMAuthoritative directive specifies whether or not the User and Group files are authoritative or if other authentication methods should also be use to verify a user's access.

Common Realm Protection Enabling 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.

AuthName

The AuthName directive consists of a text string that is displayed to the client when he is prompted for authorization. This text string should be in quotes (") if it consists of more than one word. An example of a AuthName text string would be "iTools Administration User".

require

The require directive is used to initiate Realm Protection by causing the server to "require" certain conditions to be met before allowing the client to proceed. Two common examples of the way that this directive may be used follow.

require user admin
require group iToolsAdmin

Realm Protection Guidelines

It 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.

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.

4.3.4 Apache Access Controls

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.

4.4 Name Server (BIND) Database Files

Provided that the new iTools 7.1 server is replacing a Mac OS X 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 7.1 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 old 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.

4.5 Importing Users from iTools 6.5

iTools 6.5 user files are the same format as iTools 7.1. You can copy /Library/WebServer/tenon/etc/users.db and groups.db to /Library/Tenon/System/Configuration. This will import the users properly. However, iTools 6.5 FTP users depend on data stored in Netinfo. You will need to run the following commands to export iTools 6.5 users from FTP and import them to the new server:

(Execute in the old server)
nidump passwd . | grep iTools > /tmp/it-ftp-users

Copy it-ftp-users to the new server.
(Execute in the new server)
niload passwd . < /tmp/it-ftp-users

4.6 Ironing Out the Wrinkles

iTools 6.5 and Mac OS X Server uses Apache 1.3. iTools 7.1 can use both Apache 1.3 and Apache 2.0. There are many variables in a successful transition from iTools 6.5 and Mac OS X Server to iTools to account for. This section attempts to tie up any loose ends.

4.6.1 Apache Configuration Directives

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 Mac OS X Server and the httpd.conf from iTools 7.1 tries to account for all of the possibilities, you may have a unique situation that requires 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 Apache changes into the iTools 7.1 httpd.conf file (and modified the iTools 6.5 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 typing errors, and review the above instructions. If you still cannot understand what the problem is, contact Tenon Technical Support.

4.6.2 File Ownership and Permissions

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 Existing Content.

4.6.3 Apple-Specific Considerations

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.

4.6.4 Absolute Paths in CGI Scripts

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 Apache, these paths use the prefix "/Library/WebServer". In iTools, the equivalent prefix is "/Library/Tenon/WebServer". Likewise, the path to the cgi-bin directory in Apache was "/Library/WebServer/CGI-Executables". The path to the corresponding directory in iTools 7.1 is "/Library/Tenon/WebServer/CGI-Executables".

Back to Table of Contents

5.0 Transfer of Existing Content

Under Mac OS X, website content is located in the "WebSites" folder inside of the "/Library/WebServer" folder. Site-wide CGI scripts in "/Library/WebServer/CGI-Executables" folder. In iTools 7.1, website content is located in the "/Library/Tenon/WebServer/WebSites" directory, and CGI scripts are located in the "/Library/Tenon/WebServer/CGI-Executables" directory.

5.1 HTML Content

In iTools 6.5, each virtual host's content is contained within a folder called the name of the virtual host. iTools 7.1 follows this same convention. Transfering the content from Apache to iTools is as straightfoward as copying all of the folders from the WebSites folder on source computer to the WebSites directory in iTools.

5.2 CGI Scripts

Copying CGI scripts from the cgi-bin folder in "/Library/WebServer/CGI-Executables" directory to iTools 7.1 cgi-bin folder in "/Library/Tenon/WebServer/CGI-Executables" directory is as easy as transfering the HTML content.

5.3 Permissions for FTP

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.

5.3.1 Anonymous FTP

In iTools, anonymous FTP content is located in "/Users/ftp" folder. 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.

5.3.2 User FTP

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/Tenon/WebServer/WebSites/www.tenon.com
chown www:www *html
chmod 664 *html

5.3.3 Uploading CGI Scripts

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/Tenon/WebServer/CGI-Executables
chmod 755 *pl

Back to Table of Contents

6.0 Putting it All Together

All of the changes in the previous sections have described, in detail, how to migrate from iTools 6.5 to iTools 7. 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 (/var/log/system.log, /var/log/httpd/error_log, and /Library/Tenon/WebServer/Logs/error_log). Make sure that your network settings are correct. Make sure that there are not any typing error in any of the hand-edited configuration that you may have dealt with.

Back to Table of Contents

7.0 Acknowledgements

This document was written by the Tenon Technical Support Department.

Back to Table of Contents