Dev/About Debian Packaging
Debian Packaging of Kicksecure Design Documentation / Recommends vs Depends / --no-install-recommends / Files in Home Folder / Files in /etc/skel
Purpose of Packaging[edit]
Packaging serves several crucial purposes in software distribution, ensuring not only the smooth integration and functioning of software but also maintaining standards of security, legality, and consistency. Here's a breakdown of its primary objectives:
- Security hot fixes: Distributions can provide timely solutions when the original software creators are slow to respond or unavailable. This is vital since many developers are volunteers who may be preoccupied with other responsibilities.
- License compliance: Distribution maintainers (DMs) verify that the software adheres to freedom-respecting licenses, ensuring legal compliance and ethical use. See Avoid nonfreedom software for more details.
- No binary blobs: DMs ensure that the source package doesn't include pre-compiled binary files, promoting transparency and security.
- Source code completeness: This involves verifying whether the source code is complete and buildable, ensuring that the end-users receive a functional product.
- No embedded copies: Packages should not contain outdated or vulnerable third-party libraries as embedded copies. Refer to Embedded Copies for more information.
- Build reproduction: Adhering to Reproducible Builds practices allows for the creation of binaries that can be independently verified, enhancing trust and security.
- Download mirroring: In case the original sources are temporarily unavailable, distribution mirrors ensure that the software can still be downloaded and used.
- Hardening: Distributions may implement additional security measures to enhance protection against threats. This could vary based on the individual DM or team, including:
- AppArmor: Implementing mandatory access control, like an AppArmor profile, especially if it's not maintained by the original software providers.
- Compilation options: Utilizing more secure compilation options, which can be independent of the packages and applied distribution-wide.
- Distribution integrations: Integration with the distribution's specific systems is crucial. For example, distributions using different initialization systems (like systemd, OpenRC, Runit, or SysVinit) require the DM to maintain appropriate init files for their system. For instance, Devuan, a non-systemd distribution, uses SysVinit and thus needs SysVinit scripts for all packages involving daemons (like sound servers, display servers, or internet servers).
- Linting: Package checkers are used to automatically identify issues and enforce quality and standards in the packaging process.
Lintian dissects Debian packages and reports bugs and policy violations. It contains automated checks for many aspects of Debian policy as well as some checks for common errors. Every Debian maintainer should check packages with this tool.Lintian on Debian Salsa
Command-line tool and website running thousands of checks to analyze packages, suggest fixes for source, packaging, software, and spelling, useful across various distros and platforms, not just Debian.fosdem presentation, MariaDB post-release quality assurance in Debian and Ubuntu
- Lintian has a plethora of checks
- Architecture support: Upstream often provides packages and/or source code for a limited number of architectures (or Intel / AMD64 only). Distributions often build packages for multiple architectures. To learn more how Debian does that, see Debian Buildd - Debian Package Auto-Building.
- Continuous Integration: For example, debci - Debian Continuous Integration.
- Quality Assurance: For example, piuparts
piuparts is a tool for testing that .deb packages can be installed, upgraded, and removed without problems. piuparts is short for "package installation, upgrading and removal testing suite"
It does this by creating a minimal Debian installation in a chroot, and installing, upgrading, and removing packages in that environment, and comparing the state of the directory tree before and after. piuparts reports any files that have been added, removed, or modified during this process. piuparts is meant as a quality assurance tool for people who create .deb packages to test them before they upload them to the Debian package archive.
- Package Uninstallation Support:
- Want to remove something installed from upstream using
sudo make install
? Good luck. That's usually by upstream considered the job by the distribution packaging. - Removing software installed directly from upstream sources can be a challenge. This is often because upstream developers typically consider the management of installation and uninstallation processes, including clean removal of installed files, to be the responsibility of distribution packaging rather than their own. Using commands like
sudo make install
often doesn't provide an easy reversal option, highlighting the importance of distribution packages in facilitating straightforward uninstallation.
- Want to remove something installed from upstream using
Analyzing Dependency Chains[edit]
reverse-depends[edit]
1. Modify /etc/dpkg/origins/default
.
sudo unlink /etc/dpkg/origins/default sudo ln -s /etc/dpkg/origins/debian /etc/dpkg/origins/default
2. Download the source package.
apt source package
3. Undo afterwards to prevent unexpected issues.
sudo unlink /etc/dpkg/origins/default sudo ln -s /etc/dpkg/origins/whonix /etc/dpkg/origins/default
Install package(s) ubuntu-dev-tools
following these instructions
1 Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: In Template.
2 Update the package lists and upgrade the system .
sudo apt update && sudo apt full-upgrade
3 Install the ubuntu-dev-tools
package(s).
Using apt
command line
--no-install-recommends
option
is in most cases optional.
sudo apt install --no-install-recommends ubuntu-dev-tools
4 Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .
5 Done.
The procedure of installing package(s) ubuntu-dev-tools
is complete.
reverse-depends evolution-data-server
meta packages[edit]
Recommends vs Depends[edit]
This is about Recommends:
vs Depends:
in context of debian/control
.
debian/control
: There are separate meta packages for dependencies and recommended packages. For example:
kicksecure-xfce
kicksecure-cli
The reason for this is, because if we used the Recommends:
field for Kicksecure meta packages (those who pull the required Debian upstream packages for creating Kicksecure), we could not install them using apt
with --install-recommends
, which is apt
's default option, because that would also install packages recommend by any dependency we install.
On the other hand, if we installed using apt --no-install-recommends
, the packages Kicksecure meta packages recommends, will not get installed.
Therefore splitting them into packages suffixed *-dependencies
or *-recommended
which both use Depends:
and installing them using --no-install-recommends
appeared to be the only solution.
Otherwise it would install packages such as virtuoso
, soprano
and vlc
, which are not useful in context of Kicksecure.
The Recommends:
and Suggests:
field is still being used but this is mostly useful for one package advertising related packages users using apt-cache show package-name
and Packages for Debian Hosts.
See also:
Files in Home Folder[edit]
Packages placing files /home
folder must use the correct mechanism for doing so. Using defined mechanisms (see below) might be appropriate. Directly writing /home
is prohibited for reasons listed below.
/home
is for users. Not for distribution contributors.- Leads to a dpkg interactive conflict resolution dialog when package file is updated, in case file gets modified by the user or a program in the home folder (which is often very likely), which is a usability issue, which we try to avoid.
serious
lintian
errordir-or-file-in-home
.- Makes the package unfit for inclusion into
packages.debian.org
(very long term goal) (or other package repositories). - Looks amateurish in the eyes of Debian packagers.
- Makes the package unfit for inclusion into
- For which user? User
user
only? Inconsistent for multi user use cases. Hard to combine with future Multiple Boot Modes for Better Security - an Implementation of Untrusted Root withuser
, usersecureadmin
and usersuperadmin
. - Doesn't work / inconsistent in Qubes Template. Since packages are usually upgraded in Templates, the change never propagates to the home folder of the App Qube since it has an independently persistent home folder.
- Special code would be required to handle these cases. Such as a script that runs after boot but in Template that are not Disposable Template only. Example:
- https://github.com/Kicksecure/tb-updater/blob/master/usr/lib/systemd/system/tb-updater-first-boot.service
- More code to carry around, understand interactions, bugfix, maintain, explain, audit.
- Special code would be required to handle these cases. Such as a script that runs after boot but in Template that are not Disposable Template only. Example:
- In most cases there are more suitable mechanisms to reach the implementation goal than writing into the user's home folder.
- Files in /etc/skel
- If not, the lack of such mechanisms should be discussed with / requested from upstream.
Files in /etc/skel[edit]
- Files in
/etc/skel
are not as bad as files in/home
folder.- Works for any user.
- Inconsistencies. Not deployed through
/etc/skel
mechanism if file is added to a package after a user account was created. I.e. users who upgraded will miss that file.- Needs special code to handle such cases.
- If the file from
/etc/skel
is in the user's home folder, it's hard to update it. Updating the file in/etc/skel
won't effect the user's version of the file in the user's home folder.- Needs special code to handle such cases.
Modifying Default Configuration of Third Party Packages[edit]
Taking systemd as an example. Suppose /lib/systemd/system/systemd-random-seed.service
modifications are desired.
File /lib/systemd/system/systemd-random-seed.service
is owned by a third party package systemd
.
dpkg -S /lib/systemd/system/systemd-random-seed.service
systemd: /lib/systemd/system/systemd-random-seed.service
- Editing
/lib/systemd/system/systemd-random-seed.service
.- Is the worst (changes get lost on systemd package gets upgraded) (there is a solution using
dpkg-divert
encapsulated in a more sane by usingconfig-package-dev
displace
and we use it in Kicksecure source code where it could not be avoided but if avoidable it is best avoided if possible somehow).
- Is the worst (changes get lost on systemd package gets upgraded) (there is a solution using
- Shipping
/etc/systemd/system/systemd-random-seed.service
- would be better but still not great (this is for local administrator, not linux distribution)
/lib/systemd/system/systemd-random-seed.service.d
folder and a file such as/lib/systemd/system/systemd-random-seed.service.d/30_something.conf
- is an ideal solution for linux distributions such as Kicksecure since it does not takeover files by other packages and does not take away something from the local system administrator or user.
Editing a file owned by a different packages residing in /etc
would be even worse. Suppose for example file /etc/hdparm.conf
was modified by a package by a derivative Linux distribution. Next time the base distribution (Debian) updates the file, this would lead to an dpkg interactive conflict resolution dialog.
Configuration file `/etc/hdparm.conf' ==> Modified (by you or by a script) since installation. ==> Package distributor has shipped an updated version. What would you like to do about it ? Your options are: Y or I : install the package maintainer's version N or O : keep your currently-installed version D : show the differences between the versions Z : background this process to examine the situation The default action is to keep your current version. *** interfaces (Y/I/N/O/D/Z) [default=N] ? N
This is because the package manager (APT) cannot merge upstream (Debian) file changes with local file changes.
Such prompts confusing for users as users do not know what to answer. These result in support requests. Whatever the user chooses is non-ideal. If the user chooses the package maintainer's (Debian's) version, the user will loose settings modifications by the derivative. If the user keeps the file, the user will miss out on updates by the package maintainer. Merging the file is a skill that only the minority of users possesses.
This would not be an issue if the derivative distribution would fork, rebuild, upload the package that owns that file. In this example if the derivative distribution would upload package hdparm
then there would be no issue updating /etc/hdparm.conf
because the derivative would not "compete" with the base distribution. This however is not how it is done for derivatives such as Kicksecure, Whonix or Qubes. If just a small configuration change is required, the huge extra effort of a complete fork of the package is avoided to safe time. Only a drop-in configuration snippet gets shipped instead.
use /usr instead of /etc[edit]
/usr
: Is for distributions, packages./etc
: Is for system administrators.
If possible, avoid /etc
and use /usr
instead.
Why distributions are still making use of /etc
? While it's impossible for all distributions, but the most likely reason is legacy. This is for historic reasons. systemd
, which continues to shape the direction which Linux distributions develop, many Linux distributions and upstream projects agree with this direction of moving to /usr
.
Note that while
systemd
itself explicitly supports booting up with entirely unpopulated images (/usr/
being the only required directory to be populated) distributions might not be there yet: depending on your distribution further, manual work might be required to make this scenario work.Building Images Safely
While a lot of work has gone into ensuring systemd systems can safely boot with unpopulated /etc/ trees,Building Images Safely
The Linux Userspace API Group quote ticket Tracking upstream projects that do not support hermetic-usr for configuration lists Linux software packages that still require configuration in /etc
that do not support the /usr
folder for configuration yet.
Hermetic
/usr/
[...]
How can you help?
[...]
At this point some distributions (such as Fedora) are (probably more by accident than on purpose) already mostly hermetic in
/usr/
, at least for the most basic parts of the OS. However, this is not complete: many daemons require to have specific resources set up in/var/
or/etc/
before they can work, and the relevant packages do not carrysystemd-tmpfiles
descriptions that add them if missing. So there are two ways you could help here: politically, it would be highly relevant to convince distributions that an OS that is hermetic in/usr/
is highly desirable and it's a worthy goal for packagers to get there. More specifically, it would be desirable if RPM/dpkg packages would ship with enoughsystemd-tmpfiles
information so that configuration files the packages strictly need for operation are symlinked (or copied) from/usr/share/factory/
if they are missing (even better of course would be if packages from their upstream sources on would just work with an empty/etc/
and/var/
, and create themselves what they need and default to good defaults in absence of configuration files).systemd blog post Fitting Everything Together
Marek (Qubes OS lead developer) also agrees with this.
, /etc is for user changes, packages should avoid modifying config files there of other packages if possible.Qubes issue tracker
Patrick (Kicksecure lead developer) also agrees with this.
config-package-dev[edit]
Debian package xfce4-session
owns file /etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xml
. Therefore package xfce-desktop-config-dist
cannot directly overwrite it.
Preparing to unpack .../xfce-desktop-config-dist_1.4-1_all.deb ... Unpacking xfce-desktop-config-dist (3:1.4-1) ... dpkg: error processing archive /mnt/initialdeb/pool/main/w/xfce-desktop-config-dist/xfce-desktop-config-dist_1.4-1_all.deb (--unpack): trying to overwrite '\''/etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xml'\'', which is also in package xfce4-session 4.12.1-6 Errors were encountered while processing: /mnt/initialdeb/pool/main/w/xfce-desktop-config-dist/xfce-desktop-config-dist_1.4-1_all.deb E: Sub-process /usr/bin/dpkg returned an error code (1) ' + apt_get_exit_code=100
config-package-dev can help with such situations.
Examples on how to use config-package-dev displace:
- https://github.com/Kicksecure/desktop-config-dist/commit/0e9daa97e9f9e70120c969aa9c9d52cace46971a
- https://github.com/Kicksecure/security-misc/commit/93c08210545dd77b608515351154bcc16c8464b4
Ideally avoided as per above.
https://debathena.mit.edu/config-packages/
- upstream bug report dpkg-divert: warning: diverting file '/etc/issue' from an Essential package with rename is dangerous, use --no-rename
Desktop Environment (Xfce) Settings Changes[edit]
Testing modified desktop environment (Xfce) settings files in /etc/skel
or /home/user
is cumbersome.
When Xfce is shutdown, it might undo the manual or package modified settings in user home folder /home/user
as part of Xfce "save settings" procedure on shutdown. Therefore after reboot these settings might be reverted and could not be actually tested.
A script which is supposed to be run from a virtual console to simplify the steps:
/usr/libexec/helper-scripts/desktop-background-skel-test
Kicksecure / Whonix® Package Design[edit]
- whonix-base-files: Whonix-Host, Whonix-Gateway, Whonix-Workstation
- whonix-libvirt: Whonix-Host only
- anon-gw-base-files: Whonix-Gateway only
- anon-ws-base-files: Whonix-Workstation only
- kicksecure-base-files: Kicksecure-VMs and Kicksecure-Hosts
- vm-config-dist: Kicksecure-VMs and Whonix-VMs
See Also[edit]
- Versioning Format Conventions
- Build Documentation
- Build Documentation to build any package by Kicksecure such as security-misc
- Dev/Build_Documentation/generic-package
We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!