Commit a3aebf4a authored by Alan's avatar Alan
Browse files

ASP: draft design documentation

Will-fix: #14575
parent 58a76d49
[[!meta title="Additional software packages design documentation"]]
[[!toc levels=2]]
Rationale
=========
Tails includes a coherent but limited set of applications. As the system
is amnesic, new software packages for Debian can be installed a in a working session but they are not installed anymore next time Tails is started.
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.
Usecases
========
Alice is a geograph working for a NGO in an unstable country. She needs
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
Software Packages, she can have QGis installed every time she boots
Tails with her persistence enabled.
Bob is a journalist and he wants to publish colleagues videos. He needs
often needs to convert them and is used to the open source video transcoder
HandBrake. With Additional Software Packages, he doesn't need to install
it every time he boots its Tails anymore.
Specifications
==============
Goals
-----
- Allow people to choose to:
- Reinstall a package every time they start Tails.
- Stop reinstalling a package every time.
- 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.
- Ensure packages are updates when connected to the Internet.
Non-goals
---------
- We won't support installing software that are not in Debian
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
--------------------------------
The systemd user unit `tails-additional-software-install.service` is
`WantedBy=desktop.target`. It starts the system unit `tails-additional-software-install.service` with sudo (see `config/chroot_local-includes/etc/sudoers.d/zzz_tails-additional-software`).
`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 `/usr/local/sbin/tails-additional-software install` then creates `/run/live-additional-software/installed`.
`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`).
In the beginnihg of the process, the user is notified through desktop
notifications that additional software are being installed:
<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installing.png"/>
In the end, she is informed of success of failure. On the latter case,
she is offered to open a configuration window or to examine to logs to
better understand the issue.
<img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installation failed.png"/>
XXX: config/chroot_local-includes/usr/local/lib/tails-additional-software-notify
Software upgrade on Internet connection
---------------------------------------
A network-manager dispatcher hook starts the systemd unit
`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.
`tails-additional-software update` saves a copy of apt lists, then
starts `apt-get update` and launch the installation process again,
trigerring an upgrade if necessary.
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.
In the beginnihg of the process, the user is notified through desktop
notifications that additional software are being upgraded.
In the end, she is informed of success of failure. On the latter case,
she is offered to open a configuration window or to examine to logs to
better understand the issue.
<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
`config/chroot_local-includes/etc/apt/apt.conf.d/80tails-additional-software.disabled`,
which are enabled by
`config/chroot_local-hooks/99-zz-install-ASP-DPKG-hooks` in the end of
the build process.
The first hooks `DPkg::Pre-Install-Pkgs` runs before any actual
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`.
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 before to check which packages were manually installed or removed.
### When a package is installed
<img src="https://labs.riseup.net/code/attachments/download/1925/asp-flow-installed.svg" height="auto" />
#### With a persistent storage unlocked:
<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
(this logic is handeled by
`submodules/pythonlib/tailslib/additionalsoftware/config.py`).
#### With no persistent storage
<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
`tails-persistence-setup` with a GUI to let the user through the process
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
case mounted in `/media/tails-persistence-setup/TailsData` instead of
`/live/persistence/TailsData_unlocked` (this logic in handeled by
`submodules/pythonlib/tailslib/persistence.py).
XXX: config/chroot_local-includes/lib/systemd/system/tails-synchronize-data-to-new-persistent-volume-on-shutdown.service
#### With a persistent storage locked
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.
#### When it's impossible to have a persistent storage
This happens when
running from a DVD, virtual machine, or intermediary Tails.
<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
this notification in only shown once per session, not to bother people
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"/>
When *Remove* is clicked, the packages are packages removed
atomically from the `live-additional-software.conf` configuration file
(this logic is handeled by
`submodules/pythonlib/tailslib/additionalsoftware/config.py`).
Additional Software configuration window
----------------------------------------
The list of additional software can be open from:
- **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:
- `config/chroot_local-includes/usr/local/bin/tails-additional-software-config`
- `config/chroot_local-includes/usr/share/applications/org.boum.tails.additional-software-config.desktop.in`
- `config/chroot_local-includes/usr/share/tails/additional-software/configuration-window.ui`
If there is no persistent storage or before any package is added, if the persistent storage is locked or if it is impossible to have a persistent storage (for example, when running from a DVD or virtual machine) the
window shows an explanation text with appropriate pointers:
<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"/>
When some packages are already added, the window displays a list of
Additional Software Packages:
<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"/>
The privileged helper `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 `config/chroot_local-includes/usr/share/polkit-1/actions/org.boum.tails.additional-software.policy`)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment