i2p.www/www.i2p2/pages/monotone.html

{% extends "_layout.html" %}
{% block title %}Monotone{% endblock %}
{% block content %}
<h1>Monotone Guide</h1>

<div id="TOC">
  <ol>
    <li>
      <a href="#operating-a-monotone-client">Operating a Monotone client</a>
      <ol>
        <li><a href="#generating-monotone-keys">Generating Monotone keys</a></li>
        <li><a href="#trust-and-initializing-your-repository">Trust and initializing your repository</a></li>
        <li> <a href="#obtaining-and-deploying-developers-keys">Obtaining and deploying developers' keys</a></li>
        <li><a href="#setting-up-trust-evaluation-hooks">Setting up trust evaluation hooks</a></li>
        <li><a href="#pulling-the-i2p.i2p-i2p.www-and-i2p.syndie-branches">Pulling the <code>i2p.i2p</code>, <code>i2p.www</code> and <code>i2p.syndie</code> branches</a></li>
        <li><a href="#verifying-that-trust-evaluation-works">Verifying that trust evaluation works</a></li>
        <li><a href="#checking-out-a-working-copy-of-the-latest-version">Checking out a working copy of the latest version</a></li>
        <li><a href="#updating-your-working-copy-to-the-latest-version">Updating your working copy to the latest version</a></li>
      </ol>
    </li>
    <li>
      <a href="#operating-a-monotone-server">Operating a Monotone Server</a>
      <ol>
        <li><a href="#obtaining-and-deploying-developers-transport-keys">Obtaining and deploying developers’ transport keys</a></li>
        <li><a href="#granting-push-and-pull-access">Granting push and pull access</a></li>
        <li><a href="#running-monotone-in-server-mode">Running Monotone in server mode</a></li>
        <li><a href="#differences-under-debian-gnulinux">Differences under Debian GNU/Linux</a></li>
      </ol>
    </li>
  </ol>
</div>

<p>
  <i>This is a revised version of <a href="transition-guide.txt">Complication's original
  guide</a> detailing the use of Monotone in I2P development.
  For basic instructions see the <a href="newdevelopers.html">quick-start guide</a>.</i>
</p>

<p>
  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.html#commit">license agreement</a>
  needs to be signed before commit rights are granted).
</p>

<p>
  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.
</p>


<h2 id="operating-a-monotone-client">Operating a Monotone Client</h2>

<h3 id="generating-monotone-keys">Generating Monotone keys</h3>

<p>
  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.
</p>

<p>
  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>
</p>

<p>
  Without a commit key, one cannot:
  <ul>
    <li>commit any code</li>
  </ul>
</p>

<p>
  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.
</p>

<p>
  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:
  <ul>
    <li>yourname@mail.i2p</li>
    <li>yourname-transport@mail.i2p</li>
  </ul>
</p>

<p>
  Monotone stores keys under <code><b>$HOME/.monotone/keys</b></code> in text files which
  are named identically to the keys. For example:
  <ul>
    <li><code>/home/complication/.monotone/keys/complication@mail.i2p</code></li>
  </ul>
</p>

<p>
  To generate transport and commit keys, enter the following commands at a prompt:
  <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>
  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.
</p>


<h3 id="trust-and-initializing-your-repository">Trust, and initializing your repository</h3>

<p>
  <i>
  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.
  </i>
</p>

<p>
  A Monotone repository is a single file (a compressed SQLite database) which contains all of the project's source code and history.
</p>

<p>
  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.
</p>

<p>
  A repository can hold many branches. For example, our repository holds the
  following main branches:
  <ul>
    <li><b>i2p.i2p</b> &mdash; The I2P router and associated programs</li>
    <li><b>i2p.www</b> &mdash; The I2P project website</li>
    <li><b>i2p.syndie</b> &mdash; Syndie, a distributed forums tool</li>
  </ul>
</p>

<p>
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:
  <ul>
    <li><code>$ <b>mtn --db="i2p.mtn" db init</b></code></li>
  </ul>
</p>


<h3 id="obtaining-and-deploying-developers-keys">Obtaining and deploying developers' keys</h3>

<p>
  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.
</p>

<p>
Developers' commit keys are provided GPG-signed <a href="signedkeys">on another page</a>.
</p>

<p>
To import developers' keys after verifying their authenticity, copy <a href="developerskeys.html">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:
  <ul>
    <li><code>$ <b>mtn --db="i2p.mtn" read < keys.txt</b></li>
  </ul>
</p>

<p>
  <b>Note</b>: <i>Never</i> add keys to <code><b>$HOME/.monotone/keys</b></code> manually.
</p>

