518 lines
18 KiB
HTML
518 lines
18 KiB
HTML
{% extends "global/layout.html" %}
|
||
{% block title %}{% trans %}Monotone Guide{% endtrans %}{% endblock %}
|
||
{% block content_nav %}
|
||
<ol>
|
||
<li>
|
||
<a href="#operating-a-monotone-client">{% trans %}Operating a Monotone client{% endtrans %}</a>
|
||
<ol>
|
||
<li><a href="#generating-monotone-keys">{% trans %}Generating Monotone keys{% endtrans %}</a></li>
|
||
<li><a href="#trust-and-initializing-your-repository">{% trans %}Trust and initializing your repository{% endtrans %}</a></li>
|
||
<li> <a href="#obtaining-and-deploying-developers-keys">{% trans %}Obtaining and deploying developers' keys{% endtrans %}</a></li>
|
||
<li><a href="#setting-up-trust-evaluation-hooks">{% trans %}Setting up trust evaluation hooks{% endtrans %}</a></li>
|
||
<li><a href="#pulling-the-i2p.i2p-i2p.www-and-i2p.syndie-branches">{% trans %}Pulling the <code>i2p.i2p</code>, <code>i2p.www</code> and <code>i2p.syndie</code> branches{% endtrans %}</a></li>
|
||
<li><a href="#verifying-that-trust-evaluation-works">{% trans %}Verifying that trust evaluation works{% endtrans %}</a></li>
|
||
<li><a href="#checking-out-a-working-copy-of-the-latest-version">{% trans %}Checking out a working copy of the latest version{% endtrans %}</a></li>
|
||
<li><a href="#updating-your-working-copy-to-the-latest-version">{% trans %}Updating your working copy to the latest version{% endtrans %}</a></li>
|
||
</ol>
|
||
</li>
|
||
<li>
|
||
<a href="#operating-a-monotone-server">{% trans %}Operating a Monotone Server{% endtrans %}</a>
|
||
<ol>
|
||
<li><a href="#obtaining-and-deploying-developers-transport-keys">{% trans %}Obtaining and deploying developers’ transport keys{% endtrans %}</a></li>
|
||
<li><a href="#granting-push-and-pull-access">{% trans %}Granting push and pull access{% endtrans %}</a></li>
|
||
<li><a href="#running-monotone-in-server-mode">{% trans %}Running Monotone in server mode{% endtrans %}</a></li>
|
||
<li><a href="#differences-under-debian-gnulinux">{% trans %}Differences under Debian GNU/Linux{% endtrans %}</a></li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
{% endblock %}
|
||
|
||
{% block content %}
|
||
<p><i>
|
||
{% trans transitionguide=site_url('misc/transition-guide'), newdevs=site_url('get-involved/guides/new-developers') -%}
|
||
This is a revised version of <a href="{{ transitionguide }}">Complication's original
|
||
guide</a> detailing the use of Monotone in I2P development.
|
||
For basic instructions see the <a href="{{ newdevs }}">quick-start guide</a>.
|
||
{%- endtrans %}
|
||
</i></p>
|
||
|
||
<p>
|
||
{% trans licenses=site_url('get-involved/develop/licenses') -%}
|
||
I2P has a distributed development model. The source code is replicated across
|
||
independently administered <a href="http://www.monotone.ca/">Monotone</a> ("MTN") repositories.
|
||
Developers with commit rights are able to push their changes to the repository
|
||
(a <a href="{{ licenses }}#commit">license agreement</a> needs to be signed
|
||
before commit rights are granted).
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Some of Monotone's noteworthy qualities are: distributed
|
||
version control, cryptographic authentication, access control, its small size, having few
|
||
dependencies, storage of projects in a compressed SQLite database file, and
|
||
having the ability to resume interrupted synchronization attempts.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h2 id="operating-a-monotone-client">{% trans %}Operating a Monotone Client{% endtrans %}</h2>
|
||
|
||
<h3 id="generating-monotone-keys">{% trans %}Generating Monotone keys{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
A transport key grants you the ability to push your changes to a Monotone repository server.
|
||
In order to commit code into Monotone (in essence signing your code), a commit key is also needed.
|
||
None of the public Monotone servers on I2P currently require a key in order to read (or pull) the source code.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Without a transport key, one cannot:
|
||
<ul>
|
||
<li>pull code from a server which doesn't allow global read access</li>
|
||
<li>push code to any server</li>
|
||
<li>run a Monotone server</li>
|
||
</ul>
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Without a commit key, one cannot:
|
||
<ul>
|
||
<li>commit any code</li>
|
||
</ul>
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
If you only intend to retrieve code from MTN, feel free to skip to the
|
||
<a href="#trust-and-initializing-your-repository">next section</a>. If you want
|
||
to generate keys, read the following.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
By convention keys are named like an e-mail addresses, but a corresponding e-mail
|
||
address does not need to exist. For example, your keys might be named:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>yourname@mail.i2p</li>
|
||
<li>yourname-transport@mail.i2p</li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Monotone stores keys under <code><b>$HOME/.monotone/keys</b></code> in text files which
|
||
are named identically to the keys. For example:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>/home/complication/.monotone/keys/complication@mail.i2p</code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
To generate transport and commit keys, enter the following commands at a prompt:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn genkey yourname-transport@someplace</b></code></li>
|
||
<li><code>$ <b>mtn genkey yourname@someplace</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Monotone will prompt you for a password to protect your keys. You are very strongly encouraged to set a password
|
||
for the commit key. Many users will leave an empty password for the transport key, especially those running a
|
||
Monotone server.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="trust-and-initializing-your-repository">{% trans %}Trust, and initializing your repository{% endtrans %}</h3>
|
||
|
||
<p>
|
||
<i>
|
||
{% trans -%}
|
||
Monotone's security model helps to ensure that nobody can easily impersonate a developer without
|
||
it being noticed. Since developers can make mistakes and become compromised,only manual review can
|
||
ensure quality of code. Monotone's trust model will ensure that you read the right diffs. It does
|
||
not replace reading diffs.
|
||
{%- endtrans %}
|
||
</i>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
A Monotone repository is a single file (a compressed SQLite database) which contains all of the project's source code and history.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
After <a href="#obtaining-and-deploying-developers-keys">importing the developers' keys into Monotone</a> and
|
||
<a href="#setting-up-trust-evaluation-hooks">setting up trust evaluation hooks</a>,
|
||
Monotone will prevent untrusted code from being checked out into your workspace.
|
||
There are commands available to clean untrusted code from your workspace but in practice they've not been
|
||
needed due to the push access policies in place.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
A repository can hold many branches. For example, our repository holds the
|
||
following main branches:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><b>i2p.i2p</b> — {% trans %}The I2P router and associated programs{% endtrans %}</li>
|
||
<li><b>i2p.www</b> — {% trans %}The I2P project website{% endtrans %}</li>
|
||
<li><b>i2p.syndie</b> — {% trans %}Syndie, a distributed forums tool{% endtrans %}</li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
By convention, the I2P Monotone repository is named <code>i2p.mtn</code>. Before pulling
|
||
source code from servers, a database for your repository will need to be initialized.
|
||
To initialize your local repository, change into the directory that you want the
|
||
<code>i2p.mtn</code> file and branch directories to be stored and issue the following
|
||
command:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn --db="i2p.mtn" db init</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
|
||
<h3 id="obtaining-and-deploying-developers-keys">{% trans %}Obtaining and deploying developers' keys{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Keys which developers use to commit code are essential for trust evaluation in
|
||
Monotone. The other developers' transport keys are only required for Monotone server operators.
|
||
{% endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans signedkeys=site_url('get-involved/develop/signed-keys') -%}
|
||
Developers' commit keys are provided GPG-signed <a href="{{ signedkeys }}">on another page</a>.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans devkeys=site_url('get-involved/develop/developers-keys') -%}
|
||
To import developers' keys after verifying their authenticity, copy <a href="{{ devkeys }}">all of the keys</a> into a new
|
||
file. Create this file (e.g. <code><b>keys.txt</b></code>) in the same directory where <code>i2p.mtn</code> is located. Import the keys with the command:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn --db="i2p.mtn" read < keys.txt</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
<b>Note</b>: <i>Never</i> add keys to <code><b>$HOME/.monotone/keys</b></code> manually.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<h3 id="setting-up-trust-evaluation-hooks">{% trans %}Setting up trust evaluation hooks{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
The default Monotone trust policy is way too lax for our requirements: every committer is trusted by default.
|
||
That is not acceptable for I2P development.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Change into the directory <code><b>$HOME/.monotone</b></code> and open the file
|
||
<code>monotonerc</code> with a text editor. Copy and paste the following two functions into this file:
|
||
{%- endtrans %}
|
||
<p>
|
||
|
||
{% include "include/monotonerc.html" %}
|
||
|
||
<p>
|
||
{% trans -%}
|
||
The first function determines an intersection between two sets, in our case a
|
||
revision's signers and trusted signers.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
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.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
More information about Trust Evaluation Hooks can be found in the <a href="http://www.monotone.ca/docs/Hooks.html">official Monotone documentation</a>.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="pulling-the-i2p.i2p-i2p.www-and-i2p.syndie-branches">{% trans %}Pulling the <code>i2p.i2p</code>, <code>i2p.www</code> and <code>i2p.syndie</code> branches{% endtrans %}</h3>
|
||
<p>
|
||
{% trans -%}
|
||
I2P is shipped with a pre-configured tunnel pointing to the project Monotone server. Ensure that the tunnel has been started
|
||
within <a href="http://127.0.0.1:7657/i2ptunnel">I2PTunnel</a> before attempting to pull the source code from 127.0.0.1:8998.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Enter the directory where you initialized <code>i2p.mtn</code>. Depending on whether you
|
||
want only I2P sources, or also sources for the I2P website and Syndie, you can
|
||
perform the <code>pull</code> operation in different ways.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
If you only want I2P sources:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn --db="i2p.mtn" -k "" pull "mtn://127.0.0.1:8998?i2p.i2p"</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
If you want all branches:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn --db="i2p.mtn" -k "" pull "mtn://127.0.0.1:8998?i2p.*"</b></code></li>
|
||
</ul>
|
||
{% trans -%}
|
||
If the transfer aborts before completing sucessfully, simply repeating the pull command will resume the transfer.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Pulling in the above examples is done anonymously by specifying an empty transport key.
|
||
If everyone pulls anonymously it will be harder for an attacker who gains control of the server
|
||
to selectively provide some people with tampered data.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="verifying-that-trust-evaluation-works">{% trans %}Verifying that trust evaluation works{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
To verify that trust evaluation works:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>{% trans %}Make a backup of your <code>monotonerc</code> file.{% endtrans %}</li>
|
||
<li>{% trans %}Modify <code><b>monotonerc</b></code> by setting the trusted_signers variable in the following way:{% endtrans %}
|
||
<code><pre>
|
||
local trusted_signers = {}
|
||
</pre></code>
|
||
</li>
|
||
<li>
|
||
{% trans -%}
|
||
With <code><b>monotonerc</b></code> configured as above, Monotone will no longer trust any committers. Confirm this by changing into the
|
||
directory where <code>i2p.mtn</code> was created and attempt a checkout of the I2P branch:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li><code>$ <b>mtn --db="i2p.mtn" co --branch="i2p.i2p"</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
A directory named <code>i2p.i2p</code> should <b>not</b> appear. You should encounter many
|
||
error messages like:
|
||
{%- endtrans %}
|
||
|
||
<code><pre>
|
||
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
|
||
</pre></code>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
If you are satisfied with results, restore the backup of
|
||
<code>monotonerc</code> that was created above. If you didn't create a backup
|
||
as advised, re-read <a href="#setting-up-trust-evaluation-hooks">Setting up trust evaluation hooks</a>.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="checking-out-a-working-copy-of-the-latest-version">{% trans %}Checking out a working copy of the latest version{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
If you already have a branch checked out, skip to the <a href="#updating-your-working-copy-to-the-latest-version">next
|
||
section</a>.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Change into the directory where <code>i2p.mtn</code> is located. Over there issue:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>$ <code><b>mtn --db="i2p.mtn" co --branch="i2p.i2p"</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
The checkout should complete without error messages and a directory named
|
||
<code>i2p.i2p</code> should appear in the current directory. Congratulations! You have
|
||
successfully checked out the latest I2P sources, ready to be compiled.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="updating-your-working-copy-to-the-latest-version">{% trans %}Updating your working copy to the latest version{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
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
|
||
<code>i2p.mtn</code> is located and issue:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>$ <code><b>mtn --db="i2p.mtn" -k "" pull "mtn://127.0.0.1:8998?i2p.i2p"</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Now change into your <code>i2p.i2p</code> directory, and over there issue:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>$ <code><b>mtn update</b></code></li>
|
||
</ul>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
As long as there were no errors…Congratulations! You have successfully updated to the latest I2P sources. They
|
||
should be ready to compile.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h2 id="operating-a-monotone-server">{% trans %}Operating a Monotone Server{% endtrans %}</h2>
|
||
|
||
<h3 id="obtaining-and-deploying-developers-transport-keys">{% trans %}Obtaining and deploying developers' transport keys{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
As a server operator you may want to grant push access to certain developers.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<h3 id="granting-push-and-pull-access">{% trans %}Granting push and pull access{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
By default the Monotone server denies all access.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
To grant pull access to all clients, set the following in
|
||
{%- endtrans %}
|
||
<code>$HOME/.monotone/read-permissions</code>:
|
||
|
||
<code><pre>
|
||
pattern "*"
|
||
allow "*"
|
||
</pre></code>
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
No one will not be able to push code to your server without permission being explicitly granted. To grant push access:
|
||
{%- endtrans %}
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
{% trans -%}
|
||
Add the name of the user's transport key to
|
||
<code>$HOME/.monotone/write-permissions</code>, such as
|
||
<code><pre>
|
||
zzz-transport@mail.i2p
|
||
complication-transport@mail.i2p
|
||
</pre></code>
|
||
with one key per line.
|
||
{%- endtrans %}
|
||
</li>
|
||
<li>
|
||
{% trans -%}
|
||
Import the transport key(s) into your database. The procedure for importing transport keys is the same as for
|
||
importing commit keys, which is described in the section <a href="#obtaining-and-deploying-developers-keys">Obtaining and deploying developers' keys</a>.
|
||
{%- endtrans %}
|
||
</li>
|
||
</ul>
|
||
|
||
<h3 id="running-monotone-in-server-mode">{% trans %}Running Monotone in server mode{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
A separate database should be used for your Monotone server because monotone will lock the database while it is served to others.
|
||
Make a copy of your development database, then start the server with:
|
||
{%- endtrans %}
|
||
<ul>
|
||
<li>$ <code><b>mtn serve --bind="127.0.0.1:8998" --db="i2p.mtn" --key "myserver-transport@mail.i2p"</b></code></li>
|
||
</ul>
|
||
{% trans -%}
|
||
If your key is protected with a passphrase, Monotone may request the passphrase
|
||
when the first client connects. You can work around this by connecting making the first client connection to your server
|
||
(or by clearing the password for your transport key).
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
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.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
|
||
<h3 id="differences-under-debian-gnulinux">{% trans %}Differences under Debian GNU/Linux{% endtrans %}</h3>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Debian (amongst other distributions) has integrated Monotone into their
|
||
framework of daemons/services. Although Monotone servers can still be run
|
||
"the ordinary way" on Debian systems, doing it the "Debian way" may be more straightforward.
|
||
{%- endtrans %}
|
||
</p>
|
||
|
||
<p>
|
||
{% trans -%}
|
||
Permissions are granted by editing the files
|
||
<code>/etc/monotone/read-permissions</code> and
|
||
<code>/etc/monotone/write-permissions</code>. You'll also need to edit
|
||
<code>/etc/default/monotone</code> to enable monotone to start at boot or to
|
||
customize the host, port, or database location.
|
||
{%- endtrans %}
|
||
</p>
|
||
{% endblock %}
|