Preserving and Restoring iTools Configuration


Introduction

Though this paper was originally intended to serve as a guide for backing up or moving an iTools installation to another machine, it can also serve as a guide to the internals of the different components of iTools.

The basic steps to creating an iTools installation based on a previously-installed iTools are relatively straightforward:

Note: This paper assumes a fully-functioning iTools.

Preparation

In prepration for the backup of the iTools files, make a note of the various packages that you have installed. Allocate a few hours to do the migration and warn your customers of possible unexpected downtime in case something goes wrong.

DNS preparations

If you are moving iTools to a new machine at a different IP address than the one that you are using now, you must be aware of the DNS-related implications of the move. If you are going to be using the same IP address, then you can ignore this warning.

If you are doing your own DNS for your domain either with WebTen, iTools, or some other software, make a note of the "TTL" or "Time to Live" field of your DNS settings. If your ISP is doing DNS for your domain, then you will have to contact them to find out what this value is.

The TTL field represents the time that DNS servers across the Internet will hold DNS records for that zone (domain) before they contact your DNS server for updated information. The settings can be viewed in WebTen and iTools by looking at the "Start of Authority" (SOA) settings for each zone in the DNS settings section of the admin server.

The best solution

Let's just say that your TTL is set for four weeks. You should the TTL to 1 day at least four weeks before the switch. It will take as long as four weeks for the servers across the Internet to update their records to 1 day. Then, after four weeks has passed, make the switch. You will now only need to have your old server up for 1 day.

If everything is done correctly, you will notice that your old server is serving most of the requests in the beginning. As time passes, the new server will handle more and more of the hits as the DNS servers around the world become updated with the new information. After a period of 1 day, no hits should be served by the old server, and you can safely remove it when you are certain that no requests are being served by your old server.

If you have made the switch without following the steps above, then you will need to keep your old server running for the length of time equal to the TTL. Like with the above suggestion, you will experience very little traffic on your new server at first, but as time goes by, it will experience more and more traffic on your new server and less on the old. When the time specified in TTL passes, your old server should't be receiving any requests at all. At this point, it is safe to take it down.

Preparation for migrating to a new machine

If migrating your iTools installation to a different machine, prepare that machine for installation by installing the latest version of Mac OS X Server. The latest version at the time that this paper was put together is Mac OS X Server 1.02. Also, install the latest version of iTools.

After you have finished installing Mac OS X Server and iTools on the new machine, you should test the server's basic functionality. Such items include, but are not limited to:

You will have to decide how you will transfer the files to the new machine from the old one. This paper will discuss creating a "tar.gz" archive of the new files that you can FTP to the new machine, but you can also use any number of methods including Apple File Sharing, NFS, and other methods.

Preparation for backing up iTools

In order to prepare to back up iTools, you must first find a target to back up onto. The target could be a mounted Apple File Sharing drive, an NFS drive, or another hard drive in the machine. The instructions given should be able to be easily adapted to backing up instead of a migration to a new machine.

Locating the files to be backed up

This step involves determining what iTools components that you have installed, and then determining what files to back up. Based on this information, you can construct an archive file that can be moved to the new machine or backed up to another disk.

If you do not know which iTools components that you have installed, you can check the "/Local/Library/WebServer/tenon/logs/iTools.updates" file. This file contains a log of all of the iTools components that are installed. It also contains a record of the time and date at which each particular component was installed.

Main iTools package

The main iTools package consists of a number of components including the Apache server, the Squid object cache, FTP (wu-ftpd), sendmail, BIND, and the admin server. Listed below are the files associated with each component and a description.

Apache server

Directory/FileDescription
/Local/Library/WebServer/Configuration/apache.conf apache.conf is the main Apache configuration file used with iTools. All new virtual hosts and Apache directives added with the admin server are placed in this file. This file is essential for operation of both iTools and Apache.
/Local/Library/WebServer/tenon/apache/conf/iTools.conf iTools.conf is the secondary Apache configuration file used by iTools. It contains iTools-specific directives and is modified by the various installer scripts. It is important this file is saved because it contains changes and modifications made by the various installers. Failure to copy this file could result in certain iTools components (such as WebCatalog or WEBmail) from working properly.
/Local/Library/WebServer/Logs Though not essential to web server operation, it may be desireable to save the Logs directory when backing up or migrating to an iTools installation on a new machine. Saving the files in this directory can help to maintain consistancy if log analyzer utilities are used.

