mirror/kumomta
1
0
Fork 0
mirror of https://github.com/mailscope/kumomta.git synced 2026-08-19 10:58:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add troubleshooting page, add cross-reference from Tutorial, remove orphaned integration pages from Tutorial directory.

Browse Source
This commit is contained in:
Mike Hillyer
2023-10-19 22:22:33 -04:00
parent 141beb60f6
commit d433bea3f1
5 changed files with 78 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/generate-toc.py
+1
View File
@@ -221,6 +221,7 @@ TOC = [
children=[
Page("Starting KumoMTA", "userguide/operation/starting.md"),
Page("Getting Server Status", "userguide/operation/status.md"),
Page("Troubleshooting KumoMTA", "userguide/operation/troubleshooting.md,")
Page(
"Using the kcli Command-Line Client",
"userguide/operation/kcli.md",
docs/tutorial/installing_kumomta.md
+2
View File
@@ -166,3 +166,5 @@ sudo KUMOD_LOG=kumod=info /opt/kumomta/sbin/kumod --policy /opt/kumomta/etc/poli
```
If all goes well, it should return a PID and drop you back to a Linux prompt.
If KumoMTA does not start, refer to the [Troubleshooting Page](../userguide/operation/troubleshooting.md) of the User Guide.
docs/tutorial/integrate_ongage.md
-53
View File
@@ -1,53 +0,0 @@
# Ongage SMTP integration
## Get KumoMTA
1. Install KumoMTA as per the installation instructions here
https://docs.kumomta.com/userguide/installation/overview/
Before finishing this step, you should ensure that you have correctly set up DNS with a resolving sending domain, MX, PTR, SPF, DKIM, etc.
As part of this process, you will be creating a DNS entry for “bounce.<yoursendingdomain>”, as well as similar tracking and image domains so be prepared to edit your DNS.
2. Ensure that you are able to inject mail using SMTP_Auth with TLS
https://docs.kumomta.com/userguide/operation/smtpinjection/?h=smtp_auth
NOTE: TLS is crucial to this process, so have a valid and tested certificate attached to your listener config. https://docs.kumomta.com/reference/kumo/start_esmtp_listener/#tls_certificate
## Get Ongage
3. Go to Ongage.com and create an account https://www.ongage.com/registration
4. Create a support ticket to request access to use the “Private SMTP” connector and let them know you are using KumoMTA as the sending MTA.
Here is some essential reading before you set up the Private SMTP connector:
https://ongage.atlassian.net/wiki/spaces/HELP/pages/657817611/The+Ongage+Private+SMTP+Connector
5. Once registered, you can add a vendor by selecting Vendors > My Connections in the left menu
6. Create a new connection and add “Private SMTP” as the connection type.
NOTE: If you do not see this as an option, jump back up to step 4 and ask Ongage Support to add it for you.
7. Fill in all the required fields and test.
* you can choose any username and password you like, KumoMTA has no preset or preference.
* Select PLAIN authentication Type
* Select YES for “Use TLS”
* The SMTP Port should match what your listener is listening on. Remember to update your public firewall too.
If you have done everything right, you will see a positive notification that credentials were verified.
8. Pat yourself on the back then start using Ongage with KumoMTA
docs/tutorial/integrations.md
-7
View File
@@ -1,7 +0,0 @@
# Approved Integrations
## Hashicorp Vault
## Ongage
docs/userguide/operation/troubleshooting.md
+75
View File
@@ -0,0 +1,75 @@
# Troubleshooting KumoMTA
There are several things that can go wrong, especially when first installing KumoMTA. This page is intended to help with troubleshooting common issues.
!!!Note
There is a community Discord server available at https://kumomta.com/discord where you can ask for community assistance.
## Reviewing the System Journal
KumoMTA logs to the system journal for all error and status messages during operation, to view the log entries use journalctl:
```console
[root@localhost ~]# journalctl -f -n 50 -u kumomta.service
Oct 19 21:52:59 localhost systemd[1]: Started KumoMTA SMTP service.
Oct 19 21:53:00 localhost.localdomain kumod[902]: 2023-10-20T01:53:00.328546Z INFO localset-0 kumod: NodeId is 2a32fb9b-7353-48bd-a06e-cc97e224c924
Oct 19 21:53:00 localhost.localdomain kumod[902]: 2023-10-20T01:53:00.337267Z INFO localset-0 kumo_server_common::http_server: http listener on 127.0.0.1:8000
Oct 19 21:53:00 localhost.localdomain kumod[902]: 2023-10-20T01:53:00.348273Z INFO localset-0 kumod::smtp_server: smtp listener on 0.0.0.0:25
Oct 19 21:53:01 localhost.localdomain kumod[902]: 2023-10-20T01:53:01.221127Z INFO localset-0 kumod::spool: start_spool: enumeration done, spooled in 2 msgs over 117.40671ms
Oct 19 21:53:01 localhost.localdomain kumod[902]: 2023-10-20T01:53:01.221509Z INFO localset-0 kumo_server_common::start: initialization complete
```
In this example the **-f** option tells journalctl to follow the log, in other words to tail or continuously read the file, the **-n 50** option tells journalctl to start by reading the previous 50 lines, and the **-u** option tells journalctl to filter by a specific unit, in this case the *kumomta.service* unit.
A common issue with new installs is ownership of the spool directory. When the spool is provisioned as a separate volume, it will not be owned by the **kumod** user. In this example we change ownership of the */var/spool/kumomta* directory, then attempt to start the kumomta service, then read the system journal to identify the issue:
```console
[root@localhost spool]# systemctl stop kumomta
[root@localhost spool]# chown -R root /var/spool/kumomta/
[root@localhost spool]# systemctl start kumomta
[root@localhost spool]# journalctl -f -n 50 -u kumomta.service
Oct 19 22:09:06 localhost.localdomain systemd[1]: Started KumoMTA SMTP service.
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.752782Z INFO localset-0 kumod: NodeId is 2a32fb9b-7353-48bd-a06e-cc97e224c924
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.755699Z INFO localset-0 kumo_server_common::http_server: http listener on 127.0.0.1:8000
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.756982Z INFO localset-0 kumod::smtp_server: smtp listener on 0.0.0.0:25
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.757415Z ERROR localset-0 kumod::spool: Error in spool: Opening spool data: opening pid file /var/spool/kumomta/data/lock: Permission denied (os error 13)
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.758039Z ERROR localset-0 kumod::spool: Error in spool: Opening spool meta: opening pid file /var/spool/kumomta/meta/lock: Permission denied (os error 13)
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.758363Z INFO localset-0 kumod::smtp_server: smtp listener on 0.0.0.0:25 -> stopping
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.758051Z INFO main kumo_server_common::start: Shutdown completed OK!
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.772671Z ERROR localset-0 kumo_server_common::start: problem initializing: No spools have been defined
Oct 19 22:09:06 localhost.localdomain kumod[5356]: 2023-10-20T02:09:06.772827Z INFO localset-0 kumo_server_common::start: initialization complete
Oct 19 22:09:06 localhost.localdomain kumod[5356]: Error: Initialization raised an error
Oct 19 22:09:06 localhost.localdomain systemd[1]: kumomta.service: Main process exited, code=exited, status=1/FAILURE
Oct 19 22:09:06 localhost.localdomain systemd[1]: kumomta.service: Failed with result 'exit-code'.
Oct 19 22:09:07 localhost.localdomain systemd[1]: Failed to start KumoMTA SMTP service.
```
This error message makes it clear that there was an issue with permissions on the spool folder that prevented the kumomta service from starting.
## Starting KumoMTA in the Foreground
When there are issues with starting KumoMTA that are not exposed through the system journal, an additional troubleshooting step is starting KumoMTA in the foreground with extended error reporting.
To run KumoMTA in the foreground with additional error logging use the following command:
```console
sudo KUMOD_LOG=kumod=debug /opt/kumomta/sbin/kumod --policy /opt/kumomta/etc/policy/init.lua --user kumod
```
This will produce output similar to the following:
```console
[root@localhost spool]# sudo KUMOD_LOG=kumod=debug /opt/kumomta/sbin/kumod --policy /opt/kumomta/etc/policy/init.lua --user kumod
2023-10-20T02:15:00.481840Z INFO localset-0 kumod: NodeId is 2a32fb9b-7353-48bd-a06e-cc97e224c924
2023-10-20T02:15:00.485934Z INFO localset-0 kumod::smtp_server: smtp listener on 0.0.0.0:25
2023-10-20T02:15:00.486788Z DEBUG localset-0 kumod::spool: Defining local disk spool 'data' on /var/spool/kumomta/data
2023-10-20T02:15:00.487283Z ERROR localset-0 kumod::spool: Error in spool: Opening spool data: opening pid file /var/spool/kumomta/data/lock: Permission denied (os error 13)
2023-10-20T02:15:00.488043Z DEBUG localset-0 kumod::spool: Defining local disk spool 'meta' on /var/spool/kumomta/meta
2023-10-20T02:15:00.488177Z ERROR localset-0 kumod::spool: Error in spool: Opening spool meta: opening pid file /var/spool/kumomta/meta/lock: Permission denied (os error 13)
2023-10-20T02:15:00.488552Z INFO localset-0 kumod::smtp_server: smtp listener on 0.0.0.0:25 -> stopping
2023-10-20T02:15:00.514056Z DEBUG logger kumod::logging: started logger thread
2023-10-20T02:15:00.515102Z DEBUG logger kumod::logging: calling state.logger_thread()
Error: Initialization raised an error
```
One again we have a clear indication that there is an issue with permissions on the spool directory.