Page MenuHomePhorge
Files F2890218

No OneTemporary
Actions

View Options

diff --git a/src/docs/user/userguide/diffusion_hosting.diviner b/src/docs/user/userguide/diffusion_hosting.diviner
index 1639639831..ecf7e1c3e3 100644
--- a/src/docs/user/userguide/diffusion_hosting.diviner
+++ b/src/docs/user/userguide/diffusion_hosting.diviner
@@ -1,374 +1,373 @@
@title Diffusion User Guide: Repository Hosting
@group userguide
Guide to configuring Phabricator repository hosting.
= Overview =
Phabricator can host repositories and provide authenticated read and write
access to them over HTTP and SSH. This document describes how to configure
repository hosting.
= Understanding Supported Protocols =
Phabricator supports hosting over these protocols:
| VCS | SSH | HTTP |
|-----|-----|------|
| Git | Supported | Supported |
| Mercurial | Supported | Supported |
| Subversion | Supported | Not Supported |
All supported protocols handle reads (pull/checkout/clone) and writes
(push/commit). Of the two protocols, SSH is generally more robust, secure and
performant, but HTTP is easier to set up and supports anonymous access.
| | SSH | HTTP |
| |-----|------|
| Reads | Yes | Yes |
| Writes | Yes | Yes |
| Authenticated Access | Yes | Yes |
| Push Logs | Yes | Yes |
| Commit Hooks | Yes | Yes |
| Anonymous Access | No | Yes |
| Security | Better (Asymmetric Key) | Okay (Password) |
| Performance | Better | Okay |
| Setup | Hard | Easy |
Each repository can be configured individually, and you can use either protocol,
or both, or a mixture across different repositories.
SSH is recommended unless you need anonymous access, or are not able to
configure it for technical reasons.
= Configuring System User Accounts =
Phabricator uses as many as three user accounts. This section will guide you
through creating and configuring them. These are system user accounts on the
machine Phabricator runs on, not Phabricator user accounts.
The system accounts are:
- The user the daemons run as. We'll call this `daemon-user`. For more
information on the daemons, see @{article:Managing Daemons with phd}. This
user is the only user which will interact with the repositories directly.
Other accounts will `sudo` to this account in order to perform VCS
operations.
- The user the webserver runs as. We'll call this `www-user`. If you do not
plan to make repositories available over HTTP, you do not need to perform
any special configuration for this user.
- The user that users will connect over SSH as. We'll call this `vcs-user`.
If you do not plan to make repositories available over SSH, you do not need
to perform any special configuration for this user.
To configure these users:
- Create a `daemon-user` if one does not already exist (you can call this user
whatever you want, or use an existing account). When you start the daemons,
start them using this user.
- Create a `www-user` if one does not already exist. Run your webserver as
this user. In most cases, this user will already exist.
- Create a `vcs-user` if one does not already exist. Common names for this
user are `git` or `hg`. When users clone repositories, they will use a URI
like `vcs-user@phabricator.yourcompany.com`.
Now, allow the `vcs-user` and `www-user` to `sudo` as the `daemon-user`. Add
this to `/etc/sudoers`, using `visudo` or `sudoedit`.
If you plan to use SSH:
vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/bin/git-upload-pack, /path/to/bin/git-receive-pack, /path/to/bin/hg, /path/to/bin/svnserve
If you plan to use HTTP:
www-user ALL=(daemon-user) SETENV: NOPASSWD: /usr/bin/git-http-backend, /usr/bin/hg
Replace `vcs-user`, `www-user` and `daemon-user` with the right usernames for
your configuration. Make sure all the paths point to the real locations of the
binaries on your system. You can omit any binaries associated with VCSes you do
not use.
Adding these commands to `sudoers` will allow the daemon and webserver users to
write to repositories as the daemon user.
Before saving and closing `/etc/sudoers`, look for this line:
Defaults requiretty
If it's present, comment it out by putting a `#` at the beginning of the line.
With this option enabled, VCS SSH sessions won't be able to use `sudo`.
If you're planning to use SSH, you should also edit `/etc/passwd` and
`/etc/shadow` to make sure the `vcs-user` account is set up correctly.
- Open `/etc/shadow` and find the line for the `vcs-user` account.
- The second field (which is the password field) must not be set to
`!!`. This value will prevent login. If it is set to `!!`, edit it
and set it to `NP` ("no password") instead.
- Open `/etc/passwd` and find the line for the `vcs-user` account.
- The last field (which is the login shell) must be set to a real shell.
If it is set to something like `/bin/false`, then `sshd` will not be able
to execute commands. Instead, you should set it to a real shell, like
`/bin/sh`.
Finally, once you've configured `/etc/sudoers`, `/etc/shadow` and `/etc/passwd`,
set `phd.user` to the `daemon-user`:
phabricator/ $ ./bin/config set phd.user daemon-user
If you're using a `vcs-user`, you should also configure that here:
phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
= Configuring HTTP =
If you plan to use authenticated HTTP, you need to set
`diffusion.allow-http-auth` in Config. If you don't plan to use HTTP, or plan to
use only anonymous HTTP, you can leave this setting disabled.
If you plan to use authenticated HTTP, you'll also need to configure a VCS
-password in "Settings" -> "VCS Password". This is a different password than
+password in {nav Settings > VCS Password}. This is a different password than
your main Phabricator password primarily for security reasons.
Otherwise, if you've configured system accounts above, you're all set. No
additional server configuration is required to make HTTP work.
= Configuring SSH =
SSH access requires some additional setup. Here's an overview of how setup
works:
- You'll move the normal `sshd` daemon to another port, like `222`. When
connecting to the machine to administrate it, you'll use this alternate
port to get a normal login shell.
- You'll run a highly restricted `sshd` on port 22, with a special locked-down
configuration that uses Phabricator to authorize users and execute commands.
- The `sshd` on port 22 **MUST** be 6.2 or newer, because Phabricator relies
on the `AuthorizedKeysCommand` option.
Here's a walkthrough of how to perform this configuration in detail:
**Move Normal SSHD**: Be careful when editing the configuration for `sshd`. If
you get it wrong, you may lock yourself out of the machine. Restarting `sshd`
generally will not interrupt existing connections, but you should exercise
caution. Two strategies you can use to mitigate this risk are: smoke-test
configuration by starting a second `sshd`; and use a `screen` session which
automatically repairs configuration unless stopped.
To smoke-test a configuration, just start another `sshd` using the `-f` flag:
sudo /path/to/sshd -f /path/to/config_file.edited
You can then connect and make sure the edited config file is valid before
replacing your primary configuration file.
To automatically repair configuration, start a `screen` session with a command
like this in it:
sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart
The specific command may vary for your system, but the general idea is to have
the machine automatically restore configuration after some period of time if
you don't stop it. If you lock yourself out, this will fix things automatically.
Now that you're ready to edit your configuration, open up your `sshd` config
(often `/etc/ssh/sshd_config`) and change the `Port` setting to some other port,
like `222` (you can choose any port other than 22).
Port 222
Very carefully, restart `sshd`. Verify that you can connect on the new port:
ssh -p 222 ...
**Configure and Start Phabricator SSHD**: Now, configure and start a second
`sshd` instance which will run on port `22`. This instance will use a special
locked-down configuration that uses Phabricator to handle authentication and
command execution.
There are three major steps:
- Create a `phabricator-ssh-hook.sh` file.
- Create a `sshd_phabricator` config file.
- Start a copy of `sshd` using the new configuration.
**Create `phabricator-ssh-hook.sh`**: Copy the template in
`phabricator/resources/sshd/phabricator-ssh-hook.sh` to somewhere like
`/usr/libexec/phabricator-ssh-hook.sh` and edit it to have the correct
settings. Then make it owned by `root` and restrict editing:
sudo chown root /path/to/phabricator-ssh-hook.sh
sudo chmod 755 /path/to/phabricator-ssh-hook.sh
If you don't do this, `sshd` will refuse to execute the hook.
**Create `sshd_config` for Phabricator**: Copy the template in
`phabricator/resources/sshd/sshd_config.phabricator.example` to somewhere like
`/etc/ssh/sshd_config.phabricator`.
Open the file and edit the `AuthorizedKeysCommand`,
`AuthorizedKeysCommandUser`, and `AllowUsers` settings to be correct for your
system.
**Start SSHD**: Now, start the Phabricator `sshd`:
sudo /path/to/sshd -f /path/to/sshd_config.phabricator
If you did everything correctly, you should be able to run this:
echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
...and get a response like this:
{"result":"orbital","error_code":null,"error_info":null}
(If you get an authentication error, make sure you added your public key in
**Settings > SSH Public Keys**.) If you're having trouble, check the
troubleshooting section below.
= Authentication Over HTTP =
To authenticate over HTTP, users should configure a **VCS Password** in the
**Settings** screen. This panel is available only if `diffusion.allow-http-auth`
is enabled.
= Authentication Over SSH =
To authenticate over SSH, users should add **SSH Public Keys** in the
**Settings** screen.
= Cloning a Repository =
If you've already set up a hosted repository, you can try cloning it now. To
do this, browse to the repository's main screen in Diffusion. You should see
clone commands at the top of the page.
To clone the repository, just run the appropriate command.
If you don't see the commands or running them doesn't work, see below for tips
on troubleshooting.
= Troubleshooting HTTP =
Some general tips for troubleshooting problems with HTTP:
- Make sure `diffusion.allow-http-auth` is enabled in your Phabricator config.
- Make sure HTTP serving is enabled for the repository you're trying to clone.
- You can find this in "Edit Repository" -> "Hosting".
+ You can find this in {nav Edit Repository > Hosting}.
- Make sure you've configured a VCS password. This is separate from your main
- account password. You can configure this in "Settings" -> "VCS Password".
+ account password. You can configure this in {nav Settings > VCS Password}.
- Make sure the main repository screen in Diffusion shows a clone/checkout
command for HTTP. If it doesn't, something above isn't set up correctly:
double-check your configuration. You should see a `svn checkout http://...`,
`git clone http://...` or `hg clone http://...` command. Run that command
verbatim to clone the repository.
If you're using Git, using `GIT_CURL_VERBOSE` may help assess login failures.
To do so, specify it on the command line before the `git clone` command, like
this:
$ GIT_CURL_VERBOSE=1 git clone ...
This will make `git` print out a lot more information. Particularly, the line
with the HTTP response is likely to be useful:
< HTTP/1.1 403 Invalid credentials.
In many cases, this can give you more information about what's wrong.
= Troubleshooting SSH =
Some general tips for troubleshooting problems with SSH:
- Check that you've configured `diffusion.ssh-user`.
- Check that you've configured `phd.user`.
- Make sure SSH serving is enabled for the repository you're trying to clone.
You can change this setting from a main repository screen in Diffusion by
{nav Edit Repository >
Edit Hosting >
Host Repository on Phabricator >
Save and Continue >
SSH Read Only or Read/Write >
Save Changes}.
- Make sure you've added an SSH public key to your account. You can do this
- in {nav Settings >
- SSH Public Keys}.
+ in {nav Settings > SSH Public Keys}.
- Make sure the main repository screen in Diffusion shows a clone/checkout
command for SSH. If it doesn't, something above isn't set up correctly.
You should see an `svn checkout svn+ssh://...`, `git clone ssh://...` or
`hg clone ssh://...` command. Run that command verbatim to clone the
repository.
- Check your `phabricator-ssh-hook.sh` file for proper settings.
- Check your `sshd_config.phabricator` file for proper settings.
To troubleshoot SSH setup: connect to the server with `ssh`, without running
a command. You may need to use the `-T` flag. You should see a message like
this one:
$ ssh -T dweller@secure.phabricator.com
phabricator-ssh-exec: Welcome to Phabricator.
You are logged in as alincoln.
You haven't specified a command to run. This means you're requesting an
interactive shell, but Phabricator does not provide an interactive shell over
SSH.
Usually, you should run a command like `git clone` or `hg push` rather than
connecting directly with SSH.
Supported commands are: conduit, git-receive-pack, git-upload-pack, hg,
svnserve.
If you see this message, all your SSH stuff is configured correctly. **If you
get a login shell instead, you've missed some major setup step: review the
documentation above.** If you get some other sort of error, double check these
settings:
- You're connecting as the `vcs-user`.
- The `vcs-user` has `NP` in `/etc/shadow`.
- The `vcs-user` has `/bin/sh` or some other valid shell in `/etc/passwd`.
- Your SSH key is correct, and you've added it to Phabricator in the Settings
panel.
If you can get this far, but can't execute VCS commands like `git clone`, there
is probably an issue with your `sudoers` configuration. Check:
- Your `sudoers` file is set up as instructed above.
- You've commented out `Defaults requiretty` in `sudoers`.
- You don't have multiple copies of the VCS binaries (like `git-upload-pack`)
on your system. You may have granted sudo access to one, while the VCS user
is trying to run a different one.
- You've configured `phd.user`.
- The `phd.user` has read and write access to the repositories.
It may also be helpful to run `sshd` in debug mode:
$ /path/to/sshd -d -d -d -f /path/to/sshd_config.phabricator
This will run it in the foreground and emit a large amount of debugging
information.
Finally, you can usually test that `sudoers` is configured correctly by
doing something like this:
$ su vcs-user
$ sudo -E -n -u daemon-user -- /path/to/some/vcs-binary --help
That will try to run the binary via `sudo` in a manner similar to the way that
Phabricator will run it. This can give you better error messages about issues
with `sudoers` configuration.
= Miscellaneous Troubleshooting =
- If you're getting an error about `svnlook` not being found, add the path
where `svnlook` is located to the Phabricator configuration
`environment.append-paths` (even if it already appears in PATH). This issue
is caused by SVN wiping the environment (including PATH) when invoking
commit hooks.
= Next Steps =
Once hosted repositories are set up:
- learn about commit hooks with @{article:Diffusion User Guide: Commit Hooks}.
diff --git a/src/docs/user/userguide/diffusion_symbols.diviner b/src/docs/user/userguide/diffusion_symbols.diviner
index b9b96ec209..0a212055d5 100644
--- a/src/docs/user/userguide/diffusion_symbols.diviner
+++ b/src/docs/user/userguide/diffusion_symbols.diviner
@@ -1,95 +1,95 @@
@title Diffusion User Guide: Symbol Indexes
@group userguide
Guide to configuring and using the symbol index.
= Overview =
Phabricator can maintain a symbol index, which keeps track of where classes
and functions are defined in the codebase. Once you set up indexing, you can
use the index to do things like:
- link symbol uses in Differential code reviews to their definitions
- allow you to search for symbols
- let the IRC bot answer questions like "Where is SomeClass?"
NOTE: Symbol indexing is somewhat new, and has broader support for PHP than for
other languages.
= Populating the Index =
To populate the index, you need to write a script which identifies symbols in
your codebase and set up a cronjob which pipes its output to:
./scripts/symbols/import_project_symbols.php
Phabricator includes a script which can identify symbols in PHP projects:
./scripts/symbols/generate_php_symbols.php
Phabricator also includes a script which can identify symbols in any
programming language that has classes and/or functions, and is supported by
Exuberant Ctags (http://ctags.sourceforge.net):
./scripts/symbols/generate_ctags_symbols.php
If you want to identify symbols from another language, you need to write a
script which can export them (for example, maybe by parsing a ##ctags## file).
The output format of the script should be one symbol per line:
<context> <name> <type> <lang> <line> <path>
For example:
ExampleClass exampleMethod function php 13 /src/classes/ExampleClass.php
Context is, broadly speaking, the scope or namespace where the symbol is
defined. For object-oriented languages, this is probably a class name. The
symbols with that context are class constants, methods, properties, nested
classes, etc. When printing symbols without a context (those that are defined
globally, for instance), the ##<context>## field should be empty (that is, the
line should start with a space).
Your script should enumerate all the symbols in your project, and provide paths
from the project root (where ".arcconfig" is) beginning with a "/".
You can look at ##generate_php_symbols.php## for an example of how you might
write such a script, and run this command to see its output:
$ cd phabricator/
$ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
To actually build the symbol index, pipe this data to the
`import_project_symbols.php` script, providing the project name:
$ ./scripts/symbols/import_project_symbols.php yourproject < symbols_data
Then just set up a cronjob to run that however often you like.
You can test that the import worked by querying for symbols using the Conduit
method ##differential.findsymbols##. Some features (like that method, and the
IRC bot integration) will start working immediately. Others will require more
configuration.
= Configuring Differential Integration =
To configure Differential integration, you need to tell Phabricator which
projects have symbol indexes you want to use, and which other projects they
should pull symbols from. To do this, go to
-`Repositories -> Arcanist Projects -> Edit` as an administrator. You need to
+{nav Repositories > Arcanist Projects > Edit} as an administrator. You need to
fill out these fields:
- **Repository**: Associate the project with a tracked repository.
- **Indexed Languages**: Fill in all the languages you've built indexes for.
- **Uses Symbols From**: If this project depends on other projects, add the
other projects which symbols should be looked for here. For example,
Phabricator lists "Arcanist" and "libphutil" because it uses classes and
functions from these projects.
Once you've configured a project, new revisions in that project will
automatically link symbols in Differential.
NOTE: Because this feature depends on the syntax highlighter, it will work
better for some languages than others. It currently works fairly well for PHP,
but your mileage may vary for other languages.
diff --git a/src/docs/user/userguide/external_editor.diviner b/src/docs/user/userguide/external_editor.diviner
index 675ed7eb1f..c98ccb1903 100644
--- a/src/docs/user/userguide/external_editor.diviner
+++ b/src/docs/user/userguide/external_editor.diviner
@@ -1,51 +1,51 @@
@title User Guide: Configuring an External Editor
@group userguide
Setting up an external editor to integrate with Diffusion and Differential.
= Overview =
You can configure a URI handler to allow you to open files from Differential
and Diffusion in your preferred text editor.
= Configuring Editors =
-To configure an external editor, go to Settings -> Application Settings ->
-Display Preferences and set "Editor Link" to a URI pattern (see below). This
+To configure an external editor, go to {nav Settings > Application Settings >
+Display Preferences} and set "Editor Link" to a URI pattern (see below). This
will enable an "Open in Editor" link in Differential, and an "Edit" button in
Diffusion.
In general, you'll set this field to something like:
lang=uri
editor://open/?file=%f
Some editors support opening multiple files at once when filenames are separated
by spaces. If your editor supports this feature, set "Edit Multiple Files" to
"Supported". Otherwise, you can set it to "Not Supported" to disable "Open All"
buttons in the interface.
== Configuring: TextMate on OS X ==
TextMate installs a ##txmt://## handler by default, so it's easy to configure
this feature if you use TextMate.
First, create a local directory with symlinks for each repository callsign. For
example, if you're developing Phabricator, it might look like this:
/Users/alincoln/editor_links/ $ ls -l
... ARC -> /Users/alincoln/workspace/arcanist/
... P -> /Users/alincoln/workspace/phabricator/
... PHU -> /Users/alincoln/workspace/libphutil/
Then set your "Editor Link" to:
lang=uri
txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l
== Configuring: Other Editors ==
General instructions for configuring some other editors and environments can be
found here:
http://wiki.nette.org/en/howto-editor-link
diff --git a/src/docs/user/userguide/mail_rules.diviner b/src/docs/user/userguide/mail_rules.diviner
index cc0860a1ae..64d0723fdb 100644
--- a/src/docs/user/userguide/mail_rules.diviner
+++ b/src/docs/user/userguide/mail_rules.diviner
@@ -1,81 +1,81 @@
@title User Guide: Managing Phabricator Email
@group userguide
How to effectively manage Phabricator email notifications.
= Overview =
Phabricator uses email as a major notification channel, but the amount of email
it sends can seem overwhelming if you're working on an active team. This
document discusses some strategies for managing email.
By far the best approach to managing mail is to **write mail rules** to
categorize mail. Essentially all modern mail clients allow you to quickly
write sophisticated rules to route, categorize, or delete email.
= Reducing Email =
You can reduce the amount of email you receive by turning off some types of
-email in ##Settings -> Email Preferences##. For example, you can turn off email
+email in {nav Settings > Email Preferences}. For example, you can turn off email
produced by your own actions (like when you comment on a revision), and some
types of less-important notifications about events.
= Mail Rules =
The best approach to managing mail is to write mail rules. Simply writing rules
to move mail from Differential, Maniphest and Herald to separate folders will
vastly simplify mail management.
Phabricator also sets a large number of headers (see below) which can allow you
to write more sophisticated mail rules.
= Mail Headers =
Phabricator sends a variety of mail headers that can be useful in crafting rules
to route and manage mail.
Headers in plural contain lists. A list containing two items, ##1## and
`15` will generally be formatted like this:
X-Header: <1>, <15>
The intent is to allow you to write a rule which matches against "<1>". If you
just match against "1", you'll incorrectly match "15", but matching "<1>" will
correctly match only "<1>".
Some other headers use a single value but can be presented multiple times.
It is to support e-mail clients which are not able to create rules using regular
expressions or wildcards (namely Outlook).
The headers Phabricator adds to mail are:
- ##X-Phabricator-Sent-This-Message##: this is attached to all mail
Phabricator sends. You can use it to differentiate between email from
Phabricator and replies/forwards of Phabricator mail from human beings.
- ##X-Phabricator-To##: this is attached to all mail Phabricator sends.
It shows the PHIDs of the original "To" line, before any mutation
by the mailer configuration.
- ##X-Phabricator-Cc##: this is attached to all mail Phabricator sends.
It shows the PHIDs of the original "Cc" line, before any mutation by the
mailer configuration.
- ##X-Differential-Author##: this is attached to Differential mail and shows
the revision's author. You can use it to filter mail about your revisions
(or other users' revisions).
- ##X-Differential-Reviewer##: this is attached to Differential mail and
shows the reviewers. You can use it to filter mail about revisions you
are reviewing, versus revisions you are explicitly CC'd on or CC'd as
a result of Herald rules.
- ##X-Differential-Reviewers##: list version of the previous.
- ##X-Differential-CC##: this is attached to Differential mail and shows
the CCs on the revision.
- ##X-Differential-CCs##: list version of the previous.
- ##X-Differential-Explicit-CC##: this is attached to Differential mail and
shows the explicit CCs on the revision (those that were added by humans,
not by Herald).
- ##X-Differential-Explicit-CCs##: list version of the previous.
- ##X-Phabricator-Mail-Tags##: this is attached to some mail and has
a list of descriptors about the mail. (This is fairly new and subject
to some change.)
- ##X-Herald-Rules##: this is attached to some mail and shows Herald rule
IDs which have triggered for the object. You can use this to sort or
categorize mail that has triggered specific rules.

File Metadata

Mime Type
text/x-diff
Expires
Sun, Jan 19, 13:13 (3 w, 3 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1124957
Default Alt Text
(26 KB)

Event Timeline

Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0