archive/phabricator
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Reorganize Diviner articles into user/ and tech/

Browse Source 
Summary: Ref T988. I'm splitting the Phabricator documentation into two separate documentation books, one less technical and one more technical. Move all the `.diviner` article files around into `src/docs/user/` or `src/docs/tech/`, accordingly. The only actual changes here are a couple of config changes in the `.book` files.

Test Plan: Regenerated user and technical documentation and saw stuff in the right places.

Reviewers: btrahan

Reviewed By: btrahan

CC: chad, aran

Maniphest Tasks: T988

Differential Revision: https://secure.phabricator.com/D6822
This commit is contained in:
epriestley
2013-08-28 09:57:00 -07:00
parent a96582c788
commit 536b0867de
83 changed files with 20 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
src/docs/user/configuration/configuration_guide.diviner Normal file
View File

@@ -0,0 +1,197 @@
@title Configuration Guide
@group config
This document contains basic configuration instructions for Phabricator.
= Prerequisites =
This document assumes you've already installed all the components you need.
If you haven't, see @{article:Installation Guide}.
The next steps are:
- Configure your webserver (Apache, nginx, or lighttpd).
- Access Phabricator with your browser.
- Follow the instructions to complete setup.
= Webserver: Configuring Apache =
NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll
down to their sections.
Get Apache running and verify it's serving a test page. Consult the Apache
documentation for help. Make sure ##mod_php## and ##mod_rewrite## are enabled,
and ##mod_ssl## if you intend to set up SSL.
If you haven't already, set up a domain name to point to the host you're
installing on. You can either install Phabricator on a subdomain (like
phabricator.example.com) or an entire domain, but you can not install it in
some subdirectory of an existing website. Navigate to whatever domain you're
going to use and make sure Apache serves you something to verify that DNS
is correctly configured.
NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
'http://example/'. Some web browsers will not set cookies otherwise.
Now, either create a VirtualHost entry (to put Phabricator on a subdomain)
or edit the Directory entry for the DocumentRoot. It should look something like
this:
name=httpd.conf
<VirtualHost *>
# Change this to the domain which points to your host.
ServerName phabricator.example.com
# Change this to the path where you put 'phabricator' when you checked it
# out from GitHub when following the Installation Guide.
#
# Make sure you include "/webroot" at the end!
DocumentRoot /path/to/phabricator/webroot
RewriteEngine on
RewriteRule ^/rsrc/(.*) - [L,QSA]
RewriteRule ^/favicon.ico - [L,QSA]
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
</VirtualHost>
If Apache isn't currently configured to serve documents out of the directory
where you put Phabricator, you may also need to add a section like this:
<Directory "/path/to/phabricator/webroot">
Order allow,deny
Allow from all
</Directory>
After making your edits, restart Apache, then continue to "Setup" below.
= Webserver: Configuring nginx =
NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll
to their sections.
For nginx, use a configuration like this:
name=nginx.conf
server {
server_name phabricator.example.com;
root /path/to/phabricator/webroot;
try_files $uri $uri/ /index.php;
location / {
index index.php;
if ( !-f $request_filename )
{
rewrite ^/(.*)$ /index.php?__path__=/$1 last;
break;
}
}
location /index.php {
fastcgi_pass localhost:9000;
fastcgi_index index.php;
#required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
#variables to make the $_SERVER populate in PHP
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
fastcgi_param REMOTE_ADDR $remote_addr;
}
}
Restart nginx after making your edits, then continue to "Setup" below.
= Webserver: Configuring lighttpd =
NOTE: Follow these instructions to use lighttpd. To use Apache or niginx, scroll
up to their sections.
For lighttpd, add a section like this to your lighttpd.conf:
$HTTP["host"] =~ "phabricator(\.example\.com)?" {
server.document-root = "/path/to/phabricator/webroot"
url.rewrite-once = (
"^(/rsrc/.*)$" => "$1",
"^(/favicon.ico)$" => "$1",
# This simulates QSA ("query string append") mode in apache
"^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
"^(/.*)$" => "/index.php?__path__=$1",
)
}
You should also ensure the following modules are listed in your
server.modules list:
mod_fastcgi
mod_rewrite
Finally, you should run the following commands to enable php support:
$ sudo apt-get install php5-cgi # for ubuntu; other distros should be similar
$ sudo lighty-enable-mod fastcgi-php
Restart lighttpd after making your edits, then continue below.
= Setup =
Now, navigate to whichever subdomain you set up. You should see instructions to
continue setup. The rest of this document contains additional instructions for
specific setup steps.
When you resolve any issues and see the welcome screen, enter credentials to
create your initial administrator account. After you log in, you'll want to
configure how other users will be able to log in or register -- until you do,
no one else will be able to sign up or log in. For more information, see
@{article:Configuring Accounts and Registration}.
= Storage: Configuring MySQL =
During setup, you'll need to configure MySQL. To do this, get MySQL running and
verify you can connect to it. Consult the MySQL documentation for help. When
MySQL works, you need to load the Phabricator schemata into it. To do this, run:
phabricator/ $ ./bin/storage upgrade
If your configuration uses an unprivileged user to connect to the database, you
may have to override the default user so the schema changes can be applied with
root or some other admin user:
phabricator/ $ ./bin/storage upgrade --user <user> --password <password>
You can avoid the prompt the script issues by passing the ##--force## flag (for
example, if you are scripting the upgrade process).
phabricator/ $ ./bin/storage upgrade --force
NOTE: When you update Phabricator, run `storage upgrade` again to apply any
new updates.
= Next Steps =
Continue by:
- setting up your admin account and login/registration with
@{article:Configuring Accounts and Registration}; or
- understanding advanced configuration topics with
@{article:Configuration User Guide: Advanced Configuration}; or
- configuring where uploaded files and attachments will be stored with
@{article:Configuring File Storage}; or
- configuring Phabricator so it can send mail with
@{article:Configuring Outbound Email}; or
- configuring inbound mail with @{article:Configuring Inbound Email}; or
- importing repositories with @{article:Diffusion User Guide}; or
- learning about daemons with @{article:Managing Daemons with phd}; or
- configuring backups with @{article:Configuring Backups}; or
- contributing to Phabricator with @{article:Contributor Introduction}.

