en/glep/glep-0044.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
  <title>GLEP 44 -- Manifest2 format</title>
  <link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0044.txt">GLEP Source</a></b>]
</td></tr></table>
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">44</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Manifest2 format</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.8</td>
</tr>
<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0044.txt?cvsroot=gentoo">2009/01/11 19:40:56</a></td>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marius Mauch &lt;genone&#32;&#97;t&#32;gentoo.org&gt;,</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="glep-0002.html">text/x-rst</a></td>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">04-Dec-2005</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">06-Dec-2005, 23-Jan-2006, 3-Sep-2006</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#abstract" id="id9">Abstract</a></li>
<li><a class="reference internal" href="#motivation" id="id10">Motivation</a></li>
<li><a class="reference internal" href="#specification" id="id11">Specification</a><ul>
<li><a class="reference internal" href="#compability-entries" id="id12">Compability Entries</a></li>
<li><a class="reference internal" href="#scope" id="id13">Scope</a></li>
<li><a class="reference internal" href="#number-of-hashes" id="id14">Number of hashes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#rationale" id="id15">Rationale</a><ul>
<li><a class="reference internal" href="#removal-of-digest-files" id="id16">Removal of digest files</a></li>
<li><a class="reference internal" href="#reducing-redundancy" id="id17">Reducing redundancy</a></li>
<li><a class="reference internal" href="#removal-of-checksum-collisions" id="id18">Removal of checksum collisions</a></li>
<li><a class="reference internal" href="#flexible-verification-system" id="id19">Flexible verification system</a></li>
</ul>
</li>
<li><a class="reference internal" href="#backwards-compatibility" id="id20">Backwards Compatibility</a></li>
<li><a class="reference internal" href="#other-problems" id="id21">Other problems</a><ul>
<li><a class="reference internal" href="#impacts-on-infrastructure" id="id22">Impacts on infrastructure</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reference-implementation" id="id23">Reference Implementation</a></li>
<li><a class="reference internal" href="#options" id="id24">Options</a></li>
<li><a class="reference internal" href="#credits" id="id25">Credits</a></li>
<li><a class="reference internal" href="#references" id="id26">References</a></li>
<li><a class="reference internal" href="#copyright" id="id27">Copyright</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id9">Abstract</a></h1>
<p>This GLEP proposes a new format for the Portage Manifest and digest file system
by unifying both filetypes into one to improve functional and non-functional
aspects of the Portage Tree.</p>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id10">Motivation</a></h1>
<p>Please see <a class="footnote-reference" href="#reorg-thread" id="id1">[1]</a> for a general overview.
The main long term goals of this proposal are to:</p>
<ul class="simple">
<li>Remove the tiny digest files from the tree. They are a major annoyance as on a
typical configuration they waste a lot of disk space and the simple transmission
of the names for all digest files during a <tt class="docutils literal">emerge <span class="pre">--sync</span></tt> needs a substantial
amount of bandwidth.</li>
<li>Reduce redundancy when multiple hash functions are used</li>
<li>Remove potential for checksum collisions if a file is recorded in more than one
digest file</li>
<li>Difference between filetypes for a more flexible verification system</li>
</ul>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id11">Specification</a></h1>
<p>The new Manifest format would change the existing format in the following ways:</p>
<ul>
<li><p class="first">Addition of a filetype specifier, currently planned are</p>
<ul class="simple">
<li><tt class="docutils literal">AUX</tt> for files directly used by ebuilds (e.g. patches or initscripts),
located in the <tt class="docutils literal">files/</tt> subdirectory</li>
<li><tt class="docutils literal">EBUILD</tt> for all ebuilds</li>
<li><tt class="docutils literal">MISC</tt> for files not directly used by ebuilds like <tt class="docutils literal">ChangeLog</tt> or
<tt class="docutils literal">metadata.xml</tt> files</li>
<li><tt class="docutils literal">DIST</tt> for release tarballs recorded in the <tt class="docutils literal">SRC_URI</tt> variable of an ebuild,
these were previously recorded in the digest files</li>
</ul>
<p>Future portage improvements might extend this list (for example with types
relevant for eclasses or profiles)</p>
</li>
<li><p class="first">Only have one line per file listing all information instead of one line per
file and checksum type</p>
</li>
<li><p class="first">Remove the separated digest-* files in the <tt class="docutils literal">files/</tt> subdirectory</p>
</li>
</ul>
<p>Each line in the new format has the following format:</p>
<pre class="literal-block">
&lt;filetype&gt; &lt;filename&gt; &lt;filesize&gt; &lt;chksumtype1&gt; &lt;chksum1&gt; ... &lt;chksumtypen&gt; &lt;chksumn&gt;
</pre>
<p>However theses entries will be stored in the existing Manifest files.</p>
<p>An <a class="reference external" href="glep-0044-extras/manifest2-example.txt">actual example</a> <a class="footnote-reference" href="#id7" id="id8">[6]</a> for a (pure) Manifest2 file..</p>
<div class="section" id="compability-entries">
<h2><a class="toc-backref" href="#id12">Compability Entries</a></h2>
<p>To maintain compability with existing portage versions a transition period after
is the introduction of the Manifest2 format is required during which portage
will not only have to be capable of using existing Manifest and digest files but
also generate them in addition to the new entries.
Fortunately this can be accomplished by simply mixing old and new style entries
in one file for the Manifest files, existing portage versions will simply ignore
the new style entries. For the digest files there are no new entries to care
about.</p>
</div>
<div class="section" id="scope">
<h2><a class="toc-backref" href="#id13">Scope</a></h2>
<p>It is important to note that this proposal only deals with a change of the
format of the digest and Manifest system.</p>
<p>It does not expand the scope of it to cover eclasses, profiles or anything
else not already covered by the Manifest system, it also doesn't affect
the Manifest signing efforts in any way (though the implementations of both
might be coupled).</p>
<p>Also while multiple hash functions will become standard with the proposed
implementation they are not a specific feature of this format <a class="footnote-reference" href="#multi-hash-thread" id="id3">[2]</a>.</p>
</div>
<div class="section" id="number-of-hashes">
<h2><a class="toc-backref" href="#id14">Number of hashes</a></h2>
<p>While using multiple hashes for each file is a major feature of this proposal
we have to make sure that the number of hashes listed is limited to avoid
an explosion of the Manifest size that would revert the main benefit of this proposal
(reduzing tree size). Therefore the number of hashes that will be generated
will be limited to three different hash functions. For compability though we
have to rely on at least one hash function to always be present, this proposal
suggest to use SHA1 for this purpose (as it is supposed to be more secure than MD5
and currently only SHA1 and MD5 are directly available in python, also MD5 doesn't
have any benefit in terms of compability).</p>
</div>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id15">Rationale</a></h1>
<p>The main goals of the proposal have been listed in the <a class="reference internal" href="#motivation">Motivation</a>, here now
the explanation why they are improvements and how the proposed format will
accomplish them.</p>
<div class="section" id="removal-of-digest-files">
<h2><a class="toc-backref" href="#id16">Removal of digest files</a></h2>
<p>Normal users that don't use a &quot;tuned&quot; filesystem for the portage tree are
wasting several dozen to a few hundred megabytes of disk space with the current
system, largely caused by the digest files.
This is due to the filesystem overhead present in most filesystem that
have a standard blocksize of four kilobytes while most digest files are under
one kilobyte in size, so this results in approximately a waste of three kilobytes
per digest file (likely even more). At the time of this writing the tree contains
roughly 22.000 digest files, so the overall waste caused by digest files is
estimated at about 70-100 megabytes.
Furthermore it is assumed that this will also reduce the disk space wasted by
the Manifest files as they now contain more content, but this hasn't been
verified yet.</p>
<p>By unifying the digest files with the Manifest these tiny files are eliminated
(in the long run), reducing the apparent tree size by about 20%, benefitting
both users and the Gentoo infrastructure.</p>
</div>
<div class="section" id="reducing-redundancy">
<h2><a class="toc-backref" href="#id17">Reducing redundancy</a></h2>
<p>When multiple hashes are used with the current system
both the filename and filesize are repeated for every checksum type used as each
checksum is standalone. However this doesn't add any functionality and is
therefore useless, so the new format removes this redundancy.
This is a theoretical improvement at this moment as only one hash function is in
use, but expected to change soon (see <a class="footnote-reference" href="#multi-hash-thread" id="id4">[2]</a>).</p>
</div>
<div class="section" id="removal-of-checksum-collisions">
<h2><a class="toc-backref" href="#id18">Removal of checksum collisions</a></h2>
<p>The current system theoretically allows for a <tt class="docutils literal">DIST</tt> type file to be recorded
in multiple digest files with different sizes and/or checksums. In such a case
one version of a package would report a checksum violation while another one
would not. This could create confusion and uncertainity among users.
So far this case hasn't been observed, but it can't be ruled out with the
existing system.
As the new format lists each file exactly once this would be no longer possible.</p>
</div>
<div class="section" id="flexible-verification-system">
<h2><a class="toc-backref" href="#id19">Flexible verification system</a></h2>
<p>Right now portage verifies the checksum of every file listed in the Manifest
before using any file of the package and all <tt class="docutils literal">DIST</tt> files of an ebuild
before using that ebuild. This is unnecessary in many cases:</p>
<ul class="simple">
<li>During the &quot;depend&quot; phase (when the ebuild metadata is generated) only
files of type <tt class="docutils literal">EBUILD</tt> are used, so verifying the other types isn't
necessary. Theoretically it is possible for an ebuild to include other
files like those of type <tt class="docutils literal">AUX</tt> at this phase, but that would be a
major QA violation and should never occur, so it can be ignored here.
It is also not a security concern as the ebuild is verified before parsing
it, so each manipulation would show up.</li>
<li>Generally files of type <tt class="docutils literal">MISC</tt> don't need to be verified as they are
only used in very specific situations, aren't executed (just parsed at most)
and don't affect the package build process.</li>
<li>Files of type <tt class="docutils literal">DIST</tt> only need to be verified directly after fetching and
before unpacking them (which often will be one step), not every time their
associated ebuild is used.</li>
</ul>
</div>
</div>
<div class="section" id="backwards-compatibility">
<h1><a class="toc-backref" href="#id20">Backwards Compatibility</a></h1>
<p>Switching the Manifest system is a task that will need a long transition period
like most changes affecting both portage and the tree. In this case the
implementation will be rolled out in several phases:</p>
<ol class="arabic simple">
<li>Add support for verification of Manifest2 entries in portage</li>
<li>Enable generation of Manifest2 entries in addition to the current system</li>
<li>Ignore digests during <tt class="docutils literal">emerge <span class="pre">--sync</span></tt> to get the size-benefit clientside.
This step may be ommitted if the following steps are expected to follow soon.</li>
<li>Disable generation of entries for the current system</li>
<li>Remove all traces of the current system from the tree (serverside)</li>
</ol>
<p>Each step has its own issues. While 1) and 2) can be implemented without any
compability problems all later steps have a major impact:</p>
<ul class="simple">
<li>Step 3) can only be implemented when the whole tree is Manifest2 ready
(ideally speaking, practically the requirement will be more like 95% coverage
with the expectation that for the remaining 5% either bugs will be filed after
step 3) is completed or they'll be updated at step 5).</li>
<li>Steps 4) and 5) will render all portage versions without Manifest2 support
basically useless (users would have to regenerate the digest and Manifest
for each package before being able to merge it), so this requires a almost
100% coverage of the userbase with Manifest2 capabale portage versions
(with step 1) completely implemented).</li>
</ul>
<p>Another problem is that some steps affect different targets:</p>
<ul class="simple">
<li>Steps 1) and 3) target portage versions used by users</li>
<li>Steps 2) and 4) target portage versions used by devs</li>
<li>Step 5) targets the portage tree on the cvs server</li>
</ul>
<p>While it is relatively easy to get all devs to use a new portage version this is
practically impossible with users as some don't update their systems regulary.
While six months are probably sufficient to reach a 95% coverage one year is
estimated to reach an almost-complete coverage. All times are relative to the
stable-marking of a compatible portage version.</p>
<p>No timeframe for implementation is presented here as it is highly dependent
on the completion of each step.</p>
<p>In summary it can be said that while a full conversion will take over a year
to be completed due to compability issues mentioned above some benefits of the
system can selectively be used as soon as step 2) is completed.</p>
</div>
<div class="section" id="other-problems">
<h1><a class="toc-backref" href="#id21">Other problems</a></h1>
<div class="section" id="impacts-on-infrastructure">
<h2><a class="toc-backref" href="#id22">Impacts on infrastructure</a></h2>
<p>While one long term goal of this proposal is to reduce the size of the tree
and therefore make life for the Gentoo Infrastructure easier this will only
take effect once the implementation is rolled out completely. In the meantime
however it will increase the tree size due to keeping checksums in both formats.
It's not possible to give a usable estimate on the degree of the increase as
it depends on many variables such as the exact implementation timeframe,
propagation of Manifest2 capable portage versions among devs or the update
rate of the tree. It has been suggested that Manifest files that are not gpg
signed could be mass converted in one step, this could certainly help but only
to some degree (according to a recent research <a class="footnote-reference" href="#gpg-numbers" id="id5">[3]</a> about 40% of
all Manifests in the tree are signed, but this number hasn't been verified).</p>
</div>
</div>
<div class="section" id="reference-implementation">
<h1><a class="toc-backref" href="#id23">Reference Implementation</a></h1>
<p>A patch for a prototype implementation of Manifest2 verification and partial
generation has been posted at <a class="footnote-reference" href="#manifest2-patch" id="id6">[4]</a>, it will be reworked before
being considered for inclusion in portage. However it shows that adding support
for verification is quite simple, but generation is a bit tricky and will
therefore be implemented later.</p>
</div>
<div class="section" id="options">
<h1><a class="toc-backref" href="#id24">Options</a></h1>
<p>Some things have been considered for this GLEP but aren't part of the proposal
yet for various reasons:</p>
<ul class="simple">
<li>timestamp field: the author has considered adding a timestamp field for
each entry to list the time the entry was created. However so far no practical
use for such a feature has been found.</li>
<li>convert size field into checksum: Another idea was to treat the size field
like any other checksum. But so far no real benefit (other than a slightly
more modular implementation) for this has been seen while it has several
drawbacks: For once, unlike checksums, the size field is definitely required
for all <tt class="docutils literal">DIST</tt> files, also it would slightly increase the length of
each entry by adding a <tt class="docutils literal">SIZE</tt> keyword.</li>
<li>removal of the <tt class="docutils literal">MISC</tt> type: It has been suggested to completely drop
entries of type <tt class="docutils literal">MISC</tt>. This would result in a minor space reduction
(its rather unlikely to free any blocks) but completely remove the ability
to check these files for integrity. While they don't influence portage
or packages directly they can contain viable information for users, so
the author has the opinion that at least the option for integrity checks
should be kept.</li>
</ul>
</div>
<div class="section" id="credits">
<h1><a class="toc-backref" href="#id25">Credits</a></h1>
<p>Thanks to the following persons for their input on or related to this GLEP
(even though they might not have known it):
Ned Ludd (solar), Brian Harring (ferringb), Jason Stubbs (jstubbs),
Robin H. Johnson (robbat2), Aron Griffis (agriffis)</p>
<p>Also thanks to Nicholas Jones (carpaski) to make the current Manifest system
resistent enough to be able to handle this change without too many transition
problems.</p>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id26">References</a></h1>
<table class="docutils footnote" frame="void" id="reorg-thread" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://thread.gmane.org/gmane.linux.gentoo.devel/21920">http://thread.gmane.org/gmane.linux.gentoo.devel/21920</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="multi-hash-thread" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>)</em> <a class="reference external" href="http://thread.gmane.org/gmane.linux.gentoo.devel/33434">http://thread.gmane.org/gmane.linux.gentoo.devel/33434</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="gpg-numbers" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[3]</a></td><td>gentoo-core mailing list, topic &quot;Gentoo key signing practices
and official Gentoo keyring&quot;, Message-ID &lt;<a class="reference external" href="mailto:20051117075838.GB15734&#64;curie-int.vc.shawcable.net">20051117075838.GB15734&#64;curie-int.vc.shawcable.net</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="manifest2-patch" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id6">[4]</a></td><td><a class="reference external" href="http://thread.gmane.org/gmane.linux.gentoo.portage.devel/1374">http://thread.gmane.org/gmane.linux.gentoo.portage.devel/1374</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="manifest2-example" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[5]</td><td><a class="reference external" href="http://www.gentoo.org/proj/en/glep/glep-0044-extras/manifest2-example">http://www.gentoo.org/proj/en/glep/glep-0044-extras/manifest2-example</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id8">[6]</a></td><td><a class="reference external" href="glep-0044-extras/manifest2-example.txt">glep-0044-extras/manifest2-example.txt</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id27">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
</div>

</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="glep-0044.txt">View document source</a>.
Generated on: 2010-04-07 22:08 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>