additional_software_packages.mdwn 11.5 KB
Newer Older
Alan's avatar
Alan committed
1
2
3
4
5
6
7
[[!meta title="Additional software packages design documentation"]]

[[!toc levels=2]]

Rationale
=========

8
Tails includes a coherent but limited set of applications. As the system is
9
10
amnesic, new software packages for Debian can be installed in a working
session but they are not reinstalled at next reboot.
Alan's avatar
Alan committed
11

12
13
14
Additional Software Packages is a feature to remember a set of Debian Packages
to be installed automatically from [[persistent
storage|contribute/design/persistence]] each time Tails is started.
Alan's avatar
Alan committed
15

16
17
Use cases
=========
Alan's avatar
Alan committed
18

19
Alice is a geographer working for an NGO in an unstable country. They need
Alan's avatar
Alan committed
20
21
to use Tails but needs the QGis SIG to work. It would make little sense
to add such a specific software in Tails. But thanks to Additional
22
23
Software Packages, Alice can have QGis installed every time when they boot
Tails with persistent storage enabled.
Alan's avatar
Alan committed
24

25
26
27
28
Bob is a journalist and wants to publish videos made by other
colleagues. Bob needs to convert these videos and is used to the open
source video transcoder HandBrake. With Additional Software Packages,
Bob doesn't need to install it every time when they boot Tails.
Alan's avatar
Alan committed
29
30
31
32
33
34
35
36
37

Specifications
==============

Goals
-----

- Allow people to choose to:
  - Reinstall a package every time they start Tails.
38
  - Stop reinstalling a package every time on boot.
Alan's avatar
Alan committed
39
40
41
42
43
44
45
46

- Integrate this in:
  - The usual installation and removal process of a package (through
    Synaptic, another graphical tool, or APT on the command line).
  - The persistent storage configuration.

- Ensure packages are installed even offline.

47
- Ensure packages are updated when the machine is connected to the Internet.
Alan's avatar
Alan committed
48
49
50
51

Non-goals
---------

52
- We won't support installing software that is not in Debian's official
Alan's avatar
Alan committed
53
54
55
56
57
58
59
60
61
62
63
64
65
  repositories.

- We won't provide a way for people to specify which packages to install
  outside of the usual installation process of a package. We only ask
  people if they want to reinstall a package every time *after it has
  been successfully installed a first time*.

Implementation
==============

Software installation at startup
--------------------------------

66
67
68
69
70
71
The systemd user unit
[[!tails_gitweb config/chroot_local-includes/usr/lib/systemd/user/tails-additional-software-install.service]]
is `WantedBy=desktop.target`. It starts the system unit
[[!tails_gitweb config/chroot_local-includes/lib/systemd/system/tails-additional-software-install.service]]
with sudo (see
[[!tails_gitweb config/chroot_local-includes/etc/sudoers.d/zzz_tails-additional-software]]).
Alan's avatar
Alan committed
72

73
74
75
76
77
`tails-additional-software-install.service` starts if the configuration file
`/live/persistence/TailsData_unlocked/live-additional-software.conf` is not
empty. It is a oneshot service that executes
[[!tails_gitweb config/chroot_local-includes/usr/local/sbin/tails-additional-software]]
 `install` then creates `/run/live-additional-software/installed`.
Alan's avatar
Alan committed
78

79
80
81
82
`tails-additional-software install` reads `live-additional-software.conf` which
contains a package name per line and install these packages with `apt-get`
(using `DEBIAN_PRIORITY=critical` and the command line options `--yes` and
`--option DPkg::Options::=--force-confold`).
Alan's avatar
Alan committed
83

84
85
In the beginning of the process, the user is notified through desktop
notifications that additional software is being installed:
Alan's avatar
Alan committed
86
87
88

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installing.png"/>

89
90
91
92
In the end, they are informed of success of failure. In the latter case, they are
offered to open a configuration window or to examine the logs in order to better
understand the issue. The notifications with buttons displayed are as the desktop
user and are implemented in
93
[[!tails_gitweb config/chroot_local-includes/usr/local/lib/tails-additional-software-notify]].
Alan's avatar
Alan committed
94
95
96
97
98
99
100

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installation failed.png"/>


