veryroundbird.house
forked from
tangled.org/core
this repo has no description
docs/knot-hosting.md: update to reflect latest knot cli change
Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.sh>
anirudh.fi
+30
-48
docs/knot-hosting.md
+30
-48
docs/knot-hosting.md
···
34
git clone https://tangled.sh/@tangled.sh/core
35
```
36
37
-
Then, build our binaries (you need to have Go installed):
38
-
* `knotserver`: the main server program
39
-
* `keyfetch`: utility to fetch ssh pubkeys
40
-
* `repoguard`: enforces repository access control
41
42
```
43
cd core
44
export CGO_ENABLED=1
45
-
go build -o knot ./cmd/knotserver
46
-
go build -o keyfetch ./cmd/keyfetch
47
-
go build -o repoguard ./cmd/repoguard
48
```
49
50
-
Next, move the `keyfetch` binary to a location owned by `root` --
51
-
`/usr/local/libexec/tangled-keyfetch` is a good choice:
52
53
```
54
-
sudo mv keyfetch /usr/local/libexec/tangled-keyfetch
55
-
sudo chown root:root /usr/local/libexec/tangled-keyfetch
56
-
sudo chmod 755 /usr/local/libexec/tangled-keyfetch
57
```
58
59
-
This is necessary because SSH `AuthorizedKeysCommand` requires [really specific
60
-
permissions](https://stackoverflow.com/a/27638306). Let's set that up:
61
62
```
63
sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
64
Match User git
65
-
AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch
66
AuthorizedKeysCommandUser nobody
67
EOF
68
```
69
70
-
Next, create the `git` user:
71
72
```
73
sudo adduser git
74
```
75
76
-
Copy the `repoguard` binary to the `git` user's home directory:
77
-
78
-
```
79
-
sudo cp repoguard /home/git
80
-
sudo chown git:git /home/git/repoguard
81
-
```
82
-
83
-
Now, let's set up the server. Copy the `knot` binary to
84
-
`/usr/local/bin/knotserver`. Then, create `/home/git/.knot.env` with the
85
-
following, updating the values as necessary. The `KNOT_SERVER_SECRET` can be
86
-
obtaind from the [/knots](/knots) page on Tangled.
87
88
```
89
KNOT_REPO_SCAN_PATH=/home/git
···
96
97
If you run a Linux distribution that uses systemd, you can use the provided
98
service file to run the server. Copy
99
-
[`knotserver.service`](https://tangled.sh/did:plc:wshs7t2adsemcrrd4snkeqli/core/blob/master/systemd/knotserver.service)
100
to `/etc/systemd/system/`. Then, run:
101
102
```
···
161
KNOT_REPO_SCAN_PATH=/home/git/repositories
162
```
163
164
-
In your SSH config (e.g. `/etc/ssh/sshd_config.d/authorized_keys_command.conf`),
165
-
update the `AuthorizedKeysCommand` line to use the new folder. For example:
166
167
```
168
Match User git
169
-
AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -git-dir /home/git/repositories
170
AuthorizedKeysCommandUser nobody
171
-
```
172
-
173
-
Make sure to restart your SSH server!
174
-
175
-
#### git
176
-
177
-
The keyfetch executable takes multiple arguments to change certain paths. You
178
-
can view a full list by running `/usr/local/libexec/tangled-keyfetch -h`.
179
-
180
-
As an example, if you wanted to change the path to the repoguard executable,
181
-
you would edit your SSH config (e.g. `/etc/ssh/sshd_config.d/authorized_keys_command.conf`)
182
-
and update the `AuthorizedKeysCommand` line:
183
-
184
-
```
185
-
Match User git
186
-
AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -repoguard-path /path/to/repoguard
187
-
AuthorizedKeysCommandUser nobody
188
```
189
190
Make sure to restart your SSH server!
···
34
git clone https://tangled.sh/@tangled.sh/core
35
```
36
37
+
Then, build the `knot` CLI. This is the knot administration and operation tool.
38
+
For the purpose of this guide, we're only concerned with these subcommands:
39
+
40
+
* `knot server`: the main knot server process, typically run as a
41
+
supervised service
42
+
* `knot guard`: handles role-based access control for git over SSH
43
+
(you'll never have to run this yourself)
44
+
* `knot keys`: fetches SSH keys associated with your knot; we'll use
45
+
this to generate the SSH `AuthorizedKeysCommand`
46
47
```
48
cd core
49
export CGO_ENABLED=1
50
+
go build -o knot ./cmd/knot
51
```
52
53
+
Next, move the `knot` binary to a location owned by `root` --
54
+
`/usr/local/bin/knot` is a good choice:
55
56
```
57
+
sudo mv knot /usr/local/bin/knot
58
```
59
60
+
This is necessary because SSH `AuthorizedKeysCommand` requires [really
61
+
specific permissions](https://stackoverflow.com/a/27638306). The
62
+
`AuthorizedKeysCommand` specifies a command that is run by `sshd` to
63
+
retrieve a user's public SSH keys dynamically for authentication. Let's
64
+
set that up.
65
66
```
67
sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
68
Match User git
69
+
AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys
70
AuthorizedKeysCommandUser nobody
71
EOF
72
```
73
74
+
Next, create the `git` user. We'll use the `git` user's home directory
75
+
to store repositories:
76
77
```
78
sudo adduser git
79
```
80
81
+
Create `/home/git/.knot.env` with the following, updating the values as
82
+
necessary. The `KNOT_SERVER_SECRET` can be obtaind from the
83
+
[/knots](/knots) page on Tangled.
84
85
```
86
KNOT_REPO_SCAN_PATH=/home/git
···
93
94
If you run a Linux distribution that uses systemd, you can use the provided
95
service file to run the server. Copy
96
+
[`knotserver.service`](/systemd/knotserver.service)
97
to `/etc/systemd/system/`. Then, run:
98
99
```
···
158
KNOT_REPO_SCAN_PATH=/home/git/repositories
159
```
160
161
+
Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated
162
+
repository path:
163
164
```
165
+
sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
166
Match User git
167
+
AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories
168
AuthorizedKeysCommandUser nobody
169
+
EOF
170
```
171
172
Make sure to restart your SSH server!