Squid Object Cache Files

Directory/FileDescription
/usr/local/squid/etc/squid.conf squid.conf is the main Squid cache configuration file. It will contain the current cache configuration parameters such as the verbosity of the access log (whether or not referer or user-agent are logged), but also memory and disk cache size. If enabled, the squid.conf file will also contain IP-based access restrictions entered into the admin server. Failure to copy this file will result in loss of some access control settings, the cache stop list, and the various other Squid configuration parameters mentioned above.

FTP Configuration files

Directory/FileDescription
/etc/ftpaccess ftpaccess is the main FTP server configuration file. It contains all virtual anonymous FTP directives, and also contains settings such as the maximum number of users allowed to log in and whether anonymous/user-pass FTP access is enabled in the admin server. Failure to copy this file will result in loss of these settings.

Sendmail configuration files

Directory/FileDescription
/etc/sendmail.cf sendmail.cf is the main sendmail configuration file. It is rarely ever changed. There is no need to save or backup this file unless you have changed this file.
/etc/sendmail.cw sendmail.cw is a sendmail configuration file that contains a listing of the hosts for which sendmail is to receive mail for. It is recommend that you save this file if you have added virtual hosts. Each time a virtual host is added in iTools, this file is updated with the host and domain name of that host.
/etc/mail/relay-domains relay-domains is a sendmail configuration file that contains a listing of the hosts for which sendmail is to relay mail for. A relaying situation would occur if you used your iTools machine as an SMTP server. A clean iTools install delivers a blank file, so save or backup this file if you have changed it.

BIND configuration files

Directory/FileDescription
/etc/named The named directory contains the BIND or DNS configuration db files. If you are using iTools as a DNS server, it is essential that you save this directory to maintain your DNS configuration. If not, this directory can be safely ignored.

Miscellaneous iTools configuration files

Directory/FileDescription
/Local/Library/WebServer/tenon/libexec/iTools.sh iTools.sh is the main startup script for iTools. It handles all of the necessary initialization functions and configures network IP addresses if you are using IP-based virtual hosts. This script generally runs once at system startup. Failure to copy this file could result in failure of failure of IP-based virtual hosts to function properly.
/Local/Library/WebServer/tenon/etc/license.info license.info contains the license number information for iTools. Saving this file is important because a clean install of iTools loads a 14-day temporary license number. Once this license number expires, the Apache server in iTools will only operate for 2 hours at a time.
/Local/Library/WebServer/tenon/etc/users.db users.db is an Apache database file that contains the usernames and passwords used by the "Users" section of the admin server and by Apache for verifying logins to password-protected pages. Since this file contains your admin password, it is very important.
/Local/Library/WebServer/tenon/etc/groups.db groups.db is an Apache database file that contains the usernames and the groups they are associated with. This is used by the "Groups" section of the admin server and by Apache for verifying logins to realm-protected pages. Since this file contains the admin group and users allowed in this group as well as any other realm-protected group access priveledges, it is very important.

SSL packge (Domestic or International)

The SSL package enables iTools to transmit information using the Secure Socket Layer (SSL). If you have this package installed and you are using SSL, then you will need to back up some of its associated files.

SSL key files

Directory/FileDescription
/etc/ssl/private The private directory has severely restricted access permissions. The files contained within are only readable by the "root" user so they cannot be viewed by unauthorized users. The SSL key file is essential to SSL operation and it is paired with the certificate. Loss of the key file will render your SSL certificate useless, so it is important to back it up. There may be more than one key file present if you have multiple IP-based virtual hosts with SSL enabled. The keys should be named <IP address>.key where <IP address> is the IP address of the IP-based virtual host for which the key was created.

SSL certificate files