69
src/docs/user/configuration/configuring_accounts_and_registration.diviner Normal file
View File

@@ -0,0 +1,69 @@
@title Configuring Accounts and Registration
@group config
Describes how to configure user access to Phabricator.
= Overview =
Phabricator supports a number of login systems. You can enable or disable these
systems to configure who can register for and access your install, and how users
with existing accounts can login.
Methods of logging in are called **Authentication Providers**. For example,
there is a "Username/Password" authentication provider available, which allows
users to log in with a traditional username and password. Other providers
support logging in with other credentials. For example:
- **Username/Password:** Users use a username and password to log in or
register.
- **LDAP:** Users use LDAP credentials to log in or register.
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
GitHub, Facebook, or Google) to log in or register.
- **Other Providers:** More providers are available, and Phabricator
can be extended with custom providers. See the "Auth" application for
a list of available providers.
By default, no providers are enabled. You must use the "Auth" application to
add one or more providers after you complete the installation process.
After you add a provider, you can link it to existing accounts (for example,
associate an existing Phabricator account with a GitHub OAuth account) or users
can use it to register new accounts (assuming you enable these options).
= Recovering Administrator Accounts =
If you accidentally lock yourself out of Phabricator, you can use the `bin/auth`
script to recover access to an administrator account. To recover access, run:
phabricator/ $ ./bin/auth recover <username>
...where `<username>` is the admin account username you want to recover access
to. This will give you a link which will log you in as the specified
administrative user.
= Managing Accounts with the Web Console =
To manage accounts from the web, login as an administrator account and go to
##/people/## or click "People" on the homepage. Provided you're an admin,
you'll see options to create or edit accounts.
= Manually Creating New Accounts =
There are two ways to manually create new accounts: via the web UI using
the "People" application (this is easiest), or via the CLI using the
`accountadmin` binary (this has a few more options).
To use the CLI script, run:
phabricator/ $ ./bin/accountadmin
Some options (like setting passwords and changing certain account flags) are
only available from the CLI. You can also use this script to make a user
an administrator (if you accidentally remove your admin flag) or create an
administrative account.
= Next Steps =
Continue by:
- returning to the @{article:Configuration Guide}.

98
src/docs/user/configuration/configuring_backups.diviner Normal file
View File

@@ -0,0 +1,98 @@
@title Configuring Backups
@group config
Advice for backing up Phabricator.
= Overview =
Phabricator does not currently have a comprehensive backup system, but creating
backups is not particularly difficult and Phabricator does have a few basic
tools which can help you set up a reasonable process. In particular, the things
which needs to be backed up are:
- the MySQL databases;
- uploaded files; and
- your Phabricator configuration files.
This document discusses approaches for backing up this data.
= Backup: MySQL Databases =
Most of Phabricator's data is stored in MySQL, and it's the most important thing
to back up. You can run `bin/storage dump` to get a dump of all the MySQL
databases. This is a convenience script which just runs a normal `mysqldump`
of every database Phabricator owns.
Since most of this data is compressible, it may be helpful to run it through
gzip prior to storage. For example:
phabricator/ $ ./bin/storage dump | gzip > backup.sql.gz
Then store the backup somewhere safe, like in a box buried under an old tree
stump. No one will ever think to look for it there.
= Restore: MySQL =
To restore a MySQL dump, just pipe it to `mysql` on a clean host. (You may need
to uncompress it first, if you compressed it prior to storage.)
$ gunzip -c backup.sql.gz | mysql
= Backup: Uploaded Files =
Uploaded files may be stored in several different locations. The backup
procedure depends on where files are stored:
**Default / MySQL**: Under the default configuration, uploaded files are stored
in MySQL, so the MySQL backup will include all files. In this case, you don't
need to do any additional work.
**Amazon S3**: If you use Amazon S3, redundancy and backups are built in to the
service. This is probably sufficient for most installs. If you trust Amazon with
your data //except not really//, you can backup your S3 bucket outside of
Phabricator.
**Local Disk**: If you use the local disk storage engine, you'll need to back up
files manually. You can do this by creating a copy of the root directory where
you told Phabricator to put files (the `storage.local-disk.path` configuration
setting).
For more information about configuring how files are stored, see
@{article:Configuring File Storage}.
= Restore: Uploaded Files =
To restore a backup of local disk storage, just copy the backup into place.
= Backup: Configuration Files =
You should also backup your configuration files, and any scripts you use to
deploy or administrate Phabricator (like a customized upgrade script). The best
way to do this is to check them into a private repository somewhere and just use
whatever backup process you already have in place for repositories. Just copying
them somewhere will work fine too, of course.
= Restore: Configuration Files =
To restore configuration files, just copy them into the right locations.
= Security =
MySQL dumps have no builtin encryption and most data in Phabricator is stored in
a raw, accessible form, so giving a user access to backups is a lot like giving
them shell access to the machine Phabricator runs on. In particular, a user who
has the backups can:
- read data that policies do not permit them to see;
- read email addresses and object secret keys; and
- read other users' session and conduit tokens and impersonate them.
Some of this information is durable, so disclosure of even a very old backup may
present a risk. If you restrict access to the Phabricator host or database, you
should also restrict access to the backups.
= Next Steps =
Continue by:
- returning to the @{article:Configuration Guide}.