Software upgrade on Internet connection
---------------------------------------

101
A network-manager dispatcher hook starts the systemd unit
102
103
104
105
106
107
108
[[!tails_gitweb config/chroot_local-includes/lib/systemd/system/tails-additional-software-upgrade.path]]
which waits for `/run/live-additional-software/installed` then starts the
oneshot service `/usr/local/sbin/tails-additional-software upgrade` after
`tor-has-bootstrapped.service` and `tails-additional-software-install.service`
if the configuration file
`/live/persistence/TailsData_unlocked/live-additional-software.conf` is not
empty.
Alan's avatar
Alan committed
109

110
[[!tails_gitweb config/chroot_local-includes/usr/local/sbin.tails-additional-software]]
111
112
`update` saves a copy of apt lists, then starts `apt-get update` and launches the
installation process again, triggering an upgrade if necessary.
Alan's avatar
Alan committed
113
114
115
116
117
118

If the upgrade is successful, the copy of old apt lists is deleted.
Else, it would be restored by the installation process next time Tails
is started, ensuring that a network disconnection or another unexpected
issue doesn't make the Additional Software Packages unavailable.

119
120
In the beginning of the process, the user is notified via desktop
notifications that additional software is being upgraded.
Alan's avatar
Alan committed
121

122
123
124
In the end, they are informed of success of failure. In the latter case,
they are offered to open a configuration window or to examine the logs
in order to better understand the issue.
Alan's avatar
Alan committed
125
126
127
128
129
130
131
132
133
134
135

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - upgrade failed.png"/>

User interface for addition and removal of software
---------------------------------------------------

When the user installs a package either through the APT command line or
a graphical interface like Synaptic, a notification is displayed to let
them add or remove it from their list of additional software.

Two APT hooks are configured in
136
[[!tails_gitweb config/chroot_local-includes/etc/apt/apt.conf.d/80tails-additional-software.disabled]],
Alan's avatar
Alan committed
137
which are enabled by
138
[[!tails_gitweb config/chroot_local-hooks/99-zz-install-ASP-DPKG-hooks]] in the
139
end of the build process.
Alan's avatar
Alan committed
140

141
The first hook `DPkg::Pre-Install-Pkgs` runs before any actual
Alan's avatar
Alan committed
142
143
144
145
146
installation happens and calls
`/usr/local/sbin/tails-additional-software apt-pre` which saves a list
of installed and removed packages as JSON in
`/run/live-additional-software/packages`.

147
148
149
150
151
The second hook `DPkg::Post-Invoke` runs in the end of the installation
process and calls `/usr/local/sbin/tails-additional-software apt-post`.
It double forks so that APT properly returns, then parses the JSON file
written beforehand in order to check which packages were manually
installed or removed.
Alan's avatar
Alan committed
152
153
154
155
156

### When a package is installed

<img src="https://labs.riseup.net/code/attachments/download/1925/asp-flow-installed.svg" height="auto" />

157
#### With persistent storage unlocked:
Alan's avatar
Alan committed
158
159
160
161
162
163
164
165

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - add.png"/>

When *Add To Persistent Storage* is clicked,
`/usr/bin/tails-persistence-setup` is started as
`tails-persistence-setup` without a GUI to enable the
`AdditionalSoftware` preset. The new additional packages are then added
atomically to the `live-additional-software.conf` configuration file
166
(this logic is handled by
167
[[!tails_gitweb submodules/pythonlib/tailslib/additionalsoftware/config.py]])
Alan's avatar
Alan committed
168

169
#### Without persistent storage
Alan's avatar
Alan committed
170
171
172
173
174

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - add without persistent storage.png"/>

