wiki/src/contribute/build.mdwn

   1 [[!meta title="Building a Tails image"]]
   2
   3 The following instructions will lead you through the process of building
   4 a Tails ISO image with [Rake], [Vagrant] and [vagrant-libvirt].
   5
   6 [Rake]: http://rake.rubyforge.org/
   7 [Vagrant]: http://vagrantup.com/
   8 [vagrant-libvirt]: https://github.com/vagrant-libvirt/vagrant-libvirt/
   9
  10 [[!toc levels=2]]
  11
  12 # Requirements
  13
  14 To build Tails you need:
  15
  16  * Debian 9 (Stretch) or newer
  17  * the KVM virtual machine hypervisor
  18  * at least 1 GiB of free RAM
  19  * 20 GB of free storage
  20
  21 # Setup the build environment
  22
  23 1. To install everything the Tails build system needs, execute the
  24    following command:
  25
  26        sudo apt install \
  27            psmisc \
  28            git \
  29            rake \
  30            libvirt-daemon-system \
  31            dnsmasq-base \
  32            ebtables \
  33            qemu-system-x86 \
  34            qemu-utils \
  35            vagrant \
  36            vagrant-libvirt \
  37            vmdebootstrap && \
  38        sudo systemctl restart libvirtd
  39
  40 2. Ensure your user can run commands as root with `sudo`.
  41
  42 3. Ensure your user is in the relevant groups:
  43
  44        for group in kvm libvirt libvirt-qemu ; do
  45           sudo adduser "$(whoami)" "$group"
  46        done
  47
  48 4. Logout and log back in to apply the new group memberships.
  49
  50 # Build Tails
  51
  52 1. To get the Tails sources and checkout the
  53    [[development branch|contribute/git#main-repo]], execute the
  54    following commands:
  55
  56         git clone https://git-tails.immerda.ch/tails && \
  57         cd tails && \
  58         git checkout devel && \
  59         git submodule update --init
  60
  61 2. To build an ISO image, execute the following command:
  62
  63         rake build && rake vm:halt
  64
  65    When the build completes, several `tails-*` files
  66    will appear in the current directory.
  67
  68 You may also want to [[contribute/customize]] the content of the ISO
  69 image before building it.
  70
  71 <a id="vagrant-known-issues"></a>
  72
  73 # Known issues and workarounds
  74
  75 * If Vagrant fails to start the Tails builder VM with an error similar
  76   to:
  77
  78         Virtio-9p Failed to initialize fs-driver with id:fsdev-fs0
  79
  80   … then see [[!tails_ticket 11411]].
  81
  82 * If Vagrant fails to start the Tails builder VM with:
  83
  84         Initialization parameters must be an attributes hash, got NilClass nil (ArgumentError)
  85
  86   … then restart the libvirtd service:
  87
  88         sudo systemctl restart libvirtd.service
  89
  90   Finally, try building again.
  91
  92 * If Vagrant failed to start the Tails builder VM the first time
  93   (e.g. because of permission issues or the `kvm` module not being
  94   loaded) it will not automatically run the provisioning script, so
  95   you must run `rake vm:provision` yourself before attempting your
  96   first `rake build`. If that fails, run `rake vm:destroy`, which
  97   removes this half-broken VM, and then start from scratch with
  98   `rake build` or similar.
  99
 100 # Build settings
 101
 102 You can customize the build system using two environment variables:
 103
 104  * `ARTIFACTS` is the path where the ISO image is stored once the
 105    build completes; for example:
 106
 107         ARTIFACTS='/path/to/directory'
 108
 109  * To tweak other build settings, use `TAILS_BUILD_OPTIONS`,
 110    a space-separated list of build options documented below.
 111
 112    For example, you can speed up the build by setting:
 113
 114         export TAILS_BUILD_OPTIONS="ram gzipcomp"
 115
 116    This will force the build to happen in RAM and SquashFS compression
 117    will be done using *gzip*.
 118
 119 ## SquashFS compression settings
 120
 121 One of the most expensive operations when building Tails is the creation
 122 of the final SquashFS. It also depends on the compression algorithm used.
 123 When working on the `stable` or `testing` branch, the image will be made
 124 using the slow but efficient default. Any other setup will switch to the
 125 faster *gzip*.
 126
 127 Forcing a specific behaviour can be done using:
 128
 129  * **gzipcomp**: always use *gzip* to create the SquashFS.
 130  * **defaultcomp**: always use the default compression algorithm.
 131
 132 ## Memory build settings
 133
 134 Tails builds way faster when everything is done in memory. If your computer
 135 runs Linux and happens to have enough free memory before you
 136 start the virtual machine, it will automatically switch to 'build in RAM'
 137 mode.
 138
 139 To force a specific behaviour please set:
 140
 141  * **ram**: start the virtual machine with lots of memory, build Tails
 142    inside a `tmpfs`. Build fails if the system is not in a proper state to
 143    do so.
 144  * **noram**: start the virtual machine with the bare minimum needed memory if not already
 145    done, build Tails using the virtual machine hard disk.
 146
 147 ## Network settings
 148
 149  * **offline**: This option will make the build system do its best to
 150    not depend on the network, e.g. if you use the VM's caching proxy
 151    if will *only* use cached APT lists and packages. Use this when you
 152    do not have an Internet connection.
 153
 154 ## Git settings
 155
 156 You can force the build system to handle the Git tree in a special
 157 way:
 158
 159  * **ignorechanges**: allow to make a build that will ignore changes in the Git
 160    repository.
 161
 162    The build system can only work on files that have been *committed* to the Git
 163    repository. By default, it will refuse to start a build in presence of
 164    uncommitted changes.
 165
 166  * **mergebasebranch**: if building from a branch (not tag!) this
 167    forces a merge of the base branch before the build process starts
 168    for real. This is mostly meant for our Jenkins deployment, so use
 169    at your own risk.
 170
 171 ## Variations useful for testing build reproducibility
 172
 173 These options allow one to vary the build environment in ways that may
 174 affect reproducibility of the ISO image:
 175
 176  * **dateoffset=_+n_**, **dateoffset=_-n_**: change the virtual
 177    machine system time by _+n_ or _-n_ days.
 178
 179  * **cpus=_n_**: allocate _n_ CPUs to the virtual machine.
 180    Obviously you should not allocate more virtual CPUs than the number
 181    of cores available to the host system. When using Linux, the number
 182    of CPUs allocated will default to be the same as the host system.
 183
 184  * **cpumodel=_model_**: type of the CPUs allocated to the virtual
 185    machine. See
 186    [the corresponding libvirt documentation](https://libvirt.org/formatdomain.html#elementsCPU).
 187
 188  * **machinetype=_type_**: type of the QEMU machine; see the output of
 189    `qemu-system-x86_64 -machine help` for available options.
 190
 191 ## Developer convenience settings
 192
 193  * **keeprunning**: do not clean up the builder VM on build
 194    success.
 195
 196  * **forcecleanup**: ensure a new builder VM is used for `rake build`,
 197    and also clean up this VM after the build, no matter if it
 198    succeeded or not.
 199
 200  * **rescue**: implies **keeprunning** and will also not clean up the
 201    build directory, which is useful for investigating build failures.
 202
 203 ## HTTP proxy settings
 204
 205 Building Tails requires downloading a little bit more than 2 GiB of
 206 data. By default, the build system will configure and use its own HTTP
 207 caching proxy in order to speed up the following builds.
 208
 209 We recommend against modifying this behavior, but you can do it with
 210 the following build options:
 211
 212  * **extproxy**: use the external proxy configured through the `http_proxy`
 213    environment variable. Fail if it is not set.
 214
 215    <div class="bug">
 216
 217    <ul>
 218
 219      <li>An external HTTP proxy does not save any download bandwidth unless
 220      configured in a very special and undocumented way.</li>
 221
 222      <li>At least one step of the build does not honor the external proxy
 223      settings, so outgoing Internet connections from the build VM must be
 224      allowed to go through anyway.</li>
 225
 226    </ul>
 227
 228    </div>
 229
 230  * **vmproxy**: use the local proxy configured in the virtual machine even
 231    if a local HTTP proxy is set.
 232
 233  * **noproxy**: do not use any HTTP proxy.
 234
 235 Verify if the resulting ISO is reproducible
 236 ===========================================
 237
 238 See [[verification|contribute/build/reproducible#verify-iso]] section.
 239
 240 More information
 241 ================
 242
 243 To know all available Rake tasks, please run `rake -T`.
 244
 245 More documentation about the build process can be found in the [Debian
 246 Live Manual](http://live.debian.net/manual/oldstable/html/live-manual.en.html).
 247
 248 Details about how this Vagrant build system is setup, see its
 249 [[design page|build/vagrant-setup]].
 250
 251 Other related pages:
 252
 253 [[!map pages="contribute/build/*"]]