Introduction[edit]

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[edit]

Most ^[archive] Whonix ™ packages provide configuration drop-in folders:

/etc/torbrowser.d
/usr/local/etc/torbrowser.d
/etc/systemcheck.d
/etc/whonix_firewall.d
/etc/onion-grater-merger.d (Only on Whonix-Gateway ™.)
/etc/whonix_buildconfig.d (Only if you build from source code.)
/etc/sdwdate.d
/etc/sdwdate-gui.d
/etc/uwt.d

Note that configuration of Tor is a special case; see here for further details.

To explain this concept, consider the Whonix ™ firewall example. /etc/whonix_firewall.d/30_default.conf states:

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 50_....

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:

read /etc/whonix_firewall.d/30_default.conf
leave /etc/whonix_firewall.d/30_default.conf untouched
copy settings you wish to overrule from /etc/whonix_firewall.d/30_default.conf and paste them into /etc/whonix_firewall.d/50_user.conf

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 ^[1] in lexical order such as /etc/profile.d or /etc/X11/Xsession.d.
Some contain scripts which are executed, like /etc/grub.d (boot grub menu generation).

Ordinary Configuration Files[edit]

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 /etc/hdparm.conf example:

no /etc/hdparm.d folder exists
any changes must be made directly to /etc/hdparm.conf
editing this file comes with a disadvantage -- next time the file is changed by the hdparm maintainer 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.

/usr/local/etc[edit]

Some configuration files also reside in the /usr/local/etc folder.

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.

Support for configuration files in this folder was adopted in light of Qubes, which is explained in the Qubes Persistence section.

Configuration of Tor is a special case; see Tor configuration for further information.

Reset Configuration Files to Vendor Default[edit]

It is possible to reset configuration files to vendor defaults. This is useful if a user changes their mind or selected the wrong action ^[2] in response to a Changed Configuration File.

1. Check using debsums.

Run debsums ^[archive] to show a list of changed and missing configuration files.

sudo debsums -ce

sudo debsums -ce

A sample output might look like this.

sdwdate: /etc/sdwdate.d/30_default.conf

This means:

package-name: changed-configuration-file

2. Reinstall the package.

In the command below, replace package-name with the actual name of the package such as sdwdate. ^[3]

sudo apt-get-reset package-name

sudo apt-get-reset package-name

The output will be similar to below.

Setting up sdwdate (3:14.7-1) ...
Configuration file '/etc/sdwdate.d/30_default.conf', does not exist on system.
Installing new config file as you requested.

3. Re-check using debsums.

Re-run sudo debsums -ce to confirm the correct configuration files were changed as intended.

Qubes Persistence[edit]

In the Qubes Template model, ^[4] 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 /rw, including /home/user and /usr/local as well as additional directories defined by "bind directory" settings. ^[5]

Table: Qubes R4 Inheritance and Persistence

	Inheritance ^[6]	Persistence ^[7]
Template ^[archive] ^[8] ^[9]	n/a	Everything
App Qubes ^[archive] ^[10]	`/etc/skel/` to `/home/`	`/rw/` (includes `/home/` and `bind-dirs` ^[archive])
Disposable Template ^[archive] ^[11] ^[12]	`/etc/skel/` to `/home/`	`/rw/` (includes `/home/`, `/usr/local` and `bind-dirs` ^[archive])
Disposable ^[archive] ^[13] ^[14]	`/rw/` (includes `/home/`, `/usr/local` and `bind-dirs` ^[archive])	Nothing

Refer to the following advice when editing configuration files in Qubes-Whonix ™.

App Qube configuration changes: Changes in /etc are lost after reboot.
- For persistent configuration changes the /usr/local/etc folder 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 /etc folder, but this change will affect all App Qubes based on that Template.
Template: /etc persists.
Standalone: /etc persists.

For various subjects, user documentation provides advice on which VM configuration files can be edited.

Footnotes[edit]

↑
sourceed as in:
- bash source, or
- sh (shell script) . (same as bash source).
https://superuser.com/questions/46139/what-does-source-do ^[archive]
↑ For example, not installed instead of installed.
↑
apt-get-reset ^[archive] is a Whonix ™-specific feature. It performs an action like this:
```
sudo apt -o Dpkg::Options::=--force-confnew,confmiss install --reinstall package-name
```
sudo apt -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.