Before attempting to use this utility, you should be familiar with the RFC822 standard. The Unix Source Extractor parameter file is referenced throughout this document. For more information on this file, see the "User Interface" section.
Note that the migrated files will be named mmddhhmm.pkl, mmddhhmm.pri, <loginID>.pri, and <loginID>.sec. The mmddhhmm.pri file will only contain the Directory section. If a file exists with the same time, the minutes value (mm) will be incremented by one minute.
To perform the migration
migrate [-u<User File>] [-r] [-a] [-m] [-d<path>] [-p</path/Parameter File>] [-? | -h | -H]
The following table lists the command-line options available in the UNIX Mail Source Extractor tool, and their functions:
Command | Class | Function | |
-u<file name> | Optional | Indicates a file containing a list of the users to be migrated. (Note that a file name must be present.) The file can be in password file format (/etc/passwd) or a list of logon IDs with one logon ID per line. This file will be used to obtain the necessary information (such as the user ID, info section, and home directory) if the line contains 6 colons, otherwise the password file will be used. This overrides the lowest UserID variable in the Parameter file. Example: File 1: | |
-r | Optional | Create custom recipients in Microsoft Exchange. (Does not create accounts or mail.) | |
-a | Optional | Create accounts in Microsoft Exchange. (Does not migrate mail.) | |
-m | Optional | Migrate mail to Microsoft Exchange (assumes custom recipients or mailboxes exist.) | |
-d<path> | Optional | Overrides the default location where the extracted data will be located. The default location is the current directory. | |
-p | Optional | Fully qualified path to the parameter file including the file name. Use the parameter file to indicate additional parameters. The parameter file can be located anywhere with any name. (Default is current directory.) | |
-?, -h, -H | Optional | Displays command-line Help. | |
The -r, -a, and -m commands migrate only the specific type of information indicated. However, if they are used together, they will migrate all of the types. Following are examples of common command-line procedures:
To migrate custom recipients and mail
To migrate accounts and mail
To migrate custom recipients and accounts
Note This command line will generate an error message on Import.
During the extraction, the process must have read access to all files and directories where the mail exists. Read access on all files to be migrated is the minimum requirement for extraction. Root or Superuser access can be used. All mail queues must be empty. No modifications are made to the passwd file.
A system of UNIX computers in a cluster will require special consideration for migration. When you perform the migration, you must have access privileges to log on to the computer that contains the mail spooler. (IMAP access is not sufficient.) If it is not possible to log on to and access both directory locations of the user's home directories and the mail spooler, migration must be run twice; once against the home directories and once against the mail spooler.
Account information and messages are migrated to Microsoft Exchange. The account information is accessed through the /etc/passwd file along with the "hostname" command, which uses the /etc/hosts file. Mail data is migrated from the mail spool (/var/spool/mail or /usr/spool/mail) and from files located in the home directories of the individual users.
Account information is taken from the /etc/passwd file. The passwd file has the field format of "login-name:password:user-ID:group-ID:info:directory:program". The properties of the new accounts are shown in the following table.
New Microsoft Exchange Property |
| |
Common-name | Login-name field of the passwd file. | |
Display-name | The first entry of the info field of the passwd file by default. For more information, see the discussion of the info field following this table. | |
Office | The second entry of the info field of the passwd file by default. For more information, see the discussion of the info field following this table. | |
Phone | For more information, see the discussion of the info field following this table. | |
Secondary-proxy-addresses | "migrate:smtp:<login-name>@< hostname>". Login-name is from the passwd file. Hostname is to be located by the UNIX c call gethostname,which uses the /etc/hosts file. | |
Home-server | Home-server will be "~server" which, when imported into Microsoft Exchange, sets the home server to the current directory server. | |
The mapping of the info field can be adjusted to individual systems. In most systems, the info field takes the form of "display name,office,phone," although the UNIX system does not recognize phone but places both office and phone information in the office output form. You can specify directory import/export fields in the parameter file, for mapping data stored in the field. This enables the following information mappings:
/etc/passwd | Directory Import/Export | |
Bill Lee | Display-name | |
Lee, Bill | Surname,Given-name | |
Bill Lee,10B,x55555 | Display-name,Office,Phone | |
If the info field does not contain the correct number of comma delimiters corresponding to the directory import/export template, the UNIX Mail Source Extractor does not create an error. If the info field does not have enough comma delimiters, the extractor accepts the data that is present and treats the other fields as having no data. If the info field contains too many comma delimiters, the extractor will treat the data between them as part of the last directory import/export field.
By default, only users with a user-ID over 99 are migrated. It is possible to override this default by changing the LOWEST_USER_ID_TO_MIGRATE value in the param.h file or by passing a specific user list file to the source extractor on the command line. Custom recipient creation is supported.
To start migration with directory synchronization
If you want to start migration with directory synchronization, follow the procedures below to create Microsoft Exchange custom recipients for UNIX IDs.
Use the UNIX source extractor to extract the custom recipients.
Import the resulting migration files by using the Migration Wizard.
To create Microsoft Exchange custom recipients on the UNIX side
To create Microsoft Exchange custom recipients on the UNIX side, follow the steps outlined below.
Use Directory Export to create a list of Microsoft Exchange users.
Create UNIX accounts for all of the users.
Create the .forward file in order to forward mail to Microsoft Exchange.
The message data to be migrated comes from the system mail spooler and the user's personal storage. The mail spooler location is configurable in the parameter file and the default is set in a header file of the C code, param.h. Note that Param.h is the template for the parameter file that can be called on the command line. This value will only have to be set once per computer if it is set in the header file prior to being compiled.
The default location is /var/spool/mail/. Inbox, Send Items, Outbox, and Deleted Items folders are created for each user with messages from the UNIX spooler being moved to the Microsoft Exchange Inbox folder.
The source extractor will also read mail from personal storage. Mail in personal storage has to be in the same format as mail in the spooler. Messages cannot have been touched by certain Emacs e-mail clients or any other client that modifies the standard message format.
For personal storage, both ~/Mail/ and ~/mail/ will be checked by default. The parameter file can be used to change those defaults. When addresses are extracted from message headers, the UNIX comma delimiter will be changed to semicolons. The names of the UNIX files in each folder will become the names of the Microsoft Exchange folders and the original capitalization is retained. The UNIX "sent" and "sent-mail" folders will be moved to the Microsoft Exchange Sent Items folder. Subfolders, however, will not be migrated.
The folder locations will map as shown below:
New Microsoft Exchange Location | Old UNIX Location |
Inbox | /var/spool/mail/ (System spooler) |
Sent Items | Sent or Sent-Mail folders |
UNIX Folder Name (Root Level) | UNIX-Folder-Name |
The message properties will map as shown below:
New Microsoft Exchange Property |
| |
Sender | The second From line in the header. If only one exists, the first From line will be used. The second From line usually contains a more descriptive address. These names will most likely have the form "AnnDevon@xyz (Part-time Developer)," depending upon the form in the actual mail. | |
To | To line in the header. | |
Cc | Cc line in the header. | |
Bcc | Bcc line in the header. | |
Subject | Subject line in the header. | |
Send-date | Send Date in the header's second From line. If it does not exist, then Received Date is used. If neither exists, the default is to Import time. | |
Received-date | Received Date in the header's first From line. If it does not exist, then Send Date is used. If neither exists, the default is to Import time. | |
Priority | 1 (normal). | |
Unread | Mail will be marked as unread unless the header field Status exists and has "r" as the value. | |
Unsent | Always FALSE. | |
Note Pine has a concept of unsent mail that is specific to Pine and dependent on the file name of the local mail store. The UNIX source extractor ignores this value and places mail in the "postponed-msgs" folder, which requires no special handling.
No calendar or address book information will be migrated.
The user interface for the Source Extractor is command-line only. After the process has started, there is no interaction between the program and the user. All control data is passed to the source extractor through the command line and parameter file at run time.
The UNIX shortcut for directory specification of "~billlee" for specifying "/home/billlee" is not allowed.
A sample parameter file (param.txt) is provided and the defaults are listed in the following table for each variable. If the syntax of the file is incorrect, migration will stop with an error message. All fields, with the exception of "Local Mail Store Location," can have only one value. An exclamation mark (!) as the first character of a line denotes that the line is a comment only.
Variable Name | Default | Description |
DAPI string | Display-name,Office | The Directory Import string that describes the content of the info field in the password file. This information is not verified by the UNIX Mail Source Extractor. (< 200 characters.) |
Lowest User ID to Migrate | 100 | The User ID of the first user to be migrated. This is set at 100, because it is recommended not to give users a number under 100. This default does not migrate system accounts such as root, diag, sysadm, bin or news. If an illegal User ID exists for the user, the account will be migrated without an error. (Integer between -1 and 10000, retrieved with scanf.) |
Mail Spool Location | /var/spool/mail/ | Location of the mail spooler. The default is pulled from the param.h file, which can be changed at compile time. |
Local Mail Store Location | /mail/ | The directory where personal mail is stored. The value "/mail/" is translated to "~home/mail/". Ten locations are supported (most sites have a maximum of three). This field is multivalued, if this variable is listed more than once in the parameter file, the last occurrence will not overwrite the previous values. Each value must be entered one per line. |
!Directory Import string that describes the content of the Info
!field in the password file.
DAPI string: Display-name,Office
!UserID of the first user to be migrated. This is set at 100
!because it is recommended not to give users a number under 100.
!This default does not migrate accounts such as: root, diag,
!sysadm, bin, and news.
Lowest UserID to Migrate: 100
!Location of the Mail spooler.
Mail Spool Location: /var/spool/mail/
!Directory where personal mail is stored
Local Mail Store Location: /mail/
Local Mail Store Location: /Mail/