Directory/FileDescription
/Local/Library/WebServer/tenon/ssl/certs/*.crt Files with the ".crt" extension are SSL certificate files. They are matched with the key and are named <IP address>.crt where <IP address> is the IP address of the IP-based virtual host for which the certificate was created. Saving the certificate is as important as saving the key file.

Other SSL-related files

Directory/FileDescription
/Local/Library/WebServer/tenon/ssl/certs/*.cnf Files with the ".cnf" extension are SSL configuration files that contain the information that you entered when creating the certificate request (CSR) in the iTools administration server. These files are plain text files and are not required for SSL operation, but serve as a reminder of the settings that you used to create your certificate request (and certificate).
/Local/Library/WebServer/tenon/ssl/certs/*.csr Files with the ".csr" extension are SSL certificate request (CSR) files. These files are what is given to your certificate authority so that they can make you an SSL certificate that matches up with the key generated internal by iTools. CSR files are not required for SSL operation, but should be kept in the case that the certificate becomes lost and the Certificate Authority (CA) needs to create a new certificate for you.

Other iTools packages

For the most part, all other iTools packages' files are contained in the folder associated with that package configuration files that you have modified in association with each particular package should be backed up in a similar way to the iTools core and SSL package files.

Saving and Backing up files

The easiest and most effective way to manage backing up and moving the iTools configuration files is by using the "tar" command to "tar" up the configuration files and store them into a single file. This single file can then be moved to another machine and "untarred" to restore the configuration to the new system. The tar archive can also be moved to another disk or place of storage for backup purposes.

"Tarring" up a set of iTools configuration files is as easy as following the format of the following command. Because different iTools users will be using different features of iTools, some users may need to back up more than others. You should be able to add or remove the above "Directory/File" listings from above from the tar command given below.

Basic tar command

The easiest way to archive the files is to do it in a shell script. A simple shell script could look like the following. Note that the name of the archive can be changed to suit your individual preferences. You can create such a shell script by using any text editor on OS X Server. Remember to give your shell script execute permissions by issuing the command "chmod a+x <filename>" where <filename> is the name of the shell script. You can also use the OS X Server file browser utility to change the permissions on the file. You will also have to run this script as the "root" user if you want to back up your SSL key files in /etc/ssl/private.


#!/bin/sh

cd /
tar czvf itools-config-backup.tar.gz \
	/Local/Library/WebServer/Configuration/apache.conf \
	/Local/Library/WebServer/tenon/apache/conf/iTools.conf \
	/Local/Library/WebServer/Logs \
	/usr/local/squid/etc/squid.conf \
	/etc/ftpaccess \
	/etc/sendmail.cf \
	/etc/sendmail.cw \
	/etc/mail/relay-domains \
	/etc/named \
	/Local/Library/WebServer/tenon/libexec/iTools.sh \
	/Local/Library/WebServer/tenon/etc/license.info \
	/Local/Library/WebServer/tenon/etc/users.db \
	/Local/Library/WebServer/tenon/etc/groups.db \
	/etc/ssl/private \
	/Local/Library/WebServer/tenon/ssl/certs/*.crt \
	/Local/Library/WebServer/tenon/ssl/certs/*.cnf \
	/Local/Library/WebServer/tenon/ssl/certs/*.csr

You may have to modify the files archived by tar to your own preferences. For example, if you do not have SSL installed, then you will not need or want to back up any files in the "tenon/ssl/certs" directory. If you have WEBmail Pro, you may want to back up the changes that you have made to your WEBmail by adding the "/Local/Library/WebServer/web_mail" to the tar command. Remember the trailing "\". The backslash is important because it tells the shell that you are continuing on the next line.

Restoring the backed-up files

The next step is to move the tar archive to the machine on which the files are to be restored. Once the tar archive is transfered to the new machine, move it to the root or "/" directory. Then execute the following command:

If iTools is running, first execute:

/usr/sbin/apachectl stop
tar zxvf itools-config-backup.tar.gz

This should extract all of the proper files to the right places. Then start Apache by typing:

/usr/sbin/apachectl start

You will have to restart all of your other services. This can be done by issuing the "ps ax" command and recording the process IDs (PIDs) for sendmail, named, and other processes (depending on what you have installed). Then send a "HUP" signal to those processes causing them to restart. This is done by issuing the command "kill -HUP <PID>" where <PID> is the process ID of the service that you wish to restart.

All should now be well with your web server. If something doesn't appear to be working correctly, restart your machine to make sure that you didn't accidently forget to "HUP" something. If you have any difficulties, check your log files. If you have trouble figuring out the log file, go back through all of these steps to make sure that you didn't miss something. If all else fails, send an e-mail to Tenon Technical Support who will be happy to assist you with any difficulties that arise.


Page last updated 1/31/1999

http://www.tenon.com/support/itools/papers/itools-reference.html