Upgrading to WebTen 3.0 from WebTen 2.x


Introduction

If you have an existing copy of WebTen, either WebTen 1.x, 2.x, or even an early 3.0 beta, you will need to closely follow the steps in this paper. The procedure is similar to that of the cloning an existing WebTen installation.

If you are new to WebTen, just double-click the installer and follow the few simple instructions included with the WebTen installer.

If you are transitioning from WebSTAR, you can simply save your WebSTAR content, install WebTen 3.0 and move your content into the appropriate virtual host folder in the WebSites folder after you have configured it with the Admin server.

Before you install WebTen 3.0

Backup your existing installation

Transitioning from WebTen 2.x to 3.0 assumes a working, fully-functioning WebTen 2.x installation. You should also make a backup of your original functioning WebTen folder in case something goes wrong.

Saving existing configuration

In addition to backing up the WebTen folder in its entirety as mentioned above, you should follow the steps below and backup the appropriate files to a safe and organized location to make merging the settings into the new WebTen installation easier.

Exporting Users and Groups (tenon folder)

If you have a large number of users in your WebTen users database, you may want to export your users so that they can be imported by WebTen 3.0. This can be done by clicking on the "Users" button from the main page of the admin server and clicking the "Import/Export" button from the Users screen. The export file will appear in the tenon folder. See section 7.10.2 of the WebTen Users guide for more information.

Exporting SSL keys and certificates

A functioning SSL installation contains an SSL key, an SSL certificate, and a certificate request. These files have the extentions .key, .crt, and .csr respectively. WebTen keeps the key (the most important component of the SSL setup) kept tucked away inside of the Unix file system (FFS). The certificate and the certificate request (which are located in the tenon/ssl/certs) should be backed up. The files are named by the IP address of your machine with the extension .crt or .csr.

The SSL key needs to be exported from within its secure location in the FFS to the Macintosh HFS where it can be seen and backed up. To maintain security, the utility required to export the key from inside of the is not installed by default. The WebTen users guide gives a complete and easy-to-follow list of instructions describing exporting the SSL key. See section 9.7.1 of the WebTen Users guide for more information.

DNS Configuration (tenon/etc/named folder)

If you are using WebTen as a DNS server, you may want to save your existing DNS configuration. This can be done easily by backing up the contents of the tenon/etc/named folder inside of the WebTen folder. The files of importance are the "named.conf" file, and the "db" files. The DNS database files begin with "db" and end with the IP address and domain names of the DNS zones that you have configured.

Apache configuration files (httpd.conf, mime.types)

Backup the httpd.conf and mime.types files from your existing WebTen installation. These files can be found in the tenon/apache/conf folder inside of the WebTen folder.

Squid accelerator cache configuration files (squid.conf)

Backup the squid.conf file in the tenon/squid/etc folder inside of the WebTen folder.

Plugins (Plug-ins folder)

If you use WebStar plugins, you should backup the plugins in the Plug-ins folder for reinstallation into WebTen 3.0.

Miscellaneous system settings (tenon/etc folder)

If you are using NFS, backup the fstab file. If you are using cron, backup the crontab file. If you are using IP-based virtual hosting (more than one IP address on the same machine), then backup the rc.local file.

Web Content and CGIs (WebSites and cgi-bin)

You should store your web content in a save place so that it is easy to merge it back into the new WebTen 3.0 installation.

Main FTP configuration file (tenon/etc/ftpaccess)

If you have made changes to the FTP settings in WebTen 2.x such as using virtual anonymous FTP or other advanced FTP features, you should back up the ftpaccess file.

Anonymous Virtual FTP Folders (WebTen folder)

If you are using the Anonymous Virtual FTP feature of WebTen, make sure to back up any of the FTP folders (usually located in the WebTen folder) that may contain FTP content that you do not want to lose.

Installing WebTen 3.0

Once you have obtained WebTen 3.0 either by visiting http://www.tenon.com/products/webten or contacting sales@tenon.com, you are now ready to install it. The double-clickable installer asks you where you want the WebTen 3.0 folder, and then proceeds to install the necessary files. Once the installation process has completed, you are ready to start WebTen 3.0 for the first time.

WebTen 3.0 startup and configuration

Make sure WebTen 3.0 runs out of the box

If WebTen 3.0 doesn't start up correctly the first time it is run, it certainly is not going to run correctly after merging the WebTen 2.x settings into it. Once you have started WebTen 3.0 for the first time, you should set the admin password, and make sure that WebTen is serving page properly. You should also be able to navigate WebTen 3.0's configuration settings using the admin server. If WebTen 3.0 does not serve out of the box when an existing WebTen 2.x was serving pages just fine, please contact Tenon Technical support.

Beginning configuration steps

Open the WebTen preferences. You should check the appropriate checkboxes for the services that you want to run. You will also notice that a new checkbox is added that says "Mail". If you intend to use WebMail to host a "Hotmail-style" mail server on your WebTen machine, then check this box. If you were previously running Tenon-only or dual stack, then check the "Replace Open Transport" checkbox and enter the settings in the same way that you entered them in WebTen 2.x. Note: As of OS 8.6, WebTen will not work in Tenon-only stack mode due to Apple's removal of MacTCP support. To take advantage of WebTen's high-performance TCP/IP stack, you must run in dual-stack mode.

