diff --git a/README.md b/README.md index 2ebb1cb..cadf744 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Gitian -Read about the project goals at the "project home page":https://gitian.org/ . +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. @@ -10,29 +10,30 @@ This performs a build inside a VM, with deterministic inputs and outputs. If th ## Prerequisites: -Gentoo: +### Gentoo: 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 -Ubuntu: +### Ubuntu: sudo apt-get install git apache2 apt-cacher-ng python-vm-builder ruby sudo apt-get install qemu-kvm # for KVM mode sudo apt-get install debootstrap lxc # for LXC mode -OSX with MacPorts: +### OSX with MacPorts: sudo port install ruby coreutils export PATH=$PATH:/opt/local/libexec/gnubin # Needed for sha256sum -### VirtualBox +#### VirtualBox: -Install virtualbox from virtualbox.org, and make sure VBoxManage is in your $PATH. +Install virtualbox from http://www.virtualbox.org, and make sure `VBoxManage` is in your `$PATH`. -## Create the base VM for use in further builds (requires sudo, please review the script): +## Create the base VM for use in further builds +**NOTE:** requires `sudo`, please review the script ### KVM @@ -44,48 +45,57 @@ Install virtualbox from virtualbox.org, and make sure VBoxManage is in your $PAT bin/make-base-vm --lxc bin/make-base-vm --lxc --arch i386 -Set the USE_LXC environment variable to use LXC instead of KVM: +Set the `USE_LXC` environment variable to use `LXC` instead of `KVM`: + export USE_LXC=1 ### VirtualBox -Command-line VBoxManage must be in your PATH +Command-line `VBoxManage` must be in your `$PATH`. + +#### Setup: -Setup: +`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: -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--` -- 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.: -1. Are named "Gitian--" -- 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: +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/id_dsa.pub + +Then log into the vm and copy the `ssh` keys to root's `authorized_keys` file. + ssh -p 2223 ubuntu@localhost - On VM: sudo bash - On VM: mkdir -p .ssh && chmod 700 .ssh && cat ~ubuntu/.ssh/authorized_keys >> .ssh/authorized_keys + # 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`: -Set the USE_VBOX environment variable to use LXC instead of KVM: export USE_VBOX=1 ## Sanity-testing If you have everything set-up properly, you should be able to: -PATH=$PATH:$(pwd)/libexec -make-clean-vm --suite lucid --arch i386 -start-target 32 lucid-i386 -on-target ls -la -stop-target + PATH=$PATH:$(pwd)/libexec + make-clean-vm --suite lucid --arch i386 + start-target 32 lucid-i386 + on-target ls -la + stop-target ## Building 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): +Then execute the build using a `YAML` description file (can be run as non-root): export USE_LXC=1 # LXC only bin/gbuild .yml @@ -94,13 +104,13 @@ or if you need to specify a commit for one of the git remotes: bin/gbuild --commit = .yml -The resulting report will appear in result/\-res.yml +The resulting report will appear in `result/-res.yml` To sign the result, perform: bin/gsign --signer --release .yml -Where is your signing PGP key ID and is the name for the current release. This will put the result and signature in the sigs//. The sigs/ directory can be managed through git to coordinate multiple signers. +Where `` is your signing PGP key ID and `` is the name for the current release. This will put the result and signature in the `sigs//`. The `sigs/` directory can be managed through git to coordinate multiple signers. After you've merged everybody's signatures, verify them: @@ -114,7 +124,7 @@ After you've merged everybody's signatures, verify them: * 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 \.yml starts with any environment setup you would need to manually compile things on the target +* By convention, the script in `.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 @@ -130,7 +140,7 @@ Recent distributions allow lxc-start to be run by non-priviledged users, so you 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 10.0.2.2: +The machine configuration requires access to br0 and assumes that the host address is `10.0.2.2`: sudo brctl addbr br0 sudo ifconfig br0 10.0.2.2/24 up