From d433bea3f144d04591c487d4715bfc3436b681da Mon Sep 17 00:00:00 2001 From: Mike Hillyer Date: Thu, 19 Oct 2023 22:22:33 -0400 Subject: [PATCH] Add troubleshooting page, add cross-reference from Tutorial, remove orphaned integration pages from Tutorial directory. --- docs/generate-toc.py | 1 + docs/tutorial/installing_kumomta.md | 2 + docs/tutorial/integrate_ongage.md | 53 --------------- docs/tutorial/integrations.md | 7 -- docs/userguide/operation/troubleshooting.md | 75 +++++++++++++++++++++ 5 files changed, 78 insertions(+), 60 deletions(-) delete mode 100644 docs/tutorial/integrate_ongage.md delete mode 100644 docs/tutorial/integrations.md create mode 100644 docs/userguide/operation/troubleshooting.md diff --git a/docs/generate-toc.py b/docs/generate-toc.py index 30041071..de5b2a6e 100755 --- a/docs/generate-toc.py +++ b/docs/generate-toc.py @@ -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", diff --git a/docs/tutorial/installing_kumomta.md b/docs/tutorial/installing_kumomta.md index b37ebfcb..56b91f8b 100644 --- a/docs/tutorial/installing_kumomta.md +++ b/docs/tutorial/installing_kumomta.md @@ -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. diff --git a/docs/tutorial/integrate_ongage.md b/docs/tutorial/integrate_ongage.md deleted file mode 100644 index 3d23f252..00000000 --- a/docs/tutorial/integrate_ongage.md +++ /dev/null @@ -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.”, 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 - - - diff --git a/docs/tutorial/integrations.md b/docs/tutorial/integrations.md deleted file mode 100644 index 110ad6df..00000000 --- a/docs/tutorial/integrations.md +++ /dev/null @@ -1,7 +0,0 @@ -# Approved Integrations - -## Hashicorp Vault - -## Ongage - - diff --git a/docs/userguide/operation/troubleshooting.md b/docs/userguide/operation/troubleshooting.md new file mode 100644 index 00000000..9e06cfc4 --- /dev/null +++ b/docs/userguide/operation/troubleshooting.md @@ -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.