From Generic E-mail Systems#
The migration to Carbonio from a generic e-mail system requires a number of manual steps to be carried out on both the Source and Destination systems to be able to migrate correctly everything.
Since this is quite a long procedure, please read carefully the reminder of this section before attempting the migration, to understand which data, files and their format are needed.
Requirements and Limitations#
There are theoretically no limitations when migrating from a generic e-mail system, provided you can export suitable text files when required.
These files are CSV or ICS files with a precise format: they will be then processed using the scripts that we provide to import Users, Calendars, Contact, E-mails in the Destination. Make sure that the format of the files reflect the examples, to prevent any possible error while processing the files.
Phase 1, Provisioning#
This phase is divided into two steps, Accounts provisioning and DL provisioning, while the COS provisioning is an empty step, as generic e-mail systems do not have CoS.
Step 1-1, Domains and Accounts#
You need first to create on Carbonio the domain that will be imported and modify, its default COS according to your preferences, that will be applied to all users in the domain. You can refer to section Create New Domain and Class of Services (COS), respectively, for directions.
Hint
Make sure that all the desired settings for both the domain and the default COS have correct values.
Then, you need to export manually the accounts from the Source and import them in the Destination, you have three options. For each of them you need to create a CSV text file with suitable content that you later import. The difference between the files in the three alternatives described below is the data contained, which determines how users will then access their account on the first login.
We will call this file user_provisioning.csv; it must contain the following data
for each user to be migrated: e-mail address (which serves as
username), password, given name, surname, and display name. Other
values are needed, depending on the option chosen. Depending on the
Source, you should be able to export these date using a script or
some tool provided by the e-mail system.
File user_provisioning.csv must then be copied on the Destination to be
processed. We assume this file will be stored as
/tmp/user_provisioning.csv.
Option 1#
All users will receive the same password and they will need to provide a new password on the first login.
The CSV file must have the following structure:
email_1@example.io,givenName,Surname,DisplayName
email_2@example.io,givenName,Surname,DisplayName
email_3@example.io,givenName,Surname,DisplayName
As the zextras user, execute the following script, which will
create a command file that will be fed to carbonio later:
User Account Migration Script - Option 1
echo '' > user_provisioning.cmd
export USERPASS="Apsw4llUs3rs";
for p in $(cat user_provisioning.csv); do
IFS=', ' read -r -a array <<< "$p"
echo 'ca' ${array[0]} $USERPASS 'givenName "'${array[1]}'" sn "'${array[2]}'"' 'zimbraPasswordMustChange TRUE displayName "'${array[1]} ${array[2]}'"' >> user_provisioning.cmd
done
Once the script has been successfully executed, it will output file
user_provisioning.cmd, which can be given to carbonio as
input.
zextras$ carbonio prov -f user_provisioning.cmd
Option 2#
An empty password is created for all users, which are enabled for password recovery. Password recovery and a recovery address e-mail must be set up for each user.
The CSV file must have the following structure:
email_1@example.io,givenName,Surname,DisplayName,recovery_address1@domain.com
email_2@example.io,givenName,Surname,DisplayName,recovery_address2@domain.com
email_3@example.io,givenName,Surname,DisplayName,recovery_address3@domain.com
As the zextras user, execute the following script, which will
create a command file that will be fed to carbonio later:
User Account Migration Script - Option 2
echo '' > user_provisioning.cmd;
for p in $(cat user_provisioning.csv);
do
IFS=', ' read -r -a array <<< "$p"
echo 'ca' ${array[0]} "''" givenName "'${array[1]}'" sn "'${array[2]}'" displayName "'${array[3]}'" zimbraPrefPasswordRecoveryAddress ${array[4]} zimbraPrefPasswordRecoveryAddressStatus verified zimbraFeatureResetPasswordStatus enabled >> user_provisioning.cmd
done
Once the script has been successfully executed, it will output file
user_provisioning.cmd, which can be given to carbonio as
input.
zextras$ carbonio prov -f user_provisioning.cmd
Option 3#
The actual password of each user is set in the CSV file.
The CSV file must have the following structure:
email_1@example.io,password1,givenName,Surname,DisplayName
email_1@example.io,password2,givenName,Surname,DisplayName
email_1@example.io,password3,givenName,Surname,DisplayName
As the zextras user, execute the following script, which will
create a command file that will be fed to carbonio later:
User Account Migration Script - Option 3
echo '' > user_provisioning.cmd;
for p in $(cat user_provisioning.csv);
do
IFS=', ' read -r -a array <<< "$p"
echo 'ca' ${array[0]} ${array[1]} 'givenName "'${array[2]}'" sn "'${array[3]}'"' 'zimbraPasswordMustChange TRUE displayName "'${array[2]} ${array[3]}'"' >> user_provisioning.cmd
done
Once the script has been successfully executed, it will output file
user_provisioning.cmd, which can be given to carbonio as
input.
zextras$ carbonio prov -f user_provisioning.cmd
Step 1-2, Distribution Lists#
To import DLs, you need to export them in a CSV file,
called dl_provisioning.csv, that has this format:
distibution_list1@example.io,Description1,Name1,email_1@example.io,email_2@example.io,
distibution_list2@example.io,Description2,Name2,email_2@example.io,email_4@example.io,email_5@example.io
distibution_list3@example.io,Description3,Name3,email_3@example.io,email_6@example.io,email_7@example.io,email_8@example.io
The first three fields are parsed as the Distribution List’s address, Description, and Name, respectively, and they are reflected in the Carbonio Admin Panel. All remaining fields, whose number may vary, are the e-mail addresses that are member of the Distribution List.
As the zextras user, execute the following script, which will
create a command file that will be fed to carbonio later:
DLs Migration Script
echo '' > dl_provisioning.cmd
for p in $(cat dl_provisioning.csv) ;
do
IFS=', ' read -r -a array <<< "$p"
echo 'prov cdl' ${array[0]} 'description' ${array[1]} 'displayName' ${array[2]} >> dl_provisioning.cmd
len=${#array[@]}
for ((i=3; i<$len; i++))
do
echo 'prov adlm' ${array[0]} ${array[$i]} >> dl_provisioning.cmd
done
done
Once the script has been successfully executed, it will output file
dl_provisioning.cmd, which can be given to carbonio as
input.
zextras$ carbonio prov -f dl_provisioning.cmd
Alternatively, you can create manually each Distribution List as
follows. Taking the first list from the dl_provisioning.csv
file above as example, as the zextras user, enter the Carbonio
shell with command carbonio, then issue the following
commands.
carbonio> prov cdl distibution_list1@example.io displayName Name1 \
description Description1
carbonio> prov adlm email_1@example.io
carbonio> prov adlm email_2@example.io
Phase 2, Data#
This Phase is divided into three steps, which require an external tool to migrate all e-mails and exported files for Calendars and Contacts.
Step 2-1, Emails#
The most functional and standard way to read from the Source and write into the Destination is to use the IMAP protocol. For this reason, we suggest imapsync as the tool to perform IMAP migration.
Hint
We suggest not to use the Global Administrator account to perform this task, but to create temporary Administrator accounts in the Source and in the Destination to be used for the purpose of import process only, so you can safely remove them once the synchronisation has been completed, to keep the Administrators’ action history clear. These will be denoted as SOURCE_ADMIN_ACCOUNT and CARBONIO_IMPORT_ACCOUNT in the command below.
We assume that you have already obtained credentials of an account that can access all the accounts on the Source, and you have already created a Global Administrator to be used for the import only.
In the following command, that must be executed on the Node hosting Carbonio Mails and Calendar, replace all values written in ALL_CAPS with corresponding values, suitable for your infrastructure.
See also
The command uses the official imapsync’s docker image; to download it or to learn on alternative approaches (e.g., if you want to install and use imasync) and documentation, please refer to imapsyncs’s official documentation.
zextras$ for account in $(carbonio prov -l gaa SOURCE_DOMAIN); do \
docker run --rm gilleslamiral/imapsync imapsync \
--host1 SOURCE_ENDPOINT_ADDRESS --ssl1 --user1 ACCOUNT --authuser1 SOURCE_ADMIN_ACCOUNT --password1 SOURCE_ADMIN_PASSWORD \
--host2 CARBONIO_PROXY_NODE_IP --ssl2 --user2 ACCOUNT --authuser2 CARBONIO_IMPORT_ACCOUNT --password2 CARBONIO_IMPORT_ACCOUNT_PASSWORD; \
done
Step 2-2, Calendars#
We assume that the Calendar files of all users has been exported and
placed into Carbonio Mails & Calendar Node’s
/tmp/backup/ directory, in ICS Format, e.g.,
/tmp/backup/user1@example.com.ics,
/tmp/backup/user1@acme.corp.ics, and so on.
They can be imported into Carbonio using the following command:
zextras$ for account in $(carbonio prov -l gaa SOURCE_DOMAIN); do \
echo "prov sa $account postRestURL '/Calendar?fmt=ics' /tmp/backup/${account}.ics"; \
done | carbonio
Step 2-3, Contacts#
We assume that the Contacts files of all users has been exported and
placed into Carbonio Mails & Calendar Node’s
/tmp/backup/ directory, in CSV Format, e.g.,
/tmp/backup/user1@example.com.csv,
/tmp/backup/user1@acme.corp.csv, and so on.
They can be imported into Carbonio using the following command:
zextras$ for account in $(carbonio prov -l gaa SOURCE_DOMAIN); do \
echo "prov sa $account postRestURL '/Contacts?fmt=csv&csvfmt=thunderbird-csv' /tmp/backup/${account}.csv"; \
done | carbonio
Phase 4, Files#
Migration of Carbonio Files items is not supported when the Source is no Zextras-compatible platform.