Page MenuHomePhabricator
Files F14043446

D15796.diff
No OneTemporary
Actions

D15796.diff
View Options

diff --git a/resources/sshd/sshd_config.phabricator.example b/resources/sshd/sshd_config.phabricator.example
--- a/resources/sshd/sshd_config.phabricator.example
+++ b/resources/sshd/sshd_config.phabricator.example
@@ -10,7 +10,7 @@
# You may need to tweak these options, but mostly they just turn off everything
# dangerous.
-Port 22
+Port 2222
Protocol 2
PermitRootLogin no
AllowAgentForwarding no
diff --git a/src/docs/user/userguide/diffusion_hosting.diviner b/src/docs/user/userguide/diffusion_hosting.diviner
--- a/src/docs/user/userguide/diffusion_hosting.diviner
+++ b/src/docs/user/userguide/diffusion_hosting.diviner
@@ -3,13 +3,15 @@
Guide to configuring Phabricator repository hosting.
-= Overview =
+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 =
+Understanding Supported Protocols
+=================================
Phabricator supports hosting over these protocols:
@@ -35,99 +37,165 @@
| 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.
+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.
+Creating System User Accounts
+=============================
-The system accounts are:
+Phabricator uses two system user accounts, plus a third account if you
+configure SSH access. 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 user the daemons run as. We'll call this `daemon-user`. For more
- information on the daemons, see @{article:Managing Daemons with phd}. This
+The system accounts Phabricator uses are:
+
+ - The user the webserver runs as. We'll call this `www-user`.
+ - The user the daemons run as. We'll call this `daemon-user`. 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
+ Other accounts will `sudo` to this account in order to perform repository
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`.
+ - The user that humans 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 create or configure this user.
-To configure these users:
+To create these users:
+ - Create a `www-user` if one does not already exist. In most cases, this
+ user will already exist and you just need to identify which user it is. Run
+ your webserver as this user.
- 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`.
+ whatever you want, or use an existing account). Below, you'll configure
+ the daemons to start as this user.
+ - Create a `vcs-user` if one does not already exist and you plan to set up
+ SSH. When users clone repositories, they will use a URI like
+ `vcs-user@phabricator.yourcompany.com`, so common names for this user are
+ `git` or `hg`.
+
+Continue below to configure these accounts.
+
+
+Configuring Phabricator
+=======================
+
+Now that you have created or identified these accounts, update the Phabricator
+configuration to specify them.
+
+First, set `phd.user` to the `daemon-user`:
-Now, allow the `vcs-user` and `www-user` to `sudo` as the `daemon-user`. Add
-this to `/etc/sudoers`, using `visudo` or `sudoedit`.
+```
+phabricator/ $ ./bin/config set phd.user daemon-user
+```
+
+Restart the daemons to make sure this configuration works properly. They should
+start as the correct user automatically.
-If you plan to use SSH:
+If you're using a `vcs-user` for SSH, you should also configure that:
- 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
+```
+phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
+```
-If you plan to use HTTP:
+Next, you'll set up `sudo` permissions so these users can interact with one
+another.
- 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.
+Configuring Sudo
+================
-Adding these commands to `sudoers` will allow the daemon and webserver users to
-write to repositories as the daemon user.
+The `www-user` and `vcs-user` need to be able to `sudo` as the `daemon-user`
+so they can interact with repositories.
-Before saving and closing `/etc/sudoers`, look for this line:
+To grant them access, edit the `sudo` system configuration. On many systems,
+you will do this by modifying the `/etc/sudoers` file using `visudo` or
+`sudoedit`. In some cases, you may add a new file to `/etc/sudoers.d` instead.
+
+To give a user account `sudo` access to run a list of binaries, add a line like
+this to the configuration file (this example would grant `vcs-user` permission
+to run `ls` as `daemon-user`):
+
+```
+vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/bin/ls
+```
+
+The `www-user` needs to be able to run these binaries as the `daemon-user`:
+
+ - `git` (if using Git)
+ - `git-http-backend` (if using Git)
+ - `hg` (if using Mercurial)
+ - `ssh` (if configuring clusters)
+
+If you plan to use SSH, the `vcs-user` needs to be able to run these binaries
+as the `daemon-user`:
+
+ - `git` (if using Git)
+ - `git-upload-pack` (if using Git)
+ - `git-receive-pack` (if using Git)
+ - `hg` (if using Mercurial)
+ - `svnserve` (if using Subversion)
+ - `ssh` (if configuring clusters)
+
+Identify the full paths to all of these binaries on your system and add the
+appropriate permissions to the `sudo` configuration.
+
+Normally, you'll add two lines that look something like this:
+
+```
+www-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...
+vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...
+```
+
+This is just a template. In the real configuration file, you need to:
+
+ - Replace `www-user`, `dameon-user` and `vcs-user` with the correct
+ usernames for your system.
+ - List every binary that these users need access to, as described above.
+ - Make sure each binary path is the full path to the correct binary location
+ on your system.
+
+Before continuing, look for this line in your `sudo` configuration:
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`.
+
+Additional SSH User Configuration
+=================================
+
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`.
+**`/etc/shadow`**: Open `/etc/shadow` and find the line for the `vcs-user`
+account.
-Finally, once you've configured `/etc/sudoers`, `/etc/shadow` and `/etc/passwd`,
-set `phd.user` to the `daemon-user`:
+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.
- phabricator/ $ ./bin/config set phd.user daemon-user
+**`/etc/passwd`**: Open `/etc/passwd` and find the line for the `vcs-user`
+account.
-If you're using a `vcs-user`, you should also configure that here:
+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`.
- phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
-= Configuring HTTP =
+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 serve repositories over authenticated HTTP, you need to set
+`diffusion.allow-http-auth` in Config. If you don't plan to serve repositories
+over 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 {nav Settings > VCS Password}.
+If you plan to use authenticated HTTP, you (and all other users) also need to
+configure a VCS password for your account in {nav Settings > VCS Password}.
Your VCS password must be a different password than your main Phabricator
password because VCS passwords are very easy to accidentally disclose. They are
@@ -136,60 +204,58 @@
instead of HTTP to authenticate access to repositories.
Otherwise, if you've configured system accounts above, you're all set. No
-additional server configuration is required to make HTTP work.
-
-= Configuring SSH =
+additional server configuration is required to make HTTP work. You should now
+be able to fetch and push repositories over HTTP. See "Cloning a Repository"
+below for more details.
-SSH access requires some additional setup. Here's an overview of how setup
-works:
+If you're having trouble, see "Troubleshooting HTTP" below.
- - 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:
+Configuring SSH
+===============
-**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:
+SSH access requires some additional setup. You will configure and run a second,
+restricted copy of `sshd` on the machine, on a different port from the standard
+`sshd`. This special copy of `sshd` will serve repository requests and provide
+other Phabricator SSH services.
- sudo /path/to/sshd -f /path/to/config_file.edited
+NOTE: The Phabricator `sshd` service **MUST** be 6.2 or newer, because
+Phabricator relies on the `AuthorizedKeysCommand` option.
-You can then connect and make sure the edited config file is valid before
-replacing your primary configuration file.
+**Choose a Port**: These instructions will configure the alternate `sshd` on
+port `2222`. This is easy to configure, but if you run the service on this port
+users will clone and push to URIs like `ssh://git@host.com:2222/`, which is
+a little ugly.
-To automatically repair configuration, start a `screen` session with a command
-like this in it:
+The easiest way to fix this is to put a load balancer in front of the host and
+have it forward TCP traffic on port `22` to port `2222`. Then users can clone
+from `ssh://git@host.com/` without an explicit port number and you don't need
+to do anything else.
- sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart
+Alternatively, you can move the administrative `sshd` to a new port, then run
+Phabricator `sshd` on port 22. This is complicated and risky. See "Moving the
+sshd Port" below for help.
-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.
+Finally, you can just run on port `2222` and accept the explicit port in the
+URIs. This is the simplest approach, and you can start here and clean things
+up later.
-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).
+If you plan to connect to a port other than `22`, you should set this port
+as `diffusion.ssh-port` in your Phabricator config:
- Port 222
+```
+$ ./bin/config set diffusion.ssh-port 2222
+```
-Very carefully, restart `sshd`. Verify that you can connect on the new port:
+This port is not special, and you are free to choose a different port, provided
+you make the appropriate configuration adjustment below.
- ssh -p 222 ...
+**Configure and Start Phabricator SSHD**: Now, you'll configure and start a
+copy of `sshd` which will serve Phabricator services, including repositories,
+over SSH.
-**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.
+This instance will use a special locked-down configuration that uses
+Phabricator to handle authentication and command execution.
There are three major steps:
@@ -221,34 +287,38 @@
`AuthorizedKeysCommandUser`, and `AllowUsers` settings to be correct for your
system.
+This configuration file also specifies the `Port` the service should run on.
+If you intend to run on a non-default port, adjust it now.
+
**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:
+If you did everything correctly, you should be able to run this command:
- echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
+```
+$ echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
+```
...and get a response like this:
- {"result":"orbital","error_code":null,"error_info":null}
+```lang=json
+{"result":"phabricator.yourcompany.com","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
+If you get an authentication error, make sure you added your public key in
+{nav Settings > SSH Public Keys}. If you're having trouble, check the
troubleshooting section below.
-= Authentication Over HTTP =
+Authentication Over SSH
+=======================
-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.
+To authenticate over SSH, users should add their public keys under
+{nav Settings > SSH Public Keys}.
-= Authentication Over SSH =
-To authenticate over SSH, users should add **SSH Public Keys** in the
-**Settings** screen.
-
-= Cloning a Repository =
+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
@@ -259,13 +329,15 @@
If you don't see the commands or running them doesn't work, see below for tips
on troubleshooting.
-= Troubleshooting HTTP =
+
+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 {nav Edit Repository > Hosting}.
+ - Make sure HTTP serving is enabled for the repository you're trying to
+ clone. 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 {nav Settings > VCS Password}.
- Make sure the main repository screen in Diffusion shows a clone/checkout
@@ -287,7 +359,8 @@
In many cases, this can give you more information about what's wrong.
-= Troubleshooting SSH =
+Troubleshooting SSH
+===================
Some general tips for troubleshooting problems with SSH:
@@ -311,11 +384,11 @@
- 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:
+To troubleshoot SSH setup: connect to the server with `ssh`, without running a
+command. You may need to use the `-T` flag, and will need to use `-p` if you
+are running on a nonstandard port. You should see a message like this one:
- $ ssh -T dweller@secure.phabricator.com
+ $ ssh -T -p 2222 vcs-user@phabricator.yourcompany.com
phabricator-ssh-exec: Welcome to Phabricator.
You are logged in as alincoln.
@@ -338,8 +411,8 @@
- 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.
+ - Your SSH private key is correct, and you've added the corresponding
+ public key 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:
@@ -357,7 +430,7 @@
$ /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.
+information when you connect to it.
Finally, you can usually test that `sudoers` is configured correctly by
doing something like this:
@@ -369,7 +442,9 @@
Phabricator will run it. This can give you better error messages about issues
with `sudoers` configuration.
-= Miscellaneous Troubleshooting =
+
+Miscellaneous Troubleshooting
+=============================
- If you're getting an error about `svnlook` not being found, add the path
where `svnlook` is located to the Phabricator configuration
@@ -377,6 +452,54 @@
is caused by SVN wiping the environment (including PATH) when invoking
commit hooks.
+
+Moving the sshd Port
+====================
+
+If you want to move the standard (administrative) `sshd` to a different port to
+make Phabricator repository URIs cleaner, this section has some tips.
+
+This is optional, and it is normally easier to do this by putting a load
+balancer in front of Phabricator and having it accept TCP traffic on port 22
+and forward it to some other port.
+
+When moving `sshd`, be careful when editing the configuration. 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 can 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 ...
+
+Now you can move the Phabricator `sshd` to port 22, then adjust the value
+for `diffusion.ssh-port` in your Phabricator configuration.
+
+
No Direct Pushes
================
@@ -412,7 +535,8 @@
request did not pass through Phabricator.
-= Next Steps =
+Next Steps
+==========
Once hosted repositories are set up:

File Metadata

Mime Type
text/plain
Expires
Wed, Nov 13, 10:14 AM (5 d, 7 h ago)
Storage Engine
blob
Storage Format
Encrypted (AES-256-CBC)
Storage Handle
6713335
Default Alt Text
D15796.diff (22 KB)

Event Timeline

Phabricator · Built by Phacility