You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tom Robinson a6fdc28839 Add VirtualBox support to make-base-vm via Vagrant 9 years ago
bin Add VirtualBox support to make-base-vm via Vagrant 9 years ago
libexec make passing env vars work across guest OS suites 9 years ago
share Fix gitian_updater checksum matching. 9 years ago
LICENSE qemu-utils are required 9 years ago
Vagrantfile Add VirtualBox support to make-base-vm via Vagrant 9 years ago


Read about the project goals at the project home page.

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.



layman -a luke-jr  # needed for vmbuilder
sudo emerge dev-vcs/git net-misc/apt-cacher-ng app-emulation/vmbuilder dev-lang/ruby
sudo emerge app-emulation/qemu
export KVM=qemu-system-x86_64


sudo apt-get install git apache2 apt-cacher-ng python-vm-builder ruby qemu-utils
sudo apt-get install qemu-kvm         # for KVM mode
sudo apt-get install debootstrap lxc  # for LXC mode

OSX with MacPorts:

sudo port install ruby coreutils
export PATH=$PATH:/opt/local/libexec/gnubin  # Needed for sha256sum


Install virtualbox from, and make sure VBoxManage is in your $PATH.

Create the base VM for use in further builds

NOTE: requires sudo, please review the script


bin/make-base-vm --arch i386


bin/make-base-vm --lxc
bin/make-base-vm --lxc --arch i386

Set the USE_LXC environment variable to use LXC instead of KVM:

export USE_LXC=1


Command-line VBoxManage must be in your $PATH.


make-base-vm cannot yet make VirtualBox virtual machines ( patches welcome, it should be possible to use VBoxManage, boot-from-network Linux images and PXE booting to do it). So you must either get or manually create VirtualBox machines that:

  1. Are named Gitian-<suite>-<arch> -- e.g. Gitian-lucid-i386 for a 32-bit, Ubuntu 10 machine.
  2. Have a booted-up snapshot named Gitian-Clean . The build script resets the VM to that snapshot to get reproducible builds.
  3. Has the VM's NAT networking setup to forward port localhost:2223 on the host machine to port 22 of the VM; e.g.:
    VBoxManage modifyvm Gitian-lucid-i386 --natpf1 "guestssh,tcp,,2223,,22"

The final setup needed is to create an ssh key that will be used to login to the virtual machine:

ssh-keygen -t dsa -f var/id_dsa -N ""
ssh -p 2223 ubuntu@localhost 'mkdir -p .ssh && chmod 700 .ssh && cat >> .ssh/authorized_keys' < var/

Then log into the vm and copy the ssh keys to root's authorized_keys file.

ssh -p 2223 ubuntu@localhost
# Now in the vm
sudo bash
mkdir -p .ssh && chmod 700 .ssh && cat ~ubuntu/.ssh/authorized_keys >> .ssh/authorized_keys

Set the USE_VBOX environment variable to use VBOX instead of KVM:

export USE_VBOX=1


If you have everything set-up properly, you should be able to:

make-clean-vm --suite lucid --arch i386

# For LXC:
LXC_ARCH=i386 LXC_SUITE=lucid on-target ls -la

# For KVM:
start-target 32 lucid-i386
on-target ls -la


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

export USE_LXC=1 # LXC only
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


  • disable sudo in target, just in case of a hypervisor exploit
  • tar and other archive timestamp setter

LXC tips

bin/gbuild runs lxc-start, which may require root. If you are in the admin group, you can add the following sudoers line to prevent asking for the password every time:

%admin ALL=NOPASSWD: /usr/bin/lxc-start

Recent distributions allow lxc-start to be run by non-priviledged users, so you might be able to rip-out the sudo calls in libexec/*.

If you have a runaway lxc-start command, just use kill -9 on it.

The machine configuration requires access to br0 and assumes that the host address is

sudo brctl addbr br0
sudo ifconfig br0 up


Not very extensive, currently.

python -m unittest discover test