Fetchmail can't deliver messages to postfix [k8s/helm-chart]

[Xnyle]

📝 Preliminary Checks

• I tried searching for an existing issue and followed the debugging docs advice, but still need assistance.

👀 What Happened?

Using the community helm chart.
Enabled fetchmail and added one account/config to fetchmail.rc

Fetchmail starts, fetchesmMail but then fails to deliver it due to:

Helo command rejected: need fully-qualified hostname

My fetchmail is simply

poll xxxx with service imaps and timeout 120 and options no dns auth password 
    user "user" there with password "pass" is "existinguser@withuserdomain" here options fetchall ssl nokeep

👟 Reproduction Steps

No response

🐋 DMS Version

15.0.2

💻 Operating System and Architecture

k8s community Helm chart

⚙️ Container configuration files

📜 Relevant log output

2025-05-24T20:23:32.531389+00:00 docker-mailserver-5dfb984fb8-nkvdk fetchmail[67184]: reading message xxxx@xxxx:2 of 2 (7674 header octets) (log message incomplete)
2025-05-24T20:23:32.531398+00:00 docker-mailserver-5dfb984fb8-nkvdk fetchmail[67184]: SMTP error: 504 5.5.2 <docker-mailserver-5dfb984fb8-nkvdk>: Helo command rejected: need fully-qualified hostname
2025-05-24T20:23:32.531905+00:00 docker-mailserver-5dfb984fb8-nkvdk postfix/postscreen[84741]: CONNECT from [::1]:38698 to [::1]:25
2025-05-24T20:23:32.531967+00:00 docker-mailserver-5dfb984fb8-nkvdk postfix/postscreen[84741]: PASS OLD [::1]:38698

[casperklein]

Not a solution to your problem, but you might give getmail a try.

[polarathene]

fails to deliver it due to:

Helo command rejected: need fully-qualified hostname

This is an error from Postfix and this will be the first result on Google for keywords fetchmail "need fully-qualified hostname".

You could relax security on the Postfix side (via our Postfix override support), or consider why fetchmail isn't providing an acceptable HELO/EHLO.

---

Alternatively, this mailing list discussion suggests that fetchmail (or possibly Postfix too IIRC) would attempt rDNS on the IP of the network interface being used to connect through, or whatever is configured as the hostname on the system.

As you've mentioned you're using kubernetes, it lacks support for setting an explicit hostname from what I've heard through @georglauterbach , so you need to set our ENV OVERRIDE_HOSTNAME. I'm not familiar with our associated Helm chart project that well, I'd assume it has something in place to handle that?

Without that ENV being set, you'll have a single DNS label as the hostname by default AFAIK, containers usually have that set as a random hexadecimal ID. That is not a fully-qualified hostname AFAIK? (it'd expect a 2nd label I think?)

---

The alternative is like @casperklein suggested, to prefer Getmail instead. Fetchmail will deliver through SMTP it seems while Getmail differs by configuring the destination to run a command instead, which would avoid the issue entirely.

Do note that the two services behave slightly different beyond that. Our Getmail is not the latest release as we're using Debian packages for it, there are some features that newer Getmail added that it had lacked compared to Fetchmail, one was regarding the read/seen status change to remote IMAP inbox IIRC (if you didn't want to delete). Ensure that once it's setup it functions the way you expect 👍

[Xnyle]

OVERRIDE_HOSTNAME was already set, the other things you mentioned are clear.

IMHO rDNS is not the issue here as fetchmail simply uses localhost in the HELO. Not going to further debug this though.

Also not going to relax standard postfix settings as they are there for a reason, so I switched to getmail as suggested.

My expectation is that there is at least a note in the docs that fetchmail does not work out of the box under k8s.

[polarathene]

IMHO rDNS is not the issue here as fetchmail simply uses localhost in the HELO.

localhost is not a FQDN, mail.localhost would be though.

I switched to getmail as suggested.

👍

My expectation is that there is at least a note in the docs that fetchmail does not work out of the box under k8s.

Kubernetes support is unofficial, it is community managed (hence separate repo, and clarification in our docs).

You are welcome to PR that note to the fetmail docs page, it's just markdown so quite simple to contribute.

It should work though, provided the hostname is resolved to an FQDN. However fetchmail is a community contributed feature as well, no maintainer is that familiar with it's config and support, so if it lacks the ability to override the hostname, then yes without kubernetes supporting a way to configure the hostname of the container, it's not going to work I guess 😅

[georglauterbach]

I moved this issue to our K8s repository.

My expectation is [...]

My expectation is that those who open issues have understood that this project is maintained by individuals in their spare time. If there is an issue, you ask for help, and we'll do our best to resolve the issue.

---

To the matter at hand.

@cfis are you using fetchmail accidentally, or do you know anything about it not working? If so, we should (as was said) add a comment to the docs somewhere.

[cfis]

I am not using fetchmail - so don't know if it works or not. Based on this ticket though - docker-mailserver/docker-mailserver#990 - it seems to have been working on Kubernetes in 2018 so seems like it should work?

As for OVERRIDE_HOSTNAME - you MUST set it. See https://github.com/docker-mailserver/docker-mailserver-helm/blob/master/charts/docker-mailserver/values.yaml#L63.

@Xnyle how do you want to proceed on this issue? Sounds like you have moved to GetMail so should I close this? Or if you want to debug further that would be great also.

[polarathene]

For comparison to the 2018 referenced fetchmail config:

This issue:

poll xxxx with service imaps
  and timeout 120
  and options no dns auth password 
  user "user" there
  with password "pass"
  is "existinguser@withuserdomain" here
  options fetchall ssl nokeep

2018 issue:

poll 'imap.mail.eu-west-1.awsapps.com' proto IMAP
  user 'XXX@YYY.com'
  password 'PPP'
  is 'XXX'
  ssl

There has been many changes since 2018 though, chances are Postfix wasn't as strict on HELO.

EDIT: Postfix config had the config for HELO restriction added in April 2016 into the DMS v2 branch, so presumably it applied to the 2018 issue.

I don't have time to investigate atm, but perhaps it's specific to the fetchmail config differences only? (or possibly container runtimes back then were slightly different, I do recall we also treated hostname config quite differently too)

For reference, this is what our docs advise instead:

So it's unclear where @Xnyle came up with their Fetchmail config, unless they've used fetchmail elsewhere before (presumably in k8s environment too).

---

We also have a compose.yaml fetchmail example reference for testing, could probably not set the hostname and rely only on the OVERRIDE_HOSTNAME ENV to reproduce there.

Just adjust that config and run the commands detailed here should be sufficient, otherwise might need to be adapted to k8s if that works fine with compose.

[Xnyle]

Yes, my fetchmail config existed b4 outside of any container config.

BUT I already ensured that OVERRIDE_HOSTNAME is set and also even points to the correct Service IP.
And I also used the very config (ofc user changed) from the docs.

But that didn't change anything.

I also tried to find a setting in fetchmail that steers the HELO "banner" is sends but couldn't find any that has any change.

[polarathene]

I doubt this would resolve the fetchmail concern, but it is possible to replace the hostname binary with a shell script that emits the hostname you'd prefer instead. We needed that at build when installing Postfix, so you can reference what we did.

Presumably a service would instead use a syscall or similar to check the hostname, in which case that won't work.

I don't know k8s well, but this 2024 comment from a k8s maintainer states Pods have a hostname field that can be configured if that's helpful. Someone also shares a shell script attempt to change the hostname in other locations that might be checked.

[Xnyle]

Not sure I'f it's worth investigaring / solving as 90% of what you can do with fetchmail you can also do with getmail. Fetchmail would only be needed if you absolutely need to get the mail through postfix again in order to spam check/redeliver it to some other server?

This use case might be so much out of the scope of a all in one self hosted container solution?
But there should be a note (a big bold one) in the docs that fetchmail+k8s is not going to work ATM.

[polarathene]

NOTE: Nobody needs to read this comment and my next follow-up comment, they're verbose for reference purposes.

---

Reproducible with Docker Compose. There appears to be no ability to fake the hostname for that service without setting hostname in compose.yaml:

