tor-browser.mdwn 8.06 KB
Newer Older
intrigeri's avatar
intrigeri committed
1
[[!meta title="Upgrading the Tor Browser"]]
2

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
[[!toc levels=2]]

The big picture
===============

The Tails ISO build system [[!tails_gitweb
config/chroot_local-hooks/10-tbb desc="downloads"]] a set of Tor
Browser tarballs from a location specified in [[!tails_gitweb
config/chroot_local-includes/usr/share/tails/tbb-dist-url.txt]], and
compares their hash with previously verified ones found in
[[!tails_gitweb
config/chroot_local-includes/usr/share/tails/tbb-sha256sums.txt]].

Once released officially, Tor Browser tarballs can be found in
a [permanent (?)
location](http://archive.torproject.org/tor-package-archive/torbrowser/).
However, when upgrading Tor Browser for an imminent Tails release, we
generally have to use Tor Browser tarballs that are under QA and not
officially released yet. So, we have to retrieve them from another,
temporary location, such as
<http://people.torproject.org/~mikeperry/builds/>. If we hard-coded
this temporary URL in `tbb-dist-url.txt`, then our release tag would
only be buildable for as long the tarballs stay in that place, which
at best is a few months.

To solve this, we host ourselves the Tor Browser tarballs we need, and
point to [this permanent
location](http://torbrowser-archive.tails.boum.org/) for anything that
we tag.

Still, one can set an arbitrary download location in
`tbb-dist-url.txt`, which should provide all the flexibility needed
for development purposes.

Upgrade Tor Browser in Tails
============================

40
41
Have a look at

Tails developers's avatar
Tails developers committed
42
43
44
* <https://archive.torproject.org/tor-package-archive/torbrowser/>
* <https://www.torproject.org/dist/torbrowser/>
* <https://people.torproject.org/~mikeperry/builds/>
45
* <https://people.torproject.org/~gk/builds/>
46
* <https://people.torproject.org/~boklm/builds/>
Tails developers's avatar
Tails developers committed
47
* <https://people.torproject.org/~linus/builds/>
48

49
50
and see if the desired version is available. Set `TBB_DIST_URL` to the
chosen URL, and set `TBB_VERSION` to the desired Tor Browser version, for
51
example:
52

53
    TBB_DIST_URL=https://people.torproject.org/~mikeperry/builds/4.5-build5/
54
    TBB_VERSION=4.5-build5
55

56
57
58
59
<div class="caution">
Ensure you include the "-buildN" part.
</div>

Tails developers's avatar
Tails developers committed
60
61
Fetch the version's hash file and its detached signature, and verify
with GnuPG:
62

63
    wget ${TBB_DIST_URL}/sha256sums-unsigned-build.txt{.asc,} && \
anonym's avatar
anonym committed
64
    gpg --verify sha256sums-unsigned-build.txt{.asc,}
65
66

Filter the tarballs we want and make them available at build time,
Tails developers's avatar
Tails developers committed
67
when the tarballs are fetched:
68

69
70
71
    grep --color=never "\<tor-browser-linux64-.*\.tar.xz$" sha256sums-unsigned-build.txt \
    | grep -v '\<tor-browser-linux64-debug\.tar\.xz$' \
    > config/chroot_local-includes/usr/share/tails/tbb-sha256sums.txt
72

73
Then update the URL to the one chosen above:
74

75
    echo "${TBB_DIST_URL}" | sed "s,^https://,http://," > \
76
77
         config/chroot_local-includes/usr/share/tails/tbb-dist-url.txt

Tails developers's avatar
Tails developers committed
78
79
80
81
<div class="note">
<p>
We cannot use HTTPS due to limitations/bugs in
<code>apt-cacher-ng</code>, which often is used in Tails build
82
83
environments. However, it is of no consequence since we verify the
checksum file.
Tails developers's avatar
Tails developers committed
84
85
</p>
</div>
86
87
88

Lastly, commit:

Tails developers's avatar
Tails developers committed
89
    git commit config/chroot_local-includes/usr/share/tails/tbb-*.txt \
90
        -m "Upgrade Tor Browser to ${TBB_VERSION}."
91
92
93
94
95
96
97
98
99

<div class="caution">
<p>
If this new Tor Browser is meant to be included in a Tails
release, then that's not enough: as explained above, we need to host
the corresponding tarballs ourselves, so read on the next section.
</p>
</div>

100
101
102
Sync with the start-tor-browser script
======================================

103
104
105
106
Adapt our `config/chroot_local-includes/usr/local/bin/tor-browser`
and/or
`config/chroot_local-includes/usr/local/lib/tails-shell-library/tor-browser.sh`
for recent changes in `RelativeLink/start-tor-browser` in the
107
[Tor Browser builder's Git repo](https://git.torproject.org/builders/tor-browser-build.git). Look
108
109
in the Git history:

110
    git log -p projects/tor-browser/RelativeLink/start-tor-browser
111
112
113
114
115

and take note of changes to environment variables (or newly added
ones) and the commandline options passed to the `firefox` executable,
etc.

116
117
118
119
120
121
Self-hosted Tor Browser tarballs archive
========================================

Initial setup
-------------

122
First, install [[!debpts git-annex]].
123
124

Then, make sure you have an entry for `git.puppet.tails.boum.org` in
125
your `~/.ssh/config`. See `systems/ISO_history.mdwn` in the internal Git repo
126
127
128
129
130
131
132
133
for details.

Then, clone the metadata repository and initialize git-annex:

	git clone gitolite@git.puppet.tails.boum.org:torbrowser-archive.git && \
	cd torbrowser-archive && \
	git annex init 

intrigeri's avatar
intrigeri committed
134
You now have a lot of (dangling) symlinks in place of the files that are
135
136
available in this git-annex repo.

intrigeri's avatar
intrigeri committed
137
To synchronize your local git-annex metadata with the remote, run:
138
139
140

	git annex sync

141
142
Set up environment variables
----------------------------
143

144
145
146
147
1. Make sure you still have the environment variables defined in the
   previous section set.

2. Make `TAILS_GIT_REPO` point to the main Tails Git repository
148
149
   checkout where `tbb-dist-url.txt` is being worked on, for example:

150
        TAILS_GIT_REPO="$HOME/tails/git"
151

152
3. Make `TBB_ARCHIVE` point to your local git annex working
153
154
   copy of our Tor Browser archive, for example:

155
        TBB_ARCHIVE="$HOME/tails/torbrowser-archive"
156

157
4. Make `TBB_IMPORT_BRANCH` point to the branch where you want to
158
159
   import the new Tor Browser's metadata, for example:

160
        TBB_IMPORT_BRANCH=feature/123456-torbrowser-42.3.4
161

162
163
164
165
166
Import a new set of Tor Browser tarballs
----------------------------------------

1. Download and verify all the tarballs we need:

167
        TMPDIR=$(mktemp --tmpdir -d "tor-browser-${TBB_VERSION}.XXXXXXXXXX")
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
        CHROOT_INCLUDES="config/chroot_local-includes"
        TBB_SHA256SUMS_FILE="${CHROOT_INCLUDES}/usr/share/tails/tbb-sha256sums.txt"
        TBB_DIST_URL_FILE="${CHROOT_INCLUDES}/usr/share/tails/tbb-dist-url.txt"
        cd "$TAILS_GIT_REPO" && git checkout "$TBB_IMPORT_BRANCH"
        TBB_TARBALLS_BASE_URL="$(cat "${TBB_DIST_URL_FILE}" | sed "s,^http://,https://,")"
        current_branch=$(git -C "$TAILS_GIT_REPO" branch | awk '/^\* / { print $2 }')
        for branch in "$current_branch" ; do
           git -C "$TAILS_GIT_REPO" show "$branch:$TBB_SHA256SUMS_FILE" \
           | while read expected_sha256 tarball; do
              (
                 cd "$TMPDIR"
                 echo "Retrieving '${TBB_TARBALLS_BASE_URL}/${tarball}'..."
                 curl --remote-name --continue-at - \
                    "${TBB_TARBALLS_BASE_URL}/${tarball}"
              )
           done
           (
              cd "$TMPDIR" && \
              git -C "$TAILS_GIT_REPO" show "$branch:$TBB_SHA256SUMS_FILE" \
                 | sha256sum -c -
           )
        done
190

191
2. Move the tarballs into your local Git annex:
192

193
194
195
        cd "$TBB_ARCHIVE" && \
        mkdir "$TBB_VERSION" && cd "$TBB_VERSION" && \
        git annex import --duplicate "$TMPDIR/"* "$TAILS_GIT_REPO/"sha256sums-*
196
197
198
199

Commit and push your changes
----------------------------

200
201
	cd "$TBB_ARCHIVE" && \
	git commit -m "Add Tor Browser ${TBB_VERSION}." && \
202
	git annex sync && \
203
	git annex copy --to origin -- "${TBB_VERSION}"
204
205
206
207
208
209
210
211

Wait for the synchronization
----------------------------

Once you've gone through these steps, a cronjob that runs every
5 minutes will download the tarballs and make them available on
<http://torbrowser-archive.tails.boum.org/>.

212
Wait for this to happen before you proceed with the next steps.
intrigeri's avatar
intrigeri committed
213
214
215

In the meantime, you might want to import the new Tor Browser tarballs
into your `apt-cacher-ng` local cache.
216
217
218
219
220

Adjust the URL in the main Git repository
-----------------------------------------

    cd "$TAILS_GIT_REPO" && \
221
    git checkout "$TBB_IMPORT_BRANCH"
222
    current_branch=$(git branch | awk '/^\* / { print $2 }')
223
    for branch in "$current_branch" ; do
224
       git checkout "$branch" && \
225
       echo "http://torbrowser-archive.tails.boum.org/${TBB_VERSION}/" > \
226
227
            config/chroot_local-includes/usr/share/tails/tbb-dist-url.txt && \
       git commit config/chroot_local-includes/usr/share/tails/tbb-dist-url.txt \
anonym's avatar
anonym committed
228
           -m "Fetch Tor Browser from our own archive."
229
    done
230
231
232
233
234
235
236

Clean up
--------

	cd "$TBB_ARCHIVE" && \
	git annex drop -- "${TBB_VERSION}" && \
    rm -rf "$DL_DIR"