Archive-Team
/
docker-mailserver
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Revise fetchmail page (#3998)

This commit is contained in:
Brennan Kinney 2024-05-02 19:44:54 +12:00 committed by GitHub
parent 7dcbbd7173
commit d00edd7209
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 109 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
docs/content/config/advanced/mail-fetchmail.md
View File

@ -2,7 +2,7 @@
title: 'Advanced | Email Gathering with Fetchmail' title: 'Advanced | Email Gathering with Fetchmail'
--- ---
To enable the [fetchmail][fetchmail-website] service to retrieve e-mails set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet: To enable the [fetchmail][fetchmail-website] service to retrieve e-mails, set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet:
```yaml ```yaml
environment: environment:
@ -18,66 +18,89 @@ Generate a file called `fetchmail.cf` and place it in the `docker-data/dms/confi
│   ├── fetchmail.cf │   ├── fetchmail.cf
│   ├── postfix-accounts.cf │   ├── postfix-accounts.cf
│   └── postfix-virtual.cf │   └── postfix-virtual.cf
├── compose.yaml └── compose.yaml
└── README.md
``` ```
## Configuration ## Configuration
A detailed description of the configuration options can be found in the [online version of the manual page][fetchmail-docs]. Configuration options for `fetchmail.cf` are covered at the [official fetchmail docs][fetchmail-docs-config] (_see the section "The run control file" and the table with "keyword" column for all settings_).
### IMAP Configuration !!! example "Basic `fetchmail.cf` configuration"
!!! example Retrieve mail from `remote-user@somewhere.com` and deliver it to `dms-user@example.com`:
```fetchmailrc ```fetchmailrc
poll 'imap.gmail.com' proto imap poll 'mail.somewhere.com'
user 'username' proto imap
user 'remote-user'
pass 'secret' pass 'secret'
is 'user1@example.com' is 'dms-user@example.com'
ssl
``` ```
### POP3 Configuration - `poll` sets the remote mail server to connect to retrieve mail from.
- `proto` lets you connect via IMAP or POP3.
- `user` and `pass` provide the login credentials for the remote mail service account to access.
- `is` configures where the fetched mail will be sent to (_eg: your local DMS account in `docker-data/dms/config/postfix-accounts.cf`_).
!!! example ---
??? warning "`proto imap` will still delete remote mail once fetched"
This is due to a separate default setting `no keep`. Adding the setting `keep` to your config on a new line will prevent deleting the remote copy.
??? example "Multiple users or remote servers"
The official docs [config examples][fetchmail-config-examples] show a common convention to indent settings on subsequent lines for visually grouping per server.
=== "Minimal syntax"
```fetchmailrc ```fetchmailrc
poll 'pop3.gmail.com' proto pop3 poll 'mail.somewhere.com' proto imap
user 'username' user 'john.doe' pass 'secret' is 'johnny@example.com'
pass 'secret' user 'jane.doe' pass 'secret' is 'jane@example.com'
is 'user2@example.com'
ssl poll 'mail.somewhere-else.com' proto pop3
user 'john.doe@somewhere-else.com' pass 'secret' is 'johnny@example.com'
``` ```
!!! caution === "With optional syntax"
Don’t forget the last line! (_eg: `is 'user1@example.com'`_). After `is`, you have to specify an email address from the configuration file: `docker-data/dms/config/postfix-accounts.cf`. - `#` for adding comments.
- The config file may include "noise" keywords to improve readability.
More details how to configure fetchmail can be found in the [fetchmail man page in the chapter “The run control file”][fetchmail-docs-run]. ```fetchmailrc
# Retrieve mail for users `john.doe` and `jane.doe` via IMAP at this remote mail server:
poll 'mail.somewhere.com' with proto imap wants:
user 'john.doe' with pass 'secret', is 'johnny@example.com' here
user 'jane.doe' with pass 'secret', is 'jane@example.com' here
### Polling Interval # Also retrieve mail from this mail server (but via POP3).
# NOTE: This could also be all on a single line, or with each key + value as a separate line.
# Notice how the remote username includes a full email address,
# Some mail servers like DMS use the full email address as the username:
poll 'mail.somewhere-else.com' with proto pop3 wants:
user 'john.doe@somewhere-else.com' with pass 'secret', is 'johnny@example.com' here
```
By default the fetchmail service searches every 5 minutes for new mails on your external mail accounts. You can override this default value by changing the ENV variable `FETCHMAIL_POLL`: !!! tip "`FETCHMAIL_POLL` ENV: Override default polling interval"
By default the fetchmail service will check every 5 minutes for new mail at the configured mail accounts.
```yaml ```yaml
environment: environment:
- FETCHMAIL_POLL=60 # The fetchmail polling interval in seconds:
FETCHMAIL_POLL: 60
``` ```
You must specify a numeric argument which is a polling interval in seconds. The example above polls every minute for new mails.
## Debugging ## Debugging
To debug your `fetchmail.cf` configuration run this command: To debug your `fetchmail.cf` configuration run this `setup debug` command:
```sh ```sh
./setup.sh debug fetchmail docker exec -it dms-container-name setup debug fetchmail
``` ```
For more information about the configuration script `setup.sh` [read the corresponding docs][docs-setup]. ??? example "Sample output of `setup debug fetchmail`"
Here a sample output of `./setup.sh debug fetchmail`:
```log ```log
fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started
@ -119,7 +142,11 @@ fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 2
fetchmail: normal termination, status 1 fetchmail: normal termination, status 1
``` ```
[docs-setup]: ../../config/setup.sh.md !!! tip "Troubleshoot with this reference `compose.yaml`"
[A minimal `compose.yaml` example][fetchmail-compose-example] demonstrates how to run two instances of DMS locally, with one instance configured with `fetchmail.cf` and the other to simulate a remote mail server to fetch from.
[fetchmail-website]: https://www.fetchmail.info [fetchmail-website]: https://www.fetchmail.info
[fetchmail-docs]: https://www.fetchmail.info/fetchmail-man.html [fetchmail-docs-config]: https://www.fetchmail.info/fetchmail-man.html#the-run-control-file
[fetchmail-docs-run]: https://www.fetchmail.info/fetchmail-man.html#31 [fetchmail-config-examples]: https://www.fetchmail.info/fetchmail-man.html#configuration-examples
[fetchmail-compose-example]: https://github.com/orgs/docker-mailserver/discussions/3994#discussioncomment-9290570