gitian-builder/README.md

# Gitian

Read about the project goals at the "project home page":https://gitian.org/ .

This package can do a deterministic build of a package inside a VM.

## Deterministic build inside a VM

This performs a build inside a VM, with deterministic inputs and outputs.  If the build script takes care of all sources of non-determinism (mostly caused by timestamps), the result will always be the same.  This allows multiple independent verifiers to sign a binary with the assurance that it really came from the source they reviewed.

## Synopsis:

Install prereqs:

    sudo apt-get install python-vm-builder qemu-kvm apt-cacher
    sudo service apt-cacher start

Create the base VM for use in further builds (requires sudo, please review the script):

    bin/make-base-vm

Copy any additional build inputs into a directory named _inputs_.

Then execute the build using a YAML description file (can be run as non-root):

    bin/gbuild <package>.yml

or if you need to specify a commit for one of the git remotes:

    bin/gbuild --commit <dir>=<hash> <package>.yml

The resulting report will appear in result/\<package\>-res.yml

To sign the result, perform:

    bin/gsign --signer <signer> --release <release-name> <package>.yml

Where <signer> is your signing PGP key ID and <release-name> is the name for the current release.  This will put the result and signature in the sigs/<package>/<release-name>.  The sigs/<package> directory can be managed through git to coordinate multiple signers.

After you've merged everybody's signatures, verify them:

    bin/gverify --release <release-name> <package>.yml

## Poking around

* Log files are captured to the _var_ directory
* You can run the utilities in libexec by running `PATH="libexec:$PATH"`
* To start the target VM run `start-target 32 lucid-i386` or `start-target 64 lucid-amd64`
* To ssh into the target run `on-target` or `on-target -u root`
* On the target, the _build_ directory contains the code as it is compiled and _install_ contains intermediate libraries
* By convention, the script in \<package\>.yml starts with any environment setup you would need to manually compile things on the target

TODO:
- disable sudo in target, just in case of a hypervisor exploit
- tar and other archive timestamp setter
initial 2011-01-30 21:12:02 +00:00			`# Gitian`

			`Read about the project goals at the "project home page":https://gitian.org/ .`

			`This package can do a deterministic build of a package inside a VM.`

			`## Deterministic build inside a VM`

			`This performs a build inside a VM, with deterministic inputs and outputs. If the build script takes care of all sources of non-determinism (mostly caused by timestamps), the result will always be the same. This allows multiple independent verifiers to sign a binary with the assurance that it really came from the source they reviewed.`

use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`## Synopsis:`
initial 2011-01-30 21:12:02 +00:00
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`Install prereqs:`
initial 2011-01-30 21:12:02 +00:00
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`sudo apt-get install python-vm-builder qemu-kvm apt-cacher`
			`sudo service apt-cacher start`
initial 2011-01-30 21:12:02 +00:00
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`Create the base VM for use in further builds (requires sudo, please review the script):`
initial 2011-01-30 21:12:02 +00:00
			`bin/make-base-vm`

use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`Copy any additional build inputs into a directory named _inputs_.`
initial 2011-01-30 21:12:02 +00:00
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`Then execute the build using a YAML description file (can be run as non-root):`
initial 2011-01-30 21:12:02 +00:00
gverify 2011-03-27 19:24:22 +00:00			`bin/gbuild <package>.yml`
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00
security mirror, command line commit specification 2011-02-01 17:48:33 +00:00			`or if you need to specify a commit for one of the git remotes:`

gverify 2011-03-27 19:24:22 +00:00			`bin/gbuild --commit <dir>=<hash> <package>.yml`
security mirror, command line commit specification 2011-02-01 17:48:33 +00:00
use apt cacher, minor cleanup 2011-01-30 23:31:33 +00:00			`The resulting report will appear in result/\<package\>-res.yml`
multi-architecture builds 2011-02-01 07:50:59 +00:00
gverify 2011-03-27 19:24:22 +00:00			`To sign the result, perform:`

			`bin/gsign --signer <signer> --release <release-name> <package>.yml`

			`Where <signer> is your signing PGP key ID and <release-name> is the name for the current release. This will put the result and signature in the sigs/<package>/<release-name>. The sigs/<package> directory can be managed through git to coordinate multiple signers.`

			`After you've merged everybody's signatures, verify them:`

			`bin/gverify --release <release-name> <package>.yml`

multi-architecture builds 2011-02-01 07:50:59 +00:00			`## Poking around`

			`* Log files are captured to the _var_ directory`
			* You can run the utilities in libexec by running `PATH="libexec:$PATH"`
revert memory size, update apt-get to grab from new IP address 2011-03-22 16:02:53 +00:00			* To start the target VM run `start-target 32 lucid-i386` or `start-target 64 lucid-amd64`
multi-architecture builds 2011-02-01 07:50:59 +00:00			* To ssh into the target run `on-target` or `on-target -u root`
			`* On the target, the _build_ directory contains the code as it is compiled and _install_ contains intermediate libraries`
gverify 2011-03-27 19:24:22 +00:00			`* By convention, the script in \<package\>.yml starts with any environment setup you would need to manually compile things on the target`
multi-architecture builds 2011-02-01 07:50:59 +00:00
			`TODO:`
			`- disable sudo in target, just in case of a hypervisor exploit`
			`- tar and other archive timestamp setter`