diff options
-rw-r--r-- | EndoForge/README.md | 130 |
1 files changed, 95 insertions, 35 deletions
diff --git a/EndoForge/README.md b/EndoForge/README.md index 0a1f644..795441c 100644 --- a/EndoForge/README.md +++ b/EndoForge/README.md | |||
@@ -1,74 +1,132 @@ | |||
1 | EndoForge | 1 | EndoForge |
2 | --------- | 2 | =================== |
3 | A Self-Forge. | 3 | ### A `Self-Forge` |
4 | 4 | ||
5 | Convert any Git repository into a Self-Forge by merging this repository. | 5 | Convert any Git repository into a `Self-Forge` with a simple setting change. |
6 | 6 | ||
7 | Synopsis: | ||
7 | 8 | ||
9 | ``` | ||
10 | git config core.self-forge true | ||
11 | ``` | ||
8 | 12 | ||
13 | Install `EndoForge`: | ||
9 | 14 | ||
15 | ``` | ||
16 | make install | ||
17 | ``` | ||
10 | 18 | ||
19 | ## WHAT IS A `Self-Forge` | ||
11 | 20 | ||
12 | WHAT IT DOES | 21 | A `Self-Forge` is a `Git` repository that allows anonymous contribution directly |
13 | ------------ | 22 | through the `Git-Over-SSH` protocol. Each contributor is directly validated with |
23 | `OpenSSH` cryptography. | ||
14 | 24 | ||
15 | This repository contains the code to share itself (the repository) through | 25 | A `Self-Forge` relieves the owner of the repository and the repository's other |
16 | Git-over-SSH. It can be merged into other repositories, turning them | 26 | contributors from all needing to share a common "hub" `Forge` before the owner |
17 | self-sharing. | 27 | can accept a contribution. Instead, users need only `IP` connectivity to the |
28 | machine containing the repository. | ||
18 | 29 | ||
19 | It also contains the code to listen for changes sent to itself through | 30 | The contributions are stored in namespaces according to the public keys of the |
20 | Git-over-SSH. | 31 | contributors. This prevents collisions. |
21 | 32 | ||
33 | (It is also possible to do _without_ `IP` connectivity using DHT connectivity; | ||
34 | see `tuntox.git`.) | ||
22 | 35 | ||
36 | ## WHAT IS A `Forge` | ||
23 | 37 | ||
38 | A `Forge` is a "place" where programmers share source code. (Anyone could share | ||
39 | any content, in principle. The point is to track past changes.) The largest | ||
40 | `Forge`, for example, is Microsoft's `GitHub`. | ||
24 | 41 | ||
42 | Note that a `Forge` is different from a web site. A `Git`-based `Forge` must | ||
43 | accept contributions in the `Git-Over-SSH` protocol. That is the convenient and | ||
44 | standard way to use `Git`. | ||
25 | 45 | ||
46 | Nevertheless, the typical `Forge` requires users to go sign up for some web | ||
47 | service before they can connect using `Git`'s native language of `SSH`. | ||
48 | `EndoForge` uses the key provided by the `SSH` client. | ||
26 | 49 | ||
27 | HOW IT WORKS | 50 | Using a `Self-Forge` relieves users of dependency on any troublesome |
28 | ------------ | 51 | intermediary `Forge`. You get your own `Forge`. You are your own `Forge`. |
52 | |||
53 | ## What is `Git-Over-SSH` | ||
54 | |||
55 | `Git-Over-SSH` is the standard `Git` protocol for _both reading and writing_ a | ||
56 | repository. It is the same `Git` protocol one uses when _pushing_ to | ||
57 | `github.com` or any other `Git`-based `Forge`. | ||
58 | |||
59 | `Git` has other protocols for read-only access, including `Git-Over-HTTPS`. That | ||
60 | type of access to a `Git` repository, including domain name and CA certificate, | ||
61 | can be provided via `CGit` by running `selfpublish.sh`. | ||
62 | |||
63 | HOW TO ACCESS A SELF-FORGE | ||
64 | -------------------------- | ||
29 | 65 | ||
30 | Git contains a program `git-receive-pack` which implements a git | 66 | Users can run `git clone` on your `SSH` address, like this: |
31 | protocol server. The `git-receive-pack` expects to be launched as an SSH | ||
32 | server "ForcedCommand" in a configuration that protects the server from | ||
33 | untrustworthy users. | ||
34 | 67 | ||
35 | Normally, the SSH server only permits users who have already uploaded | 68 | [TODO: edit document dynamically to get real values here] |
36 | their public keys to the server. It assumes that access should be closed | 69 | ``` |
37 | to new users. | 70 | git clone $(id -u)@$(hostname):$(pwd) |
71 | ``` | ||
38 | 72 | ||
39 | Installing this code reverses that assumption, granting open access to | 73 | They can then commit changes to the repository, and push them back to `origin`. |
40 | unrecognized users. This is made safe by limiting write access to a | ||
41 | GIT_NAMESPACE over which the user proves global mathematical ownership with | ||
42 | their SSH client key. This means that the user cannot overwrite anyone else's | ||
43 | data. | ||
44 | 74 | ||
45 | The user's uploaded data is still saved and is ready to be be merged into the | 75 | The changes will exist in a separate space from where any other user can |
46 | main repository manually, or even automatically. Automatic merging could be | 76 | overwrite. The cryptography of `OpenSSH` makes this possible. |
47 | authorized on the basis of the public key, or through a consensus algorithm | ||
48 | comparing branches signed by many different keys. | ||
49 | 77 | ||
78 | HOW IT WORKS | ||
79 | ------------ | ||
50 | 80 | ||
81 | Normally, `OpenSSH` server only permits connections from users whose keys have | ||
82 | been pre-authorized on the server. `OpenSSH` assumes that access should be | ||
83 | closed to new users. Installing `EndoForge` modifies the `OpenSSH` server | ||
84 | configuration so that this assumption is reversed. Access is opened to unknown | ||
85 | users. | ||
51 | 86 | ||
87 | Anonymous users are forced to run the command `~/.ssh/AnonymousAccessCommand` | ||
88 | upon login, instead of whatever command they select for themselves. The user can | ||
89 | choose or configure their `AnonymousAccessCommand` to provide sandboxing, or to | ||
90 | implement a user authentication scheme in some flexible way. | ||
52 | 91 | ||
92 | `EndoForge` installs a `~/.ssh/AnonymousAccessCommand` that allows anonymous | ||
93 | users to run the `Git` protocol commands (`git-receive-pack`, etc.) to access | ||
94 | repositories available on the system. A repository must be configured | ||
95 | `core.self-forge true` to allow this access. | ||
53 | 96 | ||
54 | HOW TO INSTALL | 97 | INSTALLATION |
55 | -------------- | 98 | -------------- |
56 | 99 | ||
57 | Run: | 100 | Run: |
58 | ``` | 101 | ``` |
59 | make install | 102 | make install |
60 | ``` | 103 | ``` |
61 | 104 | ||
62 | This installs the `AnonymousAccessCommand` in the current user's home directory | 105 | This installs the `AnonymousAccessCommand` in the current user's home directory |
63 | (under `$HOME/.ssh`). | 106 | (under `$HOME/.ssh`). |
64 | 107 | ||
65 | Then, if sudo access is available, it enables anonymous access by | 108 | Then, if sudo access is available, it enables anonymous access by editing the |
66 | editing the system `OpenSSH` configuration. | 109 | system `OpenSSH` configuration. This allows any user to listen for `SSH` |
110 | connections via the file `$HOME/.ssh/AnonymousAccessCommand`. | ||
67 | 111 | ||
112 | Finally, the command to enable public access to the `Self-Forge` may be run: | ||
68 | 113 | ||
114 | Run: | ||
115 | ``` | ||
116 | git config core.self-forge true | ||
117 | ``` | ||
118 | |||
119 | Note that, once installed, you can run this in ANY repository. | ||
120 | |||
121 | You can also run `make shared` but that just runs the same `git config` for you. | ||
69 | 122 | ||
123 | ## HOW TO DISABLE | ||
70 | 124 | ||
125 | To disable public access to the repository, run: | ||
71 | 126 | ||
127 | ``` | ||
128 | git config core.self-forge false | ||
129 | ``` | ||
72 | 130 | ||
73 | NON-ROOT INSTALLATION | 131 | NON-ROOT INSTALLATION |
74 | --------------------- | 132 | --------------------- |
@@ -77,12 +135,14 @@ A systemd unit file to run `OpenSSH` as an unprivileged user is included. | |||
77 | 135 | ||
78 | The configuration file sets the port to `22022`. | 136 | The configuration file sets the port to `22022`. |
79 | 137 | ||
80 | This type of installation is vastly inferior to running as root, because only | 138 | This type of installation is vastly inferior to one requiring root, because |
81 | root can make `OpenSSH` listen on port `22`, as it is designed to do. | 139 | `OpenSSH` is much easier to connect to servers that listen on port `22` than any |
140 | other port. | ||
82 | 141 | ||
83 | The `install-user` target runs the unprivileged `OpenSSH` server. | 142 | The `install-user` target runs the unprivileged `OpenSSH` server. |
84 | 143 | ||
85 | ``` | 144 | ``` |
86 | make install-user | 145 | make install-user |
87 | ``` | 146 | ``` |
88 | 147 | ||
148 | The script `selftest.sh` tests connecting to the port 22022 server. | ||