Instantiate the module with:
add-module ghcr.io/nethserver/imapsync:latest 1
The output of the command will return the instance name. Output example:
{"module_id": "imapsync1", "image_name": "imapsync", "image_url": "ghcr.io/nethserver/imapsync:latest"}
Let's assume that the imapsync instance is named imapsync1.
We need to bind imapsync to a mail server inside the cluster, we use the MODULE_UUID of mail server to configure imapsync, reveal the vmail master secret of local users and start the container waiting for cron tasks or individual user tasks
Launch configure-module, by setting the following parameters:
mail_server: module uuid of the mail servermail_host: local ip of the mail server
Example:
api-cli run module/imapsync1/configure-module --data '{
"mail_server":"8dd3b3fe-609c-42f7-a2d1-cecba9461bea",
"mail_host":"10.5.4.1"
}'
The above command will:
- start and configure the imapsync instance
security : "tls" or "ssl" or ""
- delete mails and folder on local account not in remote account delete_local: true, false
- delete mails on remote account once synchronized to localaccount delete_remote: true, false
- exclude folders prepend by
^and end by$exclude: folder1,folder2,^folder3$ - start tasks by a cron (use 5m for minute, 2h for hour: start a cron
0/5 * * * *or1 */2 * * *) cron: 5m - the remote imap account credentials (you can use the password of the imap master administrator if you know it, for example vmail. use the login user*vmail and the relevant password). Otherwise use the login and the password of the remote account.
- foldersynchronization: synchronize
all, only what is ininboxorall but with exclusion("all","inbox","exclusion") - task_id : must be unical, set by a random function by the UI
Example:
api-cli run module/imapsync1/create-task --data '{
"localuser":"administrator",
"remotehostname":"imap.foo.com",
"remoteport":143,
"security":"tls",
"delete_local": false,
"delete_remote": false,
"exclude":"folder1,folder2",
"remoteusername":"username",
"remotepassword":"password",
"cron":"5m",
"task_id": "a0241w",
"foldersynchronization": "all"
}'
Example:
api-cli run module/imapsync1/delete-task --data '{
"localuser":"administrator"
}'
Example:
api-cli run module/imapsync1/stop-task --data '{
"localuser":"administrator"
}'
Example:
api-cli run module/imapsync1/start-task --data '{
"localuser":"administrator"
}'
Read all imapsync/*.env files and start the synchronization
Example:
api-cli run module/imapsync1/start-all-tasks
Read all imapsync/*.env files and stop the synchronization
Example:
api-cli run module/imapsync1/stop-all-tasks
Example:
api-cli run module/imapsync1/get-configuration
Answer:
{
"mail_server": "e8a6177c-9ae5-4356-826b-0a5f93b2dbaf",
"mail_host": "10.5.4.1",
"mail_server_URL": [
{
"name": "mail2",
"label": "mail2 (R3.rocky9-3.org)",
"value": "e8a6177c-9ae5-4356-826b-0a5f93b2dbaf,10.5.4.1"
}
],
}Read configuration from environment and from imapsync/*.{env,pwd}
api-cli run module/imapsync1/list-tasks
{
"enabled_mailboxes": [
{
"name": "administrator",
"label": "administrator",
"value": "administrator"
9A3E
},
{
"name": "foo",
"label": "foo",
"value": "foo"
},
{
"name": "john",
"label": "john",
"value": "john"
}
],
"user_properties": [
{
"task_id": "qu1dcb",
"localuser": "administrator",
"remoteusername": "user2@domain.com",
"remotehostname": "imap.domain.com",
"remoteport": "143",
"security": "tls",
"delete_local": false,
"deletefolder": "",
"exclude": "",
"delete_remote": false,
"expunge_remote": "",
"cron": "",
"folder_inbox": "",
"foldersynchronization": "all",
"remotepassword": "password",
"service_running": false
},
{
"task_id": "vd2am3",
"localuser": "john",
"remoteusername": "user@domain.com",
"remotehostname": "imap.domain.com",
"remoteport": "143",
"security": "tls",
"delete_local": false,
"deletefolder": "",
"exclude": "",
"delete_remote": false,
"expunge_remote": "",
"cron": "",
"folder_inbox": "",
"foldersynchronization": "all",
"remotepassword": "password",
"service_running": false
}
]
}
You can retrieve the email and folder numbers and the email size for the local and remote account Example:
api-cli run module/imapsync9/list-informations --data '{
"localuser": "john",
"task_id": "vd2am3"
}'
output:
{"status": true, "host1Folders": 78, "host2Folders": 78, "host1Messages": 164625, "host2Messages": 155, "host1Sizes": 3060488650, "host2Sizes": 72036894}in case of error you will have
{"status": false}in the state folder of the imapsync module you can find environment file (*.env), password file (*.pwd) and lock file when a task is running (*.lock)
You can filter by the task name (locauser to sync + task_id)
The vmail.pwd file is the credential of the dovecot master user
.config/state/
├── cron
│ ├── foo_a0241w.cron
│ └── foo_a1j44r.cron
└── imapsync
├── foo_a0241w.env
├── foo_a0241w.lock
├── foo_a0241w.pwd
├── foo_a1j44r.env
├── foo_a1j44r.pwd
└── vmail.pwd
to launch manually a task
ssh imapsync1@localhost
podman exec -ti imapsync /usr/local/bin/syncctl start foo_a1j44r
podman exec -ti imapsync /usr/local/bin/syncctl stop foo_a1j44r
podman exec -ti imapsync /usr/local/bin/syncctl status foo_a1j44r
To uninstall the instance:
remove-module --no-preserve imapsync1
Test the module using the test-module.sh script:
./test-module.sh <NODE_ADDR> ghcr.io/nethserver/imapsync:latest
The tests are made using Robot Framework
Translated with Weblate.
To setup the translation process:
- add GitHub Weblate app to your repository
- add your repository to [hosted.weblate.org]((https://hosted.weblate.org) or ask a NethServer developer to add it to ns8 Weblate project