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

3
[[!toc levels=3]]
4

5
6
7
8
9
10
11
Git repository and branches
===========================

You will need to clone the Tails Git repository, and to checkout the
branch that you want to build (most likely, _not_ `master`): learn
more about [[our Git branches layout|contribute/git#main-repo]].

Tails developers's avatar
Tails developers committed
12
13
<a id="vagrant"></a>

14
15
16
17
18
19
20
Using Vagrant
=============

Tails can be built easily in a virtual machine using [Rake], [Vagrant] and
[VirtualBox]. The process requires a minimum of 1 GB of free memory and a
maximum of 10 GB of free storage.

21
22
23
24
[Rake]: http://rake.rubyforge.org/
[Vagrant]: http://vagrantup.com/
[VirtualBox]: http://www.virtualbox.org/

25
## Installing the dependencies in Debian
26

27
28
29
30
31
32
33
34
35
### If you run Debian Jessie

1. Add Debian unstable to your APT sources:

       echo "deb http://ftp.us.debian.org/debian/ unstable main" | \
           sudo tee /etc/apt/sources.list.d/unstable.list

2. Pin all packages from Debian unstable at 500 (`apt_preferences(5)`):

Tails developers's avatar
Tails developers committed
36
       sudo tee /etc/apt/preferences.d/unstable <<EOF
37
38
39
40
41
42
       Package: *
       Pin: release o=Debian,a=unstable
       Pin-Priority: 500
       EOF

3. Install the needed tools:
43

44
45
       sudo apt-get install git virtualbox rake ruby-childprocess \
           ruby-erubis ruby-i18n ruby-log4r ruby-net-scp ruby bsdtar curl
46

47
48
49
50
51
52
53
54
55
56
### If you run Debian Wheezy

1. Add Debian Jessie, unstable and wheezy-backports to your APT sources:

       echo "deb http://ftp.us.debian.org/debian/ jessie main" | \
           sudo tee /etc/apt/sources.list.d/jessie.list
       echo "deb http://ftp.us.debian.org/debian/ unstable main" | \
           sudo tee /etc/apt/sources.list.d/unstable.list
       echo "deb http://ftp.us.debian.org/debian/ wheezy-backports main" | \
           sudo tee /etc/apt/sources.list.d/wheezy-backports.list
57

58
59
2. Pin all packages from Debian Jessie and unstable at 500 (`apt_preferences(5)`):

Tails developers's avatar
Tails developers committed
60
       sudo tee /etc/apt/preferences.d/jessie <<EOF
61
62
63
64
       Package: *
       Pin: release o=Debian,a=jessie
       Pin-Priority: 500
       EOF
Tails developers's avatar
Tails developers committed
65
       sudo tee /etc/apt/preferences.d/unstable <<EOF
66
67
68
69
70
71
       Package: *
       Pin: release o=Debian,a=unstable
       Pin-Priority: 500
       EOF

3. Install the needed tools:
72

73
74
75
       sudo apt-get install git virtualbox rake ruby-childprocess/jessie \
           ruby-net-scp/jessie ruby-erubis ruby-i18n ruby-log4r bsdtar curl \
           gettext/wheezy-backports
76

77
78
79
80
81
82
### In both Debian Wheezy and Jessie

At the moment Tails relies on a version of Vagrant (the 1.4.x series)
that is not packaged in Debian any more. Here's a workaround for both
Debian Wheezy and Jessie:

83
    sudo tee /etc/apt/preferences.d/tails-build-vagrant <<EOF
84
85
86
    Package: vagrant
    Pin: version 1.4.3+dfsg1-3
    Pin-Priority: 550
87

88
89
90
91
92
93
94
95
96
97
    Package: ruby-net-ssh
    Pin: version 1:2.6.8-2
    Pin-Priority: 550
    EOF
    echo "deb http://snapshot.debian.org/archive/debian/20141010T042049Z/ unstable main" | \
        sudo tee /etc/apt/sources.list.d/20141010T042049Z.list
    sudo apt-get -o Acquire::Check-Valid-Until=false update
    sudo apt-get install vagrant ruby-net-ssh
    sudo rm /etc/apt/sources.list.d/20141010T042049Z.list
    sudo apt-get update
98

99
100
101
102
## Building Tails using Vagrant

Once all dependencies are installed, get the Tails sources and
checkout the development branch:
103

104
    git clone https://git-tails.immerda.ch/tails
105
106
    cd tails
    git checkout devel
107
108
109

Build Tails using Vagrant:

110
    rake build
111
112
113
114
115
116
117
118
119

The first time, this can take a little while to download the base virtual
machine from Tails mirror (around 300 MB). It will then boot the machine,
set it up and start the build process. When done, several `tails-*` files
should appear in the current directory.

After you are done working on Tails, do not forget to shut the virtual
machine down:

120
    rake vm:halt
121
122
123
124
125
126
127
128
129
130

One may also want to [[contribute/customize]] their image before building.

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

Local HTTP proxy
----------------

If you have a local HTTP proxy, the build system will use it as long as
you properly set the `http_proxy` environment variable. The easiest way to
131
do so is to run:
132

133
    export http_proxy=http://proxy.lan:3142
134
135
136
137
138
139
140
141
142
143
144
145
146
147

This needs to be done before any other operations.

Build options
-------------

Options regarding the build process can be set using the
`TAILS_BUILD_OPTIONS` environment variable. Muliple options must be
separated by whitespaces.

The following options are available:

### Memory build settings

148
Tails builds way faster when everything is done in memory. If your computer
149
runs Linux and happens to have more than 7 GB of free memory before you
150
151
152
153
154
start the virtual machine, it will automatically switch to 'build in RAM'
mode.

To force a specific behaviour please set:

155
 * **ram**: start the virtual machine with 7 GB of memory, build Tails
156
157
   inside a `tmpfs`. Build fails if the system is not in a proper state to
   do so.
158
 * **noram**: start the virtual machine with 512 MB of memory if not already
159
160
161
162
   done, build Tails using the virtual machine hard disk.

### HTTP proxy settings

163
Building Tails requires downloading a little bit more than 1 GB of Debian
164
165
166
packages. To preserve bandwidth and developer sanity, using a HTTP proxy is
nearly a must. Tails virtual machine contains a fully configured local HTTP
proxy that will be used if no other local proxy is defined.
167

168
The following flags can be used to force a specific behaviour:
169

170
171
172
173
174
 * **extproxy**: use the proxy configured through the `http_proxy`
   environment variable. Fail if it is not set.
 * **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.
175

176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
### 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.

### Clean-up settings

191
192
193
194
195
Some operations are preserved accross builds. Currently they are:

* The wiki (for documentation).

In case you want to delete all these, the following option is available:
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222

 * **cleanall**: force a clean up before starting the build.

### Virtual CPUs settings

The number of virtual CPUs that are allocated in the virtual machine can be set
through:

 * **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.

### Git settings

The build system can only work on files that have been *commited* to the Git
repository. By default, it will refuse to start a build in presence of
uncommited changes. This behaviour can be controlled by:

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

### Example

The fastest build you could pretend to get can be done by setting:

223
    export TAILS_BUILD_OPTIONS="ram cache extproxy gzipcomp"
224

225
226
227
228
This will force the build to happen in RAM and allow skipping the
boostrap stage if one is cached, and will use use an HTTP proxy
external to the virtual machine, and SquashFS compression will be done
using *gzip*.
229

Tails developers's avatar
Tails developers committed
230
231
<a id="manual"></a>

232
233
234
235
Building manually
=================

In order to build Tails manually, you need a running [Debian
236
Wheezy](https://www.debian.org/releases/wheezy/) system
Tails developers's avatar
Tails developers committed
237
and some [backports](http://backports.debian.org/). Anything else
238
will fail.
239

240
Dependencies
241
242
243
------------

The following Debian packages need to be installed:
244

245
* our `live-build` 2.x package, adapted for Wheezy. Its version is
246
  something like *3.0.5+really+is+2.0.12-0.tails2*. One can install it
247
248
249
250
  from:

      deb http://deb.tails.boum.org/ builder-wheezy main

251
252
253
254
255
  This APT repository's signing key can be found:

  - in our Git tree (that you have cloned already, right?):
    `config/chroot_sources/tails.chroot.gpg`
  - at <http://deb.tails.boum.org/key.asc>
intrigeri's avatar
intrigeri committed
256
  - on the keyservers.
257

258
  It is certified by the
BitingBird's avatar
BitingBird committed
259
260
  [[Tails signing key|doc/about/openpgp_keys#signing]], and its
  fingerprint is:
261
262
263

      221F 9A3C 6FA3 E09E 182E  060B C798 8EA7 A358 D82E

264
265
* `syslinux-utils` 6.03, e.g. from our `builder-wheezy` repository
  just like `live-build`
266
267
* `eatmydata` 82 or newer, available in wheezy-backports.
* `time` and `whois` (for `/usr/bin/mkpasswd`)
268
* `ikiwiki` 3.20150107 or newer, available in stretch.
269
270
271
* `apt-get install libyaml-perl libyaml-libyaml-perl po4a perlmagick
  libyaml-syck-perl` so that the wiki builds smoothly.
* `dpkg-dev`
272
* `intltool`
273
* `gettext` 0.18.3 or newer, available in wheezy-backports
274

275
276
277
Configure live-build
--------------------

intrigeri's avatar
intrigeri committed
278
Remove any line matching `/^\[[:space:]]*LB.*MIRROR.*=/` in
279
`/etc/live/build.conf`.
280

281
Build process
282
283
-------------

284
Every build command must be run as `root`, at the root of a clone of the
285
[[`tails` repository|git]].
286

287
In short, a build shall be done using:
288

289
    lb clean --all && lb config && lb build
290

291
292
293
Running `lb config` or `lb build` in an environment that wasn't full
cleaned first is not supported.

294
### Customize the build process if needed
295
296
297

If you need to set custom build settings that are specific to your
local environment, such as a custom Debian mirror or APT proxy, you
298
probably want to configure live-build a bit.
299

300
The most common customizations are documented on this wiki:
301

302
303
304
* to avoid compressing the SquashFS using XZ (efficient, but very
  slow), `export MKSQUASHFS_OPTIONS='-comp gzip'` in your
  build environment;
305
306
* [[using a custom Debian mirror to build Tails
  images|build/custom_mirror]];
307
308
309
* [[using squid-deb-proxy to build Tails images|build/squid-deb-proxy]]
  (**Note**: most Tails contributors using the manual build method
  use [[!debpts apt-cacher-ng]] instead, nowadays.)
310

311
More documentation about this can be found in the [Debian Live
Tails developers's avatar
Tails developers committed
312
Manual](http://live.debian.net/manual-2.x/html/live-manual.en.html).
313

314
315
More information
================
316
317

More documentation about the build process can be found in the [Debian
318
Live Manual](http://live.debian.net/manual/oldstable/html/live-manual.en.html).
319

Tails developers's avatar
Tails developers committed
320
321
Related pages
=============
322
323

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