The popstore provides a migration utility which can be used to migrate mail mailboxes for login accounts to either the PMDF MessageStore or the PMDF popstore:

• On UNIX platforms, the utility migrates BSD-style mail files to the popstore or MessageStore as well as migrating popstore accounts to the MessageStore.
• On OpenVMS platforms, the utility migrates VMS MAIL NEWMAIL folders to the popstore, migrates entire VMS MAIL mail.mai files to the MessageStore, and migrates popstore accounts to the Message Store.
• On NT platforms the utility can migrate popstore accounts to the MessageStore.

The utility, described below, can be used to simultaneously migrate one or many accounts. It can either create new accounts as it runs (e.g., when migrating native mail boxes to the popstore or MessageStore), or use pre-created accounts (e.g., when moving popstore accounts to the MessageStore).

8.2.1 Migrating UNIX and NT Mailboxes

Migrate mail files between message stores or between accounts.

Syntax

pmdf movein [username [password]]

Command Switches	Default
-before=time
-debug	-nodebug
-destination=store-type
-dstdmn=user-domain
-dstusername=dest-username	source username
-exception_file=file-spec
-force_migrate	-noforce_migrate
-forward	-forward
-help
-host=hostname
-inbox=file-spec
-input=file-spec
-log	-log
-since=time
-source=store-type	-source=native
-srcdmn=user-domain
-use_existing	-nouse_existing

restrictions

You must be user root to run this utility.

Parameters

username

Optional name of a single source message store user account to migrate. If not supplied, then the names of accounts to migrate are read from either an input file or standard input, stdin.

password

Optional password to set for the new account in the destination message store. Only used when migrating to the popstore or MessageStore.

Description

The pmdf movein utility migrates mailboxes from one message store to another, or from one account to another. The supported message stores are: BSD-style mail files (the "native" message store), the PMDF MessageStore, and the PMDF popstore. When moving from or to the native or popstore message stores, only messages in the inbox are migrated. For migrations from one msgstore account to another, messages in all folders are moved.

The pmdf movein utility performs all of the necessary locking so as to allow migrations to be carried out on an active system without loss of mail. Forwardings from the source message store account to the destination message store account are automatically established for each migrated user. Note, however, that use of the -noforwarding switch can compromise this robustness.

The basic inputs to the utility are: the names of the source and destination message stores; the names of the source store user accounts to migrate; optionally, the names of the destination store user accounts to create; and, also optionally, passwords to set for these new accounts. The source store username is assumed for the destination store if a desintation username is not specified. That is, by default, the name of the account in the destination store is the same as that in the source store.

When a username is supplied on the command line, then just that one user account is migrated. To migrate multiple accounts, do not specify a username on the command line and instead use the -input switch. Each line of the input file specifies the username of a single source store account to migrate. In addition, a line can specify a password to associate with the new account in the destination store, and the username to create in the destination store. The password and destination username, if supplied, must be on the same input line following the username with one or more white space characters separating each of the three. If the password contains a space itself, it must be enclosed in double quotes. To specify a destination username without specifying a password, the password must be specfied as an empty string (two double-quotes next to each other).

Comment lines can appear in the input file: a comment line is any line which begins with a # or ! character. Leading and trailing white space characters on lines are ignored. The following sample input should give the flavor of input files:

# A comment line # # to supply a password and destination username: angel "alex's password" alex bailey blakes-password blake # # to supply a destination username, but no password: chris "" casey # # to supply a password but no destination username: dana danas-password # # to supply neither a password nor a destination username: emile

When no username or input file is specified, input lines are read from standard input, stdin. The format of those input lines is identical to that of lines read from an input file. Input is terminated by typing a CTRL/D (EOD).

When migrating to a msgstore or popstore account, the destination account is automatically created. If a password is supplied, then the password is set in the new account. If no password is supplied, then the new account is marked with the PWD_ELSEWHERE flag. Normally, that causes authentication to then be performed against /etc/passwd. See the popstore documentation for further information. When migrating from a BSD-style mail file, the owner field in the new account is set from the gcos field in the /etc/passwd file. If moving between a popstore and msgstore account, the owner field of the destination account is set from the source account.

