Changeset View
Changeset View
Standalone View
Standalone View
src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
Show All 16 Lines | final class PhabricatorMetaMTAConfigOptions | ||||
public function getGroup() { | public function getGroup() { | ||||
return 'core'; | return 'core'; | ||||
} | } | ||||
public function getOptions() { | public function getOptions() { | ||||
$send_as_user_desc = $this->deformat(pht(<<<EODOC | $send_as_user_desc = $this->deformat(pht(<<<EODOC | ||||
When a user takes an action which generates an email notification (like | When a user takes an action which generates an email notification (like | ||||
commenting on a Differential revision), Phabricator can either send that mail | commenting on a Differential revision), the "From" address can either be set | ||||
"From" the user's email address (like "alincoln@logcabin.com") or "From" the | to the user's email address (like "alincoln@logcabin.com") or the | ||||
'%s' address. | "metamta.defualt-address" address. | ||||
The user experience is generally better if Phabricator uses the user's real | The user experience is generally better if the user's real address is used as | ||||
address as the "From" since the messages are easier to organize when they appear | the "From" header value, since the messages are easier to organize when they | ||||
in mail clients, but this will only work if the server is authorized to send | appear in mail clients, but this will only work if the server is authorized to | ||||
email on behalf of the "From" domain. Practically, this means: | send email on behalf of the "From" domain. Practically, this means: | ||||
- If you are doing an install for Example Corp and all the users will have | - If you are doing an install for Example Corp and all the users will have | ||||
corporate @corp.example.com addresses and any hosts Phabricator is running | corporate @corp.example.com addresses and any hosts this software is running | ||||
on are authorized to send email from corp.example.com, you can enable this | on are authorized to send email from corp.example.com, you can enable this | ||||
to make the user experience a little better. | to make the user experience a little better. | ||||
- If you are doing an install for an open source project and your users will | - If you are doing an install for an open source project and your users will | ||||
be registering via Facebook and using personal email addresses, you probably | be registering via third-party services and/or using personal email | ||||
should not enable this or all of your outgoing email might vanish into SFP | addresses, you probably should not enable this or all of your outgoing | ||||
blackholes. | email might vanish into SFP blackholes. | ||||
- If your install is anything else, you're safer leaving this off, at least | - If your install is anything else, you're safer leaving this off, at least | ||||
initially, since the risk in turning it on is that your outgoing mail will | initially, since the risk in turning it on is that your outgoing mail will | ||||
never arrive. | never arrive. | ||||
EODOC | EODOC | ||||
, | )); | ||||
'metamta.default-address')); | |||||
$one_mail_per_recipient_desc = $this->deformat(pht(<<<EODOC | $one_mail_per_recipient_desc = $this->deformat(pht(<<<EODOC | ||||
When a message is sent to multiple recipients (for example, several reviewers on | When a message is sent to multiple recipients (for example, several reviewers on | ||||
a code review), Phabricator can either deliver one email to everyone (e.g., "To: | a code review), it can either be delieverd as one email to everyone (e.g., "To: | ||||
alincoln, usgrant, htaft") or separate emails to each user (e.g., "To: | alincoln, usgrant, htaft") or separate emails to each user (e.g., "To: | ||||
alincoln", "To: usgrant", "To: htaft"). The major advantages and disadvantages | alincoln", "To: usgrant", "To: htaft"). The major advantages and disadvantages | ||||
of each approach are: | of each approach are: | ||||
- One mail to everyone: | - One mail to everyone: | ||||
- This violates policy controls. The body of the mail is generated without | - This violates policy controls. The body of the mail is generated without | ||||
respect for object policies. | respect for object policies. | ||||
- Recipients can see To/Cc at a glance. | - Recipients can see To/Cc at a glance. | ||||
- If you use mailing lists, you won't get duplicate mail if you're | - If you use mailing lists, you won't get duplicate mail if you're | ||||
a normal recipient and also Cc'd on a mailing list. | a normal recipient and also Cc'd on a mailing list. | ||||
- Getting threading to work properly is harder, and probably requires | - Getting threading to work properly is harder, and probably requires | ||||
making mail less useful by turning off options. | making mail less useful by turning off options. | ||||
- Sometimes people will "Reply All", which can send mail to too many | - Sometimes people will "Reply All", which can send mail to too many | ||||
recipients. Phabricator will try not to send mail to users who already | recipients. This software will try not to send mail to users who already | ||||
received a similar message, but can not prevent all stray email arising | received a similar message, but can not prevent all stray email arising | ||||
from "Reply All". | from "Reply All". | ||||
- Not supported with a private reply-to address. | - Not supported with a private reply-to address. | ||||
- Mail messages are sent in the server default translation. | - Mail messages are sent in the server default translation. | ||||
- Mail that must be delivered over secure channels will leak the recipient | - Mail that must be delivered over secure channels will leak the recipient | ||||
list in the "To" and "Cc" headers. | list in the "To" and "Cc" headers. | ||||
- One mail to each user: | - One mail to each user: | ||||
- Policy controls work correctly and are enforced per-user. | - Policy controls work correctly and are enforced per-user. | ||||
Show All 25 Lines | )); | ||||
$email_preferences_description = $this->deformat(pht(<<<EODOC | $email_preferences_description = $this->deformat(pht(<<<EODOC | ||||
You can disable the email preference link in emails if users prefer smaller | You can disable the email preference link in emails if users prefer smaller | ||||
emails. | emails. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$re_prefix_description = $this->deformat(pht(<<<EODOC | $re_prefix_description = $this->deformat(pht(<<<EODOC | ||||
Mail.app on OS X Lion won't respect threading headers unless the subject is | Mail.app on OS X Lion won't respect threading headers unless the subject is | ||||
prefixed with "Re:". If you enable this option, Phabricator will add "Re:" to | prefixed with "Re:". If you enable this option, this software will add "Re:" to | ||||
the subject line of all mail which is expected to thread. If you've set | the subject line of all mail which is expected to thread. If you've set | ||||
'metamta.one-mail-per-recipient', users can override this setting in their | 'metamta.one-mail-per-recipient', users can override this setting in their | ||||
preferences. | preferences. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$vary_subjects_description = $this->deformat(pht(<<<EODOC | $vary_subjects_description = $this->deformat(pht(<<<EODOC | ||||
If true, allow MetaMTA to change mail subjects to put text like '[Accepted]' and | If true, allow MetaMTA to change mail subjects to put text like '[Accepted]' and | ||||
'[Commented]' in them. This makes subjects more useful, but might break | '[Commented]' in them. This makes subjects more useful, but might break | ||||
threading on some clients. If you've set '%s', users can override this setting | threading on some clients. If you've set '%s', users can override this setting | ||||
in their preferences. | in their preferences. | ||||
EODOC | EODOC | ||||
, | , | ||||
'metamta.one-mail-per-recipient')); | 'metamta.one-mail-per-recipient')); | ||||
$reply_to_description = $this->deformat(pht(<<<EODOC | $reply_to_description = $this->deformat(pht(<<<EODOC | ||||
If you enable `%s`, Phabricator uses "From" to authenticate users. You can | If you enable `%s`, this software uses "From" to authenticate users. You can | ||||
additionally enable this setting to try to authenticate with 'Reply-To'. Note | additionally enable this setting to try to authenticate with 'Reply-To'. Note | ||||
that this is completely spoofable and insecure (any user can set any 'Reply-To' | that this is completely spoofable and insecure (any user can set any 'Reply-To' | ||||
address) but depending on the nature of your install or other deliverability | address) but depending on the nature of your install or other deliverability | ||||
conditions this might be okay. Generally, you can't do much more by spoofing | conditions this might be okay. Generally, you can't do much more by spoofing | ||||
Reply-To than be annoying (you can write but not read content). But this is | Reply-To than be annoying (you can write but not read content). But this is | ||||
still **COMPLETELY INSECURE**. | still **COMPLETELY INSECURE**. | ||||
EODOC | EODOC | ||||
, | , | ||||
'metamta.public-replies')); | 'metamta.public-replies')); | ||||
$adapter_description = $this->deformat(pht(<<<EODOC | $adapter_description = $this->deformat(pht(<<<EODOC | ||||
Adapter class to use to transmit mail to the MTA. The default uses | Adapter class to use to transmit mail to the MTA. The default uses | ||||
PHPMailerLite, which will invoke "sendmail". This is appropriate if sendmail | PHPMailerLite, which will invoke "sendmail". This is appropriate if sendmail | ||||
actually works on your host, but if you haven't configured mail it may not be so | actually works on your host, but if you haven't configured mail it may not be so | ||||
great. A number of other mailers are available (e.g., SES, SendGrid, SMTP, | great. A number of other mailers are available (e.g., SES, SendGrid, SMTP, | ||||
custom mailers). This option is deprecated in favor of 'cluster.mailers'. | custom mailers). This option is deprecated in favor of 'cluster.mailers'. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$public_replies_description = $this->deformat(pht(<<<EODOC | $public_replies_description = $this->deformat(pht(<<<EODOC | ||||
By default, Phabricator generates unique reply-to addresses and sends a separate | By default, this software generates unique reply-to addresses and sends a | ||||
email to each recipient when you enable reply handling. This is more secure than | separate email to each recipient when you enable reply handling. This is more | ||||
using "From" to establish user identity, but can mean users may receive multiple | secure than using "From" to establish user identity, but can mean users may | ||||
emails when they are on mailing lists. Instead, you can use a single, non-unique | receive multiple emails when they are on mailing lists. Instead, you can use a | ||||
reply to address and authenticate users based on the "From" address by setting | single, non-unique reply to address and authenticate users based on the "From" | ||||
this to 'true'. This trades away a little bit of security for convenience, but | address by setting this to 'true'. This trades away a little bit of security | ||||
it's reasonable in many installs. Object interactions are still protected using | for convenience, but it's reasonable in many installs. Object interactions are | ||||
hashes in the single public email address, so objects can not be replied to | still protected using hashes in the single public email address, so objects | ||||
blindly. | can not be replied to blindly. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$single_description = $this->deformat(pht(<<<EODOC | $single_description = $this->deformat(pht(<<<EODOC | ||||
If you want to use a single mailbox for Phabricator reply mail, you can use this | If you want to use a single mailbox for reply mail, you can use this | ||||
and set a common prefix for reply addresses generated by Phabricator. It will | and set a common prefix for generated reply addresses. It will | ||||
make use of the fact that a mail-address such as | make use of the fact that a mail-address such as | ||||
`phabricator+D123+1hjk213h@example.com` will be delivered to the `phabricator` | `devtools+D123+1hjk213h@example.com` will be delivered to the `devtools` | ||||
user's mailbox. Set this to the left part of the email address and it will be | user's mailbox. Set this to the left part of the email address and it will be | ||||
prepended to all generated reply addresses. | prepended to all generated reply addresses. | ||||
For example, if you want to use `phabricator@example.com`, this should be set | For example, if you want to use `devtools@example.com`, this should be set | ||||
to `phabricator`. | to `devtools`. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$address_description = $this->deformat(pht(<<<EODOC | $address_description = $this->deformat(pht(<<<EODOC | ||||
When email is sent, what format should Phabricator use for user's email | When email is sent, what format should the software use for users' email | ||||
addresses? Valid values are: | addresses? Valid values are: | ||||
- `short`: 'gwashington <gwashington@example.com>' | - `short`: 'gwashington <gwashington@example.com>' | ||||
- `real`: 'George Washington <gwashington@example.com>' | - `real`: 'George Washington <gwashington@example.com>' | ||||
- `full`: 'gwashington (George Washington) <gwashington@example.com>' | - `full`: 'gwashington (George Washington) <gwashington@example.com>' | ||||
The default is `full`. | The default is `full`. | ||||
EODOC | EODOC | ||||
)); | )); | ||||
$mailers_description = $this->deformat(pht(<<<EODOC | $mailers_description = $this->deformat(pht(<<<EODOC | ||||
Define one or more mail transmission services. For help with configuring | Define one or more mail transmission services. For help with configuring | ||||
mailers, see **[[ %s | %s ]]** in the documentation. | mailers, see **[[ %s | %s ]]** in the documentation. | ||||
EODOC | EODOC | ||||
, | , | ||||
PhabricatorEnv::getDoclink('Configuring Outbound Email'), | PhabricatorEnv::getDoclink('Configuring Outbound Email'), | ||||
pht('Configuring Outbound Email'))); | pht('Configuring Outbound Email'))); | ||||
$default_description = $this->deformat(pht(<<<EODOC | $default_description = $this->deformat(pht(<<<EODOC | ||||
Default address used as a "From" or "To" email address when an address is | Default address used as a "From" or "To" email address when an address is | ||||
required but no meaningful address is available. | required but no meaningful address is available. | ||||
If you configure inbound mail, you generally do not need to set this: | If you configure inbound mail, you generally do not need to set this: | ||||
Phabricator will automatically generate and use a suitable mailbox on the | the software will automatically generate and use a suitable mailbox on the | ||||
inbound mail domain. | inbound mail domain. | ||||
Otherwise, this option should be configured to point at a valid mailbox which | Otherwise, this option should be configured to point at a valid mailbox which | ||||
discards all mail sent to it. If you point it at an invalid mailbox, mail sent | discards all mail sent to it. If you point it at an invalid mailbox, mail sent | ||||
by Phabricator and some mail sent by users will bounce. If you point it at a | by the software and some mail sent by users will bounce. If you point it at a | ||||
real user mailbox, that user will get a lot of mail they don't want. | real user mailbox, that user will get a lot of mail they don't want. | ||||
For further guidance, see **[[ %s | %s ]]** in the documentation. | For further guidance, see **[[ %s | %s ]]** in the documentation. | ||||
EODOC | EODOC | ||||
, | , | ||||
PhabricatorEnv::getDoclink('Configuring Outbound Email'), | PhabricatorEnv::getDoclink('Configuring Outbound Email'), | ||||
pht('Configuring Outbound Email'))); | pht('Configuring Outbound Email'))); | ||||
Show All 12 Lines | return array( | ||||
->setLocked(true) | ->setLocked(true) | ||||
->setBoolOptions( | ->setBoolOptions( | ||||
array( | array( | ||||
pht('Send Mail To Each Recipient'), | pht('Send Mail To Each Recipient'), | ||||
pht('Send Mail To All Recipients'), | pht('Send Mail To All Recipients'), | ||||
)) | )) | ||||
->setSummary( | ->setSummary( | ||||
pht( | pht( | ||||
'Controls whether Phabricator sends one email with multiple '. | 'Controls whether email for multiple recipients is sent by '. | ||||
'recipients in the "To:" line, or multiple emails, each with a '. | 'creating one message with everyone in the "To:" line, or '. | ||||
'single recipient in the "To:" line.')) | 'multiple messages that each have a single recipeint in the '. | ||||
'"To:" line.')) | |||||
->setDescription($one_mail_per_recipient_desc), | ->setDescription($one_mail_per_recipient_desc), | ||||
$this->newOption('metamta.can-send-as-user', 'bool', false) | $this->newOption('metamta.can-send-as-user', 'bool', false) | ||||
->setBoolOptions( | ->setBoolOptions( | ||||
array( | array( | ||||
pht('Send as User Taking Action'), | pht('Send as User Taking Action'), | ||||
pht('Send as Phabricator'), | pht( | ||||
'Send as %s', | |||||
PlatformSymbols::getPlatformServerName()), | |||||
)) | )) | ||||
->setSummary( | ->setSummary( | ||||
pht( | pht( | ||||
'Controls whether Phabricator sends email "From" users.')) | 'Controls whether email is sent "From" users.')) | ||||
->setDescription($send_as_user_desc), | ->setDescription($send_as_user_desc), | ||||
$this->newOption( | $this->newOption( | ||||
'metamta.reply-handler-domain', | 'metamta.reply-handler-domain', | ||||
'string', | 'string', | ||||
null) | null) | ||||
->setLocked(true) | ->setLocked(true) | ||||
->setDescription(pht('Domain used for reply email addresses.')) | ->setDescription(pht('Domain used for reply email addresses.')) | ||||
->addExample('phabricator.example.com', ''), | ->addExample('devtools.example.com', ''), | ||||
$this->newOption('metamta.recipients.show-hints', 'bool', true) | $this->newOption('metamta.recipients.show-hints', 'bool', true) | ||||
->setBoolOptions( | ->setBoolOptions( | ||||
array( | array( | ||||
pht('Show Recipient Hints'), | pht('Show Recipient Hints'), | ||||
pht('No Recipient Hints'), | pht('No Recipient Hints'), | ||||
)) | )) | ||||
->setSummary(pht('Show "To:" and "Cc:" footer hints in email.')) | ->setSummary(pht('Show "To:" and "Cc:" footer hints in email.')) | ||||
->setDescription($recipient_hints_description), | ->setDescription($recipient_hints_description), | ||||
$this->newOption('metamta.email-preferences', 'bool', true) | $this->newOption('metamta.email-preferences', 'bool', true) | ||||
->setBoolOptions( | ->setBoolOptions( | ||||
array( | array( | ||||
pht('Show Email Preferences Link'), | pht('Show Email Preferences Link'), | ||||
pht('No Email Preferences Link'), | pht('No Email Preferences Link'), | ||||
)) | )) | ||||
->setSummary(pht('Show email preferences link in email.')) | ->setSummary(pht('Show email preferences link in email.')) | ||||
->setDescription($email_preferences_description), | ->setDescription($email_preferences_description), | ||||
$this->newOption('metamta.public-replies', 'bool', false) | $this->newOption('metamta.public-replies', 'bool', false) | ||||
->setBoolOptions( | ->setBoolOptions( | ||||
array( | array( | ||||
pht('Use Public Replies (Less Secure)'), | pht('Use Public Replies (Less Secure)'), | ||||
pht('Use Private Replies (More Secure)'), | pht('Use Private Replies (More Secure)'), | ||||
)) | )) | ||||
->setSummary( | ->setSummary( | ||||
pht( | pht( | ||||
'Phabricator can use less-secure but mailing list friendly public '. | 'Reply addresses can either be private (more secure) or '. | ||||
'reply addresses.')) | 'public (which works better with mailing lists).')) | ||||
->setDescription($public_replies_description), | ->setDescription($public_replies_description), | ||||
$this->newOption('metamta.single-reply-handler-prefix', 'string', null) | $this->newOption('metamta.single-reply-handler-prefix', 'string', null) | ||||
->setSummary( | ->setSummary( | ||||
pht('Allow Phabricator to use a single mailbox for all replies.')) | pht('Allow a single mailbox to be used for all replies.')) | ||||
->setDescription($single_description), | ->setDescription($single_description), | ||||
$this->newOption('metamta.user-address-format', 'enum', 'full') | $this->newOption('metamta.user-address-format', 'enum', 'full') | ||||
->setEnumOptions( | ->setEnumOptions( | ||||
array( | array( | ||||
'short' => pht('Short'), | 'short' => pht('Short'), | ||||
'real' => pht('Real'), | 'real' => pht('Real'), | ||||
'full' => pht('Full'), | 'full' => pht('Full'), | ||||
)) | )) | ||||
->setSummary(pht('Control how Phabricator renders user names in mail.')) | ->setSummary(pht('Control how user names are rendered in mail.')) | ||||
->setDescription($address_description) | ->setDescription($address_description) | ||||
->addExample('gwashington <gwashington@example.com>', 'short') | ->addExample('gwashington <gwashington@example.com>', 'short') | ||||
->addExample('George Washington <gwashington@example.com>', 'real') | ->addExample('George Washington <gwashington@example.com>', 'real') | ||||
->addExample( | ->addExample( | ||||
'gwashington (George Washington) <gwashington@example.com>', | 'gwashington (George Washington) <gwashington@example.com>', | ||||
'full'), | 'full'), | ||||
$this->newOption('metamta.email-body-limit', 'int', 524288) | $this->newOption('metamta.email-body-limit', 'int', 524288) | ||||
->setDescription( | ->setDescription( | ||||
Show All 13 Lines |