(Redirected from Whonix Configuration Files)
Configuration Drop-In Folders
When changing any configurations it is recommended to use configuration drop-in folders whenever available to avoid the disadvantages of ordinary configuration files. To use a configuration drop-in folder means "to drop a configuration snippet" which translates to creating a new configuration file in a configuration drop-in folder.
This applies to most, if not all, other (Debian based) Linux distributions including Whonix ™.
/etc/onion-grater-merger.d(Only on Whonix-Gateway ™.)
/etc/whonix_buildconfig.d(Only if you build from source code.)
- Configuration of Tor is a special case, see Tor configuration.
We'll explain it using an example. For example,
Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
which will override the defaults found here. When Whonix ™ is updated, this
file may be overwritten.
The same in other words.
Instead of editing this file, please create and use the file
"/etc/whonix_firewall.d/50_user.conf". When Whonix ™ is updated,
"/etc/whonix_firewall.d/30_default.conf" will be overwritten. Files in folder
"/etc/whonix_firewall.d/" are sourced in alphabetical order. Anything in
"/etc/whonix_firewall.d/50_user.conf" will always override the defaults,
allowing the user to keep their settings after updating Whonix ™.
The same yet in other words... Files in configuration drop-in folders are usually sourced in lexical order. That means, files named
30_... will always get overruled by files named
For example, directly editing
/etc/whonix_firewall.d/30_default.conf is recommended against. This is because, next time Whonix ™ gets updated,
/etc/whonix_firewall.d/30_default may get new settings and improved settings. You would end up with an dpkg interactive conflict resolution dialog, which would for example look the following.
Configuration file `/etc/whonix_firewall.d/30_default.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
Modifications coming with Whonix ™ will always fall back to reasonable defaults, if you were still using an old version. However, to prevent such conflicts in the first place, you're better off reading
/etc/whonix_firewall.d/30_default.conf untouched, copying settings you wish to overrule from
/etc/whonix_firewall.d/30_default.conf and pasting them into
Since standardized configuration drop-in folders are not standardized, configuration drop-in snippets are processed in very different ways depending on the software that reads the configuration. Differences in drop-in folders:
- Some allow overwriting configuration variables from lexical lower configuration files such as
/etc/default/grub.d(grub configuration).; Some do not such as
/etc/apt/sources.list.d(where APT repository definitions can be dropped) or
/etc/apt/trusted.gpg.d(where APT signing keys can be dropped).
- Some are
sourceed in lexical order such a
- Some contain scripts which are executed such as
/etc/grub.d(boot grub menu generation).
Ordinary Configuration Files
There is something you should be aware of when editing ordinary configuration files where configuration drop-in folders are unavailable. This applies to Whonix ™ as well as most, if not all, other Debian based Linux distributions.
We'll explain it using an example. Let's take for example
There is no
/etc/hdparm.d folder. Therefore, if you want to make changes, your only option is to edit
/etc/hdparm.conf. But this comes with a disadvantage. Next time this file gets changed by the
hdparm maintainer and you upgrade your system, you would end up with an dpkg interactive conflict resolution dialog, which would for example look the following.
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
Check the differences
D, then make a decision. If you know you made changes to that file, you most likely want to keep them, i.e. select
N. If you are unsure, after the upgrade finished, check again that config file and re-apply your settings if necessary.
Some configuration files also reside in folder
Placing configuration files in
/usr/local is a relatively new development. Few applications are looking for configuration files in
/usr/local. Most configurable applications developed by Whonix developers support configuration files in folder
/usr/local/application-name.d. Some applications developed b Qubes developers might support configuration files in that folder. Other applications using configuration files in that folder are unknown.
Configuration of Tor is a special case, see Tor configuration.
In the Qubes TemplateVM model,  any changes made to a root filesystem of a TemplateBasedVM are lost upon reboot. This is advantageous for several reasons: it saves time and disk space, and allows faster, centralized updates for applications that are usually found inside the root filesystem. However, certain directories are designed to persist between reboots in order to store files and settings. These directories are stored in
/usr/local as well as additional directories defined by "bind directory" settings. 
Table: Qubes R4 Inheritance and Persistence
|Inheritance ||Persistence |
|DVM Template ||
Therefore when editing configuration files:
- Configuration changes in TemplateBasedVM: Changes in
/etcwill be lost after reboot.
- For persistent configuration changes folder
/usr/local/etccan be used in TemplateBasedVM if supported by the application. Applications that support it, will document that. Then it will apply only to that TemplateBasedVM.
- Otherwise settings can be changed persistently in TemplateVM
/etcbut then the change will effect all TemplateBasedVM based on that TemplateVM.
- For persistent configuration changes folder
User documentation will advise in which VM configuration files can be edited in documentation specific to various subjects.
Nice explanation here: https://www.freedesktop.org/software/systemd/man/modules-load.d.html
- AppVMs (qubes) and TemplateVMs.
- How to make any file in a TemplateBasedVM persistent using bind-dirs.
- Upon creation.
- Following shutdown.
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.
Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)