(Redirected from Whonix Configuration Files)
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 ™.
Configuration Drop-In Folders
/etc/onion-grater-merger.d(Only on Whonix-Gateway ™.)
/etc/whonix_buildconfig.d(Only if you build from source code.)
Note that configuration of Tor is a special case; see here for further details.
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 message is described elsewhere as follows.
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 ™.
In simple terms, files in configuration drop-in folders are usually sourced in lexical order. That means files named
30_... will always be overruled by files named
In this example, directly editing
/etc/whonix_firewall.d/30_default.conf is recommended against. This is because the next time Whonix ™ is updated,
/etc/whonix_firewall.d/30_default.conf may get new and improved settings. In this case it would cause a dpkg interactive conflict resolution dialog, which would look like 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 it is better to:
- copy settings you wish to overrule from
/etc/whonix_firewall.d/30_default.confand paste them into
Since 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. Sample differences in drop-in folders include:
- Some allow overwriting configuration variables from lexical lower configuration files, such as
/etc/default/grub.d(grub configuration). Conversely, some do not allow this 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 as
- Some contain scripts which are executed, like
/etc/grub.d(boot grub menu generation).
Ordinary Configuration Files
In some cases a configuration drop-in folder is unavailable and edits must be made to ordinary configuration files. This applies to Whonix ™ as well as most, if not all, other Debian-based Linux distributions.
Consider the following
- any changes must be made directly to
- editing this file comes with a disadvantage -- next time the file is changed by the
hdparmmaintainer and the system is upgraded, a dpkg interactive conflict resolution dialog will appear like below
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
In all cases, check the version differences (
D), then make a decision. If purposeful changes were made to that file, then you most likely want to keep them by selecting
N. If unsure, after the upgrade has finished, check the configuration file again and re-apply settings if necessary.
Some configuration files also reside in the
Placing configuration files in
/usr/local is a relatively new development and few applications will search for configuration files in this location, although some applications developed by Qubes developers may be an exception. Most configurable applications developed by Whonix ™ support configuration files in the
/usr/local/application-name.d folder. Other applications using configuration files in the
/usr/local folder are unknown.
Configuration of Tor is a special case; see Tor configuration for further information.
Reset Configuration Files to Vendor Default
In the Qubes Template model,  any changes made to a root filesystem of an App Qube [archive] 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 |
|Template [archive]  ||n/a||Everything|
|App Qubes [archive] ||
|Disposable Template [archive]  ||
|Disposable [archive]  ||
Refer to the following advice when editing configuration files in Qubes-Whonix ™.
- App Qube configuration changes: Changes in
/etcare lost after reboot.
- For persistent configuration changes the
/usr/local/etcfolder can be used in an App Qube. Applications that support this arrangement will document it, but changes will only apply to that specific App Qube.
- Otherwise settings can be changed persistently in the Template
/etcfolder, but this change will affect all App Qubes based on that Template.
- For persistent configuration changes the
For various subjects, user documentation provides advice on which VM configuration files can be edited.
- Configuration Directories and Precedence [archive] explanation
- Grub configuration changes
- Changed Configuration Files during Upgrades
- Whonix ™ Debian Packages
sourceed as in:
- For example, not installed instead of installed.
apt-get-reset[archive] is a Whonix ™-specific feature. It performs an action like this:
sudo apt-get -o Dpkg::Options::=--force-confnew,confmiss install --reinstall package-name
- App Qubes and Templates [archive].
- How to make any file in an App Qube persistent using bind-dirs [archive].
- Upon creation.
- Following shutdown.
- https://www.qubes-os.org/doc/templates/ [archive]
- The former name was TemplateVM.
- The former name was AppVM or TemplateBasedVM.
- https://github.com/QubesOS/qubes-issues/issues/4175 [archive]
- Former names included DisposableVM Template, DVM Template, and DVM.
- https://www.qubes-os.org/doc/glossary/#disposable [archive]
- Former names included DisposableVM and DispVM.