If there already is a pre-existing msgstore or popstore account---such as when migrating from the popstore to the msgstore---then the migration fails unless -use_existing is specified. Moreover, if the existing msgstore or popstore account has the MIGRATED flag set, then the migration fails unless -force_migrate is specified. When the account is successfully migrated, the MIGRATED flag is set in the account.

When migrating to a BSD-style mail file, a login account must already exist for the user. The account will not automatically be created. Any supplied password is ignored.

When migrating either to or from BSD-style mail files, the PMDF local delivery channel's methodology for locating a user's BSD-style mailbox file is used: the user's .forward file is first consulted, the PMDF profile database is checked, and as a last resort the path specified with the -inbox switch is used. If that switch is not specified, then the platform-specific /var/mail location is used as a last resort.

Note After a successful migration, the account in the source message store is left intact with its mail in place. In the case of a BSD-style mail file, the mail file is protected against further writing. In the case of migration from a popstore to MesageStore store type with the same username (or vice-versa), the account is changed in place from the one store type to the other.

The pmdf movein utility is extremely careful to back out of a failed migration, leaving the user account in the source message store in its original state. When multiple accounts are migrated, a failure to migrate an account does not terminate the utility. Instead, the utility backs out of the migration for the failed account and continues on to the next account. Failures are reported to standard error, stderr. The -exception_file switch can be used to log errors in an exception file. The format of the exception file is suitable for re-use as an input file.

Command Switches

-before=hh:mm:ss:dd-mmm-yyyy (UNIX only)

By default, all messages are migrated. The -before switch can be used to only migrate those messages stored on or before the specified time. For instance, to migrate all messages received between 08:30 and 13:00 on 1 April 2012, specify

-since=8:30:00:1-april-2012 -before=13:00:00:1-april-2012

The actual date and time time specification is parsed by the C run-time library function strptime. The formatting string used with strptime is

%H:%M:%S:%d-%b-%Y

For further information on specifying date and time specifications, please consult your platform's strptime documentation.

-debug

-nodebug (default)

Debug output can be enabled with the -debug switch.

-destination=store-type

This required switch specifies the name of the target message store. The accepted names are native (BSD-style mail files), msgstore (PMDF MessageStore), and popstore (PMDF popstore).

-dstdmn=user-domain

The name of the user domain to use in the destination message store. If not specified, then the default domain is used. Only applicable in conjunction with destination message stores which support user domains (currently, only popstore).

-dstusername=dest-username

The username to use in the destination message store. If not specified, the source store username is used.

-exception_file=file-spec

By default, failures are only written to standard error, stderr. Failures can also be reported to an exception file. The name of the exception file is given with the -exception_file switch. The file will only be created should a failure occur; the file will have the permissions 0600. For each account whose migration fails, an entry will be made to the exception file. The entry takes the form of one or more lines of comments followed by a line containing the failed username and any optional password and destination username. The format of the exception file is such that it can be re-used as an input file.

-force_migrate

-noforce_migrate (default)

This switch can be used in conjunction with the -use_existing switch. See the description of that switch for further details.

-forward (default)

-noforward

By default, a forwarding address for each migrated user account is established. This forwarding causes undelivered mail sent to the user's source message store address to be automatically forwarded to their account in the destination message store.

When migrating from the native message store, a forwarding to the account in the destination store is placed in the PMDF alias database. In addition, a .forward file with the same forwarding is created in the user's login directory. Any previously existing .forward file is renamed to .forward.save. If a file named .forward.save already exists, the previously existing .forward file is instead renamed to .forward.save.nnnnnn where nnnnnn is a six-digit number between 000000 and 999999. The new .forward file will either have the same ownership and permissions as the previous file or, if there was no previous file, it will be owned by the user and have the permissions 0600.

When migrating to the native message store, any forwarding for the account in the PMDF alias database is removed, and any .forward file is displaced in accord with the rules cited in the prior paragraph.

When migrating from the popstore or msgstore, a forwarding to the account in the destination store is added to the msgstore's forwarding database. When migrating to the popstore or msgstore, any msgstore forwarding for the destination account is removed from the msgstore's forwarding database. If the account is just being converted from popstore to msgstore (or vice-versa) in place, no forwarding is necessary.