When *Add To Persistent Storage* is clicked,
`/usr/bin/tails-persistence-setup` is started as
175
`tails-persistence-setup` with a GUI to lead the user through the process
Alan's avatar
Alan committed
176
177
178
of creating a persistent storage. The `AdditionalSoftware` preset is
automatically enabled. The new additional packages are then added to the
`live-additional-software.conf` configuration file, which is in this
179
180
case mounted to `/media/tails-persistence-setup/TailsData` instead of
`/live/persistence/TailsData_unlocked` (this logic in handled by
181
[[!tails_gitweb submodules/pythonlib/tailslib/persistence.py]]).
Alan's avatar
Alan committed
182

183
184
185
186
The systemd service
[[!tails_gitweb config/chroot_local-includes/lib/systemd/system/tails-synchronize-data-to-new-persistent-volume-on-shutdown.service]]
is used to synchronize APT data (lists and cached packages) to the newly
created persistent storage on Tails shutdown.
Alan's avatar
Alan committed
187

188
#### With persistent storage locked
Alan's avatar
Alan committed
189

190
191
192
193
194
195
No notification is displayed as people who have a persistent storage but
don't unlock it, probably do this only sometimes and for a reason. They
probably otherwise unlock their persistent storage most of the time. If
they install packages with their persistent storage locked, they
probably do it with their persistent storage unlock as well and would
learn about this feature when it's most relevant for them.
Alan's avatar
Alan committed
196

197
#### When it's impossible to have persistent storage
Alan's avatar
Alan committed
198

199
200
This happens when running from a DVD, virtual machine, or intermediary
Tails.
Alan's avatar
Alan committed
201
202
203
204

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - impossible persistent storage.png"/>

The state file `/run/live-additional-software/installer-asked` ensures
205
this notification is only shown once per session, not to bother people
Alan's avatar
Alan committed
206
207
208
209
210
211
212
213
too much.

### When a package is removed

<img src="https://labs.riseup.net/code/attachments/download/1926/asp-flow-removed.svg" height="auto" />

<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - remove.png"/>

214
215
216
When *Remove* is clicked, the packages are removed atomically from the
`live-additional-software.conf` configuration file (this logic is
handled by
217
[[!tails_gitweb submodules/pythonlib/tailslib/additionalsoftware/config.py]]).
Alan's avatar
Alan committed
218
219
220
221

Additional Software configuration window
----------------------------------------

222
The list of additional software can be opened from:
Alan's avatar
Alan committed
223
224
225
226
227
228
229
230

- **Applications**&nbsp;▸ **System Tools**&nbsp;▸ **Additional Software**
- **Applications**&nbsp;▸ **Tails**&nbsp;▸ **Additional Software**
- a click on the gear button next to the **Additional
Software** feature in the persistent storage settings

This application is implemented in the following files:

231
232
233
- [[!tails_gitweb config/chroot_local-includes/usr/local/bin/tails-additional-software-config]]
- [[!tails_gitweb config/chroot_local-includes/usr/share/applications/org.boum.tails.additional-software-config.desktop.in]]
- [[!tails_gitweb config/chroot_local-includes/usr/share/tails/additional-software/configuration-window.ui]]
Alan's avatar
Alan committed
234

235
If there is no persistent storage or before any package is added, if the
236
237
persistent storage is locked, or if it is impossible to have a persistent
storage (for example, when running from a DVD or a virtual machine) the window
238
shows an explanation text with appropriate pointers:
Alan's avatar
Alan committed
239
240
241
242
243
244
245
246
247

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - without persistent storage.png"/>

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - empty.png"/>

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - locked persistent storage.png"/>

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - impossible persistent storage.png"/>

248
249
When packages have already been added, the window displays a list of
these Additional Software Packages:
Alan's avatar
Alan committed
250
251
252
253
254
255
256

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software.png"/>

When clicking on the delete cross, a confirmation dialog is displayed:

<img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - remove.png"/>

257
258
259
260
261
The privileged helper 
[[!tails_gitweb config/chroot_config/chroot_local-includes/usr/local/sbin/tails-additional-software-remove]]
is called through *pkexec* to remove the software from the
`live-additional-software.conf` configuration file (see
[[!tails_gitweb config/chroot_config/chroot_local-includes/usr/share/polkit-1/actions/org.boum.tails.additional-software.policy]]