| 1 |
GLEP: 44
|
| 2 |
Title: Manifest2 format
|
| 3 |
Version: $Revision: 1.6 $
|
| 4 |
Last-Modified: $Date: 2006/09/04 03:06:32 $
|
| 5 |
Author: Marius Mauch <genone@gentoo.org>,
|
| 6 |
Status: Accepted
|
| 7 |
Type: Standards Track
|
| 8 |
Content-Type: text/x-rst
|
| 9 |
Created: 04-Dec-2005
|
| 10 |
Post-History: 06-Dec-2005, 23-Jan-2006, 3-Sep-2006
|
| 11 |
|
| 12 |
|
| 13 |
Abstract
|
| 14 |
========
|
| 15 |
|
| 16 |
This GLEP proposes a new format for the Portage Manifest and digest file system
|
| 17 |
by unifying both filetypes into one to improve functional and non-functional
|
| 18 |
aspects of the Portage Tree.
|
| 19 |
|
| 20 |
|
| 21 |
Motivation
|
| 22 |
==========
|
| 23 |
|
| 24 |
Please see [#reorg-thread]_ for a general overview.
|
| 25 |
The main long term goals of this proposal are to:
|
| 26 |
|
| 27 |
- Remove the tiny digest files from the tree. They are a major annoyance as on a
|
| 28 |
typical configuration they waste a lot of disk space and the simple transmission
|
| 29 |
of the names for all digest files during a ``emerge --sync`` needs a substantial
|
| 30 |
amount of bandwidth.
|
| 31 |
- Reduce redundancy when multiple hash functions are used
|
| 32 |
- Remove potential for checksum collisions if a file is recorded in more than one
|
| 33 |
digest file
|
| 34 |
- Difference between filetypes for a more flexible verification system
|
| 35 |
|
| 36 |
|
| 37 |
Specification
|
| 38 |
=============
|
| 39 |
|
| 40 |
The new Manifest format would change the existing format in the following ways:
|
| 41 |
|
| 42 |
- Addition of a filetype specifier, currently planned are
|
| 43 |
|
| 44 |
* ``AUX`` for files directly used by ebuilds (e.g. patches or initscripts),
|
| 45 |
located in the ``files/`` subdirectory
|
| 46 |
|
| 47 |
* ``EBUILD`` for all ebuilds
|
| 48 |
|
| 49 |
* ``MISC`` for files not directly used by ebuilds like ``ChangeLog`` or
|
| 50 |
``metadata.xml`` files
|
| 51 |
|
| 52 |
* ``DIST`` for release tarballs recorded in the ``SRC_URI`` variable of an ebuild,
|
| 53 |
these were previously recorded in the digest files
|
| 54 |
|
| 55 |
Future portage improvements might extend this list (for example with types
|
| 56 |
relevant for eclasses or profiles)
|
| 57 |
|
| 58 |
- Only have one line per file listing all information instead of one line per
|
| 59 |
file and checksum type
|
| 60 |
|
| 61 |
- Remove the separated digest-* files in the ``files/`` subdirectory
|
| 62 |
|
| 63 |
Each line in the new format has the following format:
|
| 64 |
|
| 65 |
::
|
| 66 |
|
| 67 |
<filetype> <filename> <filesize> <chksumtype1> <chksum1> ... <chksumtypen> <chksumn>
|
| 68 |
|
| 69 |
|
| 70 |
However theses entries will be stored in the existing Manifest files.
|
| 71 |
|
| 72 |
An `actual example`__ for a (pure) Manifest2 file..
|
| 73 |
|
| 74 |
.. __: glep-0044-extras/manifest2-example.txt
|
| 75 |
|
| 76 |
|
| 77 |
Compability Entries
|
| 78 |
-------------------
|
| 79 |
|
| 80 |
To maintain compability with existing portage versions a transition period after
|
| 81 |
is the introduction of the Manifest2 format is required during which portage
|
| 82 |
will not only have to be capable of using existing Manifest and digest files but
|
| 83 |
also generate them in addition to the new entries.
|
| 84 |
Fortunately this can be accomplished by simply mixing old and new style entries
|
| 85 |
in one file for the Manifest files, existing portage versions will simply ignore
|
| 86 |
the new style entries. For the digest files there are no new entries to care
|
| 87 |
about.
|
| 88 |
|
| 89 |
Scope
|
| 90 |
-----
|
| 91 |
|
| 92 |
It is important to note that this proposal only deals with a change of the
|
| 93 |
format of the digest and Manifest system.
|
| 94 |
|
| 95 |
It does not expand the scope of it to cover eclasses, profiles or anything
|
| 96 |
else not already covered by the Manifest system, it also doesn't affect
|
| 97 |
the Manifest signing efforts in any way (though the implementations of both
|
| 98 |
might be coupled).
|
| 99 |
|
| 100 |
Also while multiple hash functions will become standard with the proposed
|
| 101 |
implementation they are not a specific feature of this format [#multi-hash-thread]_.
|
| 102 |
|
| 103 |
Number of hashes
|
| 104 |
----------------
|
| 105 |
|
| 106 |
While using multiple hashes for each file is a major feature of this proposal
|
| 107 |
we have to make sure that the number of hashes listed is limited to avoid
|
| 108 |
an explosion of the Manifest size that would revert the main benefit of this proposal
|
| 109 |
(reduzing tree size). Therefore the number of hashes that will be generated
|
| 110 |
will be limited to three different hash functions. For compability though we
|
| 111 |
have to rely on at least one hash function to always be present, this proposal
|
| 112 |
suggest to use SHA1 for this purpose (as it is supposed to be more secure than MD5
|
| 113 |
and currently only SHA1 and MD5 are directly available in python, also MD5 doesn't
|
| 114 |
have any benefit in terms of compability).
|
| 115 |
|
| 116 |
Rationale
|
| 117 |
=========
|
| 118 |
|
| 119 |
The main goals of the proposal have been listed in the `Motivation`_, here now
|
| 120 |
the explanation why they are improvements and how the proposed format will
|
| 121 |
accomplish them.
|
| 122 |
|
| 123 |
Removal of digest files
|
| 124 |
-----------------------
|
| 125 |
|
| 126 |
Normal users that don't use a "tuned" filesystem for the portage tree are
|
| 127 |
wasting several dozen to a few hundred megabytes of disk space with the current
|
| 128 |
system, largely caused by the digest files.
|
| 129 |
This is due to the filesystem overhead present in most filesystem that
|
| 130 |
have a standard blocksize of four kilobytes while most digest files are under
|
| 131 |
one kilobyte in size, so this results in approximately a waste of three kilobytes
|
| 132 |
per digest file (likely even more). At the time of this writing the tree contains
|
| 133 |
roughly 22.000 digest files, so the overall waste caused by digest files is
|
| 134 |
estimated at about 70-100 megabytes.
|
| 135 |
Furthermore it is assumed that this will also reduce the disk space wasted by
|
| 136 |
the Manifest files as they now contain more content, but this hasn't been
|
| 137 |
verified yet.
|
| 138 |
|
| 139 |
By unifying the digest files with the Manifest these tiny files are eliminated
|
| 140 |
(in the long run), reducing the apparent tree size by about 20%, benefitting
|
| 141 |
both users and the Gentoo infrastructure.
|
| 142 |
|
| 143 |
Reducing redundancy
|
| 144 |
-------------------
|
| 145 |
|
| 146 |
When multiple hashes are used with the current system
|
| 147 |
both the filename and filesize are repeated for every checksum type used as each
|
| 148 |
checksum is standalone. However this doesn't add any functionality and is
|
| 149 |
therefore useless, so the new format removes this redundancy.
|
| 150 |
This is a theoretical improvement at this moment as only one hash function is in
|
| 151 |
use, but expected to change soon (see [#multi-hash-thread]_).
|
| 152 |
|
| 153 |
Removal of checksum collisions
|
| 154 |
------------------------------
|
| 155 |
|
| 156 |
The current system theoretically allows for a ``DIST`` type file to be recorded
|
| 157 |
in multiple digest files with different sizes and/or checksums. In such a case
|
| 158 |
one version of a package would report a checksum violation while another one
|
| 159 |
would not. This could create confusion and uncertainity among users.
|
| 160 |
So far this case hasn't been observed, but it can't be ruled out with the
|
| 161 |
existing system.
|
| 162 |
As the new format lists each file exactly once this would be no longer possible.
|
| 163 |
|
| 164 |
Flexible verification system
|
| 165 |
----------------------------
|
| 166 |
|
| 167 |
Right now portage verifies the checksum of every file listed in the Manifest
|
| 168 |
before using any file of the package and all ``DIST`` files of an ebuild
|
| 169 |
before using that ebuild. This is unnecessary in many cases:
|
| 170 |
|
| 171 |
- During the "depend" phase (when the ebuild metadata is generated) only
|
| 172 |
files of type ``EBUILD`` are used, so verifying the other types isn't
|
| 173 |
necessary. Theoretically it is possible for an ebuild to include other
|
| 174 |
files like those of type ``AUX`` at this phase, but that would be a
|
| 175 |
major QA violation and should never occur, so it can be ignored here.
|
| 176 |
It is also not a security concern as the ebuild is verified before parsing
|
| 177 |
it, so each manipulation would show up.
|
| 178 |
|
| 179 |
- Generally files of type ``MISC`` don't need to be verified as they are
|
| 180 |
only used in very specific situations, aren't executed (just parsed at most)
|
| 181 |
and don't affect the package build process.
|
| 182 |
|
| 183 |
- Files of type ``DIST`` only need to be verified directly after fetching and
|
| 184 |
before unpacking them (which often will be one step), not every time their
|
| 185 |
associated ebuild is used.
|
| 186 |
|
| 187 |
|
| 188 |
Backwards Compatibility
|
| 189 |
=======================
|
| 190 |
|
| 191 |
Switching the Manifest system is a task that will need a long transition period
|
| 192 |
like most changes affecting both portage and the tree. In this case the
|
| 193 |
implementation will be rolled out in several phases:
|
| 194 |
|
| 195 |
1. Add support for verification of Manifest2 entries in portage
|
| 196 |
|
| 197 |
2. Enable generation of Manifest2 entries in addition to the current system
|
| 198 |
|
| 199 |
3. Ignore digests during ``emerge --sync`` to get the size-benefit clientside.
|
| 200 |
This step may be ommitted if the following steps are expected to follow soon.
|
| 201 |
|
| 202 |
4. Disable generation of entries for the current system
|
| 203 |
|
| 204 |
5. Remove all traces of the current system from the tree (serverside)
|
| 205 |
|
| 206 |
Each step has its own issues. While 1) and 2) can be implemented without any
|
| 207 |
compability problems all later steps have a major impact:
|
| 208 |
|
| 209 |
- Step 3) can only be implemented when the whole tree is Manifest2 ready
|
| 210 |
(ideally speaking, practically the requirement will be more like 95% coverage
|
| 211 |
with the expectation that for the remaining 5% either bugs will be filed after
|
| 212 |
step 3) is completed or they'll be updated at step 5).
|
| 213 |
|
| 214 |
- Steps 4) and 5) will render all portage versions without Manifest2 support
|
| 215 |
basically useless (users would have to regenerate the digest and Manifest
|
| 216 |
for each package before being able to merge it), so this requires a almost
|
| 217 |
100% coverage of the userbase with Manifest2 capabale portage versions
|
| 218 |
(with step 1) completely implemented).
|
| 219 |
|
| 220 |
Another problem is that some steps affect different targets:
|
| 221 |
|
| 222 |
- Steps 1) and 3) target portage versions used by users
|
| 223 |
|
| 224 |
- Steps 2) and 4) target portage versions used by devs
|
| 225 |
|
| 226 |
- Step 5) targets the portage tree on the cvs server
|
| 227 |
|
| 228 |
While it is relatively easy to get all devs to use a new portage version this is
|
| 229 |
practically impossible with users as some don't update their systems regulary.
|
| 230 |
While six months are probably sufficient to reach a 95% coverage one year is
|
| 231 |
estimated to reach an almost-complete coverage. All times are relative to the
|
| 232 |
stable-marking of a compatible portage version.
|
| 233 |
|
| 234 |
No timeframe for implementation is presented here as it is highly dependent
|
| 235 |
on the completion of each step.
|
| 236 |
|
| 237 |
In summary it can be said that while a full conversion will take over a year
|
| 238 |
to be completed due to compability issues mentioned above some benefits of the
|
| 239 |
system can selectively be used as soon as step 2) is completed.
|
| 240 |
|
| 241 |
|
| 242 |
Other problems
|
| 243 |
==============
|
| 244 |
|
| 245 |
Impacts on infrastructure
|
| 246 |
-------------------------
|
| 247 |
|
| 248 |
While one long term goal of this proposal is to reduce the size of the tree
|
| 249 |
and therefore make life for the Gentoo Infrastructure easier this will only
|
| 250 |
take effect once the implementation is rolled out completely. In the meantime
|
| 251 |
however it will increase the tree size due to keeping checksums in both formats.
|
| 252 |
It's not possible to give a usable estimate on the degree of the increase as
|
| 253 |
it depends on many variables such as the exact implementation timeframe,
|
| 254 |
propagation of Manifest2 capable portage versions among devs or the update
|
| 255 |
rate of the tree. It has been suggested that Manifest files that are not gpg
|
| 256 |
signed could be mass converted in one step, this could certainly help but only
|
| 257 |
to some degree (according to a recent research [#gpg-numbers]_ about 40% of
|
| 258 |
all Manifests in the tree are signed, but this number hasn't been verified).
|
| 259 |
|
| 260 |
|
| 261 |
Reference Implementation
|
| 262 |
========================
|
| 263 |
|
| 264 |
A patch for a prototype implementation of Manifest2 verification and partial
|
| 265 |
generation has been posted at [#manifest2-patch]_, it will be reworked before
|
| 266 |
being considered for inclusion in portage. However it shows that adding support
|
| 267 |
for verification is quite simple, but generation is a bit tricky and will
|
| 268 |
therefore be implemented later.
|
| 269 |
|
| 270 |
|
| 271 |
Options
|
| 272 |
=======
|
| 273 |
|
| 274 |
Some things have been considered for this GLEP but aren't part of the proposal
|
| 275 |
yet for various reasons:
|
| 276 |
|
| 277 |
- timestamp field: the author has considered adding a timestamp field for
|
| 278 |
each entry to list the time the entry was created. However so far no practical
|
| 279 |
use for such a feature has been found.
|
| 280 |
|
| 281 |
- convert size field into checksum: Another idea was to treat the size field
|
| 282 |
like any other checksum. But so far no real benefit (other than a slightly
|
| 283 |
more modular implementation) for this has been seen while it has several
|
| 284 |
drawbacks: For once, unlike checksums, the size field is definitely required
|
| 285 |
for all ``DIST`` files, also it would slightly increase the length of
|
| 286 |
each entry by adding a ``SIZE`` keyword.
|
| 287 |
|
| 288 |
- removal of the ``MISC`` type: It has been suggested to completely drop
|
| 289 |
entries of type ``MISC``. This would result in a minor space reduction
|
| 290 |
(its rather unlikely to free any blocks) but completely remove the ability
|
| 291 |
to check these files for integrity. While they don't influence portage
|
| 292 |
or packages directly they can contain viable information for users, so
|
| 293 |
the author has the opinion that at least the option for integrity checks
|
| 294 |
should be kept.
|
| 295 |
|
| 296 |
Credits
|
| 297 |
=======
|
| 298 |
|
| 299 |
Thanks to the following persons for their input on or related to this GLEP
|
| 300 |
(even though they might not have known it):
|
| 301 |
Ned Ludd (solar), Brian Harring (ferringb), Jason Stubbs (jstubbs),
|
| 302 |
Robin H. Johnson (robbat2), Aron Griffis (agriffis)
|
| 303 |
|
| 304 |
Also thanks to Nicholas Jones (carpaski) to make the current Manifest system
|
| 305 |
resistent enough to be able to handle this change without too many transition
|
| 306 |
problems.
|
| 307 |
|
| 308 |
References
|
| 309 |
==========
|
| 310 |
|
| 311 |
.. [#reorg-thread] http://thread.gmane.org/gmane.linux.gentoo.devel/21920
|
| 312 |
|
| 313 |
.. [#multi-hash-thread] http://thread.gmane.org/gmane.linux.gentoo.devel/33434
|
| 314 |
|
| 315 |
.. [#gpg-numbers] gentoo-core mailing list, topic "Gentoo key signing practices
|
| 316 |
and official Gentoo keyring", Message-ID <20051117075838.GB15734@curie-int.vc.shawcable.net>
|
| 317 |
|
| 318 |
.. [#manifest2-patch] http://thread.gmane.org/gmane.linux.gentoo.portage.devel/1374
|
| 319 |
|
| 320 |
.. [#manifest2-example] http://www.gentoo.org/proj/en/glep/glep-0044-extras/manifest2-example
|
| 321 |
|
| 322 |
Copyright
|
| 323 |
=========
|
| 324 |
|
| 325 |
This document has been placed in the public domain.
|
| 326 |
|
Parent Directory
| 
Revision Log