diff --git a/admin_manual/configuration/configuration_mail.rst b/admin_manual/configuration/configuration_mail.rst index 01e7c56f7..4de9c2b37 100644 --- a/admin_manual/configuration/configuration_mail.rst +++ b/admin_manual/configuration/configuration_mail.rst @@ -1,21 +1,140 @@ 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 `_. To -take advantage of this function it needs to be configured properly. + +ownCloud is capable of sending password reset emails, notifying users of new +file shares, changes in files, and activity notifications. Your users configure +which notifications they want to receive on their Personal pages. + +ownCloud does not contain a full email server, but rather connects to your +existing mail server. You must have a functioning mail server for ownCloud to be +able to send emails. You may have a mail server on the same machine as ownCloud, +or it may be a remote server. + +ownCloud 7 introduces a new feature, the graphical SMTP Configuration Wizard. + +.. figure:: ../images/smtp-config-wizard.png + +With the new wizard, connecting ownCloud to your mail server is fast and easy. +The wizard fills in the values in ``config/config.php``, so you may use either +or both as you prefer. + +The ownCloud SMTP wizard supports three types of mail server connections: SMTP, +PHP, and Sendmail. Use the SMTP configurator for a remote server, and PHP or +Sendmail when your mail server is on the same machine as ownCloud. + +.. note:: The Sendmail option refers to the Sendmail SMTP server, and any + drop-in Sendmail replacement such as Postfix, Exim, or Courier. All of these + include a ``sendmail`` binary, and are freely-interchangeable. + +Configuring an SMTP Server +-------------------------- + +You need the following information from your mailserver administrator to +connect ownCloud to a remote SMTP server: + +* Encryption type: None, SSL, or TLS + +* The From address you want your outgoing ownCloud mails to use + +* Whether authentication is required + +* Authentication method: None, Login, Plain, or NT LAN Manager + +* The server's IP address or fully-qualified domain name + +* Login credentials, if required + +.. figure:: ../images/smtp-config-smtp.png + +Your changes are saved immediately, and you can click the Send Email button to +test your configuration. This sends a test message to the email address you +configured on your Personal page. The test message says:: + + If you received this email, the settings seem to be correct. + + -- + ownCloud + web services under your control + +Configuring PHP and Sendmail +---------------------------- + +Configuring PHP or Sendmail requires only that you select one of them, and then +enter your desired return address. + +.. figure:: ../images/smtp-config-php-sendmail.png + +How do you decide which one to use? PHP mode uses your local ``sendmail`` +binary. Use this if you want to use ``php.ini`` to control some of your mail +server functions, such as setting paths, headers, or passing extra command +options to the ``sendmail`` binary. These vary according to which server you +are using, so consult your server's documentation to see what your options are. + +In most cases the ``smtp`` option is best, because it removes the extra step of +passing through PHP, and you can control all of your mail server options in one +place, in your mail server configuration. -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**. +Using Email Templates +--------------------- -Parameters ----------- +Another useful new feature is editable email templates. Now you can edit +ownCloud's email templates on your Admin page. These are your available +templates: -All parameters need to be set in :file:`config/config.php` +* Sharing email (http) -- HTML version of emails notifying users of new file + shares + +* Sharing email -- Plain text email notifying users of new file shares + +* Lost password mail -- Password reset email for users who lose their passwords. + +* Activity notification mail -- Notification of activities that users have + enabled in the Notifications section of their Personal pages. + +In addition to providing the email templates, this feature enables you to apply +any preconfigured themes to the email. + +To modify an email template to users: + +1. Access the Admin page. + +2. Scroll to the Mail templates section. + +3. Select a template from the drop-down menu. + +4. Make any desired modifications to the template. + +The templates are written in PHP and HTML, and are already loaded with the +relevant variables such as username, share links, and filenames. You can, if you +are careful, edit these even without knowing PHP or HTML; don't touch any of the +code, but you can edit the text portions of the messages. For example, this the +lost password mail template: + +.. code-block:: php + + t('Use the following link to + reset your password: {link}')); + +You could change the text portion of the template, ``Use the following link to +reset your password:`` to say something else, such as ``Click the following link +to reset your password. If you did not ask for a password reset, ignore this +message.`` + +Again, be very careful to change nothing but the message text, because the +tiniest coding error will break the template. + +.. note:: You can edit the templates directly in the template text box, or you + can copy and paste them to a text editor for modification and then copy and + paste them back to the template text box for use when you are done. + +Setting Mail Server Parameters in config.php +-------------------------------------------- + +If you prefer, you may set your mail server parameters in ``config/config.php``. +The following examples are for SMTP, PHP, Sendmail, and Qmail. SMTP ~~~~ @@ -23,8 +142,8 @@ 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 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 -semicolon: +**mail_smtpport** parameter. Multiple servers can be entered, separated by +semicolons: .. code-block:: php @@ -90,7 +209,7 @@ uses the default port 25/tcp: "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 is. .. code-block:: php @@ -185,49 +304,29 @@ To test your email configuration, save your email address in your personal settings and then use the **Send email** button in *Email Server* section of the Admin settings page. -Using Email Templates ---------------------- - -As an added convenience to administrators, ownCloud provides several Email templates that you can use for sending messages to users. - -#.. figure:: ../images/remote_shares.png - -Found on the Admin page, you can choose from the following templates: - -* Sharing email (http) -- You can use this template to send emails to users about sharing links. - -* Sharing email -- You can use this template to send emails to users about sharing files. - -* Lost password mail -- When managing users, you can use this template to send emails to users about lost password recovery. - -* Activity notification mail -- You can use this template to send emails to users detailing their ownCloud activity. - -In addition to providing the Email templates, this feature enables you to apply any preconfigured themes to the email. - -To modify an email template to users: - -1. Access the Admin page. - -2. Scroll to the Mail templates section. - -3. Select a template from the drop-down menu. - -4. Make any desired modifications to the template. - - .. note:: You can edit the templates directly in the template text box or you can copy and paste them to a text editor for modification and then copy and paste them back to the template text box for use when you are done. - -5. Click ``Save`` to the file modifications. - - Once complete, the files are sent to users who choose to receive notifications through email. - - .. note:: ownCloud populates the variables with usernames and filenames prior to sending the email. Troubleshooting ----------------- +--------------- + +If you are unable to send email, try turning on debugging. Do this by enabling +the ``mail_smtpdebug parameter`` in ``config/config.php``. + +.. code-block:: php + + true; + +.. note:: Immediately after pressing the **Send email** button, as described + before, several **SMTP -> get_lines(): ...** messages appear on the screen. + This is expected behavior and can be ignored. **Question**: Why is my web domain different from my mail domain? -**Answer**: The default domain name used for the sender address is the hostname where your ownCloud installation is served. If you have a different mail domain name you can override this behavior by setting the following configuration parameter: +**Answer**: The default domain name used for the sender address is the hostname +where your ownCloud installation is served. If you have a different mail domain +name you can override this behavior by setting the following configuration +parameter: .. code-block:: php @@ -235,7 +334,8 @@ Troubleshooting "mail_domain" => "example.com", -This setting results in every email sent by ownCloud (for example, the password reset email) having the domain part of the sender address appear as follows:: +This setting results in every email sent by ownCloud (for example, the password +reset email) having the domain part of the sender address appear as follows:: no-reply@example.com @@ -248,31 +348,56 @@ This setting results in every email sent by ownCloud (for example, the password :: 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 + 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=1 ttl=64 + time=3.64ms -**Question**: How can I find out if the SMTP server is listening on a specific TCP port? -**Answer**: SMTP servers usually listen on port **25/tcp** (smtp). In -rare circumstances the SMTP server also listens on the outdated port **465/tcp** (smtps). You can use the ``telnet`` command to determining if a port is available:: +**Question**: How can I find out if the SMTP server is listening on a specific +TCP port? - telnet smtp.domain.dom 25 +**Answer**: The best way to get mail server information is to ask your mail +server admin. If you are the mail server admin, or need information in a +hurry, you can use the ``netstat`` command. This example shows all active +servers on your system, and the ports they are listening on. The SMTP server is +listening on localhost port 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 +# netstat -pant -**Question**: How can I determine if the SMTP server supports the outdated SMTPS protocol? +:: -**Answer**: A good indication that the SMTP server supports the SMTPS protocol is that it is listening on port **465/tcp**. See the previous answer to use the ``telnet`` command for checking the port availability. + Active Internet connections (servers and established) + Proto Recv-Q Send-Q Local Address Foreign Address State ID/Program name + tcp 0 0 0.0.0.0:631 0.0.0.0:* LISTEN 4418/cupsd + tcp 0 0 127.0.0.1:25 0.0.0.0:* LISTEN 2245/exim4 + tcp 0 0 127.0.0.1:3306 0.0.0.0:* LISTEN 1524/mysqld -**Question**: How can I determine if the SMTP server supports the TLS protocol? +* 25/tcp is unencrypted smtp -**Answer**: SMTP servers usually announce the availability of STARTTLS immediately after a connection has been established. You can easily check this using the ``telnet`` command. +* 110/tcp/udp is unencrypted pop3 + +* 143/tcp/udp is unencrypted imap4 + +* 465/tcp is encrypted ssmtp + +* 993/tcp/udp is encrypted imaps + +* 995/tcp/udp is encrypted pop3s + + +**Question**: How can I determine if the SMTP server supports the outdated SMTPS +protocol? + +**Answer**: A good indication that the SMTP server supports the SMTPS protocol +is that it is listening on port **465**. + +**Question**: How can I determine what authorization and encryption protocols +the mail server supports? + +**Answer**: SMTP servers usually announce the availability of STARTTLS +immediately after a connection has been established. You can easily check this +using the ``telnet`` command. .. note:: You must enter the marked lines to obtain the information displayed. @@ -286,50 +411,23 @@ rare circumstances the SMTP server also listens on the outdated port **465/tcp** 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 # <<< enter this command + 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 # <<< STARTTLS is supported! + 250-AUTH PLAIN LOGIN CRAM-MD5 # <<< Supported auth protocols + 250-STARTTLS # <<< Encryption is supported 250 HELP - QUIT # <<< enter this command - 221 smtp.domain.dom closing connection - Connection closed by foreign host. - -**Question**: How can I determine which authentication types or methods the SMTP server supports? - -**Answer**: SMTP servers usually announce the available authentication types or methods immediately following the establishment of a connection. You can easily check this using the telnet command. - -.. note:: You must enter the marked lines to obtrain 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 # <<< 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 # <<< available Authentication types - 250-STARTTLS - 250 HELP - QUIT # <<< enter this command + QUIT # <<< enter this command 221 smtp.domain.dom closing connection Connection closed by foreign host. Enabling Debug Mode ------------------- -If you are unable to send email, it might be useful to activate further debug messages by enabling the mail_smtpdebug parameter: +If you are unable to send email, it might be useful to activate further debug +messages by enabling the mail_smtpdebug parameter: .. code-block:: php @@ -337,5 +435,6 @@ If you are unable to send email, it might be useful to activate further debug me "mail_smtpdebug" => true, -.. note:: Immediately after pressing the **Send email** button, as described before, several **SMTP -> get_lines(): ...** messages appear on the screen. This is expected behavior and can be ignored. - +.. note:: Immediately after pressing the **Send email** button, as described + before, several **SMTP -> get_lines(): ...** messages appear on the screen. + This is expected behavior and can be ignored. \ No newline at end of file diff --git a/admin_manual/images/smtp-config-php-sendmail.png b/admin_manual/images/smtp-config-php-sendmail.png new file mode 100644 index 000000000..45925516f Binary files /dev/null and b/admin_manual/images/smtp-config-php-sendmail.png differ diff --git a/admin_manual/images/smtp-config-smtp.png b/admin_manual/images/smtp-config-smtp.png new file mode 100644 index 000000000..9146c9ed0 Binary files /dev/null and b/admin_manual/images/smtp-config-smtp.png differ diff --git a/admin_manual/images/smtp-config-wizard.png b/admin_manual/images/smtp-config-wizard.png new file mode 100644 index 000000000..ce8a8fe63 Binary files /dev/null and b/admin_manual/images/smtp-config-wizard.png differ