modoboa/doc-ng/moving.md

---
title: Migrate to modoboa
description: Migrate from actual provider to modoboa
head:
  - - meta
    - name: 'keywords'
      content: 'modoboa, imap, migration, constraint, offlineimap'
---


# Moving to Modoboa

You have an existing platform and you\'d like to move to Modoboa, the
following tools could help you.

## Using IMAP protocol {#imap}

::: info
[Modoboa](https://modoboa.org/) provides a way to transfer accounts
hosted on a different platform/provider to your personal server using
the IMAP protocol and a tool called
[OfflineIMAP](https://www.offlineimap.org/doc/installation.html).
:::

It works as follows:

- You first declare what needs to be migrated, basically the domain(s)
  you own and where they can be found. By doing that, you\'ll allow
  accounts hosted on the platform/provider you\'re migrating from to log
  into your Modoboa server
- The first time an old account (one coming from your previous provider)
  successfuly log into Modoboa, a dedicated migration task is created
- On a regular basis (every hour generally), a cron job is responsible
  for generating an OfflineIMAP configuration file including
  instructions to migrate all declared migrations and lauching
  OfflineIMAP to start/continue migrations

::: warning

As you probably already understood, you can\'t migrate all your accounts
at the same time since you don\'t know their corresponding password
(most of the time). Every account migration must be started by the
account\'s owner.
:::

### Configuration

Modoboa won\'thandle the installation of OfflineIMAP so you need to do
it on your own. The following
[instructions](https://www.offlineimap.org/doc/quick_start.html) will
help you.

Once done, *the new admin interface (v2)* will let you:

- define the neccessary information to `connect to your old
  platform/provider`
- define `what is to be migrated` (ie. the accounts)
- customize the behaviour of OfflineIMAP : go to \'Parameters \> Imap
  Migration\' from the left menu

::: warning

**Auto create domain** option must be enabled to make this feature

:   work. Go to \'Parameters \> Administration \> Mailboxes\' and check
    if it\'s the case.
:::

To generate an OfflineIMAP configuration file, run the following
command:

``` bash
> python manage.py generate_offlineimap_config
```

The synchronization script must be configured to run periodically on
your new server. Since it will copy mailboxes content to its final
destination, filesystem permissions must be respected. To do that, it
must be executed by the user which owns mailboxes (generally `vmail`).

Here is a configuration example where the script is executed every
hours. You can copy it inside the `/etc/cron.d/modoboa` file:

``` shell
PYTHON=/srv/modoboa/env/bin/python
INSTANCE=/srv/modoboa/instance

0       */1     *       *       *       vmail   cd /srv/vmail && $PYTHON $INSTANCE/manage.py generate_offlineimap_config --output .offlineimaprc && /usr/local/bin/offlineimap > /dev/null 2>&1
```

Feel free to adapt it.

This will sync back-and-forth user mailbox.

### Providers

A provider represents an IMAP server that hosts one or several domains
you own. It includes connection information (network address, port,
etc.) and a list of hosted domain.

For each domain you declare, you must provide its name. Modoboa will
then create a local domain with the exact same name if needed (ie. if it
does not exist yet) the first time it migrates an account.

Optionaly, you have the possibility to rename a domain (for example:
domain.com -\> domain.net) by providing a value to the \'Local domain\'
field.

### Migrations

Migrations are automatically created, you don\'t need to do it.

The first time an account of your old platform successfuly log into
Modoboa (using old credentials), a local account and a migration task
will be created.

::: warning

In case of domain renaming as described in Providers section, users
must use the new email address as username for next connection attempts.
:::

SuperAdmins can monitor running migrations and stop/delete them from the
[IMAP Migration] section (left menu).

## From postfixadmin

A dedicated command allows you to convert an existing [postfixadmin](http://postfixadmin.sourceforge.net/)
database to a Modoboa one.

Consult the [documentation](https://github.com/modoboa/modoboa-pfxadmin-migrate) to know more about the process.

## Using CSV files

Modoboa allows you to import any object (domain, domain alias, mailbox
and alias) using a simple CSV file encoded using **UTF8**.

Each line corresponds to a single object and must respect one of the following format:

```csv
domain; <name: string>; <quota: integer>; <default mailbox quota: integer>; <enabled: boolean>
domainalias; <name: string>; <targeted domain: string>; <enabled: boolean>
relaydomain; <name: string>; <target host: string>; <target port: integer>; <service: string>; <enabled: boolean>; <verify recipients: boolean>
account; <loginname: string>; <password: string>; <first name: string>; <last name: string>; <enabled: boolean>; <group: string>; <address: string>; <quota: integer>; [<domain: string>, ...]
alias; <address: string>; <enabled: boolean>; <recipient: string>; ...
```

Boolean fields accept the following values: `true`, `1`, `yes`, `y` (case insensitive).
Any other value will be evaluated as false.

::: warning
The order does matter. Objects are created sequencially so a domain must
be created before its mailboxes and aliases and a mailbox must created
before its alias(es).
:::

To actually import such a file:

``` bash
$ sudo -u <modoboa_user> -i bash
$ source <virtualenv_path>/bin/activate
$ cd <modoboa_instance_dir>
$ python manage.py modo import <your file>
```

Available options can be listed using the following command:

``` bash
$ python manage.py modo import -h
```