After you have finished configuring the WebTen preferences, quit WebTen. If you chose to operate WebTen in dual-stack mode, you will have to go to the WebTen Libraries and disable MacTCPdlib.

Double-checking your settings

As a precaution, start up WebTen and verify that your new settings have taken effect. If you have chosen to run in dual stack mode, make sure that you can serve pages on your new IP address. Make sure that you the various services (such as WebMail) function properly. It is at this point that you can run the SSL installer. Make sure that you have a version of the SSL installer that is appropriate for WebTen 3.0. The SSL installer v3.0 that was made available for WebTen 2.1.10 is the correct version for WebTen 3.0 also.

Importing and merging your original settings

It is now time to import and merge your WebTen 2.x settings and configuration into the WebTen 3.0 system. Make sure that WebTen 3.0 is not running when you make the changes below (with the exception of Importing users/groups and importing the SSL key).

Importing Users and Groups (tenon folder)

If you chose to export your users and groups from your WebTen 2.x installation, can now import those groups. Place the export file in the tenon folder and import the users following the same steps that you used to export them. Instead of clicking the "Export" button in the admin server, you will now chose the "Import button". It is best to do an "Exclusive" import if you want to keep the original admin password. See section 7.10.2 of the WebTen Users guide for more information.

Importing SSL keys and certificates

You may now move the .csr and .crt files into the tenon/ssl/certs folder after running the WebTen 3.0 SSL Installer. In order to import the SSL keys, follow the instructions listed in the WebTen Users guide. See section 9.7.2 of the WebTen Users guide for more information.

DNS Configuration (tenon/etc/named folder)

In order to return your DNS configuration to what is was before, copy the db files and the named.conf file to the tenon/etc/named folder.

Apache configuration files (httpd.conf, mime.types)

The mime.types file contains the define MIME types for different documents served by WebTen. If you have added MIME types to your WebTen 2.x installation, you can simply replace your WebTen 3.0 MIME types file with the WebTen 2.x one.

Because of the additional features of WebTen 3.0, updating the httpd.conf file is not as easy as updating the MIME types file. You should open up both the new and old httpd.conf file with a text editor that can handle Unix line feeds (such as BBedit), and copy the <Virtual> containers from the WebTen 2.x httpd.conf file to the WebTen 3.0 httpd.conf file. An Apache virtual host container begins with <Virtual> and ends with </Virtual>. These are the directives that should be copied.

Advanced Apache configuration topic: Myopic Plugin Mode

Note for W*API Plug-in users Under WebTen 2.1, and advanced setting "Myopic Plugin Mode" is set to "on" by default. In WebTen 3.0, the setting is "off" by default. If Myopic Plugin Mode is set "on" in WebTen 2.1, change the setting to "on" in the WebTen 3.0 "httpd.conf" file after moving the <VirtualHost> containers and before launching WebTen. After confirming virtual host operation, use the admin server to set Myopic Plugin Mode back to "off".

Advanced Apache configuration topic: URL redirection

If you are using "RAW!" files for URL redirection, move "mod_raw.so" from the "modules:disabled" folder to the active "modules" folder.

For more complicated installations with many customizations, it may be necessary to copy other Apache directives from the old httpd.conf to the new one. It is safest to only copy the virtual host containers and make the other small changes with the admin server.

Squid accelerator cache configuration files (squid.conf)

Unless you have made extensive changes to the squid.conf file manually (such as using Squid as a proxy server, or have made extensive access control changes via the admin server), you should not put your old squid.conf file in place of WebTen 3.0's squid.conf.

Plugins (Plug-ins folder)

You can now move your WebTen 2.x plugins into your WebTen 3.0 plugins folder

Miscellaneous system settings (tenon/etc folder)

If you intend to use NFS, you can replace the existing fstab file with the one from your WebTen 2.x installation. The other configuration files should be manually merged. If you are using IP-based virtual hosts, you should copy the "ifconfig" lines from your WebTen 2.x rc.local file into your WebTen 3.0 rc.local file. Do not simply replace the WebTen 3.0 rc.local file with your WebTen 2.x rc.local file as you may not be able to use some of WebTen 3.0's newer services.

Web Content and CGIs (WebSites and cgi-bin)

You can now move the web-based content and CGI scripts into your new WebTen 3.0 installation.

Replacing necessary FTP files

You may now want to the new ftpaccess file from your WebTen 3.0 installation with the one you backed up from WebTen 2.x if you had made extensive changes to it. You should also replace the Virtual Anonymous FTP folders at this point by moving them into the WebTen folder (or wherever you had them before.

Post configuration checkup

You are now ready to run WebTen for the first time since the WebTen 2.x settings were merged into it. The server should now operate like your old server, except that it will now offer WebTen 3.0's new features and speed improvements.

Troubleshooting

If you run into problems, here is a quick rundown of what could be wrong:

Don't hesitate to call Tenon Intersystems, or e-mail Tenon Technical support if any difficulties or questions arise.


Page last updated 1/11/2000

http://www.tenon.com/support/webten/papers/webten-3.0-upgrade.html