|
| 1 | +@title Diffusion User Guide: Repository Hosting |
| 2 | +@group userguide |
| 3 | + |
| 4 | +Guide to configuring Phabricator repository hosting. |
| 5 | + |
| 6 | += Overview = |
| 7 | + |
| 8 | +Phabricator can host repositories and provide authenticated read and write |
| 9 | +access to them over HTTP and SSH. This document describes how to configure |
| 10 | +repository hosting. |
| 11 | + |
| 12 | +NOTE: This feature is new and has some rough edges. Let us know if you run into |
| 13 | +issues (see @{article:Give Feedback! Get Support!}). |
| 14 | + |
| 15 | += Understanding Supported Protocols = |
| 16 | + |
| 17 | +Phabricator supports hosting over these protocols: |
| 18 | + |
| 19 | +| VCS | SSH | HTTP | |
| 20 | +|-----|-----|------| |
| 21 | +| Git | Supported | Supported | |
| 22 | +| Mercurial | Supported | Supported | |
| 23 | +| Subversion | Supported | Not Supported | |
| 24 | + |
| 25 | +All supported protocols handle reads (pull/checkout/clone) and writes |
| 26 | +(push/commit). Of the two protocols, SSH is generally more robust, secure and |
| 27 | +performant, but HTTP is easier to set up and supports anonymous access. |
| 28 | + |
| 29 | +| | SSH | HTTP | |
| 30 | +| |-----|------| |
| 31 | +| Reads | Yes | Yes | |
| 32 | +| Writes | Yes | Yes | |
| 33 | +| Authenticated Access | Yes | Yes | |
| 34 | +| Anonymous Access | No | Yes | |
| 35 | +| Security | Better (Asymetric Key) | Okay (Password) | |
| 36 | +| Performance | Better | Okay | |
| 37 | +| Setup | Hard | Easy | |
| 38 | + |
| 39 | +Each repository can be configured individually, and you can use either protocol, |
| 40 | +or both, or a mixture across different repositories. |
| 41 | + |
| 42 | +SSH is recommended unless you need anonymous access, or are not able to |
| 43 | +configure it for technical reasons. |
| 44 | + |
| 45 | += Configuring System User Accounts = |
| 46 | + |
| 47 | +Phabricator uses as many as three user accounts. This section will guide you |
| 48 | +through creating and configuring them. These are system user accounts on the |
| 49 | +machine Phabricator runs on, not Phabricator user accounts. |
| 50 | + |
| 51 | +The system accounts are: |
| 52 | + |
| 53 | + - The user the daemons run as. We'll call this `daemon-user`. For more |
| 54 | + information on the daemons, see @{article:Managing Daemons with phd}. |
| 55 | + - The user the webserver runs as. We'll call this `www-user`. If you do not |
| 56 | + plan to make repositories available over HTTP, you do not need to perform |
| 57 | + any special configuration for this user. |
| 58 | + - The user that users will connect over SSH as. We'll call this `vcs-user`. |
| 59 | + If you do not plan to make repositories available over SSH, you do not need |
| 60 | + to perform any special configuration for this user. |
| 61 | + |
| 62 | +To configure these users: |
| 63 | + |
| 64 | + - Create a `daemon-user` if one does not already exist (you can call this user |
| 65 | + whatever you want, or use an existing account). When you start the daemons, |
| 66 | + start them using this user. |
| 67 | + - Create a `www-user` if one does not already exist. Run your webserver as |
| 68 | + this user. In most cases, this user will already exist. |
| 69 | + - Create a `vcs-user` if one does not already exist. Common names for this |
| 70 | + user are `git` or `hg`. When users clone repositories, they will use a URI |
| 71 | + like `vcs-user@phabricator.yourcompany.com`. |
| 72 | + |
| 73 | +Now, allow the `vcs-user` and `www-user` to `sudo` as the `daemon-user`. Add |
| 74 | +this to `/etc/sudoers`, using `visudo` or `sudoedit`. |
| 75 | + |
| 76 | +If you plan to use SSH: |
| 77 | + |
| 78 | + 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 |
| 79 | + |
| 80 | +If you plan to use HTTP: |
| 81 | + |
| 82 | + www-user ALL=(daemon-user) SETENV: NOPASSWD: /usr/bin/git-http-backend, /usr/bin/hg |
| 83 | + |
| 84 | +Replace `vcs-user`, `www-user` and `daemon-user` with the right usernames for |
| 85 | +your configuration. Make sure all the paths point to the real locations of the |
| 86 | +binaries on your system. You can omit any binaries associated with VCSes you do |
| 87 | +not use. |
| 88 | + |
| 89 | +Adding these commands to `sudoers` will allow the daemon and webserver users to |
| 90 | +write to repositories as the daemon user. |
| 91 | + |
| 92 | +Finally, once you've configured `sudoers`, set `phd.user` to the `daemon-user`: |
| 93 | + |
| 94 | + phabricator/ $ ./bin/config set phd.user daemon-user |
| 95 | + |
| 96 | += Configuring HTTP = |
| 97 | + |
| 98 | +If you plan to use authenticated HTTP, you need to set |
| 99 | +`diffusion.allow-http-auth` in Config. If you don't plan to use HTTP, or plan to |
| 100 | +use only anonymous HTTP, you can leave this setting disabled. |
| 101 | + |
| 102 | +Otherwise, if you've configured system accounts above, you're all set. No |
| 103 | +additional server configuration is required to make HTTP work. |
| 104 | + |
| 105 | += Configuring SSH = |
| 106 | + |
| 107 | +SSH access requires some additional setup. Here's an overview of how setup |
| 108 | +works: |
| 109 | + |
| 110 | + - You'll move the normal `sshd` daemon to another port, like `222`. When |
| 111 | + connecting to the machine to administrate it, you'll use this alternate |
| 112 | + port. |
| 113 | + - You'll run a highly restricted `sshd` on port 22, with a special locked-down |
| 114 | + configuration that uses Phabricator to authorize users and execute commands. |
| 115 | + - The `sshd` on port 22 **MUST** be 6.2 or newer, because Phabricator relies |
| 116 | + on the `AuthorizedKeysCommand` option. |
| 117 | + |
| 118 | +Here's a walkthrough of how to perform this configuration in detail: |
| 119 | + |
| 120 | +**Move Normal SSHD**: Be careful when editing the configuration for `sshd`. If |
| 121 | +you get it wrong, you may lock yourself out of the machine. Restarting `sshd` |
| 122 | +generally will not interrupt existing connections, but you should exercise |
| 123 | +caution. Two strategies you can use to mitigate this risk are: smoke-test |
| 124 | +configuration by starting a second `sshd`; and use a `screen` session which |
| 125 | +automatically repairs configuration unless stopped. |
| 126 | + |
| 127 | +To smoke-test a configuration, just start another `sshd` using the `-f` flag: |
| 128 | + |
| 129 | + sudo sshd -f /path/to/config_file.edited |
| 130 | + |
| 131 | +You can then connect and make sure the edited config file is valid before |
| 132 | +replacing your primary configuration file. |
| 133 | + |
| 134 | +To automatically repair configuration, start a `screen` session with a command |
| 135 | +like this in it: |
| 136 | + |
| 137 | + sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart |
| 138 | + |
| 139 | +The specific command may vary for your system, but the general idea is to have |
| 140 | +the machine automatically restore configuration after some period of time if |
| 141 | +you don't stop it. If you lock yourself out, this will fix things automatically. |
| 142 | + |
| 143 | +Now that you're ready to edit your configuration, open up your `sshd` config |
| 144 | +(often `/etc/ssh/sshd_config`) and change the `Port` setting to some other port, |
| 145 | +like `222` (you can choose any port other than 22). |
| 146 | + |
| 147 | + Port 222 |
| 148 | + |
| 149 | +Very carefully, restart `sshd`. Verify that you can connect on the new port: |
| 150 | + |
| 151 | + ssh -p 222 ... |
| 152 | + |
| 153 | +**Configure and Start Phabricator SSHD**: Now, configure and start a second |
| 154 | +`sshd` instance which will run on port `22`. This instance will use a special |
| 155 | +locked-down configuration that uses Phabricator to handle authentication and |
| 156 | +command execution. |
| 157 | + |
| 158 | +There are three major steps: |
| 159 | + |
| 160 | + - Create a `phabricator-ssh-hook.sh` file. |
| 161 | + - Create a `sshd_phabricator` config file. |
| 162 | + - Start a copy of `sshd` using the new configuration. |
| 163 | + |
| 164 | +**Create `phabricator-ssh-hook.sh`**: Copy the template in |
| 165 | +`phabricator/resources/sshd/phabricator-ssh-hook.sh` to somewhere like |
| 166 | +`/usr/libexec/phabricator-ssh-hook.sh` and edit it to have the correct |
| 167 | +settings. Then make it owned by `root` and restrict editing: |
| 168 | + |
| 169 | + sudo chown root /path/to/phabricator-ssh-hook.sh |
| 170 | + sudo chmod 755 /path/to/phabricator-ssh-hook.sh |
| 171 | + |
| 172 | +If you don't do this, `sshd` will refuse to execute the hook. |
| 173 | + |
| 174 | +**Create `sshd_config` for Phabricator**: Copy the template in |
| 175 | +`phabricator/resources/sshd/sshd_config.phabricator.example` to somewhere like |
| 176 | +`/etc/ssh/sshd_config.phabricator`. |
| 177 | + |
| 178 | +Open the file and edit the `AuthorizedKeysCommand` and |
| 179 | +`AuthorizedKeysCommandUser` settings to be correct for your system. |
| 180 | + |
| 181 | +**Start SSHD**: Now, start the Phabricator `sshd`: |
| 182 | + |
| 183 | + sudo sshd -f /path/to/sshd_config.phabricator |
| 184 | + |
| 185 | +If you did everything correctly, you should be able to run this: |
| 186 | + |
| 187 | + echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping |
| 188 | + |
| 189 | +...and get a response like this: |
| 190 | + |
| 191 | + {"result":"orbital","error_code":null,"error_info":null} |
| 192 | + |
| 193 | +(If you get an authentication error, make sure you added your public key in |
| 194 | +**Settings > SSH Public Keys**.) |
| 195 | + |
| 196 | += Authentication Over HTTP = |
| 197 | + |
| 198 | +To authenticate over HTTP, users should configure a **VCS Password** in the |
| 199 | +**Settings** screen. This panel is available only if `diffusion.allow-http-auth` |
| 200 | +is enabled. |
| 201 | + |
| 202 | += Authentication Over SSH = |
| 203 | + |
| 204 | +To authenticate over SSH, users should add **SSH Public Keys** in the |
| 205 | +**Settings** screen. |
0 commit comments