services:
  # Your DMS container with fetchmail enabled:
  dms-fetch:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    # Disabled for OVERRIDE_HOSTNAME reproduction:
    #hostname: mail.example.test
    environment:
      OVERRIDE_HOSTNAME: mail.example.test
      ENABLE_FETCHMAIL: 1
      # We change this setting to 10 for quicker testing:
      FETCHMAIL_POLL: 10
      # Additionally try to override the hostname this way:
      HOSTNAME: hello-dms.test
    # You'd normally use `volumes` here but for simplicity of the example, all config is contained within `compose.yaml`:
    configs:
      - source: dms-accounts-fetch
        target: /tmp/docker-mailserver/postfix-accounts.cf
      - source: fetchmail
        target: /tmp/docker-mailserver/fetchmail.cf
      # Use user-patches.sh to attempt configuring additional fake hostnames:
      - source: try-fake-hostnames
        target: /tmp/docker-mailserver/user-patches.sh
    # This is only for this example, since no real DNS service is configured, this is a Docker internal DNS feature:
    networks:
      default:
        aliases:
          - mail.example.test
          # This is needed to resolve `@example.test` as a postfix security check on the sender address:
          - example.test

  # This container represents your remote IMAP service that receives mail that fetchmail pulls from:
  dms-remote:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    #hostname: mail.remote.test
    environment:
      OVERRIDE_HOSTNAME: mail.remote.test
      # Allows for us send a test mail easily by trusting any mail client run within this container (`swaks`):
      PERMIT_DOCKER: container
    configs:
      - source: dms-accounts-remote
        target: /tmp/docker-mailserver/postfix-accounts.cf
    # Private DNS entries to resolve these queries to this container in the docker network:
    networks:
      default:
        aliases:
          - mail.remote.test
          # This would be needed if you don't specify `--server` to swaks, resolving the `--to` address for which MTA to deliver to:
          - remote.test

# Using the Docker Compose `configs.content` feature instead of volume mounting separate files.
# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
# https://github.com/compose-spec/compose-spec/pull/446
configs:
  fetchmail:
    content: |
      poll 'mail.remote.test' proto imap
        user 'jane.doe@remote.test'
        pass 'secret'
        is 'john.doe@example.test'
        no sslcertck

  # DMS requires an account to complete setup, configure one for each instance:
  # NOTE: Both accounts are configured with the same password (SHA512-CRYPT hashed), `secret`.
  dms-accounts-fetch:
    content: |
      john.doe@example.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  dms-accounts-remote:
    content: |
      jane.doe@remote.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  # A `user-patches.sh` script:
  try-fake-hostnames:
    content: |
      #!/bin/bash

      echo 'hello.test' > /etc/hostname
      echo 'world.test' > /etc/mailname

      # Replace the `hostname` command:
      mv /usr/bin/hostname /usr/bin/hostname.bak
      echo -e "#!/bin/bash\necho 'docker-mailserver.invalid'" >/usr/bin/hostname
      chmod +x /usr/bin/hostname

      # This will fail as `/etc/hosts` is an implicit bind mount, but you can edit it manually:
      # NOTE: The extra `$` is because this script is embedded into `compose.yaml`, `$$` is required to escape `$`.
      sed -i "s|$${HOSTNAME}|hello-world.test|" /etc/hosts

Sending mail

Send a mail from the swaks CLI within the dms-remote container for dms-fetch to later retrieve:

$ docker compose exec -it dms-remote swaks --server localhost --from someone@example.test --to jane.doe@remote.test --silent

<** 504 5.5.2 <42365d7ec29b>: Helo command rejected: need fully-qualified hostname
 -> QUIT
<-  221 2.0.0 Bye
=== Connection closed with remote host.

# Related failure logs:
$ docker compose logs dms-remote | grep 'someone@example.test'

policyd-spf[793]: : prepend X-Comment: SPF check N/A for local connections - client-ip=::1; helo=058cb200d2bd; envelope-from=someone@example.test; receiver=remote.test
postfix/smtpd[789]: NOQUEUE: reject: RCPT from localhost[::1]: 504 5.5.2 <058cb200d2bd>: Helo command rejected: need fully-qualified hostname; from=<someone@example.test> to=<jane.doe@remote.test> proto=ESMTP helo=<058cb200d2bd>

Like fetchmail, swaks will default the helo to the detected hostname of the container it's running in.

That is a similar error to fetchmail.. except swaks can fix it by changing the helo value to use via the --helo option:

# Append a `--helo`:
$ docker compose exec -it dms-remote swaks --server localhost --from someone@example.test --to jane.doe@remote.test --silent --helo mail.example.test

# Mail was not rejected this time:
$ docker compose logs dms-remote | grep 'someone@example.test'

policyd-spf[807]: : prepend X-Comment: SPF check N/A for local connections - client-ip=::1; helo=mail.example.test; envelope-from=someone@example.test; receiver=remote.test
postfix/qmgr[711]: 401EFE5C7C: from=<someone@example.test>, size=759, nrcpt=1 (queue active)
amavis[764]: (00764-01) Passed CLEAN {RelayedInbound}, [::1]:56796 <someone@example.test> -> <jane.doe@remote.test>, Queue-ID: 14F89E5C74, Message-ID: <20250527073909.000927@42365d7ec29b>, mail_id: 6pkDqfMRJSbO, Hits: -, size: 549, queued_as: 401EFE5C7C, 118 ms


# Related logs for successful receive + store:
$ docker compose logs dms-remote | grep 'jane.doe@remote.test'

postfix/smtp-amavis/smtp[937]: 14F89E5C74: to=<jane.doe@remote.test>, relay=127.0.0.1[127.0.0.1]:10024, delay=0.2, delays=0.07/0.01/0.01/0.12, dsn=2.0.0, status=sent (250 2.0.0 from MTA(smtp:[127.0.0.1]:10025): 250 2.0.0 Ok: queued as 401EFE5C7C)
dovecot: lmtp(jane.doe@remote.test)<940><l+iCEB1sNWisAwAA2SGYFA>: sieve: msgid=<20250527073909.000927@42365d7ec29b>: stored mail into mailbox 'INBOX'
postfix/lmtp[766]: 401EFE5C7C: to=<jane.doe@remote.test>, relay=mail.remote.test[/var/run/dovecot/lmtp], delay=0.03, delays=0/0/0.01/0.01, dsn=2.0.0, status=sent (250 2.0.0 <jane.doe@remote.test> l+iCEB1sNWisAwAA2SGYFA Saved)

Successful delivery to dms-remote, great, but fetchmail itself will still fail with only OVERRIDE_HOSTNAME instead of hostname. None of the attempts to fake the hostname worked.

It looks like env.c in the Fetchmail source is where this is checked via glibc call via their host_fqdn() function.

Thus it'll be via a kernel syscall I think?:

• https://linux.die.net/man/2/gethostname
• cat /proc/sys/kernel/hostname or uname -n both return the hostname configured in the container.
• As the /proc/sys/.. prefix would imply, you can query that via sysctl kernel.hostname too. Container runtime support for modifying such settings varies I think. Docker is rather limited (1 + 2), kernel.hostname is not one that is permitted to be set, even though it reflects the hostname of the namespaced container?

Will need to explore some alternative solutions..

---

Side-note

I'm not sure what to think about AI driven solutions ingesting our project and the considerable time I spend to thoroughly document/troubleshoot concerns like this publicly for the benefits of others 😅 (I do this a fair amount, not just the DMS repos)

Our OVERRIDE_HOSTNAME ENV has been interpreted as more generic for Docker / containers, rather than specific to DMS:

On the bright-side, at least the AI response is providing citations by linking to source material at least.

[polarathene]

3 workarounds for fetchmail when relying on the OVERRIDE_HOSTNAME ENV

TL;DR:

• PERMIT_DOCKER=container as a quick fix, should be reasonably safe to use.
• fetchmail.cf config options:
  • --smtphost to deliver direct to LMTP (via unix socket) since the fetchmail service in DMS is bundled into the same container as Dovecot.
  • --mda to delegate to a command for deliver instead of via SMTP. Likewise suitable for local usage, added advantage that we can filter through one of our anti-spam services before delivering to Dovecot.

Presently --mda will be a hassle, DMS will need to have someone contribute changes to make it more viable. PERMIT_DOCKER=container is the least amount of friction to go with if you are ok with trusting any process in the container.

Or as suggested earlier, just go with Getmail 😎

---

Relax security via PERMIT_DOCKER=container

The broader stroke "fix" is to lean into our PERMIT_DOCKER=container feature.

