mtn.i2p2.i2pi2p.i2p, i2p.www and i2p.syndie branchesi2p.www cannot be verifiedThis is a revised version of Complication's original guide detailing the use of Monotone in I2P development. For basic instructions see the quick-start guide.
I2P has a distributed development model. The source code is replicated across independently administered Monotone repositories -- typically one repository per developer or contributor -- among which development work can be shared and merged cooperatively, and work that's considered satisfactory is eventually merged into a single trusted repository that serves as the project's master. In practice however, since contributors are often given commit privileges (after signing the developer agreement]), it's more common for completed work to be pushed directly to the master repository by its original authors.
For I2P development, some of Monotone's noteworthy qualities are: distributed version control, cryptographic authentication, access control, small size, few dependencies, storage of projects in a compressed SQLite database file, and fitness for use over the I2P network due to its ability to cleanly resume a previously interrupted sync operation.
A transport key authenticates your computer to a Monotone repository server, granting you read access. Likewise, a commit key provides write access.
To commit code into Monotone (authenticate your code as originating from you), you are strongly encouraged to use a separate key: a commit key.
If you don't generate any keys, you can get away with it. Public repositories generally provide read access to anyone, and Monotone will automatically generate temporary keys when you pull code from a repository without specifying a key. However, operating without either key will place limitations on your activities.
Without a transport key, you cannot:
Without a commit key, you cannot:
If you are certain that you will not be doing any of that, you can skip generating keys, and proceed to the next section. If you want to generate keys, read the following.
By convention, keys are named like an e-mail addresses. A corresponding e-mail address does not need to exist. For example, your keys might be named:
Monotone stores keys under `/home/username/.monotone/keys`, in text files which are named identically to the keys, for example:
To generate a transport key, and optionally also a commit key, issue in any directory commands like the following:
While creating keys, Monotone will prompt you for a passphrase to protect your keys against unauthorized use by encrypting them. It is very strongly recommended to protect a commit key. You may want to skip passphrase-protecting a transport key if you run Monotone in server mode, and require capability for automatic restarts.
Monotone helps ensure that nobody can easily impersonate a developer without others noticing. Since developers make mistakes and can be compromised, nothing but manual review can ensure quality of code. Authentication ensures you read the right diffs. It does not replace reading diffs.
A Monotone repository is a single file (an SQLite database) which contains in compressed form, all of the project's source code and history.
During the course of work, a Monotone repository may come contain code which you aren't actively working with, or even code which you don't entirely trust. This is normal. For example, you may trust a repository which gave you code, but not the author who committed it there.
When set up correctly (meaning: *do not* skip the sections Obtaining and deploying developers' keys or Setting up trust evaluation hooks) Monotone evaluates whether it trusts the committer of code, and prevents code from untrusted code from being checked out.
Code authentication happens not during syncs to repositories, but when checking out or updating a working copy from your local repository.
Commands exist which let you clean your repository of untrusted code, but they are rarely needed, if push access on the server is well managed.
A repository can hold many branches. For example, our repository holds the following main branches:
For historical reasons, you may find other branches, but they are not used. They originate from the import of the CVS repository which was used before `dev.i2p` disappeared.
By convention, the I2P Monotone repository is named `i2p.mtn`. Before you pull source code from servers, you need to initialize your own repository (it can become a new server if needed).
To initialize your local repository, change into a directory where you want the `i2p.mtn` file and branch directories to appear, and issue the following command:
Keys which developers use to commit code are essential for trust evaluation in Monotone. If you aren't running a Monotone server, you don't need their transport keys.
Developers' commit keys are provided GPG-signed below. Keys for zzz, Complication and welterde are provided clearsigned. The key for jrandom must be verified differently, since he's away, and only left a binary detached signature for his key.
To import developers' keys after verifying them, copy them all into a single text file. Create this file (e.g. `keys.txt`) in the same directory where `i2p.mtn` is. Import it by issuing:
Leave `/home/username/.monotone/keys` purely for your own keys. Monotone doesn't like having duplicate keys in two places. If you deploy other people's keys into that directory, you will soon also have them in `i2p.mtn`, and Monotone will start reporting an error: "extraneous data in keystore".
It would be inappropriate to supply anyone's GPG public keys in this guide. Find the public keys from an independent source. Current developers have their GPG keys on their eepsites. Jrandom's Syndie release key can be found on a number of public keyservers.
Tip: To find zzz's GPG key, on his eepsite locate the key `0xA76E0BED`, with the name `zzz@mail.i2p` and the fingerprint `4456 EBBE C805 63FE 57E6 B310 4155 76BA A76E 0BED`.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
[pubkey zzz-transport@mail.i2p]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDa2uZI1BobxS4TapMqmf4Ws3nyL3GYgkfb
MEawyWl0E1pfHJ4dLZkdxQdcLyCsN9OCY4jRNzmoYnDa2HtBLINq15BJmGJ0cfIDLXIB2GBO
ViAPRkEKQTVoc7IpcjtPPjtSBVganD/AW78m9cgUYag86Lbm2ynUaXWpw9i4gpLdLQIDAQAB
[end]
[pubkey zzz@mail.i2p]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCtgaWY0Wc1c8pFGIxASZx78pHpHZKQV8z6
IRQkgy65gQMjpLquaQpy3Xk8rkpnfA+6h3TS6bjplsEhlaQoxvpGxacRYOt+y1HC/n20O3RI
E1A/e3sGKHGDEQW+3ItF4WSNfeQ18DzLeun32vFknq2k9im6Ts4tiYfKs8CZ5KW0/QIDAQAB
[end]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQFHnN51QVV2uqduC+0RAv8NAJ9B/7pWKLvqVI6HnAifs9oedsdWSACfYS1E
sFwJiw4A+Sr9wQrtoO4X4ow=
=SVDV
-----END PGP SIGNATURE-----
Tip: To find welterde's GPG key, on public keyservers locate the key `0x62E011A1`, with the name `welterde@arcor.de` and the fingerprint `6720 FD81 3872 6DFC 6016 64D1 EBBC 0374 62E0 11A1`.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
[pubkey dev@welterde.de]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDRnJUBY0d4310UpZYGUlsWgxWHoD8bsKtT
vGw83vwUQRtM2xPKxCHvEntg9Dgiqr5RurOKHK7Eak6WgxCXQFfC9ALr4SoC5abI4ZFvM/CA
WRb547UIPTchSnuDUn/TSgDGqtGvMFS9t6OUp9Z/7QzIjLQhhBCqj4/hZhxUJ61XBwIDAQAB
[end]
[pubkey transport@welterde.de]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCujyq15a7t0Gki/sKoZQbv7CHJWbT3YB5O
DQyU3zfqXnHNj82tz6wVsvjZmKUYZvax7wLLRErMGX3PTGxb23I5iypLmYtWt+lbkxMZdcGT
GEXBU8JnAfhnSIdLzBJ2soe55vBQp0Tx1Ta+7/CNYwVPUxr5l6J/2gcGFJg3cAD99wIDAQAB
[end]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
iD8DBQFHojoC67wDdGLgEaERAsALAKCwNlkNFaTyC4pV4rsinXQ8hu7UvgCbBeeV
Ni/uLlSdl3Kz7KfVipwnjm4=
=oE5t
-----END PGP SIGNATURE-----
Tip: To find Complication's GPG key, on his eepsite locate the key `0x79FCCE33`, with the name `complication@mail.i2p` and the fingerprint `73CF 2862 87A7 E7D2 19FF DB66 FA1D FC6B 79FC CE33`.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
I confirm that my Monotone commit and transport keys are:
[pubkey complication@mail.i2p]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCx1F6nwBUCIiCPVsogy/h/+2d8X3uMcEdn
RIN+gxO+0pK+yrGZiFwi7TG/K3PjDfJWuxsPRKLeb9Q4NmfxrAePelGig9llalrDnRkIcRFu
cnNUOJo9C0MjvzYR9D6bIS3+udPdl6ou94JX+ueo2jLXI1lGgtdWDWTetJx9I++EvwIDAQAB
[end]
[pubkey complication-transport@mail.i2p]
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDP55FmBUIZjamtDinVDrLmS9uU40KoNfLd
iB+t/iEgEWHDPQxlwugh/aBQwsXKGGJMJSNURKwwjfrcr5y3oz9jpRjtLVqoZMBVLgp28WGA
9KbzXi4/dYhdyNmr4gHc17mDSlhCfk/L5QxifSYwSaeeFPsoAAyBBB221Z3197bmVQIDAQAB
[end]
Complication.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQFHpdQT+h38a3n8zjMRAtW8AJ0fmuw1hrZePDzOx61xSh5cK27ikQCeJn+U
g8X/m/JAsedzOFJDN0tlTig=
=LM+C
-----END PGP SIGNATURE-----
Tip: To find jrandom's GPG key for Syndie releases, on public keyservers locate the key `0x393F2DF9`, with the name `syndie-dist-key@i2p.net` and the fingerprint `AE89 D080 0E85 72F0 B777 B2ED C2FA 68C0 393F 2DF9`.
Jrandom had to leave unexpectedly in the end of 2007. His commit key was deployed in the Syndie Monotone repository, in a file named `mtn-committers`. That file also had a GPG signature, `mtn-committers.sig`, but it was a binary detached signature. I am going to supply both files in GPG ASCII-armoured form below.
First, the file `mtn-committers` containing jrandom's Monotone key. Save as `mtn-committers.asc` and unpack it using `gpg --output mtn-committers --dearmor mtn-committers.asc`:
-----BEGIN PGP ARMORED FILE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Use "gpg --dearmor" for unpacking
W3B1YmtleSBqcmFuZG9tQGkycC5uZXRdCk1JR2ZNQTBHQ1NxR1NJYjNEUUVCQVFV
QUE0R05BRENCaVFLQmdRRE9MdzA1a1pidXg1S0xkcHJjR0hlQ1RseXQrR2poR1ho
NwpBdXBzK1FNRC9GRWJJVkVGUEdJQkcyanUzMDY5VEtJSHBYcjVIRWU1bWFCZ3RJ
SkJNOU5QVnZNTkZDZ09TcmVnbW5WSXB4U2cKSGQrV2l1MUl5emhkMFN4QzVwQ0hk
bndTanYwNTFmY3RZY3AxcnM1T2NVb2pVZHZGN3RxOTF6QUFZK2tMeHBYNnpRSURB
UUFCCltlbmRdCg==
=035X
-----END PGP ARMORED FILE-----
Now the file `mtn-committers.sig`, containing the GPG signature. Save as `mtn-committers.sig.asc` and unpack it using `gpg --output mtn-committers.sig --dearmor mtn-committers.sig.asc`. Use it to verify the above supplied `mtn-committers` file:
-----BEGIN PGP ARMORED FILE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Use "gpg --dearmor" for unpacking
iD8DBQBFLssNwvpowDk/LfkRAtytAKCOiaDIveC3sri0lrdvwxt/TQciigCfXgyC
ZY3qq910P/TX94qoJGePbuc=
=8NHt
-----END PGP ARMORED FILE-----
The default Monotone trust policy is way too lax: it trusts every committer like bad old CVS. To operate in I2P, you definitely want to change that.
Change into your `/home/username/.monotone` directory, and open the file `monotonerc` with a text editor. Copy and paste two functions into this file:
function intersection(a,b)
local s={}
local t={}
for k,v in pairs(a) do s[v.name] = 1 end
for k,v in pairs(b) do if s[v] ~= nil then table.insert(t,v) end end
return t
end
function get_revision_cert_trust(signers, id, name, val)
local trusted_signers = {
"jrandom@i2p.net",
"complication@mail.i2p",
"zzz@mail.i2p",
"dev@welterde.de"
}
local t = intersection(signers, trusted_signers)
if t == nil then return false end
if table.getn(t) >= 1 then return true end
return false
end
Read the functions carefully to understand their purpose, and compare them with sample functions and descriptions provided in section 6.1.5 ("Trust evaluation hooks") of the following document: http://monotone.ca/docs/Hooks.html
The first function determines an intersection between two sets, in our case a revision's signers and trusted signers.
The second function determines trust in a given revision, by calling the first function with "signers" and "trusted" as arguments. If the intersection is null, the revision is not trusted. If the intersection is not empty, the revision is trusted. Otherwise, the revision is not trusted.
First, you need to choose a server. Some I2P developers run accessible Monotone servers, but when developers are anonymous, their servers are *very slow*.
When you set up Monotone correctly, code will be authenticated by developers' commit keys, so you should be able to safely use a public Monotone server despite risk of someone subverting it.
For this reason, it's recommended to pull sources and sync your code contributions using our public MTN server operated by welterde: `mtn.i2p2.i2p` inside I2P, or `mtn.i2p2.de` on the regular Internet. I will only provide instructions for accessing it over I2P.
First, you need the I2P destination key of the server. When I wrote this transition guide, its key was not yet included in an I2P installation (in the future it will be). The destination key of `mtn.i2p2.i2p` is:
G6VmsrLYbdcxBq585OUcQn7wbwC7J5jfXDWWL6lPBw5iq68VxqxibraiPwwF6NM2
aHV8BkqyCKYSL9fUuYWoeUc1zL~2l1DX2x~LfyItGJKDIUGImWQivXF1w7EGYMhj
q4UCmPKTsnl4G86oKW8PGaaF8mzjjUKW1R7G7941my~mnbeTrhjlLgaMK-tauVod
gTPIYkxfMJaq3zWuirztuUgDcXXIbkpzaA2Iben0VqbjbMJisj4fFh0EvqNkYAG5
4YBc26~W6SPWyBgZilXvFlcizF90Q5NkIGMMHXTq46qEYHkpQC3CoaH6PMNVDetD
PmFc3QXmc68cNcj~VPh4XVsn3qiKhXuRdXggEC3RoTcxqaeassfIG5xhRdnJzGSV
hYUE3At~8wI-AuRV~AglV1Q-AZTWT~9VxBzcxfI1PpfzeA-5z5T4542bh1e-RM9t
zXEx5ErPCt6M~zJ2~4-tz-aBsZEhBkn0iDi8pazshg6lTl1~hCnueZBxYICqPrlB
AAAA
If you want to copy it from here, you need to manually join the lines back together in a text editor. Sorry, I could not GPG-sign that very long line.
To address this destination using a convenient name, you need to enter it into the host database of your I2P router. This can be done manually by editing the `hosts.txt` file, or more easily using the SusiDNS tool:
Next, you need to create a client tunnel pointing at the server. This can be done manually by editing `i2ptunnel.config` or more easily using the I2PTunnel tool:
When you pull code as a client, the action itself implies that you want data from the server. You thus don't need to grant the server any extra permissions.
Enter the directory where you initialized `i2p.mtn`. Depending on whether you want only I2P sources, or also sources for the I2P website and Syndie, you can perform the `pull` operation in different ways.
If you only want I2P sources:
If you want all branches:
Restart the process if it stops due to network errors. Note how pulling in the above examples is anonymous (doesn't use your transport key). There is a reason for this: when everyone pulls anonymously, it is harder for an attacker who gains control of the server, to selectively provide some people with tampered data. It is therefore advised to pull anonymously.
To verify that trust evaluation works, modify your `monotonerc` file in the following way:
- local trusted_signers = {
- "jrandom@i2p.net",
- "complication@mail.i2p",
- "zzz@mail.i2p",
- "dev@welterde.de"
- }
+ local trusted_signers = {
+ }
Save the file, and your Monotone stops trusting all committers. Change into the directory where you created `i2p.mtn`, and attempt a checkout of the I2P branch like this:
A directory named `i2p.i2p` should *not* appear. You should encounter great numbers of error messages like:
mtn: warning: trust function disliked 1 signers
of branch cert on revision 523c15f6f50cad3bb002f830111fc189732f693b
mtn: warning: trust function disliked 1 signers
of branch cert on revision 8ac13edc2919dbd5bb596ed9f203aa780bf23ff0
mtn: warning: trust function disliked 1 signers
of branch cert on revision 8c4dd8ad4053baabb102a01cd3f91278142a2cd1
mtn: misuse: branch 'i2p.i2p' is empty
If you are satisfied with results, change your `monotonerc` back to match the section Setting up trust evaluation hooks.
When jrandom had to leave, and soon after that `dev.i2p` went down, other developers and server operators (e.g. Complication, zzz, welterde) had to take over his job.
It is important for the I2P project's trustability, that practical and widely known methods exist for verifying that code integrity was preserved. Perhaps the most important part in this is ability to verify the initial import into Monotone by zzz.
Fortunately the 0.6.1.30 source tarball, signed by jrandom, should make verification fairly simple. I will describe the recommended course of action below.
It would be inappropriate to supply jrandom's GPG public key in this guide. Find the public key from an independent source. Jrandom's GPG public key can be found in many places, including a number of public keyservers.
Tip: To find jrandom's GPG key for I2P releases, on public keyservers locate the key `0x065E37EE`, with the name `jrandom@i2p.net` and the fingerprint `829E F1C6 89A5 72DC E66F D5BF 42E2 7451 065E 37EE`.
There are multiple places where you can find the 0.6.1.30 source tarball and signature. I will provide two, and recommend the first one, since it's massively faster.
Deploy the tarball and signature into the directory where `i2p.mtn` is. Assuming you have jrandom's GPG key imported into your GPG keyring, verify the tarball this way:
Extract the tarball into a source tree like below, and a directory named `i2p_0_6_1_30` should appear.
To compare code in Monotone against the source tarball, we must check out the revision which corresponds to 0.6.1.30 from Monotone.
That revision is `928aadc3796083b8412829c2d18e95fdeecd8196`. To check it out, change into the directory where `i2p.mtn` is located, and over there issue:
A directory named `i2p.i2p` must appear in the current directory. You may notice that it contains a subdirectory named `_MTN`, which the source tarball does not contain.
That subdirectory is for Monotone internal use. We'll ignore it while diffing. To ascertain that the extra directory is safe, you can perform a few checks:
To perform a recursive (`-r`) `diff` of the source tarball against the Monotone checkout, writing output into `result.diff`, treating absent files and directories as empty (`-N`) for comparison, and excluding (`-x`) any `_MTN` subdirectories, you should issue:
You should read `changes.diff` with a text editor. Your work will be easier if your text editor highlights `diff` syntax, but that is optional. The only kind of changes you should see are:
That should be all. The diff ought be about 300 lines long. There should be absolutely no changes in anything but formal tags. If you see consequential changes in code, please report.
To examine what has been modified from the current moment back to release
0.6.1.30, use ordinary Monotone facilities. For example you could change into
the `i2p.i2p` directory and there issue:
$ mtn update
$ mtn log --to="928aadc3796083b8412829c2d18e95fdeecd8196" > ../changes.log
$ mtn diff --revision="928aadc3796083b8412829c2d18e95fdeecd8196" > ../changes.diff
The first command would update your local copy to the "head" or latest version. The second one would print a concise log of changes going back to 0.6.1.30, into a file in the parent directory of the working copy, and the third command would print a full diff into another file.
This diff will be *big*, and will get bigger with development. Fortunately there are compelling reasons to read it only during a short period after the transition.
Do this only if you haven't already checked out a working copy. If you checked it out according to the section Checking out 0.6.1.30 sources from Monotone, skip to the next section and do an update instead.
Change into the directory where `i2p.mtn` is located. Over there issue:
Checkout should complete without error messages, and a directory named `i2p.i2p` should appear in the current directory. Congratulations, you have successfully checked out the latest I2P sources. They should be ready to compile.
If you haven't done this already, pull fresh code from the server to your local Monotone repository. To accomplish this, change into the directory where `i2p.mtn` is located and issue:
Now change into your `i2p.i2p` directory, and over there issue:
Congratulations, you have successfully updated to the latest I2P sources. They should be ready to compile.
The branch `www.i2p` cannot be properly verified, because jrandom did not produce signed tarballs of it.
Fortunately, only a few people need the project website, and it's small enough to review manually in a modest period of time. I thus hope it's not a risk which comes back to bite us.
Changes which occur in this branch since its import into Monotone will be verifiable in future.
Because it was verified using jrandom's Monotone key.
If you obtained the `mtn-committers` and `mtn-committers.sig` files from this guide, and obtained jrandom's Syndie release key from an independent source, and the signature verified, one of the following should be true:
However if the signed tarball should become available, this document will be updated with information about it.
As a server operator you may want to grant push access to certain developers.
If development is distributed between multiple servers you may also want to give other servers push access. Servers also have transport keys -- ask the server operators for them.
The procedure for importing transport keys is the same as for importing commit keys, which is described in the section Servers, and creating a client tunnel to `mtn.i2p2.i2p`.
By default the Monotone server denies all access.
To grant pull access to all clients, set the following in
`/home/username/.monotone/read-permissions`:
pattern "*"
allow "*"
To grant push access to certain developers, add their transport keys to
`/home/username/.monotone/write-permissions`:
zzz-transport@mail.i2p
complication-transport@mail.i2p
First, to run a Monotone server, don't use your development database. Monotone locks a database while serving it to others, and this will greatly inconvenience your development work.
Instead, make a copy of your development database -- possibly into a different directory, possibly for a different user (your choice) and finally in the right directory. As the right user issue something like:
If your key is protected with a passphrase, Monotone may request the passphrase not during startup, but when the first client connects. This is probably a bug in Monotone, and will be fixed. You can get around this effect by connecting as a client to your own server.
For your server to be accessible for others over I2P, you will need to create a server tunnel for it. Use the "Standard" tunnel type and "Bulk" profile.
Some Linux distros have taken an extra step and integrated Monotone into their framework of daemons/services. Debian is among them, even though you can run Monotone "the ordinary way" under Debian too.
You can find the `read-permissions`, `write-permissions` and `hooks.lua` file under `/etc/monotone`.
You'll likely need to modify `/etc/default/monotone`, since it contains settings like the interface to listen on, and the location of data files (`i2p.mtn`).
A script `/etc/init.d/monotone` is provided for running a Monotone server. You can register it for running automatically using `update-rc.d`.
When more information becomes available it will be added here.
{% endblock %}