Specify -noforward to prevent forwardings from being established. Note, however, that when -noforward is used, undelivered mail directed to the user's old address in the source message store can be returned as undeliverable (native message store) or delivered to the old, unused account (popstore or msgstore) until such time that the old account is deleted at which point the mail will be returned as undeliverable.

-host=hostname

Optional switch to specify the host name associated with the destination message store. If omitted, the host name used will be determined from PMDF configuration information: the official local host name when the destination store is the native message store; the host name on the msgstore channel when the destination store is popstore or msgstore. This host name is only used in conjunction with the -forward switch to construct a forwarding address for each migrated account.

-inbox=file-spec

This switch can be used when the native message store is used as either a source or destination message store or both. In those cases, it provides a default file specification to use when attempting to locate a user's BSD-style inbox file. The utility will always first look for a .forward file. If that does not produce an inbox file location, then the PMDF profile database is consulted. If that does not provide an inbox file location, then the location specified with the -inbox switch is used. If that switch is not specified, then /var/mail (Solaris) or /var/spool/mail (Linux) is used.

The file specification supplied with the -inbox switch can include the following substitution strings:

%+, %s, %u	Substitute in the name of the user account being migrated
%d, %h	Substitute in the home directory of the user account being migrated
\x	Substitute in the literal character x ( e.g., \% substitutes in %).

Thus, for example, on Solaris platforms the default path is -inbox=/var/mail/%s.

-input=file-spec

Specify an input file containing names of user accounts to migrate. Can not be used in conjunction with the username command line parameter. See the description above for further information on input files.

-log (default)

-nolog

By default, the utility reports each successfully migrated account to standard error, stderr. To suppress this reporting, specify -nolog. Note that errors are always reported.

-since=hh:mm:ss:dd-mmm-yyyy (UNIX only)

By default, all messages are migrated. The -since switch can be used to only migrate those messages stored on or after the specified time. See the description of the -before switch for further details.

-source=store-type

By default, the source message store is assumed to be the native message store. The permitted values are native, popstore, and msgstore.

-srcdmn=user-domain

The name of the user domain to use in the source message store. If not specified, then the default domain is used. Only applicable in conjunction with source message stores which support user domains (currently, only popstore).

-use_existing

-nouse_existing (default)

This switch is only honored when the destination message store is the popstore or msgstore. It is ignored when migrating to the native message store.

By default, a migration to a popstore or msgstore account will fail when there already is a pre-existing account with the same name as the requested destination account name (by default, the name of the source store account being migrated). To override this behavior, specify -use_existing. However, if the pre-existing account has the msgstore/popstore MIGRATED flag set, the migration will fail unless -force_migrate is also specified. Note that when migrating to a pre-existing account, the password for the account is left unchanged and migrated messages are added to those already stored for the account.

Examples

# pmdf movein -destination=popstore sue SeCreT
movein: Destination message store host name not supplied; using pop.com
movein: User "sue" successfully migrated (/var/mail/sue)
      

This example shows migrating to the popstore the login user sue. The password on the new popstore account is set to SeCreT.

# pmdf movein -source=popstore -destination=msgstore -use_existing sue
movein: Destination message store host name not supplied; using imap.com
movein: User "sue" successfully migrated
      

This example shows migrating the popstore user sue to the MessageStore. The -use_existing switch instructs the utility to use Sue's existing profile file for her MessageStore account. This way, her password and other usage information is preserved. Note that if -use_existing was not specified, this command would fail.

# cat user_list
smith SeCreT jones
williams "" johnson
# pmdf movein -destination=msgstore -source=msgstore -input=user_list
movein: Destination message store host name not supplied; using imap.com
movein: "smith" migrated
movein: "williams" migrated
      

In the above example an input file is used to direct the pmdf movein utility. The file instructs movein to copy the messages from one msgstore account to another. For example, in the first case, a jones msgstore account is created, its password is set to "SeCreT", and all of the messages in the msgstore smith account are copied over.