From 979f0ff03dafaed496609b46d17230b3405b5db2 Mon Sep 17 00:00:00 2001 From: j-ed Date: Wed, 23 Jan 2013 10:59:05 -0800 Subject: [PATCH 1/3] Create configuration_mail.rst A first try to document how the mail parameters need to be set. --- admin_manual/configuration_mail.rst | 203 ++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 admin_manual/configuration_mail.rst diff --git a/admin_manual/configuration_mail.rst b/admin_manual/configuration_mail.rst new file mode 100644 index 000000000..ea1db2002 --- /dev/null +++ b/admin_manual/configuration_mail.rst @@ -0,0 +1,203 @@ +Mail configuration +================== + +ownCloud does not contain a full email program but contains some parameters to +allow to send e.g. password reset email to the users. This function relies on +the PHPMailer library (``http://sourceforge.net/projects/phpmailer/``). To +take advantage of this function it needs to be configured properly. + + +Requirements +------------ + +Different requirements need to be matched, depending on the environment which +you are using and the way how you want to send email. You can choose between +SMTP, PHP mail, Sendmail and qmail. + +Parameters +---------- + +* SMTP (Simple Mail Tranfer Protocol) + + If you want to send email using a local or remote SMTP server it is necessary + to enter the name or ip address of the server, optionally followed by a collon + separated port number, e.g. ``:425``. If this value is not given the default + port 25/tcp will be used unless you will change that by modifying the + ``mail_smtpport`` parameter. Multiple server can be entered separated by + semicolon. + + "mail_smtpmode" => "smtp", + "mail_smtphost" => "smtp-1.server.dom;smtp-2.server.dom:425", + "mail_smtpport" => 25, + + or + + "mail_smtpmode" => "smtp", + "mail_smtphost" => "smtp.server.dom", + "mail_smtpport" => 425, + + If a malware or SPAM scanner is running on the SMTP server it might be + necessary that you increase the SMTP timeout to e.g. 30s. + + "mail_smtptimeout" => 30, + + If the SMTP server accepts unsecure connections, the default setting can be + used: + + "mail_smtpsecure" => '', + + If the SMTP server only accepts secure connections you can choose between the + following two variants: + + :ssl - + A secure connection will be initiated using the outdated SMTPS protocol + which uses the port 465/tcp. + + "mail_smtphost" => "smtp.server.dom:465", + "mail_smtpsecure" => 'ssl', + + :tls - + A secure connection will be initiated using the STARTTLS protocol which + uses the default port 25/tcp. + + "mail_smtphost" => "smtp.server.dom", + "mail_smtpsecure" => 'tls', + + And finally it is necessary to configure if the SMTP server requires + authentication. If not, the default values can be taken as it: + + "mail_smtpauth" => false, + "mail_smtpname" => "", + "mail_smtppassword" => "", + + If SMTP authentication is required the configuration may be changed as + followed: + + "mail_smtpauth" => true, + "mail_smtpname" => "username", + "mail_smtppassword" => "password", + +* PHP mail + + If you want to use PHP mail it is necessary to have an installed and working + email system on your server. Which program in detail is used to send email is + defined by the configuration settings in the ``php.ini`` file. (On *nix + systems this will most likely be Sendmail.) ownCloud should be able to send + email out of the box. + + "mail_smtpmode" => "php", + "mail_smtphost" => "127.0.0.1", + "mail_smtpport" => 25, + "mail_smtptimeout" => 10, + "mail_smtpsecure" => "", + "mail_smtpauth" => false, + "mail_smtpname" => "", + "mail_smtppassword" => "", + +* Sendmail + + If you want to use the well known Sendmail program to send email, it is + necessary to have an installed and working email system on your *nix server. + The sendmail binary (``/usr/sbin/sendmail``) is ususally part of that system. + ownCloud should be able to send email out of the box. + + "mail_smtpmode" => "sendmail", + "mail_smtphost" => "127.0.0.1", + "mail_smtpport" => 25, + "mail_smtptimeout" => 10, + "mail_smtpsecure" => "", + "mail_smtpauth" => false, + "mail_smtpname" => "", + "mail_smtppassword" => "", + +* qmail (http://www.qmail.org/) + + If you want to use the qmail program to send email, it is necessary to have an + installed and working qmail email system on your server. The sendmail binary + (``/var/qmail/bin/sendmail``) will then be used to send email. ownCloud should + be able to send email out of the box. + + "mail_smtpmode" => "qmail", + "mail_smtphost" => "127.0.0.1", + "mail_smtpport" => 25, + "mail_smtptimeout" => 10, + "mail_smtpsecure" => "", + "mail_smtpauth" => false, + "mail_smtpname" => "", + "mail_smtppassword" => "", + +Send a test email +----------------- + +The only way to test your email configuration is, to force a login failure, +because a function to send a test email hasn't be implemented yet. +First make sure that you are using a full qualified domain and not an ip address +in the ownCloud URL, like ``http://my-owncloud-server.domain.dom/owncloud/``. +The password reset function reads the domain name from that URL to build the +email sender address, e.g. ``john@domain.dom``. +Next you need to enter your login and an *invalid* password. As soon as you +press the login button the login mask reappears and a ``I’ve forgotten my password`` +link will be shown above the login field. Click on that link, re-enter your login +and press the ``Reset password`` button - that's all. + +Trouble shooting +---------------- + +1. How can I find out if a SMTP server is reachable? + + Use the ping command to check the server availability: + + # ping smtp.server.dom + PING smtp.server.dom (ip-address) 56(84) bytes of data. + 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=1 ttl=64 time=3.64 ms + 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=2 ttl=64 time=0.055 ms + 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=3 ttl=64 time=0.062 ms + +2. How can I find out if the SMTP server is listening on a specific tcp port? + + A SMTP server is usually listening on port ``25/tcp`` (smtp) and/or in + rare circumstances is also listening on the outdated port ``465/tcp`` (smtps). + You can use the telnet command to check if a port is available: + + # telnet smtp.domain.dom 25 + Trying 192.168.1.10... + Connected to smtp.domain.dom. + Escape character is '^]'. + 220 smtp.domain.dom ESMTP Exim 4.80.1 Tue, 22 Jan 2013 22:28:14 +0100 + +3. How can I find out if a SMTP server supports the outdated SMTPS protocol? + + A good indication that a SMTP server supports the SMTPS protocol is that it + is listening on port ``465/tcp``. How this can be checked has been described + previously. + +4. How can I find out if a SMTP server supports the TLS protocol? + + A SMTP server usually announces the availability of STARTTLS right after a + connection has been established. This can easily been checked with the telnet + command. You need to enter the marked lines to get the information displayed: + + # telnet smtp.domain.dom 25 + Trying 192.168.1.10... + Connected to smtp.domain.dom. + Escape character is '^]'. + 220 smtp.domain.dom ESMTP Exim 4.80.1 Tue, 22 Jan 2013 22:39:55 +0100 + *EHLO your-server.local.lan* + 250-smtp.domain.dom Hello your-server.local.lan [ip-address] + 250-SIZE 52428800 + 250-8BITMIME + 250-PIPELINING + 250-AUTH PLAIN LOGIN CRAM-MD5 + **250-STARTTLS** + 250 HELP + *QUIT* + 221 smtp.domain.dom closing connection + Connection closed by foreign host. + +5. If you are still not able to send email it might be useful to activate + further debug messages by setting the following parameter. Right after + you have pressed the ``Reset password`` button, as described beforem a lot + ``SMTP -> get_lines(): ...`` messages will then be written on the screen. + + "mail_smtpdebug" => true; + From 3d810c4a64ffbb6d7b5ebbf8650aeffb06efea2b Mon Sep 17 00:00:00 2001 From: j-ed Date: Wed, 23 Jan 2013 20:25:30 +0100 Subject: [PATCH 2/3] Update admin_manual/configuration_mail.rst --- admin_manual/configuration_mail.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/admin_manual/configuration_mail.rst b/admin_manual/configuration_mail.rst index ea1db2002..6843408ba 100644 --- a/admin_manual/configuration_mail.rst +++ b/admin_manual/configuration_mail.rst @@ -1,4 +1,4 @@ -Mail configuration +Mail Configuration ================== ownCloud does not contain a full email program but contains some parameters to @@ -17,10 +17,10 @@ SMTP, PHP mail, Sendmail and qmail. Parameters ---------- -* SMTP (Simple Mail Tranfer Protocol) +* **SMTP (Simple Mail Tranfer Protocol)** If you want to send email using a local or remote SMTP server it is necessary - to enter the name or ip address of the server, optionally followed by a collon + to enter the name or ip address of the server, optionally followed by a colon separated port number, e.g. ``:425``. If this value is not given the default port 25/tcp will be used unless you will change that by modifying the ``mail_smtpport`` parameter. Multiple server can be entered separated by @@ -49,16 +49,14 @@ Parameters If the SMTP server only accepts secure connections you can choose between the following two variants: - :ssl - - A secure connection will be initiated using the outdated SMTPS protocol - which uses the port 465/tcp. + ssl: A secure connection will be initiated using the outdated SMTPS protocol + which uses the port 465/tcp. "mail_smtphost" => "smtp.server.dom:465", "mail_smtpsecure" => 'ssl', - :tls - - A secure connection will be initiated using the STARTTLS protocol which - uses the default port 25/tcp. + tls - A secure connection will be initiated using the STARTTLS protocol which + uses the default port 25/tcp. "mail_smtphost" => "smtp.server.dom", "mail_smtpsecure" => 'tls', @@ -77,7 +75,7 @@ Parameters "mail_smtpname" => "username", "mail_smtppassword" => "password", -* PHP mail +* **PHP mail** If you want to use PHP mail it is necessary to have an installed and working email system on your server. Which program in detail is used to send email is @@ -94,7 +92,7 @@ Parameters "mail_smtpname" => "", "mail_smtppassword" => "", -* Sendmail +* **Sendmail** If you want to use the well known Sendmail program to send email, it is necessary to have an installed and working email system on your *nix server. @@ -110,7 +108,7 @@ Parameters "mail_smtpname" => "", "mail_smtppassword" => "", -* qmail (http://www.qmail.org/) +* **qmail (http://www.qmail.org/)** If you want to use the qmail program to send email, it is necessary to have an installed and working qmail email system on your server. The sendmail binary @@ -126,7 +124,7 @@ Parameters "mail_smtpname" => "", "mail_smtppassword" => "", -Send a test email +Send a Test Email ----------------- The only way to test your email configuration is, to force a login failure, From 93e5c2e89df300442a61ddbdcd301be562213725 Mon Sep 17 00:00:00 2001 From: j-ed Date: Wed, 23 Jan 2013 20:55:34 +0100 Subject: [PATCH 3/3] Update admin_manual/configuration_mail.rst --- admin_manual/configuration_mail.rst | 67 +++++++++++++++++++---------- 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/admin_manual/configuration_mail.rst b/admin_manual/configuration_mail.rst index 6843408ba..108cdd788 100644 --- a/admin_manual/configuration_mail.rst +++ b/admin_manual/configuration_mail.rst @@ -25,6 +25,7 @@ Parameters port 25/tcp will be used unless you will change that by modifying the ``mail_smtpport`` parameter. Multiple server can be entered separated by semicolon. + :: "mail_smtpmode" => "smtp", "mail_smtphost" => "smtp-1.server.dom;smtp-2.server.dom:425", @@ -32,37 +33,45 @@ Parameters or + :: + "mail_smtpmode" => "smtp", "mail_smtphost" => "smtp.server.dom", "mail_smtpport" => 425, If a malware or SPAM scanner is running on the SMTP server it might be necessary that you increase the SMTP timeout to e.g. 30s. + :: "mail_smtptimeout" => 30, If the SMTP server accepts unsecure connections, the default setting can be used: + :: "mail_smtpsecure" => '', - If the SMTP server only accepts secure connections you can choose between the - following two variants: - - ssl: A secure connection will be initiated using the outdated SMTPS protocol - which uses the port 465/tcp. + If the SMTP server only accepts secure connections you can choose between + the following two variants: + **ssl** + - A secure connection will be initiated using the outdated SMTPS protocol + which uses the port 465/tcp. + :: "mail_smtphost" => "smtp.server.dom:465", "mail_smtpsecure" => 'ssl', - tls - A secure connection will be initiated using the STARTTLS protocol which - uses the default port 25/tcp. + **tls** + - A secure connection will be initiated using the STARTTLS protocol which + uses the default port 25/tcp. + :: "mail_smtphost" => "smtp.server.dom", "mail_smtpsecure" => 'tls', And finally it is necessary to configure if the SMTP server requires - authentication. If not, the default values can be taken as it: + authentication, if not, the default values can be taken as it. + :: "mail_smtpauth" => false, "mail_smtpname" => "", @@ -70,6 +79,7 @@ Parameters If SMTP authentication is required the configuration may be changed as followed: + :: "mail_smtpauth" => true, "mail_smtpname" => "username", @@ -79,9 +89,10 @@ Parameters If you want to use PHP mail it is necessary to have an installed and working email system on your server. Which program in detail is used to send email is - defined by the configuration settings in the ``php.ini`` file. (On *nix + defined by the configuration settings in the ``php.ini`` file. (On \*nix systems this will most likely be Sendmail.) ownCloud should be able to send email out of the box. + :: "mail_smtpmode" => "php", "mail_smtphost" => "127.0.0.1", @@ -95,9 +106,10 @@ Parameters * **Sendmail** If you want to use the well known Sendmail program to send email, it is - necessary to have an installed and working email system on your *nix server. + necessary to have an installed and working email system on your \*nix server. The sendmail binary (``/usr/sbin/sendmail``) is ususally part of that system. ownCloud should be able to send email out of the box. + :: "mail_smtpmode" => "sendmail", "mail_smtphost" => "127.0.0.1", @@ -114,6 +126,7 @@ Parameters installed and working qmail email system on your server. The sendmail binary (``/var/qmail/bin/sendmail``) will then be used to send email. ownCloud should be able to send email out of the box. + :: "mail_smtpmode" => "qmail", "mail_smtphost" => "127.0.0.1", @@ -128,11 +141,14 @@ Send a Test Email ----------------- The only way to test your email configuration is, to force a login failure, -because a function to send a test email hasn't be implemented yet. +because a function to send a test email has not be implemented yet. + First make sure that you are using a full qualified domain and not an ip address in the ownCloud URL, like ``http://my-owncloud-server.domain.dom/owncloud/``. -The password reset function reads the domain name from that URL to build the + +The password reset function fetches the domain name from that URL to build the email sender address, e.g. ``john@domain.dom``. + Next you need to enter your login and an *invalid* password. As soon as you press the login button the login mask reappears and a ``I’ve forgotten my password`` link will be shown above the login field. Click on that link, re-enter your login @@ -141,9 +157,10 @@ and press the ``Reset password`` button - that's all. Trouble shooting ---------------- -1. How can I find out if a SMTP server is reachable? +1. **How can I find out if a SMTP server is reachable?** Use the ping command to check the server availability: + :: # ping smtp.server.dom PING smtp.server.dom (ip-address) 56(84) bytes of data. @@ -151,11 +168,12 @@ Trouble shooting 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=2 ttl=64 time=0.055 ms 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=3 ttl=64 time=0.062 ms -2. How can I find out if the SMTP server is listening on a specific tcp port? +2. **How can I find out if the SMTP server is listening on a specific tcp port?** A SMTP server is usually listening on port ``25/tcp`` (smtp) and/or in rare circumstances is also listening on the outdated port ``465/tcp`` (smtps). You can use the telnet command to check if a port is available: + :: # telnet smtp.domain.dom 25 Trying 192.168.1.10... @@ -163,39 +181,44 @@ Trouble shooting Escape character is '^]'. 220 smtp.domain.dom ESMTP Exim 4.80.1 Tue, 22 Jan 2013 22:28:14 +0100 -3. How can I find out if a SMTP server supports the outdated SMTPS protocol? +3. **How can I find out if a SMTP server supports the outdated SMTPS protocol?** A good indication that a SMTP server supports the SMTPS protocol is that it is listening on port ``465/tcp``. How this can be checked has been described previously. -4. How can I find out if a SMTP server supports the TLS protocol? +4. **How can I find out if a SMTP server supports the TLS protocol?** A SMTP server usually announces the availability of STARTTLS right after a connection has been established. This can easily been checked with the telnet command. You need to enter the marked lines to get the information displayed: + :: # telnet smtp.domain.dom 25 Trying 192.168.1.10... Connected to smtp.domain.dom. Escape character is '^]'. 220 smtp.domain.dom ESMTP Exim 4.80.1 Tue, 22 Jan 2013 22:39:55 +0100 - *EHLO your-server.local.lan* + EHLO your-server.local.lan # <<< enter this command 250-smtp.domain.dom Hello your-server.local.lan [ip-address] 250-SIZE 52428800 250-8BITMIME 250-PIPELINING 250-AUTH PLAIN LOGIN CRAM-MD5 - **250-STARTTLS** + 250-STARTTLS # <<< STARTTLS is supported! 250 HELP - *QUIT* + QUIT # <<< enter this command 221 smtp.domain.dom closing connection Connection closed by foreign host. -5. If you are still not able to send email it might be useful to activate +5. **Enable Debug Mode** + + If you are still not able to send email it might be useful to activate further debug messages by setting the following parameter. Right after - you have pressed the ``Reset password`` button, as described beforem a lot - ``SMTP -> get_lines(): ...`` messages will then be written on the screen. + you have pressed the ``Reset password`` button, as described before, a + lot of ``SMTP -> get_lines(): ...`` messages will be written on the + screen. + :: "mail_smtpdebug" => true;