Installation Overview

Installation consists of:

obtaining a compressed installer (iTools-*.*.pkg.tar.gz) from the Tenon web site (www.tenon.com/products/iTools) or from an iTools CD.
expanding the installer file (tar zxvf iTools-*.*.pkg.tar.gz).
finding and starting the iTools.mpkg application.
selecting iTools components to extract and initiating the installation process. In most cases, once the installation is complete, a component is ready for use.
verification of correct installation by referencing different URL addresses related to each component or in rare cases (e.g. a database component), examining the component release notes for a prescribed steps to verify correct installation.

Suggested URL references to verify correct installation are can be found in the "mpkg" description section for each package. These URLs are a quick check for correctness and are by no means an exhaustive verification of the module.

While it is suggested that packages be installed using the "mpkg" installer, packages may be installed one-at-a-time by using the "pkg" installer. Per-component installers are available in the iTools.packages directory. Compressed versions of each of the component installers are available separately at the Tenon web site and on the iTools CD. Before installing components one-at-a-time, make sure the core iTools component has been installed as it is a necessary pre-requisite for any constituent installation.

The mpkg installer has a graphical user interface for use from a system console. Remote or network-based installation can be accomplished using a command line version of the pkg installer called /usr/bin/iTools-installer.sh. The iTools-installer.sh is described in the Network Installation section below.

Unpacking iTools

Once you have downloaded the iTools distribution, use the following command to unpack the distribution:

# tar zxvf iTools-*.*.pkg.tar.gz

This command will extract the archive, and will create a Mac OS X server package file (called iTools.mpkg). This file is used by the Mac OS X server package installer to complete the iTools installation.

If the installation is from a CD-ROM, then the iTools-*.*.pkg.tar.gz file must be copied to a directory on a local disk and then unpacked with the command above.

Installation Dependencies

The iTools family of Mac OS X Server networking applications require a properly-set-up network configuration. Each Mac OS X system must be pre-configured with a hostname, an IP address, a domain name, and an IP address for a Domain Name Server. If you are unfamiliar with these terms, please contact your system administrator.

Use Mac OS X Server's "Network Configuration Manager" to set a hostname, a domain name, and an IP address. If necessary, consult with your network administrator and the Mac OS X Documentation for more information.

In order to prepare the OS X Server correctly so that iTools will configure itself when it is first run, you should open up the "Network" control panel in OS X Server. You can do this by clicking on the Apple menu and selecting "Computer Settings", and then selecting "Network". Click on the "Connections" tab and enter your IP address and the host name. A hostname on a web server machine is usually "www", but can be any DNS registered name such as "fred". Click on the DNS tab next and enter your domain name in the "Search Domains" field. It is necessary that you enter a domain name for iTools to work properly. A domain looks like "tenon.com" or "apple.com". Next, click on the "Services" tab and make sure that the Server Name is properly synthesized from your host and domain name. It should look like this: "hostname.domainname". For example, "fred.tenon.com".

Pre-Installation

If you have previously installed iTools, this release will preserve and incorporate the existing configuration files, including the following (paths relative to /Local/Library/WebServer):

