@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Improve Diffusion hosting setup instructions somewhat?
Summary:
Ref T10866. Fixes T10386. This attempts to make it a little more plausible to follow these directions:
- Use simpler language in general.
- Remove language suggesting that HTTP requires no additional configuration.
- Suggest using a load balancer or an ugly port number instead of swapping SSH to a different port.
- Be more granular about `sudo` setup.
- Organize better?
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10386, T10866
Differential Revision: https://secure.phabricator.com/D15796
+250
-126
+1
-1
resources/sshd/sshd_config.phabricator.example
+1
-1
resources/sshd/sshd_config.phabricator.example
+249
-125
src/docs/user/userguide/diffusion_hosting.diviner
+249
-125
src/docs/user/userguide/diffusion_hosting.diviner
···
3
3
4
4
Guide to configuring Phabricator repository hosting.
5
5
6
-
= Overview =
6
+
Overview
7
+
========
7
8
8
9
Phabricator can host repositories and provide authenticated read and write
9
10
access to them over HTTP and SSH. This document describes how to configure
10
11
repository hosting.
11
12
12
-
= Understanding Supported Protocols =
13
+
Understanding Supported Protocols
14
+
=================================
13
15
14
16
Phabricator supports hosting over these protocols:
15
17
···
35
37
| Performance | Better | Okay |
36
38
| Setup | Hard | Easy |
37
39
38
-
Each repository can be configured individually, and you can use either protocol,
39
-
or both, or a mixture across different repositories.
40
+
Each repository can be configured individually, and you can use either
41
+
protocol, or both, or a mixture across different repositories.
40
42
41
43
SSH is recommended unless you need anonymous access, or are not able to
42
44
configure it for technical reasons.
43
45
44
-
= Configuring System User Accounts =
45
46
46
-
Phabricator uses as many as three user accounts. This section will guide you
47
-
through creating and configuring them. These are system user accounts on the
48
-
machine Phabricator runs on, not Phabricator user accounts.
47
+
Creating System User Accounts
48
+
=============================
49
49
50
-
The system accounts are:
50
+
Phabricator uses two system user accounts, plus a third account if you
51
+
configure SSH access. This section will guide you through creating and
52
+
configuring them. These are system user accounts on the machine Phabricator
53
+
runs on, not Phabricator user accounts.
51
54
52
-
- The user the daemons run as. We'll call this `daemon-user`. For more
53
-
information on the daemons, see @{article:Managing Daemons with phd}. This
55
+
The system accounts Phabricator uses are:
56
+
57
+
- The user the webserver runs as. We'll call this `www-user`.
58
+
- The user the daemons run as. We'll call this `daemon-user`. This
54
59
user is the only user which will interact with the repositories directly.
55
-
Other accounts will `sudo` to this account in order to perform VCS
60
+
Other accounts will `sudo` to this account in order to perform repository
56
61
operations.
57
-
- The user the webserver runs as. We'll call this `www-user`. If you do not
58
-
plan to make repositories available over HTTP, you do not need to perform
59
-
any special configuration for this user.
60
-
- The user that users will connect over SSH as. We'll call this `vcs-user`.
62
+
- The user that humans will connect over SSH as. We'll call this `vcs-user`.
61
63
If you do not plan to make repositories available over SSH, you do not need
62
-
to perform any special configuration for this user.
64
+
to create or configure this user.
63
65
64
-
To configure these users:
66
+
To create these users:
65
67
68
+
- Create a `www-user` if one does not already exist. In most cases, this
69
+
user will already exist and you just need to identify which user it is. Run
70
+
your webserver as this user.
66
71
- Create a `daemon-user` if one does not already exist (you can call this user
67
-
whatever you want, or use an existing account). When you start the daemons,
68
-
start them using this user.
69
-
- Create a `www-user` if one does not already exist. Run your webserver as
70
-
this user. In most cases, this user will already exist.
71
-
- Create a `vcs-user` if one does not already exist. Common names for this
72
-
user are `git` or `hg`. When users clone repositories, they will use a URI
73
-
like `vcs-user@phabricator.yourcompany.com`.
72
+
whatever you want, or use an existing account). Below, you'll configure
73
+
the daemons to start as this user.
74
+
- Create a `vcs-user` if one does not already exist and you plan to set up
75
+
SSH. When users clone repositories, they will use a URI like
76
+
`vcs-user@phabricator.yourcompany.com`, so common names for this user are
77
+
`git` or `hg`.
78
+
79
+
Continue below to configure these accounts.
80
+
81
+
82
+
Configuring Phabricator
83
+
=======================
84
+
85
+
Now that you have created or identified these accounts, update the Phabricator
86
+
configuration to specify them.
87
+
88
+
First, set `phd.user` to the `daemon-user`:
89
+
90
+
```
91
+
phabricator/ $ ./bin/config set phd.user daemon-user
92
+
```
93
+
94
+
Restart the daemons to make sure this configuration works properly. They should
95
+
start as the correct user automatically.
96
+
97
+
If you're using a `vcs-user` for SSH, you should also configure that:
98
+
99
+
```
100
+
phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
101
+
```
102
+
103
+
Next, you'll set up `sudo` permissions so these users can interact with one
104
+
another.
105
+
106
+
107
+
Configuring Sudo
108
+
================
109
+
110
+
The `www-user` and `vcs-user` need to be able to `sudo` as the `daemon-user`
111
+
so they can interact with repositories.
112
+
113
+
To grant them access, edit the `sudo` system configuration. On many systems,
114
+
you will do this by modifying the `/etc/sudoers` file using `visudo` or
115
+
`sudoedit`. In some cases, you may add a new file to `/etc/sudoers.d` instead.
116
+
117
+
To give a user account `sudo` access to run a list of binaries, add a line like
118
+
this to the configuration file (this example would grant `vcs-user` permission
119
+
to run `ls` as `daemon-user`):
120
+
121
+
```
122
+
vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/bin/ls
123
+
```
124
+
125
+
The `www-user` needs to be able to run these binaries as the `daemon-user`:
74
126
75
-
Now, allow the `vcs-user` and `www-user` to `sudo` as the `daemon-user`. Add
76
-
this to `/etc/sudoers`, using `visudo` or `sudoedit`.
127
+
- `git` (if using Git)
128
+
- `git-http-backend` (if using Git)
129
+
- `hg` (if using Mercurial)
130
+
- `ssh` (if configuring clusters)
77
131
78
-
If you plan to use SSH:
132
+
If you plan to use SSH, the `vcs-user` needs to be able to run these binaries
133
+
as the `daemon-user`:
134
+
135
+
- `git` (if using Git)
136
+
- `git-upload-pack` (if using Git)
137
+
- `git-receive-pack` (if using Git)
138
+
- `hg` (if using Mercurial)
139
+
- `svnserve` (if using Subversion)
140
+
- `ssh` (if configuring clusters)
79
141
80
-
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
142
+
Identify the full paths to all of these binaries on your system and add the
143
+
appropriate permissions to the `sudo` configuration.
81
144
82
-
If you plan to use HTTP:
145
+
Normally, you'll add two lines that look something like this:
83
146
84
-
www-user ALL=(daemon-user) SETENV: NOPASSWD: /usr/bin/git-http-backend, /usr/bin/hg
147
+
```
148
+
www-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...
149
+
vcs-user ALL=(daemon-user) SETENV: NOPASSWD: /path/to/x, /path/to/y, ...
150
+
```
85
151
86
-
Replace `vcs-user`, `www-user` and `daemon-user` with the right usernames for
87
-
your configuration. Make sure all the paths point to the real locations of the
88
-
binaries on your system. You can omit any binaries associated with VCSes you do
89
-
not use.
152
+
This is just a template. In the real configuration file, you need to:
90
153
91
-
Adding these commands to `sudoers` will allow the daemon and webserver users to
92
-
write to repositories as the daemon user.
154
+
- Replace `www-user`, `dameon-user` and `vcs-user` with the correct
155
+
usernames for your system.
156
+
- List every binary that these users need access to, as described above.
157
+
- Make sure each binary path is the full path to the correct binary location
158
+
on your system.
93
159
94
-
Before saving and closing `/etc/sudoers`, look for this line:
160
+
Before continuing, look for this line in your `sudo` configuration:
95
161
96
162
Defaults requiretty
97
163
98
164
If it's present, comment it out by putting a `#` at the beginning of the line.
99
165
With this option enabled, VCS SSH sessions won't be able to use `sudo`.
100
166
167
+
168
+
Additional SSH User Configuration
169
+
=================================
170
+
101
171
If you're planning to use SSH, you should also edit `/etc/passwd` and
102
172
`/etc/shadow` to make sure the `vcs-user` account is set up correctly.
103
173
104
-
- Open `/etc/shadow` and find the line for the `vcs-user` account.
105
-
- The second field (which is the password field) must not be set to
106
-
`!!`. This value will prevent login. If it is set to `!!`, edit it
107
-
and set it to `NP` ("no password") instead.
108
-
- Open `/etc/passwd` and find the line for the `vcs-user` account.
109
-
- The last field (which is the login shell) must be set to a real shell.
110
-
If it is set to something like `/bin/false`, then `sshd` will not be able
111
-
to execute commands. Instead, you should set it to a real shell, like
112
-
`/bin/sh`.
174
+
**`/etc/shadow`**: Open `/etc/shadow` and find the line for the `vcs-user`
175
+
account.
113
176
114
-
Finally, once you've configured `/etc/sudoers`, `/etc/shadow` and `/etc/passwd`,
115
-
set `phd.user` to the `daemon-user`:
177
+
The second field (which is the password field) must not be set to `!!`. This
178
+
value will prevent login. If it is set to `!!`, edit it and set it to `NP` ("no
179
+
password") instead.
116
180
117
-
phabricator/ $ ./bin/config set phd.user daemon-user
181
+
**`/etc/passwd`**: Open `/etc/passwd` and find the line for the `vcs-user`
182
+
account.
118
183
119
-
If you're using a `vcs-user`, you should also configure that here:
184
+
The last field (which is the login shell) must be set to a real shell. If it is
185
+
set to something like `/bin/false`, then `sshd` will not be able to execute
186
+
commands. Instead, you should set it to a real shell, like `/bin/sh`.
120
187
121
-
phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
122
188
123
-
= Configuring HTTP =
189
+
Configuring HTTP
190
+
================
124
191
125
-
If you plan to use authenticated HTTP, you need to set
126
-
`diffusion.allow-http-auth` in Config. If you don't plan to use HTTP, or plan to
127
-
use only anonymous HTTP, you can leave this setting disabled.
192
+
If you plan to serve repositories over authenticated HTTP, you need to set
193
+
`diffusion.allow-http-auth` in Config. If you don't plan to serve repositories
194
+
over HTTP (or plan to use only anonymous HTTP) you can leave this setting
195
+
disabled.
128
196
129
-
If you plan to use authenticated HTTP, you'll also need to configure a VCS
130
-
password in {nav Settings > VCS Password}.
197
+
If you plan to use authenticated HTTP, you (and all other users) also need to
198
+
configure a VCS password for your account in {nav Settings > VCS Password}.
131
199
132
200
Your VCS password must be a different password than your main Phabricator
133
201
password because VCS passwords are very easy to accidentally disclose. They are
···
136
204
instead of HTTP to authenticate access to repositories.
137
205
138
206
Otherwise, if you've configured system accounts above, you're all set. No
139
-
additional server configuration is required to make HTTP work.
140
-
141
-
= Configuring SSH =
207
+
additional server configuration is required to make HTTP work. You should now
208
+
be able to fetch and push repositories over HTTP. See "Cloning a Repository"
209
+
below for more details.
142
210
143
-
SSH access requires some additional setup. Here's an overview of how setup
144
-
works:
211
+
If you're having trouble, see "Troubleshooting HTTP" below.
145
212
146
-
- You'll move the normal `sshd` daemon to another port, like `222`. When
147
-
connecting to the machine to administrate it, you'll use this alternate
148
-
port to get a normal login shell.
149
-
- You'll run a highly restricted `sshd` on port 22, with a special locked-down
150
-
configuration that uses Phabricator to authorize users and execute commands.
151
-
- The `sshd` on port 22 **MUST** be 6.2 or newer, because Phabricator relies
152
-
on the `AuthorizedKeysCommand` option.
153
213
154
-
Here's a walkthrough of how to perform this configuration in detail:
214
+
Configuring SSH
215
+
===============
155
216
156
-
**Move Normal SSHD**: Be careful when editing the configuration for `sshd`. If
157
-
you get it wrong, you may lock yourself out of the machine. Restarting `sshd`
158
-
generally will not interrupt existing connections, but you should exercise
159
-
caution. Two strategies you can use to mitigate this risk are: smoke-test
160
-
configuration by starting a second `sshd`; and use a `screen` session which
161
-
automatically repairs configuration unless stopped.
217
+
SSH access requires some additional setup. You will configure and run a second,
218
+
restricted copy of `sshd` on the machine, on a different port from the standard
219
+
`sshd`. This special copy of `sshd` will serve repository requests and provide
220
+
other Phabricator SSH services.
162
221
163
-
To smoke-test a configuration, just start another `sshd` using the `-f` flag:
222
+
NOTE: The Phabricator `sshd` service **MUST** be 6.2 or newer, because
223
+
Phabricator relies on the `AuthorizedKeysCommand` option.
164
224
165
-
sudo /path/to/sshd -f /path/to/config_file.edited
225
+
**Choose a Port**: These instructions will configure the alternate `sshd` on
226
+
port `2222`. This is easy to configure, but if you run the service on this port
227
+
users will clone and push to URIs like `ssh://git@host.com:2222/`, which is
228
+
a little ugly.
166
229
167
-
You can then connect and make sure the edited config file is valid before
168
-
replacing your primary configuration file.
230
+
The easiest way to fix this is to put a load balancer in front of the host and
231
+
have it forward TCP traffic on port `22` to port `2222`. Then users can clone
232
+
from `ssh://git@host.com/` without an explicit port number and you don't need
233
+
to do anything else.
169
234
170
-
To automatically repair configuration, start a `screen` session with a command
171
-
like this in it:
172
-
173
-
sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart
235
+
Alternatively, you can move the administrative `sshd` to a new port, then run
236
+
Phabricator `sshd` on port 22. This is complicated and risky. See "Moving the
237
+
sshd Port" below for help.
174
238
175
-
The specific command may vary for your system, but the general idea is to have
176
-
the machine automatically restore configuration after some period of time if
177
-
you don't stop it. If you lock yourself out, this will fix things automatically.
239
+
Finally, you can just run on port `2222` and accept the explicit port in the
240
+
URIs. This is the simplest approach, and you can start here and clean things
241
+
up later.
178
242
179
-
Now that you're ready to edit your configuration, open up your `sshd` config
180
-
(often `/etc/ssh/sshd_config`) and change the `Port` setting to some other port,
181
-
like `222` (you can choose any port other than 22).
243
+
If you plan to connect to a port other than `22`, you should set this port
244
+
as `diffusion.ssh-port` in your Phabricator config:
182
245
183
-
Port 222
246
+
```
247
+
$ ./bin/config set diffusion.ssh-port 2222
248
+
```
184
249
185
-
Very carefully, restart `sshd`. Verify that you can connect on the new port:
250
+
This port is not special, and you are free to choose a different port, provided
251
+
you make the appropriate configuration adjustment below.
186
252
187
-
ssh -p 222 ...
253
+
**Configure and Start Phabricator SSHD**: Now, you'll configure and start a
254
+
copy of `sshd` which will serve Phabricator services, including repositories,
255
+
over SSH.
188
256
189
-
**Configure and Start Phabricator SSHD**: Now, configure and start a second
190
-
`sshd` instance which will run on port `22`. This instance will use a special
191
-
locked-down configuration that uses Phabricator to handle authentication and
192
-
command execution.
257
+
This instance will use a special locked-down configuration that uses
258
+
Phabricator to handle authentication and command execution.
193
259
194
260
There are three major steps:
195
261
···
221
287
`AuthorizedKeysCommandUser`, and `AllowUsers` settings to be correct for your
222
288
system.
223
289
290
+
This configuration file also specifies the `Port` the service should run on.
291
+
If you intend to run on a non-default port, adjust it now.
292
+
224
293
**Start SSHD**: Now, start the Phabricator `sshd`:
225
294
226
295
sudo /path/to/sshd -f /path/to/sshd_config.phabricator
227
296
228
-
If you did everything correctly, you should be able to run this:
297
+
If you did everything correctly, you should be able to run this command:
229
298
230
-
echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
299
+
```
300
+
$ echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
301
+
```
231
302
232
303
...and get a response like this:
233
304
234
-
{"result":"orbital","error_code":null,"error_info":null}
305
+
```lang=json
306
+
{"result":"phabricator.yourcompany.com","error_code":null,"error_info":null}
307
+
```
235
308
236
-
(If you get an authentication error, make sure you added your public key in
237
-
**Settings > SSH Public Keys**.) If you're having trouble, check the
309
+
If you get an authentication error, make sure you added your public key in
310
+
{nav Settings > SSH Public Keys}. If you're having trouble, check the
238
311
troubleshooting section below.
239
312
240
-
= Authentication Over HTTP =
313
+
Authentication Over SSH
314
+
=======================
241
315
242
-
To authenticate over HTTP, users should configure a **VCS Password** in the
243
-
**Settings** screen. This panel is available only if `diffusion.allow-http-auth`
244
-
is enabled.
245
-
246
-
= Authentication Over SSH =
316
+
To authenticate over SSH, users should add their public keys under
317
+
{nav Settings > SSH Public Keys}.
247
318
248
-
To authenticate over SSH, users should add **SSH Public Keys** in the
249
-
**Settings** screen.
250
319
251
-
= Cloning a Repository =
320
+
Cloning a Repository
321
+
====================
252
322
253
323
If you've already set up a hosted repository, you can try cloning it now. To
254
324
do this, browse to the repository's main screen in Diffusion. You should see
···
259
329
If you don't see the commands or running them doesn't work, see below for tips
260
330
on troubleshooting.
261
331
262
-
= Troubleshooting HTTP =
332
+
333
+
Troubleshooting HTTP
334
+
====================
263
335
264
336
Some general tips for troubleshooting problems with HTTP:
265
337
266
338
- Make sure `diffusion.allow-http-auth` is enabled in your Phabricator config.
267
-
- Make sure HTTP serving is enabled for the repository you're trying to clone.
268
-
You can find this in {nav Edit Repository > Hosting}.
339
+
- Make sure HTTP serving is enabled for the repository you're trying to
340
+
clone. You can find this in {nav Edit Repository > Hosting}.
269
341
- Make sure you've configured a VCS password. This is separate from your main
270
342
account password. You can configure this in {nav Settings > VCS Password}.
271
343
- Make sure the main repository screen in Diffusion shows a clone/checkout
···
287
359
288
360
In many cases, this can give you more information about what's wrong.
289
361
290
-
= Troubleshooting SSH =
362
+
Troubleshooting SSH
363
+
===================
291
364
292
365
Some general tips for troubleshooting problems with SSH:
293
366
···
311
384
- Check your `phabricator-ssh-hook.sh` file for proper settings.
312
385
- Check your `sshd_config.phabricator` file for proper settings.
313
386
314
-
To troubleshoot SSH setup: connect to the server with `ssh`, without running
315
-
a command. You may need to use the `-T` flag. You should see a message like
316
-
this one:
387
+
To troubleshoot SSH setup: connect to the server with `ssh`, without running a
388
+
command. You may need to use the `-T` flag, and will need to use `-p` if you
389
+
are running on a nonstandard port. You should see a message like this one:
317
390
318
-
$ ssh -T dweller@secure.phabricator.com
391
+
$ ssh -T -p 2222 vcs-user@phabricator.yourcompany.com
319
392
phabricator-ssh-exec: Welcome to Phabricator.
320
393
321
394
You are logged in as alincoln.
···
338
411
- You're connecting as the `vcs-user`.
339
412
- The `vcs-user` has `NP` in `/etc/shadow`.
340
413
- The `vcs-user` has `/bin/sh` or some other valid shell in `/etc/passwd`.
341
-
- Your SSH key is correct, and you've added it to Phabricator in the Settings
342
-
panel.
414
+
- Your SSH private key is correct, and you've added the corresponding
415
+
public key to Phabricator in the Settings panel.
343
416
344
417
If you can get this far, but can't execute VCS commands like `git clone`, there
345
418
is probably an issue with your `sudoers` configuration. Check:
···
357
430
$ /path/to/sshd -d -d -d -f /path/to/sshd_config.phabricator
358
431
359
432
This will run it in the foreground and emit a large amount of debugging
360
-
information.
433
+
information when you connect to it.
361
434
362
435
Finally, you can usually test that `sudoers` is configured correctly by
363
436
doing something like this:
···
369
442
Phabricator will run it. This can give you better error messages about issues
370
443
with `sudoers` configuration.
371
444
372
-
= Miscellaneous Troubleshooting =
445
+
446
+
Miscellaneous Troubleshooting
447
+
=============================
373
448
374
449
- If you're getting an error about `svnlook` not being found, add the path
375
450
where `svnlook` is located to the Phabricator configuration
···
377
452
is caused by SVN wiping the environment (including PATH) when invoking
378
453
commit hooks.
379
454
455
+
456
+
Moving the sshd Port
457
+
====================
458
+
459
+
If you want to move the standard (administrative) `sshd` to a different port to
460
+
make Phabricator repository URIs cleaner, this section has some tips.
461
+
462
+
This is optional, and it is normally easier to do this by putting a load
463
+
balancer in front of Phabricator and having it accept TCP traffic on port 22
464
+
and forward it to some other port.
465
+
466
+
When moving `sshd`, be careful when editing the configuration. If you get it
467
+
wrong, you may lock yourself out of the machine. Restarting `sshd` generally
468
+
will not interrupt existing connections, but you should exercise caution. Two
469
+
strategies you can use to mitigate this risk are: smoke-test configuration by
470
+
starting a second `sshd`; and use a `screen` session which automatically
471
+
repairs configuration unless stopped.
472
+
473
+
To smoke-test a configuration, just start another `sshd` using the `-f` flag:
474
+
475
+
sudo /path/to/sshd -f /path/to/config_file.edited
476
+
477
+
You can then connect and make sure the edited config file is valid before
478
+
replacing your primary configuration file.
479
+
480
+
To automatically repair configuration, start a `screen` session with a command
481
+
like this in it:
482
+
483
+
sleep 60 ; mv sshd_config.good sshd_config ; /etc/init.d/sshd restart
484
+
485
+
The specific command may vary for your system, but the general idea is to have
486
+
the machine automatically restore configuration after some period of time if
487
+
you don't stop it. If you lock yourself out, this can fix things automatically.
488
+
489
+
Now that you're ready to edit your configuration, open up your `sshd` config
490
+
(often `/etc/ssh/sshd_config`) and change the `Port` setting to some other port,
491
+
like `222` (you can choose any port other than 22).
492
+
493
+
Port 222
494
+
495
+
Very carefully, restart `sshd`. Verify that you can connect on the new port:
496
+
497
+
ssh -p 222 ...
498
+
499
+
Now you can move the Phabricator `sshd` to port 22, then adjust the value
500
+
for `diffusion.ssh-port` in your Phabricator configuration.
501
+
502
+
380
503
No Direct Pushes
381
504
================
382
505
···
412
535
request did not pass through Phabricator.
413
536
414
537
415
-
= Next Steps =
538
+
Next Steps
539
+
==========
416
540
417
541
Once hosted repositories are set up:
418
542