mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2024-01-19 02:48:50 +00:00
docs: Add compatibility section to debugging page (#3404)
docs: Add compatibility section to debugging page ci: Adjust bug report template Reduce some text + compress the preliminary checks down to single check item.
This commit is contained in:
Brennan Kinney
GitHub
parent
68c6f247a6
commit
a276589e40
21
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
21
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
|
|
@ -10,20 +10,10 @@ body:
|
|||
id: preliminary-checks
|
||||
attributes:
|
||||
label: 📝 Preliminary Checks
|
||||
description: Please read these carefully.
|
||||
description: |
|
||||
By submitting this issue, you agree to our [Code of Conduct](https://github.com/docker-mailserver/docker-mailserver/blob/master/CODE_OF_CONDUCT.md).
|
||||
options:
|
||||
- label: I checked that all ports are open and not blocked by my ISP / hosting provider.
|
||||
required: true
|
||||
- label: I know that SSL errors are likely the result of a wrong setup on the user side and not caused by DMS itself. I'm confident my setup is correct.
|
||||
required: true
|
||||
- label: I searched the issue tracker but was unable to find my issue.
|
||||
required: true
|
||||
- label: |
|
||||
I have read:
|
||||
- The [extended documentation in general](https://docker-mailserver.github.io/docker-mailserver/latest/) but found nothing to resolve the issue;
|
||||
- The [documentation on debugging](https://docker-mailserver.github.io/docker-mailserver/latest/config/debugging/), tried the proposed steps to debug the problem, but was still unable to resolve the issue;
|
||||
- This project's [Code of Conduct](https://github.com/docker-mailserver/docker-mailserver/blob/master/CODE_OF_CONDUCT.md) and I agree;
|
||||
- The [documentation about filing a bug report](https://docker-mailserver.github.io/docker-mailserver/latest/contributing/issues-and-pull-requests/#filing-a-bug-report).
|
||||
- label: I tried searching for an existing issue and followed the [debugging docs](https://docker-mailserver.github.io/docker-mailserver/latest/config/debugging/) advice, but still need assistance.
|
||||
required: true
|
||||
- type: textarea
|
||||
id: what-happened
|
||||
|
|
@ -64,10 +54,9 @@ body:
|
|||
attributes:
|
||||
label: ⚙️ Container configuration files
|
||||
description: |
|
||||
Show us the file that you use to run DMS (and possibly other related services).
|
||||
Show us the `compose.yaml` file or command that you used to run DMS (and possibly other related services).
|
||||
- This field is formatted as YAML.
|
||||
- This is most likely your `compose.yaml` file, but you can also show us your equivalent `docker run` command, if applicable.
|
||||
- If you are using Kubernetes, you can also put your manifest files here.
|
||||
- If you are using Kubernetes, you can alternatively share your manifest files here.
|
||||
render: yml
|
||||
- type: textarea
|
||||
id: relevant-log-output
|
||||
|
|
|
|||
|
|
@ -10,7 +10,10 @@ This page contains valuable information when it comes to resolving issues you en
|
|||
|
||||
Please consider contributing solutions to the [FAQ][docs-faq] :heart:
|
||||
|
||||
## Preliminary Information
|
||||
## Preliminary Checks
|
||||
|
||||
- Check that all published DMS ports are actually open and not blocked by your ISP / hosting provider.
|
||||
- SSL errors are likely the result of a wrong setup on the user side and not caused by DMS itself.
|
||||
|
||||
### Mail sent from DMS does not arrive at destination
|
||||
|
||||
|
|
@ -25,7 +28,7 @@ These links may advise how the provider can unblock the port through additional
|
|||
## Steps for Debugging DMS
|
||||
|
||||
1. **Increase log verbosity**: Very helpful for troubleshooting problems during container startup. Set the environment variable [`LOG_LEVEL`][docs-environment-log-level] to `debug` or `trace`.
|
||||
2. **Use error logs as a search query**: Try finding an _existing issue_ or _search engine result_ from any errors in your container log output. Often you'll find answers or more insights. If you still need to open an issue, sharing links from your search may help us assist you. The mail server log can be acquired by running `docker log <CONTAINER NAME>` (_or `docker logs -f <CONTAINER NAME>` if you want to follow the log_).
|
||||
2. **Use error logs as a search query**: Try [finding an _existing issue_][gh-issues] or _search engine result_ from any errors in your container log output. Often you'll find answers or more insights. If you still need to open an issue, sharing links from your search may help us assist you. The mail server log can be acquired by running `docker log <CONTAINER NAME>` (_or `docker logs -f <CONTAINER NAME>` if you want to follow the log_).
|
||||
3. **Understand the basics of mail servers**: Especially for beginners, make sure you read our [Introduction][docs-introduction] and [Usage][docs-usage] articles.
|
||||
4. **Search the whole FAQ**: Our [FAQ][docs-faq] contains answers for common problems. Make sure you go through the list.
|
||||
5. **Reduce the scope**: Ensure that you can run a basic setup of DMS first. Then incrementally restore parts of your original configuration until the problem is reproduced again. If you're new to DMS, it is common to find the cause is misunderstanding how to configure a minimal setup.
|
||||
|
|
@ -38,11 +41,45 @@ If you need more flexibility than `docker logs` offers, within the container `/v
|
|||
|
||||
To install additional software:
|
||||
|
||||
- `apt-get update` is needed to update repository metadata.
|
||||
- `apt-get install <PACKAGE>`
|
||||
- For example if you need a text editor, `nano` is a good package choice for beginners.
|
||||
1. `apt-get update` to update repository metadata.
|
||||
2. `apt-get install <PACKAGE>`
|
||||
|
||||
For example a text editor you can use in the terminal: `apt-get install nano`
|
||||
|
||||
## Compatibility
|
||||
|
||||
It's possible that the issue you're experiencing is due to a compatibility conflict.
|
||||
|
||||
This could be from outdated software updates, or running a system that isn't able to provide you newer software and kernels. You may want to verify if you can reproduce the issue on a system that is not affected by these concerns.
|
||||
|
||||
### Network
|
||||
|
||||
- **`userland-proxy`:** Prior to Docker `v23`, [changing the `userland-proxy` setting did not reliably remove NAT rules][network::docker-userlandproxy].
|
||||
- **UFW / firewalld:** Some users expect only their firewall frontend to manage the firewall rules, but these will be bypassed when Docker publishes a container port as there is no integration between the two.
|
||||
- **`iptables` / `nftables`:**
|
||||
- Docker [only manages the NAT rules via `iptables`][network::docker-nftables], relying on compatibility shims for supporting the successor `nftables`. Internally DMS expects `nftables` support on the host kernel for services like Fail2Ban to function correctly.
|
||||
- [Kernels older than 5.2 may affect management of NAT rules via `nftables`][network::kernel-nftables]. Other software outside of DMS may also manipulate these rules, such as firewall frontends.
|
||||
- **IPv6:**
|
||||
- Requires [additional configuration][docs-ipv6] to prevent or properly support IPv6 connections (eg: Preservering the Client IP).
|
||||
- Support in 2023 is still considered experimental. You are advised to use at least Docker Engine `v23` (2023Q1).
|
||||
- Various networking bug fixes have been addressed since the intitial IPv6 support arrived in Docker Engine `v20.10.0` (2020Q4).
|
||||
|
||||
### System
|
||||
|
||||
- **Kernel:** Some systems provide [kernels with modifications (_replacing defaults and backporting patches_)][network::kernels-modified] to support running legacy software or kernels, complicating compatibility. This can be commonly experienced with products like NAS.
|
||||
- **CGroups v2:** Hosts running older kernels (prior to 5.2) and systemd (prior to v244) are not likely to leverage cgroup v2, or have not defaulted to the cgroup v2 `unified` hierarchy. Not meeting this baseline may influence the behaviour of your DMS container, even with the latest Docker Engine installed.
|
||||
- **Rootless containers** have additional constraints that vary by container runtime (_Docker, Podman, etc - which already have subtle differences_).
|
||||
- This can introduce differences such as for container networking which may further impact support for IPv6 and preserving the client IP (Remote address).
|
||||
- cgroup v2 is required for supporting rootless containers.
|
||||
|
||||
[network::docker-userlandproxy]: https://github.com/moby/moby/issues/44721
|
||||
[network::docker-nftables]: https://github.com/moby/moby/issues/26824
|
||||
[network::kernels-modified]: https://github.com/docker-mailserver/docker-mailserver/pull/2662#issuecomment-1168435970
|
||||
[network::kernel-nftables]: https://unix.stackexchange.com/questions/596493/can-nftables-and-iptables-ip6tables-rules-be-applied-at-the-same-time-if-so-wh/596497#596497
|
||||
|
||||
[docs-faq]: ../faq.md
|
||||
[docs-environment-log-level]: ./environment.md#log_level
|
||||
[docs-ipv6]: ./advanced/ipv6.md
|
||||
[docs-introduction]: ../introduction.md
|
||||
[docs-usage]: ../usage.md
|
||||
[gh-issues]: https://github.com/docker-mailserver/docker-mailserver/issues
|
||||
|
|
|
|||
Loading…
Reference in a new issue