• Any local connection within the container would then be trusted, skipping security checks (the sender address having valid DNS wouldn't be required either, so the network alias example.test assigned to the dms-fetch container could be dropped too).
• In fact, if you set that ENV on the dms-fetch container, it'll likewise workaround the problem you encountered with the HELO check. Security wise, it might be acceptable, but I'd encourage considering the other workarounds I've documented here.

With PERMIT_DOCKER=container set on both DMS containers (add this to the previous compose.yaml snippet):

# Add PERMIT_DOCKER=container env:
services:
  dms-fetch:
    environment:
      # Allows for us send a test mail easily by trusting any mail client run within this container (`fetchmail`):
      PERMIT_DOCKER: container

  dms-remote:
    environment:
      # Allows for us send a test mail easily by trusting any mail client run within this container (`swaks`):
      PERMIT_DOCKER: container

$ docker compose up -d --force-recreate
$ docker compose exec -it dms-remote swaks --server localhost --from someone@example.test --to jane.doe@remote.test --silent

# dms-remote has the mail stored until fetchmail retrieves it for dms-fetch:
$ docker compose exec -it dms-remote doveadm mailbox status -u jane.doe@remote.test messages INBOX
INBOX messages=1
$ docker compose exec -it dms-fetch doveadm mailbox status -u john.doe@example.test messages INBOX
INBOX messages=0

# Once fetchmail is triggered at the polling interval (success, no helo failure):
$ docker compose exec -it dms-remote doveadm mailbox status -u jane.doe@remote.test messages INBOX
INBOX messages=0
$ docker compose exec -it dms-fetch doveadm mailbox status -u john.doe@example.test messages INBOX
INBOX messages=1

---

LMTP delivery (deliver direct to Dovecot instead of going through Postfix first)

Using the fetchmail config option smtphost / --smtphost (CLI option), we can give a regular SMTP hostname or a unix socket instead for LMTP. When this setting isn't configured, the default is localhost.

Preferring to deliver via LMTP should technically be ok - in fact going through SMTP is typically discouraged for fetchmail/getmail when they're delivering mail they've retrieved. Postfix internally will hand the mail off to Dovecot via LMTP.

NOTE: This will skip all security checks that Postfix would have normally done. That should be acceptable, given that we're trusting the internal fetchmail service itself, however it also means any anti-spam/virus checks are skipped too.

To do this, we just add to the fetchmailrc configuration (fetchmail.cf) this extra setting:

smtphost /var/run/dovecot/lmtp

That unix socket is defined in /etc/dovecot/conf.d/10-master.conf, where we have ownership and group of docker / 5000. Thus to avoid an error that will occur, the fetchmail user must also exist in the docker group, which we'll workaround for now via a user-patches.sh script (fix-fetchmail):

services:
  dms-fetch:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    #hostname: mail.example.test
    environment:
      OVERRIDE_HOSTNAME: mail.example.test
      ENABLE_FETCHMAIL: 1
      FETCHMAIL_POLL: 10
    configs:
      - source: dms-accounts-fetch
        target: /tmp/docker-mailserver/postfix-accounts.cf
      - source: fetchmail
        target: /tmp/docker-mailserver/fetchmail.cf
      # Add fetchmail to the postfix group for Dovecot LMTP socket access:
      - source: fix-fetchmail
        target: /tmp/docker-mailserver/user-patches.sh
    networks:
      default:
        aliases:
          - mail.example.test
          - example.test

  dms-remote:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    #hostname: mail.remote.test
    environment:
      OVERRIDE_HOSTNAME: mail.remote.test
      # Optional - Avoiding the need to override the HELO when using `swaks` CLI:
      PERMIT_DOCKER: container
    configs:
      - source: dms-accounts-remote
        target: /tmp/docker-mailserver/postfix-accounts.cf
    # Private DNS resolve these queries to this container in the docker network:
    networks:
      default:
        aliases:
          - mail.remote.test
          - remote.test

# Using the Docker Compose `configs.content` feature instead of volume mounting separate files.
# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
# https://github.com/compose-spec/compose-spec/pull/446
configs:
  fetchmail:
    content: |
      poll 'mail.remote.test' proto imap
        user 'jane.doe@remote.test'
        pass 'secret'
        is 'john.doe@example.test'
        no sslcertck
        smtphost /var/run/dovecot/lmtp

  # DMS requires an account to complete setup, configure one for each instance:
  # NOTE: Both accounts are configured with the same password (SHA512-CRYPT hashed), `secret`.
  dms-accounts-fetch:
    content: |
      john.doe@example.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  dms-accounts-remote:
    content: |
      jane.doe@remote.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  fix-fetchmail:
    content: |
      #!/bin/bash

      adduser fetchmail postfix

So that works, and removed the need for a PERMIT_DOCKER=container on our dms-fetch container 👍

$ docker compose up -d --force-recreate
$ docker compose exec -it dms-remote swaks --server localhost --from someone@example.test --to jane.doe@remote.test --silent

# dms-remote has the mail stored until fetchmail retrieves it for dms-fetch:
$ docker compose exec -it dms-remote doveadm mailbox status -u jane.doe@remote.test messages INBOX
INBOX messages=1
$ docker compose exec -it dms-fetch doveadm mailbox status -u john.doe@example.test messages INBOX
INBOX messages=0

# Once fetchmail is triggered at the polling interval (success, no helo failure):
$ docker compose exec -it dms-remote doveadm mailbox status -u jane.doe@remote.test messages INBOX
INBOX messages=0
$ docker compose exec -it dms-fetch doveadm mailbox status -u john.doe@example.test messages INBOX
INBOX messages=1

If you need to have a bit more flexibility, including spam checking, then the alternative fetchmail config setting --mda might be better.

Fetchmail config option --mda

--mda (or mda in fetchmailrc config) will allow you to deliver mail by delegating to a command to run instead. Useful if you want to also delegate via spamc or rspamc commands for spam filtering before handing to Dovecot for storing.

Config is the same as the LMTP example, except we replace smtphost /var/run/dovecot/lmtp for mda "/usr/lib/dovecot/deliver -d %T" where fetchmail will change %T to the recipient address. This command is roughly the same as delivering via LMTP AFAIK, just the CLI equivalent? There's also no need for the user-patches.sh script.

Compose config example

services:
  dms-fetch:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    #hostname: mail.example.test
    environment:
      OVERRIDE_HOSTNAME: mail.example.test
      ENABLE_FETCHMAIL: 1
      FETCHMAIL_POLL: 10
    configs:
      - source: dms-accounts-fetch
        target: /tmp/docker-mailserver/postfix-accounts.cf
      - source: fetchmail
        target: /tmp/docker-mailserver/fetchmail.cf
    networks:
      default:
        aliases:
          - mail.example.test
          - example.test

  dms-remote:
    image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
    #hostname: mail.remote.test
    environment:
      OVERRIDE_HOSTNAME: mail.remote.test
      # Optional - Avoiding the need to override the HELO when using `swaks` CLI:
      PERMIT_DOCKER: container
    configs:
      - source: dms-accounts-remote
        target: /tmp/docker-mailserver/postfix-accounts.cf
    # Private DNS resolve these queries to this container in the docker network:
    networks:
      default:
        aliases:
          - mail.remote.test
          - remote.test

# Using the Docker Compose `configs.content` feature instead of volume mounting separate files.
# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
# https://github.com/compose-spec/compose-spec/pull/446
configs:
  fetchmail:
    content: |
      poll 'mail.remote.test' proto imap
        user 'jane.doe@remote.test'
        pass 'secret'
        is 'john.doe@example.test'
        no sslcertck
        mda "/usr/lib/dovecot/deliver -d %T"

  # DMS requires an account to complete setup, configure one for each instance:
  # NOTE: Both accounts are configured with the same password (SHA512-CRYPT hashed), `secret`.
  dms-accounts-fetch:
    content: |
      john.doe@example.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

  dms-accounts-remote:
    content: |
      jane.doe@remote.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.

I don't think I've updated the Getmail docs yet with a WIP revision I had which demonstrates using rspamc / spamc for filtering spam, but it'd be roughly the same for fetchmail with --mda.

Full walkthrough (verbose, click to view)

Unlike the LMTP approach, this has quite a few hoops to jump through to get into a workin state. Documenting for reference.

$ docker compose up -d --force-recreate

# Send a mail to dms-remote for dms-fetch to retrieve and store in it's container:
docker compose exec -it dms-remote swaks --server localhost --from someone@example.test --to jane.doe@remote.test

# Once fetchmail polls 10s later, check the logs and we'll see error output:
docker compose logs dms-fetch

fetchmail[679]: 1 message for jane.doe@remote.test at mail.remote.test.
dovecot: auth: Error: client doesn't have lookup permissions for this user: userdb uid (5000) doesn't match peer uid (101) (to bypass this check, set: service auth { unix_listener /run/dovecot/auth-userdb { mode=0777 } })
dovecot: lda(john.doe@example.test)<797><>: Error: auth-master: userdb lookup(john.doe@example.test): Auth USER lookup failed
dovecot: lda(797): Fatal: Internal error occurred. Refer to server log for more information.
fetchmail[679]: reading message jane.doe@remote.test@mail.remote.test:1 of 1 (813 header octets) (28 body octets) (log message incomplete)
fetchmail[679]: MDA returned nonzero status 75
fetchmail[679]:  not flushed

/etc/dovecot/conf.d/10-master.conf must be edited to relax permissions (update mode):

service auth {
  # auth_socket_path points to this userdb socket by default. It's typically
  # used by dovecot-lda, doveadm, possibly imap process, etc. Users that have
  # full permissions to this socket are able to get a list of all usernames and
  # get the results of everyone's userdb lookups.
  #
  # The default 0666 mode allows anyone to connect to the socket, but the
  # userdb lookups will succeed only if the userdb returns an "uid" field that
  # matches the caller process's UID. Also if caller's uid or gid matches the
  # socket's uid or gid the lookup succeeds. Anything else causes a failure.
  #
  # To give the caller full permissions to lookup all users, set the mode to
  # something else than 0666 and Dovecot lets the kernel enforce the
  # permissions (e.g. 0777 allows everyone full permissions).
  unix_listener auth-userdb {
    mode = 0777
    user = docker
    group = docker
  }

Then we can run dovecot reload to have Dovecot respond to the update:

$ dovecot reload

# Confirm the changes are applied:
$ stat -c '%a' /var/run/dovecot/auth-userdb
777

Now we get the following failure about the group nogroup / 65534 not matching what was expected:

fetchmail[1884]: 1 message for jane.doe@remote.test at mail.remote.test.
dovecot: lda(john.doe@example.test)<1903><x1QWMuoONWhvBwAAEAQt/A>: Fatal: setgid(5000(docker) from userdb lookup) failed with euid=101(fetchmail), gid=65534(nogroup), egid=65534(nogroup): Operation not permitted (This binary should probably be called with process group set to 5000(docker) instead of 65534(nogroup))
fetchmail[1884]: reading message jane.doe@remote.test@mail.remote.test:1 of 1 (813 header octets) (28 body octets) (log message incomplete)
fetchmail[1884]: MDA returned nonzero status 75
fetchmail[1884]:  not flushed

We can resolve that:

# Replace the primary group of the `fetchmail` user to now be `docker` (5000):
# NOTE: `adduser docker fetchmail` would not work as the primary group is what needs to be matched
usermod -g docker fetchmail

# Restart the service so the fetchmail process now runs with the updated primary group:
supervisorctl restart fetchmail

Instead of a setgid error, we now get the same for setuid:

# ...
Fatal: setuid(5000(docker) from userdb lookup) failed with euid=101(fetchmail): Operation not permitted (This binary should probably be called with process user set to 5000(docker) instead of 101(fetchmail))

Dovecot is using setuid + setgid to switch based on /etc/dovecot/userdb entry (which has 5000:5000 set, aka docker:docker for UID/GID):

john.doe@example.test:{SHA512-CRYPT}$6$sbgFRCmQ.KWS5ryb$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.:5000:5000::/var/mail/example.test/john.doe/home::

So fetchmail service would need to run as docker:docker (the Dovecot vmail user/group in DMS). Assigning the supervisord service a user of docker would then use the docker primary group, but that'll fail, but so will running as root due to an owner mismatch for the config at /etc/failmailrc:

# Running fetchmail as root:
$ USER=fetchmail HOME="/var/lib/fetchmail" /usr/bin/fetchmail -f /etc/fetchmailrc --nodetach --nosyslog
fetchmail: WARNING: Running as root is discouraged.
File /etc/fetchmailrc must be owned by you.

# Fix and try again:
$ chown root /etc/fetchmailrc
$ USER=fetchmail HOME="/var/lib/fetchmail" /usr/bin/fetchmail -f /etc/fetchmailrc --nodetach --nosyslog
fetchmail: WARNING: Running as root is discouraged.
fetchmail: starting fetchmail 6.4.37 daemon
1 message for jane.doe@remote.test at mail.remote.test.
reading message jane.doe@remote.test@mail.remote.test:1 of 1 (813 header octets) (28 body octets) flushed
fetchmail: sleeping at Tue May 27 04:09:30 2025 for 300 seconds

$ chown docker /etc/fetchmailrc

# Run a process with different UID/GID, similar to what supervisor would do:
$ setpriv --reuid=docker --regid=docker --clear-groups -- bash -c 'USER=fetchmail HOME="/var/lib/fetchmail" /usr/bin/fetchmail -f /etc/fetchmailrc --nodetach --nosyslog'
fetchmail: lstat: /var/lib/fetchmail/.fetchids: Permission denied

# Fix that too, try again and it should work now:
$ chown docker /var/lib/fetchmail
$ setpriv --reuid=docker --regid=docker --clear-groups -- bash -c 'USER=fetchmail HOME="/var/lib/fetchmail" /usr/bin/fetchmail -f /etc/fetchmailrc --nodetach --nosyslog'
fetchmail: starting fetchmail 6.4.37 daemon
1 message for jane.doe@remote.test at mail.remote.test.
reading message jane.doe@remote.test@mail.remote.test:1 of 1 (813 header octets) (28 body octets) flushed
fetchmail: sleeping at Tue May 27 04:14:42 2025 for 300 seconds

# Change fetchmail service `user` to `docker`:
nano /etc/supervisor/conf.d/dms-services.conf

# Refresh the service config of supervisord so it runs the updated config:
supervisorctl update fetchmail
supervisorctl start fetchmail

One more permission issue to address:

fetchmail[9148]: fetchmail: lock creation failed, pidfile "/var/run/fetchmail/fetchmail.pid": Permission denied
dms-fetch-1  | 2025-05-27 04:18:53,253 WARN exited: fetchmail (exit status 8; not expected)

chown docker /var/run/fetchmail

Anyway... bulk of that can be skipped with a PR fix to DMS.

Reference

DMS container config files related content:

/etc/passwd:

fetchmail:x:101:65534::/var/lib/fetchmail:/bin/false

/etc/group:

nogroup:x:65534:

Our supervisord config dms-services.conf has these two service configs (/etc/supervisor/conf.d/dms-services.conf in the container):

• fetchmail
• getmail

Supervisor does support user switching via a user setting, but not one for changing the group/GID for the process/service:

As such the only way that's really going to work is for fetchmail to run as our vmail user/group (presently assigned as docker). Or like the referenced service Getmail that is similar in functionality, running it as root to leverage setuid/setgid.

From the official fetchmail docs for the --mda command:

If fetchmail is running as root, it sets its user id while delivering mail through an MDA as follows:

• First, the FETCHMAILUSER, LOGNAME, and USER environment variables are checked in this order. The value of the first variable from his list that is defined (even if it is empty!) is looked up in the system user database.
• If none of the variables is defined, fetchmail will use the real user id it was started with.
• If one of the variables was defined, but the user stated there is not found, fetchmail continues running as root, without checking remaining variables on the list.

Practically, this means that if you run fetchmail as root (not recommended), it is most useful to define the FETCHMAILUSER environment variable to set the user that the MDA should run as.

Some MDAs (such as maildrop) are designed to be setuid root and setuid to the recipient's user id, so you do not lose functionality this way even when running fetchmail as unprivileged user. Check the MDA's manual for details.

Our supervisor config for fetchmail has the following which sets USER and HOME as part of the user switch:

environment=HOME="/var/lib/fetchmail",USER="fetchmail"
command=/usr/bin/fetchmail -f /etc/fetchmailrc --nodetach --daemon "%(ENV_FETCHMAIL_POLL)s" -i /var/lib/fetchmail/.fetchmail-UIDL-cache --pidfile /var/run/fetchmail/fetchmail.pid

Fetchmail can take args here, or as settings it's referenced fetchmailrc file (these are documented as Keyword values after the equivalent CLI option). Additional syntax for fetchmailrc is documented here. I need to update our docs at some point to reference these 🤔