How do I solve email issues
Email is an essential feature for most foswiki installations. it's used for:
- Registration of new users
- Notification of topic changes
- Password reset
As of Foswiki 1.1.4, there is a new email test capability that can help resolve issues without access to the web server logs. Prior to version 1.1.4, most debugging efforts require access to the logs.
There are two methods that Foswiki can use to send email: It can call an email client like
sendmail
and have it do the word, or it can use Perl modules to communicate with the server directly.
In earlier versions of Foswiki, the selection of mail method was automatic, inferred from other configuration information
- If a MAILHOST was configured and
Net::SMTP
was available, then foswiki would use the perl module
- Otherwise it would default to calling the local program
sendmail
As of Foswiki 1.1.4, this is now an explicit configuration option. Although foswiki will fall back to the old decision logic, it is recommended to configure email explicitly.
Sending email using sendmail
With this method, foswiki will run an external program to originate email. The program can be configured however the default options are generally acceptable.
- This option does not work for Microsoft Windows servers. (there can be exceptions)
- While the called program is
sendmail
, it is often a wrapper for an agent supplied by the OS install.
- Specific debug options for
sendmail
will be different depending upon the installed email agent; Exim
, Postfix
, Sendmail
, SSMTP
and others.
- Error logs are typically external to foswiki.
Common sendmail
issues
If sendmail is on your local host, then any addresses from or to the local email domain must exist. Symptom of his problem is a "soft" failure when sending mail. If the problem is the
From:address, a failure is logged, but the mail is still sent.The error will be something like:
Error sending email SomeUser <someuser@somedomain.com> - ERROR: Exit code 4390912 (17152) from Foswiki::cfg{MailProgram} at ..path-to../lib/Foswiki/Net.pm line 493.
Note that on 1.1.5, the error will be
Error: Exit code 67 (17152)
. It is incorrectly reported on Foswiki 1.1.4 and earlier.
sendmail
debugging
- Modify the mailprogram to have the following options: [to be added]
Sending email using perl modules
With the perl modules, foswiki is making a direct connection to the smtp server and doesn't depend upon an external mail program.
Net::SMTP
debugging
Caution: If SMTP debugging is enabled and you are using email authentication, the userid/password exchange with the email server will be recorded in the log, and/or reported to the configure email test results. This can expose passwords. Never post the results of the email authentication exchange.
Enable the {SMTP}{Debug} option in configure (under "Mail and Proxies" -> "Email server", with "Expert options" shown). Running scripts such as
MailerContrib 's
mailnotify
from the command line will then produce verbose output to allow one to determine where mail sending is failing (e.g. at the SMTP authentication phase).
SELinux environments
Some distributions now install and configure
Security Enhanced Linux by default. When SELinux is in Enforcing mode, it can prevent the web server from sending email. Note that the below instructions may vary from distribution to distribution. It is preferable to consult with someone more familiar with the OS installation.
From some various sources found on the web, here are some notes that
might be helpful
- Temporarily disable selinux by issuing setenforce 0 and restart Apache.
- setsebool -P httpd_can_network_connect=1 will permit Apache to connect to make outgoing connections
- setsebool -P httpd_can_sendmail=1 will permit Apache to use sendmail
- On FC5: run "system-config-securitylevel"
- SELinux tab click "Modify SELinux policy",
- "HTTPD Service" check box next to "Allow HTTPD scripts and modules to connect to the network".
Other common issues
Email is inconsistent: some domains work, some fail. Or, emails don't appear to get sent at all.
Your SMTP provider might be blocking "relaying" from unauthenticated clients. Try configuring Foswiki to use SMTP Auth (Not applicable to
sendmail
)
My email provider doesn't allow unencrypted SMTP. (ex. Gmail)
- Ensure that the perl module
Net::SMTP::SSL
is installed
- Make sure your LocalSite.cfg is not world readable - This will expose your gmail account information!
- Set {SMTP}{MAILHOST} to
smtp.gmail.com:465
- Set {SMTP}{Username} to your gmail email address (
someuser@gmail.com
)
- Set {SMTP}{Password} to your gmail password
- Also, GMail has been known to mark Foswiki emails as spam - if emails are being sent to a GMail account, be sure to check that account's "Spam" folder.
Error: No SASL mechanism found
If the email fails with:
>>>> SMTP auth: Attempting authentication for someuser
>>>> FAILURE Sending e-mail to someuser@somehost.com - No SASL mechanism found
- Check earlier in the debug log for a line:
Net::SMTP=GLOB(0x........)<<< 250-AUTH ...
(some auth methods listed here)
- Verify that at least one of the methods is supported by Authen::SASL, for example
250-AUTH LOGIN PLAIN
- If your server reports
250-AUTH NTLM
for example, it requires a method not supported by default with Authen::SASL.
- There is an optional extension to add support for NTLM authentication:
- Install NTLMEmailAuthContrib. This adds a method to Authen::SASL which authenticates connections to Exchange servers that require NTLM authentication.
- It should provide support for NTLM Version 2 authentication. Older NTLM V1 might work. See the extension for more details.
- See CPAN:Authen::SASL::Perl for more details on supported methods.
Error: Use of uninitialized value $_...
Email fails with following errors:
<<< 250-AUTH LOGIN PLAIN XOAUTH
....
>>>> SMTP auth: Attempting authentication for someuser@gmail.com
>>>> FAILURE Sending e-mail to admin@mywiki.com - Use of uninitialized value $_ in pattern match (m//) at ...path../Net/Cmd.pm line 222.
-
- This one can be difficult to debug. This happens when the module
Authen::SASL
was unable to support the methods suggested by the email server. It returns an empty string, and Net::Cmd
fails.
- There is no one simple solution - here are some things to try:
- Verify that all dependencies are met for the perl modules.
- If you are using binary packages, be sure that they have been built for your architecture. (32 bit, 64 bit). There is a known issue with some ubuntu SASL packages. Try re-installing them using CPAN
-
Authen::SASL
comes with a pure perl version of the mechanism, and can also use some optional implementations: Authen::SASL::XS
or Authen::SASL:Cyrus
. If either the XS or Cyrus modules are installed, try removing them.
- Note that
Authen::SASL::XS
requires a connection to a Cyrus SASL server. This option is not supported by Foswiki.
Error: Default SSL_verify_mode deprecated
Email test fails with the following error:
>>>> FAILURE Sending e-mail to some@address -
*******************************************************************
Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
together with SSL_ca_file|SSL_ca_path for verification.
If you really don't want to verify the certificate and keep the
connection open to Man-In-The-Middle attacks please set
SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
*******************************************************************
This is an issue introduced in a version 1.79 of
CPAN:IO::Socket::SSL. In order to prevent "Man-In-The-Middle" attacks, it's important that a client verify the certificate presented by the server. The authors of
IO::Socket::SSL
have made this change to force a conscious decision to not verify the server's certificate rather than defaulting to an insecure solution. Unfortunately
Net::SMTP
and
Net::SMTP::SSL
don't support these options.
The following solutions are possible:
- Downgrade IO::Socket::SSL to 1.78
- OR Find and edit your local copy of Net::SMTP and insert an option:
...
LocalPort => $arg{LocalPort},
Proto => 'tcp',
SSL_verify_mode => 0, <======== INSERT THIS LINE
Timeout => defined $arg{Timeout}
? $arg{Timeout}
...
Step by Step - how to replace the buggy Authen::SASL on Ubuntu
This applies if you are using the Net::SMTP::SSL on Ubuntu and it fails even though everything appears to be set up correctly. This issue has been seen reported in various forums. The authentication modules appear to have been built for the wrong architecture. (32 bit v.s. 64 bit).
Follow these steps:
- Remove Ubuntu provided Authentication packages. We remove all the perl SASL stuff
- sudo apt-get remove libauthen-sasl-cyrus-perl libauthen-sasl-perl
- Install same manually using CPAN
- sudo cpan
- If this is first time you need to setup CPAN. Choose sudo and let it suggest a CPAN repository. Takes a few seconds.
- inside CPAN: install Authen::SASL
- quit
Now try the email setup again. With gmail the settings are
- {Email}{MailMethod} is set to Net::SMTP::SSL
- {MailProgram} is not used with Net::SMTP::SSL. Ignore it
- {SMTP}{MAILHOST} is set to smtp.gmail.com:465
- {SMTP}{SENDERHOST} is set to whatever is your domain name. Does not matter
- {SMTP}{Username} is set to your Google email login xxxxx@gmail.com
- {SMTP}{Password} is set to your Google mail password