* Add warning to mailer documentation about authentication References #7966 Signed-off-by: Andrew Thornton <art27@cantab.net> * As per @guillep2k and @mrsdizzie * as per @mrsdizzie Signed-off-by: Andrew Thornton <art27@cantab.net> Co-authored-by: guillep2k <18600385+guillep2k@users.noreply.github.com>tags/v1.13.0-rc1
; Mail server | ; Mail server | ||||
; Gmail: smtp.gmail.com:587 | ; Gmail: smtp.gmail.com:587 | ||||
; QQ: smtp.qq.com:465 | ; QQ: smtp.qq.com:465 | ||||
; Note, if the port ends with "465", SMTPS will be used. Using STARTTLS on port 587 is recommended per RFC 6409. If the server supports STARTTLS it will always be used. | |||||
; Using STARTTLS on port 587 is recommended per RFC 6409. | |||||
; Note, if the port ends with "465", SMTPS will be used. | |||||
HOST = | HOST = | ||||
; Disable HELO operation when hostnames are different. | ; Disable HELO operation when hostnames are different. | ||||
DISABLE_HELO = | DISABLE_HELO = | ||||
USE_CERTIFICATE = false | USE_CERTIFICATE = false | ||||
CERT_FILE = custom/mailer/cert.pem | CERT_FILE = custom/mailer/cert.pem | ||||
KEY_FILE = custom/mailer/key.pem | KEY_FILE = custom/mailer/key.pem | ||||
; Should SMTP connection use TLS | |||||
; Should SMTP connect with TLS, (if port ends with 465 TLS will always be used.) | |||||
; If this is false but STARTTLS is supported the connection will be upgraded to TLS opportunistically. | |||||
IS_TLS_ENABLED = false | IS_TLS_ENABLED = false | ||||
; Mail from address, RFC 5322. This can be just an email address, or the `"Name" <email@example.com>` format | ; Mail from address, RFC 5322. This can be just an email address, or the `"Name" <email@example.com>` format | ||||
FROM = | FROM = | ||||
; Mailer user name and password | ; Mailer user name and password | ||||
; Please Note: Authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via STARTTLS) or `HOST=localhost`. | |||||
USER = | USER = | ||||
; Use PASSWD = `your password` for quoting if you use special characters in the password. | ; Use PASSWD = `your password` for quoting if you use special characters in the password. | ||||
PASSWD = | PASSWD = |
- `DISABLE_HELO`: **\<empty\>**: Disable HELO operation. | - `DISABLE_HELO`: **\<empty\>**: Disable HELO operation. | ||||
- `HELO_HOSTNAME`: **\<empty\>**: Custom hostname for HELO operation. | - `HELO_HOSTNAME`: **\<empty\>**: Custom hostname for HELO operation. | ||||
- `HOST`: **\<empty\>**: SMTP mail host address and port (example: smtp.gitea.io:587). | - `HOST`: **\<empty\>**: SMTP mail host address and port (example: smtp.gitea.io:587). | ||||
- Using opportunistic TLS via STARTTLS on port 587 is recommended per RFC 6409. | |||||
- `IS_TLS_ENABLED` : **false** : Forcibly use TLS to connect even if not on a default SMTPS port. | |||||
- Note, if the port ends with `465` SMTPS/SMTP over TLS will be used despite this setting. | |||||
- Otherwise if `IS_TLS_ENABLED=false` and the server supports `STARTTLS` this will be used. Thus if `STARTTLS` is preferred you should set `IS_TLS_ENABLED=false`. | |||||
- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or | - `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or | ||||
the "Name" \<email@example.com\> format. | the "Name" \<email@example.com\> format. | ||||
- `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address). | - `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address). | ||||
- `PASSWD`: **\<empty\>**: Password of mailing user. Use \`your password\` for quoting if you use special characters in the password. | - `PASSWD`: **\<empty\>**: Password of mailing user. Use \`your password\` for quoting if you use special characters in the password. | ||||
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or `HOST=localhost`. See [Email Setup]({{< relref "doc/usage/email-setup.en-us.md" >}}) for more information. | |||||
- `SKIP_VERIFY`: **\<empty\>**: Do not verify the self-signed certificates. | - `SKIP_VERIFY`: **\<empty\>**: Do not verify the self-signed certificates. | ||||
- **Note:** Gitea only supports SMTP with STARTTLS. | - **Note:** Gitea only supports SMTP with STARTTLS. | ||||
- `SUBJECT_PREFIX`: **\<empty\>**: Prefix to be placed before e-mail subject lines. | - `SUBJECT_PREFIX`: **\<empty\>**: Prefix to be placed before e-mail subject lines. | ||||
- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system (can be | - `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system (can be | ||||
command or full path). | command or full path). | ||||
- `SENDMAIL_TIMEOUT`: **5m**: default timeout for sending email through sendmail | - `SENDMAIL_TIMEOUT`: **5m**: default timeout for sending email through sendmail | ||||
- ``IS_TLS_ENABLED`` : **false** : Decide if SMTP connections should use TLS. | |||||
## Cache (`cache`) | ## Cache (`cache`) | ||||
For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}) | For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}) | ||||
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through: | |||||
- Via the server supporting TLS through STARTTLS - usually provided on port 587. (Also known as Opportunistic TLS.) | |||||
- SMTPS connection (SMTP over transport layer security) via the default port 465. | |||||
- Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.) | |||||
- This is due to protections imposed by the Go internal libraries against STRIPTLS attacks. | |||||
### Gmail | ### Gmail | ||||
The following configuration should work with GMail's SMTP server: | The following configuration should work with GMail's SMTP server: |