105
src/docs/user/configuration/configuring_file_storage.diviner Normal file
View File

@@ -0,0 +1,105 @@
@title Configuring File Storage
@group config
Setup how Phabricator will store files.
= Overview =
Phabricator allows users to upload files, and several applications use file
storage (for instance, Maniphest allows you to attach files to tasks). You can
configure several different storage systems:
- you can store data in MySQL: this is the easiest to set up, but doesn't
scale well;
- you can store data on local disk: this is also easy to set up but won't
scale to multiple web frontends without NFS;
- or you can build a custom storage engine.
By default, Phabricator is configured to store files up to 1MB in MySQL, and
reject files larger than 1MB. It is recommended you set up local disk storage
for files larger than 1MB. This should be sufficient for most installs. If you
have a larger install or more unique requirements, you may want to customize
this further.
For technical documentation (including instructions on building custom storage
engines) see @{article:File Storage Technical Documentation}.
You don't have to fully configure this immediately, the defaults are okay until
you need to upload larger files and it's relatively easy to port files between
storage engines later.
= Storage Engines =
Builtin storage engines and information on how to configure them.
== MySQL ==
- **Pros**: Fast, no setup required.
- **Cons**: Storing files in a database is a classic bad idea. Does not scale
well. Maximum file size is limited.
MySQL storage is configured by default, for files up to (just under) 1MB. You
can configure it with these keys:
- ##storage.mysql-engine.max-size##: Change the filesize limit. Set to 0
to disable.
For most installs, it is recommended you configure local disk storage below,
and then either leave this as is or disable it, depending on how upset you feel
about putting files in a database.
== Local Disk ==
- **Pros**: Very simple. Almost no setup required.
- **Cons**: Doesn't scale to multiple web frontends without NFS.
For most installs, it is **strongly recommended** that you configure local disk
storage. To do this, set the configuration key:
- ##storage.local-disk.path##: Set to some writable directory on local disk.
Make that directory. You're done.
== Amazon S3 ==
- **Pros**: Scales well.
- **Cons**: More complicated and expensive than other approaches.
To enable file storage in S3, set these key:
- ##amazon-s3.access-key## Your AWS access key.
- ##amazon-s3.secret-key## Your AWS secret key.
- ##storage.s3.bucket## S3 bucket name where files should be stored.
== Custom Engine ==
For details about writing a custom storage engine, see @{article:File Storage
Technical Documentation}.
= Testing Storage Engines =
You can test that things are correctly configured by going to the Files
application (##/file/##) and uploading files.
= Migrating Files Between Engines =
If you want to move files between storage engines, you can use the `bin/files`
script to perform migrations. For example, suppose you previously used MySQL but
recently set up S3 and want to migrate all your files there. First, migrate one
file to make sure things work:
phabricator/ $ ./bin/files migrate --engine amazon-s3 F12345
If that works properly, you can then migrate everything:
phabricator/ $ ./bin/files migrate --engine amazon-s3 --all
You can use `--dry-run` to show which migrations would be performed without
taking any action. Run `bin/files help` for more options and information.
= Next Steps =
Continue by:
- configuring file size upload limits with
@{article:Configuring File Upload Limits}; or
- returning to the @{article:Configuration Guide}.

77
src/docs/user/configuration/configuring_file_upload_limits.diviner Normal file
View File

@@ -0,0 +1,77 @@
@title Configuring File Upload Limits
@group config
Explains limits on file upload sizes.
= Overview =
File uploads are limited by a large number of pieces of configuration, at
multiple layers of the application. Generally, the minimum value of all the
limits is the effective one. To upload large files, you need to increase all
the limits above the maximum file size you want to support. The settings which
limit uploads are:
- **HTTP Server**: The HTTP server may set a limit on the maximum request
size. If you exceed this limit, you'll see a default server page with an
HTTP error. These directives limit the total size of the request body,
so they must be somewhat larger than the desired maximum filesize.
- **Apache**: Apache limits requests with the Apache `LimitRequestBody`
directive.
- **nginx**: nginx limits requests with the nginx `client_max_body_size`
directive. This often defaults to `1M`.
- **lighttpd**: lighttpd limits requests with the lighttpd
`server.max-request-size` directive.
- **PHP**: PHP has several directives which limit uploads. These directives
are found in `php.ini`.
- **upload_max_filesize**: Maximum file size PHP will accept in a file
upload. If you exceed this, Phabricator will give you a useful error. This
often defaults to `2M`.
- **post_max_size**: Maximum POST request size PHP will accept. If you
exceed this, Phabricator will give you a useful error. This often defaults
to `8M`.
- **memory_limit**: For some uploads, file data will be read into memory
before Phabricator can adjust the memory limit. If you exceed this, PHP
may give you a useful error, depending on your configuration.
- **max_input_vars**: When files are uploaded via HTML5 drag and drop file
upload APIs, PHP parses the file body as though it contained normal POST
parameters, and may trigger `max_input_vars` if a file has a lot of
brackets in it. You may need to set it to some astronomically high value.
- **Storage Engines**: Some storage engines can be configured not to accept
files over a certain size. To upload a file, you must have at least one
configured storage engine which can accept it. Phabricator should give you
useful errors if any of these fail.
- **MySQL Engine**: Upload size is limited by the Phabricator setting
`storage.mysql-engine.max-size`.
- **Amazon S3**: Upload size is limited by Phabricator's implementation to
`5G`.
- **Local Disk**: Upload size is limited only by free disk space.
- **Resource Constraints**: File uploads are limited by resource constraints
on the application server. In particular, some uploaded files are written
to disk in their entirety before being moved to storage engines, and all
uploaded files are read into memory before being moved. These hard limits
should be large for most servers, but will fundamentally prevent Phabricator
from processing truly enormous files (GB/TB scale). Phabricator is probably
not the best application for this in any case.
- **Phabricator Master Limit**: The master limit, `storage.upload-size-limit`,
is used to show upload limits in the UI.
Phabricator can't read some of these settings, so it can't figure out what the
current limit is or be much help at all in configuring it. Thus, you need to
manually configure all of these limits and then tell Phabricator what you set
them to. Follow these steps:
- Pick some limit you want to set, like `100M`.
- Configure all of the settings mentioned above to be a bit bigger than the
limit you want to enforce (**note that there are some security implications
to raising these limits**; principally, your server may become easier to
attack with a denial-of-service).
- Set `storage.upload-size-limit` to the limit you want.
- The UI should now show your limit.
- Upload a big file to make sure it works.
= Next Steps =
Continue by:
- configuring file storage with @{article:Configuring File Storage}; or
- retuning to the @{article:Configuration Guide}.

236
src/docs/user/configuration/configuring_inbound_email.diviner Normal file
View File

@@ -0,0 +1,236 @@
@title Configuring Inbound Email
@group config
This document contains instructions for configuring inbound email, so users
may update Differential and Maniphest by replying to messages and create
Maniphest tasks via email.
= Preamble =
This can be extremely difficult to configure correctly. This is doubly true if
you use sendmail.
There are basically a few approaches available:
- Use SendGrid (<http://sendgrid.com/>), which is very easy but is not free.
- Run your own MTA, which can be quite harrowing to configure but is free.
- Tell the Phabricator devteam about another service you'd like support for,
this stuff is seriously terrible to configure on your own.
= Configuring Phabricator =
By default, Phabricator uses a "noreply@phabricator.example.com" email address
as the 'From' (configurable with ##metamta.default-address##) and sets
'Reply-To' to the user generating the email (e.g., by making a comment), if the
mail was generated by a user action. This means that users can reply (or
reply-all) to email to discuss changes, but the conversation won't be recorded
in Phabricator and users will not be able to take actions like claiming tasks or
requesting changes to revisions.
To change this behavior so that users can interact with objects in Phabricator
over email, set these configuration keys:
- ##metamta.differential.reply-handler-domain##: enables email replies for
Differential.
- ##metamta.maniphest.reply-handler-domain##: enables email replies for
Maniphest.
Set these keys to some domain which you configure according to the instructions
below, e.g. "##phabricator.example.com##". You can set these both to the same
domain, and will generally want to. Once you set these keys, emails will use a
'Reply-To' like "##T123+273+af310f9220ad@example.com##", which -- when
configured correctly, according to the instructions below -- will parse incoming
email and allow users to interact with Maniphest tasks and Differential
revisions over email.
If you don't want phabricator to take up an entire domain (or subdomain) you
can configure a general prefix so you can use a single mailbox to receive mail
on. To make use of this set ##metamta.single-reply-handler-prefix## to the
prefix of your choice, and phabricator will prepend this to the 'Reply-To'
mail address. This works because everything up to the first (optional) '+'
character in an email-address is considered the receiver, and everything
after is essentially "ignored".
You can also set up a task creation email address, like ##bugs@example.com##,
which will create a Maniphest task out of any email which is set to it. To do
this, set ##metamta.maniphest.public-create-email## in your configuration. This
has some mild security implications, see below.
= Security =
The email reply channel is "somewhat" authenticated. Each reply-to address is
unique to the recipient and includes a hash of user information and a unique
object ID, so it can only be used to update that object and only be used to act
on behalf of the recipient.
However, if an address is leaked (which is fairly easy -- for instance,
forwarding an email will leak a live reply address, or a user might take a
screenshot), //anyone// who can send mail to your reply-to domain may interact
with the object the email relates to as the user who leaked the mail. Because
the authentication around email has this weakness, some actions (like accepting
revisions) are not permitted over email.
This implementation is an attempt to balance utility and security, but makes
some sacrifices on both sides to achieve it because of the difficulty of
authenticating senders in the general case (e.g., where you are an open source
project and need to interact with users whose email accounts you have no control
over).
If you leak a bunch of reply-to addresses by accident, you can change
##phabricator.mail-key## in your configuration to invalidate all the old hashes.
You can also set ##metamta.public-replies##, which will change how Phabricator
delivers email. Instead of sending each recipient a unique mail with a personal
reply-to address, it will send a single email to everyone with a public reply-to
address. This decreases security because anyone who can spoof a "From" address
can act as another user, but increases convenience if you use mailing lists and,
practically, is a reasonable setting for many installs. The reply-to address
will still contain a hash unique to the object it represents, so users who have
not received an email about an object can not blindly interact with it.
If you enable ##metamta.maniphest.public-create-email##, that address also uses
the weaker "From" authentication mechanism.
NOTE: Phabricator does not currently attempt to verify "From" addresses because
this is technically complex, seems unreasonably difficult in the general case,
and no installs have had a need for it yet. If you have a specific case where a
reasonable mechanism exists to provide sender verification (e.g., DKIM
signatures are sufficient to authenticate the sender under your configuration,
or you are willing to require all users to sign their email), file a feature
request.
= Testing and Debugging Inbound Email =
You can use the `bin/mail` utility to test and review inbound mail. This can
help you determine if mail is being delivered to Phabricator or not:
phabricator/ $ ./bin/mail list-inbound # List inbound messages.
phabricator/ $ ./bin-mail show-inbound # Show details about a message.
You can also test receiving mail, but note that this just simulates receiving
the mail and doesn't send any information over the network. It is
primarily aimed at developing email handlers: it will still work properly
if your inbound email configuration is incorrect or even disabled.
phabricator/ $ ./bin/mail receive-test # Receive test message.
Run `bin/mail help <command>` for detailed help on using these commands.
= SendGrid =
To use SendGrid, you need a SendGrid account with access to the "Parse API" for
inbound email. Provided you have such an account, configure it like this:
- Configure an MX record according to SendGrid's instructions, i.e. add
##phabricator.example.com MX 10 mx.sendgrid.net.## or similar.
- Go to the "Parse Incoming Emails" page on SendGrid
(<http://sendgrid.com/developer/reply>) and add the domain as the
"Hostname".
- Add the URL ##https://phabricator.example.com/mail/sendgrid/## as the "Url",
using your domain (and HTTP instead of HTTPS if you are not configured with
SSL).
- If you get an error that the hostname "can't be located or verified", it
means your MX record is either incorrectly configured or hasn't propagated
yet.
- Set ##metamta.maniphest.reply-handler-domain## and/or
##metamta.differential.reply-handler-domain## to
"##phabricator.example.com##" (whatever you configured the MX record for),
depending on whether you want to support email replies for Maniphest,
Differential, or both.
That's it! If everything is working properly you should be able to send email
to ##anything@phabricator.example.com## and it should appear in
`bin/mail list-inbound` within a few seconds.
= Installing Mailparse =
If you're going to run your own MTA, you need to install the PECL mailparse
extension. In theory, you can do that with:
$ sudo pecl install mailparse
You may run into an error like "needs mbstring". If so, try:
$ sudo yum install php-mbstring # or equivalent
$ sudo pecl install -n mailparse
If you get a linker error like this:
COUNTEREXAMPLE
PHP Warning: PHP Startup: Unable to load dynamic library
'/usr/lib64/php/modules/mailparse.so' - /usr/lib64/php/modules/mailparse.so:
undefined symbol: mbfl_name2no_encoding in Unknown on line 0
...you need to edit your php.ini file so that mbstring.so is loaded **before**
mailparse.so. This is not the default if you have individual files in
##php.d/##.
= MTA: Configuring Sendmail =
Before you can configure Sendmail, you need to install Mailparse. See the
section "Installing Mailparse" above.
Sendmail is very difficult to configure. First, you need to configure it for
your domain so that mail can be delivered correctly. In broad strokes, this
probably means something like this:
- add an MX record;
- make sendmail listen on external interfaces;
- open up port 25 if necessary (e.g., in your EC2 security policy);
- add your host to /etc/mail/local-host-names; and
- restart sendmail.
Now, you can actually configure sendmail to deliver to Phabricator. In
##/etc/aliases##, add an entry like this:
phabricator: "| /path/to/phabricator/scripts/mail/mail_handler.php <ENV>"
...where <ENV> is the PHABRICATOR_ENV the script should run under. Run
##sudo newaliases##. Now you likely need to symlink this script into
##/etc/smrsh/##:
sudo ln -s /path/to/phabricator/scripts/mail/mail_handler.php /etc/smrsh/
Finally, edit ##/etc/mail/virtusertable## and add an entry like this:
@yourdomain.com phabricator@localhost
That will forward all mail to @yourdomain.com to the Phabricator processing
script. Run ##sudo /etc/mail/make## or similar and then restart sendmail with
##sudo /etc/init.d/sendmail restart##.
= MTA: Configuring Lamson =
Before you can configure Lamson, you need to install Mailparse. See the section
"Installing Mailparse" above.
In contrast to Sendmail, Lamson is relatively easy to configure. It is fairly
minimal, and is suitable for a development or testing environment. Lamson
listens for incoming SMTP mails and passes the content directly to Phabricator.
To get started, follow the provided instructions
(<http://lamsonproject.org/docs/getting_started.html>) to set up an instance.
One likely deployment issue is that binding to port 25 requires root
privileges. Lamson is capable of starting as root then dropping privileges, but
you must supply ##-uid## and ##-gid## arguments to do so, as demonstrated by
Step 8 in Lamson's deployment tutorial (located here:
<http://lamsonproject.org/docs/deploying_oneshotblog.html>).
The Lamson handler code itself is very concise; it merely needs to pass the
content of the email to Phabricator:
import logging, subprocess
from lamson.routing import route, stateless
from lamson import view
PHABRICATOR_ROOT = "/path/to/phabricator"
PHABRICATOR_ENV = "custom/myconf"
LOGGING_ENABLED = True
@route("(address)@(host)", address=".+")
@stateless
def START(message, address=None, host=None):
if LOGGING_ENABLED:
logging.debug("%s", message.original)
process = subprocess.Popen([PHABRICATOR_ROOT + "scripts/mail/mail_handler.php",PHABRICATOR_ENV],stdin=subprocess.PIPE)
process.communicate(message.original)

187
src/docs/user/configuration/configuring_outbound_email.diviner Normal file
View File

@@ -0,0 +1,187 @@
@title Configuring Outbound Email
@group config
Instructions for configuring Phabricator to send mail.
= Overview =
Phabricator can send outbound email via several different adapters:
- by running ##sendmail## on the local host with SMTP; or
- by running postfix on the local host with SMTP; or
- by using Amazon SES (Simple Email Service); or
- by using SendGrid's REST API; or
- via a custom adapter you write; or
- by dropping email into a hole and not delivering it.
Of these, ##sendmail## is the default but requires some configuration. SES and
SendGrid are easier, but cost money and have some limitations. Writing a custom
solution requires digging into the code. See below for details on how to set up
each method.
Phabricator can also send outbound email in two ways:
- immediately, when messages are generated (default); or
- in the background, via a daemon.
Sending mail in the background requires that you be running the Phabricator
daemons, but can greatly improve the performance of the application if your mail
handler is slow. For more information on using daemons, see
@{article:Managing Daemons with phd}.
= Basics =
Regardless of how outbound email is delivered, you should configure these keys
in your configuration file:
- **metamta.default-address** determines where mail is sent "From" by
default. If your domain is ##example.org##, set this to something like
"##noreply@example.org##".
- **metamta.domain** should be set to your domain, e.g. "##example.org##".
- **metamta.can-send-as-user** should be left as ##false## in most cases,
but see the documentation in ##default.conf.php## for details.
= Configuring Mail Adapters =
To choose how mail will be sent, change the **metamta.mail-adapter** key in
your configuration. Possible values are:
- ##PhabricatorMailImplementationPHPMailerLiteAdapter##: default, uses
"sendmail", see "Adapter: Sendmail".
- ##PhabricatorMailImplementationPHPMailerAdapter##: uses SMTP, see
"Adapter: SMTP".
- ##PhabricatorMailImplementationAmazonSESAdapter##: use Amazon SES, see
"Adapter: Amazon SES".
- ##PhabricatorMailImplementationSendGridAdapter##: use SendGrid, see
"Adapter: SendGrid".
- ##Some Custom Class You Write##: use a custom adapter you write, see
"Adapter: Custom".
- ##PhabricatorMailImplementationTestAdapter##: this will
**completely disable** outbound mail. You can use this if you don't want to
send outbound mail, or want to skip this step for now and configure it
later.
= Adapter: Sendmail =
This is the default, and selected by choosing
##PhabricatorMailImplementationPHPMailerLiteAdapter## as the value for
**metamta.mail-adapter**. This requires a 'sendmail' binary to be installed on
the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your
machine may not have one installed by default. For install instructions, consult
the documentation for your favorite MTA.
Since you'll be sending the mail yourself, you are subject to things like SPF
rules, blackholes, and MTA configuration which are beyond the scope of this
document. If you can already send outbound email from the command line or know
how to configure it, this option is straightforward. If you have no idea how to
do any of this, consider using Amazon SES.
= Adapter: SMTP =
For most situations of using SMTP to send email, you could actually use
'sendmail' or 'postfix' to do it. But some SMTP server requires authentication
and the 'sendmail' mailer doesn't work. If you want to try with postfix, for
install instructions, consult the documentation for postfix as MTA and you
could configure to use SMTP then.
To configure Phabricator to use SMTP, set these configuration keys:
- **metamta.mail-adapter**: set to
"PhabricatorMailImplementationPHPMailerAdapter".
- **phpmailer.mailer**: set to "smtp".
- **phpmailer.smtp-host**: set to hostname of your smtp server.
- **phpmailer.smtp-port**: set to port of your smtp server.
- **phpmailer.smtp-user**: set to your username used for authentication.
- **phpmailer.smtp-password**: set to your password used for authentication.
= Adapter: Amazon SES =
Amazon SES is Amazon's cloud email service. It is not free, but is easier to
configure than sendmail and can simplify outbound email configuration. To use
Amazon SES, you need to sign up for an account with Amazon at
<http://aws.amazon.com/ses/>.
To configure Phabricator to use Amazon SES, set these configuration keys:
- **metamta.mail-adapter**: set to
"PhabricatorMailImplementationAmazonSESAdapter".
- **amazon-ses.access-key**: set to your Amazon SES access key.
- **amazon-ses.secret-key**: set to your Amazon SES secret key.
NOTE: Amazon SES **requires you to verify your "From" address**. Configure which
"From" address to use by setting "##metamta.default-address##" in your config,
then follow the Amazon SES verification process to verify it. You won't be able
to send email until you do this!
NOTE: Amazon SES is slow to accept mail (often 1-2 seconds) and application
performance will improve greatly if you configure outbound email to send in
the background.
= Adapter: SendGrid =
SendGrid is an email delivery service like Amazon SES. You can learn more at
<http://sendgrid.com/>. It is easy to configure, but not free.
You can configure SendGrid in two ways: you can send via SMTP or via the REST
API. To use SMTP, just configure ##sendmail## and leave Phabricator's setup
with defaults. To use the REST API, follow the instructions in this section.
To configure Phabricator to use SendGrid, set these configuration keys:
- **metamta.mail-adapter**: set to
"PhabricatorMailImplementationSendGridAdapter".
- **sendgrid.api-user**: set to your SendGrid login name.
- **sendgrid.api-key**: set to your SendGrid password.
If you're logged into your SendGrid account, you may be able to find this
information easily by visiting <http://sendgrid.com/developer>.
= Adapter: Custom =
You can provide a custom adapter by writing a concrete subclass of
@{class:PhabricatorMailImplementationAdapter} and setting it as the
**metamta.mail-adapter**.
TODO: This needs to be better documented once extending Phabricator is better
documented.
= Adapter: Disable Outbound Mail =
You can use the @{class:PhabricatorMailImplementationTestAdapter} to completely
disable outbound mail, if you don't want to send mail or don't want to configure
it yet. Just set **metamta.mail-adapter** to
"PhabricatorMailImplementationTestAdapter".
= Configuring MetaMTA to Send Mail Using a Daemon =
Regardless of how you are sending outbound email, you can move the handoff to
the MTA out of the main process and into a daemon. This will greatly improve
application performance if your mailer is slow, like Amazon SES. In particular,
commenting on Differential Revisions and Maniphest Tasks sends outbound email.
If you set **metamta.send-immediately** to ##false## in your configuration,
MetaMTA will queue mail to be send by a PhabricatorTaskmasterDaemon.
For more information on using daemons, see @{article:Managing Daemons with phd}.
= Testing and Debugging Outbound Email =
You can use the `bin/mail` utility to test, debug, and examine outbound mail. In
particular:
phabricator/ $ ./bin/mail list-outbound # List outbound mail.
phabricator/ $ ./bin/mail show-outbound # Show details about messages.
phabricator/ $ ./bin/mail send-test # Send test messages.
Run `bin/mail help <command>` for more help on using these commands.
You can monitor daemons using the Daemon Console (##/daemon/##, or click
**Daemon Console** from the homepage).
= Next Steps =
Continue by:
- @{article:Configuring Inbound Email} so users can reply to email they
receive about revisions and tasks to interact with them; or
- learning about daemons with @{article:Managing Daemons with phd}; or
- returning to the @{article:Configuration Guide}.

138
src/docs/user/configuration/managing_daemons.diviner Normal file
View File

@@ -0,0 +1,138 @@
@title Managing Daemons with phd
@group config
Explains Phabricator daemons and the daemon control program ##phd##.
= Overview =
Phabricator uses daemons (background processing scripts) to handle a number of
tasks:
- tracking repositories, discovering new commits, and importing and parsing
commits;
- sending email; and
- collecting garbage, like old logs and caches.
Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
launcher). Daemons can be monitored via a web console.
You do not need to run daemons for most parts of Phabricator to work, but some
features (principally, repository tracking with Diffusion) require them and
several features will benefit in performance or stability if you configure
daemons.
= phd =
**phd** is a command-line script (located at ##phabricator/bin/phd##). To get
a list of commands, run ##phd help##:
phabricator/ $ ./bin/phd help
NAME
phd - phabricator daemon launcher
...
Generally, you will use:
- **phd start** to launch all daemons;
- **phd restart** to restart all daemons;
- **phd status** to get a list of running daemons; and
- **phd stop** to stop all daemons.
If you want finer-grained control, you can use:
- **phd launch** to launch individual daemons; and
- **phd debug** to debug problems with daemons.
NOTE: When you upgrade Phabricator or change configuration, you should restart
the daemons by running `phd restart`.
= Daemon Console =
You can view status and debugging information for daemons in the Daemon Console
via the web interface. Go to ##/daemon/## in your install or click
**Daemon Console** from "More Stuff".
The Daemon Console shows a list of all the daemons that have ever launched, and
allows you to view log information for them. If you have issues with daemons,
you may be able to find error information that will help you resolve the problem
in the console.
NOTE: The easiest way to figure out what's wrong with a daemon is usually to use
**phd debug** to launch it instead of **phd start**. This will run it without
daemonizing it, so you can see output in your console.
= Available Daemons =
You can get a list of launchable daemons with **phd list**:
- **libphutil test daemons** are not generally useful unless you are
developing daemon infrastructure or debugging a daemon problem;
- **PhabricatorTaskmasterDaemon** performs work from a task queue;
- **PhabricatorRepositoryPullLocalDaemon** daemons track repositories, for
more information see @{article:Diffusion User Guide}; and
- **PhabricatorGarbageCollectorDaemon** cleans up old logs and caches.
= Debugging and Tuning =
In most cases, **phd start** handles launching all the daemons you need.
However, you may want to use more granular daemon controls to debug daemons,
launch custom daemons, or launch special daemons like the IRC bot.
To debug a daemon, use `phd debug`:
phabricator/bin/ $ ./phd debug <daemon>
You can pass arguments like this (normal arguments are passed to the daemon
control mechanism, not to the daemon itself):
phabricator/bin/ $ ./phd debug <daemon> -- --flavor apple
In debug mode, daemons do not daemonize, and they print additional debugging
output to the console. This should make it easier to debug problems. You can
terminate the daemon with `^C`.
To launch a nonstandard daemon, use `phd launch`:
phabricator/bin/ $ ./phd launch <daemon>
This daemon will daemonize and run normally.
== General Tips ==
- You can set the number of taskmasters that `phd start` starts by the config
key `phd.start-taskmasters`. If you have a task backlog, try increasing it.
- When you `phd launch` or `phd debug` a daemon, you can type any unique
substring of its name, so `phd launch pull` will work correctly.
- `phd stop` and `phd restart` stop **all** of the daemons on the machine, not
just those started with `phd start`. If you're writing a restart script,
have it launch any custom daemons explicitly after `phd restart`.
- You can write your own daemons and manage them with `phd` by extending
@{class:PhabricatorDaemon}. See @{article:libphutil Libraries User Guide}.
- See @{article:Diffusion User Guide} for details about tuning the repository
daemon.
== Multiple Machines ==
If you have multiple machines, you should use `phd launch` to tweak which
daemons launch, and split daemons across machines like this:
- `PhabricatorRepositoryPullLocalDaemon`: Run one copy on any machine.
On each web frontend which is not running a normal copy, run a copy
with the `--no-discovery` flag.
- `PhabricatorGarbageCollectorDaemon`: Run one copy on any machine.
- `PhabricatorTaskmasterDaemon`: Run as many copies as you need to keep
tasks from backing up. You can run them all on one machine or split them
across machines.
A gratuitously wasteful install might have a dedicated daemon machine which
runs `phd start` with a large pool of taskmasters set in the config, and then
runs `phd launch PhabricatorRepositoryPullLocalDaemon --no-discovery` on each
web server. This is grossly excessive in normal cases.
= Next Steps =
Continue by:
- learning about the repository daemon with @{article:Diffusion User Guide};
or
- writing your own daemons with @{article:libphutil Libraries User Guide}.

74
src/docs/user/configuration/troubleshooting_https.diviner Normal file
View File

@@ -0,0 +1,74 @@
@title Troubleshooting HTTPS
@group config
Detailed instructions for troubleshooting HTTPS connection problems.
= Overview =
If you're having trouble connecting to an HTTPS install of Phabricator, and
particularly if you're receiving a "There was an error negotiating the SSL
connection." error, this document may be able to help you diagnose and resolve
the problem.
Connection negotation can fail for several reasons. The major ones are:
- You have not added the the Certificate Authority as a trusted authority
(this is the most common problem, and usually the issue for self-signed
certificates).
- The SSL certificate is signed for the wrong domain. For example, a
certificate signed for `www.example.com` will not work for
`phabricator.example.com`.
- The server rejects TLSv1 SNI connections for the domain (this is
complicated, see below).
= Certificate Authority Problems =
SSL certificates need to be signed by a trusted authority (called a Certificate
Authority or "CA") to be accepted. If the CA for a certificate is untrusted, the
connection will fail (this defends the connection from an eavesdropping attack
called "man in the middle"). Normally, you purchase a certificate from a known
authority and clients have a list of trusted authorities.
You can self-sign a certificate by creating your own CA, but clients will not trust it by default. They need to add the CA as a trusted authority.
For instructions on adding CAs, see `libphutil/resources/ssl/README`.
Although it is possible to accept certificates that aren't signed by trusted
CAs, this is not currently supported because it compromises the ability of SSL
to protect the connection against eavesdropping.
= Domain Problems =
Verify the domain the certificate was issued for. You can generally do this
with:
$ openssl x509 -text -in <certificate>
If the certificate was accidentally generated for, e.g. `www.example.com` but
you installed Phabricator on `phabricator.example.com`, you need to generate a
new certificate for the right domain.
= SNI Problems =
Server Name Identification ("SNI") is a feature of TLSv1 which works a bit like
Apache VirtualHosts, and allows a server to present different certificates to
clients who are connecting to it using different names.
Servers that are not configured properly may reject TSLv1 SNI requests because
they do not recognize the name the client is connecting with. This
topic is complicated, but you can test for it by running:
$ openssl s_client -connect example.com:443 -servername example.com
Replace **both** instances of "example.com" with your domain. If you receive
an error in `SSL23_GET_SERVER_HELLO` with `reason(1112)`, like this:
CONNECTED(00000003)
87871:error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:reason(1112):
/SourceCache/OpenSSL098/OpenSSL098-44/src/ssl/s23_clnt.c:602:
...it indicates server is misconfigured. The most common cause of this problem
is an Apache server that does not explicitly name the Phabricator domain as a
valid VirtualHost.
This error occurs only for some versions of the OpenSSL client library (from v0.9.8r or earlier until 1.0.0), so only some users may experience it.