<h3 id="setting-up-trust-evaluation-hooks">Setting up trust evaluation hooks</h3>

<p>
  The default Monotone trust policy is way too lax for our requirements: every comitter is trusted by default.
  That is not acceptable for I2P development.
</p>

<p>
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:
<p>

{% include "_monotonerc.html" %}

<p>
  The first function determines an intersection between two sets, in our case a
  revision's signers and trusted signers.
</p>

<p>
  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.
</p>

<p>
More information about Trust Evauluation Hooks can be found in the <a href="http://monotone.ca/docs/Hooks.html">official Monotone documentation</a>.
</p>


<h3 id="pulling-the-i2p.i2p-i2p.www-and-i2p.syndie-branches">Pulling the <code>i2p.i2p</code>, <code>i2p.www</code> and <code>i2p.syndie</code> branches</h3>

<p>
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.
</p>

<p>
  If you only want I2P sources:
  <ul>
    <li><code>$ <b>mtn --db="i2p.mtn" -k "" pull 127.0.0.1:8998 i2p.i2p</b></code></li>
  </ul>
</p>

<p>
  If you want all branches:
  <ul>
    <li><code>$ <b>mtn --db="i2p.mtn" -k "" pull 127.0.0.1:8998 "i2p.*"</b></code></li>
  </ul>
  If the transfer aborts before completing sucessfully, simply repeating the pull command will resume the transfer.
</p>

<p>
  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.
</p>


<h3 id="verifying-that-trust-evaluation-works">Verifying that trust evaluation works</h3>

<p>
To verify that trust evaluation works:
<ul><li>Make a backup of your <code>monotonerc</code> file.</li>
  <li>Modify <code><b>monotonerc</b></code> by setting the trusted_signers variable in the following way:
<code><pre>
     local trusted_signers = {}
</pre></code>
</li>
  <li>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:
  <ul>
    <li><code>$ <b>mtn --db="i2p.mtn" co --branch="i2p.i2p"</b></code></li>
  </ul>
</p>

<p>
A directory named <code>i2p.i2p</code> should <b>not</b> appear. You should encounter many
  error messages like:

<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>
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 hools</a>.
</p>


<h3 id="checking-out-a-working-copy-of-the-latest-version">Checking out a working copy of the latest version</h3>

<p>
  If you already have a branch checked out, skip to the <a href="#updating-your-working-copy-to-the-latest-version">next
  section</a>.
</p>

<p>
Change into the directory where <code>i2p.mtn</code> is located. Over there issue:
  <ul>
    <li>$ <code><b>mtn --db="i2p.mtn" co --branch="i2p.i2p"</b></code></li>
  </ul>
</p>

<p>
  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.
</p>


<h3 id="updating-your-working-copy-to-the-latest-version">Updating your working copy to the latest version</h3>

<p>
  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:
  <ul>
    <li>$ <code><b>mtn --db="i2p.mtn" -k "" pull 127.0.0.1:8998 i2p.i2p</b></code></li>
  </ul>
</p>

<p>
Now change into your <code>i2p.i2p</code> directory, and over there issue:
  <ul>
    <li>$ <code><b>mtn update</b></code></li>
  </ul>
</p>

<p>
  As long as there were no errors&hellip;Congratulations! You have successfully updated to the latest I2P sources. They
  should be ready to compile.
</p>


<h2 id="operating-a-monotone-server">Operating a Monotone Server</h2>

<h3 id="obtaining-and-deploying-developers-transport-keys">Obtaining and deploying developers' transport keys</h3>

<p>
  As a server operator you may want to grant push access to certain developers.
</p>

<h3 id="granting-push-and-pull-access">Granting push and pull access</h3>

<p>
  By default the Monotone server denies all access.
</p>

<p>
  To grant pull access to all clients, set the following in
  <code>$HOME/.monotone/read-permissions</code>:

<code><pre>
    pattern "*"
    allow "*"
</pre></code>
</p>

<p>No one will not be able to push code to your server without permission being explicitly granted. To grant push access:
<ul><li>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.
  </li>
<li>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>.
</li></ul>
</p>

<h3 id="running-monotone-in-server-mode">Running Monotone in server mode</h3>

<p>
  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:
  <ul>
    <li>$ <code><b>mtn serve --bind="127.0.0.1:8998" --db="i2p.mtn" --key "myserver-transport@mail.i2p"</b></code></li>
  </ul>
  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).
</p>

<p>
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.
</p>


<h3 id="differences-under-debian-gnulinux">Differences under Debian GNU/Linux</h3>

<p>
  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.
</p>

<p>
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.
</p>
{% endblock %}