Configuration/apache.conf:	The Apache configuration file
Configuration/tenon/squid/etc/squid.conf:	The cache configuration file
tenon/etc/*.db:	The iTools user and group database files
WebSites/:	Virtual host web content directories

Even though the package installer preserves an existing configuration, it is always a good idea to back up important files such as those listed above in case something goes wrong. If you are currently using Apple's built-in Apache web server, you may want to preserve your apache.conf file located in /Local/Library/WebServer/Configuration, and any additional Apache modules you may have added. The Apache modules can be found in /System/Library/Apache/Modules.

UFS and HFS

With OS X Server, Apple provides an advanced Unix file system called UFS. This file system is not compatible with HFS and HFS+ which were used with previous MacOS versions. OS X Server installs the "Blue Box" by default which contains a Macintosh File system for use with the version of MacOS that runs under OS X Server. Though web-based content can be stored in the HFS, HFS does not provide all of the performance and flexibility that can be taken advantage of by storing web-based content on the UFS. For example, HFS limits file names to 32 characters, and does not support Unix symbolic links. This can come at a serious disadvantage when flexible file names or placement are needed. We recommend storing web content on the UFS, and only using the HFS to store web-based content when absolutely necessary.

Installation

Install the iTools package using the Mac OS X package installer. The package installer can be found here:

The Package Installer

The package installer looks like the below picture when run. Use it to select the iTools for Mac OS X Server package as shown. The iTools package file may be called iTools.mpkg or iTools.pkg. The iTools.mpkg is an installer which allows selective installation of all the iTools components at one time. The iTools.pkg will only install the iTools essentials and not the extras which are discussed briefly in the iTools Extensions section.

Selecting the iTools Package

You must be the root or Administrator user in order to install iTools.

The iTools package installer creates the following files and directories. Subdirectories are not shown here but can be found in the package installer's log files.

/Local/Library/WebServer/WebSites

/Local/Library/WebServer/tenon

/Local/Applications/iTools.app/

/usr/local/squid -> /Local/Library/WebServer/tenon/squid

/Local/Library/WebServer/WebSites will be the home for all new virtual host content. Any pre-existing virtual host information is stored in the /Local/Library/WebServer/Documents directory.

Other files and directories may be installed depending on which iTools package has been installed. A sample version of the iTools.mpkg selection screen is shown below:

Selecting the iTools Packages

The installation takes about 5 minutes. After installation, iTools will be configured and running.

Network Installation

iTools can be installed remotely using the iTools-installer.sh provided on the iTools CD in the "Utilities" directory. This is a specially modified script approximation of the Installer application and is similar to the /usr/bin/installer.sh utility included with MacOS X Server. Use this script to install iTools remotely. The iTools-installer.sh script will also be located in /usr/bin/iTools-installer.sh after the first iTools installation. Note that the iTools-installer script only installs a single package at a time. iTools-installer parameters include `--help' to display a set of options, `--install' to install a package, and `--delete' to uninstall a package.

iTools Daemons

iTools for Mac OS X Server contains updated versions of key protocol implementations: Apache 1.3.9, DNS (Bind 8.2), Sendmail (Sendmail 8.9.3), and FTPD (wu-FTPD 1.3.4(7)). These are included to update and extend existing versions and to close one or more security holes that exist in the versions distributed from Apple. Bind 4.9.2 had a number of problems with the ability of outsiders to modify zone information without proper authority. Sendmail 8.9.1 had security problems in that internet spammers were able to forward mail through the server so that mail looked like it came from your host rather than the original spammer. Sendmail 8.9.3 closed this loophole. FTPD was updated to support virtual FTP hosts and to improve file access controls.

After iTools is installed, the DNS and FTPD Daemons are made active on your system. After WEBmail is installed, the Sendmail Daemon is made active on your system. If you do not need these Daemons running, you should turn them off as they waste system overhead. The paragraphs below show how each Daemon can be shut off if it is not needed.

DNS Daemon

If iTools finds evidence that the Domain Name Server (DNS) application - named - is running or configured, iTools will save any existing DNS configuration files in /Local/Library/WebServer/tenon/Backups/MACOSX-named.tgz. After preserving any existing named information and binary applications, the iTools installer updates the named software with BIND 8.2, creates named configuration information in a new /etc/named directory and installs a named start file in the /etc/startup directory. The /etc/hostconfig file is then modified to set DNSSERVER=-YES- so that named will be started automatically during system restart. If you do not plan to use the local machine as a DNS server, you should modify the DNSSERVER entry in the /etc/hostconfig file as DNSSERVER=-NO- and restart the system. This will save system overhead.

FTP Daemon

The FTP Daemon is preserved and controlled in the same way the Sendmail Daemon is controlled. Any existing files are stored in /Local/Library/WebServer/tenon/backups/MACOSX-ftpd.tgz. Then the iTools installer updates the FTP Daemon software and startup information. The FTP Daemon startup can be controlled by the "APPLE->Computer Settings->Network" control panel and selection of the "Servers" tab item. The FTP Server may be selected as ON or OFF to cause the Daemon to run or not at system restart.

We urge you strongly to turn these Daemons off if they will not be used by your system. It saves processor and memory overhead as well as reduces the risk that any external forces can attack your system.

Launching the iTools Application

iTools includes a Mac OS X Server application designed to modify local administration username and password information, change the Tenon software licensing, start and stop the web and administration servers, and flush the cache. Use the Workspace Manager to launch the iTools application /Local/Applications/iTools.app. This application serves as the "front-end" application to the iTools servers. This application can be quit at any time. The iTools servers are not automatically stopped when the front end application is quit. The iTools front-end application can be restarted at any time. The iTools servers are not restarted if they are already running when the front-end application is launched.

For new installations, a web server administration account is automatically created when iTools is installed with username admin and password admin. Overlay installations (those that install over a previous iTools package) preserve existing web server accounts. As one of the first system operations, you should change default administration user name and password.

You can change the default password by the following:

Pull down the "Admin" menu and select the "Set Admin Password" item. Enter the admin username and a new password for the iTools administration server. This username and password is used only by iTools. It need not exist in the system password database nor does iTools enter it into the system password database.

Setting the admin password is shown in the screenshot below:

Set the Admin Password

Interesting URLs

Use a browser to connect to the local system. The default URL "http://hostname.domainname" should give you the content previously available from the Apple supplied web server. Here are a few more interesting URLs. With the URL http://hostname.domainname/itools_admin You should get the iTools administration page. With this page you can:

Create new virtual hosts.
Enable SSL support. In order to use SSL, you must first obtain the SSL package by contacting Tenon Intersystems.
Add users and groups.
Look at status and operations logs for the web server and much more.

The initial username is 'admin' and the initial password is 'admin'. You are strongly advised to change these defaults. See Setting Admin Password above.

iTools Extensions

iTools includes separately install able packages that add functionality to the iTools web server. iTools extensions include ht://dig, a Sherlock-savvy search engine, and WEBmail, a hotmail-style mail server. Third-party packages include WebCatalog, a powerful eCommerce storefront, WebEvent, a calendar and appointment scheduler, WebCrossing, a conferencing application, HTML/OS a sophisticated tool for creating dynamic web pages, and FrontBase a powerful SQL92 compliant database . Open source packages include JServe, PHP, and MySQL. Once these packages are installed, you can browse the URLs listed below to find out more information.

http://hostname.domainname/webmail You should be able to access POP mail from remote servers.
http://hostname.domainname/webmail_adduser The iTools Administrator uses this URL to add local restricted users to the system database. These user accounts will be permitted to receive local email but will not be allowed login (e.g. telnet or rlogin) access to the system. Send a created user email and use WEBmail to read the message. By default, one needs to have an iTools admin account to add new webmail users. For a "Hotmail" style system in which anybody can create their own e-mail account, edit the iTools.conf file in /Local/Library/WebServer/tenon/apache/conf and comment out line 385. Line 385 contains the information "require group iToolsAdmin". You can comment it out by placing a "#" character as the first character of that line.
http://hostname.domain/index.cgi This url will give you a default set of indexing rules to make a searchable database of the local site. Run this index to create a searchable database.
http://hostname.domain/search.shtml This URL will search the database for key words and phrases.
http://hostname.domain/webcatalog This URL accesses the web page for WebCatalog.
http://hostname.domain/jserv/. This URL creates a dynamic web page indicating JServ status. To test Java Servlets, try http://hostname.domain/servlets/Hello. To test Java Script Pages try http://hostname.domain/jsp/shoop.jsp. To test embedded Java Servlets try http://hostname.domain/test.jhtml.
http://hostname.domain/test.php3. This URL generates a PHP environment table. Its sophisticated and a gives a great sense of what PHP has to offer. If PHP4 is installed instead of PHP3, use http://hostname.domain/test.php for the PHP4 version of the same table.
mySQL is not directly testable from a URL and must be tested from a series of command line requests. The mySQL release notes contain a set of command line requests that establish a small set of databases and then proceed to exercise the databases.
http://hostname.domain/webevent This URL accesses a demonstration copy of WebEvent, a popular Web based calendar program by Matador Design (http://www.matadordesign.com). Browse this URL immediately after iTools installation to set up the WebEvent administrator account.
http://hostname.domain/webx This URL accesses the web page for the demo version of WebCrossing.
http://hostname.domain/cgi-bin/htmlos-setup.cgi. This URL accesses the web page for the demo version of HTML/OS.

Note that these URLs only exist if the particular package has been installed.

Installing iTools: MacOS X Server