build.mdwn 7.93 KB
Newer Older
1
2
[[!meta title="Building a Tails image"]]

3
4
The following instructions will lead you through the process of building
a Tails ISO image with [Rake], [Vagrant] and [vagrant-libvirt].
5

6
7
[Rake]: http://rake.rubyforge.org/
[Vagrant]: http://vagrantup.com/
8
[vagrant-libvirt]: https://github.com/vagrant-libvirt/vagrant-libvirt/
9

10
11
[[!toc levels=2]]

12
13
14
15
# Requirements

To build Tails you need:

16
 * Debian 9 (Stretch) or newer
17
18
19
20
 * the KVM virtual machine hypervisor
 * at least 1 GiB of free RAM
 * 20 GB of free storage

21
22
23
24
25
26
# Setup the build environment

1. To install everything the Tails build system needs, execute the
   following command:

       sudo apt install \
27
           psmisc \
28
29
30
31
32
33
34
35
36
37
38
39
           git \
           rake \
           libvirt-daemon-system \
           dnsmasq-base \
           ebtables \
           qemu-system-x86 \
           qemu-utils \
           vagrant \
           vagrant-libvirt \
           vmdebootstrap && \
       sudo systemctl restart libvirtd

40
41
42
2. Ensure your user can run commands as root with `sudo`.

3. Ensure your user is in the relevant groups:
43
44
45
46
47

       for group in kvm libvirt libvirt-qemu ; do
          sudo adduser "$(whoami)" "$group"
       done

48
4. Logout and log back in to apply the new group memberships.
anonym's avatar
anonym committed
49

50
51
# Build Tails

