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: