TITLE
    AppleShare IP 6.0: Mail Tool Read Me
Article ID:
Created:
Modified:
24625
9/23/98
10/13/99

TOPIC

    This article contains the Read Me document for the AppleShare IP 6.0 Mail Tool.


DISCUSSION

    Contents

    o Notes
    o Tool Purpose
    o Tool Requirements
    o Tool Features
    o Tool Questions & Answers and Troubleshooting

    Notes

    A prudent safety precaution would be to save/backup the original AppleShare IP Mail Database and Users & Groups file before running the AppleShare IP Mail Tool on it.

    Tool Purpose

    The AppleShare IP Mail Tool allows administrators to manage the AppleShare IP Mail Server database. While this database requires no management or intervention by users under normal circumstances, it is possible for the database to become corrupted after a system crash. The AppleShare IP Mail Tool also allows reassignment of mail messages for disabled mailboxes, and can be used to update and compress existing databases. The tool will also be necessary to upgrade an existing 5.0.x Databases into 6.0 Databases that can then be used by the 6.0 Mail Server.

    Tool Requirements

    The 6.0 version of the AppleShare IP Mail Tool requires AppleShare IP 6.0 or later. You will also need a 5.0.x version of the Mail Database if you intend to upgrade it to a 6.0 Database.

    Note: Running the Mail Tool on a very large Database file can take a long time. Running the Mail Tool using a G3 Server on a Database that was 1.5 GB took 4 hours. It would be wise to backup your Mail Database nightly to prevent a long downtime if the server happens to crash during the day. Just remember to backup your Users & Group File at the same time you backup your Database.

    Tool Features

    o Mail Database Updating

    Users of AppleShare IP 5.0.1 or later will need to upgrade their Mail Databases to be compatible with the 6.0 version of the Mail Server. Please note that the name of the Database has changed from "AppleShare IP Mail Database" for 5.0.x, into "AppleShare IP Mail 6.0 Data" for 6.0. If you use the default settings during the upgrade the tool will use the proper name for the new database. Be sure that the new database is placed inside the "AppleShare IP Mail Folder" with the correct name to complete the upgrade operation.

    Note for AppleShare IP 5.0 Users: The 6.0 version of the AppleShare IP Mail Tool will not create or modify an AppleShare IP 5.0 compatible mail database. AppleShare IP 5.0 users will need to upgrade their Mail Server and Mail Database to version 5.0.1 or later before they will be able to run the 6.0 version of the mail tool. In order to upgrade a 5.0 Database to a 5.0.x Database you will need the 5.0.2 version of the mail tool found on the AppleShare IP web site. Once you have upgraded your 5.0 Database to a 5.0.x Database you can then run the 6.0 Mail Tool to upgrade your Database so that it can be used by the 6.0 version of the Mail Server.

    o Mail Database Compression and Verification

    The AppleShare IP Mail Tool offers the ability to compress, verify and/or repair an AppleShare IP Mail Database. Database corruption can occur for a variety of reasons that include (but are not limited to) power failure, hardware failure, and system crashes. In addition to being a database verification tool it is also sometimes useful to run the tool on mail databases since the verification removes unused free space inside the original mail database, with the potential of greatly compressing the size of a mail database which may have grown over time.

    o Disabled Mailbox Reassignment

    The mail server uses a special "fingerprint" to ensure that a user's mailbox in the mail database matches the correct user record in the current AppleShare IP Users & Groups. The fingerprint is a unique number that is stored in both the user's record and the user's mailbox in the AppleShare IP Mail Database.

    The mail server checks for fingerprint mismatches each time it starts up. When it finds a mailbox in the AppleShare IP Mail Database whose fingerprint does not match the fingerprint of a user in the currently active Users & Groups file the server disables that mailbox. No mail is deleted from the disabled mailbox, however, the mailbox in inaccessible to a user trying to login under that account. To retrieve mail from a disabled mailbox, use the AppleShare IP Mail Tool to assign the disabled mailbox to a valid user in the AppleShare IP Users & Groups file.

    You can prevent mailbox mismatch problems by taking these precautions:

    - Treat the Users & Groups file and the AppleShare IP Mail Database as a set. Always back up and restore them together. If you were to restore the AppleShare IP Users & Groups file without also restoring the mail database, the mail server could disable mailboxes that have no matching user in the current Users & Groups file. If you must restore the Users & Groups file, make sure that all current users have retrieved their mail first (if possible). Then restore the Users & Groups file and the mail database from the same backup. Alternatively, you can restore the Users & Groups file, start the mail server, note the mailboxes that are disabled, and use the AppleShare IP Mail Tool to assign the disabled mailboxes to valid users.

    - If you move the AppleShare IP Mail Database to another computer, move the AppleShare IP Users & Groups file also. If you were to move the AppleShare IP mail database to another computer without moving the Users & Groups file, the mail server would disable most if not all mailboxes and create new, empty mailboxes for all users in the Users & Groups file for whom mail is enabled. Note that moving the Users & Groups file to another computer that is running the Web & File Server will cause any access privileges that have been assigned on that computer to be lost because the access privileges no longer match the Users & Group File.

    - When you delete users for whom mail is enabled, make sure the AppleShare IP Mail Server is running. If the mail server is not running when you delete users for whom mail is enabled, the next time the mail server starts up, it will report that each deleted users' mailbox does not have a matching entry and it will disable their mailboxes.

    Note: It is always safe to throw away a mail database that is empty (as indicated by a zero in the "Number of Messages" field in the mail server Activity window). When you restart the mail server, it will create a mailbox for each user in the AppleShare IP Users & Groups file for which the Enable Mail radio button is selected.

    Tool Questions & Answers and Troubleshooting

    Question: What is the "Indexes" folder that is inside the Mail Database Folder?
    Answer: That folder is used by the V-Twin search engine that is a part of the Mail Server. It stores temporary files used to index mail messages for quick searching. It can be thrown away and will be recreated when a user issues a new search of their mailbox. The folder should be backed up along with the Mail Database in order to speed up search operations, but you are not required to do so.

    Question: How do I export mail that is in a user's mailbox to a text file?
    Answer: The 5.0.2 version of the mail tool had a button that did this operation, but that button has been removed for the 6.0 Mail Tool. This functionality has been moved over to the IMAP Admin port. In order to export a user's mailbox, you log into the mail server via the IMAP Admin port using any IMAP client. Then you rename the mail folder that you would like to export with the suffix of ".xdump". (For example, a folder named "Accounting" would be renamed to "Accounting.xdump") All the mail in this folder will appear in a text file that is created inside the AppleShare IP Mail Folder.

    Question: What else does the tool scavenge out of the old Mail Database besides email?
    Answer: The Mail Server stores server and host preferences inside the Mail Database. After running the tool you will not have to re-enter your server and host settings.

    Question: Can I AppleScript the AppleShare IP Mail Tool to compress the AppleShare IP Mail Database before making a backup with my normal backup software?
    Answer: No. The AppleShare IP Mail Tool does not support AppleScript. We are evaluating adding AppleScript support to a future version.

    Question: Can I run the AppleShare IP Mail Tool while the Mail Server and Mail Admin are running?
    Answer: No. The Mail Server and Admin must be shutdown for the AppleShare IP Mail Tool to function.

    Question: I've noticed in the AppleShare IP Reassignment screen that some entries in the User's list are in italics, and I can't click on these users. Why is that?
    Answer: The AppleShare IP Mail Tool only allows the selection of users that have no mail in their accounts, or are not enabled for Mail. Users who are enabled for mail and have 1 or more messages in their Mailboxes can not be a target for reassignment. These users are shown in italic in the list to indicate their non-selectable status.

    Question: Can I Reassign disabled Mailboxes and continue to use AppleShare IP Mail 5.0.x?
    Answer: No. The AppleShare IP Mail Tool only supports account reassignment for 6.0 Mail Databases. If you have to reassign accounts in a Mail 5.0.x Database you will first need to "update" the Mail Database file using the AppleShare IP Mail Tool.

    Question: Do I have to reassign all the disabled mailboxes in an AppleShare IP Mail Database?
    Answer: No. The AppleShare IP Mail Tool supports the direct deletion of disabled mailboxes. This feature is useful for clearing out the mail of a user whose account record has been deleted from the Users & Groups file.

    Question: Can I run the AppleShare IP Mail Tool on a different machine than where the mail server runs?
    Answer: Yes, but it is not recommended. While the AppleShare IP Mail Tool is reassigning accounts or updating/repairing a Mail Database, it uses and updates user-mail information present in the Users & Groups file on the server. It is best if you use the tool on the machine with the same Users & Groups file as the database was originally used with.

    Question: After running the AppleShare IP Mail Tool I've noticed that the resulting mail database file is much smaller than the original file. Does this mean I have lost mail?
    Answer: No. In the normal day to day use of the mail server it can occasionally grow the mail database file to a large size to accommodate large messages and/or a large number of smaller messages. Over time this space is released and the mail server then reuses space inside the file. When running the AppleShare IP Mail Tool a new copy of all the information present in the original file is created. Many times the space requirements of this information are far less than the maximum file size represented by the old database.

    Question: After running the tool, some of my users received duplicates of some messages that they had already downloaded and deleted. Is this expected?
    Answer: Yes. Depending on when, where, and how bad the damage is to an AppleShare IP Mail Database it is sometimes difficult for the tool to determine if the message was actually deleted by the user. In cases like this the ASIP Mail Tool errors on the side of caution, and will post a copy of a message with an ambiguous deletion state. This can lead to message duplicates for mail that users have already received. We apologize for these messages, but felt that this was better than risking the loss of mail that wasn't actually deleted by the user.

    Question: The AppleShare IP Mail Tool makes a copy of my users and groups file. Why is this?
    Answer: The AppleShare IP Mail Database tool needs to modify the fingerprints of users inside the Users & Groups file while performing: verification, compression, or an upgrade of an existing AppleShare IP Mail Database. After the AppleShare IP Mail Tool updates the fingerprints, the old AppleShare IP Mail database file will no longer match the updated user fingerprints. Therefore as a safety measure the AppleShare IP Mail Tool makes a copy of the User & Groups data before any modifications are performed. This gives an AppleShare IP Administrator the option to revert to an old AppleShare IP Mail Database file (if necessary) and still use the old Mail Database file, rather than the newly created AppleShare IP Mail Database.

    Question: I pressed the cancel button during a Mail Database compression operation. Does this mean I have to restore the Users & Groups file in order to use my preexisting AppleShare IP Mail database file?
    Answer: No. The last step in the verification the AppleShare IP Mail Tool performs is the update of the fingerprints in the current Users & Groups file. And while the tool is updating the fingerprints the "cancel" button is disabled. This operation is normally so fast that unless your Users & Groups file has thousands of users it will be virtually instant (and even then it only takes a few seconds). During verification, the old Mail Database is moved into a backup folder for safe keeping. This folder is also where the Users & Groups file copy is placed. If the Users & Groups file copy is absent from this folder, then the existing mail database file is usable with out the need to restore the Users & Groups file.

    Question: What is the worst that can happen if I don't restore the Users & Groups data file; but after running the AppleShare IP Mail Tool I choose to reuse the old mail database rather than the new mail database?
    Answer: Good question. First issue: NO mail will be lost as a result of using an old AppleShare IP Mail database after running the tool. If you choose to re-use an older AppleShare IP Mail database after running the AppleShare IP Mail Tool (instead of using the new database file). When the AppleShare IP Mail server is run for the first time, it will most likely disable all mailboxes found in the old mail database (since the old mailboxes don't match the current fingerprints in the Users & Groups file). This then requires that you quit the Mail Server, run the AppleShare IP Mail Tool and reassign the disabled mailboxes. After reassigning the mailboxes, launching the AppleShare IP Mail server will work fine, and all users will have access to all of their mail.

    Question: Wow, the previous two answers sound complicated, how do I avoid all this?
    Answer: The above situation is only applicable if you've run the AppleShare IP Mail Tool, created a New AppleShare IP Mail Database (as the result of a compress, verify, or upgrade function); and after running the tool you wish to continue using the old AppleShare IP Mail database file. The universal rule is that when using an older copy of an AppleShare IP Mail database you have to also restore the Users & Groups file, otherwise you risk disabling mailboxes when you launch AppleShare IP Mail Server.

    (c) 1998 Apple Computer, Inc. All rights reserved. Apple, AppleShare, and AppleTalk are trademarks of Apple Computer, Inc., registered in the United States and other countries.

Document Information
Product Area: Apple Software; Communications-Networking
Category: AppleShare
Sub Category: AppleShare for Mac OS

Copyright © 2000 Apple Computer, Inc. All rights reserved.