52
53
54
1. To get the Tails sources and checkout the
   [[development branch|contribute/git#main-repo]], execute the
   following commands:
55

56
57
58
59
        git clone https://git-tails.immerda.ch/tails && \
        cd tails && \
        git checkout devel && \
        git submodule update --init
60

intrigeri's avatar
intrigeri committed
61
2. To build an ISO image, execute the following command:
62

63
        rake build && rake vm:halt
64

65
66
   When the build completes, several `tails-*` files
   will appear in the current directory.
67

68
69
You may also want to [[contribute/customize]] the content of the ISO
image before building it.
70

intrigeri's avatar
intrigeri committed
71
72
<a id="vagrant-known-issues"></a>

73
# Known issues and workarounds
anonym's avatar
anonym committed
74

75
* If Vagrant fails to start the Tails builder VM with an error similar
76
  to:
77

78
79
80
81
82
83
84
85
        Virtio-9p Failed to initialize fs-driver with id:fsdev-fs0

  … then see [[!tails_ticket 11411]].

* If Vagrant fails to start the Tails builder VM with:

        Initialization parameters must be an attributes hash, got NilClass nil (ArgumentError)

86
  … then restart the libvirtd service:
87

88
89
90
        sudo systemctl restart libvirtd.service

  Finally, try building again.
91

anonym's avatar
anonym committed
92
* If Vagrant failed to start the Tails builder VM the first time
Cyril Brulebois's avatar
Cyril Brulebois committed
93
  (e.g. because of permission issues or the `kvm` module not being
anonym's avatar
anonym committed
94
95
96
  loaded) it will not automatically run the provisioning script, so
  you must run `rake vm:provision` yourself before attempting your
  first `rake build`. If that fails, run `rake vm:destroy`, which
Cyril Brulebois's avatar
Cyril Brulebois committed
97
98
  removes this half-broken VM, and then start from scratch with
  `rake build` or similar.
99

100
# Build settings
101

102
You can customize the build system using two environment variables:
103

104
105
 * `ARTIFACTS` is the path where the ISO image is stored once the
   build completes; for example:
106

107
        ARTIFACTS='/path/to/directory'
intrigeri's avatar
intrigeri committed
108

109
110
 * To tweak other build settings, use `TAILS_BUILD_OPTIONS`,
   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
117
   This will force the build to happen in RAM and SquashFS compression
   will be done using *gzip*.
118

119
120
121
122
123
124
125
126
127
128
129
130
131
## SquashFS compression settings

One of the most expensive operations when building Tails is the creation
of the final SquashFS. It also depends on the compression algorithm used.
When working on the `stable` or `testing` branch, the image will be made
using the slow but efficient default. Any other setup will switch to the
faster *gzip*.

Forcing a specific behaviour can be done using:

 * **gzipcomp**: always use *gzip* to create the SquashFS.
 * **defaultcomp**: always use the default compression algorithm.

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
137
138
139
140
start the virtual machine, it will automatically switch to 'build in RAM'
mode.

To force a specific behaviour please set:

141
 * **ram**: start the virtual machine with lots of memory, build Tails
142
143
   inside a `tmpfs`. Build fails if the system is not in a proper state to
   do so.
144
 * **noram**: start the virtual machine with the bare minimum needed memory if not already
145
146
   done, build Tails using the virtual machine hard disk.

147
## Network settings
148
149
150
151
152
153

 * **offline**: This option will make the build system do its best to
   not depend on the network, e.g. if you use the VM's caching proxy
   if will *only* use cached APT lists and packages. Use this when you
   do not have an Internet connection.

154
## Git settings
155

156
157
You can force the build system to handle the Git tree in a special
way:
158
159
160
161

 * **ignorechanges**: allow to make a build that will ignore changes in the Git
   repository.

162
163
164
165
166
167
168
169
170
   The build system can only work on files that have been *committed* to the Git
   repository. By default, it will refuse to start a build in presence of
   uncommitted changes.

 * **mergebasebranch**: if building from a branch (not tag!) this
   forces a merge of the base branch before the build process starts
   for real. This is mostly meant for our Jenkins deployment, so use
   at your own risk.

171
## Variations useful for testing build reproducibility
172

173
174
These options allow one to vary the build environment in ways that may
affect reproducibility of the ISO image:
175
176
177
178

 * **dateoffset=_+n_**, **dateoffset=_-n_**: change the virtual
   machine system time by _+n_ or _-n_ days.

179
180
181
182
183
184
185
186
187
188
189
190
 * **cpus=_n_**: allocate _n_ CPUs to the virtual machine.
   Obviously you should not allocate more virtual CPUs than the number
   of cores available to the host system. When using Linux, the number
   of CPUs allocated will default to be the same as the host system.

 * **cpumodel=_model_**: type of the CPUs allocated to the virtual
   machine. See
   [the corresponding libvirt documentation](https://libvirt.org/formatdomain.html#elementsCPU).

 * **machinetype=_type_**: type of the QEMU machine; see the output of
   `qemu-system-x86_64 -machine help` for available options.

191
## Developer convenience settings
192
193

 * **keeprunning**: do not clean up the builder VM on build
anonym's avatar
anonym committed
194
   success.
195

196
 * **forcecleanup**: ensure a new builder VM is used for `rake build`,
intrigeri's avatar
intrigeri committed
197
   and also clean up this VM after the build, no matter if it
198
199
   succeeded or not.

200
201
202
 * **rescue**: implies **keeprunning** and will also not clean up the
   build directory, which is useful for investigating build failures.

203
204
## HTTP proxy settings

205
206
207
Building Tails requires downloading a little bit more than 2 GiB of
data. By default, the build system will configure and use its own HTTP
caching proxy in order to speed up the following builds.
208

209
210
We recommend against modifying this behavior, but you can do it with
the following build options:
211

212
 * **extproxy**: use the external proxy configured through the `http_proxy`
213
214
215
216
   environment variable. Fail if it is not set.

   <div class="bug">

217
218
219
220
221
222
223
224
225
226
   <ul>

     <li>An external HTTP proxy does not save any download bandwidth unless
     configured in a very special and undocumented way.</li>

     <li>At least one step of the build does not honor the external proxy
     settings, so outgoing Internet connections from the build VM must be
     allowed to go through anyway.</li>

   </ul>
227
228
229
230
231
232
233
234

   </div>

 * **vmproxy**: use the local proxy configured in the virtual machine even
   if a local HTTP proxy is set.

 * **noproxy**: do not use any HTTP proxy.

intrigeri's avatar
intrigeri committed
235
236
Verify if the resulting ISO is reproducible
===========================================
237

238
See [[verification|contribute/build/reproducible#verify-iso]] section.
239

240
241
More information
================
242

243
244
To know all available Rake tasks, please run `rake -T`.

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
249
Details about how this Vagrant build system is setup, see its
[[design page|build/vagrant-setup]].
250

251
Other related pages:
252
253

[[!map pages="contribute/build/*"]]