back round 0 view raw

docs/knot-hosting.md: update to reflect latest knot cli change #199

merged
opened by anirudh.fi targeting master from push-qkkmntrmxqly
options
unified split
Changed files
+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!