Actions

Configuration Files

From Whonix


Configuration Drop-In Folders[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 ™.

Most [archive] of packages by Whonix ™ provide configuration drop-in folders.

  • /etc/torbrowser.d
  • /usr/local/etc/torbrowser.d
  • /etc/whonix.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
  • Configuration of Tor is a special case, see Tor configuration.

We'll explain it using an example. For example, /etc/whonix_firewall.d/30_default.conf says.

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

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, leaving /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 /etc/whonix_firewall.d/50_user.conf.

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 /etc/profile.d or /etc/X11/Xsession.d.
  • Some contain scripts which are executed such as /etc/grub.d (boot grub menu generation).

Ordinary Configuration Files[edit]

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

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.

/usr/local/etc[edit]

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

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.

Support for configuration files in that folder was created because of Qubes, which is explained in next chapter, see Qubes Persistence.

Configuration of Tor is a special case, see Tor configuration.

Qubes Persistence[edit]

In the Qubes TemplateVM model, [1] any changes made to a root filesystem of a TemplateBasedVM [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, include /home/user and /usr/local as well as additional directories defined by "bind directory" settings. [2]

Table: Qubes R4 Inheritance and Persistence

Inheritance [3] Persistence [4]
TemplateVM n/a Everything
TemplateBasedVM /etc/skel/ to /home/ /rw/ (includes /home/ and bind-dirs [archive])
DVM Template [archive] [5] /etc/skel/ to /home/ /rw/ (includes /home/, /usr/local and bind-dirs [archive])
DisposableVM [archive] /rw/ (includes /home/, /usr/local and bind-dirs [archive]) Nothing

Therefore when editing configuration files:

  • Configuration changes in TemplateBasedVM: Changes in /etc will be lost after reboot.
    • For persistent configuration changes folder /usr/local/etc can 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 /etc but then the change will effect all TemplateBasedVM based on that TemplateVM.
  • TemplateVM: /etc persists.
  • StandaloneVM: /etc persists.

User documentation will advise in which VM configuration files can be edited in documentation specific to various subjects.

See Also[edit]

Nice explanation here: https://www.freedesktop.org/software/systemd/man/modules-load.d.html [archive]

Footnotes[edit]



Follow: Twitter.png Facebook.png 1280px-Gab text logo.svg.png Rss.png Matrix logo.svg.png 1024px-Telegram 2019 Logo.svg.png Discourse logo.svg

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate whonix.png

Share: Twitter | Facebook

Have you contributed [archive] to Whonix ™? If so, feel free to add your name and highlight what you did on the Whonix authorship [archive] page.

https [archive] | (forcing) onion [archive]

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 [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint.