1Gitian building 2================ 3 4*Setup instructions for a Gitian build of Bitcoin Core using a Debian VM or physical system.* 5 6Gitian is the deterministic build process that is used to build the Bitcoin 7Core executables. It provides a way to be reasonably sure that the 8executables are really built from the source on GitHub. It also makes sure that 9the same, tested dependencies are used and statically built into the executable. 10 11Multiple developers build the source code by following a specific descriptor 12("recipe"), cryptographically sign the result, and upload the resulting signature. 13These results are compared and only if they match, the build is accepted and uploaded 14to bitcoin.org. 15 16More independent Gitian builders are needed, which is why this guide exists. 17It is preferred you follow these steps yourself instead of using someone else's 18VM image to avoid 'contaminating' the build. 19 20Table of Contents 21------------------ 22 23- [Create a new VirtualBox VM](#create-a-new-virtualbox-vm) 24- [Connecting to the VM](#connecting-to-the-vm) 25- [Setting up Debian for Gitian building](#setting-up-debian-for-gitian-building) 26- [Installing Gitian](#installing-gitian) 27- [Setting up the Gitian image](#setting-up-the-gitian-image) 28- [Getting and building the inputs](#getting-and-building-the-inputs) 29- [Building Bitcoin Core](#building-bitcoin-core) 30- [Building an alternative repository](#building-an-alternative-repository) 31- [Signing externally](#signing-externally) 32- [Uploading signatures](#uploading-signatures) 33 34Preparing the Gitian builder host 35--------------------------------- 36 37The first step is to prepare the host environment that will be used to perform the Gitian builds. 38This guide explains how to set up the environment, and how to start the builds. 39 40Debian Linux was chosen as the host distribution because it has a lightweight install (in contrast to Ubuntu) and is readily available. 41Any kind of virtualization can be used, for example: 42- [VirtualBox](https://www.virtualbox.org/) (covered by this guide) 43- [KVM](http://www.linux-kvm.org/page/Main_Page) 44- [LXC](https://linuxcontainers.org/), see also [Gitian host docker container](https://github.com/gdm85/tenku/tree/master/docker/gitian-bitcoin-host/README.md). 45 46You can also install Gitian on actual hardware instead of using virtualization. 47 48Create a new VirtualBox VM 49--------------------------- 50In the VirtualBox GUI click "New" and choose the following parameters in the wizard: 51 52![](gitian-building/create_new_vm.png) 53 54- Type: Linux, Debian (64-bit) 55 56![](gitian-building/create_vm_memsize.png) 57 58- Memory Size: at least 3000MB, anything less and the build might not complete. 59 60![](gitian-building/create_vm_hard_disk.png) 61 62- Hard Disk: Create a virtual hard disk now 63 64![](gitian-building/create_vm_hard_disk_file_type.png) 65 66- Hard Disk file type: Use the default, VDI (VirtualBox Disk Image) 67 68![](gitian-building/create_vm_storage_physical_hard_disk.png) 69 70- Storage on physical hard disk: Dynamically Allocated 71 72![](gitian-building/create_vm_file_location_size.png) 73 74- File location and size: at least 40GB; as low as 20GB *may* be possible, but better to err on the safe side 75- Click `Create` 76 77After creating the VM, we need to configure it. 78 79- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attached to `NAT`. 80 81![](gitian-building/network_settings.png) 82 83- Click `Advanced`, then `Port Forwarding`. We want to set up a port through which we can reach the VM to get files in and out. 84- Create a new rule by clicking the plus icon. 85 86![](gitian-building/port_forwarding_rules.png) 87 88- Set up the new rule the following way: 89 - Name: `SSH` 90 - Protocol: `TCP` 91 - Leave Host IP empty 92 - Host Port: `22222` 93 - Leave Guest IP empty 94 - Guest Port: `22` 95 96- Click `Ok` twice to save. 97 98Get the [Debian 8.x net installer](http://cdimage.debian.org/debian-cd/8.5.0/amd64/iso-cd/debian-8.5.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). 99This DVD image can be validated using a SHA256 hashing tool, for example on 100Unixy OSes by entering the following in a terminal: 101 102 echo "ad4e8c27c561ad8248d5ebc1d36eb172f884057bfeb2c22ead823f59fa8c3dff debian-8.5.0-amd64-netinst.iso" | sha256sum -c 103 # (must return OK) 104 105Then start the VM. On the first launch you will be asked for a CD or DVD image. Choose the downloaded iso. 106 107![](gitian-building/select_startup_disk.png) 108 109Installing Debian 110------------------ 111 112This section will explain how to install Debian on the newly created VM. 113 114- Choose the non-graphical installer. We do not need the graphical environment; it will only increase installation time and disk usage. 115 116![](gitian-building/debian_install_1_boot_menu.png) 117 118**Note**: Navigating in the Debian installer: 119To keep a setting at the default and proceed, just press `Enter`. 120To select a different button, press `Tab`. 121 122- Choose locale and keyboard settings (doesn't matter, you can just go with the defaults or select your own information) 123 124![](gitian-building/debian_install_2_select_a_language.png) 125![](gitian-building/debian_install_3_select_location.png) 126![](gitian-building/debian_install_4_configure_keyboard.png) 127 128- The VM will detect network settings using DHCP, this should all proceed automatically 129- Configure the network: 130 - Hostname `debian`. 131 - Leave domain name empty. 132 133![](gitian-building/debian_install_5_configure_the_network.png) 134 135- Choose a root password and enter it twice (remember it for later) 136 137![](gitian-building/debian_install_6a_set_up_root_password.png) 138 139- Name the new user `debian` (the full name doesn't matter, you can leave it empty) 140- Set the account username as `debian` 141 142![](gitian-building/debian_install_7_set_up_user_fullname.png) 143![](gitian-building/debian_install_8_set_up_username.png) 144 145- Choose a user password and enter it twice (remember it for later) 146 147![](gitian-building/debian_install_9_user_password.png) 148 149- The installer will set up the clock using a time server; this process should be automatic 150- Set up the clock: choose a time zone (depends on the locale settings that you picked earlier; specifics don't matter) 151 152![](gitian-building/debian_install_10_configure_clock.png) 153 154- Disk setup 155 - Partitioning method: Guided - Use the entire disk 156 157![](gitian-building/debian_install_11_partition_disks.png) 158 159 - Select disk to partition: SCSI1 (0,0,0) 160 161![](gitian-building/debian_install_12_choose_disk.png) 162 163 - Partition Disks -> *All files in one partition* 164 165![](gitian-building/all_files_in_one_partition.png) 166 167 - Finish partitioning and write changes to disk -> *Yes* (`Tab`, `Enter` to select the `Yes` button) 168 169![](gitian-building/debian_install_14_finish.png) 170![](gitian-building/debian_install_15_write_changes.png) 171 172- The base system will be installed, this will take a minute or so 173- Choose a mirror (any will do) 174 175![](gitian-building/debian_install_16_choose_a_mirror.png) 176 177- Enter proxy information (unless you are on an intranet, leave this empty) 178 179![](gitian-building/debian_install_18_proxy_settings.png) 180 181- Wait a bit while 'Select and install software' runs 182- Participate in popularity contest -> *No* 183- Choose software to install. We need just the base system. 184- Make sure only 'SSH server' and 'Standard System Utilities' are checked 185- Uncheck 'Debian Desktop Environment' and 'Print Server' 186 187![](gitian-building/debian_install_19_software_selection.png) 188 189- Install the GRUB boot loader to the master boot record? -> Yes 190 191![](gitian-building/debian_install_20_install_grub.png) 192 193- Device for boot loader installation -> ata-VBOX_HARDDISK 194 195![](gitian-building/debian_install_21_install_grub_bootloader.png) 196 197- Installation Complete -> *Continue* 198- After installation, the VM will reboot and you will have a working Debian VM. Congratulations! 199 200![](gitian-building/debian_install_22_finish_installation.png) 201 202 203After Installation 204------------------- 205The next step in the guide involves logging in as root via SSH. 206SSH login for root users is disabled by default, so we'll enable that now. 207 208Login to the VM using username `root` and the root password you chose earlier. 209You'll be presented with a screen similar to this. 210 211![](gitian-building/debian_root_login.png) 212 213Type: 214 215``` 216sed -i 's/^PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config 217``` 218and press enter. Then, 219``` 220/etc/init.d/ssh restart 221``` 222and enter to restart SSH. Logout by typing 'logout' and pressing 'enter'. 223 224Connecting to the VM 225---------------------- 226 227After the VM has booted you can connect to it using SSH, and files can be copied from and to the VM using a SFTP utility. 228Connect to `localhost`, port `22222` (or the port configured when installing the VM). 229On Windows you can use [putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and [WinSCP](http://winscp.net/eng/index.php). 230 231For example, to connect as `root` from a Linux command prompt use 232 233 $ ssh root@localhost -p 22222 234 The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established. 235 RSA key fingerprint is ae:f5:c8:9f:17:c6:c7:1b:c2:1b:12:31:1d:bb:d0:c7. 236 Are you sure you want to continue connecting (yes/no)? yes 237 Warning: Permanently added '[localhost]:22222' (RSA) to the list of known hosts. 238 root@localhost's password: (enter root password configured during install) 239 240 The programs included with the Debian GNU/Linux system are free software; 241 the exact distribution terms for each program are described in the 242 individual files in /usr/share/doc/*/copyright. 243 244 Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent 245 permitted by applicable law. 246 root@debian:~# 247 248Replace `root` with `debian` to log in as user. 249 250Setting up Debian for Gitian building 251-------------------------------------- 252 253In this section we will be setting up the Debian installation for Gitian building. 254 255First we need to log in as `root` to set up dependencies and make sure that our 256user can use the sudo command. Type/paste the following in the terminal: 257 258```bash 259apt-get install git ruby sudo apt-cacher-ng qemu-utils debootstrap lxc python-cheetah parted kpartx bridge-utils make ubuntu-archive-keyring curl 260adduser debian sudo 261``` 262 263Then set up LXC and the rest with the following, which is a complex jumble of settings and workarounds: 264 265```bash 266# the version of lxc-start in Debian needs to run as root, so make sure 267# that the build script can execute it without providing a password 268echo "%sudo ALL=NOPASSWD: /usr/bin/lxc-start" > /etc/sudoers.d/gitian-lxc 269echo "%sudo ALL=NOPASSWD: /usr/bin/lxc-execute" >> /etc/sudoers.d/gitian-lxc 270# make /etc/rc.local script that sets up bridge between guest and host 271echo '#!/bin/sh -e' > /etc/rc.local 272echo 'brctl addbr br0' >> /etc/rc.local 273echo 'ifconfig br0 10.0.3.2/24 up' >> /etc/rc.local 274echo 'iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE' >> /etc/rc.local 275echo 'echo 1 > /proc/sys/net/ipv4/ip_forward' >> /etc/rc.local 276echo 'exit 0' >> /etc/rc.local 277# make sure that USE_LXC is always set when logging in as debian, 278# and configure LXC IP addresses 279echo 'export USE_LXC=1' >> /home/debian/.profile 280echo 'export GITIAN_HOST_IP=10.0.3.2' >> /home/debian/.profile 281echo 'export LXC_GUEST_IP=10.0.3.5' >> /home/debian/.profile 282reboot 283``` 284 285At the end the VM is rebooted to make sure that the changes take effect. The steps in this 286section only need to be performed once. 287 288Installing Gitian 289------------------ 290 291Re-login as the user `debian` that was created during installation. 292The rest of the steps in this guide will be performed as that user. 293 294There is no `python-vm-builder` package in Debian, so we need to install it from source ourselves, 295 296```bash 297wget http://archive.ubuntu.com/ubuntu/pool/universe/v/vm-builder/vm-builder_0.12.4+bzr494.orig.tar.gz 298echo "76cbf8c52c391160b2641e7120dbade5afded713afaa6032f733a261f13e6a8e vm-builder_0.12.4+bzr494.orig.tar.gz" | sha256sum -c 299# (verification -- must return OK) 300tar -zxvf vm-builder_0.12.4+bzr494.orig.tar.gz 301cd vm-builder-0.12.4+bzr494 302sudo python setup.py install 303cd .. 304``` 305 306**Note**: When sudo asks for a password, enter the password for the user *debian* not for *root*. 307 308Clone the git repositories for bitcoin and Gitian. 309 310```bash 311git clone https://github.com/devrandom/gitian-builder.git 312git clone https://github.com/bitcoin/bitcoin 313git clone https://github.com/bitcoin-core/gitian.sigs.git 314``` 315 316Setting up the Gitian image 317------------------------- 318 319Gitian needs a virtual image of the operating system to build in. 320Currently this is Ubuntu Trusty x86_64. 321This image will be copied and used every time that a build is started to 322make sure that the build is deterministic. 323Creating the image will take a while, but only has to be done once. 324 325Execute the following as user `debian`: 326 327```bash 328cd gitian-builder 329bin/make-base-vm --lxc --arch amd64 --suite trusty 330``` 331 332There will be a lot of warnings printed during the build of the image. These can be ignored. 333 334**Note**: When sudo asks for a password, enter the password for the user *debian* not for *root*. 335 336Getting and building the inputs 337-------------------------------- 338 339Follow the instructions in [doc/release-process.md](release-process.md#fetch-and-build-inputs-first-time-or-when-dependency-versions-change) 340in the bitcoin repository under 'Fetch and create inputs' to install sources which require 341manual intervention. Also optionally follow the next step: 'Seed the Gitian sources cache 342and offline git repositories' which will fetch the remaining files required for building 343offline. 344 345Building Bitcoin Core 346---------------- 347 348To build Bitcoin Core (for Linux, OS X and Windows) just follow the steps under 'perform 349Gitian builds' in [doc/release-process.md](release-process.md#perform-gitian-builds) in the bitcoin repository. 350 351This may take some time as it will build all the dependencies needed for each descriptor. 352These dependencies will be cached after a successful build to avoid rebuilding them when possible. 353 354At any time you can check the package installation and build progress with 355 356```bash 357tail -f var/install.log 358tail -f var/build.log 359``` 360 361Output from `gbuild` will look something like 362 363 Initialized empty Git repository in /home/debian/gitian-builder/inputs/bitcoin/.git/ 364 remote: Counting objects: 57959, done. 365 remote: Total 57959 (delta 0), reused 0 (delta 0), pack-reused 57958 366 Receiving objects: 100% (57959/57959), 53.76 MiB | 484.00 KiB/s, done. 367 Resolving deltas: 100% (41590/41590), done. 368 From https://github.com/bitcoin/bitcoin 369 ... (new tags, new branch etc) 370 --- Building for trusty amd64 --- 371 Stopping target if it is up 372 Making a new image copy 373 stdin: is not a tty 374 Starting target 375 Checking if target is up 376 Preparing build environment 377 Updating apt-get repository (log in var/install.log) 378 Installing additional packages (log in var/install.log) 379 Grabbing package manifest 380 stdin: is not a tty 381 Creating build script (var/build-script) 382 lxc-start: Connection refused - inotify event with no name (mask 32768) 383 Running build script (log in var/build.log) 384 385Building an alternative repository 386----------------------------------- 387 388If you want to do a test build of a pull on GitHub it can be useful to point 389the Gitian builder at an alternative repository, using the same descriptors 390and inputs. 391 392For example: 393```bash 394URL=https://github.com/laanwj/bitcoin.git 395COMMIT=2014_03_windows_unicode_path 396./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml 397./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml 398./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml 399``` 400 401Building fully offline 402----------------------- 403 404For building fully offline including attaching signatures to unsigned builds, the detached-sigs repository 405and the bitcoin git repository with the desired tag must both be available locally, and then gbuild must be 406told where to find them. It also requires an apt-cacher-ng which is fully-populated but set to offline mode, or 407manually disabling gitian-builder's use of apt-get to update the VM build environment. 408 409To configure apt-cacher-ng as an offline cacher, you will need to first populate its cache with the relevant 410files. You must additionally patch target-bin/bootstrap-fixup to set its apt sources to something other than 411plain archive.ubuntu.com: us.archive.ubuntu.com works. 412 413So, if you use LXC: 414 415```bash 416export PATH="$PATH":/path/to/gitian-builder/libexec 417export USE_LXC=1 418cd /path/to/gitian-builder 419./libexec/make-clean-vm --suite trusty --arch amd64 420 421LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root apt-get update 422LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root \ 423 -e DEBIAN_FRONTEND=noninteractive apt-get --no-install-recommends -y install \ 424 $( sed -ne '/^packages:/,/[^-] .*/ {/^- .*/{s/"//g;s/- //;p}}' ../bitcoin/contrib/gitian-descriptors/*|sort|uniq ) 425LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root apt-get -q -y purge grub 426LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root -e DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade 427``` 428 429And then set offline mode for apt-cacher-ng: 430 431``` 432/etc/apt-cacher-ng/acng.conf 433[...] 434Offlinemode: 1 435[...] 436 437service apt-cacher-ng restart 438``` 439 440Then when building, override the remote URLs that gbuild would otherwise pull from the Gitian descriptors:: 441```bash 442 443cd /some/root/path/ 444git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git 445 446BTCPATH=/some/root/path/bitcoin 447SIGPATH=/some/root/path/bitcoin-detached-sigs 448 449./bin/gbuild --url bitcoin=${BTCPATH},signature=${SIGPATH} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml 450``` 451 452Signing externally 453------------------- 454 455If you want to do the PGP signing on another device, that's also possible; just define `SIGNER` as mentioned 456and follow the steps in the build process as normal. 457 458 gpg: skipped "laanwj": secret key not available 459 460When you execute `gsign` you will get an error from GPG, which can be ignored. Copy the resulting `.assert` files 461in `gitian.sigs` to your signing machine and do 462 463```bash 464 gpg --detach-sign ${VERSION}-linux/${SIGNER}/bitcoin-linux-build.assert 465 gpg --detach-sign ${VERSION}-win/${SIGNER}/bitcoin-win-build.assert 466 gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/bitcoin-osx-build.assert 467``` 468 469This will create the `.sig` files that can be committed together with the `.assert` files to assert your 470Gitian build. 471 472Uploading signatures 473--------------------- 474 475After building and signing you can push your signatures (both the `.assert` and `.assert.sig` files) to the 476[bitcoin-core/gitian.sigs](https://github.com/bitcoin-core/gitian.sigs/) repository, or if that's not possible create a pull 477request. You can also mail the files to Wladimir (laanwj@gmail.